MCP Pool Deployment-Ring and Resource-Isolation Contract

Status: Frozen implementation contract for PR #109
Scope: MCP Pool, Operational Spine Capability Fabric, shared Platform services, marketplaces, memory, queues, logs, and external-customer activation

1. Decision

IntegrateWise uses one versioned code line and three isolated operational rings:

1. development
2. customer_zero
3. customer_production

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

                         ONE VERSIONED PRODUCT LINE
                                      |
                   same schemas / contracts / packages
                                      |
                +---------------------+---------------------+
                |                     |                     |
                v                     v                     v
          DEVELOPMENT          CUSTOMER ZERO        CUSTOMER PRODUCTION
          non-production       production-internal  external multi-tenant
          isolated resources   isolated resources   isolated prod resources

This is deployment-ring isolation, not a code fork and not one physical stack per ordinary external tenant.

2. Ring definitions

2.1 Development

Purpose:

• feature development;
• migrations and contract testing;
• connector preview validation;
• synthetic or explicitly approved test data;
• destructive testing and failure injection.

Rules:

• cannot access Customer Zero or customer-production credentials;
• cannot produce to production queues;
• cannot bind to production D1, KV, R2, Vectorize, AI Search, Durable Objects, workflows, or audit sinks;
• may expose additional diagnostic capabilities only through authenticated development/operator surfaces;
• must still use the remote-only MCP topology rather than local vendor fan-out.

2.2 Customer Zero

Purpose:

• first production tenant;
• IntegrateWise operational workload;
• proof environment for the exact external Product contract;
• controlled Platform-operator administration.

Rules:

• expected tenant is iw-customer-zero, resolved from authenticated membership and installation state;
• uses real IntegrateWise-owned connections and production policies;
• has dedicated state, credentials, queues, caches, indexes, memory, evidence, and audit streams;
• exposes the exact customer-facing 19-tool contract for parity;
• internal operator capabilities remain a separate RBAC-governed Platform surface and are never added to the public MCP catalog;
• cannot be used as development, marketplace-review, demo, or customer seed data.

2.3 Customer Production

Purpose:

• external customer Plugin and MCP installations;
• browser Workbench tenants;
• shared IntegrateWise-managed production Platform.

Rules:

• each request resolves a dynamic tenant, account, workspace, membership, installation, policy, and Spine Network;
• external tenants share stateless Platform deployments where safe;
• 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;
• no external tenant receives Customer Zero state, credentials, queues, cache, indexes, evidence, memory, or audit;
• dedicated physical customer infrastructure is optional and policy-driven for approved isolation tiers, not the default for every tenant.

3. Profile dimensions

The following dimensions must not be collapsed:

Dimension	Examples	Authority
Deployment ring	development, customer_zero, customer_production	deployment configuration
Audience profile	Customer Zero, external customer	Gateway identity and membership
Entry channel	Plugin, MCP, browser Workbench, operator administration	installation and host binding
Tenant	iw-customer-zero or dynamic customer tenant	authenticated Gateway resolution
Capability profile	plan, role, connector state, installation state, governance policy	ADK + Operational Spine state

A client-provided header or tool argument cannot select a deployment ring, audience profile, tenant, or operator mode.

4. Resource classes

4.1 Resources that must never be shared across rings

• D1 databases and database IDs;
• KV namespaces and namespace IDs;
• Queues, producers, consumers, DLQs, and queue names;
• R2 buckets containing tenant or operational data;
• Vectorize and AI Search indexes/namespaces containing operational, memory, or knowledge data;
• Durable Object namespaces and state;
• Workflow instances and workflow state;
• secrets, OAuth credentials, encryption keys, signing keys, and service tokens;
• connector connection IDs and provider credential references;
• idempotency stores, outboxes, installation state, rate-limit state, and caches;
• agent/session logs, audit logs, evidence stores, observability datasets, and replay streams;
• memory-promotion queues, promotion audit, and organisational memory;
• webhook endpoints or signing identities whose authority crosses rings.

4.2 Assets that may be shared as versioned definitions

• source code and package artifacts;
• schemas and migrations as files;
• ADK capability definitions;
• public 19-tool schemas;
• connector catalog metadata;
• marketplace listing metadata;
• runtime-adapter interfaces;
• policy templates and activation-profile definitions without secrets or tenant identities;
• test fixtures that contain no production data.

4.3 Stateless compute rule

The same source and build artifact may be deployed into every ring. Each deployment must receive only same-ring bindings.

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

5. Resource topology

The target is not one new resource per service per customer. The target is one authoritative inventory with resources grouped by ownership and isolation requirement.

Example naming:

iw-dev-spine-cache
iw-cz-spine-cache
iw-prod-spine-cache

iw-dev-memory-promote
iw-cz-memory-promote
iw-prod-memory-promote

iw-dev-knowledge
iw-cz-knowledge
iw-prod-knowledge

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

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

6. MCP Pool deployments

The MCP Pool is deployed once per ring:

integratewise-mcp-pool-dev
integratewise-mcp-pool-customer-zero
integratewise-mcp-pool-prod

Exact deployed names may differ, but the three-ring distinction is mandatory.

Each Pool deployment:

• embeds the same ADK registry and CapabilityResolver version;
• resolves context only from same-ring Operational Spine resources;
• binds only to same-ring Integration Manager, Provider Manager, Pipeline, Knowledge, Continuity, Intelligence, Twin, Agent Runtime, Task, Workflow, Marketplace Installation, and audit runtimes;
• publishes only to same-ring queues;
• uses same-ring agent registry, connector state, marketplace installation state, memory, indexes, and audit sinks;
• rejects a resolved tenant whose ring/profile does not match the deployment identity.

No Cloudflare service binding may cross from one ring to another.

7. Capability behavior by ring

Concern	Development	Customer Zero	Customer Production
Public semantic tools	contract-compatible; diagnostics separate	exact 19	exact 19
Internal capability discovery	developer/operator only	RBAC operator only	never exposed
Connectors	preview/test credentials	IntegrateWise-owned production connections	customer-authorized connections
Writes	test ring only	governed production writes	governed tenant-scoped writes
Approval	required for production-parity tests	mandatory	mandatory
Memory promotion	isolated test lifecycle	isolated C0 lifecycle	tenant-scoped prod lifecycle
Marketplace installation	test installations	private/staged C0 installations	public customer installations
Logs and audit	isolated non-prod	isolated production-internal	tenant-scoped production
Model policy	development policy	C0 production policy	tenant entitlement policy

Development may simulate failures or bypass external billing only through explicit test fixtures. It must not weaken the governance contract used by the production rings.

8. External-customer isolation inside customer production

Physical ring isolation and logical tenant isolation are both required.

Every customer-production record/event must carry the applicable identity tuple:

tenant_id
tenant_account_id
workspace_id
spine_network_id
installation_id or connection_id
entity_id or runtime_record_id
source_connection_id
correlation_id
provenance
policy_version

Required enforcement:

• D1 queries include tenant/workspace predicates;
• KV keys begin with ring and tenant scope;
• queue messages include signed tenant/workspace context and are validated by consumers;
• Vectorize/AI Search queries always filter tenant metadata;
• Durable Object IDs are derived from trusted tenant/workspace identity;
• R2 object keys include tenant scope and access is mediated by a service contract;
• logs and metrics carry tenant scope but redact secrets and private reasoning;
• credentials are referenced, never returned through MCP results;
• cross-tenant operations require an explicit machine-client capability and governance policy; empty allow-lists cannot silently mean global access in customer production.

9. Memory and promotion isolation

Each ring owns an independent promotion lifecycle:

same-ring Spine write
  -> same-ring spine.written event
  -> same-ring MEMORY_PROMOTE queue
  -> same-ring Pipeline promotion consumer
  -> governance state
  -> same-ring org memory and promotion audit
  -> same-ring knowledge index

Customer-production promotion is additionally tenant-scoped. No memory item, promotion event, audit row, or vector may move between tenants or rings through fallback behavior.

10. Marketplace and connector isolation

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

shared connector definition
  + ring-local publication state
  + tenant-local installation/consent
  + tenant-local connection and credential reference
  = eligible tenant capability

The MCP Pool consumes the resulting eligibility state. It does not infer capability availability from a static connector list alone.

11. Audit and provisioning guard

The resource-isolation audit must fail CI for:

• placeholder or empty IDs in deployable environments;
• the same mutable resource identifier used in more than one ring;
• a service binding targeting a Worker in another ring;
• queue producer and consumer ring mismatch;
• production resources referenced by development configuration;
• missing tenant-scope enforcement metadata for customer-production resources;
• unclassified resources;
• secrets or raw credentials in configuration files.

The audit should distinguish:

1. declaration aliases;
2. actual Cloudflare resource identities;
3. immutable shared definitions;
4. mutable ring-local resources;
5. tenant-dedicated resources created only by approved isolation policy.

A provisioning generator must consume a reviewed resource inventory. It must not create a resource for every raw binding occurrence.

12. Required resource inventory

Create one machine-readable inventory, for example:

resources:
  - logical_id: spine_cache
    kind: d1
    owner: operational_spine
    isolation: per_ring
    bindings:
      - SPINE_CACHE
      - CACHE_DB
  - logical_id: memory_promote
    kind: queue
    owner: pipeline
    isolation: per_ring
    bindings:
      - MEMORY_PROMOTE

The inventory must define:

• logical resource ID;
• Cloudflare resource kind;
• owning service/domain;
• isolation class (global_immutable, per_ring, per_tenant_policy);
• binding aliases;
• retention and backup policy;
• producer/consumer set;
• migration/provisioning status;
• real resource IDs per ring;
• deployment dependencies.

Wrangler manifests should be generated or verified against this inventory.

13. Remediation sequence

1. Commit the audit script and complete violation report.
2. Build the normalized resource inventory from all Wrangler declarations.
3. Classify each logical resource by owner and isolation class.
4. Deduplicate aliases before provisioning.
5. Provision missing development resources.
6. Provision missing Customer Zero resources.
7. Provision missing customer-production resources.
8. Patch Wrangler files from inventory output.
9. Run the audit and require zero critical/error violations.
10. Run package tests and binding-contract tests.
11. Deploy in dependency order within each ring.
12. Run authenticated cross-ring negative tests and customer-production cross-tenant negative tests.
13. Enable CI deployment blocking only after the inventory and manifests agree.

14. Deployment order per ring

state resources and secrets
  -> Provider / Integration / Marketplace Installation
  -> Pipeline / Spine / Knowledge / Continuity
  -> Intelligence / Twin / Agent Runtime
  -> Task / Workflow / audit sinks
  -> MCP Pool
  -> MCP Connector / public IW-Spine-Network ingress
  -> Gateway / Workbench / Plugin surfaces

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

15. Acceptance criteria

• one code line and one semantic capability model;
• three isolated deployment rings;
• no mutable Cloudflare resource identity shared across rings;
• no direct cross-ring service binding, queue, credential, cache, memory, or audit path;
• Customer Zero proves the exact public contract without exposing operator capabilities;
• external customers use shared production compute with strict tenant isolation by default;
• dedicated customer infrastructure is policy-driven rather than automatic;
• the public MCP remains remote-only and exposes exactly 19 semantic tools;
• the internal Pool remains coupled to ADK, Operational Spine, marketplaces, agent runtimes, logs, memory, and promotion queues;
• resource audit and provisioning are driven from a reviewed logical inventory, not raw binding count.