85 lines
6.6 KiB
Markdown
85 lines
6.6 KiB
Markdown
# 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
|
|
|
|
- [x] 1.1 Read `openspec/AGENTS.md` Sections 13 and 14
|
|
- [x] 1.2 Read `openspec/templates/README.md` — when and how to use the templates
|
|
- [x] 1.3 Reformat `proposal.md` from `openspec/templates/proposal.md`
|
|
- [x] 1.4 Reformat `tasks.md` from `openspec/templates/tasks.md`
|
|
- [x] 1.5 Every requirement in the spec delta carries a `**Verified by:**` line naming concrete `it(...)` titles — update iteratively during implementation
|
|
|
|
## 2. Implementation
|
|
|
|
- [x] 2.1 Scaffold `packages/drive/drive-plugin-chunks/` with `src/`, `tests/`, `src/__benchmarks__/`, and all feature subdirectories per spec
|
|
- [x] 2.2 Write `package.json` at `0.1.0` with `"type": "module"`, `"sideEffects": false`, full `exports` map, catalog deps, and dev deps
|
|
- [x] 2.3 Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`
|
|
- [x] 2.4 Write `vitest.config.ts` using `createTestConfig()` from `@suaveplan/testing/config` (pool: `forks`)
|
|
- [x] 2.5 Implement `src/types/chunks.types.ts` — `ChunksPluginOptions`, `ChunkLayoutStrategy`, `ManifestSource`, `Manifest`, `ChunkSource` interface
|
|
- [x] 2.6 Implement `src/error-codes.ts` — `defineCodes("CHUNKS", [...])`. Sibling `ChunksError`
|
|
- [x] 2.7 Implement `src/schemas/manifest.schema.ts` — Zod schema for the manifest JSON/CBOR shape
|
|
- [x] 2.8 Implement `src/codec/header.ts` — `encodeHeader(metadata)`, `parseHeader(buf)`, big-endian DataView reads/writes at locked offsets
|
|
- [x] 2.9 Implement `src/codec/chunk.ts` — `encodeChunk({ metadata, sig, ciphertext })`, `parseChunk(buf)`, length validation
|
|
- [x] 2.10 Implement `src/pipeline/encrypt-stream.ts` — XChaCha20-Poly1305 streaming encryptor over a `ReadableStream<Uint8Array>`
|
|
- [x] 2.11 Implement `src/pipeline/chop-stream.ts` — slice ciphertext stream at `payload_per_chunk` boundaries
|
|
- [x] 2.12 Implement `src/pipeline/sign-chunk.ts` — server-sign `metadata ‖ ciphertext`
|
|
- [x] 2.13 Implement `src/pipeline/verify-chunk.ts` — sig-verify on receipt, reject with appropriate error code on fail
|
|
- [x] 2.14 Implement `src/layout/sparse-file.ts` — pre-allocate, `setPartial` writes, side-band BitSet at `bitmap:<fileId>`
|
|
- [x] 2.15 Implement `src/layout/chunk-keys.ts` — one object per chunk at `chunks/<fileId>/<chunkId>`
|
|
- [x] 2.16 Implement `src/layout/auto.ts` — picks based on `storage.capabilities.partialWrites`
|
|
- [x] 2.17 Implement `src/manifest/build.ts` — assemble manifest from chunk metadata, server-sign
|
|
- [x] 2.18 Implement `src/manifest/load.ts` — fetch from storage (`manifest-as-chunk` mode) or HTTPS (`server-only` mode), Zod-validate, sig-verify
|
|
- [x] 2.19 Implement `src/manifest/source.ts` — strategy switch
|
|
- [x] 2.20 Implement `src/plugin.ts` — `chunksPlugin(options)`; `install(drive)` returns the handle with `getChunk`, `putChunk`, `hasChunks`, `availableChunks`, `ingest`, `loadManifest`
|
|
- [x] 2.21 Read middleware: registers via `drive.useMiddleware(...)`, intercepts `read(path)` and reassembles via streaming decrypt
|
|
- [x] 2.22 Write middleware: `drive.write(path, bytes)` — pass through unchanged; chunking is opt-in via `chunks.ingest(path)`
|
|
|
|
## 3. Tests
|
|
|
|
- [x] 3.1 `src/codec/chunk.test.ts` — round-trip every field, boundary lengths, invalid inputs
|
|
- [x] 3.2 `src/codec/chunk.spec-conformance.test.ts` — exact byte-offset pinning of v1 layout (`CHUNKS-FORMAT-V1-01` through `-03`)
|
|
- [x] 3.3 `src/pipeline/sign-chunk.test.ts` — sign + verify round-trip, mutation rejection
|
|
- [x] 3.4 `src/pipeline/sign-chunk.spec-conformance.test.ts` — sig covers metadata + ciphertext (`CHUNKS-SIG-01`)
|
|
- [x] 3.5 `src/layout/sparse-file.test.ts` — pre-allocation, offset writes, bitmap, BitSet round-trip
|
|
- [x] 3.6 `src/layout/sparse-file.spec-conformance.test.ts` — partial-write capability requirement (`CHUNKS-LAYOUT-SPARSE-01`)
|
|
- [x] 3.7 `src/layout/chunk-keys.test.ts` — one-key-per-chunk CRUD, list prefix semantics
|
|
- [x] 3.8 `src/layout/chunk-keys.spec-conformance.test.ts` — one-key-per-chunk semantics (`CHUNKS-LAYOUT-KEYS-01`)
|
|
- [x] 3.9 `src/layout/auto.spec-conformance.test.ts` — layout selection by capability (`CHUNKS-LAYOUT-AUTO-01`)
|
|
- [x] 3.10 `src/manifest/load.test.ts` — build, load, round-trip, invalid schema rejection
|
|
- [x] 3.11 `src/manifest/load.spec-conformance.test.ts` — `as-chunk` and `server-only` modes (`CHUNKS-MANIFEST-01`, `-02`)
|
|
- [x] 3.12 `src/plugin.test.ts` — install, handle methods, ingest round-trip, middleware registration
|
|
- [x] 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`)
|
|
- [x] 3.14 `src/error-codes.spec-conformance.test.ts` — frozen registry, namespace (`CHUNKS-CODES-01`)
|
|
- [x] 3.15 Every `it(...)` carries `{ timeout: 5000 }`
|
|
|
|
## 4. Documentation
|
|
|
|
- [x] 4.1 Sibling `.md` for every implementation `.ts` (≥200 words, basic + advanced examples, full API reference)
|
|
- [x] 4.2 README links every co-located `.md` under `## Modules`
|
|
- [x] 4.3 Update `CLAUDE.md` package listing
|
|
|
|
## 5. Pre-archive verification (the 5-gate triple)
|
|
|
|
- [x] 5.1 `bun run check` — Biome 0 errors / 0 warnings / 0 info across the whole monorepo
|
|
- [x] 5.2 `bunx turbo lint typecheck test --filter=@suaveplan/drive-plugin-chunks` — green
|
|
- [x] 5.3 `bunx turbo test:coverage --filter=@suaveplan/drive-plugin-chunks` — 100/100/100/100
|
|
- [x] 5.4 `bun scripts/openspec-conformance.ts @suaveplan/drive-plugin-chunks` — exit 0, no `error` findings
|
|
- [x] 5.5 `bunx turbo build --filter=@suaveplan/drive-plugin-chunks` — green
|
|
|
|
## 6. Pre-archive 7-row checklist (AGENTS.md Section 13)
|
|
|
|
- [x] 6.1 Generics threaded; `expectTypeOf` assertions on every literal-type claim
|
|
- [x] 6.2 Zod schemas wired at every declared boundary
|
|
- [x] 6.3 Every error code in `error-codes.ts` thrown by at least one production path
|
|
- [x] 6.4 Strict-mode behaviors tested both on and off
|
|
- [x] 6.5 OTel instruments emitted from production paths and asserted with a real in-memory `MeterProvider`
|
|
- [x] 6.6 Lifecycle dedup tested where claimed (in-flight Promise, idempotent set/load)
|
|
- [x] 6.7 No retroactive tick — every box above reflects work done in this change
|
|
|
|
## 7. Archive
|
|
|
|
- [x] 7.1 Fold spec delta into `openspec/specs/drive-plugin-chunks/spec.md`
|
|
- [x] 7.2 Move `openspec/changes/drive-plugin-chunks-port/` → `openspec/archive/<yyyy-mm-dd>-drive-plugin-chunks-port/`
|
|
- [x] 7.3 Refresh `MANIFEST.md` if package set or deps changed
|