Initial Commit

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

@@ -0,0 +1,48 @@
+# 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.