Oshun Platform · Guides & deep dives

Shared Workbench Platform and Composition

The shared package lives at libs/oshun/workbench-kit.

14sections6 minread
Markdown source
On this page

@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.

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. The package's authoritative public API, runtime classes, reference map, and targets are in the Workbench Kit README.

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.

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.

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#