Status: CANONICAL · Architecture source of truth
Authority hierarchy: This doc > AGENTS.md > package-level docs > code + tests
Version: 2.2 (v1.1 Book-of-Record reconciliation)
Date: 2026-08-06 · v1.1 implementation freeze reconciliation
Supersedes: every other document in docs/architecture/. See Appendix L.

---

How to read this document

This document is the canonical architecture source of truth for IntegrateWise
and Spine Workspace.

Other repository documents may describe implementation, operational procedures,
or scoped development rules, but must not redefine canonical architecture.

If something contradicts it, this wins — including AGENTS.md, CLAUDE.md,
and any file in docs/architecture/ not listed as Retained in Appendix K.

Seven parts, read in order or entered at any heading:

Part	Answers	Changes
I — Foundations	Why the system is shaped this way	Rarely. A change here is a major version.
II — The System	What each part owns and where the boundaries are	Slowly. Implementations improve; responsibilities do not move.
III — Reality	What is actually built, what has drifted, what is undecided	Continuously. Dated evidence, not aspiration.
IV — Consolidated Ref	Earlier consolidation (superseded by V–VII)	Historical. Do not edit — see Part V, VI, VII instead.
V — Master Reference	Product definition, vocabulary, Workbench doctrine, UI	Slowly. Design-level consolidation.
VI — Consolidated Canon	Canonical hierarchy, runtime loop, final product model	Rarely. Architectural invariants.
VII — Book-of-Record	Implementation baseline, service contracts, go-live gates	With each release phase.
Appendices	Exact tables, routes, bindings, contracts	With the code.

Recommended reading path:

1. New to IntegrateWise? Start with Part I (§1–§17) for design rationale,
   then Part VI (§44–§50) for the canonical architecture.
2. Implementing a feature? Start with Part VII for implementation contracts,
   then Part II (§18–§22) for component specifications.
3. Understanding drift? Check Part III for current reality vs. design.
4. Historical context? Part IV preserves the earlier consolidation.

A note on what this document is for. IntegrateWise accumulated 94 architecture
documents totalling 265,000 words. Sixteen were declared canonical. Six had "canonical" in
the filename. That is not a documentation problem — it is an architectural risk, because a
system whose architecture cannot be held in one head is a system whose invariants will be
violated by accident. The purpose of consolidating is to make the invariants cheap to
know.

---

Part I — Foundations

1. The problem this architecture solves

Organisations run on dozens of systems that each hold a fragment of the truth and none of
the whole. People become the integration layer: reconstructing context by hand, moving
facts between systems that disagree, and re-explaining everything to whatever AI they try.

The naïve responses both fail:

• Replace the systems. Nobody will. The switching cost is the business.
• Bolt AI onto each system. This produces one assistant per silo, each with the same
  partial view and none with authority. It multiplies the fragmentation it was meant to fix.

The architectural bet is a third path: leave the systems where they are, and build the
governed layer between them — one that owns canonical operational truth, projects it to
the person doing the work, and lets AI act only through approvals that a human grants.

Four failure modes name what goes wrong without it. Each is architectural, and each is
answered by a specific component:

Failure	Root cause	Answered by
Amnesia — the AI knows nothing today about yesterday	No canonical state to stand on; session memory that guesses	Adaptive Spine
Human API — the person bridges the tools	No capability fabric; integration done by hand	Capability Fabric + Workbench
Hallucination — confident, wrong	Reasoning without grounded operational truth	Grounded context
Babysitting — starts a task, stops halfway	No governed execution path that carries an action to completion	Governance + Hermes

2. Five commitments, and what each costs

Every durable property of this system follows from five decisions. Each is a genuine
trade-off, taken deliberately.

2.1 Truth lives outside the applications

Canonical operational state is assembled from connected systems into a store the
organisation owns, with provenance on every field.

Buys: cross-system questions become answerable; AI reasoning has ground to stand on;
the switching cost is accumulated verified memory rather than data hostage-taking.
Costs: an ingestion and reconciliation burden that never ends, and a permanent
consistency question — the Spine is eventually consistent with source systems, never
instantaneously. Every projection therefore carries freshness state, and "unknown" is a
legitimate answer the system must be able to give.

2.2 Governance is architecture, not policy

Proposal → approval → execution → audit is the physics of the system. No approval token,
no external mutation. This is not a setting, a middleware, or a default that can be turned
off; the execution path has no branch that skips it.

Buys: AI can be pointed at consequential work, because it structurally cannot act
alone. Regulation moves toward this posture, not away from it.
Costs: latency and friction on every consequential action, and a permanent design
tension with "just automate it." The tension is the product. Where it becomes intolerable,
the answer is narrower pre-authorised capabilities with thresholds — never a bypass.

2.3 Deterministic and adaptive systems are separated

Pipelines, synchronisation, normalisation and validation are deterministic. Reasoning,
planning, triage and learning are adaptive. They are different runtimes with different
authority, and the boundary between them is a hard one.

Buys: the parts that must be reproducible are reproducible. An AI failure degrades
suggestion quality; it cannot corrupt truth.
Costs: two systems where one might have seemed sufficient, and the discipline to keep
resisting "the model can just do the normalisation."

The corollary — confidence never grants authority — is the most frequently attacked
invariant in the system. A 0.99-confidence proposal and a 0.55-confidence proposal require
the identical approval to become real. Confidence describes evidence quality. It is an
input to human judgement, never a substitute for it.

2.4 One surface, composed per role

There is one Workbench. Role, department and industry select what is projected onto it;
they never create a separate product, a separate database, or a separate navigation model.

Buys: cross-functional work stays possible — one account, one person, one decision,
visible from every relevant angle without copying truth. New roles are configuration.
Costs: the projection layer carries real complexity, and there is constant pressure to
"just build a Sales app." Yielding once produces the fragmentation the product exists to
remove.

2.5 The Twin is a participant, not an authority

The Twin shares the user's surface and context, prepares work, and proposes with evidence.
It is silent by default and prefers silence to low-value commentary. It never owns truth
and never executes.

Buys: collaboration inside the work rather than chat beside it, and a trust model that
survives the model being wrong.
Costs: a less impressive demo than an autonomous agent, and a discipline that must be
enforced server-side — because in a plugin host, the reasoning model is someone else's and
cannot be trusted to respect a client-side gate.

2.6 OneAuth → Total Continuity

One connection per host. Entire ecosystem discovers. No N×M re-connections.

Today, every host (ChatGPT, Claude, DIA, etc.) requires its own set of OAuth connections.
If ChatGPT is connected to 50 apps and Claude is connected to 50 apps, the user must
authenticate separately for each host × each app. This is N×M complexity.

IntegrateWise solves this with OneAuth: a single identity entry point that hydrates the
Spine, discovers all connected apps from the host, and projects them as connectors. The
user never re-authenticates. The host's existing OAuth grants are discovered, not duplicated.

Host A (ChatGPT: 50 apps) → OneAuth → Spine → Discovery → 50 connectors projected
Host B (Claude: 50 apps)   → Same OneAuth → Same Spine → 50 more connectors projected
Host C (DIA: 3 apps)       → Same OneAuth → Same Spine → 3 more connectors projected

Total: 3 hosts, 103 apps, 3 connections (not 309)

Buys: the user connects once per host; the entire IntegrateWise ecosystem (Spine, Twin,
agents, memory, workbench) immediately has access to all data from all connected apps.
Agent-to-agent communication happens through the Spine — Claude's work is visible to
ChatGPT, and vice versa, without separate integrations.
Costs: IntegrateWise must trust the host's identity and connection grants, which means
the security boundary is at the host level, not the individual connector level. A compromised
host grants access to all its connections.

3. The kernel vocabulary

Twelve terms. Every concept in the system reduces to one of them. This is not a glossary —
it is a completeness claim: if a proposal cannot be expressed in these terms, it is either
duplicating an existing primitive or it is a major version.

Term	Definition	Owner
WORK	A human or machine is moving an objective through state	Spine
CONTEXT	The minimum relevant connected state required to understand current work	Continuity
SPINE	The canonical connected model of operational work state	Spine
CONTINUITY	Preservation and bounded transfer of relevant context across time, systems, humans and agents	Bridge
WORKBENCH	The role-specific projection of work and context presented to a human	Product
TWIN	The non-authoritative cognitive participant that consumes grounded context	Intelligence
CAPABILITY	A registered operation that may read, derive, or change work state	MCP Pool
GOVERNANCE	The authority that determines whether a capability or proposed consequence is permitted	Governance
HERMES	The execution coordinator for authorised capability invocations	Execution
SYNC	The reconciliation of resulting state across connected systems	Sync
BRIDGE	The governed exchange boundary through which an authorised consumer receives or contributes bounded continuity	Bridge
OUTCOME	The observed result of work or execution that may become new canonical state	Spine

Why these twelve and not fewer. WORK and OUTCOME are the beginning and end of the loop.
SPINE holds truth; CONTEXT and CONTINUITY carry the relevant slice of it across boundaries.
WORKBENCH and TWIN are how a human and a machine meet the work. CAPABILITY, GOVERNANCE,
HERMES and SYNC are the four stages an intention must pass through to become a real change
in the world. BRIDGE is the only sanctioned way anything crosses out. Removing any one
leaves a responsibility with no owner.

Why not more. Each additional term is a new place for two people to mean different
things. The document set this replaces contains "OS Shell," "Views," "Topic Boards," "Atlas
Spine," "Cognitive OS," and sixteen named agent personas — all of which turned out to be
existing primitives wearing new names. See Appendix J.

4. The eight laws

Each settles a class of argument permanently. When a design debate recurs, find the law
that already answers it.

#	Law	Statement	What it prevents
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
2	Context Law	The human never explains already-known work context to AI	Re-briefing; the Human API failure returning through the front door
3	Memory Law	Spine owns truth. Memory informs truth. Memory is not truth	AI-generated material silently becoming operational record
4	Authority Law	Confidence increases trust. Confidence never grants authority	Threshold-based auto-approval
5	Silence Law	Twin prefers silence over low-value commentary	Notification fatigue destroying the signal the Twin exists to carry
6	Capability Law	Workbench projects tool capabilities, doesn't duplicate tools	Rebuilding Salesforce inside the Workbench
7	Bridge Law	One platform. One boundary. Different projections	A second entry point with its own identity authority
8	Product–Platform Law	Broad underneath. Narrow at the surface	Platform capability leaking into user-facing vocabulary

Laws 1, 5 and 8 are violated by well-intentioned product requests. Laws 3, 4 and 7 are
violated by well-intentioned engineering shortcuts. Both classes are currently present in
the codebase — see §20.

5. What is frozen, and what may change

Change	Version impact
New kernel concept	Major
New runtime step	Major
New doctrine or law	Minor
New capability type	Minor
Implementation improvement	Patch
New projection	Patch
New role composition	Patch

Frozen: the product doctrine, the twelve kernel terms, the runtime sequence, the Adaptive
Spine entity contract, and the Capability Fabric model.

Not frozen: every implementation detail beneath them. The runtime sequence is an ordering
of responsibilities, not an instruction for how many services implement it. Merging or
splitting services is a patch as long as the ordering and the ownership hold.

---

Part II — The System

6. The four planes

Every service belongs to exactly one plane. A service that seems to belong to two has
conflated responsibilities and should be split.

┌─────────────────────────────────────────────────────┐
│  EXPERIENCE     User Workbench · Twin · Admin       │
│                 Knows only six nouns.               │
├─────────────────────────────────────────────────────┤
│  INTELLIGENCE   Hermes · Knowledge · Memory ·       │
│                 Signals — adaptive, no authority    │
├─────────────────────────────────────────────────────┤
│  EXECUTION      Gateway · MCP Pool · Provider /     │
│                 Integration / Task MCP — governed   │
├─────────────────────────────────────────────────────┤
│  FOUNDATION     Adaptive Spine · Identity ·         │
│                 Security · Storage · Timeline ·     │
│                 Provenance — deterministic          │
└─────────────────────────────────────────────────────┘

The Experience plane knows six nouns and nothing else: Entity, Projection, Capability,
Signal, Context, Twin. It knows nothing of OAuth, MCP, Cloudflare, provider APIs,
connector SDKs, or databases. This is Law 8 made concrete, and it is the reason the frontend
can be rewritten without touching the platform.

The Intelligence plane is the only adaptive plane. It reasons, plans and learns. It holds
no authority and writes no canonical truth. The Foundation plane is the only one that holds
truth. Execution is the only one that changes the outside world, and only through Governance.

7. The runtime sequence

Thirteen steps, frozen in order. Nothing skips a step; nothing reorders.

Configuration → Integration → Pipeline → Adaptive Spine → Workbench Composition
→ Continuity Bridge → User Workbench → Twin → Capability → Governance
→ Hermes → Sync → Promotion

#	Step	Owns
1	Configuration	Tenant schema, depth matrix, policies, runtime bindings
2	Integration	Connector installation, consent, credential references, provider bindings
3	Pipeline	Deterministic normalisation, triage routing, promotion — the only canonical writer
4	Adaptive Spine	Canonical entities, relationships, timeline, provenance, permissions
5	Workbench Composition	Role- and permission-scoped projection assembly
6	Continuity Bridge	Bounded, governed context exchange across time, systems, hosts
7	User Workbench	The single human surface
8	Twin	Grounded reasoning, drafts, proposals — never execution
9	Capability	Resolution of an intent to a registered, versioned operation
10	Governance	The hard gate. Policy evaluation, authority check, approval token
11	Hermes	The only coordinator of approved external execution
12	Sync	Reconciliation of the resulting state across connected systems
13	Promotion	Re-ingested outcome becomes new canonical state

Step 10 is the one that gets routed around under delivery pressure. It is the product, not
an obstacle to it.

The loop closes. Step 13 feeds step 4. An approved action does not end at the provider —
it returns through re-ingestion, verification and reconciliation, and only then becomes
canonical. This is why "did it work?" is answerable, and why an ambiguous provider response
must be queried and reconciled rather than retried blindly.

8. Truth

8.1 Three stores, and only one of them is business truth

The word "Spine" covers two different things that are not tiers of each other, plus a cache
that is frequently mistaken for both.

	Canonical Spine	Operational Spine	Edge cache
Answers	What is true about the business?	What is wired, and is it working?	What did we just compute?
Technology	Neon Postgres	D1	D1 + KV
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
Lifecycle	Append-only, versioned; durable fact	High-churn; reflects runtime state	Expiring
Written by	Pipeline promotion only	The service that owns the runtime object	Pipeline and Projection Engine
Read by	Workbench projections, Twin, capabilities	Activation Hub, Integration Manager, Observability	Everything, transparently
Governance	Hard gate	None needed — it holds no business truth	None — it holds nothing
If lost	Unrecoverable	Rewire and resync	Recompute

Operational Spine is the state of the machine. Canonical Spine is the state of the
business. That formulation resolves a conflation that has caused repeated confusion: the
seven operational entity types are first-class runtime objects, not a cache of anything
canonical. A SyncJob has no counterpart in Neon it could be a projection of. It is simply
a different kind of fact, with a different lifecycle and no need of a governance gate.

The edge cache is the third thing, and it is the one that must never be mistaken for either.

The operational store is a cache and a staging boundary. If an operational record matters
after its expiry, it must be promoted through the governed path. It must not be retained
merely because it happens to exist in a cache — and expiry itself never confers truth.

Aging is not promotion. This is worth stating separately because it has been proposed
repeatedly. D1/KV expiry removes or rebuilds bounded state. Canonical promotion is
evidence-, schema-, provenance-, policy- and authority-driven. A record does not become true
by surviving.

8.2 Storage ownership

Store	Owns	Never
Neon (Fortress)	Canonical entities, relationships, lineage, connector metadata, schema mappings, work, governance, audit, promoted outcomes	—
R2	Files, attachments, raw payloads, exports, immutable evidence bytes	Canonical structured truth
Vectorize / AI Search	Derived embeddings and retrieval indexes	Truth
Spine Cache	The read-optimised, policy-filtered, LLM-readable projection of Spine. The default agent read surface	Truth, and never a write target
D1	Active context, idempotency, runtime indexes, projection snapshots	Independent record
KV	Sessions, hot projections, connector state, invalidation	Truth
Credential wall (Nango)	Tenant-owned OAuth/API credentials	— the Spine stores opaque references only

8.2a Fortress is never directly exposed

Hosts, MCP clients, Workbench frontends and LLM agents reach truth through governed APIs,
MCP tools or Spine Cache projections. None of them queries Fortress storage.

Spine Cache is not an optimisation — it is a trust boundary with a specific job: make
canonical state legible to a language model without handing a model raw rows. Its
projections remove provider noise, retain provenance and canonical IDs, expose compact
summaries, carry freshness, authority and confidence, include only policy-visible
relationships, support deterministic retrieval by entity and continuity thread, and —
critically — distinguish fact from inference from proposal from memory.

That last property is what stops a model treating its own prior output as ground truth. It
is the Memory Law enforced at the read surface rather than trusted to the reasoning.

8.2b The store assignment rule

Six stores, one rule for choosing between them:

Numbers you aggregate go to Postgres. Everything else goes to the store that matches its
shape — and none of those stores is truth.

Data class	Store
Entity structured fields · KPI aggregations · counts · status · relationships · approval state · provenance	Neon Postgres
Long-form text · semantic search · similar-entity matching · Twin context retrieval · duplicate detection	Vectorize / AI Search
Attachments · invoice and contract PDFs · images and media · raw email bodies · exports	R2
Bounded active context · idempotency · projection snapshots · runtime indexes	D1
Session cache · hot projections · connector health · SLA and build flags · feature flags · invalidation	KV
Twin conversation runtime · per-subject active context · agent working memory	Durable Objects

Durable Objects are the sixth store and were previously unnamed. They hold the live
working state of a reasoning session — the Twin's conversation, the active context for one
account, an agent's in-flight working memory. That state is real, it is scoped, and it is
not truth: it expires, and anything in it that should survive must be promoted through the
governed path like anything else.

A caution on "Postgres/D1." Those two are not interchangeable and must never be written
as one tier. Neon is canonical. D1 holds a bounded, rebuildable projection of it. A KPI
may be computed into D1 as a cache; a KPI may not live in D1 as its record. The same
applies to "live entity state" in KV — a cached current value is fine, an authoritative one
is a violation of §8.1.

8.2c Memory is interpreted truth, in four scopes

Memory is neither canonical nor operational. It is interpreted — derived from canonical
facts and session evidence, carrying confidence and provenance. That is precisely why it
needs a governance gate that neither Spine requires: an entity is observed, but a memory is
concluded.

Scope	Boundary	Governance	Store
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
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
Conversational	One session or thread. Ephemeral working context	Decays; never promoted directly	conversational_memory
Organisational	Tenant-wide interpreted truth	Governed: staging → approved → published	org_memory

Scope only ever widens through promotion, and promotion is always governed.
Conversational and Agent memory are evidence, not truth. Personal memory never widens at
all — it can only be cited by the user who owns it.

That last rule is stronger than a privacy preference. If personal memory could be promoted,
every private note becomes a candidate for organisational truth, and the hard boundary that
makes the scope usable at all disappears.

8.2c-i Triage classifies. The Promotion Gate governs.

Evidence                       Interpretation          Truth
────────                       ──────────────          ─────
conversational_memory  ┐
agent_memory           ├──► TRIAGE ──► candidate ──► PROMOTION GATE ──► org_memory
session events         │    classify                 govern             staging → approved
canonical entities     ┘
                                                          │
                                        personal_memory ──┘  never promoted;
                                                             widened only by its owner

These are two responsibilities and they must not merge. A classifier that can also approve
is not a gate. Triage may receive, validate, classify, redact, deduplicate, link,
quarantine and stage. It may not decide that unverified material has become organisational
truth; it decides only where a candidate goes for review.

Automation may reach staging. It may never reach approved. This is the defensible
middle between "every extraction needs a human" and "high confidence auto-approves": the
system does the sorting, a human does the deciding, and material sitting in staging is
not available to Twin reasoning until approved. Approval automation without approval
bypass.

This is the Authority Law again — confidence never grants authority — expressed at the
memory layer. It deserves to be a test, not a comment: no promotion path may write
governance_state = 'approved' without an approver identity.

8.2c-ii The same separation governs learned behaviour

Behaviour learns through an evidence pipeline, never by direct mutation of an agent:

observation → candidate → suggested → shadow → approval → active
                                                   ↓
                     remain · return to shadow · suspend · retire

An agent may move a pattern to candidate or suggested. An agent may never promote a rule
to approved_autonomous. Autonomy is granted by policy, never inferred by the agent that
would exercise it — the Authority Law applied where it is most often violated.

Shadow rules evaluate against live opportunities and take no action. Proactive rules may
propose but perform no external write. Autonomous rules execute only a fixed, approved rule
version inside a declared envelope — action types, entity types, rate ceiling, value at risk,
freshness requirement, approval expiry, emergency disable — and drift suspends them without
a code deploy.

Confidence is six things, and one number must never represent all six: pattern confidence ·
prediction confidence · input completeness · data freshness · historical precision · policy
eligibility. Small samples use a named conservative lower bound, not raw accuracy — 3/3 is not
better evidence than 470/500.

Detail: Edge Conditions and Governed Learning
Spec §9–§12.

8.2d The enrichment pipeline

Normalisation makes data canonical. Enrichment makes it retrievable. They are different
passes with different failure modes, and conflating them is why "the search is bad" and "the
data is wrong" get diagnosed as one problem.

Entity created or updated in Neon
        ↓
Extract text from structured fields + linked R2 content
        ↓
Chunk (512 tokens, 50 overlap)
        ↓
Embed into Vectorize
        ↓
Link related entities into the relationship graph
        ↓
Extract key concepts onto the entity
        ↓
Write the embedding reference back onto the entity in Neon

One canonical write triggers the pass. The Twin then reads Vectorize for context and Neon
for structured truth, and the user never learns which store answered — which is the point,
and also the reason the two must never disagree about what is authoritative.

8.2e Cross-source canonical records

Some canonical entities are assembled from several providers at once. An invoice is the
clearest case: billing tool, payment gateway, subscription platform and usage platform each
hold a fragment, and the canonical record carries references to all of them.

Those links are established by the pipeline, never by a user. A human manually asserting
that two provider records are the same object is exactly the identity-resolution decision
that must be deterministic and provenance-bearing — and if it is ambiguous, it blocks rather
than guesses.

8.3 Write authority

Pipeline promotion through Governed Spine Writers
= the sole canonical commit path

The browser, the Twin, connectors, the public MCP, the Normalizer, Triage and the Projection
Engine never write Neon directly. Not "should not" — the credential boundary is meant to
make it impossible. (Today it is not; see §20 S8.)

No dual-write. Ever. Nothing writes synchronously to both the Spine and a projection. The
canonical mutation, its field lineage and a transactional outbox event commit in one
database transaction; every projection is an asynchronous consumer of that event.

┌─ one Spine transaction ─────────────────┐
│  canonical mutation                      │
│  field lineage                           │
│  outbox event                            │
└──────────────┬──────────────────────────┘
               ↓ at-least-once, idempotent consumers
   Brain · search · vector · signals · Workbench · org-memory cache

Delivery is at-least-once with stable event ids, monotonic entity versions, backoff with
jitter, dead-letter queues and reconciliation. The architecture does not claim cross-store
exactly-once delivery — any document that does is wrong.

This is the structural fix for the whole class of defect in §20: a projection that is written
directly becomes a second writer, and a second writer becomes a second source of truth. It
closes S0b and M1 — Neon memory.org_memory is the store, the D1 table is a
projection, and the promotion gate is its only writer.

Detail: Edge Conditions and Governed Learning
Spec §2.

8.3a Uncertainty is a value, not an absence

unknown · unresolved · insufficient_data · conflicted · stale · failed are valid
persisted states. The platform never converts uncertainty into a guessed canonical value.

This applies at three levels, and all three are required:

Level	Carries
Field	normalizationStatus: valid · coerced · invalid · missing · conflicted — with rawValue preserved whenever coercion fails
Identity	resolution_status and canonical_status; an unresolved entity is provisional and not eligible for automation
Response	state (§11.4) and completeness — orthogonal, both required

Two rules that follow and are violated often:

An unknown enumerated value maps to unknown, never to the nearest known value. Nearest-
match is how a system quietly invents facts.

Null, blank and absent are three different things. Collapsing them destroys the difference
between we know it is empty and we never asked.

8.4 The entity contract

Every canonical entity owns seven properties. This is frozen:

Property	Meaning
identity	Canonical reference (id, provider, tenant)
fields	Structured attributes
relationships	Connected entities
timeline	Temporal history
provenance	Source and lineage
permissions	Access governance
capabilities	Available operations

Provenance is not metadata. It is the reason any number on a Workbench can be traced to the
system and field it came from and the time it last changed — which is what makes grounded
reasoning possible and hallucination structurally harder.

8.5 Schemas are entity-based; experience is projection-based

A persisted record represents a business or platform entity, relationship, event, evidence
artifact, policy, capability, execution, versioned definition or runtime record. A table is
never created because a sidebar label exists. There is no canonical home, inbox,
finance-manager or view-n table. Those are projections.

Role, department and industry are projection dimensions, not storage partitions. This is
the single most load-bearing storage decision in the system: it is what preserves
cross-functional work. One account, person, task, document, risk, decision or outcome is
projected into every relevant view without its truth being copied into a departmental
database.

Storage rules:

• One shared public schema; tenant-owned truth in tenant-scoped rows, not tenant-specific schemas
• Each canonical entity type in its own table, with its own opaque primary key
• tenant_id mandatory on every canonical row, relationship, event, cache entry and evidence link
• Every entity carries a classification address: app_category → business_domain → lifecycle_stage

8.6 The scope envelope

Concern	Field	Meaning
Isolation boundary	tenant_id	The owning tenant. Always required.
Tenant operating account	tenant_account_id	The tenant's root account identifier
Tenant Spine Network	spine_network_id	Groups the entity graph, connector bindings, events and projections
Workspace context	workspace_id	Optional active scope; never replaces tenant_id
Entity identity	<entity>_id, canonical_id	Row identity and merge identity
Connector install binding	connector_binding_id	The user/tenant/provider-workspace installation
Connector connection	spine_connection_id	Lineage of one provider connection
Traceability	trace_id, correlation_id, source_flow	The end-to-end route

spine_network_id and spine_connection_id are not interchangeable. The first is the
tenant's network root, required for cross-connector grouping. The second is the lineage of
one connection inside it. A tenant network has many connections and also holds user-created,
imported and governed entities that belong to no connection.

spine_users are authenticated product users. A business person or contact is a canonical
entity with a person subtype. Conflating them is a recurring bug class.

9. The four flows

Everything entering the system is classified into one of four flows, and only two can create
truth.

Flow	Carries	Canonical boundary
A — Structured operational data	Entities, typed fields, relationships, metrics, events, status, ownership, lifecycle	Deterministic normalisation prepares candidates; governed writers commit
B — Documents and communications	Threads, messages, meetings, calls, documents, attachments, transcripts, evidence	Raw artifacts preserved; extracted meaning retains lineage; promotion uses governed writers
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
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

Flow C is where every well-meaning shortcut wants to live. "Let the model write it,
we'll review later" is precisely what this partition exists to prevent.

Flow D runs first. It is not a peer of A, B and C — it is their precondition. Nothing can
be classified, scoped or written until identity, tenant, workspace, consent, connection binding
and capability grants have resolved. An observation arriving before Flow D has no tenant, and a
record without a tenant cannot be written; it fails closed.

Flow D is not the execution path. An approved effect follows
Capability → Governance → Hermes → provider → outcome → re-ingestion → reconciliation → promotion. Flow D supplies the authority and binding context that path runs under; it does
not turn external execution into platform-binding data. (This is a recorded post-lock
correction: Architecture Lock v1.0 described Flow D as approved external actions. v1.1
corrected it.)

9.0a Three things arrive from an AI, and they are not the same thing

Conflating them is the most consequential modelling error at the host boundary.

What the AI produced	It is	Destination
Tool result — it invoked an app and got records	Evidence	Flow A or B, via Loader → Normalizer
Model output — reasoning, summary, conclusion	Interpretation	Flow C — candidate only
Requested action — "send this", "update that"	Intent	Not a flow. The governed execution path; its outcome re-enters as A/B

The sharpest case: when a host's model reasons over IntegrateWise data and reaches a
conclusion, that conclusion is Flow C. It does not become organisational truth because a
capable model asserted it, and it does not become truth because its confidence was high. The
reasoning is rented; the truth is owned; the gate between them is ours.

Detailed channel mapping:
Marketplace Channels and Data Flow Spec.

9.1 Normalizer and Triage are separate runtimes

	Normalizer	Triage
Nature	Deterministic	Adaptive
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
Authority	None — prepares candidates	None — cannot self-authorise or auto-promote

Neither commits. Loader Runtime is the sole outer ingress controller; Governed Spine
Writers / Pipeline promotion are the only modules that commit canonical truth.

10. Capability, Governance, Hermes — the execution path

10.0 Capability has three effect classes

One kernel term, three effect classes. Every registered capability declares which it is, and
its governance requirement follows deterministically — it is not a judgement call at
invocation time.

Effect class	Does	External effect	Governance	Examples
read	Retrieves state from a system of record	None	Policy scope only	Fetch an opportunity, list messages
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
mutate	Changes external or canonical business state	Yes	Proposal → policy → approval token → receipt → reconciliation	Send an email, update a CRM record, create an obligation

This resolves a conflation that ran through the whole prior document set. The Capability
Law reads "Workbench projects tool capabilities" — the word "tool" was already there,
which means the doctrine only ever governed provider operations and left the cognitive half
of the system unnamed. Fourteen of the nineteen public tools are derive or read:
get_context, get_related, get_permitted_memory, get_relevant_knowledge, ask_twin.
Those are the product. They now have a declared class, a governance rule, and a home.

Two consequences worth stating:

A derive capability produces candidates, never facts. Its output enters Flow C. It
reaches canonical truth only through Triage, a promotion record and the applicable approval.
This is the Memory Law expressed as a capability property rather than a convention.

Only mutate requires an approval token. Reads and derivations are bounded by policy
scope, not by approval. Requiring approval for a memory lookup would make the gate
meaningless through overuse.

10.1 The path

Twin or user intent
→ capability resolution          (what operation is this, at what version)
→ immutable execution plan       (parameters fixed; nothing may change after this)
→ Governance policy + evidence   (is this permitted, by whom, with what evidence)
→ explicit human approval        (when required)
→ approval token
→ Hermes                         (the only coordinator of approved execution)
→ provider connector / MCP capability
→ source-system result
→ Pipeline normalisation
→ promoted outcome in Neon
→ projection invalidation

Governance route and execution route are separate decisions. This is the correction
that makes multi-host deployment possible. Whether an action is permitted, and where it
runs, are answered independently:

• The governance route is invariant. Canonical entity resolution → policy evaluation →
  proposal → approval or confirmation → route resolution → execution → receipt capture →
  reconciliation into Spine. Every material write passes through all of it.
• The execution route is resolved per operation. A write may execute through a
  host-native tool or through the IntegrateWise Capability Fabric. Both produce the same
  canonical receipt structure and both reconcile into the same Spine.

Hermes orchestrates — it plans, sequences, tracks, retries and reconciles, and it
coordinates host-native handoffs as readily as IntegrateWise connectors. It is not the sole
executor. What is invariant is the governance path and the receipt, not the transport.

Three properties make this trustworthy rather than merely orderly:

The plan is immutable. Once prepared, the parameters are fixed. What is approved is
exactly what executes — there is no window between approval and execution in which the
action can change.

A host confirmation is not an IntegrateWise approval. If the host prompts the user and
the user accepts, policy evaluation has still not happened. Both may be required; neither
substitutes for the other.

No material write executes without a receipt and a reconciliation. An execution whose
outcome is unknown enters reconciliation. It is never retried blindly and never assumed
successful.

10.2 Capability Fabric

Capabilities are registered, versioned, discoverable operations. The pattern is
Registry → Resolver → Health → Routing → Versioning.

pool.register(manifest, targetBinding);
pool.resolve({ capability, version });
pool.invoke({ capability, version, args, context });
pool.health();
pool.capabilities();

The Workbench projects capabilities; it does not implement them (Law 6). A capability
catalogue or executor built inside the Workbench is a Law 6 violation regardless of how
convenient it is.

10.3 What "hard gate" means

• No approval token → no external mutation. There is no branch that skips this.
• Fail closed. A missing binding, an expired credential, an ambiguous scope: all fail closed.
  A governance gate that degrades to "proceed" is not a gate.
• Enforcement is server-side at the Gateway. This matters most in a plugin host, where
  the reasoning model belongs to ChatGPT or Claude and cannot be trusted to respect a
  client-side gate. The plugin channel is the case that proves why the rule must hold
  everywhere.
• "Until successful" is policy-bounded retry, never unbounded. Ambiguous remote outcomes are
  queried and reconciled before any mutation is repeated. Exhausted work goes to dead letter
  and governed reprocessing — never blind replay.

10.4 The event envelope and reliability

Every ingress — webhook, polling, streaming, API, MCP, user or agent — normalises to one
tenant-scoped event envelope carrying event type and version, trace, correlation, causation,
idempotency key, subject, source and provenance.

Validate → archive raw evidence → publish immutable event
→ queue / stream → process → resolve capability → govern → Hermes
→ provider outcome → re-ingest → verify → reconcile
→ Pipeline promotion → projection invalidation

That one envelope is what makes the rest of the system uniform: a Slack webhook, a scheduled
Salesforce sync and a Twin-proposed action all become the same shape before anything
downstream sees them. Six guarantees are mandatory rather than best-effort — event
bus/queues, idempotency and deduplication, webhook and polling security, policy-bounded
retry and replay, sync and reconciliation, and end-to-end traceability with structured
logging and SLOs.

Two rules deserve emphasis because they are where distributed systems usually fail quietly:

An ambiguous provider outcome is a question, not a retry. If the system cannot determine
whether a mutation succeeded, it queries and reconciles before repeating. Retrying an
ambiguous write is how one approved action becomes three emails.

Exhausted work goes to dead letter and governed reprocessing. Never blind replay. A
replayed action is a new action and re-enters the governance path.

11. Projection and the Workbench

11.1 The composition contract

VIEWER DIMENSIONS          who is looking
  authenticated identity · tenant membership · role and permissions
  department · industry · policy and entitlement · preference

SUBJECT DIMENSIONS         what is being looked at, and what qualifies it
  the entity in focus · its business context · its lifecycle stage
  its relationships and evidence

SYSTEM DIMENSIONS          what is currently possible
  connector / schema / capability availability · freshness
                              ↓
                      Projection Engine
                              ↓
                        SharedWorkbench

Prior versions of this contract listed only viewer and system dimensions. That omission is
the subject of §11.1a.

The Projection Engine is the sole composer of SharedWorkbench. The Workbench never
queries provider-specific data models and never constructs its own KPI truth. Gateway
derives authority from the identity provider; browser-supplied tenant, user, role or
permission values are non-authoritative and are rejected.

11.1a Context that qualifies is a dimension, not a destination

A recurring modelling error, worth a test because it will happen again.

Business Context is a canonical entity family — business_model, market_position,
operating_environment, key_business_challenges, strategic_priorities_current_year,
digital_maturity, it_complexity_score, legacy_system_count, cloud_strategy,
data_classification. It is one row per account. It is a declared entity type in
packages/types, it has migrations, and it has its own view file.

And it appears in exactly one projected view — the quarterly business review, as "Section 1."
Every operational surface where a decision actually gets made omits it.

That is backwards, and the cost is concrete. Consider an identical operational signal:
health 42, renewal in 18 days, two unresolved P1 tickets.

Business context	What the signal probably means	Right next action
leader · cloud_native · optimizing · Cloud-first	They have outgrown the current configuration or found a gap	Product and roadmap conversation, executive-to-executive
follower · on_premise · initial · 40 legacy systems	They cannot absorb what they bought	Enablement and adoption plan, hands-on

Same numbers. Opposite actions. A Twin reasoning without business context will confidently
recommend the wrong one, and will do so with evidence — because the evidence is real; only
the interpretation is unqualified.

The test. If an entity is one-to-one with its parent, is never usefully listed on its
own, and changes how other entities should be read — it is a projection dimension, not
a destination. Dimensions travel with the subject into every view. Destinations are places
you go.

Business Context, lifecycle stage and industry classification are dimensions. Accounts,
tasks, risks and engagements are destinations. Giving a dimension its own page and stopping
there is how the why gets separated from the what — and the whole product proposition is
that they arrive together.

Consequence for the projection contract: the subject's qualifying context is composed
into every projection about that subject, at the depth the surface warrants — a one-line
qualifier on a list row, a panel on an entity view, the full record on its own page. It is
not a page the user is expected to visit first and remember.

11.2 One surface

There is one Workbench, one sidebar taxonomy, and one URL namespace. RBAC projection
determines which items are present and whether the user may read, operate or administer
them.

The user-facing centre of gravity is work, not ontology. Users do not arrive to browse
teams, projects, assets and signals as destinations. They arrive to answer:

• What needs my attention?
• What is blocked?
• What is waiting for approval?
• What changed?
• What can my Twin help with next?
• Which records, conversations, documents and entities explain that work?

Entity families remain essential — as supporting truth behind the operational experience,
not as the primary product noun.

Home
My Work          Inbox · Tasks · My Queue · Approvals · Notifications
                 Recent Work · Favorites
Communications   Activity Feed · Email · Calendar · Meetings · Chat
                 Calls · Documents Shared
Personal         Notes · Knowledge Base · Brainstorming Sessions · Activity
Work             ← computed: Role × Department × Industry
Platform         ← computed: Profile (§15)
Administration   Organizations · Users · Roles · Permissions · Audit · Billing

Three things are true of this structure and worth stating:

The Twin is absent, deliberately. It is not a sidebar entry, because it is not a
destination (Law 1).

Only Work and Platform are computed. Everything above them is a constant for every
user, role and profile — which is exactly what makes the structure durable.

Platform is one destination, not twenty-two. It opens a settings-style module index
within the Workbench shell. Twenty-two top-level entries would make the Workbench a
launcher for twenty-two workspaces, contradicting "one surface" — and would be unrenderable
in a constrained plugin surface, which forces the same conclusion independently.

11.3 Canvases and organisational memory

A canvas is a first-class projection surface, not decoration around a table browser. It may
compose document-like blocks, linked entity cards, embedded tables, decision logs,
timelines, policies, KPI strips and source references — all filtered by RBAC and the active
projection contract.

Organisational memory is a projection family, not a store. It behaves like the company
operating handbook: the front door for promoted knowledge, decisions, rituals and canonical
references. It is backed by memory, knowledge, documents, events and approved outcomes;
it owns no separate truth store.

11.4 Required response shape

Every semantic response carries: contract version, request/trace identifier, tenant and
permission scope, generation and freshness time, provenance, and exactly one state:

ready · partial · degraded · pending

It separately carries a completeness level — host-local, partial or canonical —
with the list of missing systems. These are orthogonal: a response can be ready and only
host-local complete. Any answer claiming cross-system completeness must report
canonical, or disclose exactly what it could not see.

This is the honesty mechanism that makes a host deployment safe. "Summarise my unread mail"
answered from the host alone is a correct, useful, host-local answer. The failure mode is
not incompleteness — it is undisclosed incompleteness.

A live failure never silently becomes seed or demo data. A projection cache miss returns
an explicit partial-evidence state. Mock and fixture data are Development-only. This is a
stop-ship invariant, because a system that quietly shows fake numbers has broken the only
promise that matters.

11.5 Roles and the projection matrix

Twelve roles × departmental modules is the composition space. A role is not a product — it
is a selection over the same Spine, expressed as a RoleConfig with a projection binding.

Adding a role is a patch: a new composition over existing entities and capabilities. If
adding a role requires a new table, a new service or a new user-facing noun, the role is not
the problem — the model is, and the request should be refused until that is understood.

The Work group resolves through Role × Department × Industry. Twelve roles by roughly
twelve departments by N industries cannot be enumerated as static configuration; the industry
axis must be derived from the tenant's activated Spine schema. See open decision
D3.

11.6 The auto-tuning boundary

The system may adapt to a user without asking. The boundary on that is precise, because
"the system learns" is otherwise indistinguishable from "the system changed something you
did not authorise."

Auto-tuning is a bounded internal mechanism assembled from Configuration, Projection,
Governance, telemetry and runtime policy — not a new service. It may propose or reversibly
apply low-risk changes: personal view order, density, prefetch, cache, notification ranking,
capability placement.

It may never silently mutate the canonical schema or truth, change permissions, authority or
governance thresholds, promote institutional memory, enable a provider or connector scope,
modify shared structures without the required approval, or remove the stable Workbench
taxonomy.

The dividing line: personal and reversible may adapt; shared and consequential requires
approval.

12. The Twin

12.1 Two modes

Passive. Continuously aware, never continuously reasoning. It observes pipeline events,
Spine changes, the current surface and entity, user actions, OODA state, approvals and
outcomes. Only a material signal produces a small contextual surfacing: "Renewal risk
detected." "Connector sync failed; account data may be stale." Passive mode does not open a
panel, generate long analysis, or compete with the user's work.

Active. On explicit invocation — or a material signal that passes the Silence Law — the
Twin escalates to grounded reasoning over the current surface, the current and related
entities, the subject's business context, the Spine projection with timeline and
provenance, pipeline freshness, OODA state, evidence, connected-system context, and
organisational memory. It produces an evidence-backed recommendation. It never decides.

Business context is load-bearing in that list, not decorative. It is what separates what
happened from what it means here — see §11.1a. A recommendation grounded in operational
facts alone is defensible and frequently wrong.

12.2 Active Context hydration is not Twin activation

Every material navigation refreshes the permitted context slice: selected entity and
relationships, visible fields, filters, linked records and documents, freshness and connector
availability, allowed capabilities and governance posture.

This is hydration, not activation. A click is context, not authority. A normal click does
not open a panel, run expensive reasoning, or convert navigation into an OODA Act. Visible
Twin output occurs only when the user invokes a button, a material signal passes the Silence
Law, or an approved assignment requires monitoring.

12.3 The four controls

The entire user-facing action grammar. Everything else is ordinary product interaction —
navigating, editing a record, logging activity.

OODA	Button	User intent	Platform behaviour
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
Orient	Ask your Twin	Understand the current work	Twin reads the surface and bounded context, reasons over Spine, evidence, connected systems and memory
Decide	Assign your Twin	Delegate a bounded task	Twin produces a draft, analysis or proposed action. No external execution
Act	Approve Twin's Action	Authorise a proposal	Governance validates; the authorised capability is invoked through Hermes; the result reconciles back to Spine

The Twin participates in the system loop only at THINK:

LOAD → NORMALIZE → STORE → THINK (Twin) → APPROVE → ACT → REPEAT
                             ↑              ↑
                    Store in Spine    Approve Twin's Action
                    Ask your Twin     Assign your Twin

13. Continuity and the Bridge

Continuity is the preservation and bounded transfer of relevant context across time,
systems, humans and agents. The Bridge is the only governed boundary through which it moves.

This is the answer to Amnesia, and it does more work than it first appears to. Three
transfers matter:

Across time. Tomorrow's session starts from today's canonical state, not from zero.

Across people. A handover transfers the context slice the recipient is permitted to
receive — not a document someone remembered to write.

Across hosts. When an agent in one host needs a system that host cannot reach, the gap
is filled by Spine completion — canonical context the Spine already holds, or an
IntegrateWise-managed connector to that system. It is not filled by brokering to another
host's connection.

This distinction matters and is easy to get wrong. IntegrateWise does not reach into
ChatGPT to borrow Claude's Salesforce token, and could not: connection tokens remain inside
their owning trust boundary and no credential is copied between host and IntegrateWise
merely to unify routing. What actually happens is that IntegrateWise holds its own canonical
Salesforce state and, where needed, its own governed connector — so the ChatGPT-side request
is answered completely without Salesforce ever being connected to ChatGPT.

The architectural claim, stated precisely: the Spine is the completion layer, and
therefore the interop substrate between hosts. There is no agent-to-agent protocol between
ChatGPT and Claude, and there does not need to be. Each host talks to the Spine; the Spine
supplies what the host lacks. Adding a fourth host is an adapter and a catalogue entry — not
an N×N integration, and not a credential-sharing arrangement.

14. Identity, tenancy and isolation

Layer	Contract
Browser identity	Descope is the identity authority
Authority derivation	Gateway validates the session and resolves tenant membership; injects trusted identity headers downstream
Browser claims	Non-authoritative. Tenant, user, role and permission values from the browser are rejected
AI / MCP consumers	Public OAuth-protected MCP boundary
Provider credentials	Tenant-owned, held in the credential wall. Never in a product repository, a projection, or an AI prompt
Tenant scope	Mandatory on every canonical row, relationship, event, cache entry, evidence link and runtime operation

Stale, ambiguous, revoked or expired bindings fail closed and are removed from sync,
projections, Twin context, capabilities and execution.

15. Three axes: Profile × Entry Channel × Surface

Three orthogonal things were previously collapsed into the word "profile," producing a
2×2 that could not represent development and could not represent tool-initiated onboarding.
The resolution is to stop storing the product of the axes and store the axes.

15.1 Profile — which capabilities exist, and who may administer

development · customer_zero · external

This is a property of the runtime a tenant is served by, not of the tenant.

Only five modules vary by profile:

Module	development	customer_zero	external
MCP Pool (admin UI)	full	full	not exposed
Capability Manager	all + experimental	all governed	tenant-permitted subset
Administration	full	full	tenant-scoped
Billing	bypassed	internal accounting	live metering
Deployments	full	full	not exposed

Everything else is identical across all three. Identity, Integration Manager, Connector
Marketplace, Activation Hub, AI Models, Knowledge, Memory & Continuity, Automation,
Pipelines, Governance, Observability, Organizations, Users, Roles, Permissions, Audit, API
Keys and Security vary by tenant scope, which RBAC already handles. Adding profile
branches to them invents variance that does not exist and creates eighteen new drift sites.

This table is resolved server-side at the Gateway and returned in the capability
manifest. The frontend never computes it and never receives definitions for modules the
profile excludes.

On MCP versus MCP Pool. They are two different jobs, not two sizes of one thing.
Verified at HEAD: services/mcp-pool/src contains zero of the 19 semantic tools — it
exposes five lifecycle verbs (register, unregister, capabilities, health, invoke)
over nine platform-management namespaces. A profile running on Pool could not use
IntegrateWise; it could only administer it. The public MCP surface is therefore
byte-identical across all three profiles. MCP Pool is an operator control plane — register, unregister, capabilities,
health, invoke — whose administration UI is exposed only in development and
customer_zero. Pool is never a tool surface and never a per-profile alternative to MCP.
If Customer Zero ran on Pool while external ran on the public surface, Customer Zero would
stop proving the external contract, which is its entire purpose.

15.2 Entry channel — where identity comes from, and where UI renders

Channel	Identity source	UI surface	First connection
connected_tool	OAuth with a provider the user already holds	IntegrateWise browser Workbench	The authenticating provider
mcp_workbench	IW OAuth via MCP registry	IntegrateWise browser Workbench	Chosen in the Workbench
plugin_host	Host installation grant	Embedded surface inside the host	Host-declared, runtime-confirmed capability context

On "inherited." Earlier wording described the plugin's first connection as inherited
from the host's connections. That phrasing is retired: it reads as credential inheritance,
which is precisely what §15.4 forbids. Credentials remain inside their owning trust boundary.
Where the host cannot supply a required capability, the user creates an explicit
IntegrateWise connection. Nothing is inherited — capability is declared and then confirmed.

One onboarding state machine serves all three:

initiated → identity_required → workspace_required → consent_required
         → binding → hydrating → active
                              ↘ degraded | revoked | failed

Only identity_required and workspace_required are channel-dependent. consent_required,
binding, hydrating and active are identical for every channel. This is the
invariant that matters: the Spine write path, hydration, projection composition and
governance do not fork per channel. Fork them and you get three onboarding funnels that
hydrate differently.

Channel and provider are orthogonal. channel is one of the three above; provider is
catalogue data. Adding a new host is a catalogue entry, not a type change.

15.3 Surface — infrastructure isolation only

dev · test · prod. No product semantics. The axes are independent: Customer Zero on
test is a valid and useful combination.

15.4 In a host deployment, the host supplies the agent

IntegrateWise does not ship inference into a host. The host's model reasons. IntegrateWise
supplies the tool surface, the truth, the memory, the governance gate and the embedded UI.

Host capability is never assumed. The IntegrateWise runtime may not enumerate every app
connected to a user's host account, may not access another app's OAuth token, may not invoke
unrelated apps directly, and may not bypass the host's permission, confirmation or workspace
controls. The host orchestrates its own apps.

Host capabilities therefore enter through explicit mechanisms only:

1. Host-declared capability context supplied at app invocation
2. Tool-result handoff — the host invokes its own app and passes the resulting evidence
   to an IntegrateWise tool
3. Workflow orchestration — the host selects both its apps and IntegrateWise tools
4. Explicit IntegrateWise connection where the capability is not available through the host
5. Installation manifest or policy declaration of expected capabilities

Declared is not available. Every one of those must be validated at runtime; expected
availability is never proof of actual runtime access. A capability's availability is
confirmed, declared or unknown, and only confirmed may be routed to.

Two further rules hold:

1. Host-granted access is readable, not writable. Any mutation is a capability execution
   and passes the governance path like any other, whatever route it executes on.
2. Host evidence is still Spine-mediated. A host tool result enters as a
   RawObservation through Loader and the Normalizer Path. The Workbench does not treat a
   provider payload as truth because the host happened to hold a token.

15.5 Create once, deploy anywhere

The governing principle of multi-host deployment:

Host-first access. Spine-complete context. Policy-governed execution. Canonical
reconciliation.

One canonical Workbench and continuity runtime is built once and deployed into many hosts —
a host being any runtime the product renders in: ChatGPT, the IntegrateWise web app, Slack,
Microsoft surfaces, embedded customer applications, desktop shells, customer-hosted
environments, future agent marketplaces.

A host is an integration context, not a rendering container. A deployment must account
for the host's authenticated user, workspace, enabled integrations, granted scopes,
supported operations, confirmation model, surface limitations and runtime availability.
Treating a host as merely a place to draw pixels is the mistake that produces per-host forks.

This resolves what looked like a question about which surface is primary. Neither is.
Domain logic is primary; every host — including the browser — is an adapter.

Layer	Owns	Never
Domain packages	Canonical types, application services, projections, governance rules, capability contracts, core UI	Host specifics
Adapters	Host and infrastructure translation: identity validation, payload translation, schema enforcement, structured results	Domain policy, provider business rules, canonical schema
Apps	Assembly of deployable surfaces	Behaviour not present in domain packages
Deploy	Environment configuration	Anything that changes behaviour

No adapter may redefine canonical entities, governance policy or projection semantics. The
test is falsifiable: the same domain and application-service packages serve the web and the
host deployments, and a deployment can move between infrastructure providers without domain
logic changing.

Repository topology follows from this. The boundary between repositories is drawn by
write authority, not by distribution channel — Platform owns canonical truth and
everything permitted to write it; Product owns operational state, agent working memory and
every channel adapter. Putting two channels in two repositories would make them peers, and
peers drift: the onboarding state machine must be byte-identical across channels, and a git
boundary converts that from a compiler guarantee into a discipline. It would also make every
future host a repository rather than a folder.
Repository Topology and Migration.

15.6 Host-first is a preference, not an entitlement

A host-native route may be selected only when the capability is actually exposed to the
current session, the required scopes are present, policy allows it, the data authority and
freshness are sufficient, and the operation can produce evidence and a receipt where
required. Otherwise the Spine completes the request.

Every request is classified before it is routed. The classification determines whether Spine
enrichment is mandatory:

Scope	Spine enrichment
host-local	Optional — lightweight provenance only
entity · continuity · cross-system · governance · write	Mandatory

A strictly host-local read may stay local only when all of the following hold: the user is
asking only about the active host; no canonical entity or cross-system context is needed; no
material write is involved; policy permits it; provenance is retained; and the result does
not claim to represent complete operational truth.

That last clause is the whole safety property. "Summarise my unread mail" is a legitimate
host-local answer. "What needs my attention?" is not — it claims cross-system completeness
and therefore requires canonical aggregation.

Read precedence: confirmed host-native live capability → Spine canonical context →
IntegrateWise-managed live connector → Spine Cache or historical data → request connection →
unavailable.

This is not a sequential query plan. The resolver combines routes: mail may be host-native
while CRM and chat arrive through the Spine, in one answer, with per-source provenance.

Write precedence: resolve canonical target and policy → create proposal → determine
allowed routes → prefer host-native when confirmed and approved → otherwise Capability
Fabric → capture receipt → normalise and reconcile → rehydrate.

15.7 Connection binding — one route per operation

The same provider must not be called through both the host and IntegrateWise merely because
both are connected. One primary route is selected per operation; a secondary route may be
used for fallback, verification or reconciliation when policy allows.

Principal matching uses canonical identity, never display name. Connection tokens remain
inside their owning trust boundary — no credential is copied between host and IntegrateWise
to unify routing, and IntegrateWise stores no host credential unless the user separately
creates an IntegrateWise connection.

A binding records the provider, the canonical principal, the optional host connection
reference, the optional IntegrateWise integration, the routing preference
(host-first · integratewise-first · policy-decides), whether duplicate calls are
permitted, and the reconciliation mode.

15.8 Agent contracts

Agents are contracts, not transports. An agent definition never owns provider-specific
transport logic, and every agent invocation receives a policy-filtered Active Context
Bundle — never raw provider payloads, unless the task is explicitly ingestion or
normalisation.

Agent	Responsibility
Twin	Reasoning, synthesis, recommendations, proposal drafting
Triage	Intent, urgency, ownership and attention classification
Governance	Policy interpretation, approval requirements, risk classification
Entity Resolver	Canonical entity and identity matching
Evidence	Evidence selection, provenance checks, contradiction detection

The Active Context Bundle is the single input contract: actor and permissions, host and
session, entities, relationships, continuity, commitments, signals, decisions, evidence,
available actions, effective policy, and the completeness level with missing systems named.

Evidence carries authority (system-of-record · canonical · derived · user-supplied) and
freshness (live · recent · stale · historical) separately, because they answer different
questions. Live host evidence is authoritative only for the provider object it
represents; the Spine remains canonical for cross-system identity, relationships,
continuity and reconciled state. Four timestamps are distinguished — observedAt,
receivedAt, normalizedAt, reconciledAt — because collapsing them is how stale data
starts looking fresh.

Derived conclusions are never stored as facts. Conflicting evidence is surfaced, not
silently resolved, and a normalisation conflict quarantines the update while preserving both
records.

16. The public boundary

16.1 Nineteen tools, exactly

The public MCP surface exposes exactly nineteen semantic tools. Not eighteen, not twenty.

Context and continuity: get_my_continuity · get_active_context · get_my_focus ·
get_context · get_changes · get_related · get_history · get_commitments ·
get_decisions · get_permitted_memory · get_relevant_knowledge

Twin: ask_twin · assign_twin · get_prepared_work

Action: get_available_actions · prepare_action · get_action_plan · approve_action

Capture: store_in_spine

The internal MCP Pool, provider operations, raw table access, transport details, context
relay, agent handoff and connector implementation tools are not public. UI resources are
additive — a widget may communicate only through the host's declared bridge and cannot reach
the host DOM, cookies, credentials, Neon, provider credentials or the internal Pool.

Notice the shape of that list: eleven read tools, three Twin tools, four action tools, one
write tool. The single write tool is store_in_spine — a human observation. The four action
tools cannot execute; approve_action requires an approval that a human granted. The public
surface is structurally incapable of autonomous mutation.

16.2 Distribution names

IntegrateWise               = company and product brand
IntegrateWise Workbench     = the user's single operational surface
Workspace                   = the tenant/user environment hosting a Workbench
IW-Spine-Network            = the public distribution identity
IW-Spine-Network Plugin     = plugin-directory package (MCP app UI + skills)
IW-Spine-Network MCP        = MCP-marketplace package and remote server
IW Spine Tools              = the public 19-tool MCP interface
Adaptive Spine              = the canonical operating model and truth substrate

IntegrateWise Workbench runs on IW-Spine-Network.

Publishing to a channel publishes a channel-specific package bound to the same public
contract — never a different backend. Installing does not clone Customer Zero: activation
resolves an isolated customer tenant and applies the Customer Zero-proven reference
configuration. Customer Zero data, credentials, memory, cache, queues and audit never cross
that boundary.

16.3 Distribution — one product, three entry points

Distribution	Marketplace promise	Primary experience	Package
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
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
IntegrateWise Workbench	Operate the complete connected workspace directly	Full browser Workbench	Browser application on the same Gateway

One product:      IntegrateWise Workbench on IW-Spine-Network
Distributed via:  MCP Marketplace · Plugin Marketplace · Direct activation

These are acquisition and interaction channels, not products. Each binds to the same
tenant and workspace, the same Adaptive Spine, the same Gateway, the same 19-tool semantic
contract, the same governance path and the same Workbench composition model. Marketing them
as distinct products creates the competing-authority problem at the commercial layer that
this document exists to prevent at the architectural one.

The three marketplace surfaces have different commercial jobs:

Marketplace	GTM role	What it installs or activates	Where value appears
Plugin Marketplace	External acquisition and embedded activation	IW-Spine-Network Plugin	Focused UI, skills and approvals inside the AI host
MCP Marketplace	External acquisition and tool-first activation	IW-Spine-Network MCP	Exact 19-tool interface, fallback results, optional widgets and browser Workbench launch
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

Plugin and MCP marketplaces distribute IntegrateWise. Connector Marketplace does not
install IntegrateWise; it expands what an activated workspace can observe and govern.
Direct Workbench activation remains a non-marketplace entry path. Provider or developer
marketplaces may wrap the Plugin or MCP contract in channel-native installation, OAuth and
webhook semantics, but they do not create another product or authority.

The full GTM motion is:

Category and demand
→ Plugin Marketplace, MCP Marketplace or direct Workbench activation
→ identity, tenant, consent and workspace activation
→ Connector Marketplace connection or eligible connection reuse
→ Spine hydration and role projections
→ first grounded value
→ first approved governed outcome
→ additional connectors, roles and recurring use

The north-star metric is time to first approved governed outcome. Channel metrics support
it: listing view → install → active for Plugin and MCP, and discover → consent → bind or
reuse → healthy → hydrated for Connector Marketplace.

16.4 Acquisition to value

Discover → Install → Resolve identity → Resolve or create workspace
→ Consent → Bind capabilities and connections → Hydrate Spine
→ Compile projections → First value → Daily use
→ Propose governed action → Execute and reconcile → Expand connected systems

Activation must create or resolve, at minimum: Actor · Tenant · TenantAccount · Workspace ·
Membership · Role and permissions · SpineNetwork · MarketplaceInstallation · HostBinding ·
ConnectorBinding · SpineConnection · CredentialReference · CapabilityManifest · PolicySet ·
RoutingPreference · SchemaBindingSet · HydrationJob · ProjectionManifest.

First use must be semantic, not administrative. In the MCP channel the first interaction
should be "What needs my attention?" — and if no workspace exists yet, the activation
detour must preserve the original intent and return to it. An onboarding flow that
discards the question the user actually asked has failed at the Context Law.

16.5 Flow classification at the channel boundary

Payloads are classified individually. A single AI-host interaction spans all four flows,
and labelling the whole exchange "AI data" is the error that lets model output become truth.

#	Event	Flow
1	Plugin installed; identity, tenant, consent, bindings resolved	D
2	User asks "What needs my attention?"	C
3	Host retrieves mail messages	B
4	Host retrieves structured CRM objects	A
5	IntegrateWise supplies canonical continuity	Spine read
6	Model produces analysis and recommendations	C
7	Model proposes an escalation email	C — proposal
8	User approves	Governance
9	Host or IW connector sends it	Governed execution
10	Sent-message artifact	B
11	Delivery and status metadata	A
12	Execution receipt	Audit evidence
13	Reconciliation updates the Spine	Canonical promotion

A tool call is three things, not one:

tool request        → Flow C   (the model's intent)
provider result     → Flow A or B   (what came back)
model interpretation → Flow C   (what the model concluded)

The transport does not determine the flow. The payload's semantic responsibility does. A
Salesforce object that travelled through ChatGPT is Flow A; the sentence ChatGPT wrote about
it is Flow C.

16.6 GTM funnel mapped to runtime state

The commercial funnel and the activation state machine are the same events. Instrument once.

GTM stage	Runtime evidence
Impression	Listing viewed
Install	MarketplaceInstallation created
Activation started	initiated
Identity completed	Canonical actor resolved
Workspace activated	Tenant · workspace · SpineNetwork resolved
First connection	Confirmed host or IntegrateWise binding
Hydration started	Initial sync job created
First value	First canonical — or explicitly disclosed partial — response
Engaged	Repeated continuity and context use
Governed value	First proposal approved
Closed loop	First execution reconciled into the Spine
Expanded	Additional provider connected
Retained	Recurring cross-system use

"Installed" is not an activation metric. The first real milestone is a grounded
continuity answer produced from a resolved workspace, with provenance and disclosed
completeness. The milestone that predicts retention is first governed action executed and
reconciled.

Detail — activation envelope, per-channel journeys, read/write routing precedence, acceptance
criteria: Marketplace Channels and Data Flow
Spec.

16.7 Product and platform ownership

Product owns	Platform owns
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

No product deployment becomes a second Fortress, connector runtime, credential store,
canonical database, projection authority or provider-execution path. Product frontends may
run anywhere; they are clients of the matching Gateway. The Platform authority stays
Cloudflare-hosted.

The browser calls one typed Gateway client using one variable, NEXT_PUBLIC_IW_API_URL. The
first canonical read after sign-in or workspace switch is GET /api/v1/workspace/discovery,
returning a versioned tenant/RBAC-scoped manifest: identity and scope, projected navigation,
projection IDs and contract versions, connector and sync availability, capability and
approval availability, activation blockers, freshness and remediation.

No browser call reaches Neon, D1, KV, R2, the credential wall, a provider, Hermes or the
internal MCP Pool.

17. Environments and promotion

Environment	Purpose	Isolation
Development	Product engineering, local/preview apps, CI, disposable tests	Synthetic data; development identity, Gateway, Neon, D1/KV/R2/queues and secrets only
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
Customer Production	External customers	Tenant-scoped everything; no access to Development or Customer Zero

Promotion is one-way: Development proof → Customer Zero validation → Customer Production release. Production data, credentials and bindings never flow back.

Test and prod must never share KV namespaces, Queues, D1 databases, R2 buckets, Vectorize
indexes, Durable Objects, secret stores, or service-binding targets. Every feature completes
in three directions: development readiness, platform release readiness, customer activation
readiness.

17.1 Frozen go-live sequence

Go-live promotes the same Product and Platform versions through isolated environments. It
does not copy Customer Zero or create a separate external product.

source commit
→ CI and contract tests
→ Development artifacts
→ Customer Zero private installation
→ Customer Zero evidence
→ version freeze
→ external clean-tenant test
→ Plugin and MCP submission-ready
→ public publication

The release completes five phases in order:

1. Shared contracts: freeze the exact 19 public tools, resources, UI intents, discovery
   envelope, tenant binding contract and versioned activation profiles
2. Customer Zero Plugin: prove the private embedded UI, identity, host composition,
   explicit delegation and the governed proposal-to-reconciliation loop
3. Customer Zero MCP and Workbench: prove OAuth, exactly 19 tools, ordinary-client
   fallback, browser launch, discovery-first composition and role-based access control
   (RBAC) projections
4. Externalization: install the same artifacts into a clean tenant and prove dynamic
   tenant resolution, customer-owned connections and complete Customer Zero isolation
5. Publication: freeze compatible versions, publish the Plugin and MCP, verify a new
   tenant installation and operate governed monitoring, rollback, revocation and deprecation

Only code, manifests, definitions, schemas and versioned activation defaults cross the
promotion boundary. Tenant data, credentials, bindings, queues, caches, evidence, audit
records and runtime state never cross it.

17.2 Mandatory release gates

Customer Production release requires all of the following evidence:

• Customer Zero runs daily work through the Plugin and browser Workbench
• the frozen versions install into an unrelated tenant without code changes
• identity, tenant authority, RBAC and environment isolation pass negative tests
• the public MCP returns exactly 19 tools and supports browser launch and ordinary-client
  fallback
• one real connector passes consent, mapping, hydration, delta sync, health, revoke and
  reconciliation
• every external action follows proposal → approval token → Hermes → provider outcome →
  Spine re-ingestion → projection refresh
• observability, audit, rate limits, rollback, deletion, export, offboarding and revocation
  have live evidence
• the release manifest records compatible Plugin, MCP, frontend, Gateway and Platform
  versions

Any missing gate is a stop-ship condition. Appendix I remains the complete invariant-level
stop-ship list.

Claims about the system use one of three states, and code presence is not live proof:

State	Meaning
Defined	The contract is decided
Implemented	Repository code or migration evidence exists
Live verified	The environment has passed the required runtime and isolation tests

---

Part III — Reality

Parts I and II describe the architecture. This part describes the system as it exists on
2026-07-31, at HEAD d941a422. Both are necessary; a document that only described the
intent would be the fourteenth such document.

18. What is load-bearing

Stripped of everything unreachable:

Browser (apps/web — Next App Router)
  │
  └─► gateway ─────────── 51-entry ROUTES prefix table
        ├─ INTERNAL_*     auth · projections · billing · tenants · admin · support
        ├─► pipeline      normalise → canonical write        (Spine writer #1)
        ├─► spine         Neon canonical CRUD                (Spine writer #2) ⚠
        ├─► connector     router only ──► loader · store · mcp-connector
        ├─► mcp-connector MCP tools + OAuth authorisation server
        ├─► connector-sync scheduled provider sync
        ├─► knowledge     chunk · embed · search · synthesis · promotion gate
        ├─► intelligence  think · act · govern · agents
        ├─► workflow      (BFF) views · analytics · stream · HITL Durable Object
        ├─► iw-agent-runtime  TWIN_AGENT + TENANT_BRAIN DOs  ⚠ not in CORE_SERVICES
        ├─► mcp-pool      capability routing control plane   ⚠ shared test/prod
        └─► hub-controller-api                               ⚠ AUTH BYPASSED
  continuity              session log; reached via mcp-connector

Nine Workers are in the canonical publication path (scripts/release/deploy-platform.sh):
pipeline → connector → mcp-connector → connector-sync → knowledge → continuity → intelligence → workflow → gateway, Gateway last.

Shared code that genuinely carries weight: @integratewise/types (99 consumers),
connector-contracts (90), lib (23), connectors (18).

Everything else — 11 unbound Workers, ~14 zero-consumer packages, 2 unreachable Capability
Fabric implementations, 2 orphaned application roots, a retired GCP product, 102
_deprecated components, 5 abandoned service folders — is inert mass.

19. Scale

Layer	Count
Source files (.ts/.tsx/.js/.jsx/.mjs, build output excluded)	2,082
apps/	5 folders, 1,006 files
services/	39 folders (30 with Worker config, 5 empty, 4 non-Worker)
packages/	40 folders
Markdown	787 documents (94 in docs/architecture/)
Migration SQL	478 files across 17 independent roots

Verified against HEAD on 2026-07-31: nine CORE_SERVICES in the stated order, 51 Gateway
ROUTES entries, 12 roles in packages/workbench-config, /api/v1/workspace/discovery
present at services/gateway/src/index.ts:2313, spine absent from CORE_SERVICES.

20. Drift register

Every item is a violation of Part I or Part II, ordered by risk removed per unit of effort.
Source: CODEBASE_EXCAVATION.md, 2026-07-30.

Tier 0 — Silent data loss

S0 · The Canonical Spine does not run. Cache writes are reported as canonical
persistence.

Verified at HEAD, 2026-07-31. This is the most severe finding in the register and it is
not a design disagreement — it is a correctness defect that reports success.

The intended canonical writer, services/pipeline/src/canonical/canonical-writer.ts, is
invoked at services/pipeline/src/index.ts:1922 and services/pipeline/src/normalizer/index.ts:1097:

// index.ts — canonical write path (Neon primary, D1 edge cache)
if (env.DATABASE_URL) {
  const neonSql = (await import("@neondatabase/serverless")).neon(env.DATABASE_URL);
  const result = await new CanonicalSpineWriter(neonSql, env.CANONICAL_SPINE_DB).write(rec as any, {
    correlation_id: body?.correlation_id,
    create_relationships: true,
  });
  if (!result.success) {
    throw new Error(`[Pipeline] Canonical spine write failed: ${result.error}`);
  }
}

// normalizer/index.ts — sectorize() canonical write path
const neonSql = env.DATABASE_URL
  ? (await import("@neondatabase/serverless")).neon(env.DATABASE_URL)
  : undefined;
const canonicalWriter = new CanonicalSpineWriter(neonSql, env.CANONICAL_SPINE_DB);

The DATABASE_URL secret is bound in wrangler.toml for all environments (dev/test/prod).
Neon migration 044_canonical_spine_neon_port.sql creates the canonical tables.

The D1 binding CANONICAL_SPINE_DB is provisioned (real UUID: 1dfe12bc-27be-4c5c-976e-8da691f5dde4)
and serves as the edge cache for fast reads. It is NOT the canonical store. The Neon
DATABASE_URL is the canonical SSOT. The CanonicalSpineWriter constructor enforces this:
Neon SQL is required (first arg), D1 is optional (second arg). If Neon is not provided,
the R8 boundary guard rejects the write.

Four implementations claim Spine authority; the two that matter are not the two anyone
expected:

Implementation	LOC	Store	State
spine/src/entity-store.ts + index.ts	898	D1	LIVE — and correct. This is the Operational Spine: the seven runtime entity types
spine/src/neon-workbench.ts	558	Neon	LIVE — tenant/actor-scoped Workbench projection
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"
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.
pipeline/src/spine/index.ts	2,773	Supabase	LEGACY — self-labelled "the legacy writer", still in the release path

This inverts §S8. There are not two competing canonical writers to choose between. There
are zero working ones, plus a retired Supabase writer that still runs.

Resolution — this closes D4.

The Canonical Spine is Neon. The Operational Spine is D1. services/spine owns both
boundaries. The Pipeline is the only writer into canonical.

Steps 1–2 implemented 2026-08-20. The CanonicalSpineWriter now takes Neon SQL as
primary (required) and D1 as optional edge cache. Constructor signature:
new CanonicalSpineWriter(neonSql, d1?). The validateBoundaryGuard() function enforces
R8: Neon must be provided, or the write is rejected. wrangler.toml binds DATABASE_URL
in all environments. Neon migration 044_canonical_spine_neon_port.sql creates the
canonical tables (spine_entities, spine_relationships, spine_timeline, etc.).

Ordered, because each step removes an ambiguity the next would otherwise encode:

1. ✅ DONE. Canonical write failure is now hard-fail. The CanonicalSpineWriter returns
   success: false on Neon write failure; it no longer swallows errors with console.warn
   • success: true. Neon PostgreSQL is the canonical SSOT; D1 is the edge cache.
2. ✅ DONE. Canonical writes route through DATABASE_URL (Neon SQL via
   @neondatabase/serverless) instead of the SPINE binding. CANONICAL_SPINE_DB is
   retained as the D1 edge cache for fast reads, not as the canonical store. The
   wrangler.toml now binds DATABASE_URL as a secret in all environments.
3. Move the 16-concept ontology into packages/spine-entities (already consumed by
   services/spine) and delete the copy-paste in entity-type-map.ts. One definition.
4. Retire services/pipeline/src/spine/ once 1–3 land.
5. Stop using the word "Spine" unqualified in new code. It is Canonical or Operational.

Steps 1–3 also unblock the repo split (§15.5): a boundary cannot be drawn while the
canonical store on one side of it is a placeholder.

S0b · org_memory is a documented cache with six writers.
d1_knowledge.sql:12 describes it as "Mirror of memory.org_memory for edge-fast reads."
Six services INSERT/UPDATE it directly — pipeline/src/index.ts,
pipeline/src/memory-promoter.ts, intelligence/src/memory/evolutionary-memory.ts,
intelligence/src/handoff/outcome.ts, intelligence/src/workflows/triage-workflow.ts,
mcp-connector/src/handlers/tools.ts — and 23 files reference it. There is no defined
reconciliation against the Postgres table it claims to mirror. This is S0 repeating one
layer up. It must become either the store or a cache, with one writer. (M1)

S0c · agent_memory exists only inside retired infrastructure. Its sole definition is
services/pipeline/src/spine/index.ts:1360 — inside the Supabase legacy writer scheduled
for deletion. It needs a D1 table alongside personal_memory before step 4 above, or
the capability is lost with the file.

Tier 0b — Publication blockers

Verified 2026-07-31. Each blocks marketplace submission; all but the last are configuration
or copy. Detail: MCP and Plugin Publishing
Spec.

#	Finding	Evidence
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
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
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
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
F5	iw-continuity-bridge.json — a retired public name (D9) — sits in the publishable directory	marketplace/apps/
F6	Five release flavours against a two-package doctrine, with no stated mapping	releases/

Tier 1 — Correctness and security

S1 · A second, unauthenticated entry point sharing one database across surfaces.
packages/api (hub-controller-api) is bound by the Gateway in dev, test and prod — all
three to the same unsuffixed Worker with one D1 database. The Gateway explicitly skips its
own authentication for every /api/* path that is not /api/v1/*. It carries billing.ts,
auth.ts and capability-routes.ts — money, identity and capability execution. No deploy
script references it, so its deployed code is unversioned relative to the release ledger.
Violates Law 7 (one boundary), §14 (Gateway derives authority), §17 (test/prod isolation).

S2 · Fifteen dangling service bindings. The core nine were renamed from
integratewise-* to bare names; consumers were never updated. These resolve to nothing at
runtime.

S3 · Five test/prod binding leaks in the Gateway. HUB_CONTROLLER and MCP_POOL point
at identical targets in both environments. validate-platform-deployment.sh asserts only
mcp-connector isolation, so none of this is caught by release:check.

Tier 2 — Restore a single truth

S8 · Three deployed Workers assert three different single sources of truth.
services/pipeline claims to be the only holder of Spine write credentials;
services/spine claims to be the platform's single source of truth and holds DATABASE_URL
plus a 995-line canonical store; services/billing asserts Supabase. Additionally
services/pipeline/src/spine/ is a second, self-labelled-legacy Spine implementation
(2,773 LOC, Supabase-backed) that is live in the release path. Violates §8.3 directly.
services/spine is Gateway-bound and named canonical, yet is not in CORE_SERVICES — so
release:deploy --service core never publishes it.

S4 · Four environment vocabularies. Eight services still use retired
staging/production; signals and telemetry have no test surface at all. Both root
wrangler.toml and wrangler.jsonc are invalid and unused. ci-cd.yml is named DISABLED
but still contains seven direct wrangler deploy invocations — a second publication path.

S9 · Seventeen migration roots, 476 files, duplicate sequence numbers. Ordering is
ambiguous in both /migrations (three collisions) and /sql-migrations (nine).

Tier 3 — Inert mass

S5 · Three Capability Fabric implementations, none of them the live one.
packages/core and packages/lib/capability-fabric are near-exact mirrors, ~35 files,
mutually redundant and unreachable. The live path is
services/gateway/src/workbench-capabilities.ts + internal/capability-execution.ts +
services/mcp-pool.

S10 · A complete second, orphaned application root inside apps/web (Vite entry, config
and router, all committed and unreachable), plus 102 tracked _deprecated components.

S11 · Retired GCP/Firebase infrastructure still committed, including
services/mcp-connector/src/lib/firestore.ts inside a core release-path Worker.

S12 · Sixteen packages omit private, which npm treats as publishable — including
packages/connectors (~90 provider integrations) and packages/core (governance engine).

Tier 3b — Contradictory governance, and doctrine enforced by nothing

S5b · Two opposite promotion rules in one service.
knowledge/src/triage-bot.ts:13 — "The Triage Bot NEVER auto-approves. Every
extraction requires customer review."
knowledge/src/synthesis/promotion-gate.ts:8 — "AUTO-APPROVE: High confidence + no
governance flags + trusted domain", with decision: "auto_approved" at lines 124 and 144.

Both are in services/knowledge. The never-auto-approve position is correct per §8.2c-i and
the Authority Law. pipeline/src/memory-promoter.ts (415 LOC, live, queue-driven) already
implements the right shape. synthesis/promotion-gate.ts is orphaned and should be deleted.

S5c · The synthesis pipeline targets a store that no longer exists.
knowledge/src/synthesis/ — triage-bot, promotion-gate, continuity-object-factory,
lineage-tracker, knowledge-model — is a complete, unreferenced pipeline built on
CouchDB, superseded by the D1 memory tables. CouchDB survives in 11 files: three in
synthesis/, three in packages/coda-pack, and five in packages/hermes-spine-memory —
an entire package on retired infrastructure.

Salvage before deleting: lineage-tracker.ts and its UnderstandingObject provenance model
have no equivalent in the live path. memory-promoter.ts writes an audit row but does
not track lineage across promotions. That is a real capability gap, not dead weight.

S5d · The canonical Authority Doctrine is in a package with zero consumers.
packages/contracts/src/authority.ts (228 LOC) declares itself "supersedes all other
architectural rules" and states the Triage Boundary that settles S5b exactly. Verified:
@integratewise/contracts has 0 importers. The doctrine is exported as a template
literal — human-readable, machine-inert. Its neighbours share the fate, including
surfaces/chat.ts ("The Chat surface IS the Triage Hub") and marketplace/installation.ts
(which services/marketplace-installation ignores in favour of its own types).

A rule enforced by nothing is not a rule. Move authority.ts into packages/types (99
consumers) and convert the Triage Boundary into a test.

Tier 4 — Vocabulary and surface discipline

S6 · Retired L-layer vocabulary is the frontend's primary organising principle, and it
leaks to users. components/l1/ is 240 files — the largest component tree in the repo —
plus l2/, l4/, l7/, layers/. A product surface renders the literal string
"12 L1 domain views + 14 L2 cognitive overlay components". The Gateway exposes 19
/api/v1/cognitive/* routes; "cognitive" is not a kernel term. Most seriously,
intelligence/src/agents/specialized/twin-orchestrator.ts embeds "CODA L4 & MCP TOOLS…
Coda documents are connected L4 projection surfaces" inside a live LLM system prompt —
so retired vocabulary is shaping the Twin's reasoning, not merely sitting in comments.
Violates Law 8 and §6.

S7 · The Workbench is not one surface. Four parallel entry namespaces resolve to
Workbench content: /workbench/[department]/work/[module],
/workspace/[department]/work/[module], /domains/[domain]/[view], /app/[...segments].
The first two page files are byte-identical except for one route string. Separately,
components/capability-shell/, inline-executor/ and proactive-capabilities/ place a
capability catalogue and executor inside the Workbench. Violates §11.2 and Law 6.

S13 · Naming collisions. packages/adapters (infrastructure) vs
packages/connectors/src/adapters (providers); two "accelerator" concepts; two Twin
orchestrators (a 3,470-LOC Worker with zero inbound bindings, and a 268-LOC agent); two
contract homes; two marketing implementations, of which the legacy-pages set is the live
one.

S15 · Canonical documentation is itself a sprawl surface. 94 documents in
docs/architecture/, 16 declared canonical, six with "canonical" in the filename. This
document is the remediation.

Schema gaps against the store model

Verified at HEAD on 2026-07-31 against the six-store assignment in §8.2b:

Column	Purpose	State
embedding_id	Vectorize reference on the entity	Present (7 files)
r2_key	R2 reference on attachments	Present, thin (2 files)
memory_scope	user · work · org (§8.2c)	Present, thin (2 files)
conversational_store_id	Raw conversational memory reference on inbox items	Missing
source_records	Cross-source provider fragments on assembled entities (§8.2e)	Missing

Chunking is confirmed at 512 tokens (services/knowledge/src/embeddings.ts:122). Durable
Objects are declared across six services — intelligence, iw-agent-runtime, hermes,
connector-sync, folder-watcher, workflow.

Tier 5 — Orphans requiring a verdict

Eleven Workers have zero inbound bindings: agent-registry, hermes,
integration-management-mcp, marketplace-installation, provider-management-mcp,
schema-ai, signals, telemetry, twin-orchestrator, vercel-mcp.

hermes is stage 11 of the frozen runtime sequence and is unreachable. It still points
at integratewise-bff, a Worker that has never existed. This is the single most significant
gap between Part II and reality: the architecture names Hermes as the only coordinator of
approved external execution, and it is not wired.

21. Open decisions

Genuine forks, not deferred work. Each blocks something.

#	Decision	Blocks	Note
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
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
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
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
D5	Does development get its own tenant, or is it customer_zero on test?	Profile resolution	§15.3 permits either
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
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
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
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
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
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
M4	Does Personal Memory ever widen to Org, and by what act?	§8.2c	The hard boundary is currently absolute, and that is defensible
M5	Canonical Spine on Neon only, or Neon plus a D1 read projection?	S0 step 2
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
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
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
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

22. Change discipline

Before adding a concept. Name the responsibility it owns using only the twelve kernel
terms. If you cannot, it is either duplication of an existing primitive or a genuine major
version — and a major version is a founder decision, not a pull request.

Before renaming. Record which of five things is happening: fundamental · evolved ·
renamed · superseded · experimental. Mixing these is how documents start conflicting. Every
rename goes in Appendix J.

Before shipping. Does the surface stay narrow? New platform capability should rarely
produce a new user-facing noun. Broad underneath, narrow at the surface.

When documents disagree. Explain the evolution; never mix eras. Optimise for
architectural fidelity, not document fidelity. Documents are snapshots; the architecture is
the living system.

When this document is wrong. Change it here. Do not write a second document. The reason
this consolidation exists is that the alternative was tried ninety-four times.

23. Implementation inventory (2026-08-20)

23.1 Apps — 16 product surfaces

Category	Apps	Purpose
Primary product UX	web, workspace, platform, platform-console, desktop, mobile	Core authenticated workspace, platform administration, device clients
Identity and connection	auth, activation, connector, one-access, one-access-console	Authentication, onboarding, OAuth, identity management
Distribution and content	marketing, marketing-sites, portfolio, docs, mcp-servers	Public web, product marketing, internal ops, documentation, MCP boundary

Ownership requirement: Apps own presentation and workflow entry points. They must not
own canonical business state or provider credentials.

23.2 Packages — 60+ reusable modules

Package group	Examples	Role
Core platform	core, kernel, bootstrap, config, types, sdk, api	Runtime primitives and developer foundations
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
Integration	connectors, connector-contracts, connector-utils, adapters, provider-base, webhooks, host-platform-connector	Provider abstractions, connector behavior, webhooks, host integration
Execution and governance	capability, orchestrator, adk, omni-router, rbac, tenancy, gateway-sdk	Governed actions, workflow routing, agent development, authority, tenant isolation
Intelligence	intelligence, model-gateway, normalizer, loader, skills, analytics	AI access, ingestion, normalization, insight generation
Projections and UI	projection-engine, projection-contracts, workbenches, workbench-config, ui, design-system, one-access-ui	Contextual product views, reusable interface primitives
Contracts and validation	contracts, connector-contracts, context-contracts, integration-tests	Stable cross-layer interfaces, integration quality controls

Dependency direction (enforced):

apps → packages → core
services → packages → core

Prohibited:

• packages → services (packages must not depend on runtime services)
• UI → direct provider access (UI must go through ProjectionService)

23.3 Services — 40+ backend components

Service group	Examples	Role
Core control plane	gateway, core-engine, tenants, admin, store, telemetry, billing, continuity	Request routing, tenant lifecycle, administration, observability
Context and Spine	context, context-fetch, spine, projection, signals, knowledge, schema-ai	Context assembly, Spine operations, projection, knowledge retrieval
Integration lifecycle	connector, connector-sync, webhook-ingress, loader, normalizer, pipeline, provider-management-mcp	Connection management, ingestion, normalization, pipeline processing
Governed execution	capability, govern, hermes, workflow, task-management, twin-orchestrator	Capability invocation, governance evaluation, orchestration, Twin coordination
AI and agents	intelligence, iw-agent-runtime, agent-registry, ai-provider-mcp, huggingface-inference, mcp-pool	AI model access, agent runtime, MCP tool management
MCP ecosystem	mcp-connector, integration-management-mcp, provider-management-mcp, vercel-mcp, marketplace-installation	MCP protocol integration, marketplace operations

Service ownership requirement: No service reads another service's database tables
directly. Communication occurs through typed service contracts, governed commands,
immutable events, service bindings, queues, and Workflows.

23.4 Golden path — the canonical integration flow

Connect Provider → Ingest → Normalize → Promote to Spine →
Render Workbench → Execute Governed Capability → Reconcile Outcome

This is the single integration path that must work end-to-end before any secondary
surface is considered complete.

24. Critical gaps and remediation (2026-08-20)

24.1 Runtime completeness gaps

Gap	Severity	Evidence	Remediation
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
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
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
Inbox mark-read path	Medium	Behavior not connected to platform memory proposal path	Wire to memory.propose with correct argument format
Unimplemented section routes	Medium	Generic work-view renders "Section not implemented"	Hide behind feature readiness rules or remove route

24.2 Evidence contradiction

POST_STOP_FORENSIC_RECONCILIATION.md contradicts prior "todo list complete" conclusions:

• Customer Zero routes used unresolvable default hostname
• Endpoints not implemented by inspected Gateway source
• Tests validated constants and comments, not UI, routes, runtime behavior, persistence, or readback

Treatment: Release blocker until independently disproven with end-to-end production-like tests.

24.3 Monorepo boundary gaps

Gap	Risk	Remediation
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
Backup/reference directories (config-backup-*, lib-backup-*)	Accidental-import and documentation-drift risk	Remove or archive outside workspace; add lint rule for backup patterns
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

24.4 Build and release gaps

Gap	Risk	Remediation
lint has no declared dependency on builds	Lint success does not establish architectural correctness	Add dependsOn: ["build"] to lint task in turbo.json
typecheck depends on upstream builds	Masks pure type problems behind build failures	Consider separate typecheck task that runs against source directly
Concurrency of 50	May overload local/CI resources; intermittent test behavior	Reduce to 10–20 for CI; keep 50 for local only
Architecture/continuity/deployment checks not mandatory CI gates	Developer-optional; verification gap	Add as required CI steps with failure-blocking

24.5 Test coverage gaps

Gap	Risk	Remediation
Some tests validate constants/comments	False confidence; no real integration coverage	Add contract tests against deployed ephemeral environments
No write-then-readback tests	Mutations may not be durable	Add readback tests for every Spine, timeline, approval, and reconciliation mutation
No failure scenario tests	Provider failure, policy denial, expired delegation, duplicate webhook, retry, idempotency, compensation untested	Add dedicated failure scenario test suite

24.6 Product-surface duplication

Surfaces	Overlap	Remediation
web, workspace	Both claim authenticated workspace	Define single responsibility: web = end-user workspace, workspace = reusable composition package
platform, platform-console	Both claim platform administration	Define: platform = backend/runtime, platform-console = customer control-plane UI
one-access, one-access-console	Both claim identity management	Define: one-access = runtime identity, one-access-console = administration console

Required: Route-to-owner registry identifying app, backing service, owner, environment,
and automated test suite for every production route.

24.7 Frontend gaps

Workbench gaps:

• Sales Workbench TODO handlers for Twin query, assignment, approval
• Generic work-view "Section not implemented" visible
• Mock fallback missing for MCP Pool failures

State and resilience:

• No degraded-mode UX for MCP Pool failures, connector outages, empty states, partial hydration
• UI behaves as if data is always present and tools always reachable

Mutation gaps:

• Twin accept actions wired through memory.propose but argument format needs platform-side fix
• Timeline API route contains TODO for Supabase insert
• Users can trigger actions that appear accepted before durable proof is guaranteed

Canonical-model mismatch:

• Frontend does not fully represent degraded connectors, approval-required proposals,
  reconciliation status, evidence availability, hydration progress

Missing frontend capabilities:

• Connector health UX (connectors.status exists but no robust degraded-state system)
• Reconciliation UX (pending/observing/verified/failed/compensation_required/compensated lifecycle not exposed)
• Evidence/audit UX (incomplete persistence and action wiring)

24.8 Highest-priority remediation order

1. Prove the golden path: authenticate → connect provider → ingest → normalize →
   Spine write → Workbench read → governed action → provider confirmation →
   reconciled Spine readback
2. Close persistence gaps: implement timeline database write and verify through durable readback tests
3. Fix runtime resilience: add explicit degraded-mode behavior when MCP Pool or provider is unavailable
4. Make release evidence real: CI deploys isolated environment, executes API and browser tests,
   verifies persistence, validates external routes before promotion
5. Publish package/service governance: owner, status, deployability, canonical contracts,
   inbound/outbound dependencies, and retirement plan per module
6. Hide incomplete actions: disable TODO handlers until Twin query, assignment, approval,
   and section routes are actually live
7. Add resilient states: loading, empty, degraded, offline/fallback for every MCP-backed workbench
8. Model platform truth in UI: approval needed, queued, executed, observing, verified,
   failed, compensated
9. Require mutation readback: no optimistic success banners for governed actions touching
   memory, Spine timeline, approvals, or provider execution

25. E2E test strategy (2026-08-20)

25.1 Current coverage (smoke tests)

Playwright runs against localhost:3000 across Chromium, Firefox, and WebKit. The suite
validates that pages and key UI controls render. It does not prove the complete
governed business loop.

Current assertions cover: auth/tenant isolation rendering, memory hub visibility,
approvals visibility, handoff lifecycle rendering, outcome ingestion rendering,
tenant class enforcement rendering, continuity loop rendering, agentic workspace
navigation rendering.

These are smoke tests — they confirm the UI exists, not that it works end-to-end.

25.2 The gap — canonical governed loop not proven

A real E2E test must prove this chain:

Authenticate
  → resolve tenant and authorization
  → connect or validate a provider
  → ingest an external event
  → normalize and promote canonical context to Spine
  → materialize projection
  → render Workbench
  → draft/propose action
  → policy and approval decision
  → execute provider action
  → reconcile provider outcome
  → append evidence/audit
  → refresh UI from verified Spine state

None of these transitions are currently tested as an integrated chain.

25.3 Missing test assertions

Layer	Required assertion
Identity	Session resolves correct tenant, membership, role, permission, capability grant — not merely "logged in"
Isolation	Second tenant cannot retrieve, mutate, search, or infer first tenant's entities, memory, connector state, files, audit events
Ingestion	Webhook/provider event accepted once, deduplicated, normalized, linked to canonical entity, visible in projected Workbench view
Governance	Same command auto-approved, queued, or denied depending on policy inputs; UI accurately displays each outcome
Execution	Provider acceptance not treated as success; UI shows pending/observing until reconciliation confirms verified, failed, or compensated
Evidence	Every material mutation produces retrievable audit/evidence records; write failure prevents material command from presenting as complete

25.4 Priority E2E scenarios

1. Tenant activation:

create tenant → deploy/resolve runtime → migrate operational store →
bootstrap workspace and policy → discover connector → hydrate working set →
open useful Workbench with initial Twin brief

2. Inbound-to-Workbench:

provider webhook → idempotency check → loader → normalizer →
Spine entity/relationship update → projection invalidation →
UI refresh → user opens correct entity with lineage and freshness shown

3. Governed outbound action:

user accepts Twin proposal → capability authorization → policy decision →
approval where required → provider call → reconciliation observation →
verified Spine update → Workbench timeline and audit readback

4. Failure and recovery:

simulate provider timeout/rejection → show failed/observing state →
retain evidence → allow retry or compensation only through governed controls →
prevent false-success UI state

5. MCP outage:

MCP Pool unavailable → Workbench shows designed degraded state →
cached read-only content when safe → retry controls →
no non-durable optimistic mutations

25.5 Test design requirements

Requirement	Rationale
Deployable E2E environment with actual service bindings	Local Next.js process cannot prove tenant isolation, provider integration, or reconciliation
Tenant-scoped data stores and provider sandbox/test doubles	Real data flow, not mocked responses
Seed data through real ingestion APIs	Never preseed only final UI-facing database state
Independent readback assertions	Provider test double → reconciliation record → Spine entity/timeline → projection API → audit/evidence API → browser UI
Test IDs and workflow correlation IDs	Trace browser actions across gateway, capability, policy, execution, reconciliation, audit
Smoke tests vs E2E gate	"Button is visible" = smoke; state transitions, durable writes, policy outcomes, tenant isolation = E2E gate

---

Appendices

Appendix A — Kernel terms

See §3. Twelve terms, frozen: WORK · CONTEXT · SPINE ·
CONTINUITY · WORKBENCH · TWIN · CAPABILITY · GOVERNANCE · HERMES · SYNC · BRIDGE · OUTCOME.

Appendix B — Runtime sequence

Configuration → Integration → Pipeline → Adaptive Spine → Workbench Composition
→ Continuity Bridge → User Workbench → Twin → Capability → Governance
→ Hermes → Sync → Promotion

Governed execution path:

Twin or user intent → Capability Fabric → Governance → Hermes → execution provider
→ provider outcome → re-ingestion → verification and reconciliation → Pipeline promotion

System loop: LOAD → NORMALIZE → STORE → THINK → REVIEW & APPROVE → ACT → REPEAT

Deterministic normalisation functions (the boundary is normative; the stage count is not a
product concept):

1 Raw Event Ingestion   2 Canonical Field Mapping   3 Schema Normalization
4 Entity Resolution     5 Deduplication             6 Relationship Linking
7 Depth Matrix Evaluation                           8 Spine Write

Appendix C — Services

Core nine (canonical publication order, Gateway last):

Worker	Responsibility
pipeline	Normalizer + Spine writer. Self-declared sole holder of Spine write credentials
connector	Compatibility router → loader · store · mcp-connector
mcp-connector	MCP tool server + OAuth authorisation server
connector-sync	Schema-driven scheduled and on-demand provider sync
knowledge	Chunking, embedding, search, synthesis, promotion gate, lineage
continuity	Append-only session event log, checkpoints, continuity assembler
intelligence	think + act + govern + agents
workflow	Bound as BFF. Views, analytics, stream gateway, HITL Durable Object
gateway	Single entry point

Bound but outside the release path: spine (SPINE) · iw-agent-runtime
(AGENT_RUNTIME) · webhook-ingress · mcp-pool · admin · billing · tenants ·
folder-watcher · loader · store · task-management

Zero inbound bindings: agent-registry · hermes · integration-management-mcp ·
marketplace-installation · provider-management-mcp · schema-ai · signals ·
telemetry · twin-orchestrator · vercel-mcp

Appendix D — Gateway routes

Route	Target	Purpose
/api/v1/auth	INTERNAL_AUTH	Authentication
/api/v1/projections	INTERNAL_PROJECTIONS	Projection Engine
/api/v1/workspace/discovery	Gateway → Spine	First canonical read
/api/v1/workspace/*	BFF	Workspace operations
/api/v1/billing	INTERNAL_BILLING	Billing
/api/v1/tenants	INTERNAL_TENANTS	Tenant management
/api/v1/support	INTERNAL_SUPPORT	Support
/api/v1/analytics	BFF	Analytics
/api/v1/agents	INTELLIGENCE	Agent management
/api/v1/continuity-bridge	MCP_CONNECTOR	Public 19-tool Spine MCP
/api/v1/connectors	CONNECTOR	Connector management
/api/v1/pipeline	PIPELINE	Data pipeline
/api/v1/intelligence	INTELLIGENCE	Intelligence layer
/api/v1/cognitive/spine	PIPELINE	Spine operations
/api/v1/cognitive/entity360	PIPELINE	Entity 360
/api/v1/cognitive/memories	KNOWLEDGE	Memory operations
/api/v1/cognitive/signals	INTELLIGENCE	Signal processing
/api/v1/cognitive/think	INTELLIGENCE	Think / Twin
/api/v1/cognitive/act	INTELLIGENCE	Act execution
/api/v1/cognitive/govern	INTELLIGENCE	Governance
/api/v1/cognitive/twin	AGENT_RUNTIME	Twin runtime
/api/v1/knowledge	KNOWLEDGE	Knowledge management
/api/v1/marketplace/installations*	MARKETPLACE_INSTALLATION	Onboarding state machine
/api/v1/marketplace/apps	SPINE	Catalogue (Spine data)
/api/v1/l2	L2	Cognitive overlay (retired label — see S6)
/admin	INTERNAL_ADMIN	Admin
/oauth	INTERNAL_AUTH	OAuth flows
/ws, /sse, /stream	BFF	Real-time

Endpoint ownership by intent:

Intent	Family	Owner
Discover product	/api/v1/workspace/discovery	Gateway + Configuration + Activation + Projection
Onboard / configure / activate	/api/v1/workspace/*	Configuration + Activation
Browse / connect / sync / revoke	/api/v1/connectors/*	Integration Manager
Compose Workbench, Inbox, Entity 360, canvas	/api/v1/projections/*	Projection Engine
Read knowledge / evidence	/api/v1/knowledge/*	Knowledge and evidence services
Ask / assign Twin	Semantic Twin routes	Twin runtime — drafts only
Approve / reject / execute	Governance command routes	Governance → Hermes

Appendix E — Gateway bindings

Category	Binding	Type
Database	DB	D1Database (integratewise-spine-cache)
KV	RATE_LIMITS, SESSIONS, CONNECTOR_STATUS, SIGNAL_CACHE, METRICS, OAUTH_STATE_KV	KVNamespace
R2	FILES	R2Bucket
Services	CONNECTOR, CONNECTOR_SYNC, PIPELINE, INTELLIGENCE, KNOWLEDGE, BFF, L2, AGENT_RUNTIME, ADMIN, BILLING, TENANTS, WEBHOOK_INGRESS, HUB_CONTROLLER, SPINE, MCP_POOL, MARKETPLACE_INSTALLATION	Fetcher

Isolation invariant: no env.test target may equal any env.prod target, for any binding
class. validate-platform-deployment.sh currently asserts this only for mcp-connector.

Appendix F — Canonical entities

Entity	Source
Connection	packages/spine-entities/src/connection.ts
Connector	packages/spine-entities/src/connector.ts
SyncJob	packages/spine-entities/src/sync-job.ts
Webhook	packages/spine-entities/src/webhook.ts
Schema	packages/spine-entities/src/schema.ts
Capability	packages/spine-entities/src/capability.ts
TimelineEvent	packages/spine-entities/src/timeline.ts

Tenant lifecycle families: spine_organizations · spine_workspaces · spine_users ·
spine_memberships · spine_roles · spine_permissions · spine_tenant_accounts ·
spine_networks. Generic spine_entities remains the compatibility graph and identity
layer; typed tables are the canonical materialised home for their families.

Entity contract (frozen): identity · fields · relationships · timeline · provenance ·
permissions · capabilities.

Appendix G — Connector lifecycle

Publish connector definition → discover / install → resolve identity and tenant
→ reuse eligible connection or request consent → store opaque credential reference
→ create tenant/workspace connection binding
→ discover provider objects, fields, events, operations
→ approve schema / entity / capability mappings
→ activate initial hydration and delta sync
→ Pipeline promotes entities, relationships, provenance, evidence
→ Projection Engine invalidates and recompiles permitted views
→ monitor, repair, revoke, reconcile

The binding must deterministically resolve:

(user_id, tenant_account_id, tenant_id, spine_network_id, provider_key,
 provider_workspace_id, connector_binding_id, spine_connection_id, schema_binding_set)

Connector installation registers mappings, sources, availability and approved additive
extensions. It does not execute ad-hoc physical DDL.

Appendix H — Public 19 tools

get_my_continuity · get_active_context · get_my_focus · get_context · get_changes ·
get_related · get_history · get_commitments · get_decisions · get_permitted_memory ·
get_relevant_knowledge · ask_twin · assign_twin · get_prepared_work ·
get_available_actions · prepare_action · get_action_plan · approve_action ·
store_in_spine

Appendix I — Stop-ship invariants

A release is not aligned if any of the following is true:

1. The browser selects a legacy identity provider while Clerk is configured
2. The public MCP lists anything other than the exact 19 tools
3. The Plugin claims automatic inheritance of other host-app credentials, or the MCP lane
   omits its standalone browser Workbench / fallback path
4. A UI or Twin route writes Neon directly
5. D1 is described or used as canonical business truth
6. A failed live projection silently becomes demo data
7. A material write executes without a proposal, a policy decision, a receipt and a
   reconciliation — on any route, host-native or IntegrateWise-native
8. A provider connector is copied into a product repository
9. The user must explain context already present in the Spine Network
10. L1/L2/L4/L7 appear as user-facing product navigation
11. A host, MCP client, frontend or agent queries Fortress storage directly
12. An answer claims cross-system completeness without reporting canonical completeness or
    disclosing the systems it could not see
13. Declared host capability is routed to without runtime confirmation
14. The same provider is called through both host and IntegrateWise by default
15. A write path returns success when the canonical write was skipped, failed, or landed
    only in a cache
16. Any automated path can write governance_state = 'approved' without an approver identity
17. A component writes synchronously to both the Spine and a projection
18. An AI classifier establishes source identity or canonical identity on its own
19. An agent promotes a rule into autonomous execution
20. A response conveys uncertainty as a guessed value rather than an explicit state

Additionally, per §17: no test/prod resource sharing of any binding class, and no Worker
publication outside Release Core Workers.

Appendix J — Vocabulary ledger

Retired	Current	Status
Cognitive OS · IntegrateWise OS · AI OS	IntegrateWise Platform	Superseded — category
OS Shell · Views · Topic Boards	Workbench	Renamed — one surface
Atlas Spine	Adaptive Spine	Renamed
16 AI Agents (named personas)	Capabilities in the Capability Fabric	Superseded — taxonomy retired
Cognitive Twin · AI assistant · copilot	Twin	Renamed — silent by default
Co-worker (as separate runtime)	Twin	Superseded — one runtime
Normalizer · Hermes (external use)	(internal only)	Never customer-facing
IW Continuity Bridge	IntegrateWise / Continuity Bridge (internal)	Retired public name
TenantClass	Profile	Renamed — it was a runtime property, not a tenant property
L1 / L2 / L4 / L7	Workbench / Twin / Continuity / Governance	Engineering-internal only; never user-facing
/api/v1/cognitive/*	(unresolved)	"Cognitive" is not a kernel term — rename or sanction as an alias
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

Appendix K — Path to alignment

The ordered sequence that closes the gap between Part II and Part III. Ordering is not
arbitrary: each step removes an ambiguity the next step would otherwise encode.

#	Step	Closes
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
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
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
3	Decide the Spine writer (D4); retire the loser; add spine to CORE_SERVICES	S8
4	Wire or formally retire hermes — it is stage 11 of the frozen sequence and currently unreachable	Tier 5
5	Normalise environment vocabulary to dev/test/prod; delete both root wrangler configs and ci-cd.yml	S4
6	Consolidate the migration ledger to one root, one sequence, no duplicate numbers	S9
7	Consolidate frontend calls on NEXT_PUBLIC_IW_API_URL and one typed Gateway client; remove production localhost and direct-service fallbacks	§16.3
8	Complete live deployment plus negative tenant/RBAC and frontend acceptance for /api/v1/workspace/discovery	§16.3
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
10	Collapse to one Workbench URL namespace; remove the capability catalogue and executor from the Workbench	S7
11	Delete inert mass — dead Capability Fabrics, orphaned Vite root, _deprecated, retired GCP surfaces, zero-consumer packages	S5, S10, S11
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
13	Complete one connector end to end: consent → strict binding → discovery → schema mapping → hydration → delta sync → revoke → projection invalidation	§16, Appendix G
14	Validate the full four-button governed loop: proposal → approval token → Hermes → provider outcome → re-ingestion → reconciliation → projection refresh	§10
15	Validate Development → Customer Zero → Customer Production promotion with isolated credentials, data, bindings, queues, caches, evidence and audit	§17

Integrated-testing gate. Do not begin the integrated testing event until every item below
has evidence. Any missing item is a blocker, not post-launch cleanup:

environment/DNS/identity/Gateway/Neon/R2/D1/KV/queue/secret health · migration ledger and
schema verification · cross-tenant and cross-environment negative tests · first-read
discovery and every visible sidebar projection contract · one real connector through the full
lifecycle · public MCP OAuth and exact 19-tool listing · no automatic inheritance of unrelated
host-app credentials · no direct frontend database/provider/internal-MCP traffic · explicit
partial and degraded states with no live-to-demo fallback · one complete governed action
trace · bounded retry, ambiguous-outcome protection, dead letter and governed replay ·
observability, audit, rollback and revocation evidence.

Appendix L — Document disposition

docs/architecture/ held 94 entries at consolidation. Their disposition:

Retained — still authoritative in their own scope

Detailed specifications this document summarises. Each remains the reference for its
implementation detail and is subordinate to this document.

APP_CATEGORY_ENTITY_DOMAIN_CLASSIFICATION.md · CANONICAL_SPINE_SCHEMA_FOUNDATION.md ·
SPINE_ENTITY_TABLE_SCHEMA.md · TENANT_LIFECYCLE_SCHEMA_REGISTER.md ·
TENANT_SPINE_FORTRESS_OPERATIONAL_FLOW_MODEL.md · WORKBENCH_ROLE_CAPABILITY_MAP.md ·
IW_SPINE_NETWORK_PLUGIN_AND_MCP_MARKETPLACE_CONTRACT.md ·
FRONTEND_PLATFORM_API_AND_DISCOVERY_SPEC.md · RUNTIME_SUBSTRATE_AND_SURFACE_CONTRACT.md ·
CODEBASE_EXCAVATION.md (the drift baseline; Part III derives from it) ·
HOST_AWARE_CONTINUITY_RUNTIME_SPEC.md (frozen 2026-07-29 — the normative source for
§15.5–15.8: request classification, capability resolution, connection binding, agent
contracts, Loader/Normalizer schemas, failure matrix and acceptance criteria)

Absorbed — content now lives here; archive

ARCHITECTURE_LOCK.md · IMPLEMENTATION_CONTRACT_v1.1.md ·
CONSOLIDATED_PRODUCT_PLATFORM_CONTRACT_v1.2.md · PLATFORM_LOCK_v1.0.md ·
FOUR_BUTTONS.md · TWIN_BEHAVIOR.md · WORKBENCH_MATRIX.md · ADAPTIVE_SPINE_MODEL_v1.md ·
CAPABILITY_FABRIC.md · SOURCE_PACK_RECONCILIATION_2026-07-28.md ·
RUNTIME_PROFILE_AND_ENTRY_CHANNEL_CONTRACT.md · CANONICAL_ARCHITECTURE.md ·
MASTER_EXECUTION_PLAN.md · PRODUCT_PLATFORM_BOUNDARY_AND_GO_LIVE_STANDARD.md ·
PLATFORM_PRODUCT_DATA_AND_PROJECTION_REFERENCE.md ·
CUSTOMER_ZERO_TO_EXTERNAL_PRODUCT_AND_MARKETPLACE_SPEC.md ·
CUSTOMER_ZERO_HOSTED_PLUGIN_CODE_BRIEF.md · BROWSER_FRONTEND_AND_MCP_PRODUCT_CODE_BRIEF.md

Constitutions — absorbed into Parts I and II

The nine constitutions each stated the doctrine for one subsystem. Their content is now
distributed across §2–§16.

ADAPTIVE_WORKBENCH_CONSTITUTION.md · CANONICAL_ENTITY_CONSTITUTION.md ·
CAPABILITY_CONSTITUTION.md · CONNECTOR_CONSTITUTION.md · EXECUTION_CONSTITUTION.md ·
GOVERNANCE_CONSTITUTION.md · PROJECTION_CONSTITUTION.md · RUNTIME_CONSTITUTION.md ·
TWIN_CONSTITUTION.md · CUSTOMER_ZERO_CONSTITUTION.md (DRAFT) ·
CUSTOMER_ZERO_DAILY_OPERATING_MANUAL.md (DRAFT)

Superseded — already marked, or superseded by this document

CANONICAL_PLATFORM_ARCHITECTURE.md · CANONICAL_SPINE_CONVERGED.md ·
CANONICAL_ARCHITECTURE_V4.md · PRODUCT_ARCHITECTURE.md · PRODUCT_ARCHITECTURE_V1.md ·
USER_SYSTEM_JOURNEY_BLUEPRINT.md · PLATFORM_ARCHITECTURE.md · END_TO_END_ARCHITECTURE.md ·
SINGLE_END_TO_END_MAP.md · FRONTEND_LAYERED_STACK.md · PLANE_LAYER_CROSS_REFERENCE.md ·
PROJECTION_MODEL.md · PROJECTION_CONTEXT_REFACTOR.md · SPINE_MODEL.md ·
SPINE_DOMAIN.md · ENTITY360_V2_MODEL.md · UNIFIED_GOVERNANCE_SPEC.md ·
WORKBENCH_DOCTRINE.md · MULTI_PROTOCOL_PLATFORM.md · ONBOARDING_FLOW.md ·
CURRENT_CONTEXT_FLOW.md · DETAILED_USER_FLOWS_AND_SYSTEM_PATHS.md ·
AI_CONNECTOR_MCP_FLOW.md · CONNECTOR_RUNTIME_PROOF.md · SPINE_INTELLIGENCE_AGENT.md ·
LONG_TERM_TASK_MANAGEMENT_MCP.md · CODEBASE_ALIGNMENT_SPEC.md ·
ARCHITECTURE_DOCUMENTATION_PLAN.md · DOCUMENTATION_COMPLETION_MANIFEST.md ·
APP_CATEGORY_ENTITY_DOMAIN_MODEL.md (+ .txt duplicate)

Lineage — historical, retain in docs/archive/

The v2 deep-dive family and the locked-v1 lineage. Valuable as evolution record; not
authority.

integratewise-architecture-v2.0.md · v2-ai-capability-fabric.md · v2-capability-layer.md ·
v2-continuity-governance.md · v2-data-model.md · v2-deployment.md · v2-ecosystem.md ·
v2-identity-ingress.md · v2-provider-fabric.md · v2-security.md · locked-v1.md ·
locked-v1.0.1.md · final-e2e-system.md · l1-reality-check.md · reality-audit.md ·
one-full-prompt.md · suite-00-34.md · source/

Unresolved

MCP_POOL_MULTI_ENVIRONMENT_STRATEGY.md — DRAFT, conflicts with §15.1. Blocked on D6.
Do not archive until decided; do not treat as authority meanwhile.

Not architecture

PRODUCT_NARRATIVE.md and STAKEHOLDER_PITCH.md are commercial documents and belong under
docs/commercial/, governed by the Deck Core and
GTM Canon. README.md becomes a pointer to
this document. CANONICAL_SPINE_SCHEMA.sql is an artifact, not a document.

For the checkout-grounded ownership, wiring, storage, deployment, marketplace, migration, and
component-disposition map, see the subordinate
Canonical Ecosystem Coverage Companion. It separates
repository/configuration evidence from deployed runtime proof and does not override this document
or its canonical amendments.

---

Part IV — Consolidated Reference (historical, superseded)

Note: This part was an earlier consolidation. It is now superseded by
Parts V (Master Reference), VI (Consolidated Canon), and VII (Book-of-Record
Baseline). The content below is retained for historical continuity. Do not
edit — make changes in Parts V–VII instead.

This part consolidates the architecture into 12 canonical sections. It is the
primary reference for implementation, documentation, onboarding, and product
messaging. Earlier parts remain as design history and detailed specification.

23. Product definition

IntegrateWise is an Adaptive Operational Workspace built on an Adaptive Spine
that provides Organizational Continuity through a Shared Workbench, a contextual
Twin, and governed capability execution.

Earlier descriptions (AI Workspace, Productivity Platform, Department Workspace)
are product descriptions, not the architecture.

24. Platform flow

The complete platform is always described in one direction:

Marketplace / Plugin
        │
        ▼
Workspace Activation
        │
        ▼
Configuration Manager
        │
        ▼
Integration Manager
        │
        ▼
Activation Bridge
        │
        ▼
Loader Runtime
        │
        ▼
Normalizer + Triage
        │
        ▼
Adaptive Spine
        │
        ▼
Projection Engine
        │
        ▼
Adaptive User Workbench
        │
        ▼
Twin
        │
        ▼
Capability Fabric
        │
        ▼
Governance
        │
        ▼
Hermes
        │
        ▼
Execution
        │
        ▼
Sync
        │
        ▼
Continuity Pipeline
        │
        ▼
Adaptive Spine

25. User onboarding

The onboarding flow is lifecycle-first, not role-first:

Marketplace Install
        ↓
Identity
        ↓
Organization
        ↓
OAuth
        ↓
Connect one or two tools
        ↓
One-click Loader
        ↓
Adaptive Spine
        ↓
Projection Engine
        ↓
Adaptive Workbench

Then the user continues connecting:

Slack, GitHub, Notion, Google, HubSpot, Salesforce, Jira, ...

Every connector expands the same organization rather than creating another
workspace.

26. Adaptive Spine

The Base Spine is mandatory. Everything else expands it:

Base Spine
  + Industry
  + Department
  + Role
  + Connector
  + Tenant
  + Context
  = Effective Spine

Nothing replaces the Base Spine. Everything is additive.

27. Projection Engine

The Projection Engine is the architectural boundary that prevents UI coupling:

Adaptive Spine
        ↓
Projection Engine
        ↓
Workbench
        ↓
Twin

Not:

Workbench → Database
Gateway → Workbench

28. User Workbench

The Workbench is:

• Not a dashboard
• Not CRUD
• Not a CRM
• Not a document editor

It is the operational hub of every department. It composes fields, entities,
memories, capabilities, and views from every connected system.

29. Twin

The Twin is not another chatbot. It continuously observes:

• Current work
• Selected records
• Organization context
• Historical continuity
• Permissions
• Available capabilities

and performs the heavy operational work.

30. OODA

The four-button interaction model is canonical:

Observe → Store in Spine
Orient  → Ask Your Twin
Decide  → Assign Your Twin
Act     → Approve Twin Action

The Twin never owns "Act." The human always authorizes execution.

31. Capability Fabric

Execution paths include:

• Tool → Tool
• Memory Fetch
• MCP
• Agent → Agent
• Local execution
• API execution

The Workbench composes the work. Capability Fabric resolves execution.
Governance authorizes it. Hermes orchestrates it.

32. Runtime substrate

State planes are separated and must never be merged:

Plane	Purpose
Adaptive Spine	Operational Truth
Twin Memory	AI Continuity
Session Logs	Conversation History
Audit Logs	Execution Accountability
Knowledge	Semantic Retrieval
Blobs	Files
Cache	Acceleration
Sync	Convergence
Config	Tenant Runtime
Ephemeral	Temporary Runtime

33. Runtime guarantees

The operational guarantees required for production:

Ingress
    ↓
Validation
    ↓
Event Bus
    ↓
Queues
    ↓
Capability
    ↓
Governance
    ↓
Hermes
    ↓
Execution
    ↓
Outcome
    ↓
Verification
    ↓
Reconciliation
    ↓
Promotion
    ↓
Spine

Supporting guarantees (mandatory platform primitives):

• Idempotency
• Retries
• Dead-letter queues
• Traceability
• Structured logging
• Observability
• Replay

34. Customer Zero — lifecycle-first operating model

Departments become participants in lifecycle execution rather than the primary
organizing principle:

Lifecycle
    ↓
Event
    ↓
State
    ↓
SOP
    ↓
Capability
    ↓
Approval
    ↓
Execution
    ↓
Evidence
    ↓
Memory
    ↓
Next Lifecycle

35. Consolidated layer responsibility

Layer	Responsibility
Workspace Activation	Tenant and identity onboarding
Configuration Manager	Runtime configuration
Integration Manager	Connectors, OAuth, discovery
Activation Bridge	Compile active workspace context
Loader + Normalizer	Canonical ingestion
Adaptive Spine	Operational source of truth
Projection Engine	Compose workbench projections
Adaptive Workbench	Human operating surface
Twin	Contextual reasoning and preparation
Capability Fabric	Execution path resolution
Governance	Authorization and policy
Hermes	Orchestration
Sync + Continuity Pipeline	Reconciliation and persistence

Part V — Master Reference

This part consolidates the Master Index into the canonical architecture. The
full Master Index (IntegrateWise_Master_Index.md) remains as a detailed
supporting document; this section captures the essential structure.

36. Product definition (Master Index)

IntegrateWise is a self-organizing operational Workbench.

It gives every user one place to understand, decide, communicate, approve,
and complete their work while the connected ecosystem coordinates continuously
underneath.

Core doctrine:

• One Workbench for the user
• One Spine underneath
• Truth you own. AI you rent. Approval in between.

The Twin is proactive, not passive: it organizes context, surfaces the actual
todos, proposes actions, and coordinates with tools and agents while the user
stays in control.

37. Core vocabulary

Term	Meaning
Spine	The unified SSOT. Not a single database — a collection of purpose-fit data stores.
Digital Memory	User-facing name for the Spine.
Twin	AI reasoning layer. Rented cognition operating on owned truth.
Workbench	The operational UI surface. Interactive, not a dashboard.
Continuity Debt	Accumulated cost of context lost every time a tool changes or a person leaves.
LOOP	THINK → ACT → GOVERN → REPEAT → ADJUST. The compounding intelligence cycle.
HITL	Human-in-the-loop. AI proposes, humans decide. Architectural invariant, not a setting.
Capability Network	The Spine as shared connectivity — connect once, accessible everywhere.
MCP Pool	Capability registry split by operational plane vs cognitive plane.
Customer Zero	IntegrateWise running IntegrateWise on itself. The founder's own workbench.

38. Workbench Doctrine

The IntegrateWise UI is not a dashboard. It is an operational workbench — a
single, interactive surface where the user does real work without juggling
tabs, tools, or context switches.

• A dashboard is passive. It shows you data.
• A workbench is active. You act on data directly — add a task, update a
  pipeline, approve a request, respond to an email — all without leaving
  the surface.

39. Five-Zone Shell

Every department uses the same structural shell. What changes is the data,
the KPIs, the entity types, and the capabilities. The layout never changes.

Zone 1 — Department Header: Name, icon, Continuity Score, last sync
timestamp. Two global filters (time range + owner) that cascade to
everything below.

Zone 2 — Pulse Bar: Four KPI cards per department, live from the
Gateway projection. Clicking a card filters Zone 3 to that subset.

Department	KPI 1	KPI 2	KPI 3	KPI 4
Sales	Pipeline Value	Open Deals	Win Rate	Overdue Tasks
Customer Success	Accounts at Risk	Renewals	Avg Health	Open Tickets
Finance	ARR	Outstanding Invoices	Burn Rate	Overdue Payments
Operations	Active Projects	Blockers	SLA Compliance	Pending Approvals
Marketing	Active Campaigns	MQLs	Conversion Rate	Content Published
Engineering	Open PRs	Bugs	Deploy Frequency	Incidents

Zone 3 — Main Work Surface: Three view modes: Table (default), Board
(Kanban), Calendar. In table mode every row has inline capability buttons
— Call, Email, Task — on hover.

Zone 4 — OODA Action Bar: Fixed at the bottom. Always visible. Never
scrolls away.

Button	Action
Observe	Slides up — write to Spine (fact, decision, risk, learning)
Orient	Focuses the Twin panel with current context
Decide (n pending)	Approval queue — inline approve/reject
Act	Capability picker — search + recent capabilities

Zone 5 — Twin Panel: 300px right rail. Always present. Never hidden.

• Top: Live signals feed — risk (ember), opportunity (gold), action (forest green)
• Middle: Pending proposals with inline approve / reject
• Below: Quick prompt chips (3 contextual suggestions)
• Bottom: Ask Twin input

40. Sidebar Architecture

The sidebar answers three progressively broader questions:

1. What do I need to work on? Tasks, inbox, approvals, communications
2. Where am I working? Customer Zero, AI Workspace, Account Success, Sales, Operations
3. How is the platform configured? Integrations, MCP Pool, Governance, Settings

Navigation layers

Personal (80–90% of time): Home · Inbox · Tasks · My Queue · Approvals · Notifications · Recent Work · Favorites

Communications: Activity Feed · Email · Calendar · Meetings · Chat · Calls · Documents Shared

Workspaces (12 Departmental Views):

#	Workspace
0	Customer Zero
1	Account Success
2	Sales
3	Business Operations
4	Revenue Operations
5	Finance
6	Administration
7	Engineering
8	Product Development
9	Service
10	Customer Support
11	AI Workspace
12	Knowledge

Platform: Integration Manager · Connector Marketplace · Activation Manager · Capability Manager · MCP Pool · AI Models · Knowledge · Memory · Automation · Pipelines · Governance · Observability

Administration: Organizations · Users · Roles · Permissions · Audit · Billing · Deployments · API Keys · Security

Personal (bottom): Profile · Preferences · Personalization · Connected Accounts · Notifications · Appearance · Keyboard Shortcuts · Help · Feedback · Settings

41. Platform UI Design System

One layout grammar. Twelve operational surfaces.

Design Doctrine

The Platform UI is not a collection of dashboards. It is a Platform Control
Plane — a consistent operational grammar where page content changes but
structural layout never does.

Primary workspace: Paper & Forest system (warm paper background, forest
green accents). The dark sidebar remains.

Shared Page Anatomy

Every Platform page has:

1. Context header — title, description, status badge, primary action(s)
2. Operational status summary — KPI strip (compact, not marketing cards)
3. Primary management surface — table, card grid, or guided flow
4. Inspector / Twin rail — collapsible right panel, context-aware
5. Activity and audit timeline — bottom panel, always present

Platform Pages

Page	Purpose
Integration Manager	Connection operations console
Connector Marketplace	App marketplace for discovery
Activation Hub	Onboarding and setup flows
Capability Manager	Capability registry and resolution
MCP Pool	MCP tool registry and routing
AI Models	Model configuration and routing
Knowledge	Document and evidence management
Memory & Continuity	Durable memory and continuity management
Automation	Workflow and automation management
Pipelines	Data pipeline management
Governance	Policy, authority, and approval management
Observability	Logs, traces, metrics, audit

42. Design System Tokens

Token	Value	Use
Background	#F4F0E8	Warm white paper
Sidebar	#0C0C0C	Canvas black
Active accent	#2D5A3D	Forest green
Signals/gold	#B8943F	Opportunity, warning
Risk/urgent	#E8693A	Ember
Heading font	DM Serif Display	Page and section titles
Body font	Instrument Sans	UI, labels, body
Number font	IBM Plex Mono	All numbers and timestamps

43. Workbench IA & Spine Projection Map

Every navigation item is a surface. Every surface is a projection over the
Spine. No surface owns its own database.

Standard surface template

For each surface:

• What it is — one sentence
• User question — what this surface helps the user answer
• Spine domains — Work, Communication, Knowledge, Memory, Governance, Capability, Platform, or Identity
• Source tables — canonical tables and connector-derived records
• Twin behavior — when it appears and what it can propose
• Actions — what the user can do from the surface
• Missing schema — only if a needed table does not exist yet
• Projection output — entities, KPIs, signals, capabilities, memory refs

Home surface

The user's operational command centre. Not a dashboard — a living brief
assembled by the Twin every session.

Spine domains: Work Spine + Communication Spine + Signal Spine + Memory Spine

Twin behavior:

• Assembles the daily brief: priorities, blockers, decisions needed
• Surfaces continuity threads that were interrupted since last session
• Proposes the first three actions for the day
• Flags anything that degraded overnight

Part VI — Consolidated Canon

This part consolidates the complete architecture into a single canonical
reference. It supersedes all prior conflicting statements and represents
the unified architecture as of this document.

44. Canonical hierarchy

INTEGRATEWISE
│
├── ONE AUTH / IDENTITY
│
├── SPINE NETWORK / MARKETPLACE ENTRY
│
├── WORKSPACE ACTIVATION RUNTIME
│
├── CONNECTOR + INGESTION FABRIC
│
├── ADAPTIVE SPINE
│   ├── Entity
│   ├── Relationship
│   ├── Timeline / Events
│   ├── Operational State
│   ├── Knowledge
│   ├── Memory / Continuity
│   ├── Context
│   ├── Signals
│   ├── Governance
│   ├── Capability
│   └── Projection
│
├── PROJECTION ENGINE
│
├── ADAPTIVE WORKBENCH
│
├── CONTEXTUAL TWIN
│
├── CAPABILITY FABRIC
│
├── GOVERNANCE
│
├── ORCHESTRATION / EXECUTION
│
└── VERIFY → RECONCILE → SPINE

The Workbench is one. The Spine is one. The Projection is many.

45. Canonical runtime loop

Discover / Install
      ↓
One Auth
      ↓
Identify User + Organization + Tenant
      ↓
Connect Initial Systems
      ↓
Discover Connector / MCP / Tool Capabilities
      ↓
Ingest
      ↓
Load
      ↓
Aggregate by Tenant
      ↓
Normalize / Triage
      ↓
Promotion / Governance
      ↓
Adaptive Spine
      ↓
Projection Engine
      ↓
Adaptive Workbench
      ↓
User Works
      ↓
Twin Observes + Orients
      ↓
Ask / Assign
      ↓
Twin Researches / Prepares / Proposes
      ↓
Capability Resolver
      ↓
Governance / Authority Check
      ↓
Orchestrate + Execute
      ↓
Acknowledge
      ↓
Re-ingest Outcome
      ↓
Verify
      ↓
Reconcile
      ↓
Promote / Update Spine
      ↓
Re-project
      ↓
Rehydrate Workbench
      ↓
Continue

46. Adaptive Workbench — compiled, not constructed

The Workbench is compiled rather than manually constructed:

Base Workbench
+ Identity
+ Role / Responsibility
+ Department
+ Industry
+ Permissions
+ Tenant Policy
+ Connected Systems
+ Available Spine Data
+ Available Capabilities
+ Current Lifecycle
+ Active Context
+ User Preferences
+ Observed Work Behaviour
+ Need Queue
= Effective Workbench Projection

Auto-Tuner

The Auto-Tuner belongs inside this projection loop, not beside it as
another platform service:

Activity
    ↓
Need Detection
    ↓
Need Queue
    ↓
Auto-Tuner
    ↓
Projection Tuning Proposal
    ↓
Policy / Governance
    ↓
Projection Engine
    ↓
Workbench Manifest vN+1
    ↓
Rehydrate
    ↓
Observe Outcome

It may reorder, filter, group, create lenses, change information density,
surface capabilities and prioritize queues. It does not mutate canonical
Spine structure, permissions, policy or consequential execution rules.

47. Front-end consolidation — stable shell

The stable shell:

INTEGRATEWISE
│
├── Home
├── My Work
├── Inbox
├── Tasks
├── My Queue
├── Approvals
├── Notifications
│
├── Work
│    └── Adaptive domain / lifecycle projection
│
├── Knowledge / Context
│
└── Platform / Administration

The Twin appears contextually inside these surfaces. Clicking a task gives
the Twin that task, related entities, timeline, signals, memory, policy and
capabilities. Clicking an approval gives it the proposal, evidence,
authority boundary and expected write-back. Clicking an entity gives it
Entity 360 + relationships + memory + timeline.

The older standalone pages (Home, Ask, Memory Timeline, Entity 360,
Continuity, Governance, Connections) become a capability/surface
vocabulary, not the primary application navigation.

48. Twin — consolidated definition

TWIN
=
Context Assembly
+ Retrieval
+ Memory
+ Reasoning
+ Research
+ Explanation
+ Preparation
+ Proposal
+ Coordination
+ Monitoring

It follows the user's work instead of requiring the user to continually
enter a chatbot.

Interaction grammar

OBSERVE  → Store / ingest into Spine
ORIENT   → Ask Your Twin
DECIDE   → Assign Your Twin
ACT      → Approve Twin Action

Authority boundaries

Twin ≠ authority
Twin ≠ source of truth
Twin ≠ direct UI composer
Twin ≠ unrestricted executor

Spine       = truth
Projection  = presentation
Twin        = intelligence
Capability  = ability
Governance  = authority
Runtime     = execution

49. Capability Fabric + MCP Marketplace

MCP is not another product layer. The marketplace exposes the
IntegrateWise/Spine Network into external ecosystems:

Claude / ChatGPT / Gemini / Cursor / VS Code / Enterprise Agent / Other MCP Host
       │
       ▼
IW Spine Network / MCP
       │
       ▼
Identity + Tenant
       │
       ▼
Capability Discovery
       │
       ▼
Capability Resolver
       │
       ├── Native API
       ├── MCP Tool
       ├── Connector
       ├── Agent
       ├── Workflow
       ├── Memory Fetch
       ├── Local Runtime
       └── Tool → Tool

The Workbench doesn't need to understand how an operation executes. It
requests a capability. The resolver determines the execution path;
governance determines whether it may run.

50. Final product model — one platform

                    INTEGRATEWISE
         Governed AI Operating System for Work
                          │
                  ┌───────┴───────┐
                  │               │
              ONE AUTH       SPINE NETWORK
                  │               │
                  └───────┬───────┘
                          ↓
                   ADAPTIVE SPINE
                   canonical truth
                          │
             ┌────────────┼────────────┐
             ↓            ↓            ↓
         Knowledge      Memory      Capabilities
             │            │            │
             └────────────┼────────────┘
                          ↓
                   PROJECTION ENGINE
                          ↓
                  ADAPTIVE WORKBENCH
                          ↕
                  CONTEXTUAL TWIN
                          │
                          ↓
                  CAPABILITY FABRIC
                          │
                          ↓
                     GOVERNANCE
                          │
                          ↓
                 ORCHESTRATION
                          │
                          ↓
                      EXECUTE
                          │
                          ↓
               VERIFY + RECONCILE
                          │
                          └────────→ SPINE
                                       │
                                       ↓
                                   REPROJECT

The Product Boundary Model (Entry, Product, Platform, Flows) is specified in
Part VII §7.2.

The architectural statement

Other work platforms give the user tools for constructing a workspace.
IntegrateWise discovers the work, establishes the operating model in the
Spine, compiles the Workbench, gives the Twin the resulting context,
resolves available capabilities, governs execution, learns from the
outcome, and continuously recompiles the environment around the work.

The invariant

Every UI surface is a projection over the Spine; no surface owns its own
database. The Spine is the contract and the Workbench is the rendering.

---

Part VII — Book-of-Record Baseline (v1.1, 2026-08-06)

This section governs the implementation baseline for IntegrateWise. It unifies product
doctrine, runtime boundaries, storage authority, service ownership, execution contracts,
reconciliation, security, deployment, go-live sequencing, stop-ship rules, and acceptance
criteria.

v1.1 delta (reconciled from v1.0 + August 10 implementation freeze):

1. Formalize ProjectionService → ProjectionEngine → SharedWorkbench
2. Human + Twin as sibling consumers of composed operational context
3. Absorb visible Cognitive Layer functions into Twin
4. Spine Network as external AI/tool ecosystem abstraction
5. OmniRouter inside Capability/Execution Fabric
6. Auto-Tuner → Projection proposal → Projection Engine feedback loop
7. Preserve all v1.0 invariants (storage, isolation, command/event, outbox,
   reconciliation, evidence, security, stop-ship)

7.1 What IntegrateWise Is

IntegrateWise is a self-organizing operational Workbench. It gives every user one place
to understand, decide, communicate, approve, and complete their work while the connected
ecosystem coordinates continuously underneath.

Core promise: One Workbench where the human and AI work together, while the connected
ecosystem operates underneath.

Governing doctrine: Truth you own. AI you rent. Approval in between. Verification
before completion.

Architectural invariant: The Workbench is one. The Spine is one. The Projection is many.

7.2 Product Boundary Model

IntegrateWise has four explicit architectural boundaries:

• Entry — One Auth, MCP Auth, Marketplace discovery, Installation/launch handoffs,
  Consent/permission requests, Host bridges, Workspace activation. Entry does not own
  operational truth, projections, memory, orchestration, governance, or execution.

• Product — The Workbench. Owns personal work surfaces, communications, department
  projections, Twin interaction, AI coworker presentation, inline actions, approvals,
  evidence review, intent capture, operational status display. Does not own credentials,
  connector execution, canonical state, backend orchestration, policy evaluation, provider
  verification, reconciliation.

• Platform — Server-side operating system underneath the Workbench. Owns Gateway,
  Identity/tenancy, Connector authority, Discovery, Business context, Projection, Spine,
  Knowledge, Memory, Continuity, Capability Fabric, ADK, Orchestration, Governance,
  Execution, Reconciliation, Evidence, Search, Notification, Audit, Observability, Security.

• Flows — Activation, Hydration/sync, Work, Cognitive proposal, Approval, Execution,
  Reconciliation, Memory promotion, Projection refresh.

Spine Network is the umbrella abstraction for the external AI/tool ecosystem:

ChatGPT / Claude / Gemini / Cursor / Enterprise Agents
     │        │        │       │             │
     └────────┴────────┴───────┴─────────────┘
                         │
                 One Auth / MCP Auth
                         │
                  Tenant Resolution
                         │
                  Spine Network
                         │
          ┌──────────────┼──────────────┐
          │              │              │
      Resources       Context       Capabilities
          │              │              │
          └──────────────┼──────────────┘
                         ↓
               Governed Platform Runtime

After first activation, another AI host does not create another operational
environment. It resolves the same tenant and receives governed access to the
existing Spine/connection/capability environment.

7.3 Storage Authority

Dual-tier storage topology:

• Neon/PostgreSQL — Tenant registry, organization lifecycle, subscriptions,
  entitlements, deployment manifests, catalog management, platform policies, schema
  versions, usage rollups, tenant runtime routing metadata, provisioning state.
• D1 (per-tenant) — Live operational state: workspaces, users, roles, permissions,
  entities, external identities, relationships, versions, events, tasks, proposals,
  approvals, signals, communications, knowledge metadata, memory, continuity, connections,
  capability grants, execution state, projection manifests, evidence references, audit
  events, sync state, reconciliation state, transactional outbox, idempotency state.

Tenant isolation: One-tenant-to-one-D1-database topology. Every durable D1 record
carries tenant_id for defense in depth, export portability, migration safety, and
forensic traceability.

7.4 Platform Runtime Services

Core services behind the Gateway:

Service	Owns
IdentityService	Users, memberships, roles, permissions, session validation
TenantService	Tenant lifecycle, provisioning, subscriptions, entitlements
MarketplaceService	Connector/plugin/MCP catalog, versions, publication
IntegrationService	Tenant connections, OAuth lifecycle, health, sync cursors
DiscoveryService	Signal discovery, schema discovery, dead-letter routing
BusinessContextService	Effective user context, communication/calendar context
ProjectionService	Projection manifests, views, execution, invalidation
SpineService	Canonical entities, external identity mapping, relationships
WorkService	Tasks, work items, assignments, queues, dependencies
CapabilityService	Capability definitions, versions, grants, invocation auth
GovernanceService	Proposals, approvals, policies, human decision records
ExecutionService	Capability invocations, provider dispatch, retries, failures
ReconciliationService	Expected/observed state, verification, compensation
MemoryService	Memory entries, scopes, promotion, consolidation, retention
ContinuityService	Agent sessions, continuity ledger, checkpoints
EvidenceService	Evidence snapshots, R2 artifacts, integrity, signatures
SearchService	Tenant-scoped search across D1/Vectorize/AI Search
NotificationService	Notification delivery, user preferences
AuditService	Immutable audit events, usage telemetry, cold archive
ObservabilityService	Logs, traces, metrics instrumentation

No service reads another service's database tables directly.

7.5 Command and Event Contracts

Governed Command Envelope — Every mutation enters through one governed command envelope:

interface PlatformCommand<TPayload> {
  commandId: string;
  commandType: string;
  tenantId: string;
  workspaceId?: string;
  actor: { actorId: string; actorType: "user" | "agent" | "system" | "mcp_client" };
  target?: { entityId?: string; entityType?: string };
  payload: TPayload;
  origin: { channel: "workbench" | "connector" | "mcp" | "workflow" | "agent" };
  evidenceRefs: string[];
  confidence?: number;
  requestedAt: string;
  idempotencyKey: string;
}

Platform Event Envelope — Every asynchronous event uses a common envelope:

interface PlatformEvent<TPayload> {
  eventId: string;
  eventType: string;
  eventVersion: number;
  tenantId: string;
  workspaceId?: string;
  aggregateType?: string;
  aggregateId?: string;
  causationId?: string;
  correlationId: string;
  commandId?: string;
  actor?: { actorId: string; actorType: "user" | "agent" | "system" | "mcp_client" };
  payload: TPayload;
  occurredAt: string;
  producer: string;
}

Transactional Outbox — Domain mutation and event publication write atomically to:
Domain record + evidence/source link + local audit event + event_outbox. The outbox
publisher sends events to Cloudflare Queues.

7.6 Projection Contract

The Workbench never reads raw D1 tables. Every read goes through ProjectionService.

Canonical composition chain:

ProjectionService          (platform service boundary)
    │
    └── Projection Engine  (canonical composition engine)
            │
            ├── EntityAssembler
            ├── RelationshipResolver
            ├── KnowledgeEnricher
            ├── SignalEnricher
            ├── CapabilityResolver
            ├── GovernanceEvaluator
            └── ReadinessCalculator
                    │
                    ▼
              SharedWorkbench v1    (frozen composed contract)

Projection formula: Role + Department + Industry + Connected capabilities + Active context

• Permissions + Governance policy = Projected Workbench.

Human + Twin are sibling consumers:

                    SharedWorkbench
                          │
                ┌─────────┴─────────┐
                │                   │
             HUMAN                 TWIN
                │                   │
             Work             Observe
             Decide           Orient
                              Remember
                              Understand
                              Evaluate
                              Recommend
                              Prepare
                              Propose
                │                   │
                └─────────┬─────────┘
                          ↓
                  Capability Fabric
                          ↓
                     Governance

Freshness states:

• CURRENT — Fresh projection succeeded
• STALE — Cached projection returned under policy (unsafe actions disabled)
• FAILED — No permitted projection available

7.6a Auto-Tuner

The Auto-Tuner enters the projection loop as a feedback mechanism. It does not
compose the Workbench (that violates the frozen Projection Engine boundary). It
changes inputs/configuration to composition:

Workbench Activity
        ↓
Observation
        ↓
Need Detection
        ↓
Need Queue
        ↓
Auto-Tuner
        ↓
Projection Adjustment Proposal
        ↓
Policy / Governance
        ↓
Projection Engine
        ↓
SharedWorkbench vN+1
        ↓
Workbench Rehydration
        ↓
Measure Outcome

7.7 Twin and AI Coworker Model

The Twin is a persistent, user-aligned continuity layer. It is proactive but governed.

Twin may: Prepare daily brief, surface tasks, detect pending responses, retrieve
context, organize work, explain changes, draft outputs, identify risks/opportunities,
coordinate coworkers, propose actions, prepare evidence.

Twin may not: Approve its own proposal, alter operational truth, execute without
policy, conceal origin/evidence, claim completion before reconciliation.

Do not create a separate visible Cognitive Layer. The cognitive capabilities are
Twin capabilities. Their backend services remain independently owned, but the user
interaction surface is unified through Twin.

AI coworkers operate through Business Context, ADK, Capability Service, Orchestrator,
Governance, Execution, Reconciliation, Memory, and Evidence.

AI-generated material retains origin, model or agent identity, confidence, evidence,
approval history, and timestamps.

Approval changes authority, not origin.

7.8 Execution and Reconciliation

Canonical flow: Intent → Business Context → Capability resolution → Governance
evaluation → Human approval → Execution dispatch → Provider acceptance → Reconciliation
→ Verified operational state → D1 Spine update → Evidence + Audit + Memory proposal →
Projection refresh.

Capability Fabric v1.1:

Capability Registry
      ↓
Capability Discovery
      ↓
Capability Resolver
      ↓
ADK / Planning
      ↓
Governance
      ↓
OmniRouter
 ├── provider routing
 ├── connector/tool routing
 ├── credential refresh
 ├── tenant-safe caching
 ├── rate limiting
 └── concurrency control
      ↓
ExecutionService
      ↓
Provider

OmniRouter is the execution-routing engine inside the Capability/Execution boundary,
not a separate architectural layer.

Reconciliation states: pending → observing → partially_verified → verified →
failed → compensation_required → compensated → compensation_failed.

Invariant: Provider acceptance is not completion. compensated is never presented
as normal completion.

7.9 Runtime Infrastructure

Technology	Use
D1	Tenant operational Spine
KV	Session metadata, routing, rate limits
R2	Documents, attachments, evidence
Vectorize/AI Search	Derived semantic retrieval
Durable Objects	Live session coordination, presence
Queues	Ingestion, execution, retry
Workflows	Provisioning, migrations, approvals
Workers AI	Edge inference
AI Gateway	Model routing, usage, cost controls

7.10 Security and Zero Trust

• Never trust hostname as authority
• Never trust frontend-supplied tenant identity
• Never trust frontend-supplied role or policy
• Never trust projection hints as grants
• Never trust provider acceptance as success
• Never trust AI output as truth
• Always derive authority server-side

7.11 Go-Live Sequence

1. Contract Freeze — Schemas, command/event envelopes, Projection DTOs, service
   ownership, MCP v1 tools, tenant routing frozen
2. Runtime Provisioning — Neon registry, tenant Worker, per-tenant D1, migrations
3. Core Vertical Loop — One complete path: Connector event → normalization → D1
   Spine → projection → Twin proposal → approval → execution → reconciliation → evidence
4. Product Wiring — Frontend projections, tenant resolution, Workbench tasks/approvals,
   Twin context, live refresh, stale-state indicators
5. Marketplace and Onboarding — Connector catalog, activation, host-projected discovery,
   onboarding bootstrap, first-use hydration, MCP v1 tools
6. Security and Reliability — Idempotency, transactional outbox, immutable audit,
   evidence signatures, tenant-scoped search, fleet monitoring, Customer Zero isolation
7. Release Verification — All 16 verification points from §7.12

7.12 Stop-Ship Rules

Do not release if any of the following is true:

1. The Product reads D1, Neon, or provider SDKs directly
2. Tenant authority is accepted from the frontend
3. A tenant runtime can access another tenant's D1
4. A connector must be reconnected for each surface
5. Twin can approve its own proposal
6. AI output enters operational truth without governance
7. Execution bypasses the governed command path
8. Provider acceptance is displayed as completion
9. Reconciliation history is overwritten
10. Evidence can fail while the mutation succeeds
11. Audit events can be silently dropped
12. Cached projections appear current without freshness metadata
13. MCP exposes internal engine operations
14. Search can retrieve another tenant's context
15. Mock data replaces a failed live projection without disclosure
16. Customer Zero state is accessible from external tenant runtime
17. Idempotent retries can create duplicate external actions
18. Compensation is presented as successful completion

7.13 Acceptance Criteria

The baseline is operationally complete when:

• One Auth can create a tenant and provision its runtime
• Gateway dispatches to the correct tenant Worker
• Every tenant Worker has its own bound D1
• Workbench opens before full historical hydration
• Connector Marketplace supports native, wrapped, and host-projected connectors
• A connector connected once is reusable across authorized surfaces
• Workbench reads use ProjectionService only
• Every mutation uses the governed command envelope
• Every event includes correlation and causation metadata
• Every durable mutation writes an outbox record atomically
• AI proposals preserve origin, confidence, and evidence
• Human approval is cryptographically attributable
• Execution and reconciliation remain separate stages
• UI marks work complete only after verification
• Memory improves continuity without replacing operational truth
• MCP clients receive only semantic, tenant-scoped capabilities
• Search is tenant-scoped
• Audit and evidence are immutable and verifiable
• Customer Zero and external tenants remain isolated

---

Specification amendments (2026-08-06)

SPEC_AMENDMENTS_v1.md contains 15 required implementation
corrections. These amendments are canonical and supersede conflicting statements in all
prior architecture documents. Key changes:

1. Per-tenant D1 routing uses Workers for Platforms dispatch, not dynamic KV binding
2. Isolation claims corrected to database-resource isolation, not physical boundary
3. D1 fleet capacity policy added (thresholds, overflow strategy)
4. Catalog versioning uses separate identity and release tables
5. Idempotency persistence via processed_commands table in per-tenant D1
6. Transactional outbox pattern for atomic domain-write-plus-event
7. WorkService separated from ExecutionService
8. Capability invocation ownership frozen between CapabilityService and ExecutionService
9. Reconciliation model strengthened (missing transitions, observation history)
10. Complete event envelope (PlatformEvent type) with required tracing fields
11. Consistent tenant_id on every durable D1 record
12. Search service renamed to Tenant-Scoped with per-tenant AI Search instances
13. Cached projection fallback requires explicit freshness indicators
14. Cryptographic approval semantics specified (hash chain, signing, verification)
15. Frontend deployment target frozen (Vercel for product, Workers for platform)

Supporting schemas: TENANT_D1_OPERATIONAL_SCHEMA.sql
and CONTROL_PLANE_SCHEMA_AMENDMENTS.sql.

---

Consolidation record

Before	After
94 documents, 265,000 words	1 document + 10 retained specs + 1 amendment + BOR
16 declared canonical	1 canonical + 1 amendment + Book-of-Record baseline
6 files with "canonical" in the name	0
Conflicts resolved by precedence chains	Conflicts resolved in place; evolutions recorded
Drift discoverable only by excavation	Drift register, dated, in Part III

Guiding principle. Success is not more code or more documents. It is better thinking,
coherent architecture, less complexity, and a product customers genuinely adopt. If a change
makes this system harder to explain, it is probably the wrong change.

Truth you own. AI you rent. Approval in between.