{"slug":"business/v1","title":"IntegrateWise Spine Schema — v1","section":"business","sectionLabel":"Business","status":"unclassified","type":"document","path":"business/v1.mdx","bytes":9539,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Status:** Canonical Specification\n> **Milestone:** Clean State Milestone 1\n> **Date:** July 22, 2026\n> **Authority:** Nirmal (Founder)\n\n---\n\n## Purpose\n\nThis document is the canonical Spine specification.\n\nIt defines the **logical model** only. Physical storage may be PostgreSQL + JSONB + pgvector/Vectorize, but that remains an implementation detail below this layer.\n\nAll workbenches, projections, capabilities, connectors, and UI renderers must derive from this specification.\n\n---\n\n## Model\n\n```\nSpine v1\n├── Entity Model\n├── Relationship Model\n├── Operational Memory\n├── Continuity\n├── Knowledge\n├── Events\n├── Embeddings\n├── Search\n├── Governance\n└── Workbench Definitions\n```\n\n---\n\n## Storage Model\n\nLogical Spine Schema\n│\n▼\nStorage Providers\n├── PostgreSQL\n├── JSONB\n├── Vector\n├── Object Storage\n├── Cache\n└── Search Index\n\nDefault implementation:\n\n- PostgreSQL + JSONB\n- pgvector / Cloudflare Vectorize\n- Redis Cache\n- R2 Object Storage\n\nEach canonical entity is composed of:\n\n```\nEntity\n├── Structured  → SQL columns\n├── Flexible    → JSONB\n├── Semantic    → Embedding(s)\n└── Operational → Timeline, Signals, Evidence\n```\n\n---\n\n## Entity Envelope\n\nEvery canonical entity uses a common envelope:\n\n```\n{\n  canonical_id,\n  entity_type,\n  tenant_id,\n  version,\n  status,\n  scope,\n  data,\n  relationships,\n  metadata,\n  provenance,\n  timeline\n}\n```\n\n- `canonical_id` — stable global identifier\n- `entity_type` — one of the canonical root concepts\n- `tenant_id` — ownership boundary\n- `version` — append-only version\n- `status` — draft, active, archived, suppressed\n- `scope` — visibility/access context\n- `data` — flexible payload\n- `relationships` — typed edges\n- `metadata` — created/updated tracking\n- `provenance` — source system and confidence\n- `timeline` — operational history\n\n---\n\n## Root Concepts\n\nThe 16 canonical root concepts are stable and must not change in v1:\n\n| Root Concept | Prefix  | Description                         |\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## Relationship Model\n\nRelationships are first-class typed edges.\n\n- `source_id`\n- `target_id`\n- `relationship_type`\n- `valid_from`\n- `valid_until`\n- `metadata`\n- `confidence`\n\nRelationships are adaptively valid per tenant, department, industry, and governance policy.\n\n---\n\n## Operational Primitives\n\nSeven operational primitives remain stable:\n\n- Tenant\n- Entity\n- Relationship\n- Timeline\n- Activity\n- Evidence\n- Provenance\n\n---\n\n## Events\n\nEvents are append-only operational deltas emitted from canonical writes.\n\n- `created`\n- `updated`\n- `status_changed`\n- `linked`\n- `unlinked`\n- `promoted`\n- `governed`\n- `approved`\n- `rejected`\n- `suppressed`\n\nEvents drive:\n\n- real-time subscriptions\n- webhook notifications\n- audit trails\n- AI observations\n\n---\n\n## Continuity\n\nThe Spine persists state beyond session boundaries.\n\nContinuity operations:\n\n- `spine.context(tenantId)`\n- `spine.continuity(sessionId)`\n- `spine.remember(memory)`\n- `spine.hydrate(entityId)`\n\nContinuity enables:\n\n- cross-session Twin context\n- long-running workflows\n- operational memory\n- handoff and recovery\n\n---\n\n## Knowledge\n\nKnowledge is derived from Spine, not raw external state.\n\n- Promotion gate: evidence → knowledge\n- Lineage tracking\n- Deprecation rules\n- Confidence scoring\n\nSchema AI, ingestion pipelines, and memory consolidation all consume the Spine as the canonical source.\n\n---\n\n## Embeddings\n\nEmbeddings are first-class for every canonical entity.\n\n```\nEntity\n├── Structured → SQL columns\n├── Flexible   → JSONB\n├── Semantic   → Embedding(s)\n└── Operational→ Timeline, Signals, Evidence\n```\n\nEmbedding behavior is governed by field semantics:\n\n- `include: true/false`\n- `model: text-embedding-3-small | ...`\n- `scope: public | private | tenant`\n- `update: on_write | on_read | scheduled`\n\nDefault storage target: pgvector or Cloudflare Vectorize.\n\n---\n\n## Search\n\nSearch is derived from:\n\n- structured fields\n- JSONB fields\n- embeddings\n- relationships\n- timeline/events\n\nSearch indexes are role/projection-aware.\n\n---\n\n## Governance\n\nGovernance lives inside the Spine model, not around it.\n\n- `Policy` is a canonical entity\n- `Decision` is a canonical entity\n- `Evidence` is a canonical entity\n- Approval, rejection, and suppression are Spine operations\n- Signals carry confidence and governance state\n\nTwo-gate governance applies to:\n\n- capabilities\n- schema changes\n- connector registrations\n- promotion from evidence to knowledge\n\n---\n\n## Workbench Definitions\n\nWorkbenches are role-specific projections over the same canonical Spine.\n\n```\nCanonical Spine\n    │\n    ├── Founder Projection\n    ├── Sales Projection\n    ├── Customer Success Projection\n    ├── Marketing Projection\n    ├── Finance Projection\n    ├── Operations Projection\n    └── Engineering Projection\n```\n\nA workbench definition declares:\n\n- entities to expose\n- capabilities available in the workbench\n- continuity items\n- widgets\n- role-specific field visibility\n\nExample:\n\n```yaml\nworkbench: sales\nentities:\n  - account\n  - contact\n  - opportunity\n\ncapabilities:\n  - qualify_lead\n  - create_opportunity\n  - send_email\n\ncontinuity:\n  - conversations\n  - meetings\n\nwidgets:\n  - pipeline\n  - forecast\n```\n\nThe UI, search, and capabilities all derive from this single source.\n\n---\n\n## Field Semantics\n\nEvery field is a governed operational asset.\n\nField semantics define:\n\n- storage\n- validation\n- UI presentation\n- permissions\n- search behavior\n- embedding behavior\n- capability binding\n- event emission\n- projection rules\n\nExample:\n\n```yaml\nentity: Account\n\nfield: account.name\n  storage:\n    type: text\n    column: name\n\n  ui:\n    label: Company Name\n    placeholder: Enter company name\n    control: text\n    required: true\n\n  search:\n    indexed: true\n    fulltext: true\n\n  embedding:\n    include: true\n\n  permissions:\n    read:\n      - sales\n      - founder\n    write:\n      - sales_manager\n\n  workbenches:\n    founder:\n      visible: true\n      section: overview\n    sales:\n      visible: true\n      section: basic\n    finance:\n      visible: false\n\n  capabilities:\n    requires:\n      - crm.account.create\n      - crm.account.update\n```\n\nThis means:\n\n- one definition drives storage, UI, search, embeddings, permissions, capabilities, and projections\n- adding a field requires updating one place only\n- all downstream systems discover the change automatically\n\n---\n\n## Adaptive UI\n\nUI rendering is driven by Spine field semantics and workbench projections.\n\n```\nWorkbench\n    │\n    ▼\nProjection\n    │\n    ▼\nField Metadata\n    │\n    ▼\nUI Renderer\n```\n\nThe renderer asks:\n\n- “How should I display this field?”\n- “Should this field be visible for this role?”\n- “What controls does this field require?”\n\nNot hardcoded form assumptions.\n\n---\n\n## Adaptive Capabilities\n\nCapabilities declare required fields, not React forms.\n\n```yaml\ncapability: crm.account.create\nrequires:\n  - account.name\n  - account.owner\n  - account.industry\n```\n\nThe UI resolves required fields from the Spine schema and renders the form dynamically.\n\n---\n\n## Canonical Spine Registry\n\nThe Spine specification is the authoritative source for:\n\n- storage semantics\n- UI rendering\n- validation\n- permissions\n- search behavior\n- embeddings\n- AI context\n- capability bindings\n- projection rules\n- event mappings\n- synchronization behavior\n\nEverything else consumes that registry.\n\n## Docs\n\n- [docs/architecture/CANONICAL_SPINE_CONVERGED.md](/Users/nirmal/Documents/kimi/workspace/integratewise-live/docs/architecture/CANONICAL_SPINE_CONVERGED.md)\n- [docs/internal/sql-migrations/026_universal_spine_schema.sql](/Users/nirmal/Documents/kimi/workspace/integratewise-live/docs/internal/sql-migrations/026_universal_spine_schema.sql)\n- [docs/internal/sql-migrations/035_spine_adaptive_registry.sql](/Users/nirmal/Documents/kimi/workspace/integratewise-live/docs/internal/sql-migrations/035_spine_adaptive_registry.sql)\n- [packages/types/src/spine-schema-provider.ts](/Users/nirmal/Documents/kimi/workspace/integratewise-live/packages/types/src/spine-schema-provider.ts)\n- [services/pipeline/src/canonical/operational-definitions.ts](/Users/nirmal/Documents/kimi/workspace/integratewise-live/services/pipeline/src/canonical/operational-definitions.ts)\n"}