{"slug":"internal/architecture/CANONICAL_SPINE_CONVERGED","title":"Canonical Spine — Converged Architecture","section":"internal","sectionLabel":"Internal","status":"superseded","type":"document","path":"internal/architecture/CANONICAL_SPINE_CONVERGED.mdx","bytes":10728,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** SUPERSEDED AS A FULL IMPLEMENTATION CLAIM — adaptation reference only\n**Date:** July 20, 2026\n**Supersedes:** Previous fragmented Spine implementations\n\n> The configuration/projection doctrine remains useful, but D1 provisioning and\n> deployment claims in this file do not override Neon truth and D1/KV bounds in\n> [`INTEGRATEWISE_ARCHITECTURE.md`](INTEGRATEWISE_ARCHITECTURE.md) v2.2.\n\n---\n\n## The Governing Principle\n\nThe Spine adapts by **configuration and interpretation**, not by changing its foundational concepts.\n\n- **Stable:** ontology, entity envelope, relationship model, event model, canonical IDs.\n- **Adaptive:** entity definitions, connector mappings, governance policies, memory strategies, projections, AI context, and workbench views.\n\nThis separation allows tenants in different industries and with different operational needs to share the same canonical model while experiencing a system that behaves as though it were tailored specifically to their organization.\n\n---\n\n## Architecture\n\n```\n                Universal Ontology\n                       │\n             (never changes)\n                       │\n        ┌──────────────┴──────────────┐\n        │                             │\n Adaptive Definitions          Governance Rules\n        │                             │\n        └──────────────┬──────────────┘\n                       │\n               Canonical Spine\n                       │\n         ┌─────────────┼─────────────┐\n         │             │             │\n      Memory      Projections     AI/Twins\n```\n\n### Layer 1: Universal Ontology (Stable)\n\nThe 16 root concepts + 7 operational primitives never change:\n\n- Organization, Person, Team, Process, Project, Objective, Outcome, Asset, Knowledge, Decision, Policy, Capability, Signal, Memory, Conversation\n- Tenant, Entity, Relationship, Timeline, Activity, Evidence, Provenance\n\n### Layer 2: Adaptive Definitions\n\nWhat changes per tenant:\n\n- **Entity definitions:** What fields an Organization has for SaaS vs Healthcare\n- **Relationship patterns:** What graph edges are valid\n- **Connector mappings:** How Salesforce Account → Organization, HubSpot Company → Organization\n- **Memory categories:** Which memory types are relevant\n- **Governance rules:** Strict audit for healthcare, light touch for SaaS\n\n### Layer 3: Canonical Spine (Storage)\n\nThe persisted graph:\n\n- `spine_entities` — append-only versioned entities\n- `spine_relationships` — typed edge graph\n- `spine_timeline` — immutable audit trail\n- `spine_entity_resolution` — external ID → canonical ID mapping\n\n### Layer 4: Consumption Layers\n\n- **Memory** — derives from Spine, opinion not truth\n- **Projections** — role-specific views assembled at query time\n- **AI/Twins** — different context bundles from the same Spine\n\n---\n\n## The 16 Root Concepts\n\nEvery business entity in IntegrateWise maps to one of these canonical types:\n\n| Root Concept   | Prefix  | What it is                          |\n| -------------- | ------- | ----------------------------------- |\n| `Organization` | `org_`  | Legal entity owning the tenant      |\n| `Workspace`    | `wsp_`  | Bounded context inside Organization |\n| `Person`       | `usr_`  | First-class human                   |\n| `Team`         | `team_` | Durable grouping of Persons         |\n| `Process`      | `proc_` | Repeatable set of capabilities      |\n| `Project`      | `prj_`  | Temporary initiative with timeline  |\n| `Objective`    | `obj_`  | Measurable goal                     |\n| `Outcome`      | `out_`  | Evidence-verified result            |\n| `Asset`        | `ast_`  | Durable resource                    |\n| `Knowledge`    | `knw_`  | Curated institutional memory        |\n| `Decision`     | `dec_`  | Governance-approved choice          |\n| `Policy`       | `pol_`  | Declarative rule                    |\n| `Capability`   | `cap_`  | Declarable action on the fabric     |\n| `Signal`       | `sig_`  | Derived delta with score            |\n| `Memory`       | `mem_`  | Captured observation with lifecycle |\n| `Conversation` | `conv_` | Twin ↔ User dialog                  |\n\n---\n\n## The Adaptation Model\n\n### Identity-Driven Adaptation\n\nThe adaptive resolver (`services/gateway/src/spine-schema.ts`) evaluates:\n\n- Tenant\n- Department\n- Role\n- Industry\n- Business Model\n- Enabled Capabilities\n- Connected Systems\n- Policies\n\nTwo tenants in the same department but different industries get different operational profiles.\n\n### Entity Definition Adaptation\n\nSame ontology concept, different operational definitions:\n\n**SaaS Organization:**\n\n- ARR, MRR, Renewal Date, Health Score, Usage, Segment, Tier\n\n**Healthcare Organization:**\n\n- Type, Department, Budget, Program, Compliance Status, Accreditation, Patient Capacity\n\n**Manufacturing Organization:**\n\n- Factory, Supplier Tier, Quality Rating, Production Capacity, Certifications\n\n### Relationship Adaptation\n\nThe typed edge graph adapts per domain:\n\n| Domain           | Relationship Example           |\n| ---------------- | ------------------------------ |\n| Customer Success | Organization owns Success Plan |\n| Engineering      | Organization owns Repository   |\n| Healthcare       | Patient treated_by Provider    |\n| Finance          | Account belongs_to Portfolio   |\n\n### Connector Adaptation\n\nConnectors determine what evidence exists. Pipeline normalizes to ontology:\n\n| Connector  | Source Concept | Canonical Concept |\n| ---------- | -------------- | ----------------- |\n| Salesforce | Account        | Organization      |\n| HubSpot    | Company        | Organization      |\n| Dynamics   | Customer       | Organization      |\n\nThe Spine never stores Salesforce concepts. It stores ontology concepts.\n\n### Memory Adaptation\n\nMemory categories adapt per domain:\n\n| Domain  | Memory Categories                                    |\n| ------- | ---------------------------------------------------- |\n| Sales   | Deal Memory, Meeting Memory, Conversation Memory     |\n| Support | Incident Memory, Knowledge Memory, Resolution Memory |\n| Finance | Approval Memory, Policy Memory, Audit Memory         |\n\n### Governance Adaptation\n\nSame ontology, different governance:\n\n**Healthcare:**\n\n- Signal → Approval Required → Evidence Required → Audit Trail\n\n**Startup SaaS:**\n\n- Signal → Auto Execute\n\n### Projection Adaptation\n\nOne entity, multiple projections:\n\n**Founder sees:** Revenue, Growth, Risk, Strategy\n**CS sees:** Health, Renewal, Adoption\n**Support sees:** Tickets, SLA, Escalations\n**Finance sees:** Invoices, ARR, Collections\n\n### AI Adaptation\n\nAI does not mutate the Spine. The Spine provides different context bundles:\n\n**Founder Twin:** Executive Signals, KPIs, Strategic Risks\n**CS Twin:** Renewals, Usage, Playbooks, Accounts\n**Engineering Twin:** Repositories, Incidents, Deployments\n\n---\n\n## Write Path\n\n```\nConnector / Webhook / MCP / API / Manual\n        ↓\nPipeline (sole writer)\n        ↓\nAdaptive Resolver\n        ↓\nEntity Type Mapping\n        ↓\nCanonical Entity Creation\n        ↓\nspine_entities (append-only)\n        ↓\nspine_timeline (audit trail)\n        ↓\nMemory (derives from Spine)\n```\n\n## Read Path\n\n```\nUser / Twin / API\n        ↓\nProjection Engine\n        ↓\nResolve Tenant Operational Profile\n        ↓\nQuery Canonical Spine\n        ↓\nRole-Specific View\n        ↓\nTypedProjectionResult\n```\n\n---\n\n## Key Design Decisions\n\n### 1. Hybrid Storage Model\n\nCanonical metadata (typed, queryable): `canonical_id`, `entity_type`, `tenant_id`, `version`, `status`\n\nCore fields (typed): `name`, `domain`, `industry`, `role`, `department`\n\nBusiness payload (JSON): provider-specific attributes\n\nThis avoids migration sprawl while keeping the ontology stable.\n\n### 2. Append-Only Versioning\n\nEvery mutation creates a new version. Old version invalidated via `valid_until`. Enables audit, time-travel, rollback, AI reasoning over history.\n\n### 3. Typed Edge Graph\n\nRelationships are first-class: typed edges with temporal validity, metadata, and confidence.\n\n### 4. Operational Definitions\n\nStored in `spine_operational_definitions`. Adapts fields, relationships, connector mappings, governance rules, memory categories, and projection fields per industry/department.\n\n### 5. Tenant Profiles\n\n`spine_tenant_profiles` stores the resolved operational profile for each tenant. Drives all downstream consumption.\n\n---\n\n## Implementation Status\n\n| Component                | Status      | Location                                                      |\n| ------------------------ | ----------- | ------------------------------------------------------------- |\n| Universal Ontology       | ✅ Stable   | 16 root concepts + 7 primitives                               |\n| Adaptive Resolver        | ✅ Complete | `services/gateway/src/spine-schema.ts`                        |\n| Operational Definitions  | ✅ Complete | `services/pipeline/src/canonical/operational-definitions.ts`  |\n| Entity Type Mapping      | ✅ Complete | `services/pipeline/src/canonical/entity-type-map.ts`          |\n| Canonical Spine Writer   | ✅ Complete | `services/pipeline/src/canonical/canonical-writer.ts`         |\n| Adaptive Bridge          | ✅ Complete | `services/gateway/src/canonical-spine-bridge.ts`              |\n| SQL Schema (core)        | ✅ Complete | `sql-migrations/080_canonical_spine_entities.sql`             |\n| SQL Schema (operational) | ✅ Complete | `sql-migrations/081_operational_definitions.sql`              |\n| D1 Database              | ⏳ Pending  | Create via `wrangler d1 create integratewise-canonical-spine` |\n| Pipeline Integration     | ✅ Complete | `services/pipeline/src/index.ts`                              |\n| Projection Engine        | ⏳ Pending  | Assemble role-specific views                                  |\n| Memory → Spine Reads     | ⏳ Pending  | Memory should consume Spine                                   |\n\n---\n\n## Next Steps\n\n1. **Create D1 database**: `wrangler d1 create integratewise-canonical-spine`\n2. **Run migrations**: Apply `080` and `081` SQL files\n3. **Update wrangler.toml**: Add actual D1 database IDs\n4. **Deploy pipeline**: `wrangler deploy` in `services/pipeline/`\n5. **Implement projection engine**: Assemble role-specific views from canonical Spine + operational definitions\n6. **Wire memory to Spine reads**: Memory consumes Spine, doesn't replace it\n7. **Seed operational definitions**: Populate `spine_operational_definitions` with industry/department variants\n"}