# Tasks — add-cache-storage-cbor-codec

> Every checkbox MUST reflect work actually done in this change. Additive only — no behaviour change to existing codecs.

## 1. Pre-flight

- [ ] 1.1 Re-read `openspec/AGENTS.md` §0c (delta format) and §13 (gate order)
- [ ] 1.2 Confirm `@suaveplan/cbor` ships on genesis with `encode`, `decode`, `Tagged`, `type TagHandler` in the root barrel
- [ ] 1.3 Confirm `packages/flow/cache-storage/src/codec/codec.types.ts` exposes `Codec<T>` and that `storage-cache.ts` defaults to `JsonCodec` (no behaviour change needed)
- [ ] 1.4 Numbered checklist of every `### Requirement` and `#### Scenario` in `specs/cache-storage/spec.md` exists in working notes (AGENTS §0c step 6)

## 2. Package wiring

- [ ] 2.1 Add `@suaveplan/cbor` to `packages/flow/cache-storage/package.json` `dependencies` at `workspace:^`
- [ ] 2.2 Add subpath export `./codec/structured-clone` mirroring the shape of `./codec/json` and `./codec/identity`
- [ ] 2.3 Confirm `sideEffects` array remains correct (no new side-effect file added)

## 3. Error registry extension

- [ ] 3.1 Extend `CACHE_STORAGE_CODES` in `src/errors/errors.ts` with `CODEC_UNSUPPORTED_TYPE` and `CODEC_UNKNOWN_TAG`
- [ ] 3.2 Update `src/errors/errors.md` Features + API Reference to list the two new codes (doc-drift gate §4a)

## 4. Implementation — StructuredCloneCodec

- [ ] 4.1 `src/codec/structured-clone.ts` — `StructuredCloneCodec<T> implements Codec<T>`; lift table per `design.md`; encode/decode against `@suaveplan/cbor`
- [ ] 4.2 `src/codec/structured-clone.md` — sibling docs (≥200 words, basic + advanced examples, API reference, implementation notes)
- [ ] 4.3 `src/codec/index.ts` — explicit named re-export of `StructuredCloneCodec`
- [ ] 4.4 Confirm file size ≤300 lines; split if needed (e.g. lift table to `src/codec/structured-clone.tags.ts`)

## 5. Conformance harness

- [ ] 5.1 `src/codec/conformance.ts` — `runCodecConformance(codec, { name, supportsStructuredClone })` covering primitives, nested objects, arrays, `Date`, `Map`, `Set`, `Uint8Array`, `bigint` (positive + negative), `RegExp`, `URL`, deep nesting, empty collections
- [ ] 5.2 `src/codec/conformance.md` — sibling docs
- [ ] 5.3 `src/codec/conformance.test.ts` — harness self-test: a deliberately broken `Codec<unknown>` must cause the harness to fail (no tautological green)

## 6. Tests

- [ ] 6.1 `src/codec/structured-clone.test.ts` — invoke `runCodecConformance(new StructuredCloneCodec(), { name: "StructuredCloneCodec", supportsStructuredClone: true })`; plus direct tests for `CODEC_UNSUPPORTED_TYPE` (encode `() => {}`, `Symbol("x")`, `new WeakMap()`) and `CODEC_UNKNOWN_TAG` (decode a CBOR-encoded `Tagged(9999, "x")`)
- [ ] 6.2 Extend `src/codec/json.test.ts` with `runCodecConformance(new JsonCodec<unknown>(), { name: "JsonCodec", supportsStructuredClone: false })`
- [ ] 6.3 Extend `src/codec/identity.test.ts` with `runCodecConformance(new IdentityCodec(), { name: "IdentityCodec", supportsStructuredClone: false })` — using `Uint8Array` payloads only
- [ ] 6.4 Extend `src/errors/errors.test.ts` to assert the two new codes are reachable
- [ ] 6.5 Every `it(...)` carries `{ timeout: 5000 }`
- [ ] 6.6 All test imports via `@suaveplan/testing/runner` (§7)

## 7. Gates (§13 order)

- [ ] 7.1 Spec reconciliation — walk every `### Requirement` / `#### Scenario` against impl
- [ ] 7.2 `bunx turbo lint typecheck test --filter=@suaveplan/cache-storage`
- [ ] 7.3 `bunx turbo test:coverage --filter=@suaveplan/cache-storage` — 100/100/100/100
- [ ] 7.4 `bunx turbo build --filter=@suaveplan/cache-storage`
- [ ] 7.5 Banned-pattern, barrel-shape, runner-import, missing-`.md`, bare-version scans (zero output)
- [ ] 7.6 `bunx turbo test --filter=...@suaveplan/cache-storage` — dependent sweep (`@suaveplan/cache-redis` must remain green)

## 8. Manifest & archival

- [ ] 8.1 `bun scripts/folder-reorg/generate-manifest.ts`
- [ ] 8.2 Update `packages/flow/cache-storage/README.md` Modules section with the new codec
- [ ] 8.3 `bunx markdownlint-cli2 --fix`
- [ ] 8.4 Fold `specs/cache-storage/spec.md` into `openspec/specs/cache-storage/spec.md` (merge `## ADDED` block into existing spec)
- [ ] 8.5 Move change folder → `openspec/archive/<yyyy-mm-dd>-add-cache-storage-cbor-codec/`