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 inevidence/v1-workbenches/(regenerated bypnpm 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):
- Does a new
@oshun/workbench-kitpackage get created, or is neutral behavior folded into the existing@oshun/studio-authoring, or is everything retained in Tara for now? - Who owns domain-neutral contracts, UI shell/primitives, server boundaries, persistence helpers, testing utilities, and domain plugins?
- 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-authoringand@oshun/contractsas lower layers. No cycle exists in either direction (tara-studio-authoring-overlap.json). @oshun/studio-authoringhas 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/bffproject. 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 inevidence/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.jsonconfigures 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-kitexport 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.mjsbuilds its report from Tara's import graph only, andSHARED_KIT_PACKAGESis 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§S0evidence/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, andREADME.md