# 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.