{"slug":"architecture/SPINE_TO_TWIN_BOUNDARY","title":"Spine → Twin Boundary Architecture","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/SPINE_TO_TWIN_BOUNDARY.mdx","bytes":11898,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> What Spine owns, what Twin owns, what Entity 360 bridges, and what Govern gates.\n\n---\n\n## Current Surface-Binding Doctrine\n\n- Operational Workbench = the primary work surface; left sidebar nav; Twin sidebar pops out when needed.\n- Twin Workbench = full AI ecosystem surface (skills, knowledge, agents, prompts, conversational library).\n- Governance is embedded at every layer — not a separate workbench.\n- OpenWebUI is not the customer-facing product shell.\n- Twin / OpenWebUI runtime surfaces use the canonical Forest + Paper system language.\n- Midnight Executive is investor-deck / fundraising language only.\n\nUse older L1/L2 / workspace / knowledge-UI language in this file through that boundary if any historical phrasing remains.\n\n---\n\n## Boundary Overview\n\n```\n┌───────────────────────────────────────────────────────────────────────────────────┐\n│                              IntegrateWise Platform                               │\n│                                                                                   │\n│  ┌──────────┐     ┌──────────────┐     ┌────────────────┐    ┌──────────┐    ┌───┐│\n│  │  SPINE   │────▶│  ENTITY 360  │────▶│ MorningContext │───▶│   TWIN   │────▶│GOV││\n│  │ (Write)  │     │  (Assembly)  │     │  (Edge Builder)│    │ (Reason) │    │   ││\n│  └──────────┘     └──────────────┘     └────────────────┘    └──────────┘    └───┘│\n│       ▲                                                              │         │  │\n│       │                                 NEVER                        │         │  │\n│       └─────────────────────────────────── ✗ ────────────────────────┘         │  │\n│                                                                                │  │\n│  Twin NEVER writes to Spine. Twin reasons strictly over edge MorningContext.   │  │\n└───────────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## What Spine Owns\n\nSpine is the source of truth for all entity data. It owns writes, schema, and routing.\n\n| Responsibility            | Implementation                                                 | Details                                                    |\n| ------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------- |\n| Entity storage            | Spine DB tables (`entities_account`, `entities_contact`, etc.) | Partitioned by workspace_id, RLS enforced                  |\n| Schema definition         | Postgres migrations                                            | Entity types, field types, constraints, computed columns   |\n| Schema routing            | Router Worker                                                  | Determines which table an entity writes to based on type   |\n| Source attribution        | `source_attributions` table                                    | Every field tagged with source, confidence, sync timestamp |\n| Identity links            | `identity_links` table                                         | Maps entity_id to external IDs across systems              |\n| Conflict resolution rules | `conflict_rules` table (JSONB)                                 | Per-field rules: latest-wins, highest-confidence, manual   |\n| Write validation          | CHECK constraints + triggers                                   | Confidence range, required fields, type validation         |\n| Event emission            | `entity_changed` events on Cloudflare Queue                    | Downstream consumers (Assembler, Twin) subscribe           |\n\n### Spine's Contract\n\n- Spine accepts writes ONLY from the Writer Worker (end of Flow A pipeline).\n- Spine emits `entity_changed` events for every write.\n- Spine never calls external APIs — it is a pure persistence layer.\n- Spine schema is version-controlled and deployed via migrations.\n\n---\n\n## What Twin Owns\n\nTwin is the reasoning layer. It evaluates triggers and produces insights.\n\n| Responsibility      | Implementation              | Details                                                 |\n| ------------------- | --------------------------- | ------------------------------------------------------- |\n| Trigger definitions | `trigger_definitions` table | 14 built-in types + custom triggers                     |\n| Trigger evaluation  | Twin Worker (Intelligence)  | Evaluates conditions against Entity 360 snapshots       |\n| Insight generation  | `twin_insights` table       | Severity, evidence, recommended action, entity_id       |\n| Insight routing     | Notification Worker         | Routes insights to correct view (CSM Hub, Intelligence) |\n| Trigger suppression | Dedup logic in Twin Worker  | Same trigger + entity within 24h = suppressed           |\n| Evaluation history  | `trigger_evaluations` table | Audit trail of every evaluation (fired or not)          |\n\n### Twin's Contract\n\n- **Twin reads ONLY from the Edge-Local Morning Context Retrieval Layer (`MorningContext` / `MorningContextBuilder`)** — never from raw database/Supabase tables, ensuring 100% sandboxed reasoning.\n- Twin writes ONLY to `twin_insights` and `trigger_evaluations` — never to Spine entity tables.\n- Twin does not mutate entity data. It observes and reasons.\n- Twin's insights are advisory — they recommend actions (Playbooks) but do not execute them.\n\n### Why Twin Never Writes to Spine\n\n| Risk            | Description                                                                    | Mitigation                                                       |\n| --------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------- |\n| Feedback loops  | Insight changes entity → triggers new evaluation → new insight → infinite loop | Write isolation eliminates the possibility                       |\n| Data corruption | Reasoning error writes bad data to source of truth                             | Twin has no write access to Spine                                |\n| Audit confusion | Hard to distinguish human-sourced data from machine-generated                  | Clear boundary: Spine = external data, Twin = internal reasoning |\n| Trust erosion   | Users can't trust entity data if AI modified it                                | Entity data is always from connected sources, never from Twin    |\n\n---\n\n## What Entity 360 Bridges\n\nEntity 360 is the assembly layer — a read-only API that merges Spine data into a unified view.\n\n| Responsibility            | Implementation                | Details                                                        |\n| ------------------------- | ----------------------------- | -------------------------------------------------------------- |\n| Multi-source assembly     | Assembler Worker              | Reads all source data for an entity, merges into one response  |\n| Field conflict resolution | Trust rules engine            | Applies conflict_rules to determine winning value per field    |\n| Health score computation  | Weighted formula              | Usage (40%) + Support (25%) + Engagement (20%) + Billing (15%) |\n| Relationship mapping      | Graph query on identity_links | Surfaces related entities (contacts at account, etc.)          |\n| Timeline assembly         | Chronological merge           | Events from all sources sorted by timestamp                    |\n| Edge caching              | Cloudflare KV                 | 60-second TTL, invalidated on entity_changed event             |\n| Progressive hydration     | Tiered response               | Profile (fast) → Timeline (async) → Insights (async)           |\n\n### Entity 360's Contract\n\n- Entity 360 reads from Spine tables — it never writes to them.\n- Entity 360 is the ONLY read surface for Twin — Twin never queries Spine directly.\n- Entity 360 responses include trust metadata (sources, confidence, lastSync).\n- Entity 360 is stateless — it assembles on demand (with edge caching).\n\n---\n\n## What Govern Gates\n\nGovern is the approval layer for high-impact actions.\n\n| Action                             | Gate Type           | Approvers              | Timeout   |\n| ---------------------------------- | ------------------- | ---------------------- | --------- |\n| Entity merge (identity resolution) | Single approval     | Workspace admin or CSM | 72 hours  |\n| Entity delete                      | Double approval     | Admin + second admin   | 48 hours  |\n| Bulk field override                | Single approval     | Workspace admin        | 24 hours  |\n| Connector disconnect               | Single approval     | Workspace admin        | Immediate |\n| Schema migration (custom fields)   | Admin approval      | Platform admin         | 7 days    |\n| Export (PII-containing data)       | Compliance approval | Compliance officer     | 48 hours  |\n\n### Govern's Contract\n\n- Govern does not own data — it gates access to Spine write operations.\n- Govern creates `approval_requests` with status: pending → approved/rejected.\n- Approved actions execute via the Writer Worker (same path as pipeline writes).\n- Rejected actions are logged but never executed.\n- All Govern decisions are audited in `govern_audit_log`.\n\n---\n\n## Data Flow Summary by Boundary\n\n| Flow              | Path                                                         | Writes To                            |\n| ----------------- | ------------------------------------------------------------ | ------------------------------------ |\n| Flow A (Ingest)   | Connector → Loader → Normalizer → Resolver → Router → Writer | Spine ✅                             |\n| Flow B (Assemble) | Spine → Assembler → Entity 360 cache                         | KV cache only (read-only from Spine) |\n| Flow C (Reason)   | Entity 360 → Twin → Insights                                 | twin_insights ✅ (never Spine)       |\n| Flow D (Gate)     | User action → Govern → Approval → Writer                     | Spine ✅ (only after approval)       |\n\n---\n\n## Boundary Violations to Watch For\n\n| Violation                                          | Detection                              | Severity                        |\n| -------------------------------------------------- | -------------------------------------- | ------------------------------- |\n| Twin writes to Spine table                         | RLS policy + audit log                 | Critical — architectural breach |\n| Entity 360 mutates data                            | Assembler Worker has read-only DB role | Critical — should be impossible |\n| Writer bypasses Govern for gated action            | Govern middleware check on Writer      | High — compliance risk          |\n| Direct Spine read from UI (bypassing Entity 360)   | API gateway routing rules              | Medium — consistency risk       |\n| Twin reads raw Spine tables (bypassing Entity 360) | Network policy + code review           | Medium — coupling risk          |\n"}