{"slug":"architecture/suite-00-34","title":"IntegrateWise — Unified Platform Architecture Suite (00–34)","section":"architecture","sectionLabel":"Architecture","status":"superseded","type":"document","path":"architecture/suite-00-34.mdx","bytes":90437,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Version:** 1.0 — Architecture Freeze \n> **Companion to:** IntegrateWise — Marketplace Onboarding & Persona Architecture (m054+) \n> **Status:** SUPERSEDED — historical architecture suite\n>\n> Do not use as an implementation handoff. Current authority is\n> `ARCHITECTURE_LOCK.md`, `IMPLEMENTATION_CONTRACT_v1.1.md` and\n> `CONSOLIDATED_PRODUCT_PLATFORM_CONTRACT_v1.2.md`.\n\n---\n\n## Unifying Doctrines (held constant across every doc)\n\n1. **Distribution is ingress** — every AI assistant marketplace is a tenant-acquisition channel.\n2. **Truth you own** — the Spine is canonical; AI tools are projections.\n3. **AI you rent** — the LLM provider is plumbable via Cloudflare AI Gateway; no vendor lock.\n4. **Approval in between** — every write that crosses a system boundary passes through the Governance Engine.\n5. **One capability, every surface** — the same `cap_id` resolves identically in Workbench, Twin, Chat, CLI, Slack, Mobile.\n6. **Continuity over asking** — the Spine is the source of context; the Twin never re-asks.\n7. **Persona barrier** — `tenant_spine_config.industry × department` defines the visible universe; users cannot pivot roles by widening scope.\n8. **Hard gates are non-negotiable** — Soft-sync defaulting, 5-minute first-data-load, Promotion-Queue human approval.\n\n---\n\n## Canonical ID Prefixes (used in every section below)\n\n| Prefix | Domain |\n| ------- | --------------------------------------- |\n| `tnt_` | Tenant |\n| `wsp_` | Workspace |\n| `usr_` | User |\n| `ent_` | Entity (any domain object) |\n| `rel_` | Relationship |\n| `tl_` | Timeline entry |\n| `act_` | Activity |\n| `evd_` | Evidence |\n| `sig_` | Signal |\n| `cap_` | Capability |\n| `mem_` | Memory |\n| `knw_` | Knowledge |\n| `tw_` | Twin |\n| `prj_` | Projection |\n| `evt_` | Bus event |\n| `wf_` | Workflow |\n| `gov_` | Governance token |\n| `obs_` | Observability record |\n| `mkt_` | Marketplace listing |\n| `conn_` | Connector |\n| `mod_` | Model |\n| `ag_` | Agent |\n| `plg_` | Plugin |\n| `org_` | Organization |\n| `team_` | Team |\n| `inv_` | Invitation |\n| `sub_` | Subscription / Billing |\n| `bill_` | Invoice / charge |\n| `idx_` | Search index |\n| `pipe_` | Pipeline |\n| `qry_` | Search/Cache query |\n| `tok_` | Identity token (scoped lifecycle token) |\n\n---\n\n## Documentation Hierarchy (00–34)\n\n```\n00 Vision & Doctrine\n01 Platform Architecture\n02 Operational Spine ⭐\n03 Workspace Runtime\n04 Projection Engine\n05 Capability Fabric\n06 Twin Runtime\n07 Memory System\n08 Connector Framework\n09 Governance Engine\n10 Signal Engine\n11 Workflow Engine\n12 Entity Framework\n13 Marketplace\n14 Security\n15 Deployment\n16 Observability\n17 SDKs\n18 UI/Design System\n19 API Contracts\n20 Operations Runbooks\n21 Business Ontology ⭐ (foundational)\n22 AI Model Runtime\n23 Agent Runtime\n24 Integration Manager\n25 Continuity Engine\n26 Search Engine\n27 Data Pipeline\n28 Identity Platform\n29 Billing Platform\n30 Operational Metrics\n31 Evolution Strategy\n32 Plugin Runtime\n33 Testing Architecture\n34 System Lifecycle\n```\n\n---\n\n# PART I: CORE PLATFORM (00–20)\n\n---\n\n## 00 — Vision & Doctrine\n\n### 0.1 Mission\n\nIntegrateWise is the persona-shaped operating system that sits between third-party AI assistants (ChatGPT, Claude, Perplexity, future agents) and the human systems of record (CRM, ERP, ITSM, support, finance). It converts distribution traffic into tenant truth, then operates a Twin on that truth.\n\n### 0.2 Doctrines\n\n- Distribution is ingress.\n- Truth you own.\n- AI you rent.\n- Approval in between.\n- One capability, every surface.\n- Continuity over asking.\n- Persona barrier.\n- Hard gates are non-negotiable.\n\n### 0.3 Non-goals\n\n- Replacing systems of record.\n- Becoming a data lake.\n- Hosting a general-purpose LLM.\n- Operating without a human-in-the-loop for high-governance writes.\n\n### 0.4 Audience map\n\n| Reader | Required docs |\n| ------------------ | --------------------------------------------------------------- |\n| New engineer | 02 Spine, 03 Workspace, 06 Twin, 08 Connector, 19 API Contracts |\n| Persona / product | 00 Doctrine, 04 Projection, 05 Capability, 13 Marketplace |\n| Operator | 14 Security, 15 Deployment, 16 Observability, 20 Runbooks |\n| External developer | 17 SDKs, 18 Design System, 13 Marketplace |\n| Executive | 00 Vision, 02 Spine (data-shape), 13 Marketplace (revenue) |\n\n---\n\n## 01 — Platform Architecture\n\n### 1.1 Reference layers\n\n```\n┌────────────────────────────────────────────────────────────────────┐\n│ Distribution surfaces: ChatGPT · Claude · Perplexity · Web · Slack │\n└────────────────────────────────────────────────────────────────────┘\n ↓\n┌────────────────────────────────────────────────────────────────────┐\n│ Gateway (Cloudflare Worker) RS256 JWT · rate limit · routing │\n└────────────────────────────────────────────────────────────────────┘\n ↓\n┌────────────────────────────────────────────────────────────────────┐\n│ Operational Spine (D1 + DO SQL) canonical entities + timeline │\n└────────────────────────────────────────────────────────────────────┘\n ↓ ↑ ↑\n┌──────────────────────┐ ┌───────────────────────┐ ┌──────────────┐\n│ Projection Engine │ │ Twin Runtime │ │ Workflows │\n│ (Workbench, Persona, │ │ (OODA, Memory, │ │ (triggers, │\n│ Workspace surfaces) │ │ Persona Grammar) │ │ retries) │\n└──────────────────────┘ └───────────────────────┘ └──────────────┘\n ↓\n┌────────────────────────────────────────────────────────────────────┐\n│ Capability Fabric (registry + SDK) sync_mode = soft|real|propose │\n└────────────────────────────────────────────────────────────────────┘\n ↓\n┌────────────────────────────────────────────────────────────────────┐\n│ Connectors (Nango · MCP · Native · AI Provider) outbound writes │\n└────────────────────────────────────────────────────────────────────┘\n ↓\n┌────────────────────────────────────────────────────────────────────┐\n│ Systems of Record (Salesforce, HubSpot, Jira, NetSuite, ...) │\n└────────────────────────────────────────────────────────────────────┘\n```\n\n### 1.2 Subsystem responsibility matrix\n\n| Subsystem | Defined in | Runtime contract template applied |\n| ------------------- | ---------- | --------------------------------- |\n| Operational Spine | 02 | ✔ |\n| Workspace Runtime | 03 | ✔ |\n| Projection Engine | 04 | ✔ |\n| Capability Fabric | 05 | ✔ |\n| Twin Runtime | 06 | ✔ |\n| Memory System | 07 | ✔ |\n| Connector Framework | 08 | ✔ |\n| Governance Engine | 09 | ✔ |\n| Signal Engine | 10 | ✔ |\n| Workflow Engine | 11 | ✔ |\n| Entity Framework | 12 | ✔ |\n| Marketplace | 13 | ✔ |\n| Security | 14 | ✔ |\n| Deployment | 15 | ✔ |\n| Observability | 16 | ✔ |\n| SDKs | 17 | delivery surfaces |\n| UI/Design System | 18 | delivery surfaces |\n| API Contracts | 19 | delivery surfaces |\n| Runbooks | 20 | delivery surfaces |\n\n### 1.3 Runtime-contract template (used identically in 02–13)\n\nEach subsystem spec contains these fields, in this order:\n\n1. Responsibilities — what this subsystem owns.\n2. Inputs — events, APIs, scheduled inputs.\n3. Outputs — events, APIs, persisted rows.\n4. Events produced — names emitted onto the Event Bus.\n5. Events consumed — names subscribed-to from the Event Bus.\n6. APIs — Gateway routes / worker RPCs that touch this subsystem.\n7. State transitions — the lifecycle state machine.\n8. Failure handling — retries, fallbacks, dead-letter.\n9. Extension points — how external code injects behavior.\n\n---\n\n## 02 — Operational Spine ⭐ (canonical, highest priority)\n\n### 2.1 Responsibilities\n\n- Own the canonical entity graph.\n- Own the canonical timeline (event-sourced append-only).\n- Own entity versioning and provenance.\n- Mint canonical IDs (ent\\_… prefix).\n- Resolve merge / conflict between Connector Deltas and proposed writes.\n- Enforce soft-delete vs hard-delete semantics.\n- Serve temporal queries (\"as-of\" reads).\n\n### 2.2 Canonical entity graph\n\n```\nTenant (tnt_)\n ├── Workspace (wsp_)\n │ ├── User (usr_)\n │ ├── Persona (derived from tenant_spine_config)\n │ └── Module bindings\n ├── Entity (ent_) ── typed by Entity Framework (12)\n │ ├── Attribute (typed)\n │ ├── Reference (typed)\n │ └── Lifecycle (draft|active|archived|deleted)\n ├── Relationship (rel_) ── directed, typed, attributed\n ├── Timeline (tl_) ── event-sourced\n │ └── Activity (act_)\n ├── Evidence (evd_) ── citations for any claim\n ├── Signal (sig_) ── derived from delta diffs (10)\n ├── Capability (cap_) ── declared actions (05)\n └── Memory (mem_) ── three-axis:\n ├── Spine-truth (L1)\n ├── Twin-meaning (L7 of pipeline → see 07)\n └── Knowledge-doc (SOPs, runbooks)\n```\n\n### 2.3 Canonical IDs\n\n- Type-prefixed nanoid (collision-resistant, URL-safe).\n- Tenants carry `tnt_id`; workspaces scoped under tenant with `wsp_id`.\n- Cross-tenant references are forbidden except via `rel_external` and an explicit Marketplace grant (see 13).\n- Every ID has a 32-byte SHA-256 content-hash sidecar so duplicates can be detected without a lookup.\n\n### 2.4 Entity lifecycle\n\n```\ndraft ──▶ active ──▶ archived ──▶ (soft-deleted)\n ▲ │ │\n │ ▼ ▼\n └────── proposed ◀── restore\n │\n ▼\n hard-deleted (judicial only; tenant_id + actor + signed reason required)\n```\n\n- **Soft delete:** `lifecycle.status = \"deleted\"`, retained 90 days, hidden from projections.\n- **Hard delete:** requires Governance Token (09) with `gov.posture=judicial` and an immutable audit record (16).\n\n### 2.5 Timeline model\n\n- Append-only timeline table keyed by `tl_id`.\n- Every state change creates one Timeline entry; the row in the entity table is a projection of the latest Timeline entry.\n- Form: `{ tl_id, tnt_id, ent_id, kind, payload, actor, occurred_at, source_connector, evidence_refs[] }`.\n\n### 2.6 Relationship graph\n\n- Directed, typed, attributed edges in relationship (`rel_`).\n- Allowed types: `belongs_to`, `depends_on`, `references`, `derived_from`, `supersedes`, `contested_by`.\n- Graph traversal API: `POST /spine/graph/traverse { from, edge[], to?, depth, as_of? }` returns a DAG slice as-of `as_of`.\n\n### 2.7 Event model (Spine-internal)\n\n| Event | Producer | Notes |\n| ---------------------- | ------------ | --------------------------- |\n| EntityCreated | 02 | new ent\\_ |\n| EntityUpdated | 02 | attribute mutation |\n| EntityMerged | 02 | conflict resolution applied |\n| EntityArchived | 02 | lifecycle change |\n| RelationshipAsserted | 02 | new rel\\_ |\n| RelationshipRetracted | 02 | withdrawn edge |\n| TimelineAppended | 02 | always emitted, fan-out |\n| ProvenanceRecorded | 02 | evidence link added |\n| SpineSnapshotRequested | 20 / runbook | scheduled export |\n| VersionPinned | 02 | explicit as-of point |\n\n### 2.8 Versioning\n\n- Each Entity row carries `version` (monotonic per entity).\n- Every mutation increments version; never decrements.\n- Temporal query `?as_of=ISO8601` reads Timeline to reconstruct.\n- Schema migrations bump `tenant_spine_config.schema_version` (aligned to m054+).\n\n### 2.9 Provenance\n\n- Every Entity / Relationship row carries `provenance[]`: at least one of `{ actor, source_connector, evidence_ref, derived_signal }`.\n- `derived_signal` requires the originating `sig_id` to be reproducible.\n- Provenance is required for any field flagged `pinned` in the Entity Framework (12).\n\n### 2.10 Merge / conflict rules\n\n| Source | Authoritative for | Loses to |\n| -------------------------------- | ----------------------- | ---------------------------------- |\n| Connector Delta (≤ 30s old) | field-level truth | local edit during soft-sync window |\n| Local edit (pending soft-sync) | during soft-sync window | Connector Delta after window |\n| Twin proposal (pending approval) | never (read-only) | always |\n| Hard governance action | always | all |\n\n**Rule of thumb:** most-recent timestamp wins, except (a) pinned fields never auto-update, (b) governance-required fields always block, (c) explicitly merged events track both sides.\n\n### 2.11 Soft vs hard deletion\n\n- Soft delete is the default; surfaces omit the row.\n- Hard delete requires `gov.judicial` token (09) and is recorded in `audit_log` (16) forever.\n- Cross-tenant hard delete is impossible.\n\n### 2.12 Temporal queries\n\n```\nGET /spine/entities/ent_abc123 # latest\nGET /spine/entities/ent_abc123?as_of=2025-03-01T00:00:00Z\nGET /spine/relationships?from=ent_a&to=ent_b&as_of=…\n```\n\n- All temporal reads go through `spineRead` MCP tool; no Workbench code may bypass it.\n\n### 2.13 Storage (D1 + Durable Objects)\n\n- **Hot metadata:** D1 (`spine.entities`, `spine.relationships`, `spine.timeline`, `spine.provenance`).\n- **Per-tenant Durable Object:** `SpineDO{tnt_id}` for transactional consistency of a tenant's write stream.\n- **Cold snapshots:** R2 (`/snapshots/{tnt_id}/{date}.parquet`).\n\n### 2.14 APIs\n\n| Method | Path | Purpose |\n| ------ | ------------------------ | -------------------------------- |\n| POST | /spine/entities | create entity |\n| PATCH | /spine/entities/{ent_id} | mutate (issues TimelineAppended) |\n| GET | /spine/entities/{ent_id} | read (with ?as_of) |\n| POST | /spine/relationships | assert |\n| GET | /spine/graph/traverse | DAG slice |\n| GET | /spine/timeline | paginate timeline |\n| POST | /spine/restore/{ent_id} | from soft-delete |\n\n### 2.15 Failure handling\n\n- D1 retry: exponential, 5 attempts, ≤ 30s.\n- DO retry: 3 attempts; on exhaustion → deferred_queue (Cloudflare Queue) with `evt_id`.\n- Temporal read with missing Timeline entries: surface \"incomplete provenance\" banner instead of silent fallback.\n\n### 2.16 Extension points\n\n- Custom entity types (12) registered at `tenant_spine_config.enabled_entities[]`.\n- Custom provenance reporters (e.g., SHA-pinning artifacts).\n- Custom merge strategies via plugin interface `SPINE_MERGE_PLUGIN(name)`.\n\n---\n\n## 03 — Workspace Runtime\n\n### 3.1 Responsibilities\n\n- Define the Workspace unit (Personal / Work / Business).\n- Hold per-workspace context, projections, module set, layout, and persistence.\n- Handle workspace switching without losing Twin continuity (Continuity Bridge).\n\n### 3.2 Workspace definition\n\n```yaml\nworkspace_id: wsp_abc\ntenant_id: tnt_xyz\ntype: personal | work | business\npersona: { department: CTX_SALES, industry: saas_tech, sub_role: AE }\nmodules: [leads, accounts, deals, signals]\nlayout: ref→ prj_layout_01\ncreated_at, updated_at, archived_at\n```\n\n### 3.3 Lifecycle\n\n```\ninit ──▶ bootstrapping ──▶ active ──▶ suspended ──▶ archived\n └──▶ migrated (tenant merge)\n```\n\n### 3.4 Inputs\n\n- Onboarding completion event (per existing spec).\n- Manual add/remove of modules and layouts.\n- Administrator actions.\n\n### 3.5 Outputs\n\n- Workbench projection mount points.\n- Persona-side module compatibility matrix.\n- Continuity Bridge context bundle (delivered to Twin on switch).\n\n### 3.6 Events\n\n- **Produced:** WorkspaceCreated, WorkspaceSwitched, WorkspaceModuleAdded, WorkspaceModuleRemoved, WorkspaceArchived, WorkspaceMigrated.\n- **Consumed:** `onboarding_complete=true`, TenantMerged, UserRoleChanged.\n\n### 3.7 APIs\n\n`POST /workspaces`, `GET /workspaces/{wsp_id}`, `POST /workspaces/{wsp_id}/switch`, `POST /workspaces/{wsp_id}/modules/{module_id}`, `DELETE /workspaces/{wsp_id}/modules/{module_id}`.\n\n### 3.8 State transitions\n\nSwitching is a `WorkspaceSwitched` event and updates `user.last_workspace_id`; the Twin suspends but does not lose memory.\n\n### 3.9 Failure handling\n\n- Module load failure → fallback to \"minimal\" module set (always-on: leads, signals, evidence).\n- Migration failure → block switch, surface diff in Workbench.\n\n### 3.10 Extension points\n\n- Custom modules (see 12).\n- Custom layouts persisted via 18 (Design Tokens) but routed through Projection Engine (04).\n\n---\n\n## 04 — Projection Engine\n\n### 4.1 Responsibilities\n\n- Project the Spine into Workbench, Persona, Workspace, and React components.\n- Own cursor strategy, pagination, widget layouts, and per-persona defaults.\n\n### 4.2 Pipeline\n\n```\nSpine (02) ──▶ Projection Engine ──▶ Persona (06) ──▶ Workspace (03) ──▶ React Components (18)\n```\n\n### 4.3 Inputs\n\n- Spine reads (with as_of).\n- Persona fits from `tenant_spine_config`.\n- Workspace layout ref.\n- User viewport, locale, density.\n\n### 4.4 Outputs\n\n- Render-tree JSON (workbench), iframe-bundle (webview), push payload (mobile/Slack).\n\n### 4.5 Events\n\n- **Produced:** ProjectionBuilt, ProjectionStale, ProjectionInvalidated.\n- **Consumed:** every evt\\_… from Spine (02), PersonaChanged, WorkspaceSwitched.\n\n### 4.6 APIs\n\n`POST /project/build`, `GET /project/{prj_id}?as_of=…`, `POST /project/{prj_id}/invalidate`.\n\n### 4.7 State transitions\n\n`pending → building → fresh → stale → invalid → fresh`.\n\n### 4.8 Failure handling\n\n- Incomplete Spine data → render safe-empty with explicit chip (\"Evidence partial\").\n- Persona mismatch → render lockout (Persona Barrier).\n\n### 4.9 Extension points\n\n- Custom widget renderer (Widget SDK — listed under 17).\n- Custom projection transforms `PROJECTION_TRANSFORM(name)`.\n\n---\n\n## 05 — Capability Fabric\n\n### 5.1 Responsibilities\n\n- Host the capability registry (`cap_id`).\n- Resolve invocation surfaces uniformly.\n- Bind sync mode (soft | real | propose) and rollback strategy.\n- Mint governance tokens when required.\n\n### 5.2 Capability definition\n\n```yaml\nid: cap_draft_outreach # canonical\nname: Draft Outreach\ndescription: Free-text. Includes the persona-fit profile.\nversion: 1.4.2\ninputs:\n to_lead_id: { type: ent_id, required: true, scope: leads }\n template_id: { type: ent_id, required: false }\n personalization: { type: string, required: false, max: 4000 }\noutputs:\n draft_id: { type: ent_id, scope: messages }\n confidence: { type: number, range: [0, 1] }\nrequiredScopes: [leads:read, messaging:write]\nconfidenceThreshold: 0.7\ndefaultSyncMode: soft\ngovernancePolicy: propose\nauditSchema: { actor, lead_id, delta_text_hash, proposal_only }\nrollbackStrategy: delete_draft\nsurfaceCompatibility:\n workbench: true\n twin: true\n chat: true\n cli: true\n slack: true\n mobile: true\n```\n\n### 5.3 Lifecycle\n\n```\ndeclared ──▶ registered ──▶ versioned ──▶ deprecated ──▶ removed\n │\n └──▶ revoked (security incident)\n```\n\n### 5.4 Inputs\n\n- Capability SDK / manifest submission.\n- Admin overrider via governance_posture.\n\n### 5.5 Outputs\n\n- A capability invocation record `cap_invocation` and the corresponding `gov_token` when applicable.\n\n### 5.6 Events\n\n- **Produced:** CapabilityRegistered, CapabilityDeprecated, CapabilityInvoked, CapabilityCompleted, CapabilityFailed, CapabilityRolledBack.\n- **Consumed:** PersonaChanged, ConnectorHealthyChanged, WorkspaceSwitched, TwinProposing.\n\n### 5.7 APIs\n\n`POST /capabilities`, `POST /capabilities/{cap_id}/invoke`, `GET /capabilities/{cap_id}/invocations`.\n\n### 5.8 State transitions (per invocation)\n\n`requested → validated → authorized → executing → succeeded | failed | rolled_back`.\n\n### 5.9 Failure handling\n\n- Auth failure → reject before Connector call.\n- Connector call failure → invoke rollbackStrategy; emit CapabilityFailed.\n- Replay protection via idempotency key in the capability invocation row.\n\n### 5.10 Extension points\n\n- Vendors may register new capabilities via Marketplace (13).\n- Conflicting capability ids rejected by prefix rule.\n\n---\n\n## 06 — Twin Runtime\n\n### 6.1 Responsibilities\n\n- Drive the OODA loop for the user-facing Twin.\n- Compose context, prompt, persona grammar, evidence, tool calls, capability selections.\n- Calibrate confidence and produce proposals.\n\n### 6.2 Flow\n\n```\nUser input / screen-state\n ↓\nContext Builder (Continuity Bridge, persona, screen)\n ↓\nMemory Retrieval (07; references L1–L7)\n ↓\nEvidence Ranking (02; evd_ refs sorted by recency + relevance)\n ↓\nPrompt Builder (Persona Grammar)\n ↓\nLLM call (Cloudflare AI Gateway, plumbed provider)\n ↓\nTool selection (resolve capability or read-only spineRead)\n ↓\nConfidence calibration (cap.confidenceThreshold)\n ↓\nProposal generation (cap.governancePolicy == propose)\n ↓\nTwin response (Message Object: blocks, evidence, snapshots, actions)\n```\n\n### 6.3 Persona Grammar\n\n- Maya (Sales) — terse, action-oriented.\n- Sana (CS) — cautious, evidence-heavy.\n- Tomás (Engineering) — diagnostic.\n- (Others inherited; persona grammar ref: `twin_greeting_id` and `persona_grammar_ref` in `tenant_spine_config`.)\n\n### 6.4 Activation gate (safety invariant)\n\n- Existing `evaluateActivation` from original spec preserved.\n- Additional checks: minimum memory depth (L7 has at least one approved item), governance posture set, Continuity Bridge non-empty.\n\n### 6.5 Inputs\n\n- User chat / surface action.\n- Screen-state projection (04).\n- Continuity Bridge context.\n\n### 6.6 Outputs\n\n- Message Object per existing spec.\n- Capability invocations (05).\n- Memory intakes (07 → L1).\n\n### 6.7 Events\n\n- **Produced:** TwinResponded, TwinProposing, TwinContextBuilt, TwinMemoryIntake.\n- **Consumed:** every Projection/Stale from 04, every Memory Approve/Reject from 07, every Governance Decision from 09.\n\n### 6.8 APIs\n\n`POST /twin/chat`, `POST /twin/propose`, `GET /twin/messages/{msg_id}`.\n\n### 6.9 State transitions (per turn)\n\n`received → building → proposing | executing → responded → archived`.\n\n### 6.10 Failure handling\n\n- LLM timeout → degrade to \"Last Good Answer\" projection; mark `TwinResponded(stale=true)`.\n- Persona Grammar missing → fallback to neutral; warn.\n- Memory retrieval empty → operation continues with explicit \"no prior context\" chip.\n\n### 6.11 Extension points\n\n- Custom persona grammar via `twin.grammar` package.\n- Custom tool resolvers.\n\n---\n\n## 07 — Memory System\n\n### 7.1 Responsibilities\n\n- Own the 8-layer memory pipeline (already defined in original spec).\n- Bind the three-axis separation: Spine (truth), Memory (meaning), Knowledge (docs).\n- Operate the Promotion Queue as the human-in-the-loop gate.\n\n### 7.2 The eight layers\n\n```\nL1 Twin Memory — conversational working memory (ephemeral, ≤10 turns)\nL2 Memory Intake — raw observations, immutable for 24h\nL3 Triage Bot — classification (fact | decision | observation | relationship | noise)\nL4 Memory Evolution — pattern detection (cluster, dedupe, propose promotion)\nL5 Promotion Queue — staging surface (single most important screen)\nL6 Human Approval — gating event (MemoryApproved | MemoryRejected)\nL7 Organizational Memory — durable, indexed, queryable\nL8 Knowledge — SOPs, playbooks, runbooks (curated from L7 + human authored)\n```\n\n### 7.3 Inputs\n\n- TwinMemoryIntake events (from 06).\n- Manual memory creation (Admin).\n- Knowledge imports (Markdown, Docs).\n\n### 7.4 Outputs\n\n- Promotion Queue items.\n- L7 search hits (`mem.search(…\")`).\n- Knowledge article refs.\n\n### 7.5 Events\n\n- **Produced:** MemoryTriaged, MemoryPromoted, MemoryApproved, MemoryRejected, MemoryDeprecated, KnowledgeArticlePublished.\n- **Consumed:** TwinMemoryIntake, EntityUpdated (to evolve), AdminMemoryEdited.\n\n### 7.6 APIs\n\n`POST /memory/intake`, `GET /memory/promotion-queue`, `POST /memory/{mem_id}/approve`, `POST /memory/{mem_id}/reject`, `GET /memory/search`.\n\n### 7.7 State transitions\n\n`intake → triaged → cluster → queued_for_promotion → approved | rejected → deprecated`.\n\n### 7.8 Failure handling\n\n- Triage bot mis-classifies → user may re-tag (human-in-the-loop).\n- Stuck queue → admin SLA alert (16).\n\n### 7.9 Extension points\n\n- Custom Triage Bot rules.\n- Custom Evolution patterns.\n\n---\n\n## 08 — Connector Framework\n\n### 8.1 Responsibilities\n\n- Own connector lifecycle (declared → registered → healthy → degraded → retired).\n- Manage authentication, refresh, sync policy, retry, conflict, health.\n\n### 8.2 Lifecycle\n\n```\ndeclared ──▶ sandboxed ──▶ certified ──▶ active ──▶ degraded ──▶ retired\n │ │ │\n ▼ ▼ ▼\n revoked recovering archived\n```\n\n### 8.3 Adapter interface (canonical contract)\n\n```typescript\ninterface ConnectorAdapter {\n id: string; // e.g., \"salesforce\"\n version: string;\n scopes: string[];\n\n // discovery\n capabilities(): CapabilityDescriptor[];\n\n // lifecycle\n install(ctx): Promise;\n uninstall(ctx): Promise;\n refresh(ctx): Promise;\n health(): Promise;\n\n // data plane\n pull(since): AsyncIterable;\n push(intent): Promise;\n revert(intent, reason): Promise;\n\n // error model\n classify(err): ErrorClass; // transient | permission | schema | rate | fatal\n}\n```\n\n### 8.4 Authentication lifecycle\n\n- OAuth via Nango.\n- Tokens stored vault-side (14).\n- Refresh on `expires_in * 0.75` margin.\n- Per-tenant secret rotation cadence.\n\n### 8.5 Sync policies\n\n- Soft sync (default for sensitive industries), Real sync (default for high-volume mutations), Propose→Approve (default for high-risk actions).\n- Conflict resolution deferred to Spine (02) by emitting a Connector Delta.\n\n### 8.6 Retry policy\n\n- **Transient:** 5 attempts, exponential with jitter.\n- **Permission:** 0 retry, surface via Workbench banner requiring admin action.\n- **Schema:** 0 retry, dataclass outlier → admin queue.\n- **Rate:** token-bucket per vendor (Cloudflare Queue throttle).\n- **Fatal:** connector retired and HealthChanged emitted.\n\n### 8.7 Health monitoring\n\n`HealthSnapshot { status: healthy | degraded | down, latency_ms, error_rate, last_sync_at, breaker_state }`.\n\n### 8.8 Inputs\n\n- Vendor API events (webhooks), Connector Deltas.\n- Admin actions (install/uninstall/revoke).\n\n### 8.9 Outputs\n\n- Connector Deltas → Spine (02).\n- ConnectorHealthyChanged events → Workflows, Signals.\n\n### 8.10 Events\n\n- **Produced:** ConnectorInstalled, ConnectorSynced, ConnectorHealthyChanged, ConnectorDeltaReceived, ConnectorRefreshed, ConnectorRetired.\n- **Consumed:** UserRoleChanged, WorkspaceArchived, TenantMerged.\n\n### 8.11 APIs\n\n`POST /connectors`, `DELETE /connectors/{conn_id}`, `POST /connectors/{conn_id}/sync`, `GET /connectors/{conn_id}/health`.\n\n### 8.12 State transitions\n\nPer state machine in 8.2, with breaker transitions on health.\n\n### 8.13 Failure handling\n\n- Consecutive failures > N → degraded then down, emit ConnectorHealthyChanged.\n- Backoff + dead-letter queue (Cloudflare Queue).\n\n### 8.14 Extension points\n\n- New connectors authored against SDK (17).\n- Custom retry policy per vendor.\n\n---\n\n## 09 — Governance Engine\n\n### 9.1 Responsibilities\n\n- Issue governance tokens (`gov_…`) before any high-risk write.\n- Enforce approval chains and confidence thresholds.\n- Drive multi-level approvals and delegations.\n- Operate emergency overrides.\n\n### 9.2 Approval chain\n\n- Confidence ≥ 0.85 → auto-approve (subject to posture).\n- 0.70 ≤ Confidence < 0.85 → single approver.\n- Confidence < 0.70 → multi-level approver chain.\n- `governancePolicy = judicial` → N-of-M approvers; cannot be auto-approved.\n\n### 9.3 Token minting\n\n```yaml\ngov_token:\n id: gov_abc\n capability_id: cap_update_field\n ent_id: ent_lead_123\n delta: { … }\n posture: propose | judicial | auto\n approver_chain: [usr_mgr, usr_director]\n expires_at: ISO8601\n audit_ref: obs_audit_…\n```\n\n### 9.4 Policy engine\n\n- Policies declared in `tenant_spine_config.governance_posture` (per existing spec).\n- Policies can be capability-scoped, entity-typed, or field-pinned.\n\n### 9.5 Emergency overrides\n\n- Break-glass token requires MFA + auto-creates AuditEvent flagged `severity=emergency` (16).\n\n### 9.6 Inputs\n\n- CapabilityInvoked with governancePolicy != null.\n- Admin overrides.\n\n### 9.7 Outputs\n\n- `gov_token` issued, then CapabilityAuthorized event.\n\n### 9.8 Events\n\n- **Produced:** GovernanceRequested, GovernanceApproved, GovernanceRejected, GovernanceTokenMinted, GovernanceOverrode.\n- **Consumed:** CapabilityInvoked, AdminOverrideRequested.\n\n### 9.9 APIs\n\n`POST /governance/request`, `POST /governance/{gov_id}/approve`, `POST /governance/{gov_id}/reject`.\n\n### 9.10 State transitions\n\n`requested → pending_approval → approved | rejected | overrode | expired`.\n\n### 9.11 Failure handling\n\n- Approver unavailable → fallback to next in chain + SLA breach (16).\n- Expired token → re-request.\n\n### 9.12 Extension points\n\n- Custom policies via `POLICY_PACK(name)`.\n- Delegated approvers.\n\n---\n\n## 10 — Signal Engine\n\n### 10.1 Responsibilities\n\n- Detect deltas, classify them, score them, surface them as Signals, derive Insights, and feed Proposals into Twin.\n\n### 10.2 Pipeline\n\n```\nConnector Delta ──▶ Detection Rule ──▶ Aggregation ──▶ Scoring ──▶ Priority ──▶ Signal ──▶ Insight ──▶ Proposal\n```\n\n### 10.3 Signal definition\n\n```yaml\nsig_id: sig_abc\nkind: risk | opportunity | anomaly | trend | slip\nsubject: ent_lead_123\nscore: 0..1\npriority: p0 | p1 | p2 | p3\ndetected_at: ISO8601\nttl: duration\nprovenance: […]\n```\n\n### 10.4 Detection Rule (DSL)\n\n```yaml\nrule:\n id: sig_rule_renewal_risk_30d\n trigger: ConnectorDelta(conn=salesforce, object=opportunity, field=close_date)\n condition: close_date - today <= 30d AND stage_change_count >= 2\n aggregate: over(7d) by ent_account_id\n score: 0.8\n priority: p1\n downstream: [signal, insight, proposal_cap_mark_renewal_risk]\n```\n\n### 10.5 Inputs\n\n- ConnectorDeltaReceived (08).\n- Memory evolution events (07) for cross-source patterns.\n\n### 10.6 Outputs\n\n- SignalCreated, InsightDerived, ProposalGenerated.\n\n### 10.7 Events\n\n- **Produced:** SignalCreated, SignalScored, InsightDerived, ProposalGenerated, SignalExpired.\n- **Consumed:** ConnectorDeltaReceived, MemoryPromoted.\n\n### 10.8 APIs\n\n`POST /signals/rules`, `GET /signals?priority=…`, `POST /signals/{sig_id}/accept`, `POST /signals/{sig_id}/dismiss`.\n\n### 10.9 State transitions\n\n`detected → scored → surfaced → accepted | dismissed | expired`.\n\n### 10.10 Failure handling\n\n- Rule evaluation failure → dead-letter queue.\n- Signal TTL elapsed → emit SignalExpired.\n\n### 10.11 Extension points\n\n- New detection rules via Marketplace (13) or admin SDK.\n\n---\n\n## 11 — Workflow Engine\n\n### 11.1 Responsibilities\n\n- Run deterministic, retryable, schedulable automations triggered by Events.\n- Compose capabilities (05) with approvals (09) and human tasks.\n\n### 11.2 Anatomy\n\n```yaml\nworkflow:\n id: wf_renewal_save_play\n trigger: SignalCreated(kind=risk, score>=0.7)\n steps:\n - call: cap_mark_renewal_risk\n with: { lead_id: trigger.subject }\n on_error: notify_owner\n - human_task: review_renewal_plan\n assignee: owner\n - call: cap_schedule_call\n with: { lead_id: trigger.subject, when: +2d }\n retries:\n cap_mark_renewal_risk: 3 backoff=exp\n schedule: none\n```\n\n### 11.3 Inputs\n\n- Any Event Bus event by name.\n- Cron schedules.\n\n### 11.4 Outputs\n\n- Step records and final outcome event WorkflowCompleted | WorkflowFailed.\n\n### 11.5 Events\n\n- **Produced:** WorkflowStarted, WorkflowStepCompleted, WorkflowHumanTaskCreated, WorkflowCompleted, WorkflowFailed, WorkflowRetried.\n- **Consumed:** all event bus events (filtered by trigger).\n\n### 11.6 APIs\n\n`POST /workflows`, `POST /workflows/{wf_id}/run`, `GET /workflows/runs/{run_id}`.\n\n### 11.7 State transitions\n\n`scheduled → running → waiting_human → running → completed | failed`.\n\n### 11.8 Failure handling\n\n- Per-step retries, exponential, max configurable.\n- After max retries → WorkflowFailed + admin notification.\n\n### 11.9 Extension points\n\n- New step types (including external HTTP), marketplace-distributed templates.\n\n---\n\n## 12 — Entity Framework\n\n### 12.1 Responsibilities\n\n- Define the canonical entity types permitted per tenant (`enabled_entities`).\n- Provide inheritance, dynamic fields, industry extensions, validation.\n\n### 12.2 Inheritance\n\n```\nEntity (base: id, version, lifecycle, provenance)\n ├── AggregateEntity (typed by purpose)\n │ ├── CRMAccount (inherits references[] → contacts)\n │ ├── CRMLead\n │ ├── CRMOpportunity\n │ ├── Ticket\n │ ├── Invoice\n │ └── …\n └── ReferenceEntity\n ├── User\n ├── Product\n └── …\n```\n\n### 12.3 Dynamic fields\n\n- Schema-additive. Each tenant may add fields via `tenant_spine_config.field_extensions[]`.\n- Fields typed `string | number | date | ref | enum | json`.\n\n### 12.4 Industry extensions\n\n- Declared in the 12×11 matrix; example for Healthcare: `phi_flag`, `consent_ref`, `hipaa_scope`.\n\n### 12.5 Validation\n\n- Type-level validators per field.\n- Cross-entity validators (e.g., `opportunity.amount > 0 AND opportunity.stage != closed`).\n- Validator plugins `VALIDATOR(name)`.\n\n### 12.6 References and graph traversal\n\n- Reference integrity checked via Spine (02).\n\n### 12.7 Events\n\n- **Produced:** EntityTypeRegistered, EntityExtensionAdded.\n- **Consumed:** OnboardingComplete to seed enabled entities.\n\n### 12.8 APIs\n\n`POST /entity-types`, `POST /entity-types/{type}/fields`, `POST /entities/validate`.\n\n### 12.9 Failure handling\n\n- Validation failure blocks write; suggests fix in the error message.\n- Extension conflicts surface as admin warnings.\n\n---\n\n## 13 — Marketplace\n\n### 13.1 Responsibilities\n\n- Listings for Connectors, Capabilities, Workflows, Design Packs, Persona Kits.\n- Installation, upgrade, uninstall, reinstallation, tenant migration.\n\n### 13.2 Listing model\n\n```yaml\nmkt_listing:\n id: mkt_listing_…\n vendor: org_…\n kind: connector | capability | workflow | design_pack | persona_kit\n version: semver\n visibility: public | tenant_only | beta\n permissions: [scopes…]\n pricing: free | trial | metered | seat\n trial_days: 14\n artifacts: [signed bundle URLs]\n audits: last_review_at, reviewer\n```\n\n### 13.3 Installation lifecycle\n\n```\ndiscover ──▶ trial ──▶ purchase ──▶ installed ──▶ upgraded ──▶ (uninstalled | reinstalled)\n │ │ │\n ▼ ▼ ▼\n refunded downgraded archived\n```\n\n### 13.4 Tenant migration\n\n- Migrating a listing installation is a re-bind; IDs preserved via `installation_id`.\n- Revoked listing → all hanging tenants receive `ListingRevoked` event.\n\n### 13.5 Permissions / Billing / Trial / Uninstall / Reinstall\n\n- Permissions enforced by Governance (09) on first invocation.\n- Billing via Stripe (CF Worker integration); usage events emitted for metered SKUs.\n- Trial marks tenant with `trial=true`; expiry triggers downgrade flow.\n- Uninstall revokes tokens, archives projection cache, retains audit (16).\n- Reinstall uses `installation_id` to keep Connector credentials rotation-safe.\n\n### 13.6 Events\n\n- **Produced:** ListingInstalled, ListingUpgraded, ListingTrialStarted, ListingUninstalled, ListingRevoked, ListingBilled.\n- **Consumed:** CapabilityRegistered, WorkflowRegistered.\n\n### 13.7 APIs\n\n`POST /marketplace/listings`, `POST /marketplace/install`, `POST /marketplace/{mkt_id}/uninstall`, `POST /marketplace/{mkt_id}/upgrade`.\n\n### 13.8 Failure handling\n\n- Install auth failure → reject + admin notification.\n- Uninstall mid-call → mark pending then finalize.\n\n### 13.9 Extension points\n\n- Vendors onboard through SDK (17), validated by automated review and manual sign-off.\n\n---\n\n## 14 — Security Architecture\n\n### 14.1 Responsibilities\n\n- Zero Trust model at the Gateway and Worker level.\n- Tenant isolation, secrets, keys, encryption, RBAC inheritance, ABAC, sessions.\n\n### 14.2 Tenets\n\n- Every request is authenticated.\n- Every request is authorized for the specific tenant + workspace + entity.\n- Secrets never leave the Vault.\n- Encryption at rest (D1+R2) and in transit (HTTPS).\n\n### 14.3 Tenant isolation\n\n- **Logical:** row-level multi-tenancy via `tnt_id` predicate in every query.\n- **Physical:** per-tenant D1 partition (`tnt_id` sharding key) + per-tenant DO.\n- **Network:** egress to connectors only via Nango + allowlist.\n\n### 14.4 Secret management\n\n- Cloudflare Secrets + KMS-backed envelope.\n- Key rotation cadence: 90 days for connector tokens; 30 days for signing keys.\n\n### 14.5 RBAC inheritance\n\n- Roles (`rbac_roles`) inherit capabilities and permissions.\n- `rbac_users.scope` is the persona barrier.\n\n### 14.6 ABAC layer\n\n- Attribute-based decisions supplement RBAC: time-of-day, region, device posture, signal severity.\n\n### 14.7 Session management\n\n- Short-lived signed JWTs (≤ 30 min), refresh-token chain bound to device fingerprint.\n- Re-auth required on tenant switch.\n\n### 14.8 Events\n\n- SecurityAlert, SecretRotated, KeyRotated, SessionAnomalous.\n\n### 14.9 APIs\n\n`GET /security/policies`, `POST /security/secrets/{name}/rotate`, `POST /security/sessions/{sid}/revoke`.\n\n### 14.10 Failure handling\n\n- Repeated anomalies → account lock + alert (16).\n\n### 14.11 Extension points\n\n- ABAC pluggable via `POLICY_PACK(name)`.\n\n---\n\n## 15 — Deployment Architecture\n\n### 15.1 Cloudflare-native topology\n\n```\nCloudflare\n │\n ▼\nGateway (Worker) ── auth, routing, rate limit\n │\n ▼\nWorkers (stateless compute) ── Twin, Memory, Signals, Workflows, Marketplace\n │\n ▼\nQueues ── retries, dead-letter\n │\n ▼\nD1 + DO ── Spine, RBAC, projections\n │\n ▼\nKV ── capability registry, persona greetings cache\n │\n ▼\nR2 ── snapshots, audit archive, listing bundles\n │\n ▼\nDurable Objects ── per-tenant SpineDO, TwinAgent DO, TenantBrainDO\n │\n ▼\nExternal Connectors ── via Nango + MCP\n```\n\n### 15.2 Environments\n\n| Env | Purpose |\n| ------- | --------------------------------- |\n| dev | personal compute |\n| staging | synthetic tenant population |\n| prod | multi-region (CF smart placement) |\n\n### 15.3 Release strategy\n\n- Dark-launch via feature flag (FeatureFlag per tenant).\n- Progressive rollout 1% → 10% → 50% → 100%.\n- Rollback via flag flip.\n\n### 15.4 Migration strategy\n\n- Versioned migrations, reversible, dry-run in staging.\n- Schema migration bumps `tenant_spine_config.schema_version` (m054+).\n\n### 15.5 Failure handling\n\n- Worker crash → DO alarm catches; CF retry + Queue.\n\n### 15.6 Extension points\n\n- Region pinning per tenant.\n\n---\n\n## 16 — Observability\n\n### 16.1 Responsibilities\n\n- Traces, logs, metrics, audits, healthchecks, service map.\n\n### 16.2 Trace model\n\n- OpenTelemetry-compatible spans, exported via Cloudflare Logpush → Honeycomb/Datadog.\n\n### 16.3 Logs\n\n- Structured JSON, `tnt_id` always present, retain 90 days hot, 1 year cold.\n\n### 16.4 Metrics\n\n- Latency p50/p95/p99 per Gateway route.\n- Error rate per capability, per connector.\n- Cost per LLM call, per Twin turn.\n\n### 16.5 Audit\n\n- `obs_audit`: append-only, signed, retained 7 years (regulatory baseline).\n- Audit events emitted by Governance (09), Memory Human Approval (06/07), Judicial actions, Security (14).\n\n### 16.6 Healthchecks\n\n- `/healthz` Worker + DO probes.\n\n### 16.7 Service map\n\n- Generated from traces; exported as graph.\n\n### 16.8 Events\n\n- **Emitted:** AuditAppended, AlertRaised, HealthCheckFailed.\n\n### 16.9 APIs\n\n`/obs/audit`, `/obs/metrics`, `/obs/traces`, `/obs/health`, `/obs/alerts`.\n\n### 16.10 Failure handling\n\n- Alert SLA: P0 ≤ 5 min notify, P1 ≤ 30 min, P2 ≤ 4 h.\n\n### 16.11 Extension points\n\n- Webhook exporters.\n\n---\n\n## 17 — SDKs\n\n### 17.1 Server SDK (`@integratewise/server`)\n\n- Capability registration, connector adapters, policy packs, projection transforms.\n\n### 17.2 Capability SDK contributor guide\n\n- Author `cap_*.yaml` per 05.\n- Validation rules + code-signing step.\n\n### 17.3 Connector SDK (`@integratewise/connector-sdk`)\n\n- Implements `ConnectorAdapter` (08.3).\n- Provides test harness: `connector test --mock-vendor=mux`.\n\n### 17.4 Worker SDK (`@integratewise/worker`)\n\n- Helpers for Spine, Twin, Workflows, Signals.\n\n### 17.5 Client SDKs\n\n- `@integratewise/react`, `@integratewise/swift`, `@integratewise/kotlin`.\n\n### 17.6 CLI (`@integratewise/cli`)\n\n- `iw onboard`, `iw capability register`, `iw connector test`, `iw marketplace publish`.\n\n### 17.7 Versioning\n\n- All SDKs follow semver; breaking changes shipped with MAJOR + migration guide.\n\n---\n\n## 18 — UI / Design System\n\n### 18.1 Design token spec\n\n- Color, type, spacing, motion, density, dark/light.\n- Tokens published as CSS vars and JSON; versions align with Design Pack releases.\n\n### 18.2 Components\n\n- Button, Card, Table, Timeline, Activity Feed, Evidence Ribbon, Promotion Queue, Workspace Switcher, Command Palette, Notification Center.\n\n### 18.3 Theme & density\n\n- Per-tenant theme tokens; high-density worksurfaces opt-in.\n\n### 18.4 Extension SDK\n\n- Custom tokens registered through `theme.json` (validated via CLI).\n\n---\n\n## 19 — API Contracts\n\n### 19.1 Versioning\n\n- URI version (`/v1/…`, migrating to `/v2025-09/…` for explicit dates).\n- Deprecation policy: 6 months notice, sun-set banner, parallel-run.\n\n### 19.2 Error model\n\n```json\n{ \"code\": \"IW-1234\", \"message\": \"…\", \"doc\": \"https://…\", \"trace_id\": \"…\" }\n```\n\n- Codes are stable; messages may be translated.\n\n### 19.3 Pagination\n\n- Cursor-based by default (`?cursor=…&limit=…`).\n- Page size limit max 1000.\n\n### 19.4 Feature flags\n\n- `X-IW-Feature-Flags` header; tenant overrides honor most-specific scope.\n\n### 19.5 Configuration system\n\n- Server-driven config: `tenant_spine_config` (existing) + `feature_flags` + `experiment_assignments`.\n\n### 19.6 Testing strategy\n\n- Contract tests against openapi spec (`@integratewise/contract-tests`).\n- Synthetic tenant population tests.\n\n---\n\n## 20 — Operations Runbooks\n\n### 20.1 Daily motion runbook\n\n- Morning brief sanity, Promotion Queue SLAs, Connector healthcheck dashboard review.\n\n### 20.2 Incident runbooks\n\n- **P0:** Twin down → revert to \"Last Good Answer\" projection.\n- **P0:** Connector down → triage by vendor, Nango re-auth, soft-sync queue flush.\n- **P1:** Spine write failures → DO alarm, retry, manual rebuild.\n- **P2:** Signal lag → check rule DSL hot-reload.\n\n### 20.3 Compliance runbook\n\n- Quarterly RBAC review.\n- Annual encryption & key rotation.\n\n### 20.4 DR runbook\n\n- R2 snapshot restore flow documented in runbook channel (links 15, 16, 02).\n\n---\n\n# PART II: ADVANCED SUBSYSTEMS (21–34)\n\n---\n\n## 21 — Business Ontology ⭐ (foundational)\n\n### 21.1 Why this is the largest gap\n\nThe original spec defined `tenant_spine_config` and the entity graph with concrete entity types but no ontological foundation. Two B2B SaaS tenants that both have a \"Person\" need that to be the same concept, queried the same way, governed the same way.\n\n### 21.2 The 16 root concepts\n\n| Concept | Definition |\n| ------------ | --------------------------------------------------------------- |\n| Organization | Legal entity owning the tenant |\n| Workspace | Bounded context inside Organization (inherits from 03) |\n| Person | First-class human (User is a Person with login) |\n| Team | Durable grouping of Persons, with role inheritance |\n| Process | Repeatable set of capabilities used to produce Outcomes |\n| Project | Time-bound container of Activities |\n| Objective | Measurable target a Process or Project exists to advance |\n| Outcome | Observed result, scored against an Objective |\n| Asset | Durable, non-ephemeral object of value (data, doc, code, model) |\n| Knowledge | Distilled truth (SOP, playbook, runbook; sits at L8 of memory) |\n| Decision | Recorded commitment (chair-of-record artifact) |\n| Policy | Rule that gates Decisions and Actions |\n| Capability | Declared action (inherits from 05) |\n| Signal | Derived observation (inherits from 10) |\n| Memory | Narrative artifact at any of the 8 layers (inherits from 07) |\n| Conversation | Twin ↔ User dialog (inherits from 06) |\n| Time | Canonical timeline reference (inherits from 02 Timeline) |\n\n### 21.3 Inheritance tree (canonical)\n\n```\nThing (id, version, lifecycle, provenance, evidence[]) ← base\n ├── Organization\n ├── Workspace\n ├── Agent (23)\n ├── Knowledge\n ├── Decision\n ├── Policy\n └── TimeAnchor\n\nAgentOfActivity (Thing + who/what performed)\n ├── Person — has Identities (28)\n └── Agent — has Lifecycle (23)\n\nBoundedContainer (AgentOfActivity + lifecycle scope)\n ├── Team — composition of Persons and Agents\n ├── Workspace — composition of Things (03)\n └── Project — composition of Activities, has Objective\n\nValueCarrier (Thing + has measurable state)\n ├── Asset\n ├── Knowledge — value = reusability\n └── Decision — value = commitment weight\n\nProcess (BoundedContainer + repeatable, has Objective)\n ├── Process — def + runs[]\n └── Workflow — runnable Process (inherits from 11)\n\nOutcome (ValueCarrier + measured against Objective)\n ├── Outcome\n └── Signal — derived from deltas (10)\n\nAction (Thing + executes Capability, gated by Policy)\n ├── Capability (inherits from 05)\n └── Conversation — composed of Message Tuples\n └── Memory — meaning-axis (07)\n```\n\n### 21.4 Canonical IDs per root concept\n\n| Concept | Prefix | Notes |\n| ------------ | ------- | ---------------------------------------------------- |\n| Organization | `org_` | Legal entity; one Organization ⇒ one or more Tenants |\n| Workspace | `wsp_` | Inherits from 03 |\n| Person | `usr_` | Login-bound Person |\n| Team | `team_` | Inherits from Person and Agent |\n| Process | `proc_` | Template; resolved through Workflows |\n| Project | `prj_` | Inherits from Process |\n| Objective | `obj_` | Has metric_id, target, range |\n| Outcome | `out_` | Measured vs obj\\_ |\n| Asset | `ast_` | Sub-typed by kind |\n| Knowledge | `knw_` | Inherits from L8 memory |\n| Decision | `dec_` | Chair-of-record artifact |\n| Policy | `pol_` | Declarative rule |\n| Capability | `cap_` | Inherits from 05 |\n| Signal | `sig_` | Inherits from 10 |\n| Memory | `mem_` | Inherits from 07 |\n| Conversation | `conv_` | Inherits from 06 |\n| Time | `tl_` | Inherits from 02 Timeline |\n\n### 21.5 Cross-concept reference rules\n\n- A Capability always belongs to ≥ 1 Process.\n- An Objective always references ≥ 1 Process.\n- An Outcome always references ≥ 1 Objective and ≥ 1 Process.\n- A Decision always references ≥ 1 Outcome OR ≥ 1 Signal.\n- A Policy always references ≥ 1 Capability or Entity type.\n- Memory is either Spine-truth, Twin-meaning, or Knowledge (three-axis separation, 07).\n\n### 21.6–21.14 Runtime Contract\n\n- **Responsibilities:** Define the 16 root concepts and inheritance tree; bind every ID prefix; bind cross-concept reference rules; pin three-axis Memory rule.\n- **Inputs:** OnboardingComplete (initial seeding); admin declarations of new root concepts (rare).\n- **Outputs:** Inheritance-validated entity writes (every new ent\\_ must inherit from ≥ 1 root concept); schema version bumps force revalidation.\n- **Events Produced:** OntologyDefined, ConceptExtensionAdded, ReferenceViolationDetected.\n- **Events Consumed:** EntityCreated, EntityUpdated, SchemaVersionBumped.\n- **APIs:** `GET /ontology/concepts`, `GET /ontology/inheritance/{kind}`, `POST /ontology/concepts`, `POST /ontology/validate`.\n- **State transitions:** Ontology itself: draft → ratified → superseded.\n- **Failure handling:** Reference violation → reject write, surface explainer referencing 21.5. Ontology supersession without migration → hard block writes involving supersession path.\n- **Extension points:** Vendors may add new root concepts (rare, requires Steering Committee review). New sub-types within an existing concept are normal extensions.\n\n---\n\n## 22 — AI Model Runtime\n\n### 22.1 Responsibilities\n\nOwn the AI Gateway at the model-routing layer (Cloudflare AI Gateway). Model selection, routing, cost optimization, latency routing, fallback hierarchy. Prompt versioning, evaluation, safety filters, caching, streaming.\n\n### 22.2 Pipeline\n\n```\nUser Request\n ↓\nIntent Detection\n ↓\nModel Router\n ↓\nModel Selection\n ↓\nTool Calls (via 05 Capability Fabric)\n ↓\nResponse Validation\n ↓\nMemory Commit (via 07 Memory → L1)\n```\n\n### 22.3 Inputs\n\n- Twin chat (06).\n- Workflow steps (11) calling capability `cap_llm_x`.\n- Ad-hoc admin calls from `/ai/run`.\n\n### 22.4 Outputs\n\n- Streamed (SSE or chunked) or buffered model output.\n- Memory intake events (07 / L1).\n- Cost/latency metrics (16, 30).\n\n### 22.5 Events Produced\n\nModelRouted, ModelInvoked, ModelStreamingStarted, ModelCompleted, ModelFailed, ModelFallbackEngaged, PromptVersionUsed, SafetyFilterTriggered, CacheHit, CacheMiss, EvalRunCompleted.\n\n### 22.6 Events Consumed\n\nTwinChat, CapabilityInvoked (when capability is llm\\_\\*), WorkflowStepStarted.\n\n### 22.7 APIs\n\n`POST /ai/run`, `POST /ai/route`, `POST /ai/eval`, `GET /ai/prompts/{prompt_id}/versions`, `POST /ai/prompts/{prompt_id}/publish`.\n\n### 22.8 State transitions\n\nPer invocation: `received → intent → routed → invoked → streaming → validating → completed | failed | fallback | aborted`.\nPrompt versions: `draft → canary → stable → deprecated → removed`.\nSafety filters: `bypass → warn → block → quarantine`.\n\n### 22.9 Failure handling\n\n- Primary model timeout → fallback to next in hierarchy (22.10).\n- Fallback exhaustion → degrade to \"Last Good Answer\" projection (06.10).\n- Safety filter trigger: warn returns redacted content, block denies, quarantine sends to admin review.\n- Eval regression detected on stable prompt version → auto-rollback to last known-good version.\n\n### 22.10 Fallback hierarchy (default)\n\n1. Primary (provider × model) per `tenant_spine_config.model_profile`.\n2. Cheap secondary (smaller/cheaper model same vendor).\n3. Cross-vendor secondary.\n4. Cached prior good response (cache TTL ≤ 7 d).\n5. Persona-template static fallback (\"Last Good Answer\").\n6. Quarantine + alert.\n\n### 22.11 Cost & latency routing\n\n- Per-route `cost_budget_per_turn_cents` and `p95_latency_ms`.\n- Router picks provider/model by `(capability_needed × cost × latency × traffic_class)`.\n- Off-peak windows may choose smaller models automatically; near SLA breach escalates to premium model.\n\n### 22.12 Prompt versioning\n\n- Every prompt template is a `mod_prompt_{id}` with version (semver), status, owner, `evalset_ref`.\n- Browse + diffing in CLI (`iw prompt diff v1.4 v1.5`).\n- Canary rollout through feature flags (15.3, 19.4).\n\n### 22.13 Evaluation\n\n- `evalset` = golden prompts × expected behaviors (text, tool-calls, JSON schema, refusal). Runs on every prompt publish and every model swap.\n- Run record: `mod_evalrun_{id}` with pass/fail per expectation; downstream alerting.\n\n### 22.14 Safety filters\n\n- Categories: PII exfiltration, jailbreak, toxicity, secret-leak, prompt-injection, vendor-policy-violation.\n- Levels: bypass (debug only), warn, block, quarantine.\n- Tenant overrides require `governancePolicy=judicial` (09).\n\n### 22.15 Caching\n\n- Prompt-level cache keyed by `prompt_id + version + params_hash`.\n- Response cache keyed by `prompt_id + version + params_hash + tenant.tier`.\n- TTL configurable; default 7 d.\n\n### 22.16 Streaming\n\n- Workspaces and Chat both consume via SSE; mobile via chunked JSON.\n- Late chunk miss → fetch from response cache; surface degraded badge.\n\n### 22.17 Extension points\n\n- Custom router strategies `AI_ROUTER(name)`.\n- Custom safety filters `SAFETY_FILTER(name)`.\n- New model provider adapters via `@integratewise/connector-sdk`.\n\n---\n\n## 23 — Agent Runtime\n\n### 23.1 Responsibilities\n\nOwn the Agent Registry, lifecycle, memory, permissions, scheduling, communication, supervision, and failure handling for automated agents beyond the Twin.\n\n### 23.2 Agent kinds (canonical)\n\n- **Twin** — inherits 06, persona-bound.\n- **Worker Agent** — runs inside a Workflow step (11), no persona-fit, transactional.\n- **Supervisor Agent** — watches Worker Agents and Twin health, can pause/restart.\n- **Background Agent** — runs from a cron or Event, e.g., TwinAgent (morning brief), TenantBrainDO (approvals).\n- **Community Agent** — contributed via Marketplace (13); sandboxed.\n\n### 23.3 Inputs\n\nWorkflow step launch, cron schedule, Event Bus trigger, Manual admin launch. Continuity context (25).\n\n### 23.4 Outputs\n\nCapability invocations (05), Memory intakes (07), Signals (10), Workflow handoffs (11).\n\n### 23.5 Events Produced\n\nAgentRegistered, AgentScheduled, AgentStarted, AgentPaused, AgentResumed, AgentStopped, AgentFailed, AgentSupervisedAction, AgentCommunicationSent, AgentCommunicationReceived.\n\n### 23.6 Events Consumed\n\nWorkflowStarted, WorkflowStepDue, CronTick, EventBus\\*, TwinRoutedRequest.\n\n### 23.7 APIs\n\n`POST /agents`, `POST /agents/{ag_id}/schedule`, `POST /agents/{ag_id}/pause`, `POST /agents/{ag_id}/resume`, `POST /agents/{ag_id}/invoke`, `GET /agents/{ag_id}/runs`.\n\n### 23.8 State transitions\n\n`declared → registered → scheduled → running → paused → resumed → stopped → failed → archived`.\nHealth watch: `healthy → degrading → critical → quarantined`.\n\n### 23.9 Agent lifecycle specification\n\nMandatory metadata: id, kind, capabilities[], permissions[], memory_scope, owner, contacts[].\nPermissions inherit from capability-level requiredScopes + agent-level overrides.\nRun traces appended to Observability (16); supervision emits AgentSupervisedAction.\n\n### 23.10 Agent registry\n\nPersistent in D1 (`agents.agents`, `agents.runs`, `agents.permissions`).\nDiscoverable per workspace via Projection Engine (04).\n\n### 23.11 Agent memory\n\n- `memory_scope` chooses: Twin-meaning (07/L1) for ephemeral, Organizational Memory (07/L7) for durable.\n- Agents may not write directly to Spine (02) — only via Capability Fabric (05).\n\n### 23.12 Agent permissions\n\n- Each agent declares `requiredScopes[]` evaluated through 09 Governance.\n- Cross-workspace calls require `gov.cross_workspace` token.\n\n### 23.13 Agent scheduling\n\n- Trigger types: cron, Event Bus (filter), Time-window, Manual, Chain.\n- Time windows enforced in DO durable alarms.\n\n### 23.14 Agent communication\n\n- Two patterns: (a) Capability invocation through 05; (b) Async envelope through Event Bus.\n- All envelopes signed; recipient validates.\n\n### 23.15 Agent supervision\n\n- Supervisor Agent checks HealthSnapshot (08.7-style), run success rate, drift metrics.\n- Allowed actions: pause, restart, route to fallback model (22), quarantine.\n\n### 23.16 Failure handling\n\n- **Twin:** rehydrate context from 25; do not lose conversation state.\n- **Worker Agent:** idempotent retry, max N=3.\n- **Community Agent:** quarantine + admin notify.\n- Cross-agent failure cascade: Supervisor Agent breaks the loop.\n\n### 23.17 Extension points\n\n- New Agent kinds via registry; reviewed for sandbox if kind=community.\n- Custom runners (e.g., remote executor) via `AGENT_RUNNER(name)`.\n\n---\n\n## 24 — Integration Manager\n\n### 24.1 Why this doc exists\n\nConnector Framework (08) describes Nango/MCP/Native/Custom API as separate concepts. The Integration Manager is the single abstraction layer that lets a Capability invocation pick the right underlying transport.\n\n### 24.2 Pipeline\n\n```\nCapability (05)\n ↓\nIntegration Manager\n ↓\nNango ── managed OAuth & vendor APIs\nMCP ── tool servers, structured contexts\nNative ── first-party adapters (Salesforce, HubSpot)\nCustom API ── raw HTTP/GraphQL/protobuf\n```\n\n### 24.3 Responsibilities\n\n- Resolve Capability `transport_hints[]` to one of `{nango, mcp, native, custom}`.\n- Mint & cache short-lived `conn_` tokens through 08 / 14.\n- Aggregate Connector Deltas into a unified ConnectorDelta shape.\n- Health-impose per-transport breakers.\n\n### 24.4 Inputs\n\nCapabilityInvoked events (05). Connector HealthyChanged (08). Admin transport overrides.\n\n### 24.5 Outputs\n\nResolved writes through chosen transport. Aggregated ConnectorDelta stream into Spine (02) and Signals (10).\n\n### 24.6 Events Produced\n\nIntegrationResolved, IntegrationDispatched, IntegrationCompleted, IntegrationFailed, IntegrationTokenRefreshed, IntegrationBreakerOpened, IntegrationBreakerClosed.\n\n### 24.7 Events Consumed\n\nEvery CapabilityInvoked, ConnectorHealthyChanged, MCPDiscoveryUpdated.\n\n### 24.8 APIs\n\n`POST /integration/resolve`, `GET /integration/{cap_id}/transports`, `POST /integration/{cap_id}/dispatch`, `GET /integration/breakers`.\n\n### 24.9 State transitions\n\n`idle → resolving → dispatching → succeeded | failed → cooldown → idle`.\n\n### 24.10 Failure handling\n\n- Transport failure → breaker open per transport; subsequent attempts use next transport.\n- After N consecutive breaker opens → emit ConnectorRetired (08.10).\n\n### 24.11 Extension points\n\n- New transports via `INTEGRATION_TRANSPORT(name)`.\n- Custom resolver strategies `INTEGRATION_RESOLVER(name)`.\n\n---\n\n## 25 — Continuity Engine\n\n### 25.1 Responsibilities\n\nContext assembly. Session continuity. Cross-device, cross-model, cross-workspace continuity. Context compaction, memory hydration, context prioritization.\n\n### 25.2 Continuity surfaces\n\n| Surface | What must be continuous |\n| --------------- | ----------------------------------------------------- |\n| Session | Current Twin conversation state (L1) |\n| Cross-device | Active session survives device switch |\n| Cross-model | Switch vendor/model mid-session without losing intent |\n| Cross-workspace | Switching wsp* → wsp* keeps task context |\n| Cross-temporal | As-of queries are intrinsic to Spine reads |\n\n### 25.3 Pipeline\n\n```\nContext Triggers (07 event, 06 screen state, 22 cache hit, 04 projection, 02 timeline)\n ↓\nContext Assembler (assembles ordered fragments, applies priority)\n ↓\nMemory Hydrator (pulls relevant L1+L7 hits per fragment)\n ↓\nCompactor (only when budget exceeded)\n ↓\nContext Pack (consumed by 06 prompt builder and 05 capability resolver)\n```\n\n### 25.4 Inputs\n\nTwinContextBuilt triggers, WorkspaceSwitched, ModelRouted, MemoryApproved, EntityUpdated (for context-bearing entities).\n\n### 25.5 Outputs\n\nContextPack attached to every TwinResponded, and to every capability invocation that requires tenant-wide awareness.\n\n### 25.6 Events Produced\n\nContextAssembled, ContextCompacted, ContextHydrated, ContextPrioritized, ContinuityBridgeActivated, ContinuityBridgeDeactivated.\n\n### 25.7 Events Consumed\n\nWorkspaceSwitched, ModelRouted, EntityUpdated (subset bearing relevance), MemoryApproved, TwinContextBuilt.\n\n### 25.8 APIs\n\n`POST /continuity/assemble`, `GET /continuity/context/{session_id}`, `POST /continuity/compact`, `POST /continuity/hydrate`.\n\n### 25.9 State transitions\n\n`empty → assembling → hydrating → compacting? → assembled → consumed → purged`. Bridge state: `cold → warm → hot → cold`.\n\n### 25.10 Priorities (canonical order)\n\n1. Persona-bind (industry × department × sub-role).\n2. Workspace module set.\n3. Active screen state (Projection — 04).\n4. Last 10 Twin turns (L1).\n5. Recent Entity updates relevant to screen.\n6. L7 promotion queue items pending approval.\n7. Capabilities restricted by persona.\n\n### 25.11 Compaction\n\n- Token budget exhausted → summarize older turns via 22; never drop pinned Memory.\n- Compaction log emitted as ContextCompacted with reduction_ratio.\n\n### 25.12 Failure handling\n\n- Memory Lookup timeout → continue with degraded pack, badge \"Partial context\".\n- Cross-device state divergence → resolve via Spine timestamp; last write wins for non-pinned; pinned fields stay.\n\n### 25.13 Extension points\n\n- Custom priority rules `CONTINUITY_PRIORITY(name)`.\n- Custom compacters `COMPACTOR(name)`.\n\n---\n\n## 26 — Search Engine\n\n### 26.1 Pipeline\n\n```\nSearch (request)\n ↓\nSpine\nMemory\nKnowledge\nConnector Search\nConversation Search\nSemantic Search\nHybrid Ranking\n```\n\n### 26.2 Responsibilities\n\nProvide Universal Search (P-1) and Command Palette (P-2). Index and search across Spine (02), Memory (07), Knowledge (07/L8), Connector indexes, Conversations (06), plus semantic vectors and lexical indexes. Compose results with hybrid ranker.\n\n### 26.3 Inputs\n\nUser search request, contextual triggers (selected entity, screen state).\n\n### 26.4 Outputs\n\nRanked result set with provenance (every item carries `provenance[]` per 02). Highlight spans.\n\n### 26.5 Index kinds\n\n| Index | Source | Type |\n| ---------- | --------------------- | ---------------- |\n| idx_spine | Spine entities | lexical + vector |\n| idx_mem_l1 | Twin conversations | vector |\n| idx_mem_l7 | Organizational Memory | lexical + vector |\n| idx_knw | Knowledge articles | lexical + vector |\n| idx_conn | Connector feeds | lexical |\n| idx_conv | Twin transcripts | lexical + vector |\n\n### 26.6 Events Produced\n\nIndexBuilt, IndexIncremented, IndexInvalidated, SearchExecuted, SearchResultClicked.\n\n### 26.7 Events Consumed\n\nEntityUpdated, MemoryApproved, KnowledgeArticlePublished, ConnectorSynced, TwinResponded.\n\n### 26.8 APIs\n\n`POST /search`, `GET /search/{idx_id}/status`, `POST /search/{idx_id}/rebuild`.\n\n### 26.9 State transitions\n\nPer index: `cold → warming → warm → degraded → cold`. Per query: `received → planning → fused → ranked → served`.\n\n### 26.10 Hybrid ranking\n\nReciprocal Rank Fusion across lexical (BM25) + vector (cosine) + recency + persona boost.\nPersona boost via 06; tenant admin can override weights.\n\n### 26.11 Failure handling\n\n- Index unreachable → serve last good snapshot with degraded badge.\n- Vector index down → fall back to lexical only.\n\n### 26.12 Extension points\n\n- Custom ranking models `RANKER(name)`.\n- Custom indexers `INDEXER(name)`.\n\n---\n\n## 27 — Data Pipeline\n\n### 27.1 Pipeline\n\n```\nIngestion\n ↓\nNormalization\n ↓\nValidation\n ↓\nDeduplication\n ↓\nCanonical Mapping\n ↓\nEnrichment\n ↓\nProjection\n ↓\nStorage\n```\n\n### 27.2 Responsibilities\n\nRun the pipeline for every Connector Delta (08), Memory intake (07), and Knowledge import (07/L8). Idempotency keyed on `(source, source_record_id, observed_at, hash)`. Strict stage ordering; failure of one stage quarantines the artifact (DLQ).\n\n### 27.3 Inputs\n\nConnectorDeltaReceived, MemoryIntake, KnowledgeImportRequested, admin batch uploads.\n\n### 27.4 Outputs\n\nCanonical Spine updates (02) + Signal side-effects (10) + Memory write-backs (07).\n\n### 27.5 Events Produced\n\nPipelineStarted, PipelineStageCompleted, PipelineStageFailed, PipelineCompleted, PipelineDuplicateDetected, PipelineEnrichmentApplied, PipelineAborted.\n\n### 27.6 Events Consumed\n\nConnectorDeltaReceived, MemoryIntake, KnowledgeImportRequested, EntityTypeRegistered.\n\n### 27.7 APIs\n\n`POST /pipeline/run`, `GET /pipeline/runs/{pipe_id}`, `POST /pipeline/dlq/{item_id}/replay`.\n\n### 27.8 Stage definitions\n\n- **Ingestion:** parse vendor payload; schema check.\n- **Normalization:** apply `tenant_spine_config.field_extensions`, normalize dates/currency.\n- **Validation:** cross-field, cross-entity (12).\n- **Deduplication:** hash + semhash; resolve via Spine `?as_of`.\n- **Canonical Mapping:** map to `ent_` via 12 inheritance.\n- **Enrichment:** Signals (10) may attach; capability `cap_enrich_x` may run pre-storage.\n- **Projection:** build per-persona projection shape (04).\n- **Storage:** write to Spine (02); archive snapshot to R2.\n\n### 27.9 State transitions\n\n`received → ingested → normalized → validated → deduped → mapped → enriched → projected → stored`.\nFailure path: `… → DLQ`. Replay path: `DLQ → received`.\n\n### 27.10 Failure handling\n\nStage failure → stop, retry policy per stage (configurable), finally DLQ. DLQ item presents replay UI in Workbench under Pipeline Admin.\n\n### 27.11 Extension points\n\n- Custom pipeline steps via `PIPELINE_STEP(name)`.\n- Custom canonical mappers `MAPPER(name)`.\n\n---\n\n## 28 — Identity Platform\n\n### 28.1 Responsibilities\n\nIdentity, Organizations, Invitations, Teams, SCIM, SAML, Enterprise SSO, MFA, Service Accounts, API Keys.\n\n### 28.2 Identity layers\n\n- **Person Identity:** email/password, OAuth, SAML, magic-link.\n- **Organization Identity:** SCIM-issued users, federated mapping.\n- **Service Identity:** Service Accounts (`svc_`), API Keys (`key_`), scoped to workspaces and capabilities.\n\n### 28.3 Inputs\n\nMarketplace OAuth (per existing spec). Admin invites, SCIM provisioning, SAML IdP assertions.\n\n### 28.4 Outputs\n\n`usr_`, `org_`, `team_`, `inv_`, `key_` records. Session JWTs bound to device fingerprint (14). Audit events for every identity operation.\n\n### 28.5 Events Produced\n\nIdentityCreated, IdentityUpdated, InvitationSent, InvitationAccepted, InvitationExpired, TeamCreated, TeamMemberAdded, TeamMemberRemoved, SCIMProvisioned, SCIMDeprovisioned, ServiceAccountCreated, APIKeyIssued, APIKeyRevoked, MFAChallengeIssued, MFAVerified, MFAFailed.\n\n### 28.6 Events Consumed\n\nMarketplaceInstalled (per existing spec), WorkspaceSwitched, SecurityAlert.\n\n### 28.7 APIs\n\n`POST /identity/invitations`, `POST /identity/invitations/{inv_id}/accept`, `POST /identity/scim/sync`, `POST /identity/saml/acs`, `POST /identity/mfa/challenge`, `POST /identity/mfa/verify`, `POST /identity/service-accounts`, `POST /identity/api-keys`.\n\n### 28.8 State transitions\n\n- User: `pending → active → suspended → deleted`.\n- Invitation: `sent → accepted | expired | revoked`.\n- Service Account: `active → rotating → retired`.\n- API Key: `active → rotated → revoked`.\n\n### 28.9 RBAC + ABAC cross-reference\n\n- RBAC tables (per existing spec) bind `usr_ → role → cap`.\n- ABAC layer (14.6) reads identity attributes: is_service, mfa_verified_within, device_posture, geo_region.\n\n### 28.10 SCIM\n\n- Endpoint: `/scim/v2/{org_}`.\n- Mappings: SCIM user ↔ `usr_`; SCIM group ↔ `team_`.\n- Provisioning direction configurable: pull (SCIM → platform) or push (platform → SCIM).\n\n### 28.11 SAML / Enterprise SSO\n\n- ACS endpoint: `/identity/saml/acs`.\n- Standard attributes mapped: email, name, department, employee_id.\n- JIT (Just-In-Time) provisioning gated by `governancePosture.sso_provision`.\n\n### 28.12 MFA\n\n- TOTP, WebAuthn, push (via mobile app).\n- Risk-based re-challenge for high-governance capabilities.\n\n### 28.13 Service Accounts\n\n- Bound to a Team (not an individual) for audit clarity.\n- API Keys scoped to `cap_ids[]` and `wsp_ids[]`.\n\n### 28.14 Failure handling\n\n- SCIM conflict → preserve newer-side, raise admin alert.\n- SAML assertion replay → reject + alert.\n- MFA failure > N → soft lock + admin notify.\n\n### 28.15 Extension points\n\n- New identity provider via `IDENTITY_PROVIDER(name)`.\n- Custom ABAC rules via `POLICY_PACK(name)` (14).\n\n---\n\n## 29 — Billing Platform\n\n### 29.1 Responsibilities\n\nPlans, Seats, Usage, Credits, Trials, Metering, Invoices, Limits, Quotas.\n\n### 29.2 Plan model\n\n```yaml\nsub_plan:\n id: sub_plan_…\n code: free | starter | growth | enterprise\n prices: [{ currency, amount, interval: monthly|annual }]\n seats: included\n usage_credits: included # optional\n overage_policy: [block | bill | throttle]\n features: [cap_id, signal_priority, marketplace_discount]\n```\n\n### 29.3 Inputs\n\nWorkspaceCreated, UserAdded (seat consumption), CapabilityInvoked (metered), SignalCreated (signal metering), API call (`/ai/run` LLM tokens).\n\n### 29.4 Outputs\n\n`sub_` records, `bill_` invoices, Stripe receipts (13.5). Enforcement events (LimitExceeded, QuotaWarning).\n\n### 29.5 Events Produced\n\nPlanAssigned, SeatConsumed, SeatReleased, UsageMetered, CreditConsumed, CreditGranted, TrialStarted, TrialConverted, TrialExpired, InvoiceIssued, InvoicePaid, InvoiceFailed, LimitExceeded, QuotaWarning.\n\n### 29.6 Events Consumed\n\nWorkspaceCreated, UserAdded, UserRemoved, CapabilityInvoked, SignalCreated, ModelInvoked, ListingInstalled.\n\n### 29.7 APIs\n\n`POST /billing/plans`, `POST /billing/subscriptions`, `POST /billing/usage/record`, `GET /billing/invoices`, `POST /billing/credits/grant`.\n\n### 29.8 State transitions\n\nSubscription: `trialing → active → past_due → canceled → reactivated`.\n\n### 29.9 Metering\n\nMetered units: seat, llm_token, signal_score, cap_invocation, connector_sync_call, r2_storage_gb.\nHourly aggregation → monthly close.\n\n### 29.10 Limits & Quotas\n\nPer-tenant caps; per-workspace caps; per-user caps.\n`overage_policy`: block (deny), bill (Stripe metered SKU), throttle (rotate to cheaper path).\nSurfaced via 30 Operational Metrics dashboards.\n\n### 29.11 Credits\n\nTrial and grant credits stored in `sub_credits`, consumed FIFO, tracked in audit log.\n\n### 29.12 Invoices\n\nMonthly per workspace; line items mirror UsageMetered events.\nReconciliation against Stripe via daily job.\n\n### 29.13 Failure handling\n\nPayment failure → soft-cap features; admin notified.\nMetering lag → rechecks current usage every 6 h.\n\n### 29.14 Extension points\n\nNew SKUs via Marketplace (13). Custom overage policy via `BILLING_POLICY(name)`.\n\n---\n\n## 30 — Operational Metrics\n\n### 30.1 Responsibilities\n\nDefine, compute, and surface the canonical operational metrics. Make every metric queryable per tenant, per workspace, per persona, per agent.\n\n### 30.2 Canonical metrics\n\n| Metric | Definition |\n| -------------------------- | -------------------------------------------------------------------- |\n| Workspace Activation Rate | % of tenants with at least one wsp\\_ transitioned past bootstrapping |\n| Time to First Value (TTFV) | Wall clock from OAuth complete → first non-empty projection render |\n| Connector Adoption | Average number of active conn* per wsp* by industry × department |\n| Capability Usage | Daily invocations per cap_id, bucketed by persona |\n| Twin Acceptance Rate | % of Twin proposals accepted vs surfaced |\n| Memory Promotion Rate | L5 → L6 promotions per 24h per tenant |\n| Signal Precision | Accepted signals / surfaced signals, rolling 7 d |\n| Approval Latency | GovernanceRequested → GovernanceApproved p50/p95 |\n\n### 30.3 Inputs\n\nAll event bus events (filtered / aggregated). Tenant onboarding completion events (existing spec).\n\n### 30.4 Outputs\n\nTime-series metrics in a TSDB. Aggregate reports rolled up nightly.\n\n### 30.5 Events Produced\n\nOperationalMetricComputed, OperationalMetricAnomalyDetected.\n\n### 30.6 Events Consumed\n\nAll events (filtered by metric rule).\n\n### 30.7 APIs\n\n`GET /ops/metrics/{metric_id}`, `POST /ops/metrics/{metric_id}/compute`, `GET /ops/dashboards/{tenant_id}`.\n\n### 30.8 State transitions\n\n`preregistered → live → deprecated`. Anomaly state: `nominal → warning → critical`.\n\n### 30.9 Anomaly detection\n\nPer-metric threshold low/high plus weekly ML-driven adjustment; admins can pin.\n\n### 30.10 Failure handling\n\nCompute lag beyond SLO → MetricStale event + dashboard badge.\nAnomaly spam-protection: min interval 15 minutes between alerts per metric per tenant.\n\n### 30.11 Extension points\n\n- Custom metrics `OP_METRIC(name)`.\n- Custom anomaly rules `OP_ANOMALY(name)`.\n\n---\n\n## 31 — Evolution Strategy\n\n### 31.1 Responsibilities\n\nDefine safe evolution of Schema, Capability, Connector, Persona, API, Memory, and Migration strategy.\n\n### 31.2 Evolution areas\n\n| Area | Reference | Strategy |\n| ---------- | ---------------------- | --------------------------------------------------------------- |\n| Schema | 12 + 02 | Additive-first; bump schema_version; reversible |\n| Capability | 05 | New cap_id per major change; deprecate old by status |\n| Connector | 08 | Version bump; certified path; admin opt-in for breaking changes |\n| Persona | (existing spec, 12×11) | New sub-role or industry requires Steering Committee |\n| API | 19 | URI versioning; 6-mo deprecation; parallel-run |\n| Memory | 07 | Versioning of pipeline layer logic; data is append-only |\n| Migration | 15.4 + 21 | Reversible; dry-run; bump schema_version |\n\n### 31.3 Inputs\n\nSchema change PRs, Capability change PRs, authored Connector changes. Admin-initiated migrations.\n\n### 31.4 Outputs\n\nRollout plan + flag flips (15.3). Migration artifact (id, scope, dry-run result, reversal procedure).\n\n### 31.5 Events Produced\n\nEvolutionStarted, EvolutionFlagged, EvolutionRolledBack, EvolutionCompleted, SchemaVersionBumped, CapabilityDeprecated, ConnectorDeprecated, ApiDeprecated, MemoryLayerDeprecated.\n\n### 31.6 Events Consumed\n\nCapabilityRegistered, CapabilityDeprecated, ConnectorInstalled, ConnectorRetired, SchemaVersionBumped.\n\n### 31.7 APIs\n\n`POST /evolution/migrations`, `POST /evolution/migrations/{mig_id}/dry-run`, `POST /evolution/migrations/{mig_id}/apply`, `POST /evolution/migrations/{mig_id}/rollback`.\n\n### 31.8 State transitions\n\n`draft → tested → dark_launch → canary → progressive → stable → deprecated → removed`.\n\n### 31.9 Principles\n\n- Additive-first, never destructive by default.\n- Every deprecation publishes a Sun-Set banner 6 months in advance (19.1).\n- Backwards compatibility is preserved for ≥ 1 prior schema_version.\n\n### 31.10 Failure handling\n\n- Dark launch metric regression → automatic flag rollback.\n- Migration apply failure → automated reversal; admin notified.\n\n### 31.11 Extension points\n\nNew evolution channels via `EVOLUTION_CHANNEL(name)`.\n\n---\n\n## 32 — Plugin Runtime\n\n### 32.1 Pipeline\n\n```\nPlugin\n ↓\nValidation\n ↓\nSandbox\n ↓\nPermissions\n ↓\nResources\n ↓\nCapability Registration\n ↓\nLifecycle\n```\n\n### 32.2 Responsibilities\n\nHost third-party Plugin bundles (WASM or JS-in-Worker) supplied through Marketplace (13). Validate, sandbox, assign permissions, allocate resources, register capabilities, manage lifecycle.\n\n### 32.3 Plugin kinds\n\n`connector_plugin`, `capability_plugin`, `workflow_plugin`, `persona_kit_plugin`, `design_pack_plugin`.\n\n### 32.4 Inputs\n\nListingInstalled (Community Agent kind; 23.2). Admin overrides.\n\n### 32.5 Outputs\n\nRegistered Capabilities (05), Workflows (11), Persona Kits (06).\n\n### 32.6 Events Produced\n\nPluginValidated, PluginSandboxed, PluginPermissionsGranted, PluginRegistered, PluginResourcesAllocated, PluginLifecycleEvent, PluginUninstalled, PluginQuarantined.\n\n### 32.7 Events Consumed\n\nListingInstalled, ListingUpgradeStarted, CapabilityRegistered.\n\n### 32.8 APIs\n\n`POST /plugins`, `POST /plugins/{plg_id}/validate`, `POST /plugins/{plg_id}/sandbox`, `GET /plugins/{plg_id}/health`, `POST /plugins/{plg_id}/permissions`, `POST /plugins/{plg_id}/uninstall`.\n\n### 32.9 State transitions\n\n`uploaded → validating → validated → sandboxed → permissions_assigned → resources_allocated → installed → upgrading → deprecated → uninstalled → quarantined`.\n\n### 32.10 Sandbox\n\nWASM execution in Worker with capability allowlist enforced at runtime.\nResource budgets: CPU ms, memory bytes, network egress URLs (allowlist).\n\n### 32.11 Permissions\n\nPlugin declares `permissions[]` (capabilities + data scopes + network egress hosts).\nValidation rule: declared permissions ⊨ advertised Marketplace scopes.\n\n### 32.12 Resources\n\nQuotas per plugin per tenant; default ceilings in 29 Billing.\nPer-plugin token meter for cost attribution.\n\n### 32.13 Lifecycle ownership\n\nPlugin may declare its own lifecycle adapter, but bounded by Plugin Runtime contract; cannot terminate itself.\n\n### 32.14 Failure handling\n\n- Crashed plugin → auto-restart ≤ 3; quarantine after.\n- Resource ceiling breach → throttle + admin notify.\n\n### 32.15 Extension points\n\n- New plugin kinds via Plugin SDK (17).\n- Custom sandbox capability types `SANDBOX_CAP(name)`.\n\n---\n\n## 33 — Testing Architecture\n\n### 33.1 Responsibilities\n\nDefine the multi-layer testing architecture: Unit, Integration, Connector simulation, Synthetic tenants, AI evaluation, Persona validation, End-to-end, Load, Chaos.\n\n### 33.2 Layers\n\n| Layer | Scope |\n| -------------------- | ------------------------------------------------------------------------- |\n| Unit | Pure functions, SDK contracts |\n| Integration | Subsystem boundaries (02↔05, 08↔02, etc.) |\n| Connector simulation | Vendor mocks (per mock-vendor=mux from SDK 17.3) |\n| Synthetic tenants | Generated tenant population exercising the 12×11 matrix |\n| AI evaluation | Evalset runs on prompt versions and model swaps (22.13) |\n| Persona validation | Persona-fit assertions: greeting, capability defaults, governance posture |\n| End-to-end | Full flows (OAuth → Onboard → First Value → Promotion) |\n| Load testing | Synthetic traffic across Gateway/Spine |\n| Chaos testing | Fault injection on DO, Queue, Vendor rate limit, LLM timeout |\n\n### 33.3 Inputs\n\nCI event (PR, push), scheduled nightly jobs, pre-release gate.\n\n### 33.4 Outputs\n\nPass/fail per layer; release gate decisions; coverage report.\n\n### 33.5 Events Produced\n\nTestSuiteStarted, TestSuiteCompleted, TestFailure, EvalRegressionDetected, ChaosDrillCompleted.\n\n### 33.6 Events Consumed\n\nCI events, schedules.\n\n### 33.7 APIs\n\n`POST /test/run`, `GET /test/runs/{run_id}`, `POST /test/evalset/publish`.\n\n### 33.8 State transitions\n\n`queued → running → passed | failed | flaky → archived`.\n\n### 33.9 Failure handling\n\n- Flake quarantine (re-run twice, isolate).\n- Eval regression → force prompt rollback (22.9).\n\n### 33.10 Extension points\n\n- New test kinds via `TEST_KIND(name)`.\n- Custom chaos faults via `CHAOS_FAULT(name)`.\n\n### 33.11 Release gate (canonical)\n\nP0 release requires all layers pass for the last 7 days.\nAny regression freezes the gate until resolved or exempted by Steering Committee.\n\n---\n\n## 34 — System Lifecycle\n\n### 34.1 Why this doc exists\n\nThe Lifecycle section was added because the platform needed a superseding view that spans everything — Tenants, Connectors, Workspaces, Memories, Agents, Capabilities. Each subsystem already has its own lifecycle, but a unified lifecycle is the true cross-cutting doctrine.\n\n### 34.2 Tenant lifecycle (canonical)\n\n```\nTenant\n ↓\nActivated — OAuth complete; identity record created\n ↓\nHydrated — tenant_spine_config written; Spine seeded\n ↓\nOperational — first capability invocation succeeded\n ↓\nGrowing — usage metrics in green band (30.3)\n ↓\nDormant — zero activity for N days; admin notified\n ↓\nArchived — soft-archived; data retained\n ↓\nDeleted — judicial hard-delete only (02.11)\n```\n\n### 34.3–34.7 Subsystem lifecycles (cross-referenced)\n\n- **Connector:** declared → sandboxed → certified → active → degraded → retired → archived → revoked (08.2).\n- **Workspace:** init → bootstrapping → active → suspended → archived → migrated (03.3).\n- **Memory:** intake → triaged → cluster → queued_for_promotion → approved | rejected → deprecated (07.7).\n- **Agent:** declared → registered → scheduled → running → paused → resumed → stopped → failed → archived (23.8).\n- **Capability:** declared → registered → versioned → deprecated → removed → revoked (05.3).\n\n### 34.8 Cross-lifecycle policy\n\nAn object can only transition to a lifecycle state if its dependencies are healthy:\n\n- A Capability cannot be registered until its required connectors are active.\n- A Workspace cannot be active until its Tenant is Hydrated.\n- An Agent cannot be running until its declared memories exist.\n- Memory cannot be approved until L5 has human review.\n\n### 34.9 Lifecycle event bus\n\nEvery transition emits a LifecycleEvent carrying from_state, to_state, actor, reason.\nProjection Engine (04) uses these to invalidate stale caches.\n\n### 34.10 Events Produced\n\nLifecycleEvent, LifecycleViolationDetected (cross-lifecycle policy breaches).\n\n### 34.11 Events Consumed\n\nAll subsystem lifecycle events.\n\n### 34.12 APIs\n\n`GET /lifecycle/{kind}/{id}`, `POST /lifecycle/{kind}/{id}/transition`, `GET /lifecycle/diagram`.\n\n### 34.13 State transitions\n\nEach suspended state has TTL: auto-resume, auto-archive, or escalate depending on kind.\n\n### 34.14 Failure handling\n\n- Cross-lifecycle policy breach → block transition + explainer.\n- Dormant Tenant reactivation returns to Operational after warm-up projection rebuild.\n\n### 34.15 Extension points\n\nCustom transition rules via `LIFECYCLE_RULE(name)`.\n\n---\n\n# APPENDIX\n\n## A. Cross-Spec Runtime Contracts — Consolidated\n\nEvery doc (02–34) carries the identical contract template:\n\n1. Responsibilities\n2. Inputs\n3. Outputs\n4. Events produced\n5. Events consumed\n6. APIs\n7. State transitions\n8. Failure handling\n9. Extension points\n\nThere is now no subsystem in IntegrateWise without a runtime contract.\n\n## B. Business Ontology Cross-References\n\nEvery doc references back to 21 Business Ontology where its primary types are defined:\n\n| Doc | Primary Ontology Types |\n| ------------------------ | --------------------------------------- |\n| 22 (Models) | Person / Agent / Decision |\n| 23 (Agents) | Agent / Team / Conversation |\n| 24 (Integration Manager) | Capability / Asset |\n| 25 (Continuity Engine) | Person / Workspace / Memory |\n| 26 (Search Engine) | Knowledge / Memory / Conversation |\n| 27 (Data Pipeline) | Asset / Knowledge / Capability |\n| 28 (Identity Platform) | Person / Team / Organization / Decision |\n| 29 (Billing) | Organization / Workspace / Process |\n| 30 (Operational Metrics) | Outcome / Objective |\n| 31 (Evolution Strategy) | Capability / Memory / Decision |\n| 32 (Plugin Runtime) | Capability / Asset / Policy |\n| 33 (Testing) | All root types as test surface |\n| 34 (System Lifecycle) | All root types as governable things |\n\n## C. Single Canonical Cross-Spec Rule for Evolving the Platform\n\n1. Update the Spine (02) entity or event vocabulary first.\n2. Update producers (03–13, 21–34) to emit the new event name.\n3. Update consumers (03–13, 21–34) to declare the new event in Events Consumed.\n4. Bump `tenant_spine_config.schema_version` (m054+) and write a migration (15.4).\n5. Roll out under feature flag (15.3 / 19.4).\n\n## D. Coverage Summary\n\n### Completed (00–34) — Architecture\n\n✅ Doctrine, Platform, Spine, Workspace, Projection, Capability, Twin, Memory, Connectors, Governance, Signals, Workflows, Entities, Marketplace, Security, Deployment, Observability, SDKs, UI, APIs, Runbooks (Part I)\n✅ NEW: Business Ontology, AI Model Runtime, Agent Runtime, Integration Manager, Continuity Engine, Search Engine, Data Pipeline, Identity Platform, Billing Platform, Operational Metrics, Evolution Strategy, Plugin Runtime, Testing Architecture, System Lifecycle (Part II)\n\n### Remaining — Implementation & Operations\n\n🔧 PRDs per module, Database DDL, OpenAPI specs, Infrastructure-as-Code\n🔧 Security audits, Compliance evidence, SLOs/SLIs, Capacity planning\n🔧 End-user docs, Administrator guides\n\n---\n\n_End of Unified Specification. Version 1.0 — Architecture Freeze._\n"}