Initial commit

docs/work/epics/binder-wrap-helper/01-wire-use-case-helper/_story.md

@@ -0,0 +1,45 @@
+---
+id: 01-wire-use-case-helper
+epic: binder-wrap-helper
+title: Introduce wireUseCase helper in core-shared
+type: technical-story
+status: done
+feature: core-shared
+depends-on: []
+blocks: [02-migrate-feature-binders, 03-update-generator-templates]
+created: 2026-05-13T19:17:10+02:00
+updated: 2026-05-14T19:21:52.308Z
+---
+
+## Goal
+
+Add `wire-use-case.ts` + `wire-use-case.test.ts` to `packages/core-shared/src/conformance/` and export the helper from the `@repo/core-shared/conformance` barrel. The helper encapsulates `withSpan(withCapture(withAudit?(factory(deps))))` composition and performs the container bind step, so callers pass options and get back a brand-stacked wired value.
+
+## Why
+
+Every feature binder currently inlines the same `withSpan + withCapture` wrapping per use case — 30–79 lines of mechanical boilerplate per binder pair. A single helper in core-shared eliminates the structural clone groups and makes adjusting the wrapping shape a one-file change.
+
+## Done when
+
+- `packages/core-shared/src/conformance/wire-use-case.ts` exists and is exported from `packages/core-shared/src/conformance/index.ts`.
+- `wire-use-case.test.ts` covers: no-audit path (Instrumented + Captured brands present), audit path (Instrumented + Captured + Audited brands present), span-name derivation (`<feature>.<name>`), capture-tag structure (`{ feature, layer, name }`), container binding (symbol resolves to wired value), idempotent re-bind (unbind + bind when symbol already bound).
+- `pnpm typecheck && pnpm test && pnpm lint && pnpm conformance && pnpm fallow:audit && pnpm coverage:diff` all pass.
+- `wire-use-case.ts` reaches 100% statement/branch coverage (file is small; exhaustive test coverage is achievable).
+
+## In scope
+
+- `packages/core-shared/src/conformance/wire-use-case.ts` — the helper and its exported types.
+- `packages/core-shared/src/conformance/wire-use-case.test.ts` — unit tests using `RecordingTracer` / `RecordingLogger` / `RecordingAuditLog` (or equivalent mocks from core-shared/core-audit).
+- Export line added to `packages/core-shared/src/conformance/index.ts`.
+- No changes to `withSpan`, `withCapture`, or `withAudit` internals — the helper composes them as-is.
+
+## Out of scope
+
+- Feature binder changes (Story 02).
+- Generator template changes (Story 03).
+- `wireController` peer — the `layer` discriminator in `wireUseCase` covers controllers too if the shapes converge; a separate peer is a follow-up if needed.
+- Repository or service binding patterns.
+
+## Tasks
+
+- [x] Add `wire-use-case.ts` + `wire-use-case.test.ts` to `packages/core-shared/src/conformance/` and export from the conformance index — implement the helper (options object: `container`, `symbol`, `factory`, `deps`, `feature`, `layer`, `name`, `tracer`, `logger`, optional `auditLog`) with full unit tests covering both audit and no-audit paths, brand presence assertions via `isInstrumented` / `isCaptured` / `isAudited`, container binding, and idempotent re-bind; all gates pass on this single commit.