{"slug":"architecture/ONE_AUTH_WORKBENCH_PLATFORM_REFERENCE_ARCHITECTURE","title":"One Auth, User Workbench and Platform Backend: Reference Architecture and Productisation Report","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/ONE_AUTH_WORKBENCH_PLATFORM_REFERENCE_ARCHITECTURE.mdx","bytes":66299,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Status: SUPERSEDED REFERENCE / SOURCE PROVENANCE.** Retained as input lineage. Its useful\n> identity, delegation and connector-projection material has been adapted into\n> [`INTEGRATEWISE_ARCHITECTURE.md`](INTEGRATEWISE_ARCHITECTURE.md) v2.2. Conflicting host-trust,\n> naming, unrestricted-discovery or product-boundary claims must not be implemented.\n\nExecutive summary\nThe supplied model is best productised as a host-governed integration and intelligence ecosystem in which the host remains the authority for identity, connector ownership and external-system credentials, while the product ecosystem adds reusable projections, normalised business context, orchestration, tools and AI-assisted workflows.\n\nThe central architectural decision is that a projected connector is not another connection to the external provider. It is a policy-constrained, versioned reference to a host-owned connector. It should contain identifiers, capability grants, policy bindings and status, but never a copied provider refresh token. All external-system execution should either be performed by the host connector runtime or authorised by a short-lived, audience-bound delegation issued by the host.\n\nOne Auth should consequently operate as a host-controlled identity and delegation broker rather than an independent identity silo. The host authenticates the user, determines tenant membership and connector entitlements, and issues signed assertions or grants. One Auth validates those assertions, creates an ecosystem session and maps host connectors into product-specific projections. OpenID Connect is the preferred modern authentication protocol because it adds an identity layer over OAuth 2.0; SAML remains an enterprise federation option where the host already supports it. OAuth security guidance recommends authorisation-code flows with PKCE, audience restriction, least privilege and sender-constrained or rotated tokens rather than implicit flows and broadly reusable bearer tokens.\n\nThe Product Package should be divided into four logical planes:\n\nPlane Components Purpose\nControl plane Discovery, Capabilities, adK, connector projection registry Defines what packages, connectors, tools and schemas exist and who may use them\nIntegration data plane Loader, Normalizer, MCP Connector, Tool Capability Reads, transforms and acts on host-connected systems\nContext plane Spine Cache, Business Context Provides fast operational views and durable governed business meaning\nExecution plane Orchestrator Coordinates deterministic workflows, approvals, tools, services and agents\n\nThe Platform Backend should provide a shared Package Control Plane, domain Services, model-facing AI gateway, governed Agents, segregated Memory and durable Pipelines. The User Workbench should remain a product experience rather than becoming the owner of connector credentials, workflow state or canonical business data.\n\nThe recommended product boundary is:\n\nHost owns identity and external connections. Product Package turns host connections into governed capabilities and context. Platform Backend supplies reusable execution and intelligence infrastructure. User Workbench presents the resulting work, decisions and actions.\n\nThe most important implementation principles are:\n\nDecision Recommendation\nConnector ownership Host-only; projections carry no provider secrets\nSession architecture Browser-to-backend session plus short-lived ecosystem access tokens\nDelegated execution Per-operation connector lease or OAuth token exchange\nCanonical data Business Context is durable and governed\nFast data Spine Cache is rebuildable and freshness-aware\nWorkflow engine Deterministic orchestration is authoritative; agents are bounded participants\nTool execution Every tool call passes policy, schema validation, idempotency and audit controls\nAPI style REST for commands, GraphQL for Workbench composition, CloudEvents for asynchronous changes\nMCP baseline Pin the stable 25 November 2025 specification initially; trial the 28 July 2026 release candidate behind protocol negotiation and feature flags\nScaling Begin as a modular platform; split ingestion, execution and AI workloads as scale or isolation demands\nMulti-tenancy Tenant identifiers, policy labels and encryption boundaries must be present in every persistent and runtime context\nProductisation Signed, versioned packages containing manifests, mappings, tools, policies, migrations and certification tests\n\nAs of 6 August 2026, MCP’s 28 July 2026 version is published as a release candidate rather than an established final release. The previous 25 November 2025 specification provides a safer production baseline, with version negotiation and adapters insulating the product from protocol evolution.\n\nReference model and component responsibilities\nThe names supplied by the product owner are treated as authoritative. Where their internal semantics were not supplied, the definitions below are recommended contracts rather than claims about an existing implementation.\n\nTerminology clarification. “Product Package” and the Platform Backend component named “Package” are liable to be confused. The latter should be named Package Control Plane or Package Registry and Runtime in technical documentation, even if the commercial product retains the shorter label.\n\nProduct Package\nComponent Recommended definition and primary responsibility Inputs and outputs Must not own\nDiscovery Discovers installable packages, host connector projections, schemas, capability manifests, MCP endpoints, versions and health. It is the ecosystem catalogue and negotiation surface. Inputs: tenant, host, package and policy context. Outputs: versioned descriptors and availability status. Provider credentials, workflow state or canonical records\nCapabilities Registry and evaluator for what an identity, package, projected connector or tool is allowed and technically able to do. A capability is a typed, versioned contract, not merely an OAuth scope string. Inputs: manifests, policies, host grants and runtime health. Outputs: effective capability set. Executing the operation itself\nSpine Cache Rebuildable, low-latency materialised view linking identities, tenants, projections, canonical entities, context summaries, capabilities and freshness metadata. It is the navigational “spine” of the Workbench. Inputs: normalisation events, context changes and capability changes. Outputs: fast entity and relationship reads. Sole source of truth or irreplaceable history\nadK The expansion of adK was not supplied and should not be inferred. The safest product contract is a thin developer kernel or SDK that standardises context access, capability invocation, policy hooks, package lifecycle, errors and telemetry. Inputs: package manifests and runtime bindings. Outputs: stable developer APIs used by Product Package modules and optional extensions. Workflow decisions, credentials, durable memory or vendor-specific agent semantics\nOrchestrator Durable coordinator for workflows, state transitions, retries, compensation, approvals, tool calls and agent tasks. It decides when and in what sequence work occurs. Inputs: command, context snapshot, capability grants and policies. Outputs: execution state, events and results. Direct ungoverned provider access or model-only decision authority\nBusiness Context Governed semantic model of business entities, relationships, assertions, policies, provenance and temporal validity. It represents what the organisation currently knows and why. Inputs: normalised records, user changes and approved agent outputs. Outputs: canonical context objects and relations. Ephemeral conversation state or unverified model speculation\nLoader Connector-facing ingestion boundary responsible for extraction, pagination, webhooks, cursors, checkpointing, rate-limit handling, raw envelopes and replay. Inputs: projection and load request. Outputs: immutable or append-only raw records and load events. Canonical business semantics\nNormalizer Converts provider-specific records into versioned canonical entities and relations; validates, deduplicates, resolves identities and attaches provenance. Inputs: raw envelopes and mapping specifications. Outputs: canonical mutations, validation errors and lineage. Provider authentication or workflow sequencing\nMCP Connector Gateway that exposes approved internal resources/tools through MCP and, when required, consumes external MCP servers. It performs MCP lifecycle negotiation, protocol translation, authorisation and policy enforcement. Inputs: MCP JSON-RPC messages and capability bindings. Outputs: MCP resources, prompts, tools, results and audit events. Bypassing Tool Capability policy or retaining provider secrets\nTool Capability Concrete executable operation available to users, workflows or agents, with typed input/output schemas, side-effect classification, approval rules, version and idempotency policy. Inputs: validated invocation plus execution grant. Outputs: structured result, side effects and audit record. Autonomous selection of itself or unconstrained downstream access\n\nMCP itself distinguishes application-controlled resources, user-controlled prompts and model-controlled tools. Its stable specification also requires capability and protocol-version negotiation during initialisation. Those distinctions support separating the MCP Connector from Tool Capability and from the Orchestrator.\n\nadK should remain an internal product term until its intended expansion is confirmed. It should not automatically be equated with any external “Agent Development Kit”; the architecture does not require a specific agent framework.\n\nProduct and Platform Backend\nComponent Recommended responsibility Primary interfaces\nUser Workbench Human-facing workspace for discovery, search, context navigation, workflow initiation, approvals, agent interaction, execution progress and audit explanation. GraphQL/read APIs, command APIs, event stream and One Auth session\nPackage Control Plane Stores, verifies, publishes, installs, activates, upgrades, deprecates and rolls back Product Packages. Package manifest API, artefact registry, signature verification and deployment events\nServices Reusable domain and platform APIs such as tenancy, policy, audit, notifications, search, configuration and execution ledger. REST/gRPC/GraphQL and events\nAI Model gateway that abstracts model providers, routing, redaction, model policy, prompt assets, usage, safety filters and evaluation. Model inference and embedding APIs\nAgents Governed runtimes that plan or perform bounded tasks using Business Context, Memory and Tool Capabilities through the Orchestrator. Agent-run API, tool protocol and evaluation interface\nMemory Tenant-scoped storage for session, working, episodic and semantic memory derived from interactions. Memory remains subordinate to Business Context. Retrieval, write, forget, retention and provenance APIs\nPipelines Durable ingestion, transformation, indexing, enrichment, evaluation and maintenance workflows. Event subscriptions, scheduled jobs and pipeline control API\n\nThe MCP host-client-server model is particularly aligned with the proposed boundary: the host coordinates permissions and model integration, each client maintains an isolated relationship with a server, and servers expose context and tools. The platform should preserve an equivalent isolation boundary even where MCP is only one of several transport options.\n\nProductisation model\nA Product Package should be a signed, immutable release artefact containing:\n\nPackage element Contents\nManifest Package ID, version, compatibility ranges, required host capabilities and dependencies\nConnector projections Supported host connector types and projection rules\nCapability catalogue Read, write, search, event and administrative capabilities\nCanonical schemas Entity, relation, event and error schemas\nLoader definitions Extraction modes, pagination, webhook and cursor behaviour\nNormalisation mappings Provider-to-canonical transformation and identity-resolution rules\nTool definitions Inputs, outputs, side-effect class, permissions and approval requirements\nMCP bindings Resource, prompt and tool names, versions and policy bindings\nUI metadata Workbench panels, labels, icons and display schema\nPolicy defaults Scope reduction, data classification, retention and approval policy\nMigrations Data, configuration and cache migrations\nCertification suite Contract tests, fixtures, replay tests, security assertions and compatibility cases\n\nRecommended lifecycle:\n\nvalidation fails\nactivation fails\nrollback\nDraft\nValidated\nCertified\nPublished\nInstalled\nActivated\nDeprecated\nRetired\n\nShow code\nCommercially, this lends itself to a core Workbench plus separately governable connector or domain packages, while preserving a single host-controlled connector estate. Enterprise options may add private data-plane deployment, customer-managed keys, advanced policy, longer audit retention and dedicated model endpoints without altering the logical contracts.\n\nArchitecture and interaction flows\nOverall logical architecture\nPlatform Backend\nProduct Package\nHost Trust Boundary\nderived retrieval\nUser\nUser Workbench\nOne Auth\nHost Identity and Session Authority\nHost Connector Control Plane\nHost Connector Runtime\nHost Credential Vault\nDiscovery\nCapabilities\nadK\nOrchestrator\nLoader\nNormalizer\nBusiness Context\nSpine Cache\nMCP Connector\nTool Capability\nPackage Control Plane\nServices\nAI Gateway\nAgents\nMemory\nPipelines\n\nShow code\nThe architecture intentionally separates the control plane from the runtime data plane. Discovery, package metadata, projection definitions and capability policies change relatively infrequently and should continue operating even when individual connector executions fail. Loader and tool calls are rate-limited, failure-prone external operations and should scale independently.\n\nA small deployment may run most Product Package components in one modular service with PostgreSQL, a queue and a cache. A medium deployment should separate connector ingestion, normalisation and orchestration workers. A large deployment should adopt tenant or regional cells, with a shared package/control plane and isolated execution and data planes.\n\nHost-controlled authentication flow\nmermaid\nCopy\nsequenceDiagram\nautonumber\nactor User\nparticipant WB as User Workbench\nparticipant OA as One Auth\nparticipant HostAuth as Host Auth Authority\nparticipant HostConn as Host Connector Control Plane\nparticipant Proj as Projection Service\nparticipant Orch as Orchestrator\nparticipant HostRun as Host Connector Runtime\nparticipant Provider as External Provider\n\n    User->>WB: Open ecosystem\n    WB->>OA: Start login with host hint and PKCE challenge\n    OA->>HostAuth: Redirect or federated auth request\n    HostAuth->>User: Authenticate through host policy\n    User->>HostAuth: Credentials / MFA / enterprise SSO\n    HostAuth-->>OA: Signed code or assertion\n    OA->>HostAuth: Validate or exchange code\n    HostAuth-->>OA: Host identity, tenant and session claims\n    OA->>HostConn: Request authorised host connector descriptors\n    HostConn-->>OA: Connector IDs, types and effective grants\n    OA->>Proj: Materialise or refresh projections\n    Proj-->>OA: Projection IDs and capability bindings\n    OA-->>WB: Ecosystem session; no provider tokens\n\n    User->>WB: Invoke a connector-backed action\n    WB->>Orch: Command with projection ID\n    Orch->>HostConn: Request short-lived execution grant\n    HostConn-->>Orch: Audience-bound connector lease\n    Orch->>HostRun: Execute capability with lease\n    HostRun->>Provider: Call using host-held credential\n    Provider-->>HostRun: Provider response\n    HostRun-->>Orch: Structured result and provider metadata\n    Orch-->>WB: Result, state and audit reference\n\nOIDC should normally be used between One Auth and a host that offers modern identity APIs; SAML may terminate at the host for established enterprise federation. OAuth alone is an authorisation framework, while OIDC defines identity claims and end-user authentication over OAuth. SAML defines an XML-based framework for exchanging security assertions between parties and is valuable for compatibility, but it is less convenient for fine-grained API delegation than OAuth-based tokens.\n\nConnector projection mapping\nConsumers\nCapability Bindings\nProjection Registry\nHost\nhost_connector_id\nsame connector, reduced grant\nhost_connector_id\nHost Connector\nCRM Account A\nHost Connector\nDrive Account B\nProjection\nWorkbench CRM Read\nProjection\nSales Automation CRM Write\nProjection\nWorkbench Drive Search\ncrm.account.read\ncrm.opportunity.update\ndrive.document.search\nUser Workbench\nAgent\nPipeline\n\nShow code\nA projection should be modelled as a first-class resource with:\n\ntext\nCopy\nprojection =\nhost connector reference\n\n- product/package scope\n- effective capabilities\n- tenant and principal constraints\n- policy reference\n- schema/version bindings\n- lifecycle and health state\n  It should not include:\n\ntext\nCopy\nprovider access token\nprovider refresh token\nprovider client secret\nhost session cookie\nunrestricted host connector permissions\nA single host connector may create multiple projections. For example, the Workbench may receive read-only CRM search while an approved pipeline receives a narrowly bounded update capability. Revoking or degrading the host connector must invalidate or suspend every dependent projection.\n\nProduct Package to Platform Backend data flow\nraw page or webhook\nraw envelope\nCloudEvent\ncanonical mutation\nmaterialised view update\nnormalisation event\nembed, summarise, classify\nquality and lineage\nquery\nauthoritative detail\ncommand\ncontext request\nfast lookup\nagent task\nmodel request\nmemory retrieval\nproposed tool call\nvalidated invocation\nexecution grant\nresult\naudit and domain event\nHost Connector Runtime\nLoader\nRaw Landing / Object Store\nEvent Bus\nNormalizer\nBusiness Context\nSpine Cache\nPlatform Pipelines\nMemory and Retrieval Index\nPlatform Services\nUser Workbench\nOrchestrator\nAgents\nAI Gateway\nTool Capability\n\nShow code\nCloudEvents provides a common envelope for events across services and platforms, while OpenAPI provides a language-independent description for HTTP interfaces. These are suitable package-level interoperability contracts rather than vendor-specific messaging formats.\n\nSuggested production visual. Create an SVG named “Host Authority and Ecosystem Execution Boundaries” with three vertically separated trust zones:\n\nHost identity and credential zone.\nProduct Package integration and context zone.\nPlatform intelligence and operations zone.\nUse solid arrows for token-bearing calls, dashed arrows for metadata or events, key icons only inside the host vault, and a red “no credential replication” boundary around projected connectors. This visual should appear in product security reviews, connector certification guides and enterprise architecture decks.\n\nSecurity, identity, interaction patterns and failure handling\nIdentity and token model\nThe recommended model uses different credential classes for different purposes rather than one ecosystem-wide bearer token.\n\nCredential or session Issuer and holder Purpose Recommended properties\nHost identity session Host; held by host-facing user agent Authentication under host policy Host-controlled MFA, device and enterprise SSO policy\nLogin transaction One Auth and Workbench Bind login initiation to callback PKCE, nonce/state, exact redirect matching and single use\nEcosystem browser session One Auth/BFF; browser receives secure cookie Maintain Workbench login HttpOnly, Secure, appropriate SameSite, CSRF protection and server-side revocation\nEcosystem access token One Auth; held by backend services Call ecosystem APIs Short-lived, audience-restricted, tenant- and subject-bound\nProjection grant Host or projection authority Authorise use of a projected connector Contains projection, capability, policy and expiry claims\nConnector execution lease Host connector control plane Authorise one operation or bounded execution window Narrow capability, provider account binding, idempotency and trace ID\nService identity Workload identity authority Service-to-service authentication mTLS or signed workload identity; automatically rotated\nProvider token External provider; held only by host vault/runtime Access provider API Never exposed to Workbench, projection store, agents or model prompts\n\nWhere interoperable JWT access tokens are used, they should follow the JWT access-token profile, including signed tokens and clear access-token typing. Opaque tokens with introspection may instead be preferred when immediate central revocation and reduced claim disclosure matter more than local validation.\n\nOAuth token exchange is appropriate when the Orchestrator receives an ecosystem token and requires a narrower downstream token for a host connector or service. The exchanged token should reduce audience and permissions rather than reproduce the caller’s entire authority.\n\nFor workload identity, either cloud-native managed identities, mTLS certificates or SPIFFE-compatible identities can be used. SPIFFE defines portable workload identities and short-lived identity documents that can establish authenticated service channels without distributing static application secrets.\n\nHost connector and projection interaction patterns\nPattern Description Appropriate use Primary control\nHost-mediated execution Product calls host runtime; host calls provider Default and strongest ownership boundary Provider credentials never leave host\nDelegated short-lived execution Host issues a narrowly scoped lease to an approved runtime High-volume or latency-sensitive connector workers Audience-bound, expiring, sender-constrained grant\nEvent projection Host emits connector events consumed by Product Package Near-real-time ingestion Signed events, replay controls and tenant routing\nPull projection Loader asks host runtime for pages since a cursor Backfills and providers lacking webhooks Cursor checkpoint and rate-limit control\nOn-demand resource projection MCP or Workbench requests contextual data only when needed Expensive or sensitive sources Policy evaluation at read time\nCached projection Normalised subset is retained in Spine Cache or Business Context Repeated business operations and cross-system context Classification, retention, freshness and revocation propagation\n\nA projected connector’s effective permissions should be the intersection of:\n\ntext\nCopy\nhost connector permissions\n∩ user or service entitlement\n∩ package-declared requirement\n∩ tenant policy\n∩ tool-specific permission\n∩ current risk and health policy\nSecurity controls\nAuthorisation flow. Use authorisation code plus PKCE and avoid implicit token delivery. Validate issuer, audience, nonce, exact redirect URI and token type. OAuth’s current best practice recommends PKCE, restricted access-token privileges, audience restriction, refresh-token rotation or sender constraint, and mTLS or DPoP where replay resistance is needed.\n\nSender-constrained options.\n\nOption Advantages Costs and limitations\nmTLS-bound token Strong workload authentication and token binding; suitable for managed backend services Certificate lifecycle, proxy/TLS-termination complexity and harder browser use\nDPoP Application-layer proof of possession; useful when mTLS is impractical Key management in clients, nonce/replay handling and incomplete ecosystem support\nRotating bearer tokens Broadest compatibility and simplest implementation Stolen current token remains usable until expiry or revocation\nOpaque token with introspection Central policy and immediate status checks Runtime dependency and added latency\nSigned JWT Local verification and lower authorisation-server dependency Harder immediate revocation and greater risk of excessive claim disclosure\n\nmTLS binds tokens to an X.509 certificate; DPoP binds them to a public key and requires proof of the corresponding private key during use. Neither removes the need for HTTPS, audience validation, least privilege or token expiry.\n\nRevocation. Host connector revocation must produce a high-priority event that marks all projections inactive, invalidates connector leases, terminates related MCP sessions where necessary, clears sensitive cached results and prevents new tool execution. OAuth defines a token revocation mechanism that may invalidate the token and related grant material.\n\nZero trust. Neither host network location nor internal-service status should imply authorisation. Every resource request should evaluate principal, workload, tenant, projection, capability, data classification and runtime posture. NIST’s zero-trust model explicitly removes implicit trust based solely on network location or asset ownership and focuses controls on resources and identities.\n\nMCP-specific controls. MCP HTTP deployments should use protected-resource metadata and authorisation-server discovery. The MCP server is a protected resource, and its access token is distinct from any credential needed by the underlying provider connector. MCP also recommends visible tool exposure and human control over sensitive invocations.\n\nFailure modes and mitigations\nFailure mode Result Detection Mitigation and recovery\nHost authentication unavailable New sessions cannot start Login synthetic checks and auth error rate Preserve existing valid sessions within policy; fail closed for new login; clear host-status messaging\nHost assertion invalid or issuer mismatch Identity confusion or attack attempt Signature, issuer, nonce and audience validation failure Reject; audit at high severity; never fall back to unsigned claims\nHost connector revoked Projection appears available but cannot execute Revocation event and execution denial Atomically suspend projections, clear leases and invalidate relevant cache entries\nProjection drift Projection grants differ from host reality Scheduled reconciliation and version hash mismatch Host remains authoritative; reconcile and reduce permissions automatically\nScope or capability mismatch Tool visible but execution denied Discovery-versus-execution comparison Suppress unavailable tool; offer re-authorisation through host; never silently escalate\nProvider token expiry Connector calls fail Host runtime receives provider auth error Host refreshes or marks reconnect-required; Product Package receives status, not refresh token\nProvider throttling Load lag and user-facing delays Rate-limit headers, queue age and retry metrics Adaptive concurrency, backoff, prioritised queues and quota-aware scheduling\nDuplicate webhook or retry Duplicate business mutation Event ID and idempotency checks Inbox table, deduplication key and idempotent normalisation\nLoader cursor loss Missed or repeated records Cursor continuity checks and count reconciliation Persist cursor transactionally; replay from immutable raw landing zone\nPoison record Normalisation pipeline stalls Repeated schema-validation failure Per-record dead-letter queue; continue batch; retain provenance and repair tool\nSpine Cache stale Workbench shows old summary freshness_at, source watermark and lag metrics Show freshness; authoritative fallback to Business Context or source; rebuild asynchronously\nOrchestration partial failure Some side effects applied Execution ledger and incomplete state Saga-style compensation, idempotent retry and human resolution queue\nTool timeout with unknown provider outcome Unsafe duplicate retry Timeout plus missing confirmation Query provider by idempotency key before retry; classify as indeterminate\nMCP protocol mismatch Client/server cannot negotiate initialize rejection Support explicit version matrix and adapters; no best-guess protocol fallback\nAgent proposes unsafe action Potential destructive or unauthorised change Policy engine, action classifier and approval gate Deny by default; require explicit approval; constrain tools and arguments\nMemory contains deleted or stale data Privacy or correctness breach Retention scan and provenance comparison Tombstone propagation, re-indexing and deletion verification\nRegion or cell outage Tenant workload unavailable Health, queue and replication monitoring Cell failover where policy allows; preserve single-writer semantics for workflows\n\nData models, schemas, storage and caching\nCanonical relationship model\ncontains\nowns\nprojects\ndeclares\nreceives\ngrants\nimplements\nsupplies\nproduces\ntransforms_to\ngoverns\nmaterialises\nsource\ntarget\nhas\nindexed_as\nsource\ntarget\naccepts\nexposes\nmaps\ncarries\nTENANT\nPRINCIPAL\nHOST_CONNECTOR\nCONNECTOR_PROJECTION\nPRODUCT_PACKAGE\nCAPABILITY_GRANT\nCAPABILITY\nTOOL_BINDING\nLOAD_JOB\nRAW_RECORD\nNORMALIZATION_RESULT\nMAPPING_SPEC\nCONTEXT_OBJECT\nCONTEXT_RELATION\nCONTEXT_ASSERTION\nSPINE_ENTRY\nSPINE_EDGE\nMCP_SERVER\nMCP_SESSION\nMCP_TOOL_BINDING\nMCP_INVOCATION\n\nShow code\nEvery multi-tenant table should include at least tenant_id, and every derived datum should include source and provenance. Referential identifiers should be opaque and globally unique; provider-native identifiers should be stored separately and always qualified by connector and object type.\n\nSpine Cache schema\nThe Spine Cache is a read model, not the canonical business record.\n\nEntity or field Purpose\nspine_entry_id Stable cache/read-model identifier\ntenant_id Mandatory tenancy boundary\nentity_type Canonical type such as person, account, document or workflow\ncanonical_object_id Reference to Business Context\ndisplay_label Workbench-friendly label\nsummary Compact materialised summary\nsearch_tokens Keyword/full-text projection\nprojection_refs[] Relevant connector projections\ncapability_refs[] Capabilities that can operate on the entry\nclassification Data handling label\nsource_watermark Latest source event or cursor represented\nfreshness_at Time at which the view was known fresh\nschema_version Read-model schema version\netag Optimistic caching and conditional read token\nexpires_at Optional policy-driven cache expiry\npayload Bounded denormalised JSON for view rendering\n\nspine_edge should contain from_entry_id, to_entry_id, relation_type, weight_or_rank, provenance_ref, valid_from, valid_to and schema_version.\n\nRecommended indexes are:\n\ntext\nCopy\n(tenant_id, canonical_object_id)\n(tenant_id, entity_type, freshness_at)\n(tenant_id, projection_ref)\nfull-text or search index on display_label, summary and search_tokens\ngraph-like adjacency index on from_entry_id and to_entry_id\nPostgreSQL can provide relational integrity together with indexed JSONB documents; GIN indexes support searches over keys and values within JSONB. This makes PostgreSQL a strong initial Spine Cache store before scale or query patterns justify a dedicated search or graph system.\n\nBusiness Context schema\nEntity Core fields\ncontext_space space_id, tenant_id, name, policy_ref, schema_version\ncontext_object object_id, space_id, type, canonical_key, attributes, status, valid_from, valid_to, version\ncontext_relation relation_id, from_object_id, predicate, to_object_id, attributes, valid_from, valid_to\ncontext_assertion assertion_id, subject_id, predicate, value_or_object_id, confidence, verification_status, validity\nprovenance_record provenance_id, source_projection_id, source_record_id, load_job_id, normalization_run_id, observed_at, transform_version\ncontext_policy_label object_id, classification, retention_class, residency, purpose_limits\n\nThe recommended canonical object envelope is:\n\njson\nCopy\n{\n\"object_id\": \"ctx_01J...\",\n\"tenant_id\": \"ten_01J...\",\n\"space_id\": \"space_sales\",\n\"type\": \"crm.opportunity\",\n\"canonical_key\": \"crm.opportunity:host-connector-123:provider-987\",\n\"attributes\": {\n\"name\": \"Enterprise Renewal\",\n\"stage\": \"negotiation\",\n\"amount\": {\n\"value\": \"250000.00\",\n\"currency\": \"INR\"\n}\n},\n\"status\": \"active\",\n\"valid_from\": \"2026-08-01T10:00:00Z\",\n\"valid_to\": null,\n\"version\": 14,\n\"provenance\": [\n{\n\"projection_id\": \"prj_01J...\",\n\"source_record_id\": \"provider-987\",\n\"observed_at\": \"2026-08-06T06:15:00Z\",\n\"mapping_version\": \"crm-normalizer@3.2.0\"\n}\n],\n\"classification\": [\"tenant-confidential\"]\n}\nBusiness Context should support bitemporal or at least valid-time semantics for entities where the difference between “when the business fact was true” and “when the platform learned it” matters. For less demanding deployments, versioned records plus append-only change events are sufficient.\n\nLoader schema\nEntity Important fields\nload_job job_id, tenant_id, projection_id, mode, requested_by, status, started_at, completed_at, cursor_before, cursor_after, attempt\nraw_record raw_record_id, job_id, source_object_type, source_id, operation, observed_at, event_id, content_type, payload_location, payload_hash\nsource_cursor projection_id, stream, cursor, watermark, updated_at, lease_owner, lease_expiry\nload_error job_id, raw_record_id, category, provider_code, retryable, details, next_attempt_at\nwebhook_inbox event_id, projection_id, received_at, signature_valid, processing_status, dedupe_key\n\nRaw provider payloads should generally be stored in encrypted object storage, while metadata and cursors are stored transactionally. Large payloads should be referenced by URI rather than duplicated into relational rows or event messages.\n\nNormalizer schema\nEntity Important fields\nmapping_spec mapping_id, connector_type, source_schema_version, target_schema_version, transform_version, status\nnormalization_run run_id, raw_record_id, mapping_id, status, started_at, completed_at\nnormalization_result run_id, canonical_type, canonical_id, operation, output_hash, quality_score\nidentity_resolution resolution_id, candidate_keys, resolved_object_id, method, confidence, review_status\nvalidation_error run_id, field_path, rule, observed_value_ref, severity, resolution\nlineage_edge source_record_id, canonical_object_id, transform_version, effective_at\n\nNormalisers should be deterministic for a fixed input and mapping version. Model-assisted classification may be used as an enrichment step, but its result should be explicitly marked as inferred, carry model and prompt provenance, and not replace deterministic core mappings without an approval policy.\n\nMCP Connector schema\nEntity Important fields\nmcp_server_registration server_id, tenant_id, endpoint_or_runtime, transport, supported_versions, auth_metadata, status\nmcp_session session_id, server_id, principal_id, negotiated_version, client_capabilities, server_capabilities, started_at, ended_at\nmcp_capability_snapshot session_id, resource_hash, prompt_hash, tool_hash, captured_at\nmcp_tool_binding mcp_name, tool_capability_id, tool_version, input_schema, output_schema, approval_policy\nmcp_invocation invocation_id, session_id, request_id, tool_binding_id, status, trace_id, result_ref, error_ref\n\nMCP uses JSON-RPC and supports standard stdio and Streamable HTTP transports in the stable specification. It also defines lifecycle initialisation, capability negotiation and protocol-version agreement.\n\nStorage and caching comparison\nStorage choice Best fit Advantages Limitations Recommended role\nRelational database Tenancy, projection registry, Business Context, orchestration state and audit indexes Transactions, constraints, mature querying and JSON support Horizontal write scaling may require partitioning or cells System of record for control and context data\nIn-memory key-value cache Sessions, capability decisions, short-lived Spine fragments and rate limits Very low latency, TTL and eviction controls Memory cost, eviction risk and weaker complex queries Ephemeral cache only\nDocument database Highly variable source-specific documents Flexible document shape and straightforward object retrieval Cross-document constraints and joins may be weaker Raw or semi-normalised document projections\nSearch engine Workbench keyword, faceting and relevance Rich full-text search and aggregations Eventual consistency and operational overhead Search projection of Spine/Business Context\nGraph database Deep relationship traversal and dependency analysis Efficient multi-hop graph queries Additional operational model and dual-write concerns Optional large-scale relationship index\nObject storage Raw payloads, large documents, artefacts and replay data Low-cost durability and lifecycle policies Not suited to transactional point updates Raw landing zone and package artefacts\nEvent log or broker Connector events and pipeline decoupling Replay, fan-out and independent consumers Ordering, duplicate delivery and schema governance complexity Integration backbone\nVector index Semantic retrieval over approved context and memory Similarity search over unstructured content Approximate results, deletion and provenance challenges Derived retrieval index; never sole source of truth\n\nRedis supports explicit key expiry and configurable eviction policies such as LRU and LFU. Those facilities are useful for cache behaviour, but business-authoritative data should not depend on an evictable cache.\n\nRecommended caching strategy:\n\nData class Pattern Invalidation\nDiscovery manifest Read-through cache with ETag Package publication or deprecation event\nCapability decision Short-lived decision cache Policy, identity, projection or host grant change\nConnector health Stale-while-revalidate Health event or bounded expiry\nSpine entity Event-updated materialised cache Canonical context event and connector revocation\nTool metadata Version-keyed immutable cache New tool version, not in-place mutation\nTool result Only for explicitly cacheable reads Source event, projection revocation or TTL\nWorkbench GraphQL response Per-user/tenant short cache Underlying entity and capability change\nAgent retrieval result Query and policy-sensitive transient cache Context/memory update or conversation boundary\n\nCache keys should always include tenant, principal or role where relevant, effective capability set, projection version, schema version and locale. Otherwise data from one authorisation context may be reused in another.\n\nAPI contracts and integration surfaces\nOpenAPI should describe REST command and query endpoints, GraphQL should support Workbench composition, JSON Schema should define capability inputs and outputs, and CloudEvents should describe asynchronous change envelopes. OpenAPI is designed to make HTTP interfaces understandable to humans and software without source-code inspection; GraphQL offers a typed schema and introspection model independent of the backing storage.\n\nAll command APIs should support:\n\ntext\nCopy\nAuthorization\nX-Tenant-Id or tenant claim\nIdempotency-Key\nTraceparent\nContent-Type\nIf-Match for version-sensitive changes\nPrefer: respond-async where applicable\nErrors should share a standard envelope:\n\njson\nCopy\n{\n\"type\": \"https://errors.example.invalid/capability-denied\",\n\"title\": \"Capability denied\",\n\"status\": 403,\n\"code\": \"CAPABILITY_DENIED\",\n\"detail\": \"The projection does not grant crm.opportunity.update.\",\n\"trace_id\": \"4bf92f3577b34da6a3ce929d0e0e4736\",\n\"retryable\": false,\n\"remediation\": {\n\"kind\": \"host_reauthorisation\",\n\"projection_id\": \"prj_01J...\"\n}\n}\nDiscovery REST contract\nhttp\nCopy\nGET /v1/discovery?package_id=sales-workbench&include=connectors,capabilities,mcp\nAuthorization: Bearer <ecosystem-access-token>\nIf-None-Match: \"discovery-ten_123-v45\"\njson\nCopy\n{\n\"tenant_id\": \"ten_123\",\n\"generated_at\": \"2026-08-06T07:00:00Z\",\n\"etag\": \"discovery-ten_123-v45\",\n\"packages\": [\n{\n\"package_id\": \"sales-workbench\",\n\"version\": \"2.4.0\",\n\"status\": \"active\",\n\"compatible_platform\": \">=3.1 <4.0\"\n}\n],\n\"connector_projections\": [\n{\n\"projection_id\": \"prj_crm_read\",\n\"host_connector_id\": \"host_conn_789\",\n\"connector_type\": \"crm\",\n\"status\": \"ready\",\n\"freshness_at\": \"2026-08-06T06:58:30Z\",\n\"capabilities\": [\n{\n\"id\": \"crm.opportunity.read\",\n\"version\": \"1.2\",\n\"availability\": \"available\"\n}\n]\n}\n],\n\"mcp_servers\": [\n{\n\"server_id\": \"mcp_sales\",\n\"protocol_versions\": [\"2025-11-25\"],\n\"transport\": \"streamable-http\"\n}\n]\n}\nDiscovery should support conditional requests and immutable version references. A package or capability descriptor already retrieved by version should not change underneath clients.\n\nOrchestrator REST contract\nhttp\nCopy\nPOST /v1/orchestrations\nAuthorization: Bearer <ecosystem-access-token>\nIdempotency-Key: **\\*\\*\\*\\***\njson\nCopy\n{\n\"workflow\": {\n\"id\": \"renewal-risk-review\",\n\"version\": \"3.1.0\"\n},\n\"subject\": {\n\"context_object_id\": \"ctx_opportunity_123\"\n},\n\"execution_mode\": \"agent_assisted\",\n\"requested_capabilities\": [\n\"crm.opportunity.read\",\n\"document.search\"\n],\n\"constraints\": {\n\"allow_side_effects\": false,\n\"require_human_approval\": true\n},\n\"input\": {\n\"review_period\": \"P90D\"\n}\n}\nhttp\nCopy\nHTTP/1.1 202 Accepted\nLocation: /v1/orchestrations/orch_01J...\njson\nCopy\n{\n\"orchestration_id\": \"orch_01J...\",\n\"status\": \"accepted\",\n\"current_state\": \"validating_capabilities\",\n\"links\": {\n\"self\": \"/v1/orchestrations/orch_01J...\",\n\"events\": \"/v1/orchestrations/orch_01J.../events\"\n}\n}\nThe orchestration state machine should use explicit states such as accepted, validating, running, waiting_for_approval, waiting_for_external_system, compensating, succeeded, failed and cancelled. Model output should never be the only record of execution state.\n\nLoader REST and event contract\nhttp\nCopy\nPOST /v1/load-jobs\nAuthorization: Bearer <service-token>\nIdempotency-Key: loader-crm-prj-123-2026-08-06T07:00Z\njson\nCopy\n{\n\"projection_id\": \"prj_crm_read\",\n\"mode\": \"incremental\",\n\"object_types\": [\"account\", \"contact\", \"opportunity\"],\n\"cursor\": {\n\"strategy\": \"resume\"\n},\n\"delivery\": {\n\"raw_retention_class\": \"standard\",\n\"normalization_profile\": \"crm-canonical@3.2.0\"\n}\n}\njson\nCopy\n{\n\"job_id\": \"load_01J...\",\n\"status\": \"queued\",\n\"projection_id\": \"prj_crm_read\",\n\"cursor_before\": \"opaque-host-cursor\",\n\"estimated_records\": null\n}\nCloudEvent-style result:\n\njson\nCopy\n{\n\"specversion\": \"1.0\",\n\"id\": \"evt_01J...\",\n\"source\": \"/loaders/crm/prj_crm_read\",\n\"type\": \"com.example.loader.raw-record.received.v1\",\n\"subject\": \"opportunity/provider-987\",\n\"time\": \"2026-08-06T07:03:14Z\",\n\"datacontenttype\": \"application/json\",\n\"tenantid\": \"ten_123\",\n\"projectionid\": \"prj_crm_read\",\n\"data\": {\n\"raw_record_id\": \"raw_01J...\",\n\"operation\": \"upsert\",\n\"payload_ref\": \"object://raw/ten_123/load_01J/raw_01J\",\n\"payload_hash\": \"sha256:...\"\n}\n}\nTool Capability REST contract\nhttp\nCopy\nPOST /v1/tool-invocations\nAuthorization: Bearer <ecosystem-or-agent-token>\nIdempotency-Key: tool-call-01J...\njson\nCopy\n{\n\"tool\": {\n\"id\": \"crm.opportunity.update-stage\",\n\"version\": \"2.0.1\"\n},\n\"projection_id\": \"prj_crm_write\",\n\"context\": {\n\"orchestration_id\": \"orch_01J...\",\n\"subject_object_id\": \"ctx_opportunity_123\"\n},\n\"input\": {\n\"opportunity_id\": \"ctx_opportunity_123\",\n\"expected_version\": 14,\n\"new_stage\": \"closed_won\"\n},\n\"execution\": {\n\"dry_run\": true,\n\"approval_token\": null\n}\n}\njson\nCopy\n{\n\"invocation_id\": \"toolinv_01J...\",\n\"status\": \"approval_required\",\n\"effect_preview\": {\n\"operation\": \"update\",\n\"target\": \"crm.opportunity\",\n\"changes\": [\n{\n\"path\": \"/stage\",\n\"from\": \"negotiation\",\n\"to\": \"closed_won\"\n}\n]\n},\n\"approval\": {\n\"request_id\": \"approval_01J...\",\n\"required_role\": \"sales_manager\"\n}\n}\nEvery tool definition should include:\n\njson\nCopy\n{\n\"id\": \"crm.opportunity.update-stage\",\n\"version\": \"2.0.1\",\n\"side_effect\": \"external_write\",\n\"input_schema\": {},\n\"output_schema\": {},\n\"required_capabilities\": [\"crm.opportunity.update\"],\n\"idempotency\": \"required\",\n\"approval_policy\": \"conditional\",\n\"timeout_policy\": \"provider-status-check-before-retry\",\n\"data_classifications\": [\"tenant-confidential\"]\n}\nMCP management and invocation contracts\nManagement API:\n\nhttp\nCopy\nPOST /v1/mcp/servers\nAuthorization: Bearer <admin-token>\njson\nCopy\n{\n\"name\": \"sales-context\",\n\"transport\": \"streamable-http\",\n\"endpoint\": \"https://mcp.internal.example.invalid/sales\",\n\"allowed_protocol_versions\": [\"2025-11-25\"],\n\"auth_mode\": \"oauth-protected-resource\",\n\"tool_policy\": {\n\"allow\": [\n\"crm.opportunity.read\",\n\"document.search\"\n],\n\"deny_side_effects_without_approval\": true\n}\n}\nMCP initialisation follows JSON-RPC:\n\njson\nCopy\n{\n\"jsonrpc\": \"2.0\",\n\"id\": 1,\n\"method\": \"initialize\",\n\"params\": {\n\"protocolVersion\": \"2025-11-25\",\n\"capabilities\": {\n\"roots\": {\n\"listChanged\": true\n},\n\"sampling\": {}\n},\n\"clientInfo\": {\n\"name\": \"user-workbench\",\n\"version\": \"3.4.0\"\n}\n}\n}\nTool discovery:\n\njson\nCopy\n{\n\"jsonrpc\": \"2.0\",\n\"id\": 2,\n\"method\": \"tools/list\",\n\"params\": {}\n}\nTool invocation:\n\njson\nCopy\n{\n\"jsonrpc\": \"2.0\",\n\"id\": 3,\n\"method\": \"tools/call\",\n\"params\": {\n\"name\": \"crm_opportunity_read\",\n\"arguments\": {\n\"projection_id\": \"prj_crm_read\",\n\"opportunity_id\": \"ctx_opportunity_123\"\n}\n}\n}\nThe MCP Connector should translate this call into the same internal Tool Capability invocation used by REST and agents. It must not create a privileged execution path unique to MCP. MCP tools are model-controlled in the protocol, but implementations are advised to provide visible tool exposure and human ability to deny invocations.\n\nWorkbench GraphQL contract\nGraphQL is suitable for composing Business Context and Spine Cache read models while REST remains preferable for durable commands and idempotent external side effects.\n\ngraphql\nCopy\nquery WorkbenchOpportunity(\n$id: ID!\n$includeRelated: Boolean! = true\n) {\nopportunity(id: $id) {\nid\nversion\nname\nstage\nfreshness {\nobservedAt\nsourceWatermark\nstatus\n}\nsourceProjections {\nid\nconnectorType\nhealth\n}\neffectiveCapabilities {\nid\nversion\navailability\ndenialReason\n}\nrelated(limit: 20) @include(if: $includeRelated) {\nrelation\nobject {\nid\ntype\ndisplayLabel\n}\n}\n}\n}\nMutation:\n\ngraphql\nCopy\nmutation StartRenewalReview($input: StartRenewalReviewInput!) {\nstartRenewalReview(input: $input) {\norchestrationId\nstatus\napprovalRequired\n}\n}\nProduction GraphQL should use field-level authorisation, bounded pagination, query-cost limits, persisted operations for first-party clients and controlled introspection. GraphQL’s own security guidance notes that deployments serving only first-party clients may disable introspection outside development.\n\nPlatform operations, AI, agents and memory\nScaling model\nDeployment level Recommended topology Trigger for progression\nSmall Modular Product Package service, relational database, managed cache, object storage and managed queue Initial product validation and a small connector catalogue\nGrowing Separate Loader, Normalizer, Orchestrator and MCP workers; independently scaled queues External API latency, ingestion backlog or differing CPU/memory profiles\nMedium Dedicated read models, search index, workflow engine and model gateway; tenant-aware partitions Higher workflow concurrency, search volume and package diversity\nLarge Cell-based execution/data planes, regional routing, partitioned event streams and isolated high-risk connectors Large tenants, residency requirements, failure-domain isolation or noisy-neighbour effects\nRegulated/private Shared control plane with customer- or region-hosted data plane Data residency, network isolation or customer-managed-key requirements\n\nThe control plane can be globally available while execution and data remain regional, provided package metadata and policy versions are replicated safely. Workflow state and external side effects should maintain clear single-writer ownership to avoid duplicate operations during failover.\n\nObservability\nOpenTelemetry provides vendor-neutral instrumentation for traces, metrics and logs; its collector can aggregate, transform and scrub telemetry before export.\n\nA single trace should span:\n\ntext\nCopy\nWorkbench request\n→ One Auth/session validation\n→ Orchestrator\n→ capability evaluation\n→ agent or deterministic step\n→ tool invocation\n→ host connector runtime\n→ provider API\n→ context/cache update\nRecommended correlation attributes:\n\nAttribute Use\ntenant.id Tenant isolation and SLO aggregation\nprincipal.id_hash Correlation without emitting direct personal data\npackage.id and package.version Release impact analysis\nprojection.id Connector health and permission analysis\norchestration.id End-to-end workflow correlation\ntool.id and tool.version Tool reliability\nnormalizer.mapping_version Data-quality regressions\nmcp.protocol_version Compatibility analysis\nai.model_route Model performance and cost\napproval.required Human-control metrics\n\nDo not place raw provider tokens, prompts containing unrestricted source data, complete connector payloads or sensitive customer values in logs or trace baggage.\n\nOperational indicators should include auth success and latency, projection-reconciliation drift, connector lease failures, provider rate-limit utilisation, loader queue age, cursor lag, normalisation error rate, Spine freshness, orchestration completion and compensation rates, tool idempotency conflicts, MCP negotiation failures, agent approval rate, model cost and memory deletion lag.\n\nCI/CD and connector certification\nEvery package release should pass:\n\nTest layer Required coverage\nStatic validation Manifest, JSON Schema, permissions, policy and dependency checks\nUnit tests Mappings, capability evaluation, idempotency and error classification\nContract tests Host API, REST, GraphQL, events and MCP protocol contracts\nGolden fixture tests Provider raw fixture to expected canonical output\nReplay tests Duplicate, reordered and delayed events\nMigration tests Upgrade, downgrade where supported and rollback safety\nSecurity tests Token substitution, tenant crossover, scope escalation and prompt injection\nResilience tests Rate limit, timeout, partial response, provider outage and queue replay\nAgent evaluations Tool selection, refusal, grounding, policy compliance and adversarial context\nPerformance tests Loader throughput, cache latency, orchestration concurrency and hot-tenant behaviour\nCertification Signed record that the connector/package satisfies the supported platform matrix\n\nConnector compatibility should be defined across independent axes:\n\ntext\nCopy\nhost connector contract version\npackage manifest version\ncapability contract version\ncanonical schema version\nmapping version\ntool version\nMCP protocol version\nA connector should never be declared simply “version 3” without identifying which axis changed.\n\nRelease and backward-compatibility strategy\nUse additive schema evolution wherever possible. Consumers should ignore unknown optional fields, but producers must not silently change the meaning of an existing field. Breaking changes require a new major contract, a compatibility adapter or a migration.\n\nRecommended rollout sequence:\n\ntext\nCopy\ndevelopment tenant\n→ automated certification\n→ internal tenant\n→ shadow read traffic\n→ canary tenant cohort\n→ limited production\n→ broad production\n→ old-version deprecation\nKubernetes Deployments can run multiple releases to implement a canary pattern and progressively update workloads, but equivalent methods can be implemented using serverless revisions, service-mesh routing or load-balancer weights.\n\nFor high-risk connector changes:\n\nRun old and new normalisers against the same immutable raw data.\nCompare output hashes and semantic differences.\nWrite new canonical versions to a shadow namespace.\nEnable reads for internal users.\nPromote by tenant cohort.\nMaintain a rollback adapter until the deprecation window closes.\nAI gateway and agent architecture\ndeterministic workflow\nagent-assisted\napproved\ndenied\nUser or Pipeline Command\nOrchestrator\nPolicy and Capability Evaluation\nWorkflow Step\nAgent Runtime\nContext and Memory Retrieval\nBusiness Context\nMemory\nAI Gateway\nApproved Model Provider\nProposed Plan / Tool Call\nSchema, Risk and Approval Validation\nTool Capability\nExplain / Request Approval\nHost Connector Runtime\nStructured Result\nExecution Ledger\nMemory and Context Pipelines\n\nShow code\nThe AI gateway should centralise model-provider configuration, supported data classifications, prompt assets, model routing, redaction, rate limits, cost attribution, response validation and evaluation. Agents must not hold model-provider keys directly.\n\nThe Orchestrator must remain the execution authority. An agent may propose a plan or tool call, but the Orchestrator validates:\n\ntext\nCopy\nprincipal\ntenant\nprojection\ntool and version\ninput schema\ncurrent capability\ndata classification\nside-effect category\napproval requirement\nidempotency key\nbudget and rate limit\nMCP sampling permits servers to request model generations through the client so that the client retains model-selection and permission control. It also recommends a human review path. This reinforces placing model governance in the AI gateway/host rather than distributing unrestricted provider keys to packages.\n\nBusiness Context versus Memory\nStore Status Content Can drive external action?\nBusiness Context Authoritative or explicitly qualified Canonical business entities, relations, verified assertions and provenance Yes, subject to policy\nSession memory Ephemeral Current Workbench or agent conversation state Only within the current governed run\nWorking memory Run-scoped Intermediate plan, retrieved evidence and tool results Only after Orchestrator validation\nEpisodic memory Derived Prior decisions, outcomes and user interactions Advisory; should reference execution records\nSemantic memory Derived Summaries, embeddings and reusable knowledge fragments Advisory; requires freshness and provenance checks\nSpine Cache Materialised read model Fast summary and navigational relationships No independent authority\n\nA memory item should include:\n\njson\nCopy\n{\n\"memory_id\": \"mem_01J...\",\n\"tenant_id\": \"ten_123\",\n\"principal_scope\": \"team:sales\",\n\"kind\": \"episodic\",\n\"content_ref\": \"encrypted://memory/...\",\n\"derived_from\": [\n\"orchestration:orch_01J...\",\n\"context:ctx_opportunity_123@v14\"\n],\n\"classification\": [\"tenant-confidential\"],\n\"created_at\": \"2026-08-06T07:30:00Z\",\n\"expires_at\": \"2026-11-04T07:30:00Z\",\n\"model_provenance\": {\n\"model_route\": \"enterprise-summariser\",\n\"prompt_version\": \"decision-summary@1.4\"\n},\n\"verification_status\": \"derived_unverified\"\n}\nPipelines should create memory only after applying tenant policy, classification, redaction and retention. Deletion or access-policy changes in source context must propagate to embeddings, summaries, caches and downstream indexes.\n\nAI privacy and compliance\nNIST’s AI Risk Management Framework treats privacy, security, transparency and reliability as interconnected system characteristics. Its supporting material recommends controls for data management, minimisation, deletion and model or endpoint security.\n\nRequired design controls should include:\n\nConcern Control\nData minimisation Retrieve only fields needed for the current task\nPurpose limitation Bind memory and model use to declared product purposes\nTenant separation Separate logical namespaces, policy evaluation and encryption context\nModel-provider handling Explicit policy for retention, training use, region and subprocessors\nPrompt injection Treat connector content as untrusted data, not executable instruction\nTool misuse Allowlists, typed arguments, side-effect classification and approval gates\nProvenance Preserve source, mapping, model, prompt and execution references\nExplainability Show evidence and actions in the Workbench rather than only model prose\nDeletion Propagate tombstones through raw, canonical, cache, memory and vector indexes\nEvaluation Test grounding, policy adherence, unsafe action rate and data leakage\nHuman oversight Require review for consequential or externally mutating actions\nRetention Separate operational audit retention from conversational-memory retention\n\nThe target compliance profile should be selected per market and customer—such as SOC 2, ISO 27001, GDPR, HIPAA or sector-specific requirements—rather than hard-coded into the architecture. The baseline must nevertheless support auditability, least privilege, configurable retention, subject deletion, encryption, regional deployment and customer-specific policy.\n\nRoadmap, effort, decision gates and risk register\nThe ranges below are indicative engineering person-weeks, not calendar commitments. They intentionally remain broad because the host’s existing authentication, connector and deployment capabilities were not specified. Procurement, external certification and customer-specific security reviews are excluded.\n\nImplementation roadmap\nPhase Scope and milestone Indicative effort Exit criteria\nArchitecture contracts Confirm glossary, adK contract, trust boundaries, connector projection invariants and versioning model 3–6 person-weeks Approved architecture decision records and threat model\nOne Auth foundation Host assertion validation, Workbench session, tenant mapping, revocation and audit 8–16 person-weeks End-to-end host-controlled login with no provider credential replication\nProjection and capability control plane Projection registry, Discovery, capability intersection and host reconciliation 10–20 person-weeks A host connector produces policy-limited projections visible in Discovery\nPackage Control Plane Signed manifests, package lifecycle, compatibility matrix and installation 8–18 person-weeks Certified package can be installed, activated, upgraded and rolled back\nLoader and raw ingestion Pull, webhook, cursor, rate-limit, raw landing and replay 12–24 person-weeks per connector family plus shared foundation Incremental and backfill ingestion survive duplicates and restart\nNormalizer and Business Context Canonical schemas, mappings, provenance, identity resolution and validation 14–30 person-weeks for foundation; mappings vary by domain Provider fixtures reproducibly generate canonical context\nSpine Cache and Workbench read path Read model, freshness, search projection and GraphQL composition 10–22 person-weeks Workbench reads context with source, freshness and effective capabilities\nOrchestrator and Tool Capability Durable state machine, idempotency, approval, compensation and execution ledger 16–32 person-weeks Controlled read and write tools execute through host connector runtime\nMCP Connector Stable MCP baseline, lifecycle, tool/resource bindings, OAuth metadata and audit 8–18 person-weeks Workbench or approved MCP client negotiates and calls governed tools\nAI gateway, Agents and Memory Model abstraction, retrieval, bounded agent loop, evaluation, memory lifecycle 16–36 person-weeks Agent can propose and complete a governed workflow with evidence and approval\nOperational hardening SLOs, OTel, tenancy tests, canary, disaster recovery and connector certification 12–28 person-weeks Production readiness review and rollback-tested release\nScale and enterprise options Cells, regional data planes, customer-managed keys and private execution Unspecified until deployment obligations are known Validated against named enterprise requirements\n\nArchitecturecontracts\nTrust boundaries\nGlossary and versionaxes\nIdentity and controlplane\nOne Auth\nProjections andcapabilities\nPackage lifecycle\nData foundation\nLoader\nNormalizer\nBusiness Context\nSpine Cache\nGoverned execution\nOrchestrator\nTool Capability\nWorkbench actions\nInteroperability\nMCP Connector\nConnectorcertification\nIntelligence\nAI gateway\nAgents\nMemory pipelines\nEnterprise hardening\nObservability andSLOs\nRegional or privatedata planes\nRelative implementation sequence\n\nShow code\nRecommended milestone definitions\nMilestone Demonstrable product outcome\nHost-controlled entry A user enters through One Auth, while the host remains the identity authority\nFirst projection One host connector appears as two product projections with different permissions\nFirst context spine Workbench displays a canonical entity assembled from a host-connected source\nFirst safe action A write tool shows a dry-run diff, requests approval and executes idempotently\nFirst package upgrade A package is upgraded with schema compatibility checks and rollback\nFirst MCP surface Approved tools are exposed through MCP without a separate privileged path\nFirst governed agent Agent retrieves evidence, proposes a plan and invokes only policy-approved tools\nProduction readiness Revocation, outage, replay, rollback, deletion and cross-tenant tests pass\n\nArchitecture decision gates\nBefore committing to major infrastructure, the engineering and product teams should decide:\n\nDecision Option A Option B Selection criterion\nHost execution All provider calls remain in host runtime Short-lived delegated workers Latency, host capacity and credential-governance policy\nContext store Relational plus JSON Document or graph specialised store Actual query and traversal measurements\nOrchestration Embedded state machine Dedicated durable workflow engine Workflow duration, compensation complexity and operational maturity\nSpine search Database text/JSON indexes Dedicated search cluster Relevance, scale and facet requirements\nAgent framework In-house minimal runtime External agent SDK/framework Portability, auditability, evaluation and lock-in\nMCP release Stable 2025-11-25 2026-07-28 RC features Finalisation status and client compatibility\nMulti-region Regional tenancy cells Active-active context Residency, RTO/RPO and conflict tolerance\nToken format Opaque JWT Revocation needs versus local verification and disclosure concerns\n\nRisk register\nRisk Probability Impact Early indicator Mitigation Owner\nHost versus ecosystem authority becomes ambiguous High Critical Product services begin requesting provider credentials directly Enforce architecture invariant and credential-scanning tests Architecture and Security\nProjected connectors accumulate more rights than intended Medium Critical Projection grant exceeds package declaration Compute intersection at runtime; continuous reconciliation Identity and Connector Platform\nadK becomes an unbounded “miscellaneous” layer High High Business logic and orchestration migrate into SDK helpers Publish narrow interface and explicit non-responsibilities Platform Architecture\nCanonical model over-generalises domains Medium High Extensive opaque attributes and connector-specific exceptions Small stable core plus versioned domain extensions Data Architecture\nSpine Cache is treated as authoritative Medium High Writes or irreversible decisions depend only on cache state Include provenance/freshness and authoritative fallback Context Platform\nConnector changes break normalisation High High Validation errors or semantic diff increase after provider update Raw replay, mapping versions, fixture monitoring and canary Connector Engineering\nDuplicate or indeterminate side effects Medium Critical Timeouts followed by repeated provider writes Idempotency keys, execution ledger and provider-status reconciliation Orchestration\nMCP evolves faster than the platform adapter High Medium Client negotiation failures and divergent tool schemas Version pinning, adapter layer and compatibility suite Interoperability\nAgents bypass deterministic controls Medium Critical Direct tool credentials or unlogged actions appear Orchestrator-only execution and deny-by-default policy AI Platform and Security\nPrompt injection through connector data High High Retrieved content attempts to influence tool policy Data/instruction separation, tool allowlist and egress control AI Security\nMemory retains data beyond source policy Medium Critical Deleted source remains retrievable semantically Provenance graph, tombstones and deletion verification jobs Data Governance\nMulti-tenant leakage through cache keys or search Low–Medium Critical Result from wrong tenant/principal context Tenant-inclusive keys, row-level policy, isolation tests Platform Security\nExternal-provider rate limits undermine UX High Medium Queue lag and throttling increase Adaptive concurrency, prioritisation and freshness disclosure Connector Operations\nWorkflow engine becomes operational bottleneck Medium High Growing queue age or state-store contention Partition by tenant/cell and isolate long-running steps Platform Operations\nPackage compatibility matrix becomes unmanageable Medium High Numerous pairwise exceptions and manual upgrades Explicit compatibility axes, certification automation and deprecation policy Package Platform\nEnterprise compliance requirements arrive late Medium High Sales requests residency, CMK or private execution after build Preserve regional and private data-plane seams from the start Product and Security\nModel-provider dependency creates lock-in or outage risk Medium Medium–High Prompts and response parsing depend on one provider AI gateway, portable schemas and evaluated fallback routes AI Platform\nObservability leaks sensitive business data Medium High Raw prompts, tokens or records appear in logs Telemetry schema, redaction processor and automated scanning SRE and Security\nRevocation propagation is too slow Medium Critical Revoked host connector continues executing Priority revocation channel, lease expiry and deny check at execution Identity Platform\nProduct scope expands before core invariants stabilise High High Multiple connectors and agents precede one certified end-to-end path Vertical-slice milestones and explicit readiness gates Product and Engineering\n\nFinal recommended target state\nThe target architecture should satisfy the following invariants:\n\nNo Product Package component, Workbench module, agent or MCP client stores a provider refresh token.\nEvery projected connector resolves to one host connector and a strictly narrower effective capability set.\nEvery external side effect has an execution ledger entry, idempotency strategy and identifiable authorising principal.\nBusiness Context is the governed factual layer; Memory and Spine Cache are derived layers.\nAgents can propose actions but cannot bypass Orchestrator, policy, approval or Tool Capability contracts.\nAll packages, schemas, capabilities, mappings, tools and protocol bindings are independently versioned.\nConnector revocation, tenant deletion and policy change propagate to projections, caches, MCP sessions, memory and pending workflows.\nSmall deployments can run economically without preventing later separation into cells, regional data planes or private execution environments.\nMCP is an interoperability surface, not the internal source of authority for tools or permissions.\nUser Workbench remains the human experience layer while host identity, connector control, platform workflow state and business context remain owned by their respective backend boundaries.\n"}