{"slug":"architecture/PROJECTION_CONTRACT","title":"Projection Contract","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/PROJECTION_CONTRACT.mdx","bytes":4295,"description":"How Spine Fabric is projected into user-facing and AI-facing surfaces — the sole composition layer and its rules.","updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\nProjection is how Spine Fabric becomes visible to humans and AI. The Projection Engine is the **sole composition layer** that produces projected surfaces. No other component constructs workbench views.\n\n## Core Principle\n\n```text\nCANONICAL SPINE\n      ↓\nPROJECTION ENGINE (sole composition layer)\n      ↓\nSHARED WORKBENCH (sole composed output)\n      ↓\nUSER WORKBENCH + TWIN WORKBENCH\n```\n\nThe Projection Engine reads from Spine Fabric, applies governance, and produces a `SharedWorkbench` shape. Every downstream consumer — web app, mobile, Twin runtime, capability fabric — imports this contract.\n\n## Projection Engine\n\nThe Projection Engine is the sole component that produces a `SharedWorkbench`. No other package, service, or route handler may construct this shape.\n\nThe gateway (BFF) delegates all composition to `ProjectionEngine.compose()`. It handles auth, routing, and response formatting — but never assembles entities, relationships, or capabilities directly.\n\n**Rules:**\n- Single source of truth for workbench composition\n- Consistent output shape across all consumers\n- Versioned contract with breaking-change policy\n- No consumer may define its own workbench shape\n\n## SharedWorkbench\n\n`SharedWorkbench` (defined in `contracts/shared-workbench/v1.ts`) is the sole output type of the Projection Engine. Every downstream consumer imports this contract.\n\n**Contains:**\n- Active work surface (tasks, work items, approvals)\n- Entity context (focused entity, relationships, timeline)\n- Twin state (passive observation, active proposals)\n- Governance state (action availability, approval requirements)\n- Capability state (available actions, execution status)\n- Memory context (relevant organizational memory)\n- Connectivity state (sync health, connector status)\n\n**Rules:**\n- Type-safe contracts across the entire stack\n- Optional fields for consumer-specific extensions\n- Versioned contract with changelog\n\n## Governance at Two Gates\n\nGovernance applies at **two gates**:\n\n### 1. Composition Gate\n\nProjection Engine evaluates governance for each capability when composing SharedWorkbench. The `governance` field tells the frontend which actions are allowed, which need approval, and which are denied.\n\n### 2. Execution Gate\n\nCapability Fabric re-evaluates governance before executing any action. This prevents TOCTOU (time-of-check-time-of-use) issues where policy changes between composition and execution.\n\n```text\nComposition gate: cached policy (fast, <30s TTL)\nExecution gate: fresh policy (authoritative)\n```\n\n**Result:** Users see accurate action availability. No surprise denials at execution time.\n\n## Projection Path\n\nFrom the canonical ontology, the projection path is:\n\n```text\nCANONICAL SPINE\n      ↓\nCONTEXT ASSEMBLY\n      ↓\nPERMISSION / PURPOSE / RELEVANCE / FRESHNESS\n      ↓\nAI OPERATIONAL SANDBOX\n      ↓\nTWIN / AGENTS\n```\n\n**Rules:**\n- Canonical Spine is never directly exposed to AI\n- Context assembly is bounded by permission, purpose, relevance, freshness\n- AI operates only within the operational sandbox\n- Twin consumes projected context, not raw Spine\n\n## Workbench Regions\n\nThe Workbench surface is projected as regions:\n\n| Region | Purpose | Content |\n|--------|---------|---------|\n| **Today** | Immediate priorities | Items due, urgent signals, active work |\n| **Communications** | Channel coordination | Threads, messages, emails, meetings |\n| **Organizational Memory** | Knowledge workspace | Notion-like org knowledge, decisions, playbooks |\n| **Work** | Domain-specific work surfaces | Departmental modules, tasks, approvals |\n\nEach region is a projection of shared Business Context. The Workbench is not a second database, a static dashboard, or a departmental copy of truth.\n\n## Related\n\n- [Spine Schema](/architecture/SPINE_SCHEMA) — what is being projected\n- [Workbench Canonical Model](/architecture/WORKBENCH_CANONICAL_MODEL) — the projected surface\n- [Twin](/architecture/TWIN) — the AI workspace that consumes projections\n- [Governance](/architecture/GOVERNANCE) — the policy applied at projection and execution\n"}