# Shared Workbench Platform and Composition

`@oshun/workbench-kit` is the shared grammar for domain workbenches. It exists
to make high-risk behavior—identity, authorization, history, jobs, evidence,
recovery, and accessible composition—consistent without erasing domain ownership
or forcing every product into the same screen.

```mermaid
classDiagram
  class WorkbenchShell {
    workspaceContext
    navigation
    primaryWorkspace
    inspector
    activityAndStatus
  }
  class RequestContext {
    tenant
    actor
    grants
    correlation
  }
  class DomainAdapter {
    queries
    commands
    projections
    effects
  }
  class RevisionHistory {
    revision
    ancestry
    author
    reason
  }
  class JobRuntime {
    lease
    fence
    progress
    result
  }
  class EvidenceEnvelope {
    source
    provenance
    disclosure
    audit
  }
  WorkbenchShell --> RequestContext : carries
  WorkbenchShell --> DomainAdapter : composes
  DomainAdapter --> RevisionHistory : records
  DomainAdapter --> JobRuntime : may schedule
  DomainAdapter --> EvidenceEnvelope : returns
  JobRuntime --> EvidenceEnvelope : completes with
```

The kit defines these roles and invariants; domain adapters supply the concrete
business language and remain the only layer allowed to own domain effects.

## Ownership and dependency direction

The shared package lives at `libs/oshun/workbench-kit`. Its public exports are
owned and reviewed as platform contracts. Domain libraries and applications may
import it; it must not import domain implementations. Cross-domain business
composition belongs in an application/orchestration layer or a versioned
adapter, not in the kit.

The formal choice and package graph are in
[ADR-S1](../../../docs/adr/ADR-S1-workbench-kit-package-ownership.md). The
package's authoritative public API, runtime classes, reference map, and targets
are in the [Workbench Kit README](../../../libs/oshun/workbench-kit/README.md).

## Shell composition

A workbench shell composes domain-owned content into stable regions:

- global/product navigation and workspace/project identity;
- primary work area and responsive layout;
- contextual inspector/evidence pane;
- selection, command, history, and review surfaces;
- jobs/activity/notification feedback;
- help, disclosure, connectivity, degradation, and recovery state.

The kit defines composition primitives and semantics; a domain defines which
regions are present and what they mean. A newsroom, DAW, timeline, node graph,
course author, and DCC control room should feel related without sharing an
inappropriate layout.

## Tokens, themes, and isolation

The UI composition contract uses semantic token roles rather than domain code
reaching into global CSS. Categories cover color, typography, spacing, shape,
elevation, motion, focus, density, and data visualization. Domain themes inject
values inside their boundary; they may not change the meaning of danger,
disabled, selected, focus, evidence, or status roles.

Archetypes reconcile reusable compositions—editor, timeline, graph/canvas,
dashboard/control room, catalog/library, and review—without cloning whole
applications. The governing token and accessibility matrix is
[ADR-S4](../../../docs/adr/ADR-S4-ui-composition-and-theming.md).

## Identity, tenant, and grants

The trusted edge resolves actor, tenant, memberships/roles, session strength,
feature/release scope, and request/correlation identity. Client context is a
hint, never authorization. Domain queries and commands receive typed context and
re-check resource scope.

Step-up and confirmation are different controls:

- **Step-up** proves or refreshes the actor/session for a sensitive class.
- **Confirmation** displays the exact proposed mutation, scope, consequences,
  and preconditions before execution.
- **Authorization** decides whether that authenticated actor can perform it.
- **Domain invariants** decide whether it is valid now.

Passing one never implies the others.

## Commands, queries, and effects

Queries are permission-filtered, versioned projections. Commands name a domain
intent and include target identity/version, idempotency key, actor/tenant
context, and declared preconditions. The domain validates and performs its own
effect; the UI never converts a visual success state into an assumed write.

Useful command outcomes distinguish:

- accepted/completed with durable result identity;
- accepted/queued with job identity;
- conflict or stale precondition with current version;
- forbidden or step-up/confirmation required;
- invalid with field/domain reasons;
- unavailable/degraded/retryable;
- rejected by policy, rights, review, budget, or capacity.

## Revisions, history, and undo

History is an immutable, attributable sequence. A revision records entity,
tenant/workbench, version, parent/merge ancestry, author, command/reason,
timestamp, schema/tool versions, and changed data or snapshot reference.

Undo is modeled as a new revision or compensating command. It must not delete
the event that caused the current state. Concurrent edits expose conflict and a
resolution path; last-write-wins is only valid where a domain explicitly
declares it harmless.

## Jobs and long-running work

Jobs provide a shared state vocabulary while domains own payloads and effects. A
job includes:

- tenant/workbench/domain, requester, command, input and policy versions;
- queued/leased/running/succeeded/failed/cancelled/withheld state;
- progress phase and honest indeterminate progress where totals are unknown;
- lease owner, fencing token, heartbeat, retry count/class, and idempotency;
- logs/evidence with redaction, outputs with lineage, and cleanup state;
- cancellation/compensation semantics and operator escalation.

A worker that loses its lease cannot publish. A retry cannot duplicate an
external effect. Cancellation never claims to reverse an irreversible provider
action.

## Suggestions, assistants, and review

Suggestions are attributable candidate changes. They carry source context,
generator/model/tool version, evidence, confidence/status, affected resource and
version, and expiry. Accept/reject/dismiss is audited. Acceptance invokes a real
domain command and can still fail authorization, conflict, policy, review,
budget, or rights checks.

Eve can propose and, on builder surfaces, execute only through the governed
confirmation or work-item lease boundary. The mere presence of a tool
description or workbench adapter is not permission. See
[Eve runtime and actions](../eve/runtime-tools-and-actions.md).

## Evidence, provenance, and audit

The platform normalizes the envelope around domain evidence without pretending
all evidence is the same. Records preserve actor/producer, tenant/resource,
source/input, method/model/tool version, time, status, uncertainty, review,
lineage, and policy/rights references.

Audit events are append-only control evidence, not an analytics stream. They
exclude unnecessary content and secrets, carry stable event and correlation
identity, and declare retention and access. Provenance remains attached through
suggestion, acceptance, transformation, export, correction, and deletion.

## Storage, outbox, and projections

Domains own systems of record. Shared storage helpers provide conventions for
transactions, tenant isolation, blobs, outbox/inbox, idempotency, history,
leases, retention, deletion, and restore—but cannot choose a domain's record
shape or lifecycle.

An outbox makes a committed domain change and its event atomic. Consumers use
inbox/idempotency and version checks. Read projections declare rebuild sources,
cutover/version, staleness, and failure behavior. UI fallbacks identify stale or
partial data instead of displaying a projection as current.

## Degradation and recovery

The kit registers dependency/capability paths and their degradation plans. Each
path says which dependency failed, which user operations remain safe, which are
blocked or read-only, what evidence is shown, how recovery is detected, and
whether queued work can resume.

Recovery objectives and reference edges cover relational, blob, index/graph,
queue/outbox, audit/signing, and external-provider state. Restore validation
checks cross-store meaning and reachability rather than only individual store
health.

## Accessibility contract

Shared primitives carry semantics, keyboard behavior, focus management,
labels/descriptions, status and error announcements, reduced motion, zoom and
reflow, contrast, touch target, and high-density data affordances. A domain may
extend them, but it owns accessibility tests for the resulting composition.

Canvas, graph, timeline, waveform, spatial, and drag interactions require a
structured, keyboard-operable alternative. Virtualization cannot remove the
focused or screen-reader-active item without a managed transition.

## Extension checklist

Before adding a shared primitive or service:

1. Show that at least two domain workbenches need the same semantics, not only
   similar pixels.
2. Define ownership and dependency direction.
3. Specify success, refusal, conflict, partial, offline, retry, cancellation,
   and recovery states.
4. Define tenant/authorization, evidence/audit, privacy/rights, accessibility,
   and observability behavior.
5. Add contract and consumer tests; verify the packed public API and alias
   resolution where applicable.
6. Update ADR/reference documentation and the generated inventories.

## Canonical evidence

- [Workbench Kit README](../../../libs/oshun/workbench-kit/README.md)
- [Package ownership ADR](../../../docs/adr/ADR-S1-workbench-kit-package-ownership.md)
- [UI composition ADR](../../../docs/adr/ADR-S4-ui-composition-and-theming.md)
- `evidence/v1-workbenches/workbench-kit-registry-fixtures.json`
- `evidence/v1-workbenches/gate-registry.json`
- `evidence/v1-workbenches/inventory/library-public-symbols.json`
- `evidence/v1-workbenches/inventory/library-graph.json`