{"slug":"architecture/CANONICAL_ONTOLOGY","title":"Canonical Ontology","section":"architecture","sectionLabel":"Architecture","status":"canon","type":"document","path":"architecture/CANONICAL_ONTOLOGY.mdx","bytes":24242,"description":"Master conceptual model for SpineWorkspace and the IntegrateWise platform","updated":"2026-08-24","source":"integratewise/Integratewise-docs-wiki","content":"\n\nThe organizing center is **Business Context**.\n\nNot AI. Not the Workbench. Not integrations. Not the agent network.\n\nEverything exists to make **business context continuously available, projectable, actionable,\ngovernable, executable, and continuous across organizational work**.\n\nSpine Fabric is the contextual business-memory and continuity layer making it available to\nhumans and AI.\n\n## 1. The Ontology at One Glance\n\n```text\nINTEGRATEWISE (integratewise.ai · COMPANY)\n└── SPINEWORKSPACE (spineworkspace.com · PRODUCT)\n    ├── BUSINESS CONTEXT — Business Reality · Org Context · Business Memory · Current/Historical State\n    │                      Relationships · Events · Decisions · Evidence · Policies · Commitments\n    │                      Dependencies · Risks · Outcomes\n    ├── SPINE FABRIC — Canonical Spine · Operational Spine · Operational Sandbox · Context Assembly\n    │                 Memory · Continuity · Provenance · Schema · Lineage · Reconciliation · Promotion\n    ├── ORGANIZATION — Org · Business Units · Departments · Teams · People · Roles · Responsibilities\n    │                 Authority · Policies · Goals · Objectives · Standards · Outcomes\n    ├── BUSINESS DOMAINS — Executive · Sales · Marketing · Account Success · TAS · Support/Service\n    │                     Finance · RevOps · BizOps · Product · Engineering · HR · Legal · IT\n    │                     Security/Risk · Procurement · Administration\n    ├── WORK — Objective · Work · Work Graph · Task · Assignment · Decision · Approval\n    │          Communication · Research · Action · Dependency · Exception · Evidence\n    │          Execution · Outcome · Continuity\n    ├── PROJECTION — User · Role · Domain · Responsibility · Authority · Permission\n    │               Industry · Current Work · Relevance · Policy · Context\n    ├── HUMAN WORKBENCH — Personal · Today · My Work · My Queue · Tasks · Inbox · Approvals\n    │                    Communications · Organizational Memory · Knowledge · Work Surfaces · Domain Projections\n    ├── AI WORKSPACE — Twin · Twin Workspace · OODA · Coworker · Triage · Agents\n    │                 Working Memory · Context · Plans · Delegation · Handoffs · Execution State\n    ├── AGENT FABRIC — Twin · Coworker · Triage · Domain · Specialist · Research · Workflow · External Agents\n    ├── CAPABILITY FABRIC — Capability · Registry · Contract · Policy · Inputs · Outputs\n    │                     Evidence Requirements · Execution Binding\n    ├── EXECUTION FABRIC — API · MCP · Spine Tools · Workflow · Pipeline · ADK\n    │                    Agent Runtime · Orchestration · Queue · Worker · Durable Execution\n    ├── GOVERNANCE — Identity · Authority · Permissions · Policy · Risk · Approval · Consent · Evidence · Audit · Accountability\n    ├── CONNECTIVITY — Connector · Provider · API · MCP · OAuth · Credential Ref\n    │                Webhook · Event · Sync · Schema Ingestion · External Platform\n    ├── MEMORY — Personal · Conversational · Agent · Work · Entity · Organizational Staging · Organizational Published\n    ├── RECONCILIATION — Intent · Execution · Receipt · Actual State · Verification · Reconciliation · Outcome\n    └── PLATFORM SUBSTRATE — Identity · Configuration · Routing · AI Runtime · Execution Runtime\n                            Communications · Governance Runtime · Infrastructure · Observability\n                            Metering · OmniRoute\n```\n\n## 2. Dual Hosting / Product Domain Ontology\n\nThis is the **actual dual-domain model**:\n\n| Domain               | Represents                                                                                  | Contains                                                                                          |\n| -------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |\n| `integratewise.ai`   | **IntegrateWise** — the company, platform builder, technology provider, corporate authority | Company · Platform · Technology · Solutions · Resources · Documentation · Corporate               |\n| `spineworkspace.com` | **SpineWorkspace** — the customer-facing product and work environment                       | Product · Workspace · Work · Business Domains · Communications · Personal · Twin · Administration |\n\n```text\nINTEGRATEWISE (integratewise.ai)\n       │ builds / operates\n       ▼\nSPINEWORKSPACE (spineworkspace.com)\n```\n\nBusiness domains such as Finance or Sales are **inside SpineWorkspace** — they are not the\nsecond meaning of dual-domain terminology.\n\n## 3. Business Context Ontology\n\n| Term                      | Meaning                                                                                                                                                                                                                                      |\n| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Business Reality**      | Complete current + historical state: entities, work, relationships, events, decisions, transactions, commitments, policies, outcomes                                                                                                         |\n| **Business Context**      | The subset/representation of reality needed to understand or perform particular work                                                                                                                                                         |\n| **Business Memory**       | Persistent information retained from previous activity                                                                                                                                                                                       |\n| **Organizational Memory** | Governed institutional knowledge surviving sessions and agents — derived from organizational events, decisions, evidence, work outcomes, approved interpretations. NOT raw chat, agent memory, unreviewed extraction, or a bare vector index |\n| **Continuity**            | Preservation of coherent work across time, people, systems, teams, sessions, AI actors                                                                                                                                                       |\n\n```text\nMemory + Current State + Context + Work History = Continuity\n```\n\n## 4–5. Organization Ontology\n\nThe organization is the root business object: identity; structure (business unit → department →\nteam → function); people (employee, manager, relationship); roles, responsibilities, authority;\ngoals, objectives, standards, policies; processes, capabilities, outcomes.\n\nOrganizational lifecycle:\n\n```text\nNeed → Goal → Objective → Plan → Work → Assign → Execute → Monitor\n→ Decide → Complete → Verify → Reconcile → Outcome → Learn → Continuous Improvement\n```\n\n**One shared context.** Departments and roles are projection and authority dimensions — never\nstorage partitions:\n\n```text\nONE ORGANIZATION → CANONICAL SPINE\n        ├─ Sales ─┐\n        ├─ CS ────┼── same Work Graph\n        └─ Finance┘\n```\n\nCross-team work uses governed projections of the same Work Graph — no duplicated databases,\nno departmental copies of truth.\n\n## 6. Business Domain Ontology\n\nDomains represent where work belongs: Executive, Sales, Marketing, Account Success, Technical\nAccount Success, Support/Service, Finance, RevOps, Business Operations, Product, Engineering,\nHR, Legal, IT, Security/Risk, Procurement, Administration.\n\nDomain sub-structures (Finance → Billing/Invoices/Payments/AR/AP…; Account Success →\nAccounts/Health/Renewals/Escalations…; Sales → Leads/Pipeline/Contracts/Forecast…) are Spine\nschema content. **Never separate domain truth stores.**\n\n## 7–8. Spine Schema & Schema Synthesis\n\nSpine Schema models organizational reality — not provider APIs: Organization, Person, Team,\nRole, Responsibility, Authority, Domain, Goal, Objective, Work, Task, Assignment, Project,\nProcess, Workflow, Entity, Relationship, Event, Decision, Communication, Evidence, Policy,\nCapability, Agent, System, State, Outcome, Continuity.\n\nSynthesis pipeline:\n\n```text\nProvider Schema → Mechanical Ingestion → Normalized Raw Schema → Primitive/Field Extraction\n→ Semantic Synthesis → Canonical Entity Mapping → Canonical Relationships\n→ Spine Schema Registry → Spine\n```\n\nThe Schema Generator is NOT \"generate an API schema.\" It is:\n**translate heterogeneous system representations into the organization's canonical semantic model.**\n\n## 9–13. Entity · Relationship · Event · Decision · Evidence\n\n**Entities** have identity, attributes, relationships, state, history, provenance, permissions,\ndomain, source references. Examples: Organization, Person, Account, Contract, Opportunity,\nInvoice, Ticket, Work, Task, Workflow, Agent, Capability.\n\nKey relationships: Person→belongs_to→Team, Customer→owns→Account, Contract→generates→Invoice,\nWork→assigned_to→Person, Work→delegated_to→Agent, Decision→affects→Work.\n\n**Events** record changes or occurrences (business/user/work/communication/system/agent/\nworkflow/governance/approval/execution/reconciliation/memory). An event can produce context —\nan event does NOT automatically become canonical memory.\n\n**Decisions**: maker, context, alternatives, selected option, evidence, authority, timestamp,\nconsequences, work reference, result. Become org memory only via governance/promotion path.\n\n**Evidence**: source, references, content, provenance, timestamp, freshness, confidence,\nlineage, sensitivity. Evidence is not automatically truth — it supports truth claims or decisions.\n\n## 14–15. Memory Ontology & Memory Authority\n\nCanonical scopes: **Personal · Conversational · Agent · Organizational Staging · Organizational Published**.\nRuntime vocabulary — Session/User/Work/Entity/Organization memory — are scopes, not interchangeable storage systems.\n\nPromotion rule:\n\n```text\nEvent/Evidence → Context Assembly → Triage → Candidate → Staging → Governance\n→ Approve / Reject / Defer → Canonical Promotion → Organizational Memory → Index/Projection\n→ Human + Twin Context\n```\n\n> **Memory informs organizational truth; it does not silently become organizational truth.**\n\n## 16–18. Triage Ontology\n\nTriage is the cognitive intake and classification boundary. It performs intake, classification,\nentity linking, duplicate/conflict/ambiguity detection, sensitivity/materiality/freshness/\ncompleteness assessment, memory-scope classification, governance recommendation, staging.\n\nMay write: triage item, candidate, classification, entity links, provenance, confidence,\nconflict findings, memory scope, governance recommendation, review state, correlation ID,\ncausation ID.\n\nMay NEVER write: canonical entity state, approved organizational memory, authoritative policy,\npermissions, authority grants, canonical relationships, promoted outcomes.\n\nState machine — deliberately no `AUTO_APPROVE`:\n\n```text\nCandidate ── Repair / Reject / Defer\n     └── Pending Approval ── Reject (terminal) | Approve → Promote → Published\n```\n\n> **Triage classifies. Governance decides. The Pipeline promotes. Spine owns organizational\n> memory. Twin consumes the governed result.**\n\n## 19. Projection Ontology\n\nProjection translates shared Spine state into a user-specific view across dimensions:\norganization, domain, role, responsibility, authority, permissions, current work, context,\nrelevance, policy, industry, preferences.\n\n```text\nAuthenticated User → Gateway/TenantGate → Projection Contract\n→ Policy-filtered Spine Read Model → Versioned View Manifest → Workbench\n```\n\n## 20–23. Work · Work Graph · Assignment · Allocation\n\nWork spans users, domains, systems, and AI actors: objective, desired outcome, current state,\nowner, participants, assignments, tasks, decisions, communications, dependencies, constraints,\nevidence, actions, agent work, workflow state, approvals, exceptions, execution, results,\nreconciliation, continuity.\n\nWork Graph: Goal → Objective → Work → `{Tasks, Decisions, Communications, Approvals, Research,`\n`Actions, Exceptions, Dependencies, Agent Assignments, Workflows, Outcomes}`.\n\nAssignment targets: Human, Twin, Coworker, Domain Agent, Specialist Agent, Workflow, System,\nHuman+AI — each with assignee, role, authority, capability, scope, priority, deadline, status,\ndependency, evidence requirement, expected outcome.\n\nWork Allocation answers _\"who or what should perform what now?\"_ from capability,\nresponsibility, authority, risk, complexity, context, urgency, cost, availability, preference,\nhistorical performance, policy → Human / AI / Agent / System / Human+AI.\n\n## 24–27. Workbench · Regions · Surfaces · Self-Organizing Workspace\n\nGenerated from Business Context + Organizational Memory + Role + Responsibility + Domain +\nAuthority + Current Work + User Preferences + Twin State.\n\nRegions:\n\n| Region                | Contents                                                                                 |\n| --------------------- | ---------------------------------------------------------------------------------------- |\n| Orientation           | Home · Today · My Work · My Queue                                                        |\n| Personal              | Notes · Projects · Calendar · Activity                                                   |\n| Communication         | Email · Chat · Meetings · Calls · Documents                                              |\n| Organizational Memory | Decisions · Documents · Policies · Processes · Knowledge · Meeting Memory · Work History |\n| Work                  | Active · Waiting · Approval · Delegated · Blocked · Completed                            |\n| Domain Workspaces     | Sales · Finance · Customer Success · …                                                   |\n\nWork Surface modes: Grid, Board, Canvas, Timeline, Entity View, Workflow View, Dashboard, Feed,\nCalendar. A surface is a representation of Work and Business Context — not the entity itself.\n\nSelf-organizing ≠ an LLM randomly rearranging UI. The workspace is contextually projected from\nintent, role, responsibility, active work, capabilities, context, changes, governance.\n\nBoundary: **personal/reversible adaptation may be automatic; shared/consequential requires governance.**\nAllowed silently: view order, density, prefetch, cache, notification ranking, capability placement.\nNever silent: canonical schema, canonical truth, permissions, authority, governance thresholds,\ninstitutional memory, shared structures, workbench taxonomy.\n\n## 28–32. Twin · Twin Workspace · Coworker · Agents · Handoffs\n\nTwin lifecycle:\n\n```text\nReceive Intent → Access Context → Reason → Plan → Allocate → Delegate\n→ Invoke Capabilities → Monitor → Handle Exceptions → Communicate → Report → Maintain Continuity\n```\n\nTwin Workspace = AI operating surface (context, current work, tasks, plans, decisions,\ndelegation, agent assignments, tool calls, workflow runs, communications, evidence, results,\nartifacts, working memory) — not canonical organizational memory.\n\nCoworker = contextual companion at the human's active surface: observation, retrieval,\npreparation, communication support, workflow assistance, screen/surface context, Twin sync.\n\nAgent anatomy: identity, purpose, capability, context scope, authority scope, tenant scope,\npolicy, evidence requirements, work input/output, reconciliation. Types: Twin, Coworker,\nTriage, Domain, Specialist, Research, Workflow, External. Handoffs transfer **work context** —\nnever ownership of organizational memory. Handoff payload includes request ID, work ID,\ncapability, context reference, result, status, evidence, actions taken, errors, confidence,\ntimestamp, attribution, recommended next step. Twin validates before incorporating.\n\n## 33–34. Context Assembly & AI Boundary\n\nContext Assembly produces **minimum sufficient relevant context**:\n\n```text\nSpine → Context Assembly → Permission → Purpose → Freshness → Relevance filters\n→ Operational Context\n```\n\nNever dump the entire Spine into the model.\n\n```text\nCANONICAL SPINE ──(never direct)──► CONTEXT ASSEMBLY ──► filters ──► OPERATIONAL SANDBOX\n                                                                    ├─ Twin · Coworker\n                                                                    ├─ Domain Agents\n                                                                    └─ External Agents\n```\n\nBoth human and AI projection paths are governed. The Twin never queries canonical Spine directly.\n\n## 35–36. Capability & Execution\n\nCapability = businessly meaningful action (`retry_payment`, `approve_discount`,\n`send_customer_message`…) containing ID, description, inputs, outputs, required context,\nrequired authority, risk, evidence requirement, policy, available implementations.\n\nExecution mechanisms (API/MCP/Spine Tool/Workflow/Pipeline/ADK/Orchestrator/Provider SDK) are\ninvisible to the user:\n\n```text\nUser Intent → Capability → Governance → Execution Binding → Execution\n```\n\n## 37–40. Governance · Communication · Lifecycle · Reconciliation\n\nGovernance decides **whether an action may occur**; Intelligence decides **what might be a good\naction**.\n\nCommunication is part of Work and can create evidence, decisions, assignments, approvals,\ncommitments, work events.\n\nExecution lifecycle — provider success is not enough:\n\n```text\nIntent → Plan → Capability → Governance → Execution → Receipt → Verification\n→ Reconciliation → Outcome\n```\n\nReconciliation states: Confirmed · Failed · Unknown · Divergent · Partially Complete · Pending\nReconciliation.\n\n## 41–42. Operational vs Canonical · Storage Ownership\n\n> **Operational Spine is the state of the machine. Canonical Spine is the state of the business.**\n\nSpine Cache = default agent read surface — not truth, never a write target.\n\nStorage by ownership and authority (physical techs are implementation details):\n\n| Layer          | Contents                                                                                   |\n| -------------- | ------------------------------------------------------------------------------------------ |\n| CANONICAL      | entities · relationships · lineage · schema · work · governance · audit · published memory |\n| RAW / EVIDENCE | files · attachments · raw payloads · immutable evidence                                    |\n| DERIVED        | embeddings · search index · retrieval index                                                |\n| OPERATIONAL    | active context · idempotency · runtime state · projection snapshots · sync state           |\n| CACHE          | sessions · hot projections · connector state · invalidations                               |\n\n## 43–45. Documentation · Repository · Apps\n\nCanonical document hierarchy: Doctrine → Business Context/Spine Ontology → Org Memory → Spine\nSchema → Projection Contract → Work Graph/Allocation → Spine Workbench → Twin/AI Workspace →\nTriage → Agent Fabric → Capability Fabric → Execution Fabric → Governance → Connectivity →\nReconciliation → Platform Architecture → Implementation Reality → ADRs → Runbooks → API Contracts.\n\nApps are surfaces; services/packages/infrastructure implement the ontology. Target service\ntaxonomy: spine, context, projections, work, twin, triage, coworker, agents, governance,\nreconciliation, orchestration. App mapping: web → User Workbench + Twin Workspace; mobile →\nMobile Workbench; portfolio → Executive Projection; one-access(+console) → Identity;\nplatform → Customer Platform Admin; platform-console → IW Platform Operations.\n\n## 46–48. Views · Interaction Model · User–Twin Lifecycle\n\nThree views: **User** (\"what do I need to know and do?\" → Workbench + Twin) · **Operator**\n(\"how is the work being executed?\" → Platform Console) · **System** (\"how is infrastructure\nfunctioning?\"). Users never need the system view.\n\nInteraction model (operational semantics, expressible via clicks/chat/NL/Slack/email/approval\nsurfaces):\n\n```text\nSTORE → ASK → DECIDE → APPROVE/REJECT/MODIFY/CONSULT → EXECUTE → VERIFY → RECONCILE → CONTINUE\n```\n\nCanonical User–Twin Lifecycle:\n\n```text\nUSER → WORKBENCH → INTERACTION → COWORKER CONTEXT GATHERING → TWIN OBSERVE\n→ SPINE CONTEXT ASSEMBLY → TWIN ORIENT → CONTEXT PROJECTION → USER REVIEW → USER DECISION\n→ TWIN RE-ORIENT → WORK ALLOCATION → AGENT/WORKFLOW/CAPABILITY → GOVERNANCE → EXECUTION\n→ SOURCE SYSTEM → RECEIPT → RECONCILIATION → SPINE CONTINUITY → TWIN → USER\n```\n\n## 49–50. Learning & Auto-Tuning\n\nLearning: Observation → Pattern → Learning → Adaptation → Suggestion → Governance → Action.\nThe Twin may learn preferences, communication styles, escalation paths, successful workflows,\nagent performance, recurring patterns. Learning NEVER overrides permissions, authority, policy,\ngovernance, canonical truth.\n\nAuto-tuning boundary:\n\n> **Personal and reversible may adapt; shared and consequential requires approval.**\n\n## 51–52. Relationship Graph & Product Loop\n\nORGANIZATION → owns goals, defines objectives/people/roles/policies → WORK GRAPH realizes\nobjectives, connects entities, assigns humans/Twin/agents, generates decisions/communications,\nrequires approvals, invokes capabilities, produces evidence, reaches OUTCOME → RECONCILIATION\n→ SPINE → CONTINUITY/MEMORY.\n\nComplete product loop:\n\n```text\nBUSINESS PURPOSE → NEED → GOAL/OBJECTIVE → WORK → BUSINESS CONTEXT → SPINE FABRIC\n→ CONTEXT ASSEMBLY → PROJECTION → WORKBENCH ↕ TWIN → ALLOCATION → HUMAN/AI/HUMAN+AI\n→ GOVERNANCE → CAPABILITY → EXECUTION → SOURCE SYSTEM → ACTUAL STATE → RECONCILIATION\n→ OUTCOME → ORGANIZATIONAL MEMORY → LEARNING → NEXT WORK\n```\n\n## 53. The Architecture in One Sentence\n\n> IntegrateWise builds SpineWorkspace, a human–AI work coordination platform centered on Spine\n> Fabric—the contextual business memory and operational continuity layer through which fragmented\n> organizational reality is normalized, assembled into relevant Business Context, projected by\n> role and responsibility into the Spine Workbench, consumed by a user's bounded Twin through an\n> operational sandbox, coordinated across Coworker, Triage, agents, capabilities and workflows,\n> governed before consequential action, executed across connected systems, reconciled against\n> actual state, and returned to organizational continuity as the basis for the next piece of work.\n\n## 54. The Deepest Ontological Question\n\nFor this organizational need, objective, work, user, role, domain, context, and moment: what\nshould the human do, what should the Twin do, what should they do together, what should be\ndelegated, what is authorized, what is missing, what needs to happen next — and how do we know\nthe business outcome actually occurred?\n\nFoundational law:\n\n> **Business Context is the center. Spine Fabric preserves and serves that context. Human and AI\n> operate on governed projections of it. Work is shared. Authority is governed. Execution is\n> reconciled. Continuity is preserved.**\n"}