Unclassified

IntegrateWise July 30 Launch Infrastructure Freeze

Status: Approved

Decision date: 2026-07-27

Hard freeze: 2026-07-29

Production go-live: 2026-07-30

Context

IntegrateWise has less than three days to freeze and launch the authenticated
Connector Marketplace, Customer Zero path, and supporting publication
infrastructure. The repository contains competing browser identity paths,
multiple connector-credential adapters, a Next.js server application paired
with a stale static Pages deployment path, and public marketplace manifests
that are not yet grounded in verified runtime evidence.

The frozen architecture already names Clerk as the browser identity authority,
Gateway as the identity and tenant-resolution boundary, Pipeline as the sole
canonical Spine writer, and Integration Manager as the product surface for
connectors, synchronization, webhooks, and schemas.

Decision

The July 30 launch uses the following production ownership:

Concern	Final owner	Runtime
Browser identity and session	Clerk	Clerk production instance
User and organization claims	Clerk	Signed session token
Internal account and tenant resolution	Gateway	Cloudflare Worker
Product web application	IntegrateWise Workbench	Vercel at `app.integratewise.ai`
Provider OAuth and token refresh	Nango	Server-side credential wall
Connector binding state	Gateway and Integration services	Bounded operational store
Canonical entities and relationships	Adaptive Spine	Neon, written through Pipeline
MCP client authorization	Gateway OAuth boundary	`auth.integratewise.ai`
Public semantic MCP	MCP Connector	Exact frozen 19-tool surface
Plugin marketplace package	IW-Spine-Network Plugin	MCP-backed app UI, skills and host activation
MCP marketplace package	IW-Spine-Network MCP	Remote 19 tools, optional widgets and browser Workbench
Approval and action	Governance to Hermes	No approval token, no execution

Clerk is the only browser identity authority. Descope is disabled from the
browser launch path. Existing Descope outbound-adapter code is retained behind
a disabled compatibility boundary during the launch window and is not exposed
as a second production session path.

Nango is the single launch credential wall for provider OAuth and refresh.
External MCP clients authenticate through the Gateway-owned OAuth boundary,
not through a browser session or a Descope session.

Hosting Boundary

The Workbench is a Next.js 16 server application with authenticated routes and
route handlers. It will run on the already-linked Vercel project. Gateway,
OAuth, MCP, Pipeline, connector services, queues, service bindings, security
controls, and canonical data services remain on Cloudflare and Neon.

This is a frontend hosting correction, not a backend migration.

Browser
  -> app.integratewise.ai (Next.js Workbench on Vercel)
  -> Clerk production identity
  -> gateway.integratewise.ai (Cloudflare Worker)
      -> account and tenant resolution
      -> connector control APIs
      -> auth.integratewise.ai (MCP OAuth)
      -> Nango credential wall
      -> Pipeline
      -> Adaptive Spine / Neon

Identity Contract

Clerk Organizations are enabled and required for launch.
Personal accounts are disabled for launch.
user_id comes from the verified Clerk subject.
organization_id comes from the active Clerk Organization claim.
Gateway maps verified membership to the internal account_id and
tenant_id.
Tenant-scoped routes reject a missing active organization, missing canonical
membership, or inactive membership.
The browser cannot provide or override user, account, organization, or
tenant identity.
Customer Zero maps explicitly to iw-customer-zero through verified
membership.
Email-domain classification cannot by itself grant tenant ownership or an
owner role.
The current email-derived tenant fallback and automatic selection of the
first organization membership are stop-ship defects.

Connector and Spine Contract

An installed connector is operational only when it resolves the complete tuple:

(user_id, account_id, tenant_id, provider_key, provider_workspace_id,
 connector_binding_id, spine_connection_id, schema_binding_set)

The provider credential is represented only by an opaque authorization
reference. Provider tokens never enter the browser, Spine, AI prompts, or the
repository.

Gateway owns authenticated operational binding. Connector services own provider
transport. Pipeline validates schema compatibility and is the sole writer that
promotes canonical Connection, Connector, Schema, SyncJob, Webhook, Capability,
and TimelineEvent state into the Adaptive Spine.

A missing, mismatched, incompatible, revoked, or unpromoted binding is stale.
Stale bindings are excluded from synchronization, webhook promotion,
capability activation, connected totals, Workbench projections, Twin context,
and governed execution.

Release Lanes

Distribution infrastructure: IW-Spine-Network Plugin and
IW-Spine-Network MCP manifests, packages, OAuth registrations, UI resources,
browser Workbench launch, registry metadata, publication checks, and staging.
Customer Zero: the exact production customer path without bypasses.
Product: Integration Manager presents verified catalog, binding, schema,
sync, webhook, capability, health, and repair state.

Publication artifacts can be built and staged in the first lane. Immutable or
externally reviewed public submissions occur only after Customer Zero accepts
the release candidate.

Options Considered

Selected: Clerk + Vercel Workbench + Cloudflare Gateway + Nango

This is the smallest path that aligns the frozen architecture with the actual
Next.js and Gateway implementation. It establishes one browser identity, one
tenant-resolution boundary, one credential wall, and one canonical promotion
path.

Rejected: Descope as browser identity

This contradicts the frozen implementation contract and creates a token
validation conflict when Gateway is configured to validate Clerk first.

Rejected: runtime-selected Clerk/Descope browser identity

Two selectable session authorities produce ambiguous identity, tenant, refresh,
logout, and callback behavior. This is explicitly a stop-ship state.

Deferred: Descope as an alternate connector credential provider

The adapter can be evaluated after launch behind the provider abstraction. It
is not part of the July 30 production path.

Consequences

Positive

One browser credential wall and one authoritative membership path.
Clear account and tenant isolation.
Native Next.js hosting without moving platform services.
Existing Gateway and Nango connector work remains usable.
Customer Zero and public distribution consume the same contracts.

Negative

Legacy browser-auth code and environment configuration must be retired.
Existing connections may require repair or migration.
DNS, Clerk production configuration, and Vercel deployment are immediate
critical-path work.
External Marketplace review timelines cannot be guaranteed by July 30.

Stop-Ship Invariants

Production is blocked if any of the following is true:

the browser selects Descope while Clerk is configured;
Gateway cannot resolve verified account and tenant membership;
browser values can override authoritative identity;
a connector becomes operational without a canonical Spine Connection and a
compatible schema binding set;
a stale connector can sync, project, count as connected, enter Twin context,
or execute;
UI or Twin writes canonical Spine truth directly;
a failed live projection silently becomes demo data;
provider credentials leave the credential wall;
the public MCP differs from the frozen 19-tool surface;
the Plugin claims host DOM/app-credential access, shares Customer Zero state
or cannot render/fallback safely;
the MCP package cannot launch the standalone browser Workbench;
Governance or Hermes is bypassed;
any cross-tenant read or write succeeds;
required production endpoints are unhealthy.

Acceptance

This decision is accepted when a clean user can sign in through Clerk, enter
the correct tenant, install a launch connector through Nango, complete binding,
schema validation, initial synchronization, and Pipeline promotion, see the
canonical state in Integration Manager, and observe stale or cross-tenant state
fail closed.