Unclassified

Projection Constitution

Status: SUPERSEDED / ABSORBED — historical subsystem constitution. Current authority: INTEGRATEWISE_ARCHITECTURE.md v2.2.
Scope: Projection engine behavior, composition, layout, caching, refresh, and fallback rules.
Canonical Owner: IntegrateWise Platform
Last Verified: 2026-07-20

1. Purpose

This document defines how the Adaptive Workbench renders projections.

The UI never consumes raw API responses. The UI consumes stable projections only.

2. Contract

interface ProjectionContract {
  input: {
    role: Role;
    department: Department;
    industry: Industry;
    connectors: ConnectorId[];
    capabilities: CapabilityId[];
    schemaVersion: string;
  };
  composition: {
    select: (schema, persona) => Field[];
    filter: (fields, permissions) => Field[];
    enrich: (fields, context) => EnrichedField[];
  };
  projection: {
    map: (fields) => UIComponent[];
    layout: (components) => LayoutGrid;
    actions: (capabilities) => ActionButton[];
  };
  render: {
    tree: (layout) => RenderTree;
    cache: (tree) => CacheKey;
    invalidate: (event) => boolean;
  };
  output: { json: RenderTree; fingerprint: string; ttl: number };
}

3. Composition Rules

  1. Projection selects fields based on role, department, industry, and active capabilities.
  2. Projection filters fields based on permissions and row-level tenant isolation.
  3. Projection enriches fields with active context and memory.
  4. Projection maps fields to explicit UI component declarations.
  5. Projection layout is computed, not hardcoded.

4. Render Rules

  1. Render tree is computed from layout at runtime.
  2. Render output is cached by fingerprint.
  3. Cache invalidation is triggered by domain events.
  4. Cached projections fail open with realistic data.

5. Fallback Rules (corrected by Amendment 13)

A stale projection must never silently masquerade as current state.

  1. Fresh projection succeeds → freshness = CURRENT. Normal rendering.
  2. Fresh projection fails but policy permits stale read → return cached
    projection with freshness = STALE, stale_since, stale_reason.
    Disable unsafe actions that depend on current state as required.
  3. No permitted cached projection → explicit projection failure. The
    Workbench must display the failure state, not silently substitute seed data
    or fabricate a synthetic record.
  4. When connectors are unavailable, show last known good projection with
    explicit connector state and freshness indicators visible to the user.

6. Invariants

  1. The UI never binds directly to provider APIs.
  2. The UI never renders raw provider field names.
  3. Projection fingerprint incorporates schema version.
  4. Projections are immutable per cache key.