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.

3.1 KiB Raw Blame History