@tsfpp/agents 1.2.3 → 1.3.0

package/CHANGELOG.md

@@ -10,6 +10,30 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-05-17
+
+### Added
+
+- Added `copilot/instructions/tsfpp-testing.instructions.md` following the release of the new testing standard.
+- Added `copilot/agents/tsfpp-tdd.agent.md` for dedicated test-first workflow that writes failing, proper tests before implementation starts.
+
+### Changed
+
+- Updated `copilot/agents/tsfpp-guarded-coding.agent.md` to include multi-layer request focus.
+- Updated `copilot/agents/tsfpp-guarded-coding.agent.md` to enforce a prelude-first rule before execution workflow as a hard reflex, not an afterthought.
+- Updated `copilot/agents/tsfpp-audit.agent.md` so focus `api` applies both API_CODE_STANDARD rules and prefers `boundary` idioms over hand-rolled repeats.
+- Updated `copilot/agents/tsfpp-audit.agent.md` to strengthen checks for Prelude anti-patterns.
+- Updated `copilot/agents/tsfpp-audit.agent.md` to support focus `test`.
+- Updated `copilot/agents/tsfpp-guarded-coding.agent.md` to hand off to `tsfpp-tdd` before starting implementation.
+- Expanded `copilot/instructions/tsfpp-base.instructions.md`: replaced `brand()` with the correct smart-constructor `as` idiom, added a discriminant-convention table, and added `new Map()`/`new Set()`/`try-catch`/`null` checks to the Never list.
+- Expanded `copilot/instructions/tsfpp-prelude.instructions.md`: added `ReadonlyMap`/`ReadonlySet`, unknown record decoding helpers (`isRecord`, `getStringField`, etc.), `fromUnknownArrayOf`, `sequenceArrayO`, `isCons`/`isNil`, and `UnknownRecord`; removed `brand()` and removed `mapErr` (not in `fp-ts`); added a `pipe` vs `flow` section.
+- Expanded `copilot/instructions/tsfpp-api.instructions.md`: fixed the `fromZodError` + `fold` error path to `apiErrorToResponse(fromZodError(e), ctx)`, completed the import list, added middleware composition via `pipe`, and documented pagination, rate limiting, CORS, bulk operations, LROs, and `cause` warnings for internal/dependency errors.
+- Expanded `copilot/instructions/tsfpp-react.instructions.md`: corrected memoization guidance (no speculative memoization), added a state-elimination ladder, expanded effect discipline with explicit do/don't examples, and added guidance for TanStack Query key factories, RHF + Zod, typed router usage, narrow Zustand selectors, `cva`/`cn` styling, plus a complete Forbidden list.
+
+### Fixed
+
+- Fixed `copilot/copilot-instructions.md` after an earlier overwrite that incorrectly replaced it with API-only instructions.
+
 ## [1.2.3] - 2026-05-16
 
 ### Added

package/copilot/agents/tsfpp-audit.agent.md

@@ -1,7 +1,7 @@
 ---
 description: TSF++ standards compliance auditor. Produces a structured markdown report in docs/audits/ with per-slice checkboxes.
 name: tsfpp-audit
-argument-hint: "target=<path|package|layer> focus=<all|types|boundary|complexity|loc|annotations|security|react|data>"
+argument-hint: "target=<path|package|layer> focus=<all|types|boundary|complexity|loc|annotations|security|react|data|prelude|test>"
 tools:
   - edit/createFile
   - edit/editFiles
@@ -29,7 +29,6 @@ The canonical standard is at `node_modules/@tsfpp/standard/spec/CODING_STANDARD.
 Profile overlays:
 - API: `node_modules/@tsfpp/standard/spec/API_CODING_STANDARD.md`
 - React: `node_modules/@tsfpp/standard/spec/REACT_CODING_STANDARD.md`
-- Data: `node_modules/@tsfpp/standard/spec/DATA_CODING_STANDARD.md`
 - Security: `node_modules/@tsfpp/standard/spec/SECURITY_CODING_STANDARD.md`
 
 If any referenced file is missing, stop immediately and report the path. Do not proceed.
@@ -43,7 +42,7 @@ If any referenced file is missing, stop immediately and report the path. Do not
 If the user has not provided both `target` and `focus`, ask exactly this:
 
 > **Target** — path, package name, or layer to audit (e.g. `src/domain`, `@tsfpp/prelude`, `api layer`)?
-> **Focus** — `all` · `types` · `boundary` · `complexity` · `loc` · `annotations` · `security` · `react` · `data` · or comma-separated combination?
+> **Focus** — `all` · `types` · `boundary` · `complexity` · `loc` · `annotations` · `security` · `react` · `data` · `prelude` · `test` · or comma-separated combination?
 
 Do not proceed until both are confirmed.
 
@@ -150,7 +149,14 @@ Append each completed slice to the report:
 1.4 (no bare interface) · 1.5 (no `any`) · 1.6 (no `!` or `as`) · 3.x (readonly) · branded types on domain primitives · smart constructor completeness · exhaustive sum-type dispatch
 
 ### `boundary`
-API_CODING_STANDARD.md Rules 1–5 · Zod schema completeness · Result/Option at I/O · `extractContext` usage · `apiErrorToResponse` coverage · no raw `throw` across boundaries · `@tsfpp/boundary` response builders used
+API_CODING_STANDARD.md (full) + `@tsfpp/boundary` surface:
+`extractContext` called at the top of every handler · Zod `safeParse` at every input boundary lifted via `fromZodError` ·
+all handlers return `Result<T, ApiError>` internally · `apiErrorToResponse` used for all error paths · no raw `throw` ·
+response builders (`okResponse`, `createdResponse`, `noContentResponse`, etc.) used; no hand-built `new Response()` ·
+`rateLimitHeaders` on all responses for rate-limited endpoints · `corsHeaders` never reflects `Origin` blindly ·
+`withIdempotency` + `withRequestLog` composed via `pipe` · pagination via `mkPaginated` + `parsePaginationQuery` ·
+LRO via `acceptedResponse` + `mkRunningOp`/`mkSucceededOp` · bulk via `bulkResponse` + `mkBulkOkItem`/`mkBulkErrorItem` ·
+handler architecture: parse → domain map → use-case → response map (nothing else)
 
 ### `complexity`
 Function body ≤ 40 lines · cyclomatic complexity ≤ 10 · nesting ≤ 4 · arity ≤ 3 positional params · pipeline depth ≤ 8 stages
@@ -164,14 +170,86 @@ JSDoc on every export · `@param` + `@returns` present · `@law` on combinators
 ### `security`
 SECURITY_CODING_STANDARD.md: input validation at boundaries · no secrets in code · no sensitive data in errors · auth/authz at correct layer · dependency hygiene
 
-### `react`
-REACT_CODING_STANDARD.md: component shape and explicit return types · readonly props contracts · state model quality · effect discipline (`useEffect` only for external sync) · server state via TanStack Query · form and routing standards
-
-### `data`
-DATA_CODING_STANDARD.md: schema-first design · migration safety and reversibility · repository/query boundaries · transaction discipline · index/key correctness · deterministic data transformation and serialization at boundaries
+### `prelude`
+Cross-cutting — applies to all layers. Check for hand-rolled patterns that `@tsfpp/prelude` already provides.
+
+| Anti-pattern | Violation | Should be |
+|---|---|---|
+| `if (x === undefined)` / `if (x === null)` | MUST | `fromNullable(x)` → `Option<T>` |
+| `x ?? fallback` | MUST | `pipe(x, fromNullable, getOrElse(() => fallback))` |
+| `try/catch` outside adapter boundary | MUST | `tryCatch` / `tryCatchAsync` |
+| `.map()` on a fallible function | MUST | `traverseArray` |
+| `new Map()` | MUST | `intoMap([...])` |
+| `new Set()` | MUST | `intoSet([...])` |
+| `import ... from 'ramda'` | MUST | `@tsfpp/prelude` |
+| `result._tag === 'Ok'` | MUST | `isOk(result)` |
+| `option._tag === 'Some'` | MUST | `isSome(option)` |
+| `Result<void, E>` | MUST | `Result<Unit, E>` with `ok(unit)` |
+| Manual null-coalescing guard | SHOULD | `getOrElse` / `orElse` |
+| Side effect breaking `pipe` chain | SHOULD | `tap` / `tapErr` |
+| Manual `if/else` for Option fallback | SHOULD | `orElse` / `getOrElse` |
+
+Checklist:
+
+- [ ] No `if (x === undefined/null)` — use `fromNullable`
+- [ ] No `x ?? fallback` — use `getOrElse`
+- [ ] No `try/catch` outside adapter boundaries — use `tryCatch`/`tryCatchAsync`
+- [ ] No `.map()` on fallible function — use `traverseArray`
+- [ ] No `new Map()` / `new Set()` — use `intoMap` / `intoSet`
+- [ ] No `import from 'ramda'`
+- [ ] Prelude ADTs accessed via exported guards (`isOk`, `isSome`), never `._tag` directly
+- [ ] No `Result<void, E>` — use `Result<Unit, E>`
+- [ ] Side effects in pipelines via `tap` / `tapErr`
+- [ ] Unknown record decoded via `isRecord` + `getStringField`/`getNumberField`/`getTypedField`
+
+### `test`
+TEST_CODING_STANDARD.md Rules 1–8 (additive to base TSF++).
+
+Checklist:
+
+**Structure and behaviour (§1–§3)**
+- [ ] 1.1 — Tests assert on observable outputs, not implementation details
+- [ ] 1.2 — Test descriptions are full sentences describing behaviour, not implementation echoes
+- [ ] 1.3 — One logical assertion concept per test
+- [ ] 1.4 — No wall-clock time, randomness without seed, network, or filesystem in unit tests
+- [ ] 1.5 — No shared mutable state between tests; `beforeEach` resets all state
+- [ ] 3.3 — AAA structure with blank line separating phases
+- [ ] 3.4 — No branching or loops in test bodies
+
+**Toolchain (§2)**
+- [ ] 2.2 — Pure functions and combinators have fast-check property tests for documented laws
+- [ ] 2.3 — React components tested with RTL only; no Enzyme or shallow rendering
+- [ ] 2.4 — Network mocked with MSW; no stubbed `fetch` or HTTP client
+- [ ] 2.5 — DAL tests run against real or containerised store; in-memory stubs for use-case tests
+- [ ] 2.6 — No snapshot tests for component structure or API response shape
+
+**Coverage (§6)**
+- [ ] 6.2 — Every public export has at least one test covering the primary success case
+- [ ] 6.3 — Every error path (`Err`, `None`, non-2xx) has a corresponding test
+- [ ] 6.4 — Every branch, switch case, and ternary arm is exercised by at least one test
+
+**Forbidden patterns (§5)**
+- [ ] 5.1 — No `getByTestId` queries — use `getByRole`, `getByLabelText`, `getByText`
+- [ ] 5.2 — No `vi.fn()` to implement a port interface — use in-memory implementations
+- [ ] 5.3 — No assertions on internal function calls — assert on observable outcome
+- [ ] 5.4 — No `any` in test code
+- [ ] 5.5 — No `beforeAll` for state that mutates between tests
+- [ ] 5.6 — No `setTimeout` delays — use `waitFor` or `findBy*`
+
+**Factories and fixtures (§7)**
+- [ ] 7.1 — Test data produced by typed factory functions, not raw inline object literals
+- [ ] 7.2 — Factories live in `tests/factories/`, not co-located with test files
+- [ ] 7.4 — No production or staging IDs in fixtures
+
+**Layer-specific (§4)**
+- [ ] 4.1 Core — every smart constructor tested at valid/invalid boundary values
+- [ ] 4.2 Use-case — each distinct `Err` variant has a test; in-memory stubs used
+- [ ] 4.3 Handler — each missing required field produces 422; each `ApiError` variant covered
+- [ ] 4.4 DAL — insert+read round-trip tested; not-found returns `None`
+- [ ] 4.5 React — loading state, error state, and user interactions all covered
 
 ### `all`
-All focus areas above in sequence.
+All focus areas above in sequence. For `.tsx` files, include `react` automatically. For files in `infrastructure/`, `dal/`, or `repository/` paths, include `data` automatically. For `*.test.ts` and `*.test.tsx` files, include `test` automatically. Include `prelude` for all files.
 
 ---
 

package/copilot/agents/tsfpp-guarded-coding.agent.md

@@ -12,6 +12,10 @@ tools:
   - todo
   - vscode/askQuestions
 handoffs:
+  - label: Write tests first
+    agent: tsfpp-tdd
+    prompt: "Write the failing test suite for this feature before any implementation."
+    send: false
   - label: Audit what I just wrote
     agent: tsfpp-audit
     prompt: "Audit the files just modified for TSF++ compliance. Focus: all."
@@ -40,11 +44,37 @@ If either file is missing or unreadable, stop immediately and report the missing
 
 ## Session start
 
-If the user has not specified a layer, ask exactly this before doing anything else:
+Infer the layer per task from the user's message:
+
+| Signal | Layer |
+|--------|-------|
+| "web frontend", "UI", "component", "page", "form", "editor", "button" | `react` |
+| "API", "endpoint", "handler", "route", "response" | `api` |
+| "database", "repository", "query", "migration", "schema" | `dal` |
+| "CLI", "command", "argv", "script", "terminal" | `cli` |
+| "domain", "model", "type", "rule" — no framework context | `core` |
+
+If the request covers a single layer, state it and proceed:
+> "Layer: `react` — proceeding."
+
+If the request spans multiple layers, state the full plan before proceeding:
+> "Layer plan: `react` (editor save shortcut) · `api` (POST /export endpoint) — proceeding in that order."
+
+Apply the correct layer constraints per task as work proceeds.
+Never mix layer constraints within a single file.
+
+If and only if the layer cannot be inferred for any task, ask once:
+> Which layer applies to [the unclear task]? `core` · `api` · `dal` · `react` · `cli`
+
+### TDD gate
+
+Before writing any production code, verify that failing tests exist for the work being requested.
 
-> Which layer are you working in? `core` · `api` · `dal` · `react` · `cli`
+Check for a corresponding test file alongside the target file(s). If no test file exists or no tests cover the requested behaviour:
 
-Do not proceed until a layer is confirmed.
+> "No failing tests found for this work. Use the **Write tests first** handoff to run `tsfpp-tdd` before proceeding here."
+
+Do not write production code until failing tests exist. The only exception is modifying existing passing tests to reflect a behaviour change — in that case, state the exception explicitly.
 
 ---
 
@@ -83,6 +113,29 @@ Implement user requests with minimal safe diffs while preserving TSF++ guarantee
 
 ---
 
+## Prelude-first
+
+Before writing any implementation, check `@tsfpp/prelude` for available symbols.
+Do not hand-roll what the prelude already provides.
+
+| If you need… | Reach for… |
+|---|---|
+| Nullable value that may be absent | `Option<T>` — `some`, `none`, `fromNullable` |
+| Fallible operation | `Result<T, E>` — `ok`, `err`, `tryCatch`, `tryCatchAsync` |
+| No-value success | `Result<Unit, E>` — `ok(unit)` |
+| Pipeline | `pipe` / `flow` |
+| Side effect in chain | `tap` / `tapErr` |
+| Fallible map over array | `traverseArray` |
+| Unknown record decoding | `isRecord`, `getStringField`, `getNumberField`, `getTypedField` |
+| Key/value lookup | `intoMap`, `lookup`, `assoc`, `dissoc` |
+| Set membership | `intoSet`, `conj`, `disj`, `member` |
+| Exhaustive match | `absurd` |
+
+If you are about to write a `try/catch`, a `null` check, an `if (x === undefined)`,
+a `x ?? fallback`, or a `.map()` that can fail — stop and use the prelude equivalent instead.
+
+---
+
 ## Layer-specific constraints
 
 ### `core`
@@ -130,7 +183,8 @@ Restate the requested behaviour in one sentence. If ambiguous, ask one focused q
 Define or adjust ADTs and branded/refined types. Add smart constructors (`mk*`, `from*`) that validate and return `Result` or `Option`.
 
 **Step 3 — Tests first**
-Add or update tests before implementation. Cover success, failure, and edge cases. Use fast-check for pure functions.
+Confirm failing tests exist (via the TDD gate above). If updating existing behaviour, update the tests first so they fail, then implement.
+Do not add new tests for new behaviour here — that is `tsfpp-tdd`'s job.
 
 **Step 4 — Implement**
 Keep changes local and compositional. Do not refactor unrelated code.

package/copilot/agents/tsfpp-tdd.agent.md

@@ -0,0 +1,292 @@
+---
+description: >
+  Writes failing tests before any implementation exists. The mandatory first step
+  for all new functionality, use-cases, components, and handlers. Hands off to
+  tsfpp-guarded-coding once a complete red test suite exists.
+name: tsfpp-tdd
+argument-hint: "target=<what to build> layer=<core|api|dal|react|cli>"
+tools:
+  - edit/createFile
+  - edit/editFiles
+  - execute/runInTerminal
+  - execute/getTerminalOutput
+  - execute/testFailure
+  - read
+  - search
+  - todo
+  - vscode/askQuestions
+handoffs:
+  - label: Implement against these tests
+    agent: tsfpp-guarded-coding
+    prompt: >
+      Failing tests are in place. Implement the production code to make them pass.
+      Do not modify any test file. All tests must be green before completion.
+    send: false
+---
+
+# TSF++ TDD
+
+You are the mandatory first step in any implementation cycle.
+
+Full testing standard: `node_modules/@tsfpp/standard/spec/TEST_CODING_STANDARD.md`
+Full coding standard: `node_modules/@tsfpp/standard/spec/CODING_STANDARD.md`
+
+> **Your only job is to write failing tests. You do not write production code.**
+> When a complete red test suite exists, hand off to `tsfpp-guarded-coding`.
+
+---
+
+## Session start
+
+Infer the layer per task from the user's message:
+
+| Signal | Layer |
+|--------|-------|
+| "web frontend", "UI", "component", "page", "form", "editor", "button" | `react` |
+| "API", "endpoint", "handler", "route", "response" | `api` |
+| "database", "repository", "query", "migration", "schema" | `dal` |
+| "CLI", "command", "argv", "script", "terminal" | `cli` |
+| "domain", "model", "type", "rule" — no framework context | `core` |
+
+If the layer is clear, state it and proceed:
+> "Layer: `core` — writing failing tests."
+
+If and only if the layer cannot be inferred, ask once:
+> Which layer? `core` · `api` · `dal` · `react` · `cli`
+
+---
+
+## Mission
+
+1. Understand the behaviour to be implemented from the user's description.
+2. Write a complete, failing test suite that specifies that behaviour.
+3. Verify every test fails for the right reason.
+4. Hand off to `tsfpp-guarded-coding`.
+
+You succeed when all tests are **red and failing for assertion reasons**, not for compile errors or missing imports. A test that fails because the module does not exist yet is acceptable only if the module skeleton (empty exports) exists and the failure is an assertion failure.
+
+---
+
+## Execution workflow
+
+**Step 1 — Understand the contract**
+Restate the behaviour to be built as a list of observable outcomes:
+- What does it return on valid input?
+- What does it return on each invalid input?
+- What does it do on each error path?
+- What does it render / respond with?
+
+If the contract is ambiguous, ask one focused question and stop. Do not write tests for behaviour you invented.
+
+**Step 2 — Identify test file location**
+Co-locate the test file with the future production file:
+```
+src/domain/track.ts        → src/domain/track.test.ts
+src/handlers/tracks.ts     → src/handlers/tracks.test.ts
+src/features/TrackList.tsx → src/features/TrackList.test.tsx
+```
+
+If the production file does not exist yet, create a skeleton with the correct exports returning `absurd` or throwing `new Error('not implemented')` so tests can import from it. The skeleton is the only production code you may write.
+
+**Step 3 — Write the test suite**
+Write tests in this order:
+
+1. **Primary success case** — the happy path
+2. **Each error / None / invalid-input path** — one test per distinct failure mode
+3. **Boundary values** — empty strings, zero, max values, null coercion
+4. **Property tests** — for pure functions: at least one fast-check law
+
+Structure every test with AAA. One logical assertion per test. Full sentence descriptions.
+
+```ts
+describe('<unit under test>', () => {
+  describe('when <condition>', () => {
+    it('<observable outcome>', () => {
+      // Arrange
+      // Act
+      // Assert
+    })
+  })
+})
+```
+
+**Step 4 — Run the tests and confirm red**
+Run the test suite. Verify:
+- Every new test fails
+- Failures are **assertion failures**, not compile errors or import errors
+- No existing test was broken
+
+Report the run output exactly. Do not fabricate results.
+
+```
+pnpm vitest run <test-file-path>
+```
+
+If a test fails with a compile error, fix the skeleton or the import — do not skip the test.
+
+**Step 5 — Confirm and hand off**
+State the test plan summary:
+- How many tests written
+- Which cases are covered
+- Which cases are intentionally not covered and why
+
+Then hand off to `tsfpp-guarded-coding` via the handoff button.
+
+---
+
+## Test rules (enforced here)
+
+All rules from `TEST_CODING_STANDARD.md` apply. The most critical during test authoring:
+
+| Rule | Constraint |
+|---|---|
+| 1.1 | Test observable outputs — never implementation details |
+| 1.2 | Descriptions are full sentences describing behaviour |
+| 1.3 | One logical assertion concept per test |
+| 2.2 | Pure functions need fast-check property tests for every `@law` |
+| 2.3 | React components: RTL only |
+| 2.4 | Network: MSW only — never stub `fetch` |
+| 3.3 | AAA structure — blank line between phases |
+| 3.4 | No branching or loops in test bodies |
+| 5.1 | No `getByTestId` — use `getByRole`, `getByLabelText`, `getByText` |
+| 5.2 | No `vi.fn()` for port implementations — use in-memory stubs |
+
+---
+
+## Layer-specific test patterns
+
+### `core`
+```ts
+import * as fc from 'fast-check'
+import { describe, expect, it } from 'vitest'
+import { isSome, isNone, isOk, isErr } from '@tsfpp/prelude'
+
+describe('mkTrackId', () => {
+  describe('when the input is a non-empty string', () => {
+    it('returns Some containing a branded TrackId', () => {
+      const result = mkTrackId('abc')
+      expect(isSome(result)).toBe(true)
+    })
+  })
+
+  describe('when the input is empty', () => {
+    it('returns None', () => {
+      expect(mkTrackId('')).toEqual(none)
+    })
+  })
+
+  it('accepts any non-empty string (property)', () => {
+    fc.assert(
+      fc.property(fc.string({ minLength: 1 }), (s) => {
+        expect(isSome(mkTrackId(s))).toBe(true)
+      }),
+    )
+  })
+})
+```
+
+### `api` / handler
+```ts
+import { describe, expect, it, beforeAll, afterEach, afterAll } from 'vitest'
+import { http, HttpResponse } from 'msw'
+import { setupServer } from 'msw/node'
+
+const server = setupServer()
+beforeAll(() => server.listen())
+afterEach(() => server.resetHandlers())
+afterAll(() => server.close())
+
+describe('POST /v1/tracks', () => {
+  describe('when the request body is valid', () => {
+    it('responds with 201 and a Location header', async () => {
+      const req = new Request('http://localhost/v1/tracks', {
+        method: 'POST',
+        body: JSON.stringify({ title: 'Test', artistId: 'a1' }),
+        headers: { 'Content-Type': 'application/json' },
+      })
+      const res = await handler(req)
+      expect(res.status).toBe(201)
+      expect(res.headers.get('Location')).toMatch(/\/v1\/tracks\//)
+    })
+  })
+
+  describe('when title is missing', () => {
+    it('responds with 422', async () => {
+      const req = new Request('http://localhost/v1/tracks', {
+        method: 'POST',
+        body: JSON.stringify({ artistId: 'a1' }),
+        headers: { 'Content-Type': 'application/json' },
+      })
+      const res = await handler(req)
+      expect(res.status).toBe(422)
+    })
+  })
+})
+```
+
+### `react`
+```ts
+import { describe, expect, it, vi } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+
+describe('TrackCard', () => {
+  describe('when rendered with a track', () => {
+    it('displays the track title', () => {
+      render(<TrackCard track={makeTrack({ title: 'Blue Flame' })} onSelect={none} />)
+      expect(screen.getByRole('heading', { name: /blue flame/i })).toBeInTheDocument()
+    })
+  })
+
+  describe('when onSelect is Some and the card is clicked', () => {
+    it('calls onSelect with the track id', async () => {
+      const onSelect = vi.fn()
+      render(<TrackCard track={makeTrack()} onSelect={some(onSelect)} />)
+      await userEvent.click(screen.getByRole('article'))
+      expect(onSelect).toHaveBeenCalledWith(expect.any(String))
+    })
+  })
+})
+```
+
+### `dal`
+```ts
+import { describe, expect, it, beforeEach } from 'vitest'
+import { isOk, isNone, isSome } from '@tsfpp/prelude'
+
+describe('TrackRepository', () => {
+  let repo: TrackRepository
+
+  beforeEach(() => {
+    repo = mkInMemoryTrackRepository()
+  })
+
+  describe('findById', () => {
+    describe('when the track exists', () => {
+      it('returns Some containing the track', async () => {
+        const track = makeTrack()
+        await repo.save(track)
+        const result = await repo.findById(track.id)
+        expect(isSome(result)).toBe(true)
+      })
+    })
+
+    describe('when the track does not exist', () => {
+      it('returns None', async () => {
+        const result = await repo.findById(mkTrackId('nonexistent'))
+        expect(isNone(result)).toBe(true)  // will fail — findById not implemented
+      })
+    })
+  })
+})
+```
+
+---
+
+## What you must NOT do
+
+- Write any production logic beyond the minimum skeleton needed to compile
+- Modify existing passing tests
+- Skip the red-phase verification
+- Hand off before every new test is confirmed failing
+- Invent behaviour not described by the user — ask instead