{"slug":"architecture/PROJECTION_CONSTITUTION","title":"Projection Constitution","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/PROJECTION_CONSTITUTION.mdx","bytes":2842,"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: Projection engine behavior, composition, layout, caching, refresh, and fallback rules.\nCanonical Owner: IntegrateWise Platform\nLast Verified: 2026-07-20\n\n---\n\n## 1. Purpose\n\nThis document defines how the Adaptive Workbench renders projections.\n\nThe UI never consumes raw API responses. The UI consumes stable projections only.\n\n---\n\n## 2. Contract\n\n```typescript\ninterface ProjectionContract {\n  input: {\n    role: Role;\n    department: Department;\n    industry: Industry;\n    connectors: ConnectorId[];\n    capabilities: CapabilityId[];\n    schemaVersion: string;\n  };\n  composition: {\n    select: (schema, persona) => Field[];\n    filter: (fields, permissions) => Field[];\n    enrich: (fields, context) => EnrichedField[];\n  };\n  projection: {\n    map: (fields) => UIComponent[];\n    layout: (components) => LayoutGrid;\n    actions: (capabilities) => ActionButton[];\n  };\n  render: {\n    tree: (layout) => RenderTree;\n    cache: (tree) => CacheKey;\n    invalidate: (event) => boolean;\n  };\n  output: { json: RenderTree; fingerprint: string; ttl: number };\n}\n```\n\n---\n\n## 3. Composition Rules\n\n1. Projection selects fields based on role, department, industry, and active capabilities.\n2. Projection filters fields based on permissions and row-level tenant isolation.\n3. Projection enriches fields with active context and memory.\n4. Projection maps fields to explicit UI component declarations.\n5. Projection layout is computed, not hardcoded.\n\n---\n\n## 4. Render Rules\n\n1. Render tree is computed from layout at runtime.\n2. Render output is cached by fingerprint.\n3. Cache invalidation is triggered by domain events.\n4. Cached projections fail open with realistic data.\n\n---\n\n## 5. Fallback Rules (corrected by Amendment 13)\n\nA stale projection must never silently masquerade as current state.\n\n1. **Fresh projection succeeds** → `freshness = CURRENT`. Normal rendering.\n2. **Fresh projection fails but policy permits stale read** → return cached\n   projection with `freshness = STALE`, `stale_since`, `stale_reason`.\n   Disable unsafe actions that depend on current state as required.\n3. **No permitted cached projection** → explicit projection failure. The\n   Workbench must display the failure state, not silently substitute seed data\n   or fabricate a synthetic record.\n4. When connectors are unavailable, show last known good projection with\n   explicit connector state and freshness indicators visible to the user.\n\n---\n\n## 6. Invariants\n\n1. The UI never binds directly to provider APIs.\n2. The UI never renders raw provider field names.\n3. Projection fingerprint incorporates schema version.\n4. Projections are immutable per cache key.\n"}