{"slug":"operations/02-operational-spine-canonical-highest-priority","title":"02 — Operational Spine ⭐ (canonical, highest priority)","section":"operations","sectionLabel":"Operations","status":"unclassified","type":"document","path":"operations/02-operational-spine-canonical-highest-priority.mdx","bytes":6233,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Extracted from:** IntegrateWise Platform Specification Suite\n> **Region:** first_pass\n> **Original line:** 599\n> **Lines:** 116 | **Chars:** 5,866\n> **Status:** Raw extraction — requires review and canonicalization\n\n02 — Operational Spine ⭐ (canonical, highest priority)\nThis is the source of truth for every other doc. Every entity, ID, lifecycle, and event listed here is referenced verbatim by 03–20.\n\n2.1 Responsibilities\nOwn the canonical entity graph.\nOwn the canonical timeline (event-sourced append-only).\nOwn entity versioning and provenance.\nMint canonical IDs (ent*… prefix).\nResolve merge / conflict between Connector Deltas and proposed writes.\nEnforce soft-delete vs. hard-delete semantics.\nServe temporal queries (“as-of” reads).\n2.2 Canonical entity graph\nCopyTenant (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)\n2.3 Canonical IDs\nType-prefixed nanoid (collision-resistant, URL-safe).\nTenants carry tnt_id; workspaces scoped under tenant with wsp_id.\nCross-tenant references forbidden except via rel_external and explicit Marketplace grant (see 13).\nEvery ID has a 32-byte SHA-256 content-hash sidecar so duplicates can be detected without a lookup.\n2.4 Entity lifecycle states\nCopydraft ──▶ active ──▶ archived ──▶ (soft-deleted)\n▲ │ │\n│ ▼ ▼\n└────── proposed ◀── restore\n│\n▼\nhard-deleted (judicial only; tenant_id + actor + signed reason required)\nSoft delete: lifecycle.status = “deleted”, retained 90 days, hidden from projections.\nHard delete: requires Governance Token (09) with gov.posture=judicial and an immutable audit record (16).\n2.5 Timeline model\nAppend-only timeline table keyed by tl_id.\nEvery state change creates one Timeline entry; the row in the entity table is a projection of the latest Timeline entry.\nForm: { tl_id, tnt_id, ent_id, kind, payload, actor, occurred_at, source_connector, evidence_refs[] }.\n2.6 Relationship graph\nDirected, typed, attributed edges in relationship (rel*).\nAllowed: belongs_to, depends_on, references, derived_from, supersedes, contested_by.\nGraph traversal API: POST /spine/graph/traverse { from, edge[], to?, depth, as_of? } returns a DAG slice as-of as_of.\n2.7 Event model\nSpine-internal events (consumed by Projection Engine, Twin, Signals, Workflows, Governance):\n\nEvent Producer Notes\nEntityCreated 02 new ent*\nEntityUpdated 02 attribute mutation\nEntityMerged 02 conflict resolution applied\nEntityArchived 02 lifecycle change\nRelationshipAsserted 02 new rel*\nRelationshipRetracted 02 withdrawn edge\nTimelineAppended 02 always emitted, fan-out\nProvenanceRecorded 02 evidence link added\nSpineSnapshotRequested 20 / runbook scheduled export\nVersionPinned 02 explicit as-of point\n2.8 Versioning\nEach Entity row carries version (monotonic per entity).\nEvery mutation increments version; never decrements.\nTemporal query ?as_of=ISO8601 reads Timeline to reconstruct.\nSchema migrations bump tenant_spine_config.schema_version (currently aligned to m054+).\n2.9 Provenance\nEvery Entity/Relationship row carries provenance[]: at least one of { actor, source_connector, evidence_ref, derived_signal }.\nderived_signal requires the originating sig_id to be reproducible.\nProvenance is required for any field flagged pinned in the Entity Framework (12).\n2.10 Merge / conflict rules (Connector Delta vs. local edit)\nSource Authoritative for Loses to\nConnector Delta (+ ≤ 30s old) field-level truth local edit during soft-sync window\nLocal edit (pending soft-sync) during soft-sync window Connector Delta after window\nTwin proposal (pending approval) never (read-only) always\nHard governance action always all\nRule of thumb: most-recent timestamp wins, except (a) pinned fields never auto-update, (b) governance-required fields always block, © explicitly merged events track both sides.\n\n2.11 Soft vs. hard deletion\nSoft delete is the default; surfaces omit the row.\nHard delete requires gov.judicial token (09) and is recorded in audit_log (16) forever.\nCross-tenant hard delete is impossible.\n2.12 Temporal queries\nCopyGET /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=…\nAll temporal reads go through spineRead MCP tool; no Workbench code may bypass it.\n\n2.13 Storage (D1 + Durable Objects)\nHot metadata: D1 (spine.entities, spine.relationships, spine.timeline, spine.provenance).\nPer-tenant Durable Object SpineDO{tnt_id} for transactional consistency of a tenant’s write stream.\nCold snapshots: R2 (/snapshots/{tnt_id}/{date}.parquet).\n2.14 APIs\nMethod Path Purpose\nPOST /spine/entities create entity\nPATCH /spine/entities/{ent_id} mutate (issues TimelineAppended)\nGET /spine/entities/{ent_id} read (with ?as_of)\nPOST /spine/relationships assert\nGET /spine/graph/traverse DAG slice\nGET /spine/timeline paginate timeline\nPOST /spine/restore/{ent_id} from soft-delete\n2.15 Failure handling\nD1 retry: exponential, 5 attempts, ≤ 30 s.\nDO retry: 3 attempts; on exhaustion → deferred_queue (Cloudflare Queue) with evt_id.\nTemporal read with missing Timeline entries: surface “incomplete provenance” banner instead of silent fallback.\n2.16 Extension points\nCustom entity types (12) registered at tenant_spine_config.enabled_entities[].\nCustom provenance reporters (e.g., SHA-pinning artifacts).\nCustom merge strategies via plugin interface SPINE_MERGE_PLUGIN(name).\n"}