{"slug":"internal/architecture/INTEGRATEWISE_ARCHITECTURE","title":"IntegrateWise — Architecture","section":"internal","sectionLabel":"Internal","status":"unclassified","type":"long-form","path":"internal/architecture/INTEGRATEWISE_ARCHITECTURE.mdx","bytes":239988,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** CANONICAL · Architecture source of truth\n**Authority hierarchy:** This doc > AGENTS.md > package-level docs > code + tests\n**Version:** 2.2 (v1.1 Book-of-Record reconciliation)\n**Date:** 2026-08-06 · v1.1 implementation freeze reconciliation\n**Supersedes:** every other document in `docs/architecture/`. See [Appendix L](#appendix-l--document-disposition).\n\n---\n\n## How to read this document\n\nThis document is the canonical architecture source of truth for IntegrateWise\nand Spine Workspace.\n\nOther repository documents may describe implementation, operational procedures,\nor scoped development rules, but must not redefine canonical architecture.\n\nIf something contradicts it, this wins — including `AGENTS.md`, `CLAUDE.md`,\nand any file in `docs/architecture/` not listed as _Retained_ in Appendix K.\n\nSeven parts, read in order or entered at any heading:\n\n| Part | Answers | Changes |\n| --------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------- |\n| **I — Foundations** | Why the system is shaped this way | Rarely. A change here is a major version. |\n| **II — The System** | What each part owns and where the boundaries are | Slowly. Implementations improve; responsibilities do not move. |\n| **III — Reality** | What is actually built, what has drifted, what is undecided | Continuously. Dated evidence, not aspiration. |\n| **IV — Consolidated Ref** | Earlier consolidation (superseded by V–VII) | Historical. Do not edit — see Part V, VI, VII instead. |\n| **V — Master Reference** | Product definition, vocabulary, Workbench doctrine, UI | Slowly. Design-level consolidation. |\n| **VI — Consolidated Canon** | Canonical hierarchy, runtime loop, final product model | Rarely. Architectural invariants. |\n| **VII — Book-of-Record** | Implementation baseline, service contracts, go-live gates | With each release phase. |\n| **Appendices** | Exact tables, routes, bindings, contracts | With the code. |\n\n**Recommended reading path:**\n\n1. **New to IntegrateWise?** Start with Part I (§1–§17) for design rationale,\n then Part VI (§44–§50) for the canonical architecture.\n2. **Implementing a feature?** Start with Part VII for implementation contracts,\n then Part II (§18–§22) for component specifications.\n3. **Understanding drift?** Check Part III for current reality vs. design.\n4. **Historical context?** Part IV preserves the earlier consolidation.\n\n**A note on what this document is for.** IntegrateWise accumulated 94 architecture\ndocuments totalling 265,000 words. Sixteen were declared canonical. Six had \"canonical\" in\nthe filename. That is not a documentation problem — it is an architectural risk, because a\nsystem whose architecture cannot be held in one head is a system whose invariants will be\nviolated by accident. The purpose of consolidating is to make the invariants _cheap to\nknow_.\n\n---\n\n# Part I — Foundations\n\n## 1. The problem this architecture solves\n\nOrganisations run on dozens of systems that each hold a fragment of the truth and none of\nthe whole. People become the integration layer: reconstructing context by hand, moving\nfacts between systems that disagree, and re-explaining everything to whatever AI they try.\n\nThe naïve responses both fail:\n\n- **Replace the systems.** Nobody will. The switching cost is the business.\n- **Bolt AI onto each system.** This produces one assistant per silo, each with the same\n partial view and none with authority. It multiplies the fragmentation it was meant to fix.\n\nThe architectural bet is a third path: **leave the systems where they are, and build the\ngoverned layer between them** — one that owns canonical operational truth, projects it to\nthe person doing the work, and lets AI act only through approvals that a human grants.\n\nFour failure modes name what goes wrong without it. Each is architectural, and each is\nanswered by a specific component:\n\n| Failure | Root cause | Answered by |\n| -------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------- |\n| **Amnesia** — the AI knows nothing today about yesterday | No canonical state to stand on; session memory that guesses | **Adaptive Spine** |\n| **Human API** — the person bridges the tools | No capability fabric; integration done by hand | **Capability Fabric + Workbench** |\n| **Hallucination** — confident, wrong | Reasoning without grounded operational truth | **Grounded context** |\n| **Babysitting** — starts a task, stops halfway | No governed execution path that carries an action to completion | **Governance + Hermes** |\n\n## 2. Five commitments, and what each costs\n\nEvery durable property of this system follows from five decisions. Each is a genuine\ntrade-off, taken deliberately.\n\n### 2.1 Truth lives outside the applications\n\nCanonical operational state is assembled from connected systems into a store the\norganisation owns, with provenance on every field.\n\n**Buys:** cross-system questions become answerable; AI reasoning has ground to stand on;\nthe switching cost is accumulated verified memory rather than data hostage-taking.\n**Costs:** an ingestion and reconciliation burden that never ends, and a permanent\nconsistency question — the Spine is _eventually_ consistent with source systems, never\ninstantaneously. Every projection therefore carries freshness state, and \"unknown\" is a\nlegitimate answer the system must be able to give.\n\n### 2.2 Governance is architecture, not policy\n\nProposal → approval → execution → audit is the physics of the system. No approval token,\nno external mutation. This is not a setting, a middleware, or a default that can be turned\noff; the execution path has no branch that skips it.\n\n**Buys:** AI can be pointed at consequential work, because it structurally cannot act\nalone. Regulation moves toward this posture, not away from it.\n**Costs:** latency and friction on every consequential action, and a permanent design\ntension with \"just automate it.\" The tension is the product. Where it becomes intolerable,\nthe answer is narrower pre-authorised capabilities with thresholds — never a bypass.\n\n### 2.3 Deterministic and adaptive systems are separated\n\nPipelines, synchronisation, normalisation and validation are deterministic. Reasoning,\nplanning, triage and learning are adaptive. They are different runtimes with different\nauthority, and the boundary between them is a hard one.\n\n**Buys:** the parts that must be reproducible are reproducible. An AI failure degrades\nsuggestion quality; it cannot corrupt truth.\n**Costs:** two systems where one might have seemed sufficient, and the discipline to keep\nresisting \"the model can just do the normalisation.\"\n\nThe corollary — **confidence never grants authority** — is the most frequently attacked\ninvariant in the system. A 0.99-confidence proposal and a 0.55-confidence proposal require\nthe identical approval to become real. Confidence describes evidence quality. It is an\ninput to human judgement, never a substitute for it.\n\n### 2.4 One surface, composed per role\n\nThere is one Workbench. Role, department and industry select what is _projected_ onto it;\nthey never create a separate product, a separate database, or a separate navigation model.\n\n**Buys:** cross-functional work stays possible — one account, one person, one decision,\nvisible from every relevant angle without copying truth. New roles are configuration.\n**Costs:** the projection layer carries real complexity, and there is constant pressure to\n\"just build a Sales app.\" Yielding once produces the fragmentation the product exists to\nremove.\n\n### 2.5 The Twin is a participant, not an authority\n\nThe Twin shares the user's surface and context, prepares work, and proposes with evidence.\nIt is silent by default and prefers silence to low-value commentary. It never owns truth\nand never executes.\n\n**Buys:** collaboration inside the work rather than chat beside it, and a trust model that\nsurvives the model being wrong.\n**Costs:** a less impressive demo than an autonomous agent, and a discipline that must be\nenforced server-side — because in a plugin host, the reasoning model is someone else's and\ncannot be trusted to respect a client-side gate.\n\n### 2.6 OneAuth → Total Continuity\n\n**One connection per host. Entire ecosystem discovers. No N×M re-connections.**\n\nToday, every host (ChatGPT, Claude, DIA, etc.) requires its own set of OAuth connections.\nIf ChatGPT is connected to 50 apps and Claude is connected to 50 apps, the user must\nauthenticate separately for each host × each app. This is N×M complexity.\n\nIntegrateWise solves this with OneAuth: a single identity entry point that hydrates the\nSpine, discovers all connected apps from the host, and projects them as connectors. The\nuser never re-authenticates. The host's existing OAuth grants are discovered, not duplicated.\n\n```text\nHost A (ChatGPT: 50 apps) → OneAuth → Spine → Discovery → 50 connectors projected\nHost B (Claude: 50 apps) → Same OneAuth → Same Spine → 50 more connectors projected\nHost C (DIA: 3 apps) → Same OneAuth → Same Spine → 3 more connectors projected\n\nTotal: 3 hosts, 103 apps, 3 connections (not 309)\n```\n\n**Buys:** the user connects once per host; the entire IntegrateWise ecosystem (Spine, Twin,\nagents, memory, workbench) immediately has access to all data from all connected apps.\nAgent-to-agent communication happens through the Spine — Claude's work is visible to\nChatGPT, and vice versa, without separate integrations.\n**Costs:** IntegrateWise must trust the host's identity and connection grants, which means\nthe security boundary is at the host level, not the individual connector level. A compromised\nhost grants access to all its connections.\n\n## 3. The kernel vocabulary\n\nTwelve terms. Every concept in the system reduces to one of them. This is not a glossary —\nit is a completeness claim: if a proposal cannot be expressed in these terms, it is either\nduplicating an existing primitive or it is a major version.\n\n| Term | Definition | Owner |\n| -------------- | -------------------------------------------------------------------------------------------------------------- | ------------ |\n| **WORK** | A human or machine is moving an objective through state | Spine |\n| **CONTEXT** | The minimum relevant connected state required to understand current work | Continuity |\n| **SPINE** | The canonical connected model of operational work state | Spine |\n| **CONTINUITY** | Preservation and bounded transfer of relevant context across time, systems, humans and agents | Bridge |\n| **WORKBENCH** | The role-specific projection of work and context presented to a human | Product |\n| **TWIN** | The non-authoritative cognitive participant that consumes grounded context | Intelligence |\n| **CAPABILITY** | A registered operation that may read, derive, or change work state | MCP Pool |\n| **GOVERNANCE** | The authority that determines whether a capability or proposed consequence is permitted | Governance |\n| **HERMES** | The execution coordinator for authorised capability invocations | Execution |\n| **SYNC** | The reconciliation of resulting state across connected systems | Sync |\n| **BRIDGE** | The governed exchange boundary through which an authorised consumer receives or contributes bounded continuity | Bridge |\n| **OUTCOME** | The observed result of work or execution that may become new canonical state | Spine |\n\n**Why these twelve and not fewer.** WORK and OUTCOME are the beginning and end of the loop.\nSPINE holds truth; CONTEXT and CONTINUITY carry the relevant slice of it across boundaries.\nWORKBENCH and TWIN are how a human and a machine meet the work. CAPABILITY, GOVERNANCE,\nHERMES and SYNC are the four stages an intention must pass through to become a real change\nin the world. BRIDGE is the only sanctioned way anything crosses out. Removing any one\nleaves a responsibility with no owner.\n\n**Why not more.** Each additional term is a new place for two people to mean different\nthings. The document set this replaces contains \"OS Shell,\" \"Views,\" \"Topic Boards,\" \"Atlas\nSpine,\" \"Cognitive OS,\" and sixteen named agent personas — all of which turned out to be\nexisting primitives wearing new names. See [Appendix J](#appendix-j--vocabulary-ledger).\n\n## 4. The eight laws\n\nEach settles a class of argument permanently. When a design debate recurs, find the law\nthat already answers it.\n\n| # | Law | Statement | What it prevents |\n| --- | ------------------------ | ------------------------------------------------------------- | ------------------------------------------------------------------------ |\n| 1 | **Twin Law** | Twin is a capability of the Workbench, not a panel | The Twin becoming a permanent sidebar destination, i.e. a second product |\n| 2 | **Context Law** | The human never explains already-known work context to AI | Re-briefing; the Human API failure returning through the front door |\n| 3 | **Memory Law** | Spine owns truth. Memory informs truth. Memory is not truth | AI-generated material silently becoming operational record |\n| 4 | **Authority Law** | Confidence increases trust. Confidence never grants authority | Threshold-based auto-approval |\n| 5 | **Silence Law** | Twin prefers silence over low-value commentary | Notification fatigue destroying the signal the Twin exists to carry |\n| 6 | **Capability Law** | Workbench projects tool capabilities, doesn't duplicate tools | Rebuilding Salesforce inside the Workbench |\n| 7 | **Bridge Law** | One platform. One boundary. Different projections | A second entry point with its own identity authority |\n| 8 | **Product–Platform Law** | Broad underneath. Narrow at the surface | Platform capability leaking into user-facing vocabulary |\n\nLaws 1, 5 and 8 are violated by well-intentioned product requests. Laws 3, 4 and 7 are\nviolated by well-intentioned engineering shortcuts. Both classes are currently present in\nthe codebase — see [§20](#20-drift-register).\n\n## 5. What is frozen, and what may change\n\n| Change | Version impact |\n| -------------------------- | -------------- |\n| New kernel concept | Major |\n| New runtime step | Major |\n| New doctrine or law | Minor |\n| New capability type | Minor |\n| Implementation improvement | Patch |\n| New projection | Patch |\n| New role composition | Patch |\n\nFrozen: the product doctrine, the twelve kernel terms, the runtime sequence, the Adaptive\nSpine entity contract, and the Capability Fabric model.\n\nNot frozen: every implementation detail beneath them. The runtime sequence is an ordering\nof responsibilities, not an instruction for how many services implement it. Merging or\nsplitting services is a patch as long as the ordering and the ownership hold.\n\n---\n\n# Part II — The System\n\n## 6. The four planes\n\nEvery service belongs to exactly one plane. A service that seems to belong to two has\nconflated responsibilities and should be split.\n\n```\n┌─────────────────────────────────────────────────────┐\n│ EXPERIENCE User Workbench · Twin · Admin │\n│ Knows only six nouns. │\n├─────────────────────────────────────────────────────┤\n│ INTELLIGENCE Hermes · Knowledge · Memory · │\n│ Signals — adaptive, no authority │\n├─────────────────────────────────────────────────────┤\n│ EXECUTION Gateway · MCP Pool · Provider / │\n│ Integration / Task MCP — governed │\n├─────────────────────────────────────────────────────┤\n│ FOUNDATION Adaptive Spine · Identity · │\n│ Security · Storage · Timeline · │\n│ Provenance — deterministic │\n└─────────────────────────────────────────────────────┘\n```\n\nThe Experience plane knows six nouns and nothing else: **Entity, Projection, Capability,\nSignal, Context, Twin**. It knows nothing of OAuth, MCP, Cloudflare, provider APIs,\nconnector SDKs, or databases. This is Law 8 made concrete, and it is the reason the frontend\ncan be rewritten without touching the platform.\n\nThe Intelligence plane is the only adaptive plane. It reasons, plans and learns. It holds\nno authority and writes no canonical truth. The Foundation plane is the only one that holds\ntruth. Execution is the only one that changes the outside world, and only through Governance.\n\n## 7. The runtime sequence\n\nThirteen steps, frozen in order. Nothing skips a step; nothing reorders.\n\n```\nConfiguration → Integration → Pipeline → Adaptive Spine → Workbench Composition\n→ Continuity Bridge → User Workbench → Twin → Capability → Governance\n→ Hermes → Sync → Promotion\n```\n\n| # | Step | Owns |\n| --- | --------------------- | ---------------------------------------------------------------------------------- |\n| 1 | Configuration | Tenant schema, depth matrix, policies, runtime bindings |\n| 2 | Integration | Connector installation, consent, credential references, provider bindings |\n| 3 | Pipeline | Deterministic normalisation, triage routing, promotion — the only canonical writer |\n| 4 | Adaptive Spine | Canonical entities, relationships, timeline, provenance, permissions |\n| 5 | Workbench Composition | Role- and permission-scoped projection assembly |\n| 6 | Continuity Bridge | Bounded, governed context exchange across time, systems, hosts |\n| 7 | User Workbench | The single human surface |\n| 8 | Twin | Grounded reasoning, drafts, proposals — never execution |\n| 9 | Capability | Resolution of an intent to a registered, versioned operation |\n| 10 | **Governance** | The hard gate. Policy evaluation, authority check, approval token |\n| 11 | Hermes | The only coordinator of approved external execution |\n| 12 | Sync | Reconciliation of the resulting state across connected systems |\n| 13 | Promotion | Re-ingested outcome becomes new canonical state |\n\nStep 10 is the one that gets routed around under delivery pressure. It is the product, not\nan obstacle to it.\n\n**The loop closes.** Step 13 feeds step 4. An approved action does not end at the provider —\nit returns through re-ingestion, verification and reconciliation, and only then becomes\ncanonical. This is why \"did it work?\" is answerable, and why an ambiguous provider response\nmust be _queried and reconciled_ rather than retried blindly.\n\n## 8. Truth\n\n### 8.1 Three stores, and only one of them is business truth\n\nThe word \"Spine\" covers two different things that are not tiers of each other, plus a cache\nthat is frequently mistaken for both.\n\n| | **Canonical Spine** | **Operational Spine** | **Edge cache** |\n| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |\n| Answers | _What is true about the business?_ | _What is wired, and is it working?_ | _What did we just compute?_ |\n| Technology | Neon Postgres | D1 | D1 + KV |\n| Holds | Governed entity state, typed relationships, version history, lifecycle events, evidence links, approvals, audit, promotion records, change outbox | Connections · connectors · sync jobs · webhooks · schemas · capabilities · timeline events | Projection snapshots, active context, idempotency, connector health |\n| Lifecycle | Append-only, versioned; durable fact | High-churn; reflects runtime state | Expiring |\n| Written by | **Pipeline promotion only** | The service that owns the runtime object | Pipeline and Projection Engine |\n| Read by | Workbench projections, Twin, capabilities | Activation Hub, Integration Manager, Observability | Everything, transparently |\n| Governance | **Hard gate** | None needed — it holds no business truth | None — it holds nothing |\n| If lost | **Unrecoverable** | Rewire and resync | Recompute |\n\n**Operational Spine is the state of the machine. Canonical Spine is the state of the\nbusiness.** That formulation resolves a conflation that has caused repeated confusion: the\nseven operational entity types are _first-class runtime objects_, not a cache of anything\ncanonical. A `SyncJob` has no counterpart in Neon it could be a projection of. It is simply\na different kind of fact, with a different lifecycle and no need of a governance gate.\n\nThe edge cache is the third thing, and it is the one that must never be mistaken for either.\n\nThe operational store is a cache and a staging boundary. **If an operational record matters\nafter its expiry, it must be promoted through the governed path.** It must not be retained\nmerely because it happens to exist in a cache — and expiry itself never confers truth.\n\n**Aging is not promotion.** This is worth stating separately because it has been proposed\nrepeatedly. D1/KV expiry removes or rebuilds bounded state. Canonical promotion is\nevidence-, schema-, provenance-, policy- and authority-driven. A record does not become true\nby surviving.\n\n### 8.2 Storage ownership\n\n| Store | Owns | Never |\n| --------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |\n| **Neon (Fortress)** | Canonical entities, relationships, lineage, connector metadata, schema mappings, work, governance, audit, promoted outcomes | — |\n| **R2** | Files, attachments, raw payloads, exports, immutable evidence bytes | Canonical structured truth |\n| **Vectorize / AI Search** | Derived embeddings and retrieval indexes | Truth |\n| **Spine Cache** | The read-optimised, policy-filtered, LLM-readable projection of Spine. **The default agent read surface** | Truth, and never a write target |\n| **D1** | Active context, idempotency, runtime indexes, projection snapshots | Independent record |\n| **KV** | Sessions, hot projections, connector state, invalidation | Truth |\n| **Credential wall (Nango)** | Tenant-owned OAuth/API credentials | — the Spine stores opaque references only |\n\n### 8.2a Fortress is never directly exposed\n\nHosts, MCP clients, Workbench frontends and LLM agents reach truth through governed APIs,\nMCP tools or **Spine Cache** projections. None of them queries Fortress storage.\n\nSpine Cache is not an optimisation — it is a trust boundary with a specific job: make\ncanonical state legible to a language model without handing a model raw rows. Its\nprojections remove provider noise, retain provenance and canonical IDs, expose compact\nsummaries, carry freshness, authority and confidence, include only policy-visible\nrelationships, support deterministic retrieval by entity and continuity thread, and —\ncritically — **distinguish fact from inference from proposal from memory.**\n\nThat last property is what stops a model treating its own prior output as ground truth. It\nis the Memory Law enforced at the read surface rather than trusted to the reasoning.\n\n### 8.2b The store assignment rule\n\nSix stores, one rule for choosing between them:\n\n> **Numbers you aggregate go to Postgres. Everything else goes to the store that matches its\n> shape — and none of those stores is truth.**\n\n| Data class | Store |\n| ----------------------------------------------------------------------------------------------------------- | ------------------------- |\n| Entity structured fields · KPI aggregations · counts · status · relationships · approval state · provenance | **Neon Postgres** |\n| Long-form text · semantic search · similar-entity matching · Twin context retrieval · duplicate detection | **Vectorize / AI Search** |\n| Attachments · invoice and contract PDFs · images and media · raw email bodies · exports | **R2** |\n| Bounded active context · idempotency · projection snapshots · runtime indexes | **D1** |\n| Session cache · hot projections · connector health · SLA and build flags · feature flags · invalidation | **KV** |\n| Twin conversation runtime · per-subject active context · agent working memory | **Durable Objects** |\n\n**Durable Objects are the sixth store and were previously unnamed.** They hold the live\nworking state of a reasoning session — the Twin's conversation, the active context for one\naccount, an agent's in-flight working memory. That state is real, it is scoped, and it is\n_not_ truth: it expires, and anything in it that should survive must be promoted through the\ngoverned path like anything else.\n\n**A caution on \"Postgres/D1.\"** Those two are not interchangeable and must never be written\nas one tier. Neon is canonical. D1 holds a _bounded, rebuildable projection_ of it. A KPI\nmay be **computed into** D1 as a cache; a KPI may not **live in** D1 as its record. The same\napplies to \"live entity state\" in KV — a cached current value is fine, an authoritative one\nis a violation of §8.1.\n\n### 8.2c Memory is interpreted truth, in four scopes\n\nMemory is neither canonical nor operational. It is **interpreted** — derived from canonical\nfacts and session evidence, carrying confidence and provenance. That is precisely why it\nneeds a governance gate that neither Spine requires: an entity is observed, but a memory is\n_concluded_.\n\n| Scope | Boundary | Governance | Store |\n| ------------------ | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ----------------------- |\n| **Personal** | One user. Hard boundary — no other principal reads it, including the org's own Twin acting for someone else | User owns it; no approval needed | `personal_memory` |\n| **Agent** | One agent or Twin instance within one tenant. Working state, learned routing, tool outcomes | Not directly promotable; must pass triage as evidence | `agent_memory` |\n| **Conversational** | One session or thread. Ephemeral working context | Decays; never promoted directly | `conversational_memory` |\n| **Organisational** | Tenant-wide interpreted truth | **Governed:** `staging` → approved → published | `org_memory` |\n\n**Scope only ever widens through promotion, and promotion is always governed.**\nConversational and Agent memory are _evidence_, not truth. Personal memory never widens at\nall — it can only be cited by the user who owns it.\n\nThat last rule is stronger than a privacy preference. If personal memory could be promoted,\nevery private note becomes a candidate for organisational truth, and the hard boundary that\nmakes the scope usable at all disappears.\n\n### 8.2c-i Triage classifies. The Promotion Gate governs.\n\n```\nEvidence Interpretation Truth\n──────── ────────────── ─────\nconversational_memory ┐\nagent_memory ├──► TRIAGE ──► candidate ──► PROMOTION GATE ──► org_memory\nsession events │ classify govern staging → approved\ncanonical entities ┘\n │\n personal_memory ──┘ never promoted;\n widened only by its owner\n```\n\nThese are two responsibilities and they must not merge. **A classifier that can also approve\nis not a gate.** Triage may receive, validate, classify, redact, deduplicate, link,\nquarantine and stage. It may not decide that unverified material has become organisational\ntruth; it decides only _where a candidate goes for review_.\n\n**Automation may reach `staging`. It may never reach `approved`.** This is the defensible\nmiddle between \"every extraction needs a human\" and \"high confidence auto-approves\": the\nsystem does the sorting, a human does the deciding, and material sitting in `staging` is\n**not available to Twin reasoning** until approved. Approval automation without approval\nbypass.\n\nThis is the Authority Law again — confidence never grants authority — expressed at the\nmemory layer. It deserves to be a test, not a comment: _no promotion path may write\n`governance_state = 'approved'` without an approver identity._\n\n### 8.2c-ii The same separation governs learned behaviour\n\nBehaviour learns through an evidence pipeline, never by direct mutation of an agent:\n\n```\nobservation → candidate → suggested → shadow → approval → active\n ↓\n remain · return to shadow · suspend · retire\n```\n\n**An agent may move a pattern to `candidate` or `suggested`. An agent may never promote a rule\nto `approved_autonomous`.** Autonomy is granted by policy, never inferred by the agent that\nwould exercise it — the Authority Law applied where it is most often violated.\n\nShadow rules evaluate against live opportunities and take no action. Proactive rules may\npropose but perform no external write. Autonomous rules execute only a fixed, approved rule\nversion inside a declared envelope — action types, entity types, rate ceiling, value at risk,\nfreshness requirement, approval expiry, emergency disable — and drift suspends them **without\na code deploy**.\n\n**Confidence is six things**, and one number must never represent all six: pattern confidence ·\nprediction confidence · input completeness · data freshness · historical precision · policy\neligibility. Small samples use a named conservative lower bound, not raw accuracy — 3/3 is not\nbetter evidence than 470/500.\n\nDetail: [Edge Conditions and Governed Learning\nSpec](../specifications/runtime/EDGE_CONDITIONS_AND_GOVERNED_LEARNING_SPEC.md) §9–§12.\n\n### 8.2d The enrichment pipeline\n\nNormalisation makes data canonical. **Enrichment makes it retrievable.** They are different\npasses with different failure modes, and conflating them is why \"the search is bad\" and \"the\ndata is wrong\" get diagnosed as one problem.\n\n```\nEntity created or updated in Neon\n ↓\nExtract text from structured fields + linked R2 content\n ↓\nChunk (512 tokens, 50 overlap)\n ↓\nEmbed into Vectorize\n ↓\nLink related entities into the relationship graph\n ↓\nExtract key concepts onto the entity\n ↓\nWrite the embedding reference back onto the entity in Neon\n```\n\nOne canonical write triggers the pass. The Twin then reads **Vectorize for context and Neon\nfor structured truth**, and the user never learns which store answered — which is the point,\nand also the reason the two must never disagree about what is authoritative.\n\n### 8.2e Cross-source canonical records\n\nSome canonical entities are assembled from several providers at once. An invoice is the\nclearest case: billing tool, payment gateway, subscription platform and usage platform each\nhold a fragment, and the canonical record carries references to all of them.\n\nThose links are established **by the pipeline, never by a user**. A human manually asserting\nthat two provider records are the same object is exactly the identity-resolution decision\nthat must be deterministic and provenance-bearing — and if it is ambiguous, it blocks rather\nthan guesses.\n\n### 8.3 Write authority\n\n```\nPipeline promotion through Governed Spine Writers\n= the sole canonical commit path\n```\n\nThe browser, the Twin, connectors, the public MCP, the Normalizer, Triage and the Projection\nEngine **never write Neon directly**. Not \"should not\" — the credential boundary is meant to\nmake it impossible. (Today it is not; see [§20 S8](#20-drift-register).)\n\n**No dual-write. Ever.** Nothing writes synchronously to both the Spine and a projection. The\ncanonical mutation, its field lineage and a **transactional outbox event** commit in one\ndatabase transaction; every projection is an asynchronous consumer of that event.\n\n```\n┌─ one Spine transaction ─────────────────┐\n│ canonical mutation │\n│ field lineage │\n│ outbox event │\n└──────────────┬──────────────────────────┘\n ↓ at-least-once, idempotent consumers\n Brain · search · vector · signals · Workbench · org-memory cache\n```\n\nDelivery is at-least-once with stable event ids, monotonic entity versions, backoff with\njitter, dead-letter queues and reconciliation. **The architecture does not claim cross-store\nexactly-once delivery** — any document that does is wrong.\n\nThis is the structural fix for the whole class of defect in §20: a projection that is written\ndirectly becomes a second writer, and a second writer becomes a second source of truth. It\ncloses **S0b** and **M1** — Neon `memory.org_memory` is the store, the D1 table is a\nprojection, and the promotion gate is its only writer.\n\nDetail: [Edge Conditions and Governed Learning\nSpec](../specifications/runtime/EDGE_CONDITIONS_AND_GOVERNED_LEARNING_SPEC.md) §2.\n\n### 8.3a Uncertainty is a value, not an absence\n\n`unknown` · `unresolved` · `insufficient_data` · `conflicted` · `stale` · `failed` are valid\npersisted states. **The platform never converts uncertainty into a guessed canonical value.**\n\nThis applies at three levels, and all three are required:\n\n| Level | Carries |\n| ------------ | --------------------------------------------------------------------------------------------------------------------------- |\n| **Field** | `normalizationStatus`: valid · coerced · invalid · missing · conflicted — with `rawValue` preserved whenever coercion fails |\n| **Identity** | `resolution_status` and `canonical_status`; an unresolved entity is `provisional` and **not eligible for automation** |\n| **Response** | `state` (§11.4) and `completeness` — orthogonal, both required |\n\nTwo rules that follow and are violated often:\n\n**An unknown enumerated value maps to `unknown`, never to the nearest known value.** Nearest-\nmatch is how a system quietly invents facts.\n\n**Null, blank and absent are three different things.** Collapsing them destroys the difference\nbetween _we know it is empty_ and _we never asked_.\n\n### 8.4 The entity contract\n\nEvery canonical entity owns seven properties. This is frozen:\n\n| Property | Meaning |\n| ----------------- | ------------------------------------------ |\n| **identity** | Canonical reference (id, provider, tenant) |\n| **fields** | Structured attributes |\n| **relationships** | Connected entities |\n| **timeline** | Temporal history |\n| **provenance** | Source and lineage |\n| **permissions** | Access governance |\n| **capabilities** | Available operations |\n\nProvenance is not metadata. It is the reason any number on a Workbench can be traced to the\nsystem and field it came from and the time it last changed — which is what makes grounded\nreasoning possible and hallucination structurally harder.\n\n### 8.5 Schemas are entity-based; experience is projection-based\n\nA persisted record represents a business or platform entity, relationship, event, evidence\nartifact, policy, capability, execution, versioned definition or runtime record. **A table is\nnever created because a sidebar label exists.** There is no canonical `home`, `inbox`,\n`finance-manager` or `view-n` table. Those are projections.\n\nRole, department and industry are **projection dimensions, not storage partitions**. This is\nthe single most load-bearing storage decision in the system: it is what preserves\ncross-functional work. One account, person, task, document, risk, decision or outcome is\nprojected into every relevant view without its truth being copied into a departmental\ndatabase.\n\nStorage rules:\n\n- One shared public schema; tenant-owned truth in tenant-scoped rows, not tenant-specific schemas\n- Each canonical entity type in its own table, with its own opaque primary key\n- `tenant_id` mandatory on every canonical row, relationship, event, cache entry and evidence link\n- Every entity carries a classification address: `app_category → business_domain → lifecycle_stage`\n\n### 8.6 The scope envelope\n\n| Concern | Field | Meaning |\n| ------------------------- | ------------------------------------------- | ------------------------------------------------------------------- |\n| Isolation boundary | `tenant_id` | The owning tenant. **Always required.** |\n| Tenant operating account | `tenant_account_id` | The tenant's root account identifier |\n| Tenant Spine Network | `spine_network_id` | Groups the entity graph, connector bindings, events and projections |\n| Workspace context | `workspace_id` | Optional active scope; never replaces `tenant_id` |\n| Entity identity | `_id`, `canonical_id` | Row identity and merge identity |\n| Connector install binding | `connector_binding_id` | The user/tenant/provider-workspace installation |\n| Connector connection | `spine_connection_id` | Lineage of one provider connection |\n| Traceability | `trace_id`, `correlation_id`, `source_flow` | The end-to-end route |\n\n`spine_network_id` and `spine_connection_id` are not interchangeable. The first is the\ntenant's network root, required for cross-connector grouping. The second is the lineage of\none connection inside it. A tenant network has many connections and also holds user-created,\nimported and governed entities that belong to no connection.\n\n`spine_users` are authenticated product users. A business person or contact is a _canonical\nentity_ with a person subtype. Conflating them is a recurring bug class.\n\n## 9. The four flows\n\nEverything entering the system is classified into one of four flows, and only two can create\ntruth.\n\n| Flow | Carries | Canonical boundary |\n| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |\n| **A — Structured operational data** | Entities, typed fields, relationships, metrics, events, status, ownership, lifecycle | Deterministic normalisation prepares candidates; governed writers commit |\n| **B — Documents and communications** | Threads, messages, meetings, calls, documents, attachments, transcripts, evidence | Raw artifacts preserved; extracted meaning retains lineage; promotion uses governed writers |\n| **C — AI and cognitive context** | Twin/external-AI sessions, model output, plans, proposals, tool calls, candidate memory | **Never directly mutates operational truth.** Triage proposes promotion |\n| **D — Platform binding and control** | Identity, tenant, workspace, role, department, permissions, configuration, connections, credential references, capabilities, policies, runtime bindings | Governed platform configuration writers only. Not a business-data partition |\n\n**Flow C is where every well-meaning shortcut wants to live.** \"Let the model write it,\nwe'll review later\" is precisely what this partition exists to prevent.\n\n**Flow D runs first.** It is not a peer of A, B and C — it is their precondition. Nothing can\nbe classified, scoped or written until identity, tenant, workspace, consent, connection binding\nand capability grants have resolved. An observation arriving before Flow D has no tenant, and a\nrecord without a tenant cannot be written; it fails closed.\n\n**Flow D is not the execution path.** An approved effect follows\n`Capability → Governance → Hermes → provider → outcome → re-ingestion → reconciliation →\npromotion`. Flow D supplies the authority and binding context that path runs under; it does\nnot turn external execution into platform-binding data. _(This is a recorded post-lock\ncorrection: Architecture Lock v1.0 described Flow D as approved external actions. v1.1\ncorrected it.)_\n\n### 9.0a Three things arrive from an AI, and they are not the same thing\n\nConflating them is the most consequential modelling error at the host boundary.\n\n| What the AI produced | It is | Destination |\n| --------------------------------------------------- | -------------- | --------------------------------------------------------------------------- |\n| **Tool result** — it invoked an app and got records | Evidence | **Flow A or B**, via Loader → Normalizer |\n| **Model output** — reasoning, summary, conclusion | Interpretation | **Flow C** — candidate only |\n| **Requested action** — \"send this\", \"update that\" | Intent | **Not a flow.** The governed execution path; its _outcome_ re-enters as A/B |\n\nThe sharpest case: **when a host's model reasons over IntegrateWise data and reaches a\nconclusion, that conclusion is Flow C.** It does not become organisational truth because a\ncapable model asserted it, and it does not become truth because its confidence was high. The\nreasoning is rented; the truth is owned; the gate between them is ours.\n\nDetailed channel mapping:\n[Marketplace Channels and Data Flow Spec](../specifications/surfaces/MARKETPLACE_CHANNELS_AND_DATA_FLOW_SPEC.md).\n\n### 9.1 Normalizer and Triage are separate runtimes\n\n| | **Normalizer** | **Triage** |\n| --------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Nature | Deterministic | Adaptive |\n| Does | Validate, parse, type, map, deduplicate, resolve identity and relationships, construct provenance, prepare a write candidate | Classify cognitive/unstructured material, bind evidence, estimate materiality and confidence, select a memory or knowledge scope, route for review |\n| Authority | None — prepares candidates | None — **cannot self-authorise or auto-promote** |\n\nNeither commits. **Loader Runtime** is the sole outer ingress controller; **Governed Spine\nWriters / Pipeline promotion** are the only modules that commit canonical truth.\n\n## 10. Capability, Governance, Hermes — the execution path\n\n### 10.0 Capability has three effect classes\n\nOne kernel term, three effect classes. Every registered capability declares which it is, and\nits governance requirement follows deterministically — it is not a judgement call at\ninvocation time.\n\n| Effect class | Does | External effect | Governance | Examples |\n| ------------ | -------------------------------------------- | --------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------- |\n| **read** | Retrieves state from a system of record | None | Policy scope only | Fetch an opportunity, list messages |\n| **derive** | Computes over truth, memory and evidence | None | Policy scope only; output is a candidate, never a fact | Memory view, AI search, context assembly, entity resolution, Twin reasoning |\n| **mutate** | Changes external or canonical business state | **Yes** | **Proposal → policy → approval token → receipt → reconciliation** | Send an email, update a CRM record, create an obligation |\n\nThis resolves a conflation that ran through the whole prior document set. The Capability\nLaw reads _\"Workbench projects **tool** capabilities\"_ — the word \"tool\" was already there,\nwhich means the doctrine only ever governed provider operations and left the cognitive half\nof the system unnamed. Fourteen of the nineteen public tools are `derive` or `read`:\n`get_context`, `get_related`, `get_permitted_memory`, `get_relevant_knowledge`, `ask_twin`.\nThose are the product. They now have a declared class, a governance rule, and a home.\n\nTwo consequences worth stating:\n\n**A `derive` capability produces candidates, never facts.** Its output enters Flow C. It\nreaches canonical truth only through Triage, a promotion record and the applicable approval.\nThis is the Memory Law expressed as a capability property rather than a convention.\n\n**Only `mutate` requires an approval token.** Reads and derivations are bounded by policy\nscope, not by approval. Requiring approval for a memory lookup would make the gate\nmeaningless through overuse.\n\n### 10.1 The path\n\n```\nTwin or user intent\n→ capability resolution (what operation is this, at what version)\n→ immutable execution plan (parameters fixed; nothing may change after this)\n→ Governance policy + evidence (is this permitted, by whom, with what evidence)\n→ explicit human approval (when required)\n→ approval token\n→ Hermes (the only coordinator of approved execution)\n→ provider connector / MCP capability\n→ source-system result\n→ Pipeline normalisation\n→ promoted outcome in Neon\n→ projection invalidation\n```\n\n**Governance route and execution route are separate decisions.** This is the correction\nthat makes multi-host deployment possible. _Whether_ an action is permitted, and _where_ it\nruns, are answered independently:\n\n- The **governance route** is invariant. Canonical entity resolution → policy evaluation →\n proposal → approval or confirmation → route resolution → execution → receipt capture →\n reconciliation into Spine. Every material write passes through all of it.\n- The **execution route** is resolved per operation. A write may execute through a\n host-native tool _or_ through the IntegrateWise Capability Fabric. Both produce the same\n canonical receipt structure and both reconcile into the same Spine.\n\nHermes **orchestrates** — it plans, sequences, tracks, retries and reconciles, and it\ncoordinates host-native handoffs as readily as IntegrateWise connectors. It is not the sole\nexecutor. What is invariant is the governance path and the receipt, not the transport.\n\nThree properties make this trustworthy rather than merely orderly:\n\n**The plan is immutable.** Once prepared, the parameters are fixed. What is approved is\nexactly what executes — there is no window between approval and execution in which the\naction can change.\n\n**A host confirmation is not an IntegrateWise approval.** If the host prompts the user and\nthe user accepts, policy evaluation has still not happened. Both may be required; neither\nsubstitutes for the other.\n\n**No material write executes without a receipt and a reconciliation.** An execution whose\noutcome is `unknown` enters reconciliation. It is never retried blindly and never assumed\nsuccessful.\n\n### 10.2 Capability Fabric\n\nCapabilities are registered, versioned, discoverable operations. The pattern is\n`Registry → Resolver → Health → Routing → Versioning`.\n\n```ts\npool.register(manifest, targetBinding);\npool.resolve({ capability, version });\npool.invoke({ capability, version, args, context });\npool.health();\npool.capabilities();\n```\n\nThe Workbench _projects_ capabilities; it does not implement them (Law 6). A capability\ncatalogue or executor built inside the Workbench is a Law 6 violation regardless of how\nconvenient it is.\n\n### 10.3 What \"hard gate\" means\n\n- No approval token → no external mutation. There is no branch that skips this.\n- Fail closed. A missing binding, an expired credential, an ambiguous scope: all fail closed.\n A governance gate that degrades to \"proceed\" is not a gate.\n- Enforcement is **server-side at the Gateway**. This matters most in a plugin host, where\n the reasoning model belongs to ChatGPT or Claude and cannot be trusted to respect a\n client-side gate. The plugin channel is the case that proves why the rule must hold\n everywhere.\n- \"Until successful\" is policy-bounded retry, never unbounded. Ambiguous remote outcomes are\n queried and reconciled before any mutation is repeated. Exhausted work goes to dead letter\n and governed reprocessing — never blind replay.\n\n### 10.4 The event envelope and reliability\n\nEvery ingress — webhook, polling, streaming, API, MCP, user or agent — normalises to one\ntenant-scoped event envelope carrying event type and version, trace, correlation, causation,\nidempotency key, subject, source and provenance.\n\n```\nValidate → archive raw evidence → publish immutable event\n→ queue / stream → process → resolve capability → govern → Hermes\n→ provider outcome → re-ingest → verify → reconcile\n→ Pipeline promotion → projection invalidation\n```\n\nThat one envelope is what makes the rest of the system uniform: a Slack webhook, a scheduled\nSalesforce sync and a Twin-proposed action all become the same shape before anything\ndownstream sees them. Six guarantees are mandatory rather than best-effort — event\nbus/queues, idempotency and deduplication, webhook and polling security, policy-bounded\nretry and replay, sync and reconciliation, and end-to-end traceability with structured\nlogging and SLOs.\n\nTwo rules deserve emphasis because they are where distributed systems usually fail quietly:\n\n**An ambiguous provider outcome is a question, not a retry.** If the system cannot determine\nwhether a mutation succeeded, it queries and reconciles before repeating. Retrying an\nambiguous write is how one approved action becomes three emails.\n\n**Exhausted work goes to dead letter and governed reprocessing.** Never blind replay. A\nreplayed action is a new action and re-enters the governance path.\n\n## 11. Projection and the Workbench\n\n### 11.1 The composition contract\n\n```\nVIEWER DIMENSIONS who is looking\n authenticated identity · tenant membership · role and permissions\n department · industry · policy and entitlement · preference\n\nSUBJECT DIMENSIONS what is being looked at, and what qualifies it\n the entity in focus · its business context · its lifecycle stage\n its relationships and evidence\n\nSYSTEM DIMENSIONS what is currently possible\n connector / schema / capability availability · freshness\n ↓\n Projection Engine\n ↓\n SharedWorkbench\n```\n\nPrior versions of this contract listed only viewer and system dimensions. That omission is\nthe subject of §11.1a.\n\nThe Projection Engine is the **sole composer** of `SharedWorkbench`. The Workbench never\nqueries provider-specific data models and never constructs its own KPI truth. Gateway\nderives authority from the identity provider; **browser-supplied tenant, user, role or\npermission values are non-authoritative** and are rejected.\n\n### 11.1a Context that qualifies is a dimension, not a destination\n\nA recurring modelling error, worth a test because it will happen again.\n\n**Business Context** is a canonical entity family — `business_model`, `market_position`,\n`operating_environment`, `key_business_challenges`, `strategic_priorities_current_year`,\n`digital_maturity`, `it_complexity_score`, `legacy_system_count`, `cloud_strategy`,\n`data_classification`. It is one row per account. It is a declared entity type in\n`packages/types`, it has migrations, and it has its own view file.\n\nAnd it appears in exactly one projected view — the quarterly business review, as \"Section 1.\"\nEvery operational surface where a decision actually gets made omits it.\n\nThat is backwards, and the cost is concrete. Consider an identical operational signal:\n_health 42, renewal in 18 days, two unresolved P1 tickets._\n\n| Business context | What the signal probably means | Right next action |\n| --------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------- |\n| `leader` · `cloud_native` · `optimizing` · `Cloud-first` | They have outgrown the current configuration or found a gap | Product and roadmap conversation, executive-to-executive |\n| `follower` · `on_premise` · `initial` · 40 legacy systems | They cannot absorb what they bought | Enablement and adoption plan, hands-on |\n\nSame numbers. Opposite actions. A Twin reasoning without business context will confidently\nrecommend the wrong one, and will do so with evidence — because the evidence is real; only\nthe interpretation is unqualified.\n\n**The test.** If an entity is one-to-one with its parent, is never usefully listed on its\nown, and changes how other entities should be _read_ — it is a **projection dimension**, not\na destination. Dimensions travel with the subject into every view. Destinations are places\nyou go.\n\nBusiness Context, lifecycle stage and industry classification are dimensions. Accounts,\ntasks, risks and engagements are destinations. Giving a dimension its own page and stopping\nthere is how the _why_ gets separated from the _what_ — and the whole product proposition is\nthat they arrive together.\n\n**Consequence for the projection contract:** the subject's qualifying context is composed\ninto every projection about that subject, at the depth the surface warrants — a one-line\nqualifier on a list row, a panel on an entity view, the full record on its own page. It is\nnot a page the user is expected to visit first and remember.\n\n### 11.2 One surface\n\nThere is one Workbench, one sidebar taxonomy, and one URL namespace. RBAC projection\ndetermines which items are present and whether the user may read, operate or administer\nthem.\n\nThe user-facing centre of gravity is **work**, not ontology. Users do not arrive to browse\n`teams`, `projects`, `assets` and `signals` as destinations. They arrive to answer:\n\n- What needs my attention?\n- What is blocked?\n- What is waiting for approval?\n- What changed?\n- What can my Twin help with next?\n- Which records, conversations, documents and entities explain that work?\n\nEntity families remain essential — as supporting truth behind the operational experience,\nnot as the primary product noun.\n\n```\nHome\nMy Work Inbox · Tasks · My Queue · Approvals · Notifications\n Recent Work · Favorites\nCommunications Activity Feed · Email · Calendar · Meetings · Chat\n Calls · Documents Shared\nPersonal Notes · Knowledge Base · Brainstorming Sessions · Activity\nWork ← computed: Role × Department × Industry\nPlatform ← computed: Profile (§15)\nAdministration Organizations · Users · Roles · Permissions · Audit · Billing\n```\n\nThree things are true of this structure and worth stating:\n\n**The Twin is absent, deliberately.** It is not a sidebar entry, because it is not a\ndestination (Law 1).\n\n**Only `Work` and `Platform` are computed.** Everything above them is a constant for every\nuser, role and profile — which is exactly what makes the structure durable.\n\n**`Platform` is one destination, not twenty-two.** It opens a settings-style module index\n_within_ the Workbench shell. Twenty-two top-level entries would make the Workbench a\nlauncher for twenty-two workspaces, contradicting \"one surface\" — and would be unrenderable\nin a constrained plugin surface, which forces the same conclusion independently.\n\n### 11.3 Canvases and organisational memory\n\nA canvas is a first-class projection surface, not decoration around a table browser. It may\ncompose document-like blocks, linked entity cards, embedded tables, decision logs,\ntimelines, policies, KPI strips and source references — all filtered by RBAC and the active\nprojection contract.\n\nOrganisational memory is a projection family, not a store. It behaves like the company\noperating handbook: the front door for promoted knowledge, decisions, rituals and canonical\nreferences. It is _backed by_ memory, knowledge, documents, events and approved outcomes;\nit **owns no separate truth store**.\n\n### 11.4 Required response shape\n\nEvery semantic response carries: contract version, request/trace identifier, tenant and\npermission scope, generation and freshness time, provenance, and exactly one state:\n\n`ready` · `partial` · `degraded` · `pending`\n\nIt separately carries a **completeness level** — `host-local`, `partial` or `canonical` —\nwith the list of missing systems. These are orthogonal: a response can be `ready` and only\n`host-local` complete. Any answer claiming cross-system completeness must report\n`canonical`, or disclose exactly what it could not see.\n\nThis is the honesty mechanism that makes a host deployment safe. \"Summarise my unread mail\"\nanswered from the host alone is a correct, useful, `host-local` answer. The failure mode is\nnot incompleteness — it is _undisclosed_ incompleteness.\n\n**A live failure never silently becomes seed or demo data.** A projection cache miss returns\nan explicit partial-evidence state. Mock and fixture data are Development-only. This is a\nstop-ship invariant, because a system that quietly shows fake numbers has broken the only\npromise that matters.\n\n### 11.5 Roles and the projection matrix\n\nTwelve roles × departmental modules is the composition space. A role is not a product — it\nis a selection over the same Spine, expressed as a `RoleConfig` with a projection binding.\n\nAdding a role is a **patch**: a new composition over existing entities and capabilities. If\nadding a role requires a new table, a new service or a new user-facing noun, the role is not\nthe problem — the model is, and the request should be refused until that is understood.\n\nThe `Work` group resolves through `Role × Department × Industry`. Twelve roles by roughly\ntwelve departments by N industries cannot be enumerated as static configuration; the industry\naxis must be **derived from the tenant's activated Spine schema**. See open decision\n[D3](#21-open-decisions).\n\n### 11.6 The auto-tuning boundary\n\nThe system may adapt to a user without asking. The boundary on that is precise, because\n\"the system learns\" is otherwise indistinguishable from \"the system changed something you\ndid not authorise.\"\n\nAuto-tuning is a bounded internal mechanism assembled from Configuration, Projection,\nGovernance, telemetry and runtime policy — not a new service. It may propose or **reversibly**\napply low-risk changes: personal view order, density, prefetch, cache, notification ranking,\ncapability placement.\n\nIt may never silently mutate the canonical schema or truth, change permissions, authority or\ngovernance thresholds, promote institutional memory, enable a provider or connector scope,\nmodify shared structures without the required approval, or remove the stable Workbench\ntaxonomy.\n\nThe dividing line: **personal and reversible may adapt; shared and consequential requires\napproval.**\n\n## 12. The Twin\n\n### 12.1 Two modes\n\n**Passive.** Continuously aware, never continuously reasoning. It observes pipeline events,\nSpine changes, the current surface and entity, user actions, OODA state, approvals and\noutcomes. Only a _material_ signal produces a small contextual surfacing: \"Renewal risk\ndetected.\" \"Connector sync failed; account data may be stale.\" Passive mode does not open a\npanel, generate long analysis, or compete with the user's work.\n\n**Active.** On explicit invocation — or a material signal that passes the Silence Law — the\nTwin escalates to grounded reasoning over the current surface, the current and related\nentities, **the subject's business context**, the Spine projection with timeline and\nprovenance, pipeline freshness, OODA state, evidence, connected-system context, and\norganisational memory. It produces an evidence-backed recommendation. It never decides.\n\nBusiness context is load-bearing in that list, not decorative. It is what separates _what\nhappened_ from _what it means here_ — see §11.1a. A recommendation grounded in operational\nfacts alone is defensible and frequently wrong.\n\n### 12.2 Active Context hydration is not Twin activation\n\nEvery material navigation refreshes the permitted context slice: selected entity and\nrelationships, visible fields, filters, linked records and documents, freshness and connector\navailability, allowed capabilities and governance posture.\n\n**This is hydration, not activation.** A click is context, not authority. A normal click does\nnot open a panel, run expensive reasoning, or convert navigation into an OODA Act. Visible\nTwin output occurs only when the user invokes a button, a material signal passes the Silence\nLaw, or an approved assignment requires monitoring.\n\n### 12.3 The four controls\n\nThe entire user-facing action grammar. Everything else is ordinary product interaction —\nnavigating, editing a record, logging activity.\n\n| OODA | Button | User intent | Platform behaviour |\n| ----------- | ------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |\n| **Observe** | **Store in Spine** | Capture a durable observation or decision | Workbench submits a governed write through Pipeline; Spine records entity, timeline, provenance, links. The Twin does not write |\n| **Orient** | **Ask your Twin** | Understand the current work | Twin reads the surface and bounded context, reasons over Spine, evidence, connected systems and memory |\n| **Decide** | **Assign your Twin** | Delegate a bounded task | Twin produces a draft, analysis or proposed action. **No external execution** |\n| **Act** | **Approve Twin's Action** | Authorise a proposal | Governance validates; the authorised capability is invoked through Hermes; the result reconciles back to Spine |\n\nThe Twin participates in the system loop only at THINK:\n\n```\nLOAD → NORMALIZE → STORE → THINK (Twin) → APPROVE → ACT → REPEAT\n ↑ ↑\n Store in Spine Approve Twin's Action\n Ask your Twin Assign your Twin\n```\n\n## 13. Continuity and the Bridge\n\nContinuity is the preservation and bounded transfer of relevant context across time,\nsystems, humans and agents. The Bridge is the only governed boundary through which it moves.\n\nThis is the answer to Amnesia, and it does more work than it first appears to. Three\ntransfers matter:\n\n**Across time.** Tomorrow's session starts from today's canonical state, not from zero.\n\n**Across people.** A handover transfers the context slice the recipient is permitted to\nreceive — not a document someone remembered to write.\n\n**Across hosts.** When an agent in one host needs a system that host cannot reach, the gap\nis filled by **Spine completion** — canonical context the Spine already holds, or an\nIntegrateWise-managed connector to that system. It is _not_ filled by brokering to another\nhost's connection.\n\nThis distinction matters and is easy to get wrong. IntegrateWise does not reach into\nChatGPT to borrow Claude's Salesforce token, and could not: connection tokens remain inside\ntheir owning trust boundary and no credential is copied between host and IntegrateWise\nmerely to unify routing. What actually happens is that IntegrateWise holds its own canonical\nSalesforce state and, where needed, its own governed connector — so the ChatGPT-side request\nis answered completely without Salesforce ever being connected to ChatGPT.\n\nThe architectural claim, stated precisely: **the Spine is the completion layer, and\ntherefore the interop substrate between hosts.** There is no agent-to-agent protocol between\nChatGPT and Claude, and there does not need to be. Each host talks to the Spine; the Spine\nsupplies what the host lacks. Adding a fourth host is an adapter and a catalogue entry — not\nan N×N integration, and not a credential-sharing arrangement.\n\n## 14. Identity, tenancy and isolation\n\n| Layer | Contract |\n| -------------------- | ----------------------------------------------------------------------------------------------------------- |\n| Browser identity | Descope is the identity authority |\n| Authority derivation | Gateway validates the session and resolves tenant membership; injects trusted identity headers downstream |\n| Browser claims | Non-authoritative. Tenant, user, role and permission values from the browser are rejected |\n| AI / MCP consumers | Public OAuth-protected MCP boundary |\n| Provider credentials | Tenant-owned, held in the credential wall. **Never** in a product repository, a projection, or an AI prompt |\n| Tenant scope | Mandatory on every canonical row, relationship, event, cache entry, evidence link and runtime operation |\n\nStale, ambiguous, revoked or expired bindings **fail closed** and are removed from sync,\nprojections, Twin context, capabilities and execution.\n\n## 15. Three axes: Profile × Entry Channel × Surface\n\nThree orthogonal things were previously collapsed into the word \"profile,\" producing a\n2×2 that could not represent development and could not represent tool-initiated onboarding.\nThe resolution is to **stop storing the product of the axes and store the axes**.\n\n### 15.1 Profile — which capabilities exist, and who may administer\n\n`development` · `customer_zero` · `external`\n\nThis is a property of the runtime a tenant is served by, not of the tenant.\n\nOnly five modules vary by profile:\n\n| Module | `development` | `customer_zero` | `external` |\n| ------------------- | ------------------ | ------------------- | ----------------------- |\n| MCP Pool (admin UI) | full | full | **not exposed** |\n| Capability Manager | all + experimental | all governed | tenant-permitted subset |\n| Administration | full | full | tenant-scoped |\n| Billing | bypassed | internal accounting | live metering |\n| Deployments | full | full | **not exposed** |\n\n**Everything else is identical across all three.** Identity, Integration Manager, Connector\nMarketplace, Activation Hub, AI Models, Knowledge, Memory & Continuity, Automation,\nPipelines, Governance, Observability, Organizations, Users, Roles, Permissions, Audit, API\nKeys and Security vary by _tenant scope_, which RBAC already handles. Adding profile\nbranches to them invents variance that does not exist and creates eighteen new drift sites.\n\nThis table is resolved **server-side at the Gateway** and returned in the capability\nmanifest. The frontend never computes it and never receives definitions for modules the\nprofile excludes.\n\n**On MCP versus MCP Pool.** They are two different jobs, not two sizes of one thing.\nVerified at HEAD: `services/mcp-pool/src` contains **zero** of the 19 semantic tools — it\nexposes five lifecycle verbs (`register`, `unregister`, `capabilities`, `health`, `invoke`)\nover nine platform-management namespaces. A profile running on Pool could not _use_\nIntegrateWise; it could only _administer_ it. The public MCP surface is therefore\n**byte-identical across all three profiles**. MCP Pool is an operator control plane — `register`, `unregister`, `capabilities`,\n`health`, `invoke` — whose _administration UI_ is exposed only in `development` and\n`customer_zero`. Pool is never a tool surface and never a per-profile alternative to MCP.\nIf Customer Zero ran on Pool while external ran on the public surface, Customer Zero would\nstop proving the external contract, which is its entire purpose.\n\n### 15.2 Entry channel — where identity comes from, and where UI renders\n\n| Channel | Identity source | UI surface | First connection |\n| ---------------- | -------------------------------------------- | -------------------------------- | ------------------------------------------------------- |\n| `connected_tool` | OAuth with a provider the user already holds | IntegrateWise browser Workbench | The authenticating provider |\n| `mcp_workbench` | IW OAuth via MCP registry | IntegrateWise browser Workbench | Chosen in the Workbench |\n| `plugin_host` | Host installation grant | Embedded surface inside the host | **Host-declared, runtime-confirmed capability context** |\n\n**On \"inherited.\"** Earlier wording described the plugin's first connection as _inherited\nfrom the host's connections_. That phrasing is retired: it reads as credential inheritance,\nwhich is precisely what §15.4 forbids. Credentials remain inside their owning trust boundary.\nWhere the host cannot supply a required capability, the user creates an explicit\nIntegrateWise connection. Nothing is inherited — capability is _declared and then confirmed_.\n\nOne onboarding state machine serves all three:\n\n```\ninitiated → identity_required → workspace_required → consent_required\n → binding → hydrating → active\n ↘ degraded | revoked | failed\n```\n\nOnly `identity_required` and `workspace_required` are channel-dependent. `consent_required`,\n`binding`, `hydrating` and `active` are **identical for every channel**. This is the\ninvariant that matters: the Spine write path, hydration, projection composition and\ngovernance do not fork per channel. Fork them and you get three onboarding funnels that\nhydrate differently.\n\nChannel and provider are orthogonal. `channel` is one of the three above; `provider` is\ncatalogue data. Adding a new host is a catalogue entry, not a type change.\n\n### 15.3 Surface — infrastructure isolation only\n\n`dev` · `test` · `prod`. No product semantics. The axes are independent: Customer Zero on\n`test` is a valid and useful combination.\n\n### 15.4 In a host deployment, the host supplies the agent\n\nIntegrateWise does not ship inference into a host. The host's model reasons. IntegrateWise\nsupplies the tool surface, the truth, the memory, the governance gate and the embedded UI.\n\n**Host capability is never assumed.** The IntegrateWise runtime may not enumerate every app\nconnected to a user's host account, may not access another app's OAuth token, may not invoke\nunrelated apps directly, and may not bypass the host's permission, confirmation or workspace\ncontrols. The host orchestrates its own apps.\n\nHost capabilities therefore enter through explicit mechanisms only:\n\n1. **Host-declared capability context** supplied at app invocation\n2. **Tool-result handoff** — the host invokes its own app and passes the resulting evidence\n to an IntegrateWise tool\n3. **Workflow orchestration** — the host selects both its apps and IntegrateWise tools\n4. **Explicit IntegrateWise connection** where the capability is not available through the host\n5. **Installation manifest or policy declaration** of expected capabilities\n\n**Declared is not available.** Every one of those must be validated at runtime; expected\navailability is never proof of actual runtime access. A capability's `availability` is\n`confirmed`, `declared` or `unknown`, and only `confirmed` may be routed to.\n\nTwo further rules hold:\n\n1. **Host-granted access is readable, not writable.** Any mutation is a capability execution\n and passes the governance path like any other, whatever route it executes on.\n2. **Host evidence is still Spine-mediated.** A host tool result enters as a\n `RawObservation` through Loader and the Normalizer Path. The Workbench does not treat a\n provider payload as truth because the host happened to hold a token.\n\n### 15.5 Create once, deploy anywhere\n\nThe governing principle of multi-host deployment:\n\n> **Host-first access. Spine-complete context. Policy-governed execution. Canonical\n> reconciliation.**\n\nOne canonical Workbench and continuity runtime is built once and deployed into many hosts —\na host being any runtime the product renders in: ChatGPT, the IntegrateWise web app, Slack,\nMicrosoft surfaces, embedded customer applications, desktop shells, customer-hosted\nenvironments, future agent marketplaces.\n\n**A host is an integration context, not a rendering container.** A deployment must account\nfor the host's authenticated user, workspace, enabled integrations, granted scopes,\nsupported operations, confirmation model, surface limitations and runtime availability.\nTreating a host as merely a place to draw pixels is the mistake that produces per-host forks.\n\nThis resolves what looked like a question about which surface is primary. Neither is.\n**Domain logic is primary; every host — including the browser — is an adapter.**\n\n| Layer | Owns | Never |\n| ------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |\n| **Domain packages** | Canonical types, application services, projections, governance rules, capability contracts, core UI | Host specifics |\n| **Adapters** | Host and infrastructure translation: identity validation, payload translation, schema enforcement, structured results | Domain policy, provider business rules, canonical schema |\n| **Apps** | Assembly of deployable surfaces | Behaviour not present in domain packages |\n| **Deploy** | Environment configuration | Anything that changes behaviour |\n\nNo adapter may redefine canonical entities, governance policy or projection semantics. The\ntest is falsifiable: the same domain and application-service packages serve the web and the\nhost deployments, and a deployment can move between infrastructure providers without domain\nlogic changing.\n\n**Repository topology follows from this.** The boundary between repositories is drawn by\n**write authority**, not by distribution channel — Platform owns canonical truth and\neverything permitted to write it; Product owns operational state, agent working memory and\nevery channel adapter. Putting two channels in two repositories would make them peers, and\npeers drift: the onboarding state machine must be byte-identical across channels, and a git\nboundary converts that from a compiler guarantee into a discipline. It would also make every\nfuture host a repository rather than a folder.\n[Repository Topology and Migration](../specifications/deployment/REPOSITORY_TOPOLOGY_AND_MIGRATION_SPEC.md).\n\n### 15.6 Host-first is a preference, not an entitlement\n\nA host-native route may be selected only when the capability is actually exposed to the\ncurrent session, the required scopes are present, policy allows it, the data authority and\nfreshness are sufficient, and the operation can produce evidence and a receipt where\nrequired. Otherwise the Spine completes the request.\n\nEvery request is classified before it is routed. The classification determines whether Spine\nenrichment is mandatory:\n\n| Scope | Spine enrichment |\n| ----------------------------------------------------------------- | -------------------------------------- |\n| `host-local` | Optional — lightweight provenance only |\n| `entity` · `continuity` · `cross-system` · `governance` · `write` | **Mandatory** |\n\nA strictly host-local read may stay local only when _all_ of the following hold: the user is\nasking only about the active host; no canonical entity or cross-system context is needed; no\nmaterial write is involved; policy permits it; provenance is retained; and **the result does\nnot claim to represent complete operational truth.**\n\nThat last clause is the whole safety property. \"Summarise my unread mail\" is a legitimate\nhost-local answer. \"What needs my attention?\" is not — it claims cross-system completeness\nand therefore requires canonical aggregation.\n\n**Read precedence:** confirmed host-native live capability → Spine canonical context →\nIntegrateWise-managed live connector → Spine Cache or historical data → request connection →\nunavailable.\n\nThis is not a sequential query plan. The resolver combines routes: mail may be host-native\nwhile CRM and chat arrive through the Spine, in one answer, with per-source provenance.\n\n**Write precedence:** resolve canonical target and policy → create proposal → determine\nallowed routes → prefer host-native when confirmed and approved → otherwise Capability\nFabric → capture receipt → normalise and reconcile → rehydrate.\n\n### 15.7 Connection binding — one route per operation\n\nThe same provider must not be called through both the host and IntegrateWise merely because\nboth are connected. One primary route is selected per operation; a secondary route may be\nused for fallback, verification or reconciliation when policy allows.\n\nPrincipal matching uses canonical identity, never display name. Connection tokens remain\ninside their owning trust boundary — no credential is copied between host and IntegrateWise\nto unify routing, and IntegrateWise stores no host credential unless the user separately\ncreates an IntegrateWise connection.\n\nA binding records the provider, the canonical principal, the optional host connection\nreference, the optional IntegrateWise integration, the routing preference\n(`host-first` · `integratewise-first` · `policy-decides`), whether duplicate calls are\npermitted, and the reconciliation mode.\n\n### 15.8 Agent contracts\n\nAgents are contracts, not transports. An agent definition never owns provider-specific\ntransport logic, and every agent invocation receives a **policy-filtered Active Context\nBundle** — never raw provider payloads, unless the task is explicitly ingestion or\nnormalisation.\n\n| Agent | Responsibility |\n| ------------------- | ----------------------------------------------------------------- |\n| **Twin** | Reasoning, synthesis, recommendations, proposal drafting |\n| **Triage** | Intent, urgency, ownership and attention classification |\n| **Governance** | Policy interpretation, approval requirements, risk classification |\n| **Entity Resolver** | Canonical entity and identity matching |\n| **Evidence** | Evidence selection, provenance checks, contradiction detection |\n\nThe Active Context Bundle is the single input contract: actor and permissions, host and\nsession, entities, relationships, continuity, commitments, signals, decisions, evidence,\navailable actions, effective policy, and the completeness level with missing systems named.\n\nEvidence carries `authority` (system-of-record · canonical · derived · user-supplied) and\n`freshness` (live · recent · stale · historical) separately, because they answer different\nquestions. Live host evidence is authoritative **only for the provider object it\nrepresents**; the Spine remains canonical for cross-system identity, relationships,\ncontinuity and reconciled state. Four timestamps are distinguished — `observedAt`,\n`receivedAt`, `normalizedAt`, `reconciledAt` — because collapsing them is how stale data\nstarts looking fresh.\n\nDerived conclusions are never stored as facts. Conflicting evidence is surfaced, not\nsilently resolved, and a normalisation conflict quarantines the update while preserving both\nrecords.\n\n## 16. The public boundary\n\n### 16.1 Nineteen tools, exactly\n\nThe public MCP surface exposes exactly nineteen semantic tools. Not eighteen, not twenty.\n\nContext and continuity: `get_my_continuity` · `get_active_context` · `get_my_focus` ·\n`get_context` · `get_changes` · `get_related` · `get_history` · `get_commitments` ·\n`get_decisions` · `get_permitted_memory` · `get_relevant_knowledge`\n\nTwin: `ask_twin` · `assign_twin` · `get_prepared_work`\n\nAction: `get_available_actions` · `prepare_action` · `get_action_plan` · `approve_action`\n\nCapture: `store_in_spine`\n\nThe internal MCP Pool, provider operations, raw table access, transport details, context\nrelay, agent handoff and connector implementation tools are **not public**. UI resources are\nadditive — a widget may communicate only through the host's declared bridge and cannot reach\nthe host DOM, cookies, credentials, Neon, provider credentials or the internal Pool.\n\nNotice the shape of that list: eleven read tools, three Twin tools, four action tools, one\nwrite tool. The single write tool is `store_in_spine` — a human observation. The four action\ntools cannot execute; `approve_action` requires an approval that a human granted. The public\nsurface is structurally incapable of autonomous mutation.\n\n### 16.2 Distribution names\n\n```\nIntegrateWise = company and product brand\nIntegrateWise Workbench = the user's single operational surface\nWorkspace = the tenant/user environment hosting a Workbench\nIW-Spine-Network = the public distribution identity\nIW-Spine-Network Plugin = plugin-directory package (MCP app UI + skills)\nIW-Spine-Network MCP = MCP-marketplace package and remote server\nIW Spine Tools = the public 19-tool MCP interface\nAdaptive Spine = the canonical operating model and truth substrate\n```\n\n> **IntegrateWise Workbench runs on IW-Spine-Network.**\n\nPublishing to a channel publishes a **channel-specific package bound to the same public\ncontract** — never a different backend. Installing does not clone Customer Zero: activation\nresolves an isolated customer tenant and applies the Customer Zero-proven reference\nconfiguration. Customer Zero data, credentials, memory, cache, queues and audit never cross\nthat boundary.\n\n### 16.3 Distribution — one product, three entry points\n\n| Distribution | Marketplace promise | Primary experience | Package |\n| --------------------------- | ----------------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------- |\n| **IW-Spine-Network MCP** | Bring continuity and governed action into your AI workspace | Tool-first, conversational invocation | Remote MCP server exposing the 19 semantic tools |\n| **IW-Spine-Network Plugin** | See and operate your connected workspace inside the AI host | Embedded Workbench, contextual Twin, approval UI | Host app with UI resources and skills, same MCP contract |\n| **IntegrateWise Workbench** | Operate the complete connected workspace directly | Full browser Workbench | Browser application on the same Gateway |\n\n```\nOne product: IntegrateWise Workbench on IW-Spine-Network\nDistributed via: MCP Marketplace · Plugin Marketplace · Direct activation\n```\n\nThese are **acquisition and interaction channels, not products**. Each binds to the same\ntenant and workspace, the same Adaptive Spine, the same Gateway, the same 19-tool semantic\ncontract, the same governance path and the same Workbench composition model. Marketing them\nas distinct products creates the competing-authority problem at the commercial layer that\nthis document exists to prevent at the architectural one.\n\nThe three marketplace surfaces have different commercial jobs:\n\n| Marketplace | GTM role | What it installs or activates | Where value appears |\n| ------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |\n| **Plugin Marketplace** | External acquisition and embedded activation | `IW-Spine-Network Plugin` | Focused UI, skills and approvals inside the AI host |\n| **MCP Marketplace** | External acquisition and tool-first activation | `IW-Spine-Network MCP` | Exact 19-tool interface, fallback results, optional widgets and browser Workbench launch |\n| **Connector Marketplace** | In-product capability activation and expansion | Tenant-scoped provider connection, connector binding, schema mapping and capability grant | Hydrated Spine context and governed provider capabilities inside IntegrateWise |\n\nPlugin and MCP marketplaces distribute IntegrateWise. Connector Marketplace does not\ninstall IntegrateWise; it expands what an activated workspace can observe and govern.\nDirect Workbench activation remains a non-marketplace entry path. Provider or developer\nmarketplaces may wrap the Plugin or MCP contract in channel-native installation, OAuth and\nwebhook semantics, but they do not create another product or authority.\n\nThe full GTM motion is:\n\n```text\nCategory and demand\n→ Plugin Marketplace, MCP Marketplace or direct Workbench activation\n→ identity, tenant, consent and workspace activation\n→ Connector Marketplace connection or eligible connection reuse\n→ Spine hydration and role projections\n→ first grounded value\n→ first approved governed outcome\n→ additional connectors, roles and recurring use\n```\n\nThe north-star metric is time to first approved governed outcome. Channel metrics support\nit: listing view → install → `active` for Plugin and MCP, and discover → consent → bind or\nreuse → healthy → hydrated for Connector Marketplace.\n\n### 16.4 Acquisition to value\n\n```\nDiscover → Install → Resolve identity → Resolve or create workspace\n→ Consent → Bind capabilities and connections → Hydrate Spine\n→ Compile projections → First value → Daily use\n→ Propose governed action → Execute and reconcile → Expand connected systems\n```\n\nActivation must create or resolve, at minimum: Actor · Tenant · TenantAccount · Workspace ·\nMembership · Role and permissions · SpineNetwork · MarketplaceInstallation · HostBinding ·\nConnectorBinding · SpineConnection · CredentialReference · CapabilityManifest · PolicySet ·\nRoutingPreference · SchemaBindingSet · HydrationJob · ProjectionManifest.\n\n**First use must be semantic, not administrative.** In the MCP channel the first interaction\nshould be _\"What needs my attention?\"_ — and if no workspace exists yet, the activation\ndetour must **preserve the original intent and return to it**. An onboarding flow that\ndiscards the question the user actually asked has failed at the Context Law.\n\n### 16.5 Flow classification at the channel boundary\n\nPayloads are classified **individually**. A single AI-host interaction spans all four flows,\nand labelling the whole exchange \"AI data\" is the error that lets model output become truth.\n\n| # | Event | Flow |\n| --- | -------------------------------------------------------------- | --------------------- |\n| 1 | Plugin installed; identity, tenant, consent, bindings resolved | **D** |\n| 2 | User asks \"What needs my attention?\" | **C** |\n| 3 | Host retrieves mail messages | **B** |\n| 4 | Host retrieves structured CRM objects | **A** |\n| 5 | IntegrateWise supplies canonical continuity | _Spine read_ |\n| 6 | Model produces analysis and recommendations | **C** |\n| 7 | Model proposes an escalation email | **C** — proposal |\n| 8 | User approves | _Governance_ |\n| 9 | Host or IW connector sends it | _Governed execution_ |\n| 10 | Sent-message artifact | **B** |\n| 11 | Delivery and status metadata | **A** |\n| 12 | Execution receipt | _Audit evidence_ |\n| 13 | Reconciliation updates the Spine | _Canonical promotion_ |\n\n**A tool call is three things, not one:**\n\n```\ntool request → Flow C (the model's intent)\nprovider result → Flow A or B (what came back)\nmodel interpretation → Flow C (what the model concluded)\n```\n\nThe transport does not determine the flow. **The payload's semantic responsibility does.** A\nSalesforce object that travelled through ChatGPT is Flow A; the sentence ChatGPT wrote about\nit is Flow C.\n\n### 16.6 GTM funnel mapped to runtime state\n\nThe commercial funnel and the activation state machine are the same events. Instrument once.\n\n| GTM stage | Runtime evidence |\n| ------------------- | ---------------------------------------------------------------- |\n| Impression | Listing viewed |\n| Install | MarketplaceInstallation created |\n| Activation started | `initiated` |\n| Identity completed | Canonical actor resolved |\n| Workspace activated | Tenant · workspace · SpineNetwork resolved |\n| First connection | Confirmed host or IntegrateWise binding |\n| Hydration started | Initial sync job created |\n| **First value** | First `canonical` — or explicitly disclosed `partial` — response |\n| Engaged | Repeated continuity and context use |\n| **Governed value** | First proposal approved |\n| **Closed loop** | First execution reconciled into the Spine |\n| Expanded | Additional provider connected |\n| Retained | Recurring cross-system use |\n\n**\"Installed\" is not an activation metric.** The first real milestone is _a grounded\ncontinuity answer produced from a resolved workspace, with provenance and disclosed\ncompleteness_. The milestone that predicts retention is _first governed action executed and\nreconciled_.\n\nDetail — activation envelope, per-channel journeys, read/write routing precedence, acceptance\ncriteria: [Marketplace Channels and Data Flow\nSpec](../specifications/surfaces/MARKETPLACE_CHANNELS_AND_DATA_FLOW_SPEC.md).\n\n### 16.7 Product and platform ownership\n\n| Product owns | Platform owns |\n| --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Workbench rendering, canvas composition, interaction state, contextual Twin UI, approval UI, onboarding and administration presentation | Identity resolution, tenant authority, connector catalog and credentials, canonical truth, projections, capability resolution, governance, execution, reconciliation, audit, semantic APIs |\n\n**No product deployment becomes a second Fortress, connector runtime, credential store,\ncanonical database, projection authority or provider-execution path.** Product frontends may\nrun anywhere; they are clients of the matching Gateway. The Platform authority stays\nCloudflare-hosted.\n\nThe browser calls one typed Gateway client using one variable, `NEXT_PUBLIC_IW_API_URL`. The\nfirst canonical read after sign-in or workspace switch is `GET /api/v1/workspace/discovery`,\nreturning a versioned tenant/RBAC-scoped manifest: identity and scope, projected navigation,\nprojection IDs and contract versions, connector and sync availability, capability and\napproval availability, activation blockers, freshness and remediation.\n\nNo browser call reaches Neon, D1, KV, R2, the credential wall, a provider, Hermes or the\ninternal MCP Pool.\n\n## 17. Environments and promotion\n\n| Environment | Purpose | Isolation |\n| ----------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |\n| **Development** | Product engineering, local/preview apps, CI, disposable tests | Synthetic data; development identity, Gateway, Neon, D1/KV/R2/queues and secrets only |\n| **Customer Zero** | IntegrateWise operating IntegrateWise as its first real customer | Production-grade but isolated tenant, credentials, MCP Pool, queues, evidence, audit and bindings. **Never a general test tenant** |\n| **Customer Production** | External customers | Tenant-scoped everything; no access to Development or Customer Zero |\n\nPromotion is one-way: `Development proof → Customer Zero validation → Customer Production\nrelease`. Production data, credentials and bindings never flow back.\n\nTest and prod must never share KV namespaces, Queues, D1 databases, R2 buckets, Vectorize\nindexes, Durable Objects, secret stores, or service-binding targets. Every feature completes\nin three directions: development readiness, platform release readiness, customer activation\nreadiness.\n\n### 17.1 Frozen go-live sequence\n\nGo-live promotes the same Product and Platform versions through isolated environments. It\ndoes not copy Customer Zero or create a separate external product.\n\n```text\nsource commit\n→ CI and contract tests\n→ Development artifacts\n→ Customer Zero private installation\n→ Customer Zero evidence\n→ version freeze\n→ external clean-tenant test\n→ Plugin and MCP submission-ready\n→ public publication\n```\n\nThe release completes five phases in order:\n\n1. **Shared contracts:** freeze the exact 19 public tools, resources, UI intents, discovery\n envelope, tenant binding contract and versioned activation profiles\n2. **Customer Zero Plugin:** prove the private embedded UI, identity, host composition,\n explicit delegation and the governed proposal-to-reconciliation loop\n3. **Customer Zero MCP and Workbench:** prove OAuth, exactly 19 tools, ordinary-client\n fallback, browser launch, discovery-first composition and role-based access control\n (RBAC) projections\n4. **Externalization:** install the same artifacts into a clean tenant and prove dynamic\n tenant resolution, customer-owned connections and complete Customer Zero isolation\n5. **Publication:** freeze compatible versions, publish the Plugin and MCP, verify a new\n tenant installation and operate governed monitoring, rollback, revocation and deprecation\n\nOnly code, manifests, definitions, schemas and versioned activation defaults cross the\npromotion boundary. Tenant data, credentials, bindings, queues, caches, evidence, audit\nrecords and runtime state never cross it.\n\n### 17.2 Mandatory release gates\n\nCustomer Production release requires all of the following evidence:\n\n- Customer Zero runs daily work through the Plugin and browser Workbench\n- the frozen versions install into an unrelated tenant without code changes\n- identity, tenant authority, RBAC and environment isolation pass negative tests\n- the public MCP returns exactly 19 tools and supports browser launch and ordinary-client\n fallback\n- one real connector passes consent, mapping, hydration, delta sync, health, revoke and\n reconciliation\n- every external action follows proposal → approval token → Hermes → provider outcome →\n Spine re-ingestion → projection refresh\n- observability, audit, rate limits, rollback, deletion, export, offboarding and revocation\n have live evidence\n- the release manifest records compatible Plugin, MCP, frontend, Gateway and Platform\n versions\n\nAny missing gate is a stop-ship condition. Appendix I remains the complete invariant-level\nstop-ship list.\n\nClaims about the system use one of three states, and **code presence is not live proof**:\n\n| State | Meaning |\n| ----------------- | ------------------------------------------------------------------- |\n| **Defined** | The contract is decided |\n| **Implemented** | Repository code or migration evidence exists |\n| **Live verified** | The environment has passed the required runtime and isolation tests |\n\n---\n\n# Part III — Reality\n\nParts I and II describe the architecture. This part describes the system as it exists on\n2026-07-31, at HEAD `d941a422`. Both are necessary; a document that only described the\nintent would be the fourteenth such document.\n\n## 18. What is load-bearing\n\nStripped of everything unreachable:\n\n```\nBrowser (apps/web — Next App Router)\n │\n └─► gateway ─────────── 51-entry ROUTES prefix table\n ├─ INTERNAL_* auth · projections · billing · tenants · admin · support\n ├─► pipeline normalise → canonical write (Spine writer #1)\n ├─► spine Neon canonical CRUD (Spine writer #2) ⚠\n ├─► connector router only ──► loader · store · mcp-connector\n ├─► mcp-connector MCP tools + OAuth authorisation server\n ├─► connector-sync scheduled provider sync\n ├─► knowledge chunk · embed · search · synthesis · promotion gate\n ├─► intelligence think · act · govern · agents\n ├─► workflow (BFF) views · analytics · stream · HITL Durable Object\n ├─► iw-agent-runtime TWIN_AGENT + TENANT_BRAIN DOs ⚠ not in CORE_SERVICES\n ├─► mcp-pool capability routing control plane ⚠ shared test/prod\n └─► hub-controller-api ⚠ AUTH BYPASSED\n continuity session log; reached via mcp-connector\n```\n\n**Nine Workers** are in the canonical publication path (`scripts/release/deploy-platform.sh`):\n`pipeline → connector → mcp-connector → connector-sync → knowledge → continuity →\nintelligence → workflow → gateway`, Gateway last.\n\nShared code that genuinely carries weight: `@integratewise/types` (99 consumers),\n`connector-contracts` (90), `lib` (23), `connectors` (18).\n\nEverything else — 11 unbound Workers, ~14 zero-consumer packages, 2 unreachable Capability\nFabric implementations, 2 orphaned application roots, a retired GCP product, 102\n`_deprecated` components, 5 abandoned service folders — is inert mass.\n\n## 19. Scale\n\n| Layer | Count |\n| -------------------------------------------------------------- | --------------------------------------------------------- |\n| Source files (`.ts/.tsx/.js/.jsx/.mjs`, build output excluded) | 2,082 |\n| `apps/` | 5 folders, 1,006 files |\n| `services/` | 39 folders (30 with Worker config, 5 empty, 4 non-Worker) |\n| `packages/` | 40 folders |\n| Markdown | 787 documents (94 in `docs/architecture/`) |\n| Migration SQL | 478 files across 17 independent roots |\n\nVerified against HEAD on 2026-07-31: nine `CORE_SERVICES` in the stated order, 51 Gateway\n`ROUTES` entries, 12 roles in `packages/workbench-config`, `/api/v1/workspace/discovery`\npresent at `services/gateway/src/index.ts:2313`, `spine` absent from `CORE_SERVICES`.\n\n## 20. Drift register\n\nEvery item is a violation of Part I or Part II, ordered by risk removed per unit of effort.\nSource: `CODEBASE_EXCAVATION.md`, 2026-07-30.\n\n### Tier 0 — Silent data loss\n\n**S0 · The Canonical Spine does not run. Cache writes are reported as canonical\npersistence.**\n\nVerified at HEAD, 2026-07-31. This is the most severe finding in the register and it is\nnot a design disagreement — it is a correctness defect that reports success.\n\nThe intended canonical writer, `services/pipeline/src/canonical/canonical-writer.ts`, is\ninvoked at `services/pipeline/src/index.ts:1922` and `services/pipeline/src/normalizer/index.ts:1097`:\n\n```ts\n// index.ts — canonical write path (Neon primary, D1 edge cache)\nif (env.DATABASE_URL) {\n const neonSql = (await import(\"@neondatabase/serverless\")).neon(env.DATABASE_URL);\n const result = await new CanonicalSpineWriter(neonSql, env.CANONICAL_SPINE_DB).write(rec as any, {\n correlation_id: body?.correlation_id,\n create_relationships: true,\n });\n if (!result.success) {\n throw new Error(`[Pipeline] Canonical spine write failed: ${result.error}`);\n }\n}\n```\n\n```ts\n// normalizer/index.ts — sectorize() canonical write path\nconst neonSql = env.DATABASE_URL\n ? (await import(\"@neondatabase/serverless\")).neon(env.DATABASE_URL)\n : undefined;\nconst canonicalWriter = new CanonicalSpineWriter(neonSql, env.CANONICAL_SPINE_DB);\n```\n\nThe `DATABASE_URL` secret is bound in `wrangler.toml` for all environments (dev/test/prod).\nNeon migration `044_canonical_spine_neon_port.sql` creates the canonical tables.\n\nThe D1 binding `CANONICAL_SPINE_DB` is provisioned (real UUID: `1dfe12bc-27be-4c5c-976e-8da691f5dde4`)\nand serves as the **edge cache** for fast reads. It is NOT the canonical store. The Neon\n`DATABASE_URL` is the canonical SSOT. The `CanonicalSpineWriter` constructor enforces this:\nNeon SQL is required (first arg), D1 is optional (second arg). If Neon is not provided,\nthe R8 boundary guard rejects the write.\n\nFour implementations claim Spine authority; the two that matter are not the two anyone\nexpected:\n\n| Implementation | LOC | Store | State |\n| -------------------------------------------- | ----- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `spine/src/entity-store.ts` + `index.ts` | 898 | D1 | **LIVE** — and correct. This is the Operational Spine: the seven runtime entity types |\n| `spine/src/neon-workbench.ts` | 558 | Neon | **LIVE** — tenant/actor-scoped Workbench projection |\n| `spine/src/canonical-store.ts` | 995 | D1 | **DEAD** — no importers. Declares the 16 root concepts and asserts itself the single source of truth. Its types were _copy-pasted_ into `pipeline/src/canonical/entity-type-map.ts:16` with the comment _\"Types duplicated from spine canonical-store to avoid cross-service dependency\"_ |\n| `pipeline/src/canonical/canonical-writer.ts` | 469 | Neon (primary) + D1 (edge cache) | **LIVE** — canonical SSOT writer. Neon is required (R8 boundary guard); D1 is optional edge cache for fast reads. Migration `044_canonical_spine_neon_port.sql` creates the Neon tables. |\n| `pipeline/src/spine/index.ts` | 2,773 | Supabase | **LEGACY** — self-labelled _\"the legacy writer\"_, still in the release path |\n\nThis inverts §S8. There are not two competing canonical writers to choose between. **There\nare zero working ones**, plus a retired Supabase writer that still runs.\n\n**Resolution — this closes D4.**\n\n> The Canonical Spine is Neon. The Operational Spine is D1. `services/spine` owns both\n> boundaries. The Pipeline is the only writer into canonical.\n\n**Steps 1–2 implemented 2026-08-20.** The `CanonicalSpineWriter` now takes Neon SQL as\nprimary (required) and D1 as optional edge cache. Constructor signature:\n`new CanonicalSpineWriter(neonSql, d1?)`. The `validateBoundaryGuard()` function enforces\nR8: Neon must be provided, or the write is rejected. `wrangler.toml` binds `DATABASE_URL`\nin all environments. Neon migration `044_canonical_spine_neon_port.sql` creates the\ncanonical tables (spine_entities, spine_relationships, spine_timeline, etc.).\n\nOrdered, because each step removes an ambiguity the next would otherwise encode:\n\n1. ✅ **DONE.** Canonical write failure is now hard-fail. The `CanonicalSpineWriter` returns\n `success: false` on Neon write failure; it no longer swallows errors with `console.warn`\n - `success: true`. Neon PostgreSQL is the canonical SSOT; D1 is the edge cache.\n2. ✅ **DONE.** Canonical writes route through `DATABASE_URL` (Neon SQL via\n `@neondatabase/serverless`) instead of the `SPINE` binding. `CANONICAL_SPINE_DB` is\n retained as the D1 edge cache for fast reads, not as the canonical store. The\n `wrangler.toml` now binds `DATABASE_URL` as a secret in all environments.\n3. **Move the 16-concept ontology into `packages/spine-entities`** (already consumed by\n `services/spine`) and delete the copy-paste in `entity-type-map.ts`. One definition.\n4. Retire `services/pipeline/src/spine/` once 1–3 land.\n5. Stop using the word \"Spine\" unqualified in new code. It is _Canonical_ or _Operational_.\n\nSteps 1–3 also unblock the repo split (§15.5): a boundary cannot be drawn while the\ncanonical store on one side of it is a placeholder.\n\n**S0b · `org_memory` is a documented cache with six writers.**\n`d1_knowledge.sql:12` describes it as _\"Mirror of memory.org_memory for edge-fast reads.\"_\nSix services `INSERT`/`UPDATE` it directly — `pipeline/src/index.ts`,\n`pipeline/src/memory-promoter.ts`, `intelligence/src/memory/evolutionary-memory.ts`,\n`intelligence/src/handoff/outcome.ts`, `intelligence/src/workflows/triage-workflow.ts`,\n`mcp-connector/src/handlers/tools.ts` — and 23 files reference it. There is no defined\nreconciliation against the Postgres table it claims to mirror. This is S0 repeating one\nlayer up. It must become either the store or a cache, with one writer. (**M1**)\n\n**S0c · `agent_memory` exists only inside retired infrastructure.** Its sole definition is\n`services/pipeline/src/spine/index.ts:1360` — inside the Supabase legacy writer scheduled\nfor deletion. It needs a D1 table alongside `personal_memory` **before** step 4 above, or\nthe capability is lost with the file.\n\n### Tier 0b — Publication blockers\n\nVerified 2026-07-31. Each blocks marketplace submission; all but the last are configuration\nor copy. Detail: [MCP and Plugin Publishing\nSpec](../specifications/surfaces/MCP_AND_PLUGIN_PUBLISHING_SPEC.md).\n\n| # | Finding | Evidence |\n| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |\n| **F1** | **Two Workers claim `mcp.integratewise.ai`** — the top-level Worker and `env.prod` both bind the public custom domain. Last deploy wins; a routine default-env deploy silently repoints the public MCP endpoint. `validate-platform-deployment.sh` checks _existence_ of `mcp-connector-test`/`-prod`, not route uniqueness, so it passes | `services/mcp-connector/wrangler.toml:6, 226` |\n| **F2** | **The published manifest advertises 23 tools.** The `tools` array holds 19; the description says 23 — the connector count (20 operational + 3 cognitive) written as a tool count. Violates stop-ship invariant #2 | `marketplace/apps/iw-spine-network.json` |\n| **F3** | **The public manifest names `mcp-pool` as its routing target.** Either the public path runs through the internal control plane, or the manifest is wrong and leaks internal topology. Both block | `marketplace/apps/iw-spine-network.json` → `ownership.routing` |\n| **F4** | **MCP Pool has no `env.test`, and `env.dev` binds `integratewise-integration-management-mcp-prod`.** The development control plane talks to production, on the component with the most privilege | `services/mcp-pool/wrangler.toml` |\n| **F5** | `iw-continuity-bridge.json` — a retired public name (**D9**) — sits in the publishable directory | `marketplace/apps/` |\n| **F6** | Five release flavours against a two-package doctrine, with no stated mapping | `releases/` |\n\n### Tier 1 — Correctness and security\n\n**S1 · A second, unauthenticated entry point sharing one database across surfaces.**\n`packages/api` (`hub-controller-api`) is bound by the Gateway in dev, test **and** prod — all\nthree to the same unsuffixed Worker with one D1 database. The Gateway explicitly skips its\nown authentication for every `/api/*` path that is not `/api/v1/*`. It carries `billing.ts`,\n`auth.ts` and `capability-routes.ts` — money, identity and capability execution. No deploy\nscript references it, so its deployed code is unversioned relative to the release ledger.\n_Violates Law 7 (one boundary), §14 (Gateway derives authority), §17 (test/prod isolation)._\n\n**S2 · Fifteen dangling service bindings.** The core nine were renamed from\n`integratewise-*` to bare names; consumers were never updated. These resolve to nothing at\nruntime.\n\n**S3 · Five test/prod binding leaks in the Gateway.** `HUB_CONTROLLER` and `MCP_POOL` point\nat identical targets in both environments. `validate-platform-deployment.sh` asserts only\n`mcp-connector` isolation, so none of this is caught by `release:check`.\n\n### Tier 2 — Restore a single truth\n\n**S8 · Three deployed Workers assert three different single sources of truth.**\n`services/pipeline` claims to be the only holder of Spine write credentials;\n`services/spine` claims to be the platform's single source of truth and holds `DATABASE_URL`\nplus a 995-line canonical store; `services/billing` asserts Supabase. Additionally\n`services/pipeline/src/spine/` is a second, self-labelled-legacy Spine implementation\n(2,773 LOC, Supabase-backed) that is live in the release path. _Violates §8.3 directly._\n`services/spine` is Gateway-bound and named canonical, yet is **not in `CORE_SERVICES`** — so\n`release:deploy --service core` never publishes it.\n\n**S4 · Four environment vocabularies.** Eight services still use retired\n`staging`/`production`; `signals` and `telemetry` have no test surface at all. Both root\n`wrangler.toml` and `wrangler.jsonc` are invalid and unused. `ci-cd.yml` is named DISABLED\nbut still contains seven direct `wrangler deploy` invocations — a second publication path.\n\n**S9 · Seventeen migration roots, 476 files, duplicate sequence numbers.** Ordering is\nambiguous in both `/migrations` (three collisions) and `/sql-migrations` (nine).\n\n### Tier 3 — Inert mass\n\n**S5 · Three Capability Fabric implementations, none of them the live one.**\n`packages/core` and `packages/lib/capability-fabric` are near-exact mirrors, ~35 files,\nmutually redundant and unreachable. The live path is\n`services/gateway/src/workbench-capabilities.ts` + `internal/capability-execution.ts` +\n`services/mcp-pool`.\n\n**S10 · A complete second, orphaned application root inside `apps/web`** (Vite entry, config\nand router, all committed and unreachable), plus 102 tracked `_deprecated` components.\n\n**S11 · Retired GCP/Firebase infrastructure still committed**, including\n`services/mcp-connector/src/lib/firestore.ts` inside a core release-path Worker.\n\n**S12 · Sixteen packages omit `private`,** which npm treats as publishable — including\n`packages/connectors` (~90 provider integrations) and `packages/core` (governance engine).\n\n### Tier 3b — Contradictory governance, and doctrine enforced by nothing\n\n**S5b · Two opposite promotion rules in one service.**\n`knowledge/src/triage-bot.ts:13` — _\"The Triage Bot **NEVER auto-approves.** Every\nextraction requires customer review.\"_\n`knowledge/src/synthesis/promotion-gate.ts:8` — _\"**AUTO-APPROVE:** High confidence + no\ngovernance flags + trusted domain\"_, with `decision: \"auto_approved\"` at lines 124 and 144.\n\nBoth are in `services/knowledge`. The never-auto-approve position is correct per §8.2c-i and\nthe Authority Law. `pipeline/src/memory-promoter.ts` (415 LOC, live, queue-driven) already\nimplements the right shape. `synthesis/promotion-gate.ts` is orphaned and should be deleted.\n\n**S5c · The synthesis pipeline targets a store that no longer exists.**\n`knowledge/src/synthesis/` — `triage-bot`, `promotion-gate`, `continuity-object-factory`,\n`lineage-tracker`, `knowledge-model` — is a complete, unreferenced pipeline built on\n**CouchDB**, superseded by the D1 memory tables. CouchDB survives in 11 files: three in\n`synthesis/`, three in `packages/coda-pack`, and **five in `packages/hermes-spine-memory`** —\nan entire package on retired infrastructure.\n\nSalvage before deleting: `lineage-tracker.ts` and its `UnderstandingObject` provenance model\nhave **no equivalent in the live path**. `memory-promoter.ts` writes an audit row but does\nnot track lineage across promotions. That is a real capability gap, not dead weight.\n\n**S5d · The canonical Authority Doctrine is in a package with zero consumers.**\n`packages/contracts/src/authority.ts` (228 LOC) declares itself _\"supersedes all other\narchitectural rules\"_ and states the Triage Boundary that settles S5b exactly. Verified:\n`@integratewise/contracts` has **0 importers**. The doctrine is exported as a template\nliteral — human-readable, machine-inert. Its neighbours share the fate, including\n`surfaces/chat.ts` (_\"The Chat surface IS the Triage Hub\"_) and `marketplace/installation.ts`\n(which `services/marketplace-installation` ignores in favour of its own types).\n\nA rule enforced by nothing is not a rule. Move `authority.ts` into `packages/types` (99\nconsumers) and convert the Triage Boundary into a test.\n\n### Tier 4 — Vocabulary and surface discipline\n\n**S6 · Retired L-layer vocabulary is the frontend's primary organising principle, and it\nleaks to users.** `components/l1/` is 240 files — the largest component tree in the repo —\nplus `l2/`, `l4/`, `l7/`, `layers/`. A product surface renders the literal string\n_\"12 L1 domain views + 14 L2 cognitive overlay components\"_. The Gateway exposes 19\n`/api/v1/cognitive/*` routes; \"cognitive\" is not a kernel term. Most seriously,\n`intelligence/src/agents/specialized/twin-orchestrator.ts` embeds _\"CODA L4 & MCP TOOLS…\nCoda documents are connected L4 projection surfaces\"_ **inside a live LLM system prompt** —\nso retired vocabulary is shaping the Twin's reasoning, not merely sitting in comments.\n_Violates Law 8 and §6._\n\n**S7 · The Workbench is not one surface.** Four parallel entry namespaces resolve to\nWorkbench content: `/workbench/[department]/work/[module]`,\n`/workspace/[department]/work/[module]`, `/domains/[domain]/[view]`, `/app/[...segments]`.\nThe first two page files are byte-identical except for one route string. Separately,\n`components/capability-shell/`, `inline-executor/` and `proactive-capabilities/` place a\ncapability catalogue and executor inside the Workbench. _Violates §11.2 and Law 6._\n\n**S13 · Naming collisions.** `packages/adapters` (infrastructure) vs\n`packages/connectors/src/adapters` (providers); two \"accelerator\" concepts; two Twin\norchestrators (a 3,470-LOC Worker with zero inbound bindings, and a 268-LOC agent); two\ncontract homes; two marketing implementations, of which the `legacy-pages` set is the live\none.\n\n**S15 · Canonical documentation is itself a sprawl surface.** 94 documents in\n`docs/architecture/`, 16 declared canonical, six with \"canonical\" in the filename. _This\ndocument is the remediation._\n\n### Schema gaps against the store model\n\nVerified at HEAD on 2026-07-31 against the six-store assignment in §8.2b:\n\n| Column | Purpose | State |\n| ------------------------- | ------------------------------------------------------------- | ----------------------- |\n| `embedding_id` | Vectorize reference on the entity | Present (7 files) |\n| `r2_key` | R2 reference on attachments | Present, thin (2 files) |\n| `memory_scope` | user · work · org (§8.2c) | Present, thin (2 files) |\n| `conversational_store_id` | Raw conversational memory reference on inbox items | **Missing** |\n| `source_records` | Cross-source provider fragments on assembled entities (§8.2e) | **Missing** |\n\nChunking is confirmed at 512 tokens (`services/knowledge/src/embeddings.ts:122`). Durable\nObjects are declared across six services — `intelligence`, `iw-agent-runtime`, `hermes`,\n`connector-sync`, `folder-watcher`, `workflow`.\n\n### Tier 5 — Orphans requiring a verdict\n\nEleven Workers have zero inbound bindings: `agent-registry`, `hermes`,\n`integration-management-mcp`, `marketplace-installation`, `provider-management-mcp`,\n`schema-ai`, `signals`, `telemetry`, `twin-orchestrator`, `vercel-mcp`.\n\n**`hermes` is stage 11 of the frozen runtime sequence and is unreachable.** It still points\nat `integratewise-bff`, a Worker that has never existed. This is the single most significant\ngap between Part II and reality: the architecture names Hermes as the only coordinator of\napproved external execution, and it is not wired.\n\n## 21. Open decisions\n\nGenuine forks, not deferred work. Each blocks something.\n\n| # | Decision | Blocks | Note |\n| ------- | -------------------------------------------------------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **D1** | Is `plugin_host` a peer surface or a reduced companion to the browser Workbench? | Plugin channel implementation | Changes what \"one Workbench\" means. A constrained host panel cannot render six groups and forty items |\n| **D2** | Does `Platform` become one gated destination or twenty-two sidebar entries? | Navigation consolidation | §11.2 records the recommendation (one destination); `packages/workbench-config` currently asserts the opposite |\n| **D3** | How is the Industry axis derived — tenant Spine schema, or explicit config? | `workbench-config` shape | 12 roles × ~12 departments × N industries cannot be enumerated statically |\n| ~~D4~~ | ~~Which Spine writer survives?~~ | — | **RESOLVED 2026-07-31.** Neither was writing. Canonical = Neon via the `SPINE` binding; Operational = D1 in `services/spine`; Pipeline is the sole canonical writer. See **S0** |\n| **D5** | Does `development` get its own tenant, or is it `customer_zero` on `test`? | Profile resolution | §15.3 permits either |\n| **D10** | Are the Customer Zero Supabase migrations part of the Spine? | Store model, S8 | A 2026-07-22 store mapping describes 34 Supabase migrations as _\"the Postgres partition of the Spine.\"_ `SOURCE_PACK_RECONCILIATION` (07-28) states Supabase **is not in the frozen product path**, and S8 flags two live Supabase-backed writers. Later date wins; the mapping's storage framing is superseded even where its data-class assignment is sound |\n| ~~D7~~ | ~~Is Co-worker a distinct agent or Twin behaviour?~~ | — | **RESOLVED — it was already decided twice.** `docs/wiki/21-adrs…md:66` records _\"'Co-worker' as a second runtime → Twin is the contextual AI Co-worker behavior\"_ as a superseded concept, and `packages/contracts/src/authority.ts` states the boundary: Twin understands context · Co-worker performs bounded prepared work · Human owns authority. **Co-worker is a behavioural mode of the Twin** — never a type, table, service or route. Good positioning language in user-facing copy; not a second runtime. The Host-Aware Spec §11 listing should be amended |\n| **D11** | Clerk or Descope as the browser identity authority? | §14, every onboarding path | **Live conflict.** §14 declares Clerk canonical, following `IMPLEMENTATION_CONTRACT_v1.1` §3, which also states _\"Descope browser-session paths are legacy compatibility only.\"_ A more recent Customer Zero decision selects **Descope** for Magic Link and OTP. Both cannot be authoritative. Resolve before any marketplace listing — identity is the first state in the onboarding machine, and a fork here forks both channels |\n| ~~M1~~ | ~~`org_memory`: store or cache?~~ | — | **RESOLVED.** Neon `memory.org_memory` is the store; the D1 table is a projection fed by the transactional outbox; the promotion gate is the only writer. The other five services become read-only consumers |\n| **M2** | Does a `team` memory scope exist? | `gateway/src/memory-governance.ts` | Currently a type with no backing table anywhere. If wanted, it is a new scope decision — not an orphaned type file |\n| ~~M3~~ | ~~May agent memory be cited before triage?~~ | — | **RESOLVED.** The Twin may cite agent memory **within its own scope**. It may not let agent memory inform an organisational-level claim until that material has passed triage and promotion |\n| **M4** | Does Personal Memory ever widen to Org, and by what act? | §8.2c | The hard boundary is currently absolute, and that is defensible |\n| **M5** | Canonical Spine on Neon only, or Neon plus a D1 read projection? | S0 step 2 | |\n| **M6** | Is the Chat surface the Triage Hub, per `contracts/src/surfaces/chat.ts`? | Sidebar structure, §11.2 | Better than a separate Triage nav entry; connects `Personal → Brainstorming Sessions` to the pipeline |\n| ~~D8~~ | ~~Repository structure~~ | — | **RESOLVED 2026-08-02.** Consolidated into **single monorepo** (`integratewise-live`). Platform kernel lives in `packages/` (contracts, connectors, spine-schema, adk, kernel). Product surfaces live in `apps/` (web, platform, one-access). Three invokable microfrontends: `@integratewise/auth-connectors-mfe`, `@integratewise/auth-onboarding-mfe`, `@integratewise/platform-mfe`. See [MICROFRONTENDS.md](MICROFRONTENDS.md) |\n| **D9** | Is `IW-Continuity-Bridge` a live product name? | Naming | The spec's header carries it; `CONSOLIDATED v1.2 §2` retires it as _\"historical/superseded wording only.\"_ Pick one |\n| ~~D6~~ | ~~MCP Pool: one control plane or three per-profile pools?~~ | — | **RESOLVED 2026-07-31.** One control plane. The public MCP surface is byte-identical across all three profiles; Pool is an operator control plane whose _administration UI_ is exposed only in `development` and `customer_zero`. Pool is never a tool surface, never a public route, and never named in a published artifact. `MCP_POOL_MULTI_ENVIRONMENT_STRATEGY.md` is superseded. See [MCP and Plugin Publishing Spec](../specifications/surfaces/MCP_AND_PLUGIN_PUBLISHING_SPEC.md) |\n\n## 22. Change discipline\n\n**Before adding a concept.** Name the responsibility it owns using only the twelve kernel\nterms. If you cannot, it is either duplication of an existing primitive or a genuine major\nversion — and a major version is a founder decision, not a pull request.\n\n**Before renaming.** Record which of five things is happening: _fundamental · evolved ·\nrenamed · superseded · experimental_. Mixing these is how documents start conflicting. Every\nrename goes in [Appendix J](#appendix-j--vocabulary-ledger).\n\n**Before shipping.** Does the surface stay narrow? New platform capability should rarely\nproduce a new user-facing noun. Broad underneath, narrow at the surface.\n\n**When documents disagree.** Explain the evolution; never mix eras. Optimise for\narchitectural fidelity, not document fidelity. Documents are snapshots; the architecture is\nthe living system.\n\n**When this document is wrong.** Change it here. Do not write a second document. The reason\nthis consolidation exists is that the alternative was tried ninety-four times.\n\n## 23. Implementation inventory (2026-08-20)\n\n### 23.1 Apps — 16 product surfaces\n\n| Category | Apps | Purpose |\n| ------------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------ |\n| Primary product UX | `web`, `workspace`, `platform`, `platform-console`, `desktop`, `mobile` | Core authenticated workspace, platform administration, device clients |\n| Identity and connection | `auth`, `activation`, `connector`, `one-access`, `one-access-console` | Authentication, onboarding, OAuth, identity management |\n| Distribution and content | `marketing`, `marketing-sites`, `portfolio`, `docs`, `mcp-servers` | Public web, product marketing, internal ops, documentation, MCP boundary |\n\n**Ownership requirement:** Apps own presentation and workflow entry points. They must not\nown canonical business state or provider credentials.\n\n### 23.2 Packages — 60+ reusable modules\n\n| Package group | Examples | Role |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |\n| Core platform | `core`, `kernel`, `bootstrap`, `config`, `types`, `sdk`, `api` | Runtime primitives and developer foundations |\n| Context and Spine | `context`, `context-contracts`, `spine-entities`, `spine-network`, `spine-schema`, `spine-schema-generator`, `hermes-spine-memory` | Canonical context, entity modeling, schema, relationships, memory |\n| Integration | `connectors`, `connector-contracts`, `connector-utils`, `adapters`, `provider-base`, `webhooks`, `host-platform-connector` | Provider abstractions, connector behavior, webhooks, host integration |\n| Execution and governance | `capability`, `orchestrator`, `adk`, `omni-router`, `rbac`, `tenancy`, `gateway-sdk` | Governed actions, workflow routing, agent development, authority, tenant isolation |\n| Intelligence | `intelligence`, `model-gateway`, `normalizer`, `loader`, `skills`, `analytics` | AI access, ingestion, normalization, insight generation |\n| Projections and UI | `projection-engine`, `projection-contracts`, `workbenches`, `workbench-config`, `ui`, `design-system`, `one-access-ui` | Contextual product views, reusable interface primitives |\n| Contracts and validation | `contracts`, `connector-contracts`, `context-contracts`, `integration-tests` | Stable cross-layer interfaces, integration quality controls |\n\n**Dependency direction (enforced):**\n\n```\napps → packages → core\nservices → packages → core\n```\n\n**Prohibited:**\n\n- packages → services (packages must not depend on runtime services)\n- UI → direct provider access (UI must go through ProjectionService)\n\n### 23.3 Services — 40+ backend components\n\n| Service group | Examples | Role |\n| --------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |\n| Core control plane | `gateway`, `core-engine`, `tenants`, `admin`, `store`, `telemetry`, `billing`, `continuity` | Request routing, tenant lifecycle, administration, observability |\n| Context and Spine | `context`, `context-fetch`, `spine`, `projection`, `signals`, `knowledge`, `schema-ai` | Context assembly, Spine operations, projection, knowledge retrieval |\n| Integration lifecycle | `connector`, `connector-sync`, `webhook-ingress`, `loader`, `normalizer`, `pipeline`, `provider-management-mcp` | Connection management, ingestion, normalization, pipeline processing |\n| Governed execution | `capability`, `govern`, `hermes`, `workflow`, `task-management`, `twin-orchestrator` | Capability invocation, governance evaluation, orchestration, Twin coordination |\n| AI and agents | `intelligence`, `iw-agent-runtime`, `agent-registry`, `ai-provider-mcp`, `huggingface-inference`, `mcp-pool` | AI model access, agent runtime, MCP tool management |\n| MCP ecosystem | `mcp-connector`, `integration-management-mcp`, `provider-management-mcp`, `vercel-mcp`, `marketplace-installation` | MCP protocol integration, marketplace operations |\n\n**Service ownership requirement:** No service reads another service's database tables\ndirectly. Communication occurs through typed service contracts, governed commands,\nimmutable events, service bindings, queues, and Workflows.\n\n### 23.4 Golden path — the canonical integration flow\n\n```\nConnect Provider → Ingest → Normalize → Promote to Spine →\nRender Workbench → Execute Governed Capability → Reconcile Outcome\n```\n\nThis is the single integration path that must work end-to-end before any secondary\nsurface is considered complete.\n\n## 24. Critical gaps and remediation (2026-08-20)\n\n### 24.1 Runtime completeness gaps\n\n| Gap | Severity | Evidence | Remediation |\n| ----------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |\n| MCP Pool fallback missing | **Release blocker** | Workbenches error when MCP Pool is unavailable; no mock-data fallback implemented | Add degraded-mode behavior with explicit empty/error states per workbench |\n| Sales Workbench TODO handlers | High | Twin query, assignment modal, approval flow marked TODO; actions exposed without backend | Hide or disable incomplete actions until full chain is live |\n| Spine timeline persistence | High | Route contains TODO to replace placeholder with actual Supabase insert; action history may not be durable | Implement timeline write and verify through readback tests |\n| Inbox mark-read path | Medium | Behavior not connected to platform memory proposal path | Wire to memory.propose with correct argument format |\n| Unimplemented section routes | Medium | Generic work-view renders \"Section not implemented\" | Hide behind feature readiness rules or remove route |\n\n### 24.2 Evidence contradiction\n\n`POST_STOP_FORENSIC_RECONCILIATION.md` contradicts prior \"todo list complete\" conclusions:\n\n- Customer Zero routes used unresolvable default hostname\n- Endpoints not implemented by inspected Gateway source\n- Tests validated constants and comments, not UI, routes, runtime behavior, persistence, or readback\n\n**Treatment:** Release blocker until independently disproven with end-to-end production-like tests.\n\n### 24.3 Monorepo boundary gaps\n\n| Gap | Risk | Remediation |\n| ---------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |\n| `mcp/*` and `marketplace/*` not in workspace config | May sit outside Turborepo dependency, test, typecheck, and release coverage | Include in pnpm-workspace.yaml or explicitly document exclusion rationale |\n| Backup/reference directories (`config-backup-*`, `lib-backup-*`) | Accidental-import and documentation-drift risk | Remove or archive outside workspace; add lint rule for backup patterns |\n| No machine-readable ownership/dependency policy | Package duplication and \"shadow architecture\" become likely | Publish ownership matrix with owner, status, deployability, and retirement plan per module |\n\n### 24.4 Build and release gaps\n\n| Gap | Risk | Remediation |\n| ---------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------ |\n| `lint` has no declared dependency on builds | Lint success does not establish architectural correctness | Add `dependsOn: [\"build\"]` to lint task in turbo.json |\n| `typecheck` depends on upstream builds | Masks pure type problems behind build failures | Consider separate typecheck task that runs against source directly |\n| Concurrency of 50 | May overload local/CI resources; intermittent test behavior | Reduce to 10–20 for CI; keep 50 for local only |\n| Architecture/continuity/deployment checks not mandatory CI gates | Developer-optional; verification gap | Add as required CI steps with failure-blocking |\n\n### 24.5 Test coverage gaps\n\n| Gap | Risk | Remediation |\n| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |\n| Some tests validate constants/comments | False confidence; no real integration coverage | Add contract tests against deployed ephemeral environments |\n| No write-then-readback tests | Mutations may not be durable | Add readback tests for every Spine, timeline, approval, and reconciliation mutation |\n| No failure scenario tests | Provider failure, policy denial, expired delegation, duplicate webhook, retry, idempotency, compensation untested | Add dedicated failure scenario test suite |\n\n### 24.6 Product-surface duplication\n\n| Surfaces | Overlap | Remediation |\n| ---------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------- |\n| `web`, `workspace` | Both claim authenticated workspace | Define single responsibility: `web` = end-user workspace, `workspace` = reusable composition package |\n| `platform`, `platform-console` | Both claim platform administration | Define: `platform` = backend/runtime, `platform-console` = customer control-plane UI |\n| `one-access`, `one-access-console` | Both claim identity management | Define: `one-access` = runtime identity, `one-access-console` = administration console |\n\n**Required:** Route-to-owner registry identifying app, backing service, owner, environment,\nand automated test suite for every production route.\n\n### 24.7 Frontend gaps\n\n**Workbench gaps:**\n\n- Sales Workbench TODO handlers for Twin query, assignment, approval\n- Generic work-view \"Section not implemented\" visible\n- Mock fallback missing for MCP Pool failures\n\n**State and resilience:**\n\n- No degraded-mode UX for MCP Pool failures, connector outages, empty states, partial hydration\n- UI behaves as if data is always present and tools always reachable\n\n**Mutation gaps:**\n\n- Twin accept actions wired through memory.propose but argument format needs platform-side fix\n- Timeline API route contains TODO for Supabase insert\n- Users can trigger actions that appear accepted before durable proof is guaranteed\n\n**Canonical-model mismatch:**\n\n- Frontend does not fully represent degraded connectors, approval-required proposals,\n reconciliation status, evidence availability, hydration progress\n\n**Missing frontend capabilities:**\n\n- Connector health UX (connectors.status exists but no robust degraded-state system)\n- Reconciliation UX (pending/observing/verified/failed/compensation_required/compensated lifecycle not exposed)\n- Evidence/audit UX (incomplete persistence and action wiring)\n\n### 24.8 Highest-priority remediation order\n\n1. **Prove the golden path:** authenticate → connect provider → ingest → normalize →\n Spine write → Workbench read → governed action → provider confirmation →\n reconciled Spine readback\n2. **Close persistence gaps:** implement timeline database write and verify through durable readback tests\n3. **Fix runtime resilience:** add explicit degraded-mode behavior when MCP Pool or provider is unavailable\n4. **Make release evidence real:** CI deploys isolated environment, executes API and browser tests,\n verifies persistence, validates external routes before promotion\n5. **Publish package/service governance:** owner, status, deployability, canonical contracts,\n inbound/outbound dependencies, and retirement plan per module\n6. **Hide incomplete actions:** disable TODO handlers until Twin query, assignment, approval,\n and section routes are actually live\n7. **Add resilient states:** loading, empty, degraded, offline/fallback for every MCP-backed workbench\n8. **Model platform truth in UI:** approval needed, queued, executed, observing, verified,\n failed, compensated\n9. **Require mutation readback:** no optimistic success banners for governed actions touching\n memory, Spine timeline, approvals, or provider execution\n\n## 25. E2E test strategy (2026-08-20)\n\n### 25.1 Current coverage (smoke tests)\n\nPlaywright runs against `localhost:3000` across Chromium, Firefox, and WebKit. The suite\nvalidates that pages and key UI controls render. It does **not** prove the complete\ngoverned business loop.\n\nCurrent assertions cover: auth/tenant isolation rendering, memory hub visibility,\napprovals visibility, handoff lifecycle rendering, outcome ingestion rendering,\ntenant class enforcement rendering, continuity loop rendering, agentic workspace\nnavigation rendering.\n\nThese are smoke tests — they confirm the UI exists, not that it works end-to-end.\n\n### 25.2 The gap — canonical governed loop not proven\n\nA real E2E test must prove this chain:\n\n```\nAuthenticate\n → resolve tenant and authorization\n → connect or validate a provider\n → ingest an external event\n → normalize and promote canonical context to Spine\n → materialize projection\n → render Workbench\n → draft/propose action\n → policy and approval decision\n → execute provider action\n → reconcile provider outcome\n → append evidence/audit\n → refresh UI from verified Spine state\n```\n\nNone of these transitions are currently tested as an integrated chain.\n\n### 25.3 Missing test assertions\n\n| Layer | Required assertion |\n| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |\n| Identity | Session resolves correct tenant, membership, role, permission, capability grant — not merely \"logged in\" |\n| Isolation | Second tenant cannot retrieve, mutate, search, or infer first tenant's entities, memory, connector state, files, audit events |\n| Ingestion | Webhook/provider event accepted once, deduplicated, normalized, linked to canonical entity, visible in projected Workbench view |\n| Governance | Same command auto-approved, queued, or denied depending on policy inputs; UI accurately displays each outcome |\n| Execution | Provider acceptance not treated as success; UI shows pending/observing until reconciliation confirms verified, failed, or compensated |\n| Evidence | Every material mutation produces retrievable audit/evidence records; write failure prevents material command from presenting as complete |\n\n### 25.4 Priority E2E scenarios\n\n**1. Tenant activation:**\n\n```\ncreate tenant → deploy/resolve runtime → migrate operational store →\nbootstrap workspace and policy → discover connector → hydrate working set →\nopen useful Workbench with initial Twin brief\n```\n\n**2. Inbound-to-Workbench:**\n\n```\nprovider webhook → idempotency check → loader → normalizer →\nSpine entity/relationship update → projection invalidation →\nUI refresh → user opens correct entity with lineage and freshness shown\n```\n\n**3. Governed outbound action:**\n\n```\nuser accepts Twin proposal → capability authorization → policy decision →\napproval where required → provider call → reconciliation observation →\nverified Spine update → Workbench timeline and audit readback\n```\n\n**4. Failure and recovery:**\n\n```\nsimulate provider timeout/rejection → show failed/observing state →\nretain evidence → allow retry or compensation only through governed controls →\nprevent false-success UI state\n```\n\n**5. MCP outage:**\n\n```\nMCP Pool unavailable → Workbench shows designed degraded state →\ncached read-only content when safe → retry controls →\nno non-durable optimistic mutations\n```\n\n### 25.5 Test design requirements\n\n| Requirement | Rationale |\n| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |\n| Deployable E2E environment with actual service bindings | Local Next.js process cannot prove tenant isolation, provider integration, or reconciliation |\n| Tenant-scoped data stores and provider sandbox/test doubles | Real data flow, not mocked responses |\n| Seed data through real ingestion APIs | Never preseed only final UI-facing database state |\n| Independent readback assertions | Provider test double → reconciliation record → Spine entity/timeline → projection API → audit/evidence API → browser UI |\n| Test IDs and workflow correlation IDs | Trace browser actions across gateway, capability, policy, execution, reconciliation, audit |\n| Smoke tests vs E2E gate | \"Button is visible\" = smoke; state transitions, durable writes, policy outcomes, tenant isolation = E2E gate |\n\n---\n\n# Appendices\n\n## Appendix A — Kernel terms\n\nSee [§3](#3-the-kernel-vocabulary). Twelve terms, frozen: WORK · CONTEXT · SPINE ·\nCONTINUITY · WORKBENCH · TWIN · CAPABILITY · GOVERNANCE · HERMES · SYNC · BRIDGE · OUTCOME.\n\n## Appendix B — Runtime sequence\n\n```\nConfiguration → Integration → Pipeline → Adaptive Spine → Workbench Composition\n→ Continuity Bridge → User Workbench → Twin → Capability → Governance\n→ Hermes → Sync → Promotion\n```\n\nGoverned execution path:\n\n```\nTwin or user intent → Capability Fabric → Governance → Hermes → execution provider\n→ provider outcome → re-ingestion → verification and reconciliation → Pipeline promotion\n```\n\nSystem loop: `LOAD → NORMALIZE → STORE → THINK → REVIEW & APPROVE → ACT → REPEAT`\n\nDeterministic normalisation functions (the boundary is normative; the stage count is not a\nproduct concept):\n\n```\n1 Raw Event Ingestion 2 Canonical Field Mapping 3 Schema Normalization\n4 Entity Resolution 5 Deduplication 6 Relationship Linking\n7 Depth Matrix Evaluation 8 Spine Write\n```\n\n## Appendix C — Services\n\n**Core nine (canonical publication order, Gateway last):**\n\n| Worker | Responsibility |\n| ---------------- | ------------------------------------------------------------------------------- |\n| `pipeline` | Normalizer + Spine writer. Self-declared sole holder of Spine write credentials |\n| `connector` | Compatibility router → loader · store · mcp-connector |\n| `mcp-connector` | MCP tool server + OAuth authorisation server |\n| `connector-sync` | Schema-driven scheduled and on-demand provider sync |\n| `knowledge` | Chunking, embedding, search, synthesis, promotion gate, lineage |\n| `continuity` | Append-only session event log, checkpoints, continuity assembler |\n| `intelligence` | think + act + govern + agents |\n| `workflow` | Bound as `BFF`. Views, analytics, stream gateway, HITL Durable Object |\n| `gateway` | Single entry point |\n\n**Bound but outside the release path:** `spine` (`SPINE`) · `iw-agent-runtime`\n(`AGENT_RUNTIME`) · `webhook-ingress` · `mcp-pool` · `admin` · `billing` · `tenants` ·\n`folder-watcher` · `loader` · `store` · `task-management`\n\n**Zero inbound bindings:** `agent-registry` · `hermes` · `integration-management-mcp` ·\n`marketplace-installation` · `provider-management-mcp` · `schema-ai` · `signals` ·\n`telemetry` · `twin-orchestrator` · `vercel-mcp`\n\n## Appendix D — Gateway routes\n\n| Route | Target | Purpose |\n| ------------------------------------ | ------------------------ | -------------------------------------------- |\n| `/api/v1/auth` | INTERNAL_AUTH | Authentication |\n| `/api/v1/projections` | INTERNAL_PROJECTIONS | Projection Engine |\n| `/api/v1/workspace/discovery` | Gateway → Spine | First canonical read |\n| `/api/v1/workspace/*` | BFF | Workspace operations |\n| `/api/v1/billing` | INTERNAL_BILLING | Billing |\n| `/api/v1/tenants` | INTERNAL_TENANTS | Tenant management |\n| `/api/v1/support` | INTERNAL_SUPPORT | Support |\n| `/api/v1/analytics` | BFF | Analytics |\n| `/api/v1/agents` | INTELLIGENCE | Agent management |\n| `/api/v1/continuity-bridge` | MCP_CONNECTOR | Public 19-tool Spine MCP |\n| `/api/v1/connectors` | CONNECTOR | Connector management |\n| `/api/v1/pipeline` | PIPELINE | Data pipeline |\n| `/api/v1/intelligence` | INTELLIGENCE | Intelligence layer |\n| `/api/v1/cognitive/spine` | PIPELINE | Spine operations |\n| `/api/v1/cognitive/entity360` | PIPELINE | Entity 360 |\n| `/api/v1/cognitive/memories` | KNOWLEDGE | Memory operations |\n| `/api/v1/cognitive/signals` | INTELLIGENCE | Signal processing |\n| `/api/v1/cognitive/think` | INTELLIGENCE | Think / Twin |\n| `/api/v1/cognitive/act` | INTELLIGENCE | Act execution |\n| `/api/v1/cognitive/govern` | INTELLIGENCE | Governance |\n| `/api/v1/cognitive/twin` | AGENT_RUNTIME | Twin runtime |\n| `/api/v1/knowledge` | KNOWLEDGE | Knowledge management |\n| `/api/v1/marketplace/installations*` | MARKETPLACE_INSTALLATION | Onboarding state machine |\n| `/api/v1/marketplace/apps` | SPINE | Catalogue (Spine data) |\n| `/api/v1/l2` | L2 | Cognitive overlay _(retired label — see S6)_ |\n| `/admin` | INTERNAL_ADMIN | Admin |\n| `/oauth` | INTERNAL_AUTH | OAuth flows |\n| `/ws`, `/sse`, `/stream` | BFF | Real-time |\n\nEndpoint ownership by intent:\n\n| Intent | Family | Owner |\n| -------------------------------------------- | ----------------------------- | ------------------------------------------------- |\n| Discover product | `/api/v1/workspace/discovery` | Gateway + Configuration + Activation + Projection |\n| Onboard / configure / activate | `/api/v1/workspace/*` | Configuration + Activation |\n| Browse / connect / sync / revoke | `/api/v1/connectors/*` | Integration Manager |\n| Compose Workbench, Inbox, Entity 360, canvas | `/api/v1/projections/*` | Projection Engine |\n| Read knowledge / evidence | `/api/v1/knowledge/*` | Knowledge and evidence services |\n| Ask / assign Twin | Semantic Twin routes | Twin runtime — drafts only |\n| Approve / reject / execute | Governance command routes | Governance → Hermes |\n\n## Appendix E — Gateway bindings\n\n| Category | Binding | Type |\n| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |\n| Database | `DB` | D1Database (`integratewise-spine-cache`) |\n| KV | `RATE_LIMITS`, `SESSIONS`, `CONNECTOR_STATUS`, `SIGNAL_CACHE`, `METRICS`, `OAUTH_STATE_KV` | KVNamespace |\n| R2 | `FILES` | R2Bucket |\n| Services | `CONNECTOR`, `CONNECTOR_SYNC`, `PIPELINE`, `INTELLIGENCE`, `KNOWLEDGE`, `BFF`, `L2`, `AGENT_RUNTIME`, `ADMIN`, `BILLING`, `TENANTS`, `WEBHOOK_INGRESS`, `HUB_CONTROLLER`, `SPINE`, `MCP_POOL`, `MARKETPLACE_INSTALLATION` | Fetcher |\n\nIsolation invariant: no `env.test` target may equal any `env.prod` target, for any binding\nclass. `validate-platform-deployment.sh` currently asserts this only for `mcp-connector`.\n\n## Appendix F — Canonical entities\n\n| Entity | Source |\n| ------------- | ------------------------------------------- |\n| Connection | `packages/spine-entities/src/connection.ts` |\n| Connector | `packages/spine-entities/src/connector.ts` |\n| SyncJob | `packages/spine-entities/src/sync-job.ts` |\n| Webhook | `packages/spine-entities/src/webhook.ts` |\n| Schema | `packages/spine-entities/src/schema.ts` |\n| Capability | `packages/spine-entities/src/capability.ts` |\n| TimelineEvent | `packages/spine-entities/src/timeline.ts` |\n\nTenant lifecycle families: `spine_organizations` · `spine_workspaces` · `spine_users` ·\n`spine_memberships` · `spine_roles` · `spine_permissions` · `spine_tenant_accounts` ·\n`spine_networks`. Generic `spine_entities` remains the compatibility graph and identity\nlayer; typed tables are the canonical materialised home for their families.\n\nEntity contract (frozen): identity · fields · relationships · timeline · provenance ·\npermissions · capabilities.\n\n## Appendix G — Connector lifecycle\n\n```\nPublish connector definition → discover / install → resolve identity and tenant\n→ reuse eligible connection or request consent → store opaque credential reference\n→ create tenant/workspace connection binding\n→ discover provider objects, fields, events, operations\n→ approve schema / entity / capability mappings\n→ activate initial hydration and delta sync\n→ Pipeline promotes entities, relationships, provenance, evidence\n→ Projection Engine invalidates and recompiles permitted views\n→ monitor, repair, revoke, reconcile\n```\n\nThe binding must deterministically resolve:\n\n```\n(user_id, tenant_account_id, tenant_id, spine_network_id, provider_key,\n provider_workspace_id, connector_binding_id, spine_connection_id, schema_binding_set)\n```\n\nConnector installation registers mappings, sources, availability and approved additive\nextensions. **It does not execute ad-hoc physical DDL.**\n\n## Appendix H — Public 19 tools\n\n`get_my_continuity` · `get_active_context` · `get_my_focus` · `get_context` · `get_changes` ·\n`get_related` · `get_history` · `get_commitments` · `get_decisions` · `get_permitted_memory` ·\n`get_relevant_knowledge` · `ask_twin` · `assign_twin` · `get_prepared_work` ·\n`get_available_actions` · `prepare_action` · `get_action_plan` · `approve_action` ·\n`store_in_spine`\n\n## Appendix I — Stop-ship invariants\n\nA release is not aligned if any of the following is true:\n\n1. The browser selects a legacy identity provider while Clerk is configured\n2. The public MCP lists anything other than the exact 19 tools\n3. The Plugin claims automatic inheritance of other host-app credentials, or the MCP lane\n omits its standalone browser Workbench / fallback path\n4. A UI or Twin route writes Neon directly\n5. D1 is described or used as canonical business truth\n6. A failed live projection silently becomes demo data\n7. A material write executes without a proposal, a policy decision, a receipt and a\n reconciliation — on **any** route, host-native or IntegrateWise-native\n8. A provider connector is copied into a product repository\n9. The user must explain context already present in the Spine Network\n10. L1/L2/L4/L7 appear as user-facing product navigation\n11. A host, MCP client, frontend or agent queries Fortress storage directly\n12. An answer claims cross-system completeness without reporting `canonical` completeness or\n disclosing the systems it could not see\n13. Declared host capability is routed to without runtime confirmation\n14. The same provider is called through both host and IntegrateWise by default\n15. A write path returns `success` when the canonical write was skipped, failed, or landed\n only in a cache\n16. Any automated path can write `governance_state = 'approved'` without an approver identity\n17. A component writes synchronously to both the Spine and a projection\n18. An AI classifier establishes source identity or canonical identity on its own\n19. An agent promotes a rule into autonomous execution\n20. A response conveys uncertainty as a guessed value rather than an explicit state\n\nAdditionally, per §17: no test/prod resource sharing of any binding class, and no Worker\npublication outside `Release Core Workers`.\n\n## Appendix J — Vocabulary ledger\n\n| Retired | Current | Status |\n| ----------------------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| Cognitive OS · IntegrateWise OS · AI OS | IntegrateWise Platform | Superseded — category |\n| OS Shell · Views · Topic Boards | Workbench | Renamed — one surface |\n| Atlas Spine | Adaptive Spine | Renamed |\n| 16 AI Agents (named personas) | Capabilities in the Capability Fabric | Superseded — taxonomy retired |\n| Cognitive Twin · AI assistant · copilot | Twin | Renamed — silent by default |\n| Co-worker (as separate runtime) | Twin | Superseded — one runtime |\n| Normalizer · Hermes (external use) | _(internal only)_ | Never customer-facing |\n| IW Continuity Bridge | IntegrateWise / Continuity Bridge (internal) | Retired public name |\n| TenantClass | Profile | Renamed — it was a runtime property, not a tenant property |\n| L1 / L2 / L4 / L7 | Workbench / Twin / Continuity / Governance | Engineering-internal only; never user-facing |\n| `/api/v1/cognitive/*` | _(unresolved)_ | \"Cognitive\" is not a kernel term — rename or sanction as an alias |\n| Brain _(as a write destination or truth store)_ | Brain — a reasoning and learning **projection** used by the Twin | Never a second store. The durable path is `Spine → Twin proposal → Governance → Hermes → re-ingestion into Spine` |\n\n## Appendix K — Path to alignment\n\nThe ordered sequence that closes the gap between Part II and Part III. Ordering is not\narbitrary: each step removes an ambiguity the next step would otherwise encode.\n\n| # | Step | Closes |\n| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |\n| 0 | **Make canonical write failure hard-fail** instead of `console.warn` + `success: true`; route canonical writes through `SPINE` to Neon; delete `CANONICAL_SPINE_DB` | **S0 — silent data loss.** Nothing else in this table matters if canonical writes are not landing |\n| 1 | Close the `hub-controller-api` bypass — fold into `services/` behind Gateway auth with isolated test/prod D1, or delete the catch-all route and the bypass branch | S1 |\n| 2 | Repair the 15 dangling bindings and 5 test/prod leaks; extend `validate-platform-deployment.sh` to assert, for every binding class, that no `env.test` target equals any `env.prod` target and that every `service =` resolves to a declared `name =` | S2, S3 — and converts them into a permanently-caught error class |\n| 3 | Decide the Spine writer (**D4**); retire the loser; add `spine` to `CORE_SERVICES` | S8 |\n| 4 | Wire or formally retire `hermes` — it is stage 11 of the frozen sequence and currently unreachable | Tier 5 |\n| 5 | Normalise environment vocabulary to `dev`/`test`/`prod`; delete both root wrangler configs and `ci-cd.yml` | S4 |\n| 6 | Consolidate the migration ledger to one root, one sequence, no duplicate numbers | S9 |\n| 7 | Consolidate frontend calls on `NEXT_PUBLIC_IW_API_URL` and one typed Gateway client; remove production localhost and direct-service fallbacks | §16.3 |\n| 8 | Complete live deployment plus negative tenant/RBAC and frontend acceptance for `/api/v1/workspace/discovery` | §16.3 |\n| 9 | Rename the L-layer trees; fix the rendered string in `releases-view.tsx`; **rewrite the L4 passage in the Twin's system prompt**; resolve `/api/v1/cognitive/*` | S6 |\n| 10 | Collapse to one Workbench URL namespace; remove the capability catalogue and executor from the Workbench | S7 |\n| 11 | Delete inert mass — dead Capability Fabrics, orphaned Vite root, `_deprecated`, retired GCP surfaces, zero-consumer packages | S5, S10, S11 |\n| 12 | Add `\"private\": true` to the 16 unmarked packages; make `release:packages:check` fail on any non-private package other than `sdk` and `spine-schema` | S12 |\n| 13 | Complete one connector end to end: consent → strict binding → discovery → schema mapping → hydration → delta sync → revoke → projection invalidation | §16, Appendix G |\n| 14 | Validate the full four-button governed loop: proposal → approval token → Hermes → provider outcome → re-ingestion → reconciliation → projection refresh | §10 |\n| 15 | Validate Development → Customer Zero → Customer Production promotion with isolated credentials, data, bindings, queues, caches, evidence and audit | §17 |\n\n**Integrated-testing gate.** Do not begin the integrated testing event until every item below\nhas evidence. Any missing item is a blocker, not post-launch cleanup:\n\nenvironment/DNS/identity/Gateway/Neon/R2/D1/KV/queue/secret health · migration ledger and\nschema verification · cross-tenant and cross-environment negative tests · first-read\ndiscovery and every visible sidebar projection contract · one real connector through the full\nlifecycle · public MCP OAuth and exact 19-tool listing · no automatic inheritance of unrelated\nhost-app credentials · no direct frontend database/provider/internal-MCP traffic · explicit\npartial and degraded states with no live-to-demo fallback · one complete governed action\ntrace · bounded retry, ambiguous-outcome protection, dead letter and governed replay ·\nobservability, audit, rollback and revocation evidence.\n\n## Appendix L — Document disposition\n\n`docs/architecture/` held 94 entries at consolidation. Their disposition:\n\n### Retained — still authoritative in their own scope\n\nDetailed specifications this document summarises. Each remains the reference for its\nimplementation detail and is subordinate to this document.\n\n`APP_CATEGORY_ENTITY_DOMAIN_CLASSIFICATION.md` · `CANONICAL_SPINE_SCHEMA_FOUNDATION.md` ·\n`SPINE_ENTITY_TABLE_SCHEMA.md` · `TENANT_LIFECYCLE_SCHEMA_REGISTER.md` ·\n`TENANT_SPINE_FORTRESS_OPERATIONAL_FLOW_MODEL.md` · `WORKBENCH_ROLE_CAPABILITY_MAP.md` ·\n`IW_SPINE_NETWORK_PLUGIN_AND_MCP_MARKETPLACE_CONTRACT.md` ·\n`FRONTEND_PLATFORM_API_AND_DISCOVERY_SPEC.md` · `RUNTIME_SUBSTRATE_AND_SURFACE_CONTRACT.md` ·\n`CODEBASE_EXCAVATION.md` (the drift baseline; Part III derives from it) ·\n`HOST_AWARE_CONTINUITY_RUNTIME_SPEC.md` (frozen 2026-07-29 — the normative source for\n§15.5–15.8: request classification, capability resolution, connection binding, agent\ncontracts, Loader/Normalizer schemas, failure matrix and acceptance criteria)\n\n### Absorbed — content now lives here; archive\n\n`ARCHITECTURE_LOCK.md` · `IMPLEMENTATION_CONTRACT_v1.1.md` ·\n`CONSOLIDATED_PRODUCT_PLATFORM_CONTRACT_v1.2.md` · `PLATFORM_LOCK_v1.0.md` ·\n`FOUR_BUTTONS.md` · `TWIN_BEHAVIOR.md` · `WORKBENCH_MATRIX.md` · `ADAPTIVE_SPINE_MODEL_v1.md` ·\n`CAPABILITY_FABRIC.md` · `SOURCE_PACK_RECONCILIATION_2026-07-28.md` ·\n`RUNTIME_PROFILE_AND_ENTRY_CHANNEL_CONTRACT.md` · `CANONICAL_ARCHITECTURE.md` ·\n`MASTER_EXECUTION_PLAN.md` · `PRODUCT_PLATFORM_BOUNDARY_AND_GO_LIVE_STANDARD.md` ·\n`PLATFORM_PRODUCT_DATA_AND_PROJECTION_REFERENCE.md` ·\n`CUSTOMER_ZERO_TO_EXTERNAL_PRODUCT_AND_MARKETPLACE_SPEC.md` ·\n`CUSTOMER_ZERO_HOSTED_PLUGIN_CODE_BRIEF.md` · `BROWSER_FRONTEND_AND_MCP_PRODUCT_CODE_BRIEF.md`\n\n### Constitutions — absorbed into Parts I and II\n\nThe nine constitutions each stated the doctrine for one subsystem. Their content is now\ndistributed across §2–§16.\n\n`ADAPTIVE_WORKBENCH_CONSTITUTION.md` · `CANONICAL_ENTITY_CONSTITUTION.md` ·\n`CAPABILITY_CONSTITUTION.md` · `CONNECTOR_CONSTITUTION.md` · `EXECUTION_CONSTITUTION.md` ·\n`GOVERNANCE_CONSTITUTION.md` · `PROJECTION_CONSTITUTION.md` · `RUNTIME_CONSTITUTION.md` ·\n`TWIN_CONSTITUTION.md` · `CUSTOMER_ZERO_CONSTITUTION.md` (DRAFT) ·\n`CUSTOMER_ZERO_DAILY_OPERATING_MANUAL.md` (DRAFT)\n\n### Superseded — already marked, or superseded by this document\n\n`CANONICAL_PLATFORM_ARCHITECTURE.md` · `CANONICAL_SPINE_CONVERGED.md` ·\n`CANONICAL_ARCHITECTURE_V4.md` · `PRODUCT_ARCHITECTURE.md` · `PRODUCT_ARCHITECTURE_V1.md` ·\n`USER_SYSTEM_JOURNEY_BLUEPRINT.md` · `PLATFORM_ARCHITECTURE.md` · `END_TO_END_ARCHITECTURE.md` ·\n`SINGLE_END_TO_END_MAP.md` · `FRONTEND_LAYERED_STACK.md` · `PLANE_LAYER_CROSS_REFERENCE.md` ·\n`PROJECTION_MODEL.md` · `PROJECTION_CONTEXT_REFACTOR.md` · `SPINE_MODEL.md` ·\n`SPINE_DOMAIN.md` · `ENTITY360_V2_MODEL.md` · `UNIFIED_GOVERNANCE_SPEC.md` ·\n`WORKBENCH_DOCTRINE.md` · `MULTI_PROTOCOL_PLATFORM.md` · `ONBOARDING_FLOW.md` ·\n`CURRENT_CONTEXT_FLOW.md` · `DETAILED_USER_FLOWS_AND_SYSTEM_PATHS.md` ·\n`AI_CONNECTOR_MCP_FLOW.md` · `CONNECTOR_RUNTIME_PROOF.md` · `SPINE_INTELLIGENCE_AGENT.md` ·\n`LONG_TERM_TASK_MANAGEMENT_MCP.md` · `CODEBASE_ALIGNMENT_SPEC.md` ·\n`ARCHITECTURE_DOCUMENTATION_PLAN.md` · `DOCUMENTATION_COMPLETION_MANIFEST.md` ·\n`APP_CATEGORY_ENTITY_DOMAIN_MODEL.md` (+ `.txt` duplicate)\n\n### Lineage — historical, retain in `docs/archive/`\n\nThe v2 deep-dive family and the locked-v1 lineage. Valuable as evolution record; not\nauthority.\n\n`integratewise-architecture-v2.0.md` · `v2-ai-capability-fabric.md` · `v2-capability-layer.md` ·\n`v2-continuity-governance.md` · `v2-data-model.md` · `v2-deployment.md` · `v2-ecosystem.md` ·\n`v2-identity-ingress.md` · `v2-provider-fabric.md` · `v2-security.md` · `locked-v1.md` ·\n`locked-v1.0.1.md` · `final-e2e-system.md` · `l1-reality-check.md` · `reality-audit.md` ·\n`one-full-prompt.md` · `suite-00-34.md` · `source/`\n\n### Unresolved\n\n`MCP_POOL_MULTI_ENVIRONMENT_STRATEGY.md` — DRAFT, conflicts with §15.1. Blocked on **D6**.\nDo not archive until decided; do not treat as authority meanwhile.\n\n### Not architecture\n\n`PRODUCT_NARRATIVE.md` and `STAKEHOLDER_PITCH.md` are commercial documents and belong under\n`docs/commercial/`, governed by the [Deck Core](../commercial/decks/00-deck-core.md) and\n[GTM Canon](../commercial/09-gtm/00-current-gtm-canon.md). `README.md` becomes a pointer to\nthis document. `CANONICAL_SPINE_SCHEMA.sql` is an artifact, not a document.\n\nFor the checkout-grounded ownership, wiring, storage, deployment, marketplace, migration, and\ncomponent-disposition map, see the subordinate\n[Canonical Ecosystem Coverage Companion](CANONICAL_ECOSYSTEM_COVERAGE_COMPANION.md). It separates\nrepository/configuration evidence from deployed runtime proof and does not override this document\nor its canonical amendments.\n\n---\n\n# Part IV — Consolidated Reference (historical, superseded)\n\n> **Note:** This part was an earlier consolidation. It is now superseded by\n> Parts V (Master Reference), VI (Consolidated Canon), and VII (Book-of-Record\n> Baseline). The content below is retained for historical continuity. Do not\n> edit — make changes in Parts V–VII instead.\n\nThis part consolidates the architecture into 12 canonical sections. It is the\nprimary reference for implementation, documentation, onboarding, and product\nmessaging. Earlier parts remain as design history and detailed specification.\n\n## 23. Product definition\n\n**IntegrateWise is an Adaptive Operational Workspace built on an Adaptive Spine\nthat provides Organizational Continuity through a Shared Workbench, a contextual\nTwin, and governed capability execution.**\n\nEarlier descriptions (AI Workspace, Productivity Platform, Department Workspace)\nare product descriptions, not the architecture.\n\n## 24. Platform flow\n\nThe complete platform is always described in one direction:\n\n```\nMarketplace / Plugin\n │\n ▼\nWorkspace Activation\n │\n ▼\nConfiguration Manager\n │\n ▼\nIntegration Manager\n │\n ▼\nActivation Bridge\n │\n ▼\nLoader Runtime\n │\n ▼\nNormalizer + Triage\n │\n ▼\nAdaptive Spine\n │\n ▼\nProjection Engine\n │\n ▼\nAdaptive User Workbench\n │\n ▼\nTwin\n │\n ▼\nCapability Fabric\n │\n ▼\nGovernance\n │\n ▼\nHermes\n │\n ▼\nExecution\n │\n ▼\nSync\n │\n ▼\nContinuity Pipeline\n │\n ▼\nAdaptive Spine\n```\n\n## 25. User onboarding\n\nThe onboarding flow is lifecycle-first, not role-first:\n\n```\nMarketplace Install\n ↓\nIdentity\n ↓\nOrganization\n ↓\nOAuth\n ↓\nConnect one or two tools\n ↓\nOne-click Loader\n ↓\nAdaptive Spine\n ↓\nProjection Engine\n ↓\nAdaptive Workbench\n```\n\nThen the user continues connecting:\n\n```\nSlack, GitHub, Notion, Google, HubSpot, Salesforce, Jira, ...\n```\n\nEvery connector expands the same organization rather than creating another\nworkspace.\n\n## 26. Adaptive Spine\n\nThe Base Spine is mandatory. Everything else expands it:\n\n```\nBase Spine\n + Industry\n + Department\n + Role\n + Connector\n + Tenant\n + Context\n = Effective Spine\n```\n\nNothing replaces the Base Spine. Everything is additive.\n\n## 27. Projection Engine\n\nThe Projection Engine is the architectural boundary that prevents UI coupling:\n\n```\nAdaptive Spine\n ↓\nProjection Engine\n ↓\nWorkbench\n ↓\nTwin\n```\n\nNot:\n\n```\nWorkbench → Database\nGateway → Workbench\n```\n\n## 28. User Workbench\n\nThe Workbench is:\n\n- Not a dashboard\n- Not CRUD\n- Not a CRM\n- Not a document editor\n\nIt is the operational hub of every department. It composes fields, entities,\nmemories, capabilities, and views from every connected system.\n\n## 29. Twin\n\nThe Twin is not another chatbot. It continuously observes:\n\n- Current work\n- Selected records\n- Organization context\n- Historical continuity\n- Permissions\n- Available capabilities\n\nand performs the heavy operational work.\n\n## 30. OODA\n\nThe four-button interaction model is canonical:\n\n```\nObserve → Store in Spine\nOrient → Ask Your Twin\nDecide → Assign Your Twin\nAct → Approve Twin Action\n```\n\nThe Twin never owns \"Act.\" The human always authorizes execution.\n\n## 31. Capability Fabric\n\nExecution paths include:\n\n- Tool → Tool\n- Memory Fetch\n- MCP\n- Agent → Agent\n- Local execution\n- API execution\n\nThe Workbench composes the work. Capability Fabric resolves execution.\nGovernance authorizes it. Hermes orchestrates it.\n\n## 32. Runtime substrate\n\nState planes are separated and must never be merged:\n\n| Plane | Purpose |\n| -------------- | ------------------------ |\n| Adaptive Spine | Operational Truth |\n| Twin Memory | AI Continuity |\n| Session Logs | Conversation History |\n| Audit Logs | Execution Accountability |\n| Knowledge | Semantic Retrieval |\n| Blobs | Files |\n| Cache | Acceleration |\n| Sync | Convergence |\n| Config | Tenant Runtime |\n| Ephemeral | Temporary Runtime |\n\n## 33. Runtime guarantees\n\nThe operational guarantees required for production:\n\n```\nIngress\n ↓\nValidation\n ↓\nEvent Bus\n ↓\nQueues\n ↓\nCapability\n ↓\nGovernance\n ↓\nHermes\n ↓\nExecution\n ↓\nOutcome\n ↓\nVerification\n ↓\nReconciliation\n ↓\nPromotion\n ↓\nSpine\n```\n\nSupporting guarantees (mandatory platform primitives):\n\n- Idempotency\n- Retries\n- Dead-letter queues\n- Traceability\n- Structured logging\n- Observability\n- Replay\n\n## 34. Customer Zero — lifecycle-first operating model\n\nDepartments become participants in lifecycle execution rather than the primary\norganizing principle:\n\n```\nLifecycle\n ↓\nEvent\n ↓\nState\n ↓\nSOP\n ↓\nCapability\n ↓\nApproval\n ↓\nExecution\n ↓\nEvidence\n ↓\nMemory\n ↓\nNext Lifecycle\n```\n\n## 35. Consolidated layer responsibility\n\n| Layer | Responsibility |\n| -------------------------- | ------------------------------------ |\n| Workspace Activation | Tenant and identity onboarding |\n| Configuration Manager | Runtime configuration |\n| Integration Manager | Connectors, OAuth, discovery |\n| Activation Bridge | Compile active workspace context |\n| Loader + Normalizer | Canonical ingestion |\n| Adaptive Spine | Operational source of truth |\n| Projection Engine | Compose workbench projections |\n| Adaptive Workbench | Human operating surface |\n| Twin | Contextual reasoning and preparation |\n| Capability Fabric | Execution path resolution |\n| Governance | Authorization and policy |\n| Hermes | Orchestration |\n| Sync + Continuity Pipeline | Reconciliation and persistence |\n\n# Part V — Master Reference\n\nThis part consolidates the Master Index into the canonical architecture. The\nfull Master Index (`IntegrateWise_Master_Index.md`) remains as a detailed\nsupporting document; this section captures the essential structure.\n\n## 36. Product definition (Master Index)\n\n**IntegrateWise is a self-organizing operational Workbench.**\n\nIt gives every user one place to understand, decide, communicate, approve,\nand complete their work while the connected ecosystem coordinates continuously\nunderneath.\n\nCore doctrine:\n\n- One Workbench for the user\n- One Spine underneath\n- Truth you own. AI you rent. Approval in between.\n\nThe Twin is proactive, not passive: it organizes context, surfaces the actual\ntodos, proposes actions, and coordinates with tools and agents while the user\nstays in control.\n\n## 37. Core vocabulary\n\n| Term | Meaning |\n| ------------------ | -------------------------------------------------------------------------------------- |\n| Spine | The unified SSOT. Not a single database — a collection of purpose-fit data stores. |\n| Digital Memory | User-facing name for the Spine. |\n| Twin | AI reasoning layer. Rented cognition operating on owned truth. |\n| Workbench | The operational UI surface. Interactive, not a dashboard. |\n| Continuity Debt | Accumulated cost of context lost every time a tool changes or a person leaves. |\n| LOOP | THINK → ACT → GOVERN → REPEAT → ADJUST. The compounding intelligence cycle. |\n| HITL | Human-in-the-loop. AI proposes, humans decide. Architectural invariant, not a setting. |\n| Capability Network | The Spine as shared connectivity — connect once, accessible everywhere. |\n| MCP Pool | Capability registry split by operational plane vs cognitive plane. |\n| Customer Zero | IntegrateWise running IntegrateWise on itself. The founder's own workbench. |\n\n## 38. Workbench Doctrine\n\nThe IntegrateWise UI is not a dashboard. It is an operational workbench — a\nsingle, interactive surface where the user does real work without juggling\ntabs, tools, or context switches.\n\n- A dashboard is passive. It shows you data.\n- A workbench is active. You act on data directly — add a task, update a\n pipeline, approve a request, respond to an email — all without leaving\n the surface.\n\n## 39. Five-Zone Shell\n\nEvery department uses the same structural shell. What changes is the data,\nthe KPIs, the entity types, and the capabilities. The layout never changes.\n\n**Zone 1 — Department Header:** Name, icon, Continuity Score, last sync\ntimestamp. Two global filters (time range + owner) that cascade to\neverything below.\n\n**Zone 2 — Pulse Bar:** Four KPI cards per department, live from the\nGateway projection. Clicking a card filters Zone 3 to that subset.\n\n| Department | KPI 1 | KPI 2 | KPI 3 | KPI 4 |\n| ---------------- | ---------------- | -------------------- | ---------------- | ----------------- |\n| Sales | Pipeline Value | Open Deals | Win Rate | Overdue Tasks |\n| Customer Success | Accounts at Risk | Renewals | Avg Health | Open Tickets |\n| Finance | ARR | Outstanding Invoices | Burn Rate | Overdue Payments |\n| Operations | Active Projects | Blockers | SLA Compliance | Pending Approvals |\n| Marketing | Active Campaigns | MQLs | Conversion Rate | Content Published |\n| Engineering | Open PRs | Bugs | Deploy Frequency | Incidents |\n\n**Zone 3 — Main Work Surface:** Three view modes: Table (default), Board\n(Kanban), Calendar. In table mode every row has inline capability buttons\n— Call, Email, Task — on hover.\n\n**Zone 4 — OODA Action Bar:** Fixed at the bottom. Always visible. Never\nscrolls away.\n\n| Button | Action |\n| ------------------ | ----------------------------------------------------------- |\n| Observe | Slides up — write to Spine (fact, decision, risk, learning) |\n| Orient | Focuses the Twin panel with current context |\n| Decide (n pending) | Approval queue — inline approve/reject |\n| Act | Capability picker — search + recent capabilities |\n\n**Zone 5 — Twin Panel:** 300px right rail. Always present. Never hidden.\n\n- Top: Live signals feed — risk (ember), opportunity (gold), action (forest green)\n- Middle: Pending proposals with inline approve / reject\n- Below: Quick prompt chips (3 contextual suggestions)\n- Bottom: Ask Twin input\n\n## 40. Sidebar Architecture\n\nThe sidebar answers three progressively broader questions:\n\n1. **What do I need to work on?** Tasks, inbox, approvals, communications\n2. **Where am I working?** Customer Zero, AI Workspace, Account Success, Sales, Operations\n3. **How is the platform configured?** Integrations, MCP Pool, Governance, Settings\n\n### Navigation layers\n\n**Personal (80–90% of time):** Home · Inbox · Tasks · My Queue · Approvals · Notifications · Recent Work · Favorites\n\n**Communications:** Activity Feed · Email · Calendar · Meetings · Chat · Calls · Documents Shared\n\n**Workspaces (12 Departmental Views):**\n\n| # | Workspace |\n| --- | ------------------- |\n| 0 | Customer Zero |\n| 1 | Account Success |\n| 2 | Sales |\n| 3 | Business Operations |\n| 4 | Revenue Operations |\n| 5 | Finance |\n| 6 | Administration |\n| 7 | Engineering |\n| 8 | Product Development |\n| 9 | Service |\n| 10 | Customer Support |\n| 11 | AI Workspace |\n| 12 | Knowledge |\n\n**Platform:** Integration Manager · Connector Marketplace · Activation Manager · Capability Manager · MCP Pool · AI Models · Knowledge · Memory · Automation · Pipelines · Governance · Observability\n\n**Administration:** Organizations · Users · Roles · Permissions · Audit · Billing · Deployments · API Keys · Security\n\n**Personal (bottom):** Profile · Preferences · Personalization · Connected Accounts · Notifications · Appearance · Keyboard Shortcuts · Help · Feedback · Settings\n\n## 41. Platform UI Design System\n\nOne layout grammar. Twelve operational surfaces.\n\n### Design Doctrine\n\nThe Platform UI is not a collection of dashboards. It is a Platform Control\nPlane — a consistent operational grammar where page content changes but\nstructural layout never does.\n\nPrimary workspace: Paper & Forest system (warm paper background, forest\ngreen accents). The dark sidebar remains.\n\n### Shared Page Anatomy\n\nEvery Platform page has:\n\n1. Context header — title, description, status badge, primary action(s)\n2. Operational status summary — KPI strip (compact, not marketing cards)\n3. Primary management surface — table, card grid, or guided flow\n4. Inspector / Twin rail — collapsible right panel, context-aware\n5. Activity and audit timeline — bottom panel, always present\n\n### Platform Pages\n\n| Page | Purpose |\n| --------------------- | ------------------------------------------ |\n| Integration Manager | Connection operations console |\n| Connector Marketplace | App marketplace for discovery |\n| Activation Hub | Onboarding and setup flows |\n| Capability Manager | Capability registry and resolution |\n| MCP Pool | MCP tool registry and routing |\n| AI Models | Model configuration and routing |\n| Knowledge | Document and evidence management |\n| Memory & Continuity | Durable memory and continuity management |\n| Automation | Workflow and automation management |\n| Pipelines | Data pipeline management |\n| Governance | Policy, authority, and approval management |\n| Observability | Logs, traces, metrics, audit |\n\n## 42. Design System Tokens\n\n| Token | Value | Use |\n| ------------- | ---------------- | -------------------------- |\n| Background | #F4F0E8 | Warm white paper |\n| Sidebar | #0C0C0C | Canvas black |\n| Active accent | #2D5A3D | Forest green |\n| Signals/gold | #B8943F | Opportunity, warning |\n| Risk/urgent | #E8693A | Ember |\n| Heading font | DM Serif Display | Page and section titles |\n| Body font | Instrument Sans | UI, labels, body |\n| Number font | IBM Plex Mono | All numbers and timestamps |\n\n## 43. Workbench IA & Spine Projection Map\n\nEvery navigation item is a surface. Every surface is a projection over the\nSpine. No surface owns its own database.\n\n### Standard surface template\n\nFor each surface:\n\n- What it is — one sentence\n- User question — what this surface helps the user answer\n- Spine domains — Work, Communication, Knowledge, Memory, Governance, Capability, Platform, or Identity\n- Source tables — canonical tables and connector-derived records\n- Twin behavior — when it appears and what it can propose\n- Actions — what the user can do from the surface\n- Missing schema — only if a needed table does not exist yet\n- Projection output — entities, KPIs, signals, capabilities, memory refs\n\n### Home surface\n\nThe user's operational command centre. Not a dashboard — a living brief\nassembled by the Twin every session.\n\nSpine domains: Work Spine + Communication Spine + Signal Spine + Memory Spine\n\nTwin behavior:\n\n- Assembles the daily brief: priorities, blockers, decisions needed\n- Surfaces continuity threads that were interrupted since last session\n- Proposes the first three actions for the day\n- Flags anything that degraded overnight\n\n# Part VI — Consolidated Canon\n\nThis part consolidates the complete architecture into a single canonical\nreference. It supersedes all prior conflicting statements and represents\nthe unified architecture as of this document.\n\n## 44. Canonical hierarchy\n\n```\nINTEGRATEWISE\n│\n├── ONE AUTH / IDENTITY\n│\n├── SPINE NETWORK / MARKETPLACE ENTRY\n│\n├── WORKSPACE ACTIVATION RUNTIME\n│\n├── CONNECTOR + INGESTION FABRIC\n│\n├── ADAPTIVE SPINE\n│ ├── Entity\n│ ├── Relationship\n│ ├── Timeline / Events\n│ ├── Operational State\n│ ├── Knowledge\n│ ├── Memory / Continuity\n│ ├── Context\n│ ├── Signals\n│ ├── Governance\n│ ├── Capability\n│ └── Projection\n│\n├── PROJECTION ENGINE\n│\n├── ADAPTIVE WORKBENCH\n│\n├── CONTEXTUAL TWIN\n│\n├── CAPABILITY FABRIC\n│\n├── GOVERNANCE\n│\n├── ORCHESTRATION / EXECUTION\n│\n└── VERIFY → RECONCILE → SPINE\n```\n\nThe Workbench is one. The Spine is one. The Projection is many.\n\n## 45. Canonical runtime loop\n\n```\nDiscover / Install\n ↓\nOne Auth\n ↓\nIdentify User + Organization + Tenant\n ↓\nConnect Initial Systems\n ↓\nDiscover Connector / MCP / Tool Capabilities\n ↓\nIngest\n ↓\nLoad\n ↓\nAggregate by Tenant\n ↓\nNormalize / Triage\n ↓\nPromotion / Governance\n ↓\nAdaptive Spine\n ↓\nProjection Engine\n ↓\nAdaptive Workbench\n ↓\nUser Works\n ↓\nTwin Observes + Orients\n ↓\nAsk / Assign\n ↓\nTwin Researches / Prepares / Proposes\n ↓\nCapability Resolver\n ↓\nGovernance / Authority Check\n ↓\nOrchestrate + Execute\n ↓\nAcknowledge\n ↓\nRe-ingest Outcome\n ↓\nVerify\n ↓\nReconcile\n ↓\nPromote / Update Spine\n ↓\nRe-project\n ↓\nRehydrate Workbench\n ↓\nContinue\n```\n\n## 46. Adaptive Workbench — compiled, not constructed\n\nThe Workbench is compiled rather than manually constructed:\n\n```\nBase Workbench\n+ Identity\n+ Role / Responsibility\n+ Department\n+ Industry\n+ Permissions\n+ Tenant Policy\n+ Connected Systems\n+ Available Spine Data\n+ Available Capabilities\n+ Current Lifecycle\n+ Active Context\n+ User Preferences\n+ Observed Work Behaviour\n+ Need Queue\n= Effective Workbench Projection\n```\n\n### Auto-Tuner\n\nThe Auto-Tuner belongs **inside this projection loop**, not beside it as\nanother platform service:\n\n```\nActivity\n ↓\nNeed Detection\n ↓\nNeed Queue\n ↓\nAuto-Tuner\n ↓\nProjection Tuning Proposal\n ↓\nPolicy / Governance\n ↓\nProjection Engine\n ↓\nWorkbench Manifest vN+1\n ↓\nRehydrate\n ↓\nObserve Outcome\n```\n\nIt may reorder, filter, group, create lenses, change information density,\nsurface capabilities and prioritize queues. It **does not mutate canonical\nSpine structure, permissions, policy or consequential execution rules**.\n\n## 47. Front-end consolidation — stable shell\n\nThe stable shell:\n\n```\nINTEGRATEWISE\n│\n├── Home\n├── My Work\n├── Inbox\n├── Tasks\n├── My Queue\n├── Approvals\n├── Notifications\n│\n├── Work\n│ └── Adaptive domain / lifecycle projection\n│\n├── Knowledge / Context\n│\n└── Platform / Administration\n```\n\nThe Twin appears contextually inside these surfaces. Clicking a task gives\nthe Twin that task, related entities, timeline, signals, memory, policy and\ncapabilities. Clicking an approval gives it the proposal, evidence,\nauthority boundary and expected write-back. Clicking an entity gives it\nEntity 360 + relationships + memory + timeline.\n\nThe older standalone pages (Home, Ask, Memory Timeline, Entity 360,\nContinuity, Governance, Connections) become a **capability/surface\nvocabulary**, not the primary application navigation.\n\n## 48. Twin — consolidated definition\n\n```\nTWIN\n=\nContext Assembly\n+ Retrieval\n+ Memory\n+ Reasoning\n+ Research\n+ Explanation\n+ Preparation\n+ Proposal\n+ Coordination\n+ Monitoring\n```\n\nIt follows the user's work instead of requiring the user to continually\nenter a chatbot.\n\n### Interaction grammar\n\n```\nOBSERVE → Store / ingest into Spine\nORIENT → Ask Your Twin\nDECIDE → Assign Your Twin\nACT → Approve Twin Action\n```\n\n### Authority boundaries\n\n```\nTwin ≠ authority\nTwin ≠ source of truth\nTwin ≠ direct UI composer\nTwin ≠ unrestricted executor\n\nSpine = truth\nProjection = presentation\nTwin = intelligence\nCapability = ability\nGovernance = authority\nRuntime = execution\n```\n\n## 49. Capability Fabric + MCP Marketplace\n\nMCP is not another product layer. The marketplace exposes the\nIntegrateWise/Spine Network into external ecosystems:\n\n```\nClaude / ChatGPT / Gemini / Cursor / VS Code / Enterprise Agent / Other MCP Host\n │\n ▼\nIW Spine Network / MCP\n │\n ▼\nIdentity + Tenant\n │\n ▼\nCapability Discovery\n │\n ▼\nCapability Resolver\n │\n ├── Native API\n ├── MCP Tool\n ├── Connector\n ├── Agent\n ├── Workflow\n ├── Memory Fetch\n ├── Local Runtime\n └── Tool → Tool\n```\n\nThe Workbench doesn't need to understand _how_ an operation executes. It\nrequests a capability. The resolver determines the execution path;\ngovernance determines whether it may run.\n\n## 50. Final product model — one platform\n\n```\n INTEGRATEWISE\n Governed AI Operating System for Work\n │\n ┌───────┴───────┐\n │ │\n ONE AUTH SPINE NETWORK\n │ │\n └───────┬───────┘\n ↓\n ADAPTIVE SPINE\n canonical truth\n │\n ┌────────────┼────────────┐\n ↓ ↓ ↓\n Knowledge Memory Capabilities\n │ │ │\n └────────────┼────────────┘\n ↓\n PROJECTION ENGINE\n ↓\n ADAPTIVE WORKBENCH\n ↕\n CONTEXTUAL TWIN\n │\n ↓\n CAPABILITY FABRIC\n │\n ↓\n GOVERNANCE\n │\n ↓\n ORCHESTRATION\n │\n ↓\n EXECUTE\n │\n ↓\n VERIFY + RECONCILE\n │\n └────────→ SPINE\n │\n ↓\n REPROJECT\n```\n\nThe Product Boundary Model (Entry, Product, Platform, Flows) is specified in\nPart VII §7.2.\n\n### The architectural statement\n\n> Other work platforms give the user tools for constructing a workspace.\n> IntegrateWise discovers the work, establishes the operating model in the\n> Spine, compiles the Workbench, gives the Twin the resulting context,\n> resolves available capabilities, governs execution, learns from the\n> outcome, and continuously recompiles the environment around the work.\n\n### The invariant\n\n**Every UI surface is a projection over the Spine; no surface owns its own\ndatabase. The Spine is the contract and the Workbench is the rendering.**\n\n---\n\n## Part VII — Book-of-Record Baseline (v1.1, 2026-08-06)\n\nThis section governs the implementation baseline for IntegrateWise. It unifies product\ndoctrine, runtime boundaries, storage authority, service ownership, execution contracts,\nreconciliation, security, deployment, go-live sequencing, stop-ship rules, and acceptance\ncriteria.\n\n**v1.1 delta** (reconciled from v1.0 + August 10 implementation freeze):\n\n1. Formalize `ProjectionService → ProjectionEngine → SharedWorkbench`\n2. Human + Twin as sibling consumers of composed operational context\n3. Absorb visible Cognitive Layer functions into Twin\n4. Spine Network as external AI/tool ecosystem abstraction\n5. OmniRouter inside Capability/Execution Fabric\n6. Auto-Tuner → Projection proposal → Projection Engine feedback loop\n7. Preserve all v1.0 invariants (storage, isolation, command/event, outbox,\n reconciliation, evidence, security, stop-ship)\n\n### 7.1 What IntegrateWise Is\n\nIntegrateWise is a self-organizing operational Workbench. It gives every user one place\nto understand, decide, communicate, approve, and complete their work while the connected\necosystem coordinates continuously underneath.\n\n**Core promise:** One Workbench where the human and AI work together, while the connected\necosystem operates underneath.\n\n**Governing doctrine:** Truth you own. AI you rent. Approval in between. Verification\nbefore completion.\n\n**Architectural invariant:** The Workbench is one. The Spine is one. The Projection is many.\n\n### 7.2 Product Boundary Model\n\nIntegrateWise has four explicit architectural boundaries:\n\n- **Entry** — One Auth, MCP Auth, Marketplace discovery, Installation/launch handoffs,\n Consent/permission requests, Host bridges, Workspace activation. Entry does not own\n operational truth, projections, memory, orchestration, governance, or execution.\n\n- **Product** — The Workbench. Owns personal work surfaces, communications, department\n projections, Twin interaction, AI coworker presentation, inline actions, approvals,\n evidence review, intent capture, operational status display. Does not own credentials,\n connector execution, canonical state, backend orchestration, policy evaluation, provider\n verification, reconciliation.\n\n- **Platform** — Server-side operating system underneath the Workbench. Owns Gateway,\n Identity/tenancy, Connector authority, Discovery, Business context, Projection, Spine,\n Knowledge, Memory, Continuity, Capability Fabric, ADK, Orchestration, Governance,\n Execution, Reconciliation, Evidence, Search, Notification, Audit, Observability, Security.\n\n- **Flows** — Activation, Hydration/sync, Work, Cognitive proposal, Approval, Execution,\n Reconciliation, Memory promotion, Projection refresh.\n\n**Spine Network** is the umbrella abstraction for the external AI/tool ecosystem:\n\n```\nChatGPT / Claude / Gemini / Cursor / Enterprise Agents\n │ │ │ │ │\n └────────┴────────┴───────┴─────────────┘\n │\n One Auth / MCP Auth\n │\n Tenant Resolution\n │\n Spine Network\n │\n ┌──────────────┼──────────────┐\n │ │ │\n Resources Context Capabilities\n │ │ │\n └──────────────┼──────────────┘\n ↓\n Governed Platform Runtime\n```\n\nAfter first activation, another AI host does **not** create another operational\nenvironment. It resolves the same tenant and receives governed access to the\nexisting Spine/connection/capability environment.\n\n### 7.3 Storage Authority\n\n**Dual-tier storage topology:**\n\n- **Neon/PostgreSQL** — Tenant registry, organization lifecycle, subscriptions,\n entitlements, deployment manifests, catalog management, platform policies, schema\n versions, usage rollups, tenant runtime routing metadata, provisioning state.\n- **D1 (per-tenant)** — Live operational state: workspaces, users, roles, permissions,\n entities, external identities, relationships, versions, events, tasks, proposals,\n approvals, signals, communications, knowledge metadata, memory, continuity, connections,\n capability grants, execution state, projection manifests, evidence references, audit\n events, sync state, reconciliation state, transactional outbox, idempotency state.\n\n**Tenant isolation:** One-tenant-to-one-D1-database topology. Every durable D1 record\ncarries `tenant_id` for defense in depth, export portability, migration safety, and\nforensic traceability.\n\n### 7.4 Platform Runtime Services\n\nCore services behind the Gateway:\n\n| Service | Owns |\n| ---------------------- | ------------------------------------------------------------ |\n| IdentityService | Users, memberships, roles, permissions, session validation |\n| TenantService | Tenant lifecycle, provisioning, subscriptions, entitlements |\n| MarketplaceService | Connector/plugin/MCP catalog, versions, publication |\n| IntegrationService | Tenant connections, OAuth lifecycle, health, sync cursors |\n| DiscoveryService | Signal discovery, schema discovery, dead-letter routing |\n| BusinessContextService | Effective user context, communication/calendar context |\n| ProjectionService | Projection manifests, views, execution, invalidation |\n| SpineService | Canonical entities, external identity mapping, relationships |\n| WorkService | Tasks, work items, assignments, queues, dependencies |\n| CapabilityService | Capability definitions, versions, grants, invocation auth |\n| GovernanceService | Proposals, approvals, policies, human decision records |\n| ExecutionService | Capability invocations, provider dispatch, retries, failures |\n| ReconciliationService | Expected/observed state, verification, compensation |\n| MemoryService | Memory entries, scopes, promotion, consolidation, retention |\n| ContinuityService | Agent sessions, continuity ledger, checkpoints |\n| EvidenceService | Evidence snapshots, R2 artifacts, integrity, signatures |\n| SearchService | Tenant-scoped search across D1/Vectorize/AI Search |\n| NotificationService | Notification delivery, user preferences |\n| AuditService | Immutable audit events, usage telemetry, cold archive |\n| ObservabilityService | Logs, traces, metrics instrumentation |\n\n**No service reads another service's database tables directly.**\n\n### 7.5 Command and Event Contracts\n\n**Governed Command Envelope** — Every mutation enters through one governed command envelope:\n\n```typescript\ninterface PlatformCommand {\n commandId: string;\n commandType: string;\n tenantId: string;\n workspaceId?: string;\n actor: { actorId: string; actorType: \"user\" | \"agent\" | \"system\" | \"mcp_client\" };\n target?: { entityId?: string; entityType?: string };\n payload: TPayload;\n origin: { channel: \"workbench\" | \"connector\" | \"mcp\" | \"workflow\" | \"agent\" };\n evidenceRefs: string[];\n confidence?: number;\n requestedAt: string;\n idempotencyKey: string;\n}\n```\n\n**Platform Event Envelope** — Every asynchronous event uses a common envelope:\n\n```typescript\ninterface PlatformEvent {\n eventId: string;\n eventType: string;\n eventVersion: number;\n tenantId: string;\n workspaceId?: string;\n aggregateType?: string;\n aggregateId?: string;\n causationId?: string;\n correlationId: string;\n commandId?: string;\n actor?: { actorId: string; actorType: \"user\" | \"agent\" | \"system\" | \"mcp_client\" };\n payload: TPayload;\n occurredAt: string;\n producer: string;\n}\n```\n\n**Transactional Outbox** — Domain mutation and event publication write atomically to:\nDomain record + evidence/source link + local audit event + `event_outbox`. The outbox\npublisher sends events to Cloudflare Queues.\n\n### 7.6 Projection Contract\n\nThe Workbench never reads raw D1 tables. Every read goes through ProjectionService.\n\n**Canonical composition chain:**\n\n```\nProjectionService (platform service boundary)\n │\n └── Projection Engine (canonical composition engine)\n │\n ├── EntityAssembler\n ├── RelationshipResolver\n ├── KnowledgeEnricher\n ├── SignalEnricher\n ├── CapabilityResolver\n ├── GovernanceEvaluator\n └── ReadinessCalculator\n │\n ▼\n SharedWorkbench v1 (frozen composed contract)\n```\n\n**Projection formula:** Role + Department + Industry + Connected capabilities + Active context\n\n- Permissions + Governance policy = Projected Workbench.\n\n**Human + Twin are sibling consumers:**\n\n```\n SharedWorkbench\n │\n ┌─────────┴─────────┐\n │ │\n HUMAN TWIN\n │ │\n Work Observe\n Decide Orient\n Remember\n Understand\n Evaluate\n Recommend\n Prepare\n Propose\n │ │\n └─────────┬─────────┘\n ↓\n Capability Fabric\n ↓\n Governance\n```\n\n**Freshness states:**\n\n- `CURRENT` — Fresh projection succeeded\n- `STALE` — Cached projection returned under policy (unsafe actions disabled)\n- `FAILED` — No permitted projection available\n\n### 7.6a Auto-Tuner\n\nThe Auto-Tuner enters the projection loop as a feedback mechanism. It does **not**\ncompose the Workbench (that violates the frozen Projection Engine boundary). It\nchanges inputs/configuration to composition:\n\n```\nWorkbench Activity\n ↓\nObservation\n ↓\nNeed Detection\n ↓\nNeed Queue\n ↓\nAuto-Tuner\n ↓\nProjection Adjustment Proposal\n ↓\nPolicy / Governance\n ↓\nProjection Engine\n ↓\nSharedWorkbench vN+1\n ↓\nWorkbench Rehydration\n ↓\nMeasure Outcome\n```\n\n### 7.7 Twin and AI Coworker Model\n\nThe Twin is a persistent, user-aligned continuity layer. It is proactive but governed.\n\n**Twin may:** Prepare daily brief, surface tasks, detect pending responses, retrieve\ncontext, organize work, explain changes, draft outputs, identify risks/opportunities,\ncoordinate coworkers, propose actions, prepare evidence.\n\n**Twin may not:** Approve its own proposal, alter operational truth, execute without\npolicy, conceal origin/evidence, claim completion before reconciliation.\n\n**Do not create a separate visible Cognitive Layer.** The cognitive capabilities are\nTwin capabilities. Their backend services remain independently owned, but the user\ninteraction surface is unified through Twin.\n\nAI coworkers operate through Business Context, ADK, Capability Service, Orchestrator,\nGovernance, Execution, Reconciliation, Memory, and Evidence.\n\nAI-generated material retains origin, model or agent identity, confidence, evidence,\napproval history, and timestamps.\n\nApproval changes authority, not origin.\n\n### 7.8 Execution and Reconciliation\n\n**Canonical flow:** Intent → Business Context → Capability resolution → Governance\nevaluation → Human approval → Execution dispatch → Provider acceptance → Reconciliation\n→ Verified operational state → D1 Spine update → Evidence + Audit + Memory proposal →\nProjection refresh.\n\n**Capability Fabric v1.1:**\n\n```\nCapability Registry\n ↓\nCapability Discovery\n ↓\nCapability Resolver\n ↓\nADK / Planning\n ↓\nGovernance\n ↓\nOmniRouter\n ├── provider routing\n ├── connector/tool routing\n ├── credential refresh\n ├── tenant-safe caching\n ├── rate limiting\n └── concurrency control\n ↓\nExecutionService\n ↓\nProvider\n```\n\nOmniRouter is the execution-routing engine inside the Capability/Execution boundary,\nnot a separate architectural layer.\n\n**Reconciliation states:** pending → observing → partially_verified → verified →\nfailed → compensation_required → compensated → compensation_failed.\n\n**Invariant:** Provider acceptance is not completion. `compensated` is never presented\nas normal completion.\n\n### 7.9 Runtime Infrastructure\n\n| Technology | Use |\n| ------------------- | -------------------------------------- |\n| D1 | Tenant operational Spine |\n| KV | Session metadata, routing, rate limits |\n| R2 | Documents, attachments, evidence |\n| Vectorize/AI Search | Derived semantic retrieval |\n| Durable Objects | Live session coordination, presence |\n| Queues | Ingestion, execution, retry |\n| Workflows | Provisioning, migrations, approvals |\n| Workers AI | Edge inference |\n| AI Gateway | Model routing, usage, cost controls |\n\n### 7.10 Security and Zero Trust\n\n- Never trust hostname as authority\n- Never trust frontend-supplied tenant identity\n- Never trust frontend-supplied role or policy\n- Never trust projection hints as grants\n- Never trust provider acceptance as success\n- Never trust AI output as truth\n- Always derive authority server-side\n\n### 7.11 Go-Live Sequence\n\n1. **Contract Freeze** — Schemas, command/event envelopes, Projection DTOs, service\n ownership, MCP v1 tools, tenant routing frozen\n2. **Runtime Provisioning** — Neon registry, tenant Worker, per-tenant D1, migrations\n3. **Core Vertical Loop** — One complete path: Connector event → normalization → D1\n Spine → projection → Twin proposal → approval → execution → reconciliation → evidence\n4. **Product Wiring** — Frontend projections, tenant resolution, Workbench tasks/approvals,\n Twin context, live refresh, stale-state indicators\n5. **Marketplace and Onboarding** — Connector catalog, activation, host-projected discovery,\n onboarding bootstrap, first-use hydration, MCP v1 tools\n6. **Security and Reliability** — Idempotency, transactional outbox, immutable audit,\n evidence signatures, tenant-scoped search, fleet monitoring, Customer Zero isolation\n7. **Release Verification** — All 16 verification points from §7.12\n\n### 7.12 Stop-Ship Rules\n\nDo not release if any of the following is true:\n\n1. The Product reads D1, Neon, or provider SDKs directly\n2. Tenant authority is accepted from the frontend\n3. A tenant runtime can access another tenant's D1\n4. A connector must be reconnected for each surface\n5. Twin can approve its own proposal\n6. AI output enters operational truth without governance\n7. Execution bypasses the governed command path\n8. Provider acceptance is displayed as completion\n9. Reconciliation history is overwritten\n10. Evidence can fail while the mutation succeeds\n11. Audit events can be silently dropped\n12. Cached projections appear current without freshness metadata\n13. MCP exposes internal engine operations\n14. Search can retrieve another tenant's context\n15. Mock data replaces a failed live projection without disclosure\n16. Customer Zero state is accessible from external tenant runtime\n17. Idempotent retries can create duplicate external actions\n18. Compensation is presented as successful completion\n\n### 7.13 Acceptance Criteria\n\nThe baseline is operationally complete when:\n\n- One Auth can create a tenant and provision its runtime\n- Gateway dispatches to the correct tenant Worker\n- Every tenant Worker has its own bound D1\n- Workbench opens before full historical hydration\n- Connector Marketplace supports native, wrapped, and host-projected connectors\n- A connector connected once is reusable across authorized surfaces\n- Workbench reads use ProjectionService only\n- Every mutation uses the governed command envelope\n- Every event includes correlation and causation metadata\n- Every durable mutation writes an outbox record atomically\n- AI proposals preserve origin, confidence, and evidence\n- Human approval is cryptographically attributable\n- Execution and reconciliation remain separate stages\n- UI marks work complete only after verification\n- Memory improves continuity without replacing operational truth\n- MCP clients receive only semantic, tenant-scoped capabilities\n- Search is tenant-scoped\n- Audit and evidence are immutable and verifiable\n- Customer Zero and external tenants remain isolated\n\n---\n\n## Specification amendments (2026-08-06)\n\n[`SPEC_AMENDMENTS_v1.md`](SPEC_AMENDMENTS_v1.md) contains 15 required implementation\ncorrections. These amendments are canonical and supersede conflicting statements in all\nprior architecture documents. Key changes:\n\n1. Per-tenant D1 routing uses Workers for Platforms dispatch, not dynamic KV binding\n2. Isolation claims corrected to database-resource isolation, not physical boundary\n3. D1 fleet capacity policy added (thresholds, overflow strategy)\n4. Catalog versioning uses separate identity and release tables\n5. Idempotency persistence via `processed_commands` table in per-tenant D1\n6. Transactional outbox pattern for atomic domain-write-plus-event\n7. WorkService separated from ExecutionService\n8. Capability invocation ownership frozen between CapabilityService and ExecutionService\n9. Reconciliation model strengthened (missing transitions, observation history)\n10. Complete event envelope (`PlatformEvent` type) with required tracing fields\n11. Consistent `tenant_id` on every durable D1 record\n12. Search service renamed to Tenant-Scoped with per-tenant AI Search instances\n13. Cached projection fallback requires explicit freshness indicators\n14. Cryptographic approval semantics specified (hash chain, signing, verification)\n15. Frontend deployment target frozen (Vercel for product, Workers for platform)\n\nSupporting schemas: [`TENANT_D1_OPERATIONAL_SCHEMA.sql`](TENANT_D1_OPERATIONAL_SCHEMA.sql)\nand [`CONTROL_PLANE_SCHEMA_AMENDMENTS.sql`](CONTROL_PLANE_SCHEMA_AMENDMENTS.sql).\n\n---\n\n## Consolidation record\n\n| Before | After |\n| --------------------------------------- | --------------------------------------------------- |\n| 94 documents, 265,000 words | 1 document + 10 retained specs + 1 amendment + BOR |\n| 16 declared canonical | 1 canonical + 1 amendment + Book-of-Record baseline |\n| 6 files with \"canonical\" in the name | 0 |\n| Conflicts resolved by precedence chains | Conflicts resolved in place; evolutions recorded |\n| Drift discoverable only by excavation | Drift register, dated, in Part III |\n\n**Guiding principle.** Success is not more code or more documents. It is better thinking,\ncoherent architecture, less complexity, and a product customers genuinely adopt. If a change\nmakes this system harder to explain, it is probably the wrong change.\n\n> **Truth you own. AI you rent. Approval in between.**\n"}