Disciplines · Decisions (ADRs)

ADR-S1: Workbench-Kit Package Ownership and Dependency Direction

Phase S proposes a shared @oshun/workbench-kit for genuinely domain-neutral authoring/operations behavior, extracted from Tara (the quality exemplar).

Accepted in direction · 2026-07-24
6sections7 minread

On this page

Status: Accepted in direction: Elikem ratified Option 4 on 2026-10-01 (S0.6.f). This revision records that; it takes effect when he approves it in Eve. Date: 2026-07-24 Authors: V1 Domain Workbenches extraction audit (Phase S) Reviewers: pending — Oshun Studio Architecture + affected package owners (Tara, studio-authoring, contracts, persistence)

This ADR records the context, current graph, and considered options for the shared workbench-kit ownership question (V1_DOMAIN_WORKBENCHES_TODOS_2026-07-23.md §S0.6). An agent drafted the ownership assignment (S0.6.c), the dependency rules (S0.6.d) and the boundary validation (S0.6.e) for Option 4. Elikem ratified that direction on 2026-10-01, which is the S0.6.f decision; it takes effect with his approval of this revision in Eve. Every quantitative claim below is drawn from the deterministic evidence in evidence/v1-workbenches/ (regenerated by pnpm inventory:v1-workbenches).

Context and Problem Statement#

Phase S proposes a shared @oshun/workbench-kit for genuinely domain-neutral authoring/operations behavior, extracted from Tara (the quality exemplar). Before any code moves, we must decide which package owns what and which way dependencies point, without duplicating existing packages or creating cycles.

Decision questions (S0.6.a):

  1. Does a new @oshun/workbench-kit package get created, or is neutral behavior folded into the existing @oshun/studio-authoring, or is everything retained in Tara for now?
  2. Who owns domain-neutral contracts, UI shell/primitives, server boundaries, persistence helpers, testing utilities, and domain plugins?
  3. What dependency directions are allowed among applications, the shared kit, @oshun/studio-authoring, domain libraries, @oshun/contracts, the BFF, and adapters — and which are forbidden?

Current package and consumer graph (S0.6.a snapshot)#

Evidence: tara-import-graph.json, tara-component-inventory.json, tara-bff-matrix.json, tara-studio-authoring-overlap.json, tara-contract-inventory.json, deletion-threshold.json.

Package Role Surface Consumers (production)
@oshun/tara-workbench domain logic (pure, deterministic) 209 exports (151 unused, 44+ enum/value types) 1 project — @oshun/bff only
Tara studio web 28 StudioTaraWorkbench* components + shared ShellLayout role-tagged, route-linked; 25/28 lack a co-located test Next.js app routes; reach Tara via the BFF over HTTP (no direct lib import)
Tara BFF 70 routes (/v1/studio/tara-workbench/*) all guarded + fail-closed; durable store; configured-or-fail-closed model provider the studio web surface
@oshun/studio-authoring domain-neutral logic only 315 exports across 9 categories; 0 UI components / hooks / stores consumed by Tara and other domains; does not import Tara (acyclic)
@oshun/contracts/tara shared Zod contracts 98 schemas → 22 persistence objectContract rows (0 source-less) the lower layer; the Tara domain lib consumes it

Key structural facts the decision must respect:

  • Dependency direction is already settled and acyclic: @oshun/contracts ← @oshun/tara-workbench → @oshun/studio-authoring, with @oshun/studio-authoring and @oshun/contracts as lower layers. No cycle exists in either direction (tara-studio-authoring-overlap.json).
  • @oshun/studio-authoring has no UI: it is a pure logic library (components/hooks/stores = 0). Tara's 28 UI components therefore cannot be folded into it without introducing a new UI layer there.
  • No name collisions: 0 duplicate exported contract names between studio-authoring (315) and tara-workbench (209).
  • Reuse is not yet proven: 0/209 Tara exports meet the ≥2-real-consumer deletion threshold (S0.11) — every production consumer is the single @oshun/bff project. Extracting Tara exports as-is would violate S0.11.

Considered Options (S0.6.b trade-off table)#

Option What it means Pros Cons / evidence
1. Retain current (no shared kit) Tara keeps all logic + UI; other domains build their own zero migration risk; respects S0.11 (no premature abstraction) no reuse; each new domain re-implements the shell; defers the stated Phase-S goal
2. Extend @oshun/studio-authoring move neutral logic into studio-authoring; add a UI sub-package for the shell reuses an existing, already-consumed, acyclic lower layer for logic; no new logic package studio-authoring is logic-only — the 28 UI components have nowhere to live without a new UI layer; risks overloading a currently-clean logic boundary
3. Create @oshun/workbench-kit new shared package for neutral shell UI + server/persistence/testing helpers a clean home for neutral UI + server seams; explicit extension model (S0.7) premature by S0.11: 0/209 exports have a proven 2nd consumer today; risks a one-consumer "shared" package that is just relocated Tara code
4. Hybrid (staged) neutral logic → studio-authoring; neutral UI shell/primitives → a new workbench-kit only once a 2nd domain consumer exists; Tara retains all meditation semantics matches the real structure (logic layer already exists + is consumed; UI has no home); enforces S0.11 by gating extraction on a real 2nd consumer most coordination; requires the deletion-threshold gate wired in CI (done, S0.11.f) and a per-slice migration plan (S0.10)

Decision Outcome#

Adopted: Option 4 (staged, threshold-gated hybrid), ratified by Elikem on 2026-10-01. The evidence decisively favors it over an immediate greenfield @oshun/workbench-kit (Option 3): S0.11 shows no Tara export yet clears the ≥2-consumer bar, and @oshun/studio-authoring cannot host UI (S0.4). Under the sustained direction to work the ledger through, this ADR now records the direction as adopted and derives the artifacts that follow from it:

  • S0.6.c — responsibility map. Concerns are assigned by layer: domain-neutral contracts → @oshun/contracts; domain-neutral authoring logic → @oshun/studio-authoring; domain-neutral UI shell + primitives and neutral server/persistence/testing helpers → @oshun/workbench-kit (created only when a 2nd real consumer exists, S0.11); domain vocabulary/stages/gates and domain plugins → the domain packages; transport/durability → the BFF; composition → the apps. Full map in evidence/v1-workbenches/workbench-kit-boundary.json.
  • S0.6.d — normative dependency rules. Six layers, lowest→highest: contracts < shared-logic < workbench-kit < domain < bff < app. Dependencies may point only downward; upward and same-layer edges are forbidden (15 allowed / 21 forbidden edges). Rule coverage is partial. workbench-kit-dependency-constraints.json configures 22 of the 36 edges as Nx-tag rules (5 of them kit edges); its count of 3,504 projects is a tag census, and its zero violations mean no contradiction within the configuration. 11 edges cannot be configured yet because no project carries those layers' tags, and 3 existing same-layer edges are recorded as divergences. Whether actual imports obey the configured rules is unverified: lint applies them, but no exact-commit lint run covering these projects is cited here. Remaining work: tag the missing layers, resolve the 3 divergences, and record a lint run over the tagged projects.
  • S0.6.e — boundary proof. A cycle simulation over the proposed layered graph is acyclic, cross-checked against the current observed graph proven acyclic in S0.4 (tara → studio-authoring → contracts). The proof passes; a deliberately-inserted upward edge is caught as a cycle (regression test). It checks the modelled layer graph only; it does not show that actual imports obey the rules.

S0.6.f: Elikem ratified the direction on 2026-10-01. The decision of record is his approval of this revision in Eve. Option 4's second stage has begun: @oshun/workbench-kit exists (libs/oshun/workbench-kit) and three apps use it (the BFF, web and the Eve content app). Lint (enforce-module-boundaries in eslint.config.js) is configured with the 22 covered edges; nothing yet guards the other 14. The ratification is recorded as a journal note on task v1-domain-workbenches:S0.6.f (board snapshot).

Consequences#

  • Whatever direction is chosen must preserve the existing acyclic layering (contracts ← tara-workbench → studio-authoring) and add no cycle.
  • Any @oshun/workbench-kit export must satisfy the S0.11 deletion threshold (≥2 real consumers) or carry a recorded, time-boxed exception. This is not enforced yet. scripts/v1-workbenches/deletion-threshold-gate.mjs builds its report from Tara's import graph only, and SHARED_KIT_PACKAGES is still empty although the kit now exists. Adding the kit's name there would filter the Tara report, not scan the kit's exports, and the script has no exception handling. Required gate work: scan the kit's actual exports and their consumers, honour recorded unexpired exceptions, and verify against the kit before relying on the gate.
  • Tara's large unused surface (151/209 exports) should be pruned or retained in the domain, not lifted into a shared package, per S0.11.

References#

  • V1_DOMAIN_WORKBENCHES_TODOS_2026-07-23.md §S0
  • evidence/v1-workbenches/ — tara-import-graph.json, tara-component-inventory.json, tara-bff-matrix.json, tara-studio-authoring-overlap.json, tara-contract-inventory.json, deletion-threshold.json, and README.md