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

**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](/api/content/media/624e4b10-b6cd-8569-b589-b17857e3bfe4/file)).

## 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`
