suaveplan/openspec/archive/2026-04-28-drive-plugin-chunks-port/tasks.md

Tasks — drive-plugin-chunks-port

Every checkbox MUST reflect work actually done in this change. Do not retroactively tick boxes for work that was already in main when this change opened. Do not tick a box for a test that doesn't exist or doesn't pin the requirement it claims to verify.

1. Spec authoring

• 1.1 Read openspec/AGENTS.md Sections 13 and 14
• 1.2 Read openspec/templates/README.md — when and how to use the templates
• 1.3 Reformat proposal.md from openspec/templates/proposal.md
• 1.4 Reformat tasks.md from openspec/templates/tasks.md
• 1.5 Every requirement in the spec delta carries a **Verified by:** line naming concrete it(...) titles — update iteratively during implementation

2. Implementation

• 2.1 Scaffold packages/drive/drive-plugin-chunks/ with src/, tests/, src/__benchmarks__/, and all feature subdirectories per spec
• 2.2 Write package.json at 0.1.0 with "type": "module", "sideEffects": false, full exports map, catalog deps, and dev deps
• 2.3 Write tsconfig.json extending @suaveplan/typescript-config/library.json
• 2.4 Write vitest.config.ts using createTestConfig() from @suaveplan/testing/config (pool: forks)
• 2.5 Implement src/types/chunks.types.ts — ChunksPluginOptions, ChunkLayoutStrategy, ManifestSource, Manifest, ChunkSource interface
• 2.6 Implement src/error-codes.ts — defineCodes("CHUNKS", [...]). Sibling ChunksError
• 2.7 Implement src/schemas/manifest.schema.ts — Zod schema for the manifest JSON/CBOR shape
• 2.8 Implement src/codec/header.ts — encodeHeader(metadata), parseHeader(buf), big-endian DataView reads/writes at locked offsets
• 2.9 Implement src/codec/chunk.ts — encodeChunk({ metadata, sig, ciphertext }), parseChunk(buf), length validation
• 2.10 Implement src/pipeline/encrypt-stream.ts — XChaCha20-Poly1305 streaming encryptor over a ReadableStream<Uint8Array>
• 2.11 Implement src/pipeline/chop-stream.ts — slice ciphertext stream at payload_per_chunk boundaries
• 2.12 Implement src/pipeline/sign-chunk.ts — server-sign metadata ‖ ciphertext
• 2.13 Implement src/pipeline/verify-chunk.ts — sig-verify on receipt, reject with appropriate error code on fail
• 2.14 Implement src/layout/sparse-file.ts — pre-allocate, setPartial writes, side-band BitSet at bitmap:<fileId>
• 2.15 Implement src/layout/chunk-keys.ts — one object per chunk at chunks/<fileId>/<chunkId>
• 2.16 Implement src/layout/auto.ts — picks based on storage.capabilities.partialWrites
• 2.17 Implement src/manifest/build.ts — assemble manifest from chunk metadata, server-sign
• 2.18 Implement src/manifest/load.ts — fetch from storage (manifest-as-chunk mode) or HTTPS (server-only mode), Zod-validate, sig-verify
• 2.19 Implement src/manifest/source.ts — strategy switch
• 2.20 Implement src/plugin.ts — chunksPlugin(options); install(drive) returns the handle with getChunk, putChunk, hasChunks, availableChunks, ingest, loadManifest
• 2.21 Read middleware: registers via drive.useMiddleware(...), intercepts read(path) and reassembles via streaming decrypt
• 2.22 Write middleware: drive.write(path, bytes) — pass through unchanged; chunking is opt-in via chunks.ingest(path)

3. Tests

• 3.1 src/codec/chunk.test.ts — round-trip every field, boundary lengths, invalid inputs
• 3.2 src/codec/chunk.spec-conformance.test.ts — exact byte-offset pinning of v1 layout (CHUNKS-FORMAT-V1-01 through -03)
• 3.3 src/pipeline/sign-chunk.test.ts — sign + verify round-trip, mutation rejection
• 3.4 src/pipeline/sign-chunk.spec-conformance.test.ts — sig covers metadata + ciphertext (CHUNKS-SIG-01)
• 3.5 src/layout/sparse-file.test.ts — pre-allocation, offset writes, bitmap, BitSet round-trip
• 3.6 src/layout/sparse-file.spec-conformance.test.ts — partial-write capability requirement (CHUNKS-LAYOUT-SPARSE-01)
• 3.7 src/layout/chunk-keys.test.ts — one-key-per-chunk CRUD, list prefix semantics
• 3.8 src/layout/chunk-keys.spec-conformance.test.ts — one-key-per-chunk semantics (CHUNKS-LAYOUT-KEYS-01)
• 3.9 src/layout/auto.spec-conformance.test.ts — layout selection by capability (CHUNKS-LAYOUT-AUTO-01)
• 3.10 src/manifest/load.test.ts — build, load, round-trip, invalid schema rejection
• 3.11 src/manifest/load.spec-conformance.test.ts — as-chunk and server-only modes (CHUNKS-MANIFEST-01, -02)
• 3.12 src/plugin.test.ts — install, handle methods, ingest round-trip, middleware registration
• 3.13 src/plugin.spec-conformance.test.ts — store-as-is invariant, sig-verify gate, read reassembly (CHUNKS-INVARIANT-01, CHUNKS-VERIFY-01, CHUNKS-READ-01)
• 3.14 src/error-codes.spec-conformance.test.ts — frozen registry, namespace (CHUNKS-CODES-01)
• 3.15 Every it(...) carries { timeout: 5000 }

4. Documentation

• 4.1 Sibling .md for every implementation .ts (≥200 words, basic + advanced examples, full API reference)
• 4.2 README links every co-located .md under ## Modules
• 4.3 Update CLAUDE.md package listing

5. Pre-archive verification (the 5-gate triple)

• 5.1 bun run check — Biome 0 errors / 0 warnings / 0 info across the whole monorepo
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/drive-plugin-chunks — green
• 5.3 bunx turbo test:coverage --filter=@suaveplan/drive-plugin-chunks — 100/100/100/100
• 5.4 bun scripts/openspec-conformance.ts @suaveplan/drive-plugin-chunks — exit 0, no error findings
• 5.5 bunx turbo build --filter=@suaveplan/drive-plugin-chunks — green

6. Pre-archive 7-row checklist (AGENTS.md Section 13)

• 6.1 Generics threaded; expectTypeOf assertions on every literal-type claim
• 6.2 Zod schemas wired at every declared boundary
• 6.3 Every error code in error-codes.ts thrown by at least one production path
• 6.4 Strict-mode behaviors tested both on and off
• 6.5 OTel instruments emitted from production paths and asserted with a real in-memory MeterProvider
• 6.6 Lifecycle dedup tested where claimed (in-flight Promise, idempotent set/load)
• 6.7 No retroactive tick — every box above reflects work done in this change

7. Archive

• 7.1 Fold spec delta into openspec/specs/drive-plugin-chunks/spec.md
• 7.2 Move openspec/changes/drive-plugin-chunks-port/ → openspec/archive/<yyyy-mm-dd>-drive-plugin-chunks-port/
• 7.3 Refresh MANIFEST.md if package set or deps changed