07 — Work Surface Interaction Model

Status: Active frontend handoff derived from frozen architecture
Authority: ARCHITECTURE_LOCK.md, FOUR_BUTTONS.md,
FRONTEND_PLATFORM_API_AND_DISCOVERY_SPEC.md

Purpose

The Workbench is one editable work surface over tenant entities and RBAC
projections. Tables, pages, records, queues and canvases are view modes over the
same typed contracts; they are not separate domain databases.

Interaction contract

Every material click resolves:

tenant + user + role + projection + active entity + requested operation
→ Gateway
→ authorization and projection resolution
→ Active Context Bundle
→ response with data, provenance, freshness, permissions and available capabilities

The frontend knows only Entity, Projection, Capability, Signal,
Context, and Twin. It does not infer internal services or storage.

Read and CRUD behavior

• Reads use projection and entity endpoints through the one typed Gateway
  client.
• Create, update, link, unlink and archive operations send explicit intent,
  idempotency key, expected version and changed fields.
• Optimistic UI is allowed only when the response contract supports conflict
  recovery.
• Canonical writes are never performed by the browser. The Platform decides
  whether an edit remains operational, enters promotion review or is committed
  by a Governed Spine Writer.
• Every mutation result exposes accepted, pending_approval, completed,
  conflict, or failed; the UI must not invent success.

Four Buttons

OODA	Control	UI result
Observe	Store in Spine	Submit a truth-capture intent; show promotion/governance state
Orient	Ask your Twin	Request bounded contextual reasoning for the active work
Decide	Assign your Twin	Create a proposed objective; do not execute it
Act	Approve Twin's Action	Send explicit approval for the exact proposal/version

Twin never opens automatically as a permanent panel. A material signal may
surface a compact inline card; expensive reasoning starts only after a valid
trigger or explicit control.

Canvas rules

Canvas nodes reference entity or projection IDs. Free-form blocks remain
working context until a user explicitly stores/promotes them. Moving or
formatting a block changes presentation state; changing an entity field uses the
same governed mutation contract as a table edit.

Failure and trust states

Every surface supports loading, empty, partial, stale, unauthorized, conflict,
approval-required and retryable-failure states. Evidence and freshness remain
visible wherever the UI presents an AI-derived claim.