{"slug":"internal/operations/2026-07-27-launch-infrastructure-freeze-design","title":"IntegrateWise July 30 Launch Infrastructure Freeze","section":"internal","sectionLabel":"Internal","status":"unclassified","type":"document","path":"internal/operations/2026-07-27-launch-infrastructure-freeze-design.mdx","bytes":9438,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** Approved\n\n**Decision date:** 2026-07-27\n\n**Hard freeze:** 2026-07-29\n\n**Production go-live:** 2026-07-30\n\n## Context\n\nIntegrateWise has less than three days to freeze and launch the authenticated\nConnector Marketplace, Customer Zero path, and supporting publication\ninfrastructure. The repository contains competing browser identity paths,\nmultiple connector-credential adapters, a Next.js server application paired\nwith a stale static Pages deployment path, and public marketplace manifests\nthat are not yet grounded in verified runtime evidence.\n\nThe frozen architecture already names Clerk as the browser identity authority,\nGateway as the identity and tenant-resolution boundary, Pipeline as the sole\ncanonical Spine writer, and Integration Manager as the product surface for\nconnectors, synchronization, webhooks, and schemas.\n\n## Decision\n\nThe July 30 launch uses the following production ownership:\n\n| Concern                                | Final owner                      | Runtime                                                 |\n| -------------------------------------- | -------------------------------- | ------------------------------------------------------- |\n| Browser identity and session           | Clerk                            | Clerk production instance                               |\n| User and organization claims           | Clerk                            | Signed session token                                    |\n| Internal account and tenant resolution | Gateway                          | Cloudflare Worker                                       |\n| Product web application                | IntegrateWise Workbench          | Vercel at `app.integratewise.ai`                        |\n| Provider OAuth and token refresh       | Nango                            | Server-side credential wall                             |\n| Connector binding state                | Gateway and Integration services | Bounded operational store                               |\n| Canonical entities and relationships   | Adaptive Spine                   | Neon, written through Pipeline                          |\n| MCP client authorization               | Gateway OAuth boundary           | `auth.integratewise.ai`                                 |\n| Public semantic MCP                    | MCP Connector                    | Exact frozen 19-tool surface                            |\n| Plugin marketplace package             | IW-Spine-Network Plugin          | MCP-backed app UI, skills and host activation           |\n| MCP marketplace package                | IW-Spine-Network MCP             | Remote 19 tools, optional widgets and browser Workbench |\n| Approval and action                    | Governance to Hermes             | No approval token, no execution                         |\n\nClerk is the only browser identity authority. Descope is disabled from the\nbrowser launch path. Existing Descope outbound-adapter code is retained behind\na disabled compatibility boundary during the launch window and is not exposed\nas a second production session path.\n\nNango is the single launch credential wall for provider OAuth and refresh.\nExternal MCP clients authenticate through the Gateway-owned OAuth boundary,\nnot through a browser session or a Descope session.\n\n## Hosting Boundary\n\nThe Workbench is a Next.js 16 server application with authenticated routes and\nroute handlers. It will run on the already-linked Vercel project. Gateway,\nOAuth, MCP, Pipeline, connector services, queues, service bindings, security\ncontrols, and canonical data services remain on Cloudflare and Neon.\n\nThis is a frontend hosting correction, not a backend migration.\n\n```text\nBrowser\n  -> app.integratewise.ai (Next.js Workbench on Vercel)\n  -> Clerk production identity\n  -> gateway.integratewise.ai (Cloudflare Worker)\n      -> account and tenant resolution\n      -> connector control APIs\n      -> auth.integratewise.ai (MCP OAuth)\n      -> Nango credential wall\n      -> Pipeline\n      -> Adaptive Spine / Neon\n```\n\n## Identity Contract\n\n1. Clerk Organizations are enabled and required for launch.\n2. Personal accounts are disabled for launch.\n3. `user_id` comes from the verified Clerk subject.\n4. `organization_id` comes from the active Clerk Organization claim.\n5. Gateway maps verified membership to the internal `account_id` and\n   `tenant_id`.\n6. Tenant-scoped routes reject a missing active organization, missing canonical\n   membership, or inactive membership.\n7. The browser cannot provide or override user, account, organization, or\n   tenant identity.\n8. Customer Zero maps explicitly to `iw-customer-zero` through verified\n   membership.\n9. Email-domain classification cannot by itself grant tenant ownership or an\n   owner role.\n10. The current email-derived tenant fallback and automatic selection of the\n    first organization membership are stop-ship defects.\n\n## Connector and Spine Contract\n\nAn installed connector is operational only when it resolves the complete tuple:\n\n```text\n(user_id, account_id, tenant_id, provider_key, provider_workspace_id,\n connector_binding_id, spine_connection_id, schema_binding_set)\n```\n\nThe provider credential is represented only by an opaque authorization\nreference. Provider tokens never enter the browser, Spine, AI prompts, or the\nrepository.\n\nGateway owns authenticated operational binding. Connector services own provider\ntransport. Pipeline validates schema compatibility and is the sole writer that\npromotes canonical Connection, Connector, Schema, SyncJob, Webhook, Capability,\nand TimelineEvent state into the Adaptive Spine.\n\nA missing, mismatched, incompatible, revoked, or unpromoted binding is stale.\nStale bindings are excluded from synchronization, webhook promotion,\ncapability activation, connected totals, Workbench projections, Twin context,\nand governed execution.\n\n## Release Lanes\n\n1. **Distribution infrastructure:** IW-Spine-Network Plugin and\n   IW-Spine-Network MCP manifests, packages, OAuth registrations, UI resources,\n   browser Workbench launch, registry metadata, publication checks, and staging.\n2. **Customer Zero:** the exact production customer path without bypasses.\n3. **Product:** Integration Manager presents verified catalog, binding, schema,\n   sync, webhook, capability, health, and repair state.\n\nPublication artifacts can be built and staged in the first lane. Immutable or\nexternally reviewed public submissions occur only after Customer Zero accepts\nthe release candidate.\n\n## Options Considered\n\n### Selected: Clerk + Vercel Workbench + Cloudflare Gateway + Nango\n\nThis is the smallest path that aligns the frozen architecture with the actual\nNext.js and Gateway implementation. It establishes one browser identity, one\ntenant-resolution boundary, one credential wall, and one canonical promotion\npath.\n\n### Rejected: Descope as browser identity\n\nThis contradicts the frozen implementation contract and creates a token\nvalidation conflict when Gateway is configured to validate Clerk first.\n\n### Rejected: runtime-selected Clerk/Descope browser identity\n\nTwo selectable session authorities produce ambiguous identity, tenant, refresh,\nlogout, and callback behavior. This is explicitly a stop-ship state.\n\n### Deferred: Descope as an alternate connector credential provider\n\nThe adapter can be evaluated after launch behind the provider abstraction. It\nis not part of the July 30 production path.\n\n## Consequences\n\n### Positive\n\n- One browser credential wall and one authoritative membership path.\n- Clear account and tenant isolation.\n- Native Next.js hosting without moving platform services.\n- Existing Gateway and Nango connector work remains usable.\n- Customer Zero and public distribution consume the same contracts.\n\n### Negative\n\n- Legacy browser-auth code and environment configuration must be retired.\n- Existing connections may require repair or migration.\n- DNS, Clerk production configuration, and Vercel deployment are immediate\n  critical-path work.\n- External Marketplace review timelines cannot be guaranteed by July 30.\n\n## Stop-Ship Invariants\n\nProduction is blocked if any of the following is true:\n\n- the browser selects Descope while Clerk is configured;\n- Gateway cannot resolve verified account and tenant membership;\n- browser values can override authoritative identity;\n- a connector becomes operational without a canonical Spine Connection and a\n  compatible schema binding set;\n- a stale connector can sync, project, count as connected, enter Twin context,\n  or execute;\n- UI or Twin writes canonical Spine truth directly;\n- a failed live projection silently becomes demo data;\n- provider credentials leave the credential wall;\n- the public MCP differs from the frozen 19-tool surface;\n- the Plugin claims host DOM/app-credential access, shares Customer Zero state\n  or cannot render/fallback safely;\n- the MCP package cannot launch the standalone browser Workbench;\n- Governance or Hermes is bypassed;\n- any cross-tenant read or write succeeds;\n- required production endpoints are unhealthy.\n\n## Acceptance\n\nThis decision is accepted when a clean user can sign in through Clerk, enter\nthe correct tenant, install a launch connector through Nango, complete binding,\nschema validation, initial synchronization, and Pipeline promotion, see the\ncanonical state in Integration Manager, and observe stale or cross-tenant state\nfail closed.\n"}