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

**Status**: Proposed
**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). It is deliberately
> **Proposed, not Accepted**: the ownership assignment (S0.6.c), the normative
> dependency rules for the chosen direction (S0.6.d), the boundary validation of
> that direction (S0.6.e), and the architecture/owner approval (S0.6.f) are human
> governance decisions and remain open. 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) — agent-adopted pending
named ratification.** 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, enforced as Nx-tag-style rules).
- **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).

**S0.6.f (named architecture + affected owner approval) remains open** — an agent
cannot fabricate a signoff. This direction is adopted *pending* that human
ratification; the boundary proof and rules are gated in CI so the direction
cannot silently drift before then.

## 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 — enforced by
  `deletion-threshold-gate.mjs` once the kit is added to `SHARED_KIT_PACKAGES`.
- 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`