suaveplan/openspec/changes/_superseded-narrow-deferrals-2026-05-17/add-cache-storage-cbor-codec/tasks.md

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/