One Auth, User Workbench and Platform Backend: Reference Architecture and Productisation Report

Status: SUPERSEDED REFERENCE / SOURCE PROVENANCE. Retained as input lineage. Its useful
identity, delegation and connector-projection material has been adapted into
INTEGRATEWISE_ARCHITECTURE.md v2.2. Conflicting host-trust,
naming, unrestricted-discovery or product-boundary claims must not be implemented.

Executive summary
The 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.

The 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.

One 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.

The Product Package should be divided into four logical planes:

Plane Components Purpose
Control plane Discovery, Capabilities, adK, connector projection registry Defines what packages, connectors, tools and schemas exist and who may use them
Integration data plane Loader, Normalizer, MCP Connector, Tool Capability Reads, transforms and acts on host-connected systems
Context plane Spine Cache, Business Context Provides fast operational views and durable governed business meaning
Execution plane Orchestrator Coordinates deterministic workflows, approvals, tools, services and agents

The 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.

The recommended product boundary is:

Host 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.

The most important implementation principles are:

Decision Recommendation
Connector ownership Host-only; projections carry no provider secrets
Session architecture Browser-to-backend session plus short-lived ecosystem access tokens
Delegated execution Per-operation connector lease or OAuth token exchange
Canonical data Business Context is durable and governed
Fast data Spine Cache is rebuildable and freshness-aware
Workflow engine Deterministic orchestration is authoritative; agents are bounded participants
Tool execution Every tool call passes policy, schema validation, idempotency and audit controls
API style REST for commands, GraphQL for Workbench composition, CloudEvents for asynchronous changes
MCP baseline Pin the stable 25 November 2025 specification initially; trial the 28 July 2026 release candidate behind protocol negotiation and feature flags
Scaling Begin as a modular platform; split ingestion, execution and AI workloads as scale or isolation demands
Multi-tenancy Tenant identifiers, policy labels and encryption boundaries must be present in every persistent and runtime context
Productisation Signed, versioned packages containing manifests, mappings, tools, policies, migrations and certification tests

As 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.

Reference model and component responsibilities
The 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.

Terminology 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.

Product Package
Component Recommended definition and primary responsibility Inputs and outputs Must not own
Discovery 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
Capabilities 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
Spine 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
adK 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
Orchestrator 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
Business 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
Loader 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
Normalizer 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
MCP 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
Tool 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

MCP 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.

adK 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.

Product and Platform Backend
Component Recommended responsibility Primary interfaces
User 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
Package Control Plane Stores, verifies, publishes, installs, activates, upgrades, deprecates and rolls back Product Packages. Package manifest API, artefact registry, signature verification and deployment events
Services Reusable domain and platform APIs such as tenancy, policy, audit, notifications, search, configuration and execution ledger. REST/gRPC/GraphQL and events
AI Model gateway that abstracts model providers, routing, redaction, model policy, prompt assets, usage, safety filters and evaluation. Model inference and embedding APIs
Agents 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
Memory 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
Pipelines Durable ingestion, transformation, indexing, enrichment, evaluation and maintenance workflows. Event subscriptions, scheduled jobs and pipeline control API

The 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.

Productisation model
A Product Package should be a signed, immutable release artefact containing:

Package element Contents
Manifest Package ID, version, compatibility ranges, required host capabilities and dependencies
Connector projections Supported host connector types and projection rules
Capability catalogue Read, write, search, event and administrative capabilities
Canonical schemas Entity, relation, event and error schemas
Loader definitions Extraction modes, pagination, webhook and cursor behaviour
Normalisation mappings Provider-to-canonical transformation and identity-resolution rules
Tool definitions Inputs, outputs, side-effect class, permissions and approval requirements
MCP bindings Resource, prompt and tool names, versions and policy bindings
UI metadata Workbench panels, labels, icons and display schema
Policy defaults Scope reduction, data classification, retention and approval policy
Migrations Data, configuration and cache migrations
Certification suite Contract tests, fixtures, replay tests, security assertions and compatibility cases

Recommended lifecycle:

validation fails
activation fails
rollback
Draft
Validated
Certified
Published
Installed
Activated
Deprecated
Retired

Show code
Commercially, 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.

Architecture and interaction flows
Overall logical architecture
Platform Backend
Product Package
Host Trust Boundary
derived retrieval
User
User Workbench
One Auth
Host Identity and Session Authority
Host Connector Control Plane
Host Connector Runtime
Host Credential Vault
Discovery
Capabilities
adK
Orchestrator
Loader
Normalizer
Business Context
Spine Cache
MCP Connector
Tool Capability
Package Control Plane
Services
AI Gateway
Agents
Memory
Pipelines

Show code
The 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.

A 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.

Host-controlled authentication flow
mermaid
Copy
sequenceDiagram
autonumber
actor User
participant WB as User Workbench
participant OA as One Auth
participant HostAuth as Host Auth Authority
participant HostConn as Host Connector Control Plane
participant Proj as Projection Service
participant Orch as Orchestrator
participant HostRun as Host Connector Runtime
participant Provider as External Provider

User->>WB: Open ecosystem
WB->>OA: Start login with host hint and PKCE challenge
OA->>HostAuth: Redirect or federated auth request
HostAuth->>User: Authenticate through host policy
User->>HostAuth: Credentials / MFA / enterprise SSO
HostAuth-->>OA: Signed code or assertion
OA->>HostAuth: Validate or exchange code
HostAuth-->>OA: Host identity, tenant and session claims
OA->>HostConn: Request authorised host connector descriptors
HostConn-->>OA: Connector IDs, types and effective grants
OA->>Proj: Materialise or refresh projections
Proj-->>OA: Projection IDs and capability bindings
OA-->>WB: Ecosystem session; no provider tokens

User->>WB: Invoke a connector-backed action
WB->>Orch: Command with projection ID
Orch->>HostConn: Request short-lived execution grant
HostConn-->>Orch: Audience-bound connector lease
Orch->>HostRun: Execute capability with lease
HostRun->>Provider: Call using host-held credential
Provider-->>HostRun: Provider response
HostRun-->>Orch: Structured result and provider metadata
Orch-->>WB: Result, state and audit reference

OIDC 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.

Connector projection mapping
Consumers
Capability Bindings
Projection Registry
Host
host_connector_id
same connector, reduced grant
host_connector_id
Host Connector
CRM Account A
Host Connector
Drive Account B
Projection
Workbench CRM Read
Projection
Sales Automation CRM Write
Projection
Workbench Drive Search
crm.account.read
crm.opportunity.update
drive.document.search
User Workbench
Agent
Pipeline

Show code
A projection should be modelled as a first-class resource with:

text
Copy
projection =
host connector reference

• product/package scope
• effective capabilities
• tenant and principal constraints
• policy reference
• schema/version bindings
• lifecycle and health state
  It should not include:

text
Copy
provider access token
provider refresh token
provider client secret
host session cookie
unrestricted host connector permissions
A 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.

Product Package to Platform Backend data flow
raw page or webhook
raw envelope
CloudEvent
canonical mutation
materialised view update
normalisation event
embed, summarise, classify
quality and lineage
query
authoritative detail
command
context request
fast lookup
agent task
model request
memory retrieval
proposed tool call
validated invocation
execution grant
result
audit and domain event
Host Connector Runtime
Loader
Raw Landing / Object Store
Event Bus
Normalizer
Business Context
Spine Cache
Platform Pipelines
Memory and Retrieval Index
Platform Services
User Workbench
Orchestrator
Agents
AI Gateway
Tool Capability

Show code
CloudEvents 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.

Suggested production visual. Create an SVG named “Host Authority and Ecosystem Execution Boundaries” with three vertically separated trust zones:

Host identity and credential zone.
Product Package integration and context zone.
Platform intelligence and operations zone.
Use 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.

Security, identity, interaction patterns and failure handling
Identity and token model
The recommended model uses different credential classes for different purposes rather than one ecosystem-wide bearer token.

Credential or session Issuer and holder Purpose Recommended properties
Host identity session Host; held by host-facing user agent Authentication under host policy Host-controlled MFA, device and enterprise SSO policy
Login transaction One Auth and Workbench Bind login initiation to callback PKCE, nonce/state, exact redirect matching and single use
Ecosystem browser session One Auth/BFF; browser receives secure cookie Maintain Workbench login HttpOnly, Secure, appropriate SameSite, CSRF protection and server-side revocation
Ecosystem access token One Auth; held by backend services Call ecosystem APIs Short-lived, audience-restricted, tenant- and subject-bound
Projection grant Host or projection authority Authorise use of a projected connector Contains projection, capability, policy and expiry claims
Connector execution lease Host connector control plane Authorise one operation or bounded execution window Narrow capability, provider account binding, idempotency and trace ID
Service identity Workload identity authority Service-to-service authentication mTLS or signed workload identity; automatically rotated
Provider token External provider; held only by host vault/runtime Access provider API Never exposed to Workbench, projection store, agents or model prompts

Where 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.

OAuth 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.

For 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.

Host connector and projection interaction patterns
Pattern Description Appropriate use Primary control
Host-mediated execution Product calls host runtime; host calls provider Default and strongest ownership boundary Provider credentials never leave host
Delegated 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
Event projection Host emits connector events consumed by Product Package Near-real-time ingestion Signed events, replay controls and tenant routing
Pull projection Loader asks host runtime for pages since a cursor Backfills and providers lacking webhooks Cursor checkpoint and rate-limit control
On-demand resource projection MCP or Workbench requests contextual data only when needed Expensive or sensitive sources Policy evaluation at read time
Cached projection Normalised subset is retained in Spine Cache or Business Context Repeated business operations and cross-system context Classification, retention, freshness and revocation propagation

A projected connector’s effective permissions should be the intersection of:

text
Copy
host connector permissions
∩ user or service entitlement
∩ package-declared requirement
∩ tenant policy
∩ tool-specific permission
∩ current risk and health policy
Security controls
Authorisation 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.

Sender-constrained options.

Option Advantages Costs and limitations
mTLS-bound token Strong workload authentication and token binding; suitable for managed backend services Certificate lifecycle, proxy/TLS-termination complexity and harder browser use
DPoP Application-layer proof of possession; useful when mTLS is impractical Key management in clients, nonce/replay handling and incomplete ecosystem support
Rotating bearer tokens Broadest compatibility and simplest implementation Stolen current token remains usable until expiry or revocation
Opaque token with introspection Central policy and immediate status checks Runtime dependency and added latency
Signed JWT Local verification and lower authorisation-server dependency Harder immediate revocation and greater risk of excessive claim disclosure

mTLS 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.

Revocation. 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.

Zero 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.

MCP-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.

Failure modes and mitigations
Failure mode Result Detection Mitigation and recovery
Host 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
Host 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
Host connector revoked Projection appears available but cannot execute Revocation event and execution denial Atomically suspend projections, clear leases and invalidate relevant cache entries
Projection drift Projection grants differ from host reality Scheduled reconciliation and version hash mismatch Host remains authoritative; reconcile and reduce permissions automatically
Scope or capability mismatch Tool visible but execution denied Discovery-versus-execution comparison Suppress unavailable tool; offer re-authorisation through host; never silently escalate
Provider token expiry Connector calls fail Host runtime receives provider auth error Host refreshes or marks reconnect-required; Product Package receives status, not refresh token
Provider throttling Load lag and user-facing delays Rate-limit headers, queue age and retry metrics Adaptive concurrency, backoff, prioritised queues and quota-aware scheduling
Duplicate webhook or retry Duplicate business mutation Event ID and idempotency checks Inbox table, deduplication key and idempotent normalisation
Loader cursor loss Missed or repeated records Cursor continuity checks and count reconciliation Persist cursor transactionally; replay from immutable raw landing zone
Poison record Normalisation pipeline stalls Repeated schema-validation failure Per-record dead-letter queue; continue batch; retain provenance and repair tool
Spine Cache stale Workbench shows old summary freshness_at, source watermark and lag metrics Show freshness; authoritative fallback to Business Context or source; rebuild asynchronously
Orchestration partial failure Some side effects applied Execution ledger and incomplete state Saga-style compensation, idempotent retry and human resolution queue
Tool timeout with unknown provider outcome Unsafe duplicate retry Timeout plus missing confirmation Query provider by idempotency key before retry; classify as indeterminate
MCP protocol mismatch Client/server cannot negotiate initialize rejection Support explicit version matrix and adapters; no best-guess protocol fallback
Agent 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
Memory contains deleted or stale data Privacy or correctness breach Retention scan and provenance comparison Tombstone propagation, re-indexing and deletion verification
Region or cell outage Tenant workload unavailable Health, queue and replication monitoring Cell failover where policy allows; preserve single-writer semantics for workflows

Data models, schemas, storage and caching
Canonical relationship model
contains
owns
projects
declares
receives
grants
implements
supplies
produces
transforms_to
governs
materialises
source
target
has
indexed_as
source
target
accepts
exposes
maps
carries
TENANT
PRINCIPAL
HOST_CONNECTOR
CONNECTOR_PROJECTION
PRODUCT_PACKAGE
CAPABILITY_GRANT
CAPABILITY
TOOL_BINDING
LOAD_JOB
RAW_RECORD
NORMALIZATION_RESULT
MAPPING_SPEC
CONTEXT_OBJECT
CONTEXT_RELATION
CONTEXT_ASSERTION
SPINE_ENTRY
SPINE_EDGE
MCP_SERVER
MCP_SESSION
MCP_TOOL_BINDING
MCP_INVOCATION

Show code
Every 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.

Spine Cache schema
The Spine Cache is a read model, not the canonical business record.

Entity or field Purpose
spine_entry_id Stable cache/read-model identifier
tenant_id Mandatory tenancy boundary
entity_type Canonical type such as person, account, document or workflow
canonical_object_id Reference to Business Context
display_label Workbench-friendly label
summary Compact materialised summary
search_tokens Keyword/full-text projection
projection_refs[] Relevant connector projections
capability_refs[] Capabilities that can operate on the entry
classification Data handling label
source_watermark Latest source event or cursor represented
freshness_at Time at which the view was known fresh
schema_version Read-model schema version
etag Optimistic caching and conditional read token
expires_at Optional policy-driven cache expiry
payload Bounded denormalised JSON for view rendering

spine_edge should contain from_entry_id, to_entry_id, relation_type, weight_or_rank, provenance_ref, valid_from, valid_to and schema_version.

Recommended indexes are:

text
Copy
(tenant_id, canonical_object_id)
(tenant_id, entity_type, freshness_at)
(tenant_id, projection_ref)
full-text or search index on display_label, summary and search_tokens
graph-like adjacency index on from_entry_id and to_entry_id
PostgreSQL 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.

Business Context schema
Entity Core fields
context_space space_id, tenant_id, name, policy_ref, schema_version
context_object object_id, space_id, type, canonical_key, attributes, status, valid_from, valid_to, version
context_relation relation_id, from_object_id, predicate, to_object_id, attributes, valid_from, valid_to
context_assertion assertion_id, subject_id, predicate, value_or_object_id, confidence, verification_status, validity
provenance_record provenance_id, source_projection_id, source_record_id, load_job_id, normalization_run_id, observed_at, transform_version
context_policy_label object_id, classification, retention_class, residency, purpose_limits

The recommended canonical object envelope is:

json
Copy
{
"object_id": "ctx_01J...",
"tenant_id": "ten_01J...",
"space_id": "space_sales",
"type": "crm.opportunity",
"canonical_key": "crm.opportunity:host-connector-123:provider-987",
"attributes": {
"name": "Enterprise Renewal",
"stage": "negotiation",
"amount": {
"value": "250000.00",
"currency": "INR"
}
},
"status": "active",
"valid_from": "2026-08-01T10:00:00Z",
"valid_to": null,
"version": 14,
"provenance": [
{
"projection_id": "prj_01J...",
"source_record_id": "provider-987",
"observed_at": "2026-08-06T06:15:00Z",
"mapping_version": "crm-normalizer@3.2.0"
}
],
"classification": ["tenant-confidential"]
}
Business 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.

Loader schema
Entity Important fields
load_job job_id, tenant_id, projection_id, mode, requested_by, status, started_at, completed_at, cursor_before, cursor_after, attempt
raw_record raw_record_id, job_id, source_object_type, source_id, operation, observed_at, event_id, content_type, payload_location, payload_hash
source_cursor projection_id, stream, cursor, watermark, updated_at, lease_owner, lease_expiry
load_error job_id, raw_record_id, category, provider_code, retryable, details, next_attempt_at
webhook_inbox event_id, projection_id, received_at, signature_valid, processing_status, dedupe_key

Raw 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.

Normalizer schema
Entity Important fields
mapping_spec mapping_id, connector_type, source_schema_version, target_schema_version, transform_version, status
normalization_run run_id, raw_record_id, mapping_id, status, started_at, completed_at
normalization_result run_id, canonical_type, canonical_id, operation, output_hash, quality_score
identity_resolution resolution_id, candidate_keys, resolved_object_id, method, confidence, review_status
validation_error run_id, field_path, rule, observed_value_ref, severity, resolution
lineage_edge source_record_id, canonical_object_id, transform_version, effective_at

Normalisers 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.

MCP Connector schema
Entity Important fields
mcp_server_registration server_id, tenant_id, endpoint_or_runtime, transport, supported_versions, auth_metadata, status
mcp_session session_id, server_id, principal_id, negotiated_version, client_capabilities, server_capabilities, started_at, ended_at
mcp_capability_snapshot session_id, resource_hash, prompt_hash, tool_hash, captured_at
mcp_tool_binding mcp_name, tool_capability_id, tool_version, input_schema, output_schema, approval_policy
mcp_invocation invocation_id, session_id, request_id, tool_binding_id, status, trace_id, result_ref, error_ref

MCP 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.

Storage and caching comparison
Storage choice Best fit Advantages Limitations Recommended role
Relational 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
In-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
Document 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
Search engine Workbench keyword, faceting and relevance Rich full-text search and aggregations Eventual consistency and operational overhead Search projection of Spine/Business Context
Graph database Deep relationship traversal and dependency analysis Efficient multi-hop graph queries Additional operational model and dual-write concerns Optional large-scale relationship index
Object 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
Event log or broker Connector events and pipeline decoupling Replay, fan-out and independent consumers Ordering, duplicate delivery and schema governance complexity Integration backbone
Vector 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

Redis 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.

Recommended caching strategy:

Data class Pattern Invalidation
Discovery manifest Read-through cache with ETag Package publication or deprecation event
Capability decision Short-lived decision cache Policy, identity, projection or host grant change
Connector health Stale-while-revalidate Health event or bounded expiry
Spine entity Event-updated materialised cache Canonical context event and connector revocation
Tool metadata Version-keyed immutable cache New tool version, not in-place mutation
Tool result Only for explicitly cacheable reads Source event, projection revocation or TTL
Workbench GraphQL response Per-user/tenant short cache Underlying entity and capability change
Agent retrieval result Query and policy-sensitive transient cache Context/memory update or conversation boundary

Cache 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.

API contracts and integration surfaces
OpenAPI 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.

All command APIs should support:

text
Copy
Authorization
X-Tenant-Id or tenant claim
Idempotency-Key
Traceparent
Content-Type
If-Match for version-sensitive changes
Prefer: respond-async where applicable
Errors should share a standard envelope:

json
Copy
{
"type": "https://errors.example.invalid/capability-denied",
"title": "Capability denied",
"status": 403,
"code": "CAPABILITY_DENIED",
"detail": "The projection does not grant crm.opportunity.update.",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"retryable": false,
"remediation": {
"kind": "host_reauthorisation",
"projection_id": "prj_01J..."
}
}
Discovery REST contract
http
Copy
GET /v1/discovery?package_id=sales-workbench&include=connectors,capabilities,mcp
Authorization: Bearer <ecosystem-access-token>
If-None-Match: "discovery-ten_123-v45"
json
Copy
{
"tenant_id": "ten_123",
"generated_at": "2026-08-06T07:00:00Z",
"etag": "discovery-ten_123-v45",
"packages": [
{
"package_id": "sales-workbench",
"version": "2.4.0",
"status": "active",
"compatible_platform": ">=3.1 <4.0"
}
],
"connector_projections": [
{
"projection_id": "prj_crm_read",
"host_connector_id": "host_conn_789",
"connector_type": "crm",
"status": "ready",
"freshness_at": "2026-08-06T06:58:30Z",
"capabilities": [
{
"id": "crm.opportunity.read",
"version": "1.2",
"availability": "available"
}
]
}
],
"mcp_servers": [
{
"server_id": "mcp_sales",
"protocol_versions": ["2025-11-25"],
"transport": "streamable-http"
}
]
}
Discovery should support conditional requests and immutable version references. A package or capability descriptor already retrieved by version should not change underneath clients.

Orchestrator REST contract
http
Copy
POST /v1/orchestrations
Authorization: Bearer <ecosystem-access-token>
Idempotency-Key: ****
json
Copy
{
"workflow": {
"id": "renewal-risk-review",
"version": "3.1.0"
},
"subject": {
"context_object_id": "ctx_opportunity_123"
},
"execution_mode": "agent_assisted",
"requested_capabilities": [
"crm.opportunity.read",
"document.search"
],
"constraints": {
"allow_side_effects": false,
"require_human_approval": true
},
"input": {
"review_period": "P90D"
}
}
http
Copy
HTTP/1.1 202 Accepted
Location: /v1/orchestrations/orch_01J...
json
Copy
{
"orchestration_id": "orch_01J...",
"status": "accepted",
"current_state": "validating_capabilities",
"links": {
"self": "/v1/orchestrations/orch_01J...",
"events": "/v1/orchestrations/orch_01J.../events"
}
}
The 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.

Loader REST and event contract
http
Copy
POST /v1/load-jobs
Authorization: Bearer <service-token>
Idempotency-Key: loader-crm-prj-123-2026-08-06T07:00Z
json
Copy
{
"projection_id": "prj_crm_read",
"mode": "incremental",
"object_types": ["account", "contact", "opportunity"],
"cursor": {
"strategy": "resume"
},
"delivery": {
"raw_retention_class": "standard",
"normalization_profile": "crm-canonical@3.2.0"
}
}
json
Copy
{
"job_id": "load_01J...",
"status": "queued",
"projection_id": "prj_crm_read",
"cursor_before": "opaque-host-cursor",
"estimated_records": null
}
CloudEvent-style result:

json
Copy
{
"specversion": "1.0",
"id": "evt_01J...",
"source": "/loaders/crm/prj_crm_read",
"type": "com.example.loader.raw-record.received.v1",
"subject": "opportunity/provider-987",
"time": "2026-08-06T07:03:14Z",
"datacontenttype": "application/json",
"tenantid": "ten_123",
"projectionid": "prj_crm_read",
"data": {
"raw_record_id": "raw_01J...",
"operation": "upsert",
"payload_ref": "object://raw/ten_123/load_01J/raw_01J",
"payload_hash": "sha256:..."
}
}
Tool Capability REST contract
http
Copy
POST /v1/tool-invocations
Authorization: Bearer <ecosystem-or-agent-token>
Idempotency-Key: tool-call-01J...
json
Copy
{
"tool": {
"id": "crm.opportunity.update-stage",
"version": "2.0.1"
},
"projection_id": "prj_crm_write",
"context": {
"orchestration_id": "orch_01J...",
"subject_object_id": "ctx_opportunity_123"
},
"input": {
"opportunity_id": "ctx_opportunity_123",
"expected_version": 14,
"new_stage": "closed_won"
},
"execution": {
"dry_run": true,
"approval_token": null
}
}
json
Copy
{
"invocation_id": "toolinv_01J...",
"status": "approval_required",
"effect_preview": {
"operation": "update",
"target": "crm.opportunity",
"changes": [
{
"path": "/stage",
"from": "negotiation",
"to": "closed_won"
}
]
},
"approval": {
"request_id": "approval_01J...",
"required_role": "sales_manager"
}
}
Every tool definition should include:

json
Copy
{
"id": "crm.opportunity.update-stage",
"version": "2.0.1",
"side_effect": "external_write",
"input_schema": {},
"output_schema": {},
"required_capabilities": ["crm.opportunity.update"],
"idempotency": "required",
"approval_policy": "conditional",
"timeout_policy": "provider-status-check-before-retry",
"data_classifications": ["tenant-confidential"]
}
MCP management and invocation contracts
Management API:

http
Copy
POST /v1/mcp/servers
Authorization: Bearer <admin-token>
json
Copy
{
"name": "sales-context",
"transport": "streamable-http",
"endpoint": "https://mcp.internal.example.invalid/sales",
"allowed_protocol_versions": ["2025-11-25"],
"auth_mode": "oauth-protected-resource",
"tool_policy": {
"allow": [
"crm.opportunity.read",
"document.search"
],
"deny_side_effects_without_approval": true
}
}
MCP initialisation follows JSON-RPC:

json
Copy
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-11-25",
"capabilities": {
"roots": {
"listChanged": true
},
"sampling": {}
},
"clientInfo": {
"name": "user-workbench",
"version": "3.4.0"
}
}
}
Tool discovery:

json
Copy
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}
Tool invocation:

json
Copy
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "crm_opportunity_read",
"arguments": {
"projection_id": "prj_crm_read",
"opportunity_id": "ctx_opportunity_123"
}
}
}
The 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.

Workbench GraphQL contract
GraphQL is suitable for composing Business Context and Spine Cache read models while REST remains preferable for durable commands and idempotent external side effects.

graphql
Copy
query WorkbenchOpportunity(
$id: ID!
$includeRelated: Boolean! = true
) {
opportunity(id: $id) {
id
version
name
stage
freshness {
observedAt
sourceWatermark
status
}
sourceProjections {
id
connectorType
health
}
effectiveCapabilities {
id
version
availability
denialReason
}
related(limit: 20) @include(if: $includeRelated) {
relation
object {
id
type
displayLabel
}
}
}
}
Mutation:

graphql
Copy
mutation StartRenewalReview($input: StartRenewalReviewInput!) {
startRenewalReview(input: $input) {
orchestrationId
status
approvalRequired
}
}
Production 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.

Platform operations, AI, agents and memory
Scaling model
Deployment level Recommended topology Trigger for progression
Small Modular Product Package service, relational database, managed cache, object storage and managed queue Initial product validation and a small connector catalogue
Growing Separate Loader, Normalizer, Orchestrator and MCP workers; independently scaled queues External API latency, ingestion backlog or differing CPU/memory profiles
Medium Dedicated read models, search index, workflow engine and model gateway; tenant-aware partitions Higher workflow concurrency, search volume and package diversity
Large 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
Regulated/private Shared control plane with customer- or region-hosted data plane Data residency, network isolation or customer-managed-key requirements

The 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.

Observability
OpenTelemetry provides vendor-neutral instrumentation for traces, metrics and logs; its collector can aggregate, transform and scrub telemetry before export.

A single trace should span:

text
Copy
Workbench request
→ One Auth/session validation
→ Orchestrator
→ capability evaluation
→ agent or deterministic step
→ tool invocation
→ host connector runtime
→ provider API
→ context/cache update
Recommended correlation attributes:

Attribute Use
tenant.id Tenant isolation and SLO aggregation
principal.id_hash Correlation without emitting direct personal data
package.id and package.version Release impact analysis
projection.id Connector health and permission analysis
orchestration.id End-to-end workflow correlation
tool.id and tool.version Tool reliability
normalizer.mapping_version Data-quality regressions
mcp.protocol_version Compatibility analysis
ai.model_route Model performance and cost
approval.required Human-control metrics

Do not place raw provider tokens, prompts containing unrestricted source data, complete connector payloads or sensitive customer values in logs or trace baggage.

Operational 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.

CI/CD and connector certification
Every package release should pass:

Test layer Required coverage
Static validation Manifest, JSON Schema, permissions, policy and dependency checks
Unit tests Mappings, capability evaluation, idempotency and error classification
Contract tests Host API, REST, GraphQL, events and MCP protocol contracts
Golden fixture tests Provider raw fixture to expected canonical output
Replay tests Duplicate, reordered and delayed events
Migration tests Upgrade, downgrade where supported and rollback safety
Security tests Token substitution, tenant crossover, scope escalation and prompt injection
Resilience tests Rate limit, timeout, partial response, provider outage and queue replay
Agent evaluations Tool selection, refusal, grounding, policy compliance and adversarial context
Performance tests Loader throughput, cache latency, orchestration concurrency and hot-tenant behaviour
Certification Signed record that the connector/package satisfies the supported platform matrix

Connector compatibility should be defined across independent axes:

text
Copy
host connector contract version
package manifest version
capability contract version
canonical schema version
mapping version
tool version
MCP protocol version
A connector should never be declared simply “version 3” without identifying which axis changed.

Release and backward-compatibility strategy
Use 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.

Recommended rollout sequence:

text
Copy
development tenant
→ automated certification
→ internal tenant
→ shadow read traffic
→ canary tenant cohort
→ limited production
→ broad production
→ old-version deprecation
Kubernetes 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.

For high-risk connector changes:

Run old and new normalisers against the same immutable raw data.
Compare output hashes and semantic differences.
Write new canonical versions to a shadow namespace.
Enable reads for internal users.
Promote by tenant cohort.
Maintain a rollback adapter until the deprecation window closes.
AI gateway and agent architecture
deterministic workflow
agent-assisted
approved
denied
User or Pipeline Command
Orchestrator
Policy and Capability Evaluation
Workflow Step
Agent Runtime
Context and Memory Retrieval
Business Context
Memory
AI Gateway
Approved Model Provider
Proposed Plan / Tool Call
Schema, Risk and Approval Validation
Tool Capability
Explain / Request Approval
Host Connector Runtime
Structured Result
Execution Ledger
Memory and Context Pipelines

Show code
The 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.

The Orchestrator must remain the execution authority. An agent may propose a plan or tool call, but the Orchestrator validates:

text
Copy
principal
tenant
projection
tool and version
input schema
current capability
data classification
side-effect category
approval requirement
idempotency key
budget and rate limit
MCP 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.

Business Context versus Memory
Store Status Content Can drive external action?
Business Context Authoritative or explicitly qualified Canonical business entities, relations, verified assertions and provenance Yes, subject to policy
Session memory Ephemeral Current Workbench or agent conversation state Only within the current governed run
Working memory Run-scoped Intermediate plan, retrieved evidence and tool results Only after Orchestrator validation
Episodic memory Derived Prior decisions, outcomes and user interactions Advisory; should reference execution records
Semantic memory Derived Summaries, embeddings and reusable knowledge fragments Advisory; requires freshness and provenance checks
Spine Cache Materialised read model Fast summary and navigational relationships No independent authority

A memory item should include:

json
Copy
{
"memory_id": "mem_01J...",
"tenant_id": "ten_123",
"principal_scope": "team:sales",
"kind": "episodic",
"content_ref": "encrypted://memory/...",
"derived_from": [
"orchestration:orch_01J...",
"context:ctx_opportunity_123@v14"
],
"classification": ["tenant-confidential"],
"created_at": "2026-08-06T07:30:00Z",
"expires_at": "2026-11-04T07:30:00Z",
"model_provenance": {
"model_route": "enterprise-summariser",
"prompt_version": "decision-summary@1.4"
},
"verification_status": "derived_unverified"
}
Pipelines 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.

AI privacy and compliance
NIST’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.

Required design controls should include:

Concern Control
Data minimisation Retrieve only fields needed for the current task
Purpose limitation Bind memory and model use to declared product purposes
Tenant separation Separate logical namespaces, policy evaluation and encryption context
Model-provider handling Explicit policy for retention, training use, region and subprocessors
Prompt injection Treat connector content as untrusted data, not executable instruction
Tool misuse Allowlists, typed arguments, side-effect classification and approval gates
Provenance Preserve source, mapping, model, prompt and execution references
Explainability Show evidence and actions in the Workbench rather than only model prose
Deletion Propagate tombstones through raw, canonical, cache, memory and vector indexes
Evaluation Test grounding, policy adherence, unsafe action rate and data leakage
Human oversight Require review for consequential or externally mutating actions
Retention Separate operational audit retention from conversational-memory retention

The 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.

Roadmap, effort, decision gates and risk register
The 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.

Implementation roadmap
Phase Scope and milestone Indicative effort Exit criteria
Architecture contracts Confirm glossary, adK contract, trust boundaries, connector projection invariants and versioning model 3–6 person-weeks Approved architecture decision records and threat model
One 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
Projection 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
Package Control Plane Signed manifests, package lifecycle, compatibility matrix and installation 8–18 person-weeks Certified package can be installed, activated, upgraded and rolled back
Loader 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
Normalizer 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
Spine 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
Orchestrator 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
MCP 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
AI 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
Operational hardening SLOs, OTel, tenancy tests, canary, disaster recovery and connector certification 12–28 person-weeks Production readiness review and rollback-tested release
Scale and enterprise options Cells, regional data planes, customer-managed keys and private execution Unspecified until deployment obligations are known Validated against named enterprise requirements

Architecturecontracts
Trust boundaries
Glossary and versionaxes
Identity and controlplane
One Auth
Projections andcapabilities
Package lifecycle
Data foundation
Loader
Normalizer
Business Context
Spine Cache
Governed execution
Orchestrator
Tool Capability
Workbench actions
Interoperability
MCP Connector
Connectorcertification
Intelligence
AI gateway
Agents
Memory pipelines
Enterprise hardening
Observability andSLOs
Regional or privatedata planes
Relative implementation sequence

Show code
Recommended milestone definitions
Milestone Demonstrable product outcome
Host-controlled entry A user enters through One Auth, while the host remains the identity authority
First projection One host connector appears as two product projections with different permissions
First context spine Workbench displays a canonical entity assembled from a host-connected source
First safe action A write tool shows a dry-run diff, requests approval and executes idempotently
First package upgrade A package is upgraded with schema compatibility checks and rollback
First MCP surface Approved tools are exposed through MCP without a separate privileged path
First governed agent Agent retrieves evidence, proposes a plan and invokes only policy-approved tools
Production readiness Revocation, outage, replay, rollback, deletion and cross-tenant tests pass

Architecture decision gates
Before committing to major infrastructure, the engineering and product teams should decide:

Decision Option A Option B Selection criterion
Host execution All provider calls remain in host runtime Short-lived delegated workers Latency, host capacity and credential-governance policy
Context store Relational plus JSON Document or graph specialised store Actual query and traversal measurements
Orchestration Embedded state machine Dedicated durable workflow engine Workflow duration, compensation complexity and operational maturity
Spine search Database text/JSON indexes Dedicated search cluster Relevance, scale and facet requirements
Agent framework In-house minimal runtime External agent SDK/framework Portability, auditability, evaluation and lock-in
MCP release Stable 2025-11-25 2026-07-28 RC features Finalisation status and client compatibility
Multi-region Regional tenancy cells Active-active context Residency, RTO/RPO and conflict tolerance
Token format Opaque JWT Revocation needs versus local verification and disclosure concerns

Risk register
Risk Probability Impact Early indicator Mitigation Owner
Host versus ecosystem authority becomes ambiguous High Critical Product services begin requesting provider credentials directly Enforce architecture invariant and credential-scanning tests Architecture and Security
Projected connectors accumulate more rights than intended Medium Critical Projection grant exceeds package declaration Compute intersection at runtime; continuous reconciliation Identity and Connector Platform
adK becomes an unbounded “miscellaneous” layer High High Business logic and orchestration migrate into SDK helpers Publish narrow interface and explicit non-responsibilities Platform Architecture
Canonical model over-generalises domains Medium High Extensive opaque attributes and connector-specific exceptions Small stable core plus versioned domain extensions Data Architecture
Spine Cache is treated as authoritative Medium High Writes or irreversible decisions depend only on cache state Include provenance/freshness and authoritative fallback Context Platform
Connector changes break normalisation High High Validation errors or semantic diff increase after provider update Raw replay, mapping versions, fixture monitoring and canary Connector Engineering
Duplicate or indeterminate side effects Medium Critical Timeouts followed by repeated provider writes Idempotency keys, execution ledger and provider-status reconciliation Orchestration
MCP evolves faster than the platform adapter High Medium Client negotiation failures and divergent tool schemas Version pinning, adapter layer and compatibility suite Interoperability
Agents bypass deterministic controls Medium Critical Direct tool credentials or unlogged actions appear Orchestrator-only execution and deny-by-default policy AI Platform and Security
Prompt injection through connector data High High Retrieved content attempts to influence tool policy Data/instruction separation, tool allowlist and egress control AI Security
Memory retains data beyond source policy Medium Critical Deleted source remains retrievable semantically Provenance graph, tombstones and deletion verification jobs Data Governance
Multi-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
External-provider rate limits undermine UX High Medium Queue lag and throttling increase Adaptive concurrency, prioritisation and freshness disclosure Connector Operations
Workflow engine becomes operational bottleneck Medium High Growing queue age or state-store contention Partition by tenant/cell and isolate long-running steps Platform Operations
Package compatibility matrix becomes unmanageable Medium High Numerous pairwise exceptions and manual upgrades Explicit compatibility axes, certification automation and deprecation policy Package Platform
Enterprise 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
Model-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
Observability leaks sensitive business data Medium High Raw prompts, tokens or records appear in logs Telemetry schema, redaction processor and automated scanning SRE and Security
Revocation propagation is too slow Medium Critical Revoked host connector continues executing Priority revocation channel, lease expiry and deny check at execution Identity Platform
Product 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

Final recommended target state
The target architecture should satisfy the following invariants:

No Product Package component, Workbench module, agent or MCP client stores a provider refresh token.
Every projected connector resolves to one host connector and a strictly narrower effective capability set.
Every external side effect has an execution ledger entry, idempotency strategy and identifiable authorising principal.
Business Context is the governed factual layer; Memory and Spine Cache are derived layers.
Agents can propose actions but cannot bypass Orchestrator, policy, approval or Tool Capability contracts.
All packages, schemas, capabilities, mappings, tools and protocol bindings are independently versioned.
Connector revocation, tenant deletion and policy change propagate to projections, caches, MCP sessions, memory and pending workflows.
Small deployments can run economically without preventing later separation into cells, regional data planes or private execution environments.
MCP is an interoperability surface, not the internal source of authority for tools or permissions.
User Workbench remains the human experience layer while host identity, connector control, platform workflow state and business context remain owned by their respective backend boundaries.