{"slug":"architecture/SPINE_SCHEMA","title":"Spine Schema","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/SPINE_SCHEMA.mdx","bytes":6978,"description":"The canonical data model for Spine Fabric — what is stored, how it is organized, and the rules that govern every record.","updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\nSpine Schema defines the canonical data model for all operational truth in SpineWorkspace. Every entity, relationship, event, decision, piece of evidence, work item, and memory entry follows this schema.\n\nThe schema is not a single database table. It is a **multi-store fabric** where each layer owns a specific class of truth.\n\n## Governing Rules\n\n1. **One Spine per tenant.** Role, department, and industry alter projection scope — not storage ownership.\n2. **No direct UI database reads.** The Workbench reads projected shapes through the Projection Platform API.\n3. **All writes preserve provenance.** Every mutation records actor, origin, evidence, confidence, timestamps, and source connection.\n4. **AI proposes; humans decide.** Cognitive output enters a proposal/approval path before operational promotion.\n5. **Connect once, available everywhere.** Connector ownership is tenant-scoped, not frontend-scoped.\n\n## Multi-Store Fabric\n\nThe Spine is a 6-layer fabric:\n\n| Layer | Store | What It Owns | Access Pattern |\n|-------|-------|-------------|----------------|\n| **L1** | PostgreSQL / Neon / D1 | Structured operational truth — entities, relationships, tasks, approvals, signals | SQL via Projection Platform |\n| **L2** | Redis / KV | Hot state — projection caches, SLA countdowns, queue positions, session context | Key-value, sub-100ms |\n| **L3** | R2 / Object Storage | Attachments — documents, recordings, exports, images | Signed URLs, streaming |\n| **L4** | Conversational Store | Ingested channels — email threads, chat transcripts, call recordings | Append-only, Pipeline-processed |\n| **L5** | Vectorize / pgvector | Semantic embeddings — similarity, knowledge retrieval, signal detection | Vector search, RRF scoring |\n| **L6** | Durable Objects | Agent memory — session state, user preferences, workspace context | Per-keyed hot state, snapshot to D1 |\n\n**Rule:** No department reads directly from any store. All reads go through the Projection Platform API.\n\n## Universal Record Envelope\n\nEvery operational table carries this minimum contract:\n\n```sql\nid                 text primary key,\ntenant_id          text not null,\nworkspace_id       text,\nstatus             text not null,\nversion            integer not null default 1,\norigin             text not null,\nconfidence         numeric(5,4),\nsource_connection_id text,\nprovenance         jsonb not null default '[]',\nmetadata           jsonb not default '{}',\ncreated_by         text,\nupdated_by         text,\ncreated_at         timestamptz not null,\nupdated_at         timestamptz not null,\narchived_at        timestamptz\n```\n\nAll tenant queries require `tenant_id`. Sensitive projections additionally require workspace, role, permission, and policy checks.\n\n## Core Entity Types\n\n### Identity and Tenancy\n\n- `tenants` — organization, plan, industry, region, schema version\n- `workspaces` — tenant workspace with department, industry, projection manifest\n- `users` — identity with department, manager, timezone, locale\n- `teams` — team with department and owner\n- `roles` — role with scope and governance posture\n- `permissions` — permission key, resource, action, risk level\n- `memberships` — user-workspace-role bindings\n\n### Entity and Relationship Truth\n\n- `entities` — canonical entity anchor with type, name, external keys, attributes, lifecycle\n- `relationships` — typed, weighted, time-bounded entity connections\n- `entity_versions` — append-only snapshots\n- `timeline_events` — append-only operational history with event type, subject, payload, evidence\n- `evidence` — source citations, hashes, document spans, connector references\n\n### Work, Governance, and Signals\n\n- `tasks` — title, assignee, priority, due date, entity, completion state\n- `work_items` — generalized operational item with type, queue, SLA, payload\n- `queues` — routing policy and owner\n- `assignments` — work-item-to-assignee bindings\n- `approvals` — proposal, capability, risk level, approver chain, decision\n- `proposals` — type, subject, recommended action, reasoning, confidence, evidence\n- `signals` — kind, priority, score, detection, resolution state\n- `policies` — approval, retention, write-back, data visibility, capability policies\n\n### Communications and Knowledge\n\n- `communication_threads` — channel, participants, linked entities\n- `messages` — sender, recipients, body, classification\n- `calendar_events`, `meetings`, `calls` — temporal coordination\n- `documents`, `document_chunks` — storage references and semantic embeddings\n- `knowledge_articles` — reviewed organizational knowledge\n\n### Memory and Continuity\n\n- `memory_items` — scope (user|work|org|agent|development|conversation), type, content, importance\n- `memory_proposals` — proposed promotion with classification, confidence, approval state\n- `continuity_contexts` — effective role, workspace, active entities, goals, recent evidence\n\n### Capability and Integration\n\n- `connectors` — provider, category, auth type, supported objects\n- `connections` — tenant-owned installation with health and sync state\n- `capabilities` — key, plane, inputs, outputs, governance policy\n- `capability_invocations` — request, authorization, execution, result, rollback, audit\n\n## Department Pattern\n\nEvery department defines:\n\n1. Structured operational tables\n2. Hot-state keys and projection caches\n3. Attachment/object namespaces\n4. Conversational ingestion classes\n5. Semantic/vector collections\n6. User, work, and organization memory scopes\n\nThe Workbench shell is constant across departments: Header, Pulse Bar, Main Work Surface, Action/Governance Bar, and contextual Twin surface.\n\n## Storage Ownership (Canonical)\n\nFrom the canonical ontology, storage is divided into four tiers:\n\n| Tier | What It Owns | Authority |\n|------|-------------|-----------|\n| **Spine Fabric** | Canonical entities, relationships, Work, events, decisions, evidence, memory, continuity | System of record |\n| **Memory** | Episodic, semantic, operational, user, work, org, agent, development, conversation scoped | Informs truth; memory is not truth |\n| **Fortress** | Audit, execution ledger, signed proposals, incident reconstruction | Append-only, tamper-evident |\n| **Ephemeral** | Session scratchpads, agent working state, transient caches | Disposable, no authority |\n\n**Rule:** Memory informs truth. Memory is not truth. Triage classifies. Governance decides. The Pipeline promotes. Spine owns organizational memory.\n\n## Related\n\n- [Canonical Ontology §39-40](/architecture/CANONICAL_ONTOLOGY) — storage ownership\n- [Projection Contract](/architecture/PROJECTION_CONTRACT) — how schema is projected\n- [Organizational Memory](/architecture/ORG_MEMORY_CANONICAL_MODEL) — memory authority\n"}