{"slug":"developers/07_WORK_SURFACE_INTERACTION_MODEL","title":"07 — Work Surface Interaction Model","section":"developers","sectionLabel":"Developers","status":"current","type":"document","path":"developers/07_WORK_SURFACE_INTERACTION_MODEL.mdx","bytes":2893,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** Active frontend handoff derived from frozen architecture  \n**Authority:** `ARCHITECTURE_LOCK.md`, `FOUR_BUTTONS.md`,\n`FRONTEND_PLATFORM_API_AND_DISCOVERY_SPEC.md`\n\n## Purpose\n\nThe Workbench is one editable work surface over tenant entities and RBAC\nprojections. Tables, pages, records, queues and canvases are view modes over the\nsame typed contracts; they are not separate domain databases.\n\n## Interaction contract\n\nEvery material click resolves:\n\n```text\ntenant + user + role + projection + active entity + requested operation\n→ Gateway\n→ authorization and projection resolution\n→ Active Context Bundle\n→ response with data, provenance, freshness, permissions and available capabilities\n```\n\nThe frontend knows only `Entity`, `Projection`, `Capability`, `Signal`,\n`Context`, and `Twin`. It does not infer internal services or storage.\n\n## Read and CRUD behavior\n\n- Reads use projection and entity endpoints through the one typed Gateway\n  client.\n- Create, update, link, unlink and archive operations send explicit intent,\n  idempotency key, expected version and changed fields.\n- Optimistic UI is allowed only when the response contract supports conflict\n  recovery.\n- Canonical writes are never performed by the browser. The Platform decides\n  whether an edit remains operational, enters promotion review or is committed\n  by a Governed Spine Writer.\n- Every mutation result exposes `accepted`, `pending_approval`, `completed`,\n  `conflict`, or `failed`; the UI must not invent success.\n\n## Four Buttons\n\n| OODA    | Control               | UI result                                                      |\n| ------- | --------------------- | -------------------------------------------------------------- |\n| Observe | Store in Spine        | Submit a truth-capture intent; show promotion/governance state |\n| Orient  | Ask your Twin         | Request bounded contextual reasoning for the active work       |\n| Decide  | Assign your Twin      | Create a proposed objective; do not execute it                 |\n| Act     | Approve Twin's Action | Send explicit approval for the exact proposal/version          |\n\nTwin never opens automatically as a permanent panel. A material signal may\nsurface a compact inline card; expensive reasoning starts only after a valid\ntrigger or explicit control.\n\n## Canvas rules\n\nCanvas nodes reference entity or projection IDs. Free-form blocks remain\nworking context until a user explicitly stores/promotes them. Moving or\nformatting a block changes presentation state; changing an entity field uses the\nsame governed mutation contract as a table edit.\n\n## Failure and trust states\n\nEvery surface supports loading, empty, partial, stale, unauthorized, conflict,\napproval-required and retryable-failure states. Evidence and freshness remain\nvisible wherever the UI presents an AI-derived claim.\n"}