suaveplan/openspec/archive/2026-05-12-storage-file/proposal.md

# Add @suaveplan/storage-file — Node.js filesystem AbstractStorage adapter

**Package**: `@suaveplan/storage-file`
**Status**: PROPOSED
**Type**: new-package

## Why

Genesis has `@suaveplan/storage` (AbstractStorage core with in-memory adapter) and `@suaveplan/storage-s3` (object-store adapter), but no filesystem-backed adapter for server-tier consumers (drive plugin, vault snapshots, i18n filesystem backends, integration test fixtures). The upstream `../suaveplan/packages/server/storage-file` exists at 90% coverage against the old `StorageLike` shim and ships with no atomic writes, no AbortSignal, no retry on transient errors, no path-traversal guard, and no streaming. The genesis rebuild extends `AbstractStorage`, adds POSIX-atomic temp-rename writes, hardens key validation, threads AbortSignal everywhere, and wires `@suaveplan/retry` for `EBUSY`/`EMFILE`/`ENFILE`. This unblocks several downstream packages (drive-template hydration, vault encrypted snapshots, server-side i18n backends, integration test storage fixtures).

## What changes

- ADDED: `NodeFsStorage` class extending `AbstractStorage` — full key-value storage rooted at a configurable `rootDir` with `.data`/`.meta` file pair per entry.
- ADDED: `createNodeFsStorage(options)` factory.
- ADDED: `NodeFsStorageOptions` interface + `NodeFsStorageOptionsSchema` Zod schema (Zod-validated boundary; throws `STORAGE_FILE.INVALID_OPTIONS` on malformed input).
- ADDED: `NodeFsLike` structural interface + `defaultNodeFs()` adapter wrapping `node:fs/promises` (`mkdir`, `readFile`, `writeFile`, `rename`, `unlink`, `readdir`, `stat`, `access`, `createReadStream`, `createWriteStream`). Injectable for tests.
- ADDED: `sanitizeKey(key)` strict key boundary — rejects empty, `..`, absolute paths (`/`, drive-prefixed), null bytes, control chars (0x00–0x1F, 0x7F), `KEY_TOO_LONG` over 1024 chars; normalises Windows `\` separators to POSIX `/`.
- ADDED: `STORAGE_FILE_CODES` registry via `defineCodes("STORAGE_FILE", [...])` — 8 codes: `NOT_FOUND`, `PERMISSION_DENIED`, `IO_FAILED`, `INVALID_KEY`, `ATOMIC_WRITE_FAILED`, `INVALID_OPTIONS`, `ABORTED`, `KEY_TOO_LONG`.
- ADDED: `StorageFileError extends SuaveplanError<StorageFileErrorCode>` with `key` discriminant.
- ADDED: Module-augmentation registry — `declare module "@suaveplan/storage"` adds `file: NodeFsStorage` to `StorageProviderRegistry` and `file: NodeFsStorageOptions` to `StorageProviderConfig`; `registerNodeFsProvider()` registers the constructor with the factory.
- ADDED: Atomic write helper — temp-file-then-`fs.rename` for `set` and metadata writes; rollback unlinks temp on failure.
- ADDED: `@suaveplan/retry` integration on transient filesystem errors (`EBUSY`/`EMFILE`/`ENFILE`/`EAGAIN`) — exponential backoff with injectable `TimersLike`.
- ADDED: Native Web Streams via `createReadStream`/`createWriteStream` consuming `node:fs.createReadStream`/`createWriteStream` (declared `capabilities.nativeStreams: true`).
- ADDED: `getPartial(offset, length)` via `fs.read` with a positioned `FileHandle` — declared `capabilities.partialReads: true`.
- ADDED: OTel surface — `storage_file.op_duration_ms{op,outcome}` + `storage_file.io_bytes{op,direction}` histograms; `storage_file.{reads,writes,deletes,errors}_total{outcome}` counters; per-op span on `@suaveplan/storage-file` tracer.

## Out of scope

- `setPartial` random-access writes — falls through to `AbstractStorage.defaultSetPartial` read-modify-write reference path. Reason: POSIX `pwrite` with sparse-file extension semantics is a follow-up; current callers don't require it and the reference fallback is correct.
- Watch/notify mode — `fs.watch` integration belongs in a separate `storage-file-watcher` package; the i18n filesystem backend already covers its own watch needs (`@suaveplan/i18n-backend-fs-multifile`).
- Encryption-at-rest — orthogonal concern handled by `@suaveplan/drive-plugin-chunks` (AEAD per chunk) and `@suaveplan/crypto-vault` (sealed container). Storage layer stores bytes verbatim.
- Quota enforcement beyond `AbstractStorage.maxValueSize`/`maxTotalSize` — caller-facing concern; OS-level `ulimit` and filesystem quotas are out of scope.

## Source mapping

This change derives from `../suaveplan/enterprise/storage-file.md` (118 lines) and ports `../suaveplan/packages/server/storage-file/src/filesystem.ts` (259 lines) to extend `AbstractStorage` rather than the legacy `StorageLike` shim.

| Requirement | Source lines | Notes |
|---|---|---|
| Node.js filesystem storage purpose | L10-L12 | "Node.js filesystem storage" — preserved as the package's single responsibility. |
| Zod request/response schemas | L39 | Reworded as Zod option boundary (`NodeFsStorageOptionsSchema`); the upstream phrasing references `@suaveplan/api-schemas` which is API-tier and not in scope here. |
| OpenTelemetry observability | L44 | Implemented as per-op spans, counters, and histograms emitted from production paths. |
| Retries via `@suaveplan/retry` | L45 | Mapped to transient `EBUSY`/`EMFILE`/`ENFILE`/`EAGAIN` retry with exponential backoff and injectable `TimersLike`. |
| Test coverage 100% | L52 | Adopted at the genesis-wide Istanbul 100/100/100/100 threshold. |
| File-size budget | L54 | Adopted: ≤300 LOC hard / ≤500 LOC test. |
| No mocks — real services | L55 | Tests use real `fs.mkdtemp` temp dirs and a real injectable `NodeFsLike` shim; no `vi.mock`. |
| `sideEffects: false` | L57 | Set in `package.json`. |
| Workspace deps + Bun catalog | L58 | All deps use `workspace:^` or `catalog:` refs. |
| Bun overrides exact | L59 | Inherits root override policy. |
| Biome clean | L60 | Enforced by `bun run check`. |
| TypeScript strict, no `any` | L61 | Adopted; no `any`, no `ts-ignore`. |
| Public API stability via Zod | L62 | `NodeFsStorageOptionsSchema` published; runtime validation at constructor boundary. |
| Error hierarchy via `@suaveplan/error` | L63 | `StorageFileError extends SuaveplanError<StorageFileErrorCode>`. |
| Performance benchmarks | L74 | Mitata benchmarks under `src/__benchmarks__/`. |
| Resilience — retries, cancellation | L75 | Retry on transient errors; AbortSignal threaded through every public async method. |
| Security — input validation at boundary | L76 | `sanitizeKey` strict boundary; `rootDir` isolation rejects traversal before any fs call. |

### Requirements with no source line

| Requirement | Justification |
|---|---|
| Extend `AbstractStorage` not `StorageLike` | The genesis storage core (`@suaveplan/storage`) replaces the legacy `StorageLike` shim with a richer `AbstractStorage` base class. Every adapter (memory, S3) extends it; this adapter MUST conform to the same contract for module-augmentation registry compatibility. |
| AbortSignal on every public async method | Required by `AbstractStorage`'s abstract signatures. Upstream had no AbortSignal support. |
| Atomic writes via temp-file-then-rename | Required for crash safety on the filesystem tier. Concurrent readers must never observe a torn write. POSIX `rename(2)` is atomic on the same filesystem; this is the standard primitive (e.g. `git`, `sqlite`). Upstream wrote directly to the destination path. |
| Path-traversal guard (`..`, absolute paths) | Upstream had no key sanitisation. Without it, a caller-controlled key (`../../etc/passwd`) would escape `rootDir`. Required by genesis security model. |
| Module-augmentation registry hook | The genesis `@suaveplan/storage` factory uses module augmentation (`StorageProviderRegistry`) for typed adapter dispatch. New adapters must hook in via `declare module` + `registerStorageProvider`. |
| Native streaming declared in `capabilities` | `AbstractStorage.capabilities` discriminates backends that support native streams from those that fall through to the buffered reference implementation. `node:fs.createReadStream`/`createWriteStream` are native; consumers (drive-plugin-chunks) read this flag to decide whether to chain or to pre-buffer. |
| Partial reads via positioned FileHandle | `capabilities.partialReads: true` is honoured by drive-plugin-chunks for range reads. Implementing it natively avoids `O(file-size)` memory for large objects. |

## Verification approach

Every requirement in the spec delta carries a `**Verified by:**` line referencing concrete `it(...)` titles in these files:

- `src/node-fs-storage/node-fs-storage.test.ts` — CRUD, metadata, list, clear, getSize, getPartial, native streams, AbortSignal, key sanitisation integration, atomic write under crash, retry exhaustion, OTel happy paths.
- `src/node-fs-storage/node-fs-storage.spec-conformance.test.ts` — type-level conformance against `AbstractStorage`, capabilities matrix, OTel instruments observed via real in-memory `MeterProvider`, idempotent registry registration, error-code registry exhaustion.
- `src/key-sanitizer/key-sanitizer.test.ts` — empty, traversal, absolute, null bytes, control chars, overlong, separator normalisation, valid paths.
- `src/node-fs/node-fs.test.ts` — `defaultNodeFs()` adapter forwards every method to `node:fs/promises`, against a real `fs.mkdtemp` directory.
- `src/retry-helper/retry-helper.test.ts` — transient classification (`EBUSY`/`EMFILE`/`ENFILE`/`EAGAIN` retry; `ENOENT`/`EACCES` not), exponential backoff timing under FakeClock + injectable timers, exhaustion → `IO_FAILED`.
- `src/otel/otel.test.ts` — `recordOp` emits histogram + counter with the documented attribute set against a real `InMemoryMetricExporter`.
- `src/streams/streams.test.ts` — large-file round-trip via Web Streams, AbortSignal mid-stream, structured error mapping.
- `src/registry/registry.test.ts` — registers `file` provider, `createStorage({ type: "file", config })` returns `NodeFsStorage`, idempotent re-registration.

## Impact

### Affected dependents

Run `bunx turbo ls --filter=...@suaveplan/storage-file` to enumerate. The package is new — no dependents currently. No action needed.

- No dependents (verified by `bunx turbo ls --filter=...@suaveplan/storage-file` returning the package itself).

### Affected upstreams

- `@suaveplan/storage` — `StorageProviderRegistry` module-augmented to add `file: NodeFsStorage` slot. Additive only; no breaking change. [x] no action needed (purely additive type slot).