49 lines
3.1 KiB
Markdown
49 lines
3.1 KiB
Markdown
# OpenSpec Change: drive-plugin-chunks-port
|
|
|
|
**Package**: `@suaveplan/drive-plugin-chunks`
|
|
**Status**: PROPOSED
|
|
**Type**: new-package
|
|
|
|
## Why
|
|
|
|
The core `@suaveplan/drive` package is deliberately file-level only. Chunk addressing — splitting files into signed, encrypted chunks for P2P distribution — must live in a separate plugin so that consumers who only need local file VFS (e.g. server-side S3-backed storage) don't pay the bundle cost of chunk codecs, AEAD pipelines, and manifest handling. This plugin defines the `ChunkSource` interface that `drive-mesh` and transport packages consume, establishing the file↔chunk seam as a stable, versioned contract.
|
|
|
|
## What changes
|
|
|
|
- ADDED: `@suaveplan/drive-plugin-chunks` package at `packages/drive/drive-plugin-chunks/`
|
|
- ADDED: `version 0x0001` chunk binary format — 164-byte header + variable ciphertext, big-endian, ed25519 server-signed
|
|
- ADDED: `ChunkSource` interface — consumed by mesh and transport packages, not drive core
|
|
- ADDED: Server-signed manifest format with Zod/CBOR validation
|
|
- ADDED: Two storage layouts (`sparse-file`, `chunk-keys`) plus `auto` selector
|
|
- ADDED: Streaming encrypt-then-chunk pipeline (XChaCha20-Poly1305) — never materialises whole file in memory
|
|
- ADDED: Read-path Drive middleware that intercepts `drive.read(path)` and reassembles plaintext from chunks
|
|
- ADDED: `CHUNKS_CODES` error registry (`ChunksError`) with 12 namespaced codes
|
|
|
|
## Out of scope
|
|
|
|
- Mesh / peer index / parallel pull → `drive-mesh-port`.
|
|
- Wire transports → `drive-transport-*-port`.
|
|
- v2 chunk format with compression / algo agility — reserved flag bits documented but unimplemented.
|
|
- Automatic chunking on every `drive.write()` — chunking is opt-in via `chunks.ingest(path)` only.
|
|
|
|
## Source mapping
|
|
|
|
> This package is genesis-original. No `../suaveplan/enterprise/drive-plugin-chunks.md` exists. Delete this section.
|
|
|
|
## Verification approach
|
|
|
|
Every requirement below is verified by a spec-conformance test that pins an observable behavior. Unit tests cover happy-path and edge-case scenarios for the same module.
|
|
|
|
- `src/codec/chunk.spec-conformance.test.ts` — byte-exact layout, flags rejection, payload-length invariants (`CHUNKS-FORMAT-V1-01` through `-03`)
|
|
- `src/pipeline/sign-chunk.spec-conformance.test.ts` — signature covers metadata + ciphertext, mutation detection (`CHUNKS-SIG-01`)
|
|
- `src/layout/sparse-file.spec-conformance.test.ts` — pre-allocation, `setPartial` writes, bitmap, capability gate (`CHUNKS-LAYOUT-SPARSE-01`)
|
|
- `src/layout/chunk-keys.spec-conformance.test.ts` — one-key-per-chunk semantics (`CHUNKS-LAYOUT-KEYS-01`)
|
|
- `src/layout/auto.spec-conformance.test.ts` — layout selection by capability (`CHUNKS-LAYOUT-AUTO-01`)
|
|
- `src/manifest/load.spec-conformance.test.ts` — manifest-as-chunk and server-only modes (`CHUNKS-MANIFEST-01`, `-02`)
|
|
- `src/plugin.spec-conformance.test.ts` — store-as-is invariant, sig-verify gate, read reassembly (`CHUNKS-INVARIANT-01`, `CHUNKS-VERIFY-01`, `CHUNKS-READ-01`)
|
|
- `src/error-codes.spec-conformance.test.ts` — frozen registry, namespace (`CHUNKS-CODES-01`)
|
|
|
|
## Migration impact
|
|
|
|
None — additive only. New package with no existing consumers in genesis.
|