{"slug":"internal/architecture/CANONICAL_ENTITY_CONSTITUTION","title":"Canonical Entity Constitution","section":"internal","sectionLabel":"Internal","status":"unclassified","type":"document","path":"internal/architecture/CANONICAL_ENTITY_CONSTITUTION.mdx","bytes":6619,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\nStatus: SUPERSEDED / ABSORBED — historical subsystem constitution. Current authority: [`INTEGRATEWISE_ARCHITECTURE.md`](INTEGRATEWISE_ARCHITECTURE.md) v2.2.\nScope: Stable entity shapes, relationships, state machines, and field contracts for the Adaptive Spine.\nCanonical Owner: IntegrateWise Platform\nLast Verified: 2026-07-20\n\n---\n\n## 1. Purpose\n\nThis document defines the canonical entity layer. All projections, capabilities, connectors, and Twin behavior depend on these contracts.\n\nChange this document only through platform amendment.\n\n---\n\n## 2. Entity Registry\n\n```typescript\nexport type EntityType =\n  | \"account\"\n  | \"contact\"\n  | \"opportunity\"\n  | \"deal\"\n  | \"lead\"\n  | \"renewal\"\n  | \"risk\"\n  | \"task\"\n  | \"meeting\"\n  | \"ticket\"\n  | \"incident\"\n  | \"bug\"\n  | \"sprint\"\n  | \"release\"\n  | \"deployment\"\n  | \"invoice\"\n  | \"expense\"\n  | \"payment\"\n  | \"campaign\"\n  | \"attribution\"\n  | \"content\"\n  | \"form\"\n  | \"ad\"\n  | \"feature\"\n  | \"epic\"\n  | \"story\"\n  | \"feedback\"\n  | \"pull_request\"\n  | \"commit\"\n  | \"knowledge_article\"\n  | \"document\"\n  | \"note\"\n  | \"goal\"\n  | \"project\"\n  | \"initiative\"\n  | \"workflow\"\n  | \"process\"\n  | \"vendor\"\n  | \"contract\"\n  | \"purchase_order\"\n  | \"spend_analysis\"\n  | \"system\"\n  | \"vulnerability\"\n  | \"employee\"\n  | \"student\"\n  | \"course\"\n  | \"assignment\"\n  | \"generated_insight\"\n  | \"timeline_entry\"\n  | \"action_proposal\"\n  | \"action_run\"\n  | \"approval_token\";\n```\n\n---\n\n## 3. Canonical Field Contracts\n\n### 3.1 Account\n\n| Field        | Type   | Required | Description                    |\n| ------------ | ------ | -------- | ------------------------------ |\n| id           | string | yes      | Spine entity id                |\n| tenant_id    | string | yes      | Tenant partition               |\n| name         | string | yes      | Account name                   |\n| industry     | string | no       | Industry vertical              |\n| health_score | number | no       | 0-100                          |\n| arr          | number | no       | Annual recurring revenue       |\n| mrr          | number | no       | Monthly recurring revenue      |\n| renewal_date | string | no       | ISO date                       |\n| risk         | string | no       | Risk level                     |\n| status       | string | yes      | Entity status                  |\n| source       | string | no       | Authoritative source connector |\n| created_at   | string | yes      | Spine timestamp                |\n| updated_at   | string | yes      | Spine timestamp                |\n\n### 3.2 Opportunity / Deal\n\n| Field       | Type   | Required | Description                    |\n| ----------- | ------ | -------- | ------------------------------ |\n| id          | string | yes      | Spine entity id                |\n| account_id  | string | yes      | Linked account                 |\n| stage       | string | yes      | Pipeline stage                 |\n| amount      | number | no       | Deal value                     |\n| probability | number | no       | 0-100                          |\n| close_date  | string | no       | ISO date                       |\n| owner       | string | no       | Assigned owner                 |\n| next_step   | string | no       | Next action                    |\n| source      | string | no       | Authoritative source connector |\n\n### 3.3 Task\n\n| Field       | Type   | Required | Description                    |\n| ----------- | ------ | -------- | ------------------------------ |\n| id          | string | yes      | Spine entity id                |\n| subject     | string | yes      | Task title                     |\n| status      | string | yes      | Task status                    |\n| priority    | string | no       | Task priority                  |\n| assignee    | string | no       | Assigned user                  |\n| due_date    | string | no       | ISO date                       |\n| entity_type | string | no       | Linked entity type             |\n| entity_id   | string | no       | Linked entity id               |\n| source      | string | no       | Authoritative source connector |\n\n### 3.4 Ticket\n\n| Field      | Type   | Required | Description                    |\n| ---------- | ------ | -------- | ------------------------------ |\n| id         | string | yes      | Spine entity id                |\n| account_id | string | yes      | Linked account                 |\n| status     | string | yes      | Ticket status                  |\n| priority   | string | yes      | Ticket priority                |\n| assignee   | string | no       | Assigned agent                 |\n| sla_status | string | no       | SLA state                      |\n| source     | string | no       | Authoritative source connector |\n\n---\n\n## 4. Relationship Contracts\n\n| Relationship          | From    | To          | Cardinality | Description           |\n| --------------------- | ------- | ----------- | ----------- | --------------------- |\n| account.contacts      | account | contact     | 1:N         | Account contacts      |\n| account.opportunities | account | opportunity | 1:N         | Account opportunities |\n| account.renewals      | account | renewal     | 1:N         | Account renewals      |\n| account.risks         | account | risk        | 1:N         | Account risks         |\n| account.tickets       | account | ticket      | 1:N         | Account tickets       |\n| deal.contacts         | deal    | contact     | 1:N         | Deal contacts         |\n| task.account          | task    | account     | N:1         | Task account link     |\n| ticket.account        | ticket  | account     | N:1         | Ticket account link   |\n| sprint.tasks          | sprint  | task        | 1:N         | Sprint tasks          |\n| feature.epic          | feature | epic        | N:1         | Feature epic link     |\n\n---\n\n## 5. State Machines\n\n### 5.1 Opportunity / Deal\n\n```\nnew → qualified → proposal → negotiation → won\n                                 → lost\n```\n\n### 5.2 Task\n\n```\nopen → in_progress → blocked → done\n                         → cancelled\n```\n\n### 5.3 Ticket\n\n```\nnew → open → pending → solved → closed\n       → escalated\n```\n\n### 5.4 Sprint\n\n```\nplanned → active → completed → archived\n                → cancelled\n```\n\n---\n\n## 6. Invariants\n\n1. Every entity has `tenant_id`, `source`, `created_at`, `updated_at`.\n2. The Spine never overwrites authoritative external data without a traceable sync mutation.\n3. Entity ids are immutable.\n4. Relationships are resolved through Spine ids, not external system ids alone.\n5. State transitions emit a timeline entry.\n"}