{"slug":"architecture/MCP_POOL_DEPLOYMENT_RING_ISOLATION_CONTRACT","title":"MCP Pool Deployment-Ring and Resource-Isolation Contract","section":"architecture","sectionLabel":"Architecture","status":"current","type":"document","path":"architecture/MCP_POOL_DEPLOYMENT_RING_ISOLATION_CONTRACT.mdx","bytes":16350,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** Frozen implementation contract for PR #109  \n**Scope:** MCP Pool, Operational Spine Capability Fabric, shared Platform services, marketplaces, memory, queues, logs, and external-customer activation\n\n## 1. Decision\n\nIntegrateWise uses one versioned code line and three isolated operational rings:\n\n1. `development`\n2. `customer_zero`\n3. `customer_production`\n\nThe rings use the same public IW-Spine-Network semantic contract and the same internal capability model. They do not share mutable state, credentials, queues, caches, indexes, audit streams, or runtime identity.\n\n```text\n                         ONE VERSIONED PRODUCT LINE\n                                      |\n                   same schemas / contracts / packages\n                                      |\n                +---------------------+---------------------+\n                |                     |                     |\n                v                     v                     v\n          DEVELOPMENT          CUSTOMER ZERO        CUSTOMER PRODUCTION\n          non-production       production-internal  external multi-tenant\n          isolated resources   isolated resources   isolated prod resources\n```\n\nThis is deployment-ring isolation, not a code fork and not one physical stack per ordinary external tenant.\n\n## 2. Ring definitions\n\n### 2.1 Development\n\nPurpose:\n\n- feature development;\n- migrations and contract testing;\n- connector preview validation;\n- synthetic or explicitly approved test data;\n- destructive testing and failure injection.\n\nRules:\n\n- cannot access Customer Zero or customer-production credentials;\n- cannot produce to production queues;\n- cannot bind to production D1, KV, R2, Vectorize, AI Search, Durable Objects, workflows, or audit sinks;\n- may expose additional diagnostic capabilities only through authenticated development/operator surfaces;\n- must still use the remote-only MCP topology rather than local vendor fan-out.\n\n### 2.2 Customer Zero\n\nPurpose:\n\n- first production tenant;\n- IntegrateWise operational workload;\n- proof environment for the exact external Product contract;\n- controlled Platform-operator administration.\n\nRules:\n\n- expected tenant is `iw-customer-zero`, resolved from authenticated membership and installation state;\n- uses real IntegrateWise-owned connections and production policies;\n- has dedicated state, credentials, queues, caches, indexes, memory, evidence, and audit streams;\n- exposes the exact customer-facing 19-tool contract for parity;\n- internal operator capabilities remain a separate RBAC-governed Platform surface and are never added to the public MCP catalog;\n- cannot be used as development, marketplace-review, demo, or customer seed data.\n\n### 2.3 Customer Production\n\nPurpose:\n\n- external customer Plugin and MCP installations;\n- browser Workbench tenants;\n- shared IntegrateWise-managed production Platform.\n\nRules:\n\n- each request resolves a dynamic tenant, account, workspace, membership, installation, policy, and Spine Network;\n- external tenants share stateless Platform deployments where safe;\n- mutable production resources are dedicated to the `customer_production` ring and enforce tenant scope in every record, key, vector metadata item, queue message, object identifier, log event, and credential reference;\n- no external tenant receives Customer Zero state, credentials, queues, cache, indexes, evidence, memory, or audit;\n- dedicated physical customer infrastructure is optional and policy-driven for approved isolation tiers, not the default for every tenant.\n\n## 3. Profile dimensions\n\nThe following dimensions must not be collapsed:\n\n| Dimension          | Examples                                                           | Authority                        |\n| ------------------ | ------------------------------------------------------------------ | -------------------------------- |\n| Deployment ring    | development, customer_zero, customer_production                    | deployment configuration         |\n| Audience profile   | Customer Zero, external customer                                   | Gateway identity and membership  |\n| Entry channel      | Plugin, MCP, browser Workbench, operator administration            | installation and host binding    |\n| Tenant             | `iw-customer-zero` or dynamic customer tenant                      | authenticated Gateway resolution |\n| Capability profile | plan, role, connector state, installation state, governance policy | ADK + Operational Spine state    |\n\nA client-provided header or tool argument cannot select a deployment ring, audience profile, tenant, or operator mode.\n\n## 4. Resource classes\n\n### 4.1 Resources that must never be shared across rings\n\n- D1 databases and database IDs;\n- KV namespaces and namespace IDs;\n- Queues, producers, consumers, DLQs, and queue names;\n- R2 buckets containing tenant or operational data;\n- Vectorize and AI Search indexes/namespaces containing operational, memory, or knowledge data;\n- Durable Object namespaces and state;\n- Workflow instances and workflow state;\n- secrets, OAuth credentials, encryption keys, signing keys, and service tokens;\n- connector connection IDs and provider credential references;\n- idempotency stores, outboxes, installation state, rate-limit state, and caches;\n- agent/session logs, audit logs, evidence stores, observability datasets, and replay streams;\n- memory-promotion queues, promotion audit, and organisational memory;\n- webhook endpoints or signing identities whose authority crosses rings.\n\n### 4.2 Assets that may be shared as versioned definitions\n\n- source code and package artifacts;\n- schemas and migrations as files;\n- ADK capability definitions;\n- public 19-tool schemas;\n- connector catalog metadata;\n- marketplace listing metadata;\n- runtime-adapter interfaces;\n- policy templates and activation-profile definitions without secrets or tenant identities;\n- test fixtures that contain no production data.\n\n### 4.3 Stateless compute rule\n\nThe same source and build artifact may be deployed into every ring. Each deployment must receive only same-ring bindings.\n\nExternal tenants may share the `customer_production` stateless Worker deployment. Development, Customer Zero, and customer production must not share a live Worker deployment when that would allow cross-ring bindings, secrets, cache, logs, or runtime identity.\n\n## 5. Resource topology\n\nThe target is not one new resource per service per customer. The target is one authoritative inventory with resources grouped by ownership and isolation requirement.\n\nExample naming:\n\n```text\niw-dev-spine-cache\niw-cz-spine-cache\niw-prod-spine-cache\n\niw-dev-memory-promote\niw-cz-memory-promote\niw-prod-memory-promote\n\niw-dev-knowledge\niw-cz-knowledge\niw-prod-knowledge\n```\n\nA service receives a dedicated database or queue when transactional ownership, retention, scaling, blast radius, or security requires it. Otherwise, multiple services may use the same same-ring resource through explicit schemas/prefixes and narrow service authority.\n\nDo not generate hundreds of resources merely because hundreds of Wrangler binding declarations exist. First normalize declarations into an ownership inventory and deduplicate aliases that represent the same intended resource.\n\n## 6. MCP Pool deployments\n\nThe MCP Pool is deployed once per ring:\n\n```text\nintegratewise-mcp-pool-dev\nintegratewise-mcp-pool-customer-zero\nintegratewise-mcp-pool-prod\n```\n\nExact deployed names may differ, but the three-ring distinction is mandatory.\n\nEach Pool deployment:\n\n- embeds the same ADK registry and CapabilityResolver version;\n- resolves context only from same-ring Operational Spine resources;\n- binds only to same-ring Integration Manager, Provider Manager, Pipeline, Knowledge, Continuity, Intelligence, Twin, Agent Runtime, Task, Workflow, Marketplace Installation, and audit runtimes;\n- publishes only to same-ring queues;\n- uses same-ring agent registry, connector state, marketplace installation state, memory, indexes, and audit sinks;\n- rejects a resolved tenant whose ring/profile does not match the deployment identity.\n\nNo Cloudflare service binding may cross from one ring to another.\n\n## 7. Capability behavior by ring\n\n| Concern                       | Development                               | Customer Zero                              | Customer Production             |\n| ----------------------------- | ----------------------------------------- | ------------------------------------------ | ------------------------------- |\n| Public semantic tools         | contract-compatible; diagnostics separate | exact 19                                   | exact 19                        |\n| Internal capability discovery | developer/operator only                   | RBAC operator only                         | never exposed                   |\n| Connectors                    | preview/test credentials                  | IntegrateWise-owned production connections | customer-authorized connections |\n| Writes                        | test ring only                            | governed production writes                 | governed tenant-scoped writes   |\n| Approval                      | required for production-parity tests      | mandatory                                  | mandatory                       |\n| Memory promotion              | isolated test lifecycle                   | isolated C0 lifecycle                      | tenant-scoped prod lifecycle    |\n| Marketplace installation      | test installations                        | private/staged C0 installations            | public customer installations   |\n| Logs and audit                | isolated non-prod                         | isolated production-internal               | tenant-scoped production        |\n| Model policy                  | development policy                        | C0 production policy                       | tenant entitlement policy       |\n\nDevelopment may simulate failures or bypass external billing only through explicit test fixtures. It must not weaken the governance contract used by the production rings.\n\n## 8. External-customer isolation inside customer production\n\nPhysical ring isolation and logical tenant isolation are both required.\n\nEvery customer-production record/event must carry the applicable identity tuple:\n\n```text\ntenant_id\ntenant_account_id\nworkspace_id\nspine_network_id\ninstallation_id or connection_id\nentity_id or runtime_record_id\nsource_connection_id\ncorrelation_id\nprovenance\npolicy_version\n```\n\nRequired enforcement:\n\n- D1 queries include tenant/workspace predicates;\n- KV keys begin with ring and tenant scope;\n- queue messages include signed tenant/workspace context and are validated by consumers;\n- Vectorize/AI Search queries always filter tenant metadata;\n- Durable Object IDs are derived from trusted tenant/workspace identity;\n- R2 object keys include tenant scope and access is mediated by a service contract;\n- logs and metrics carry tenant scope but redact secrets and private reasoning;\n- credentials are referenced, never returned through MCP results;\n- cross-tenant operations require an explicit machine-client capability and governance policy; empty allow-lists cannot silently mean global access in customer production.\n\n## 9. Memory and promotion isolation\n\nEach ring owns an independent promotion lifecycle:\n\n```text\nsame-ring Spine write\n  -> same-ring spine.written event\n  -> same-ring MEMORY_PROMOTE queue\n  -> same-ring Pipeline promotion consumer\n  -> governance state\n  -> same-ring org memory and promotion audit\n  -> same-ring knowledge index\n```\n\nCustomer-production promotion is additionally tenant-scoped. No memory item, promotion event, audit row, or vector may move between tenants or rings through fallback behavior.\n\n## 10. Marketplace and connector isolation\n\nMarketplace definitions may be shared as versioned metadata. Installation, consent, publication activation, connection health, credential references, hydration state, and connector execution are ring-local and tenant-scoped.\n\n```text\nshared connector definition\n  + ring-local publication state\n  + tenant-local installation/consent\n  + tenant-local connection and credential reference\n  = eligible tenant capability\n```\n\nThe MCP Pool consumes the resulting eligibility state. It does not infer capability availability from a static connector list alone.\n\n## 11. Audit and provisioning guard\n\nThe resource-isolation audit must fail CI for:\n\n- placeholder or empty IDs in deployable environments;\n- the same mutable resource identifier used in more than one ring;\n- a service binding targeting a Worker in another ring;\n- queue producer and consumer ring mismatch;\n- production resources referenced by development configuration;\n- missing tenant-scope enforcement metadata for customer-production resources;\n- unclassified resources;\n- secrets or raw credentials in configuration files.\n\nThe audit should distinguish:\n\n1. declaration aliases;\n2. actual Cloudflare resource identities;\n3. immutable shared definitions;\n4. mutable ring-local resources;\n5. tenant-dedicated resources created only by approved isolation policy.\n\nA provisioning generator must consume a reviewed resource inventory. It must not create a resource for every raw binding occurrence.\n\n## 12. Required resource inventory\n\nCreate one machine-readable inventory, for example:\n\n```yaml\nresources:\n  - logical_id: spine_cache\n    kind: d1\n    owner: operational_spine\n    isolation: per_ring\n    bindings:\n      - SPINE_CACHE\n      - CACHE_DB\n  - logical_id: memory_promote\n    kind: queue\n    owner: pipeline\n    isolation: per_ring\n    bindings:\n      - MEMORY_PROMOTE\n```\n\nThe inventory must define:\n\n- logical resource ID;\n- Cloudflare resource kind;\n- owning service/domain;\n- isolation class (`global_immutable`, `per_ring`, `per_tenant_policy`);\n- binding aliases;\n- retention and backup policy;\n- producer/consumer set;\n- migration/provisioning status;\n- real resource IDs per ring;\n- deployment dependencies.\n\nWrangler manifests should be generated or verified against this inventory.\n\n## 13. Remediation sequence\n\n1. Commit the audit script and complete violation report.\n2. Build the normalized resource inventory from all Wrangler declarations.\n3. Classify each logical resource by owner and isolation class.\n4. Deduplicate aliases before provisioning.\n5. Provision missing development resources.\n6. Provision missing Customer Zero resources.\n7. Provision missing customer-production resources.\n8. Patch Wrangler files from inventory output.\n9. Run the audit and require zero critical/error violations.\n10. Run package tests and binding-contract tests.\n11. Deploy in dependency order within each ring.\n12. Run authenticated cross-ring negative tests and customer-production cross-tenant negative tests.\n13. Enable CI deployment blocking only after the inventory and manifests agree.\n\n## 14. Deployment order per ring\n\n```text\nstate resources and secrets\n  -> Provider / Integration / Marketplace Installation\n  -> Pipeline / Spine / Knowledge / Continuity\n  -> Intelligence / Twin / Agent Runtime\n  -> Task / Workflow / audit sinks\n  -> MCP Pool\n  -> MCP Connector / public IW-Spine-Network ingress\n  -> Gateway / Workbench / Plugin surfaces\n```\n\nA ring is not promoted merely because Workers deploy. Promotion requires health, authenticated contract tests, tenant isolation tests, governance tests, Spine reconciliation, and memory-promotion verification.\n\n## 15. Acceptance criteria\n\n- one code line and one semantic capability model;\n- three isolated deployment rings;\n- no mutable Cloudflare resource identity shared across rings;\n- no direct cross-ring service binding, queue, credential, cache, memory, or audit path;\n- Customer Zero proves the exact public contract without exposing operator capabilities;\n- external customers use shared production compute with strict tenant isolation by default;\n- dedicated customer infrastructure is policy-driven rather than automatic;\n- the public MCP remains remote-only and exposes exactly 19 semantic tools;\n- the internal Pool remains coupled to ADK, Operational Spine, marketplaces, agent runtimes, logs, memory, and promotion queues;\n- resource audit and provisioning are driven from a reviewed logical inventory, not raw binding count.\n"}