suaveplan/openspec/archive/2026-05-17-add-storage-uri-plugin-bundle/proposal.md

# Add @suaveplan/storage-uri-plugin-bundle — `bundle://` URI scheme for per-package shipped assets

**Package**: `@suaveplan/storage-uri-plugin-bundle`
**Status**: PROPOSED
**Type**: new-package (genesis-original)

- **Design**: ./design.md
- **Spec delta**: ./specs/storage-uri-plugin-bundle/spec.md

## Why

Several genesis packages need to ship per-package binary assets — impulse responses, sample fonts,
sample images, room-acoustic IRs — alongside their npm tarball, and resolve them through the
existing `@suaveplan/storage-uri` ecosystem so that consumers compose them with `drive`,
`storage-plugin-cache`, OTel, AbortSignal, and structured-error machinery for free.

There is no scheme today for "an asset shipped inside a package on disk / inside a CDN-hosted npm
tarball / inside a bundler's flattened asset graph". `file://` couples to Node, `https://` couples
to a specific deployment, and bundler-virtual schemes (`asset:`, `data:`, `blob:`) vary per bundler
and don't survive packaging. The `bundle://` scheme — `bundle://<package-slug>/<relative-path>` —
fills that gap with a single contract that works identically on Node, Bun, browsers, and bundlers
that flatten assets (Vite, esbuild, webpack).

Per-package registration is the key design choice: each consuming package calls
`bundleUriPlugin({ packageSlug, rootUrl: new URL("./", import.meta.url) })` from its own `register()`
and the resolver dispatches by slug. That makes the package the source of truth for "what does my
slug resolve to", lets bundlers do their normal URL-rewrite on the `import.meta.url` literal, and
keeps the universal tier honest — no Node-only `fs.readFile`, no browser-only `Response`, just
`fetch` over the resolved URL (which handles `file:`, `https:`, `data:`, `blob:` uniformly on Node
≥ 21, Bun, and modern browsers).

## What changes

- ADDED: `bundleUriPlugin(options)` factory returning a `UriPlugin` registerable with
  `createStorageUriResolver`. One factory call per consuming package; one plugin per slug.
- ADDED: `BundleUriPluginOptions` interface + `BundleUriPluginOptionsSchema` Zod schema. Required
  `packageSlug: string` (must match `/^@?[a-z0-9][a-z0-9._/-]{0,127}$/`), `rootUrl: URL | string`
  (resolved to a `URL` with trailing-slash enforced). Optional `fetch: FetchLike`,
  `logger: LoggerLike`, `clock: Clock`, `cache: { maxBytes: number }`.
- ADDED: `BUNDLE_URI_CODES` registry via `defineCodes("BUNDLE_URI", [...])` — 9 codes:
  `PACKAGE_MISMATCH`, `PATH_TRAVERSAL`, `READ_ONLY`, `NOT_FOUND`, `INVALID_URI`, `FETCH_FAILED`,
  `RANGE_INVALID`, `RANGE_UNSUPPORTED`, `ABORTED`.
- ADDED: `BundleUriError extends SuaveplanError<BundleUriErrorCode>` with `uri`, `scheme`,
  `packageSlug`, `relPath`, `rootKind` discriminants for diagnostics.
- ADDED: `parse(uri)` enforcing `bundle://<package-slug>/<rel-path>`: slug mismatch →
  `PACKAGE_MISMATCH`; `..` traversal (raw or post-decode) → `PATH_TRAVERSAL`; empty rel-path,
  malformed scheme, missing authority → `INVALID_URI` (forwarded from `parseUri`).
- ADDED: `build(key, meta?)` inverse — re-serialises `<packageSlug>/<key>` back to a `bundle://`
  URI for `list()` round-trips and the conformance harness.
- ADDED: Universal-tier resolution strategy (decision matrix in `design.md §3`): every read is
  executed via the injected `FetchLike` against `new URL(encodedRelPath, rootUrl)`. `file:`,
  `https:`, `http:`, `data:`, `blob:`, and bundler-virtual schemes all flow through `fetch`. The
  package ships NO `fs.readFile` adapter — `fetch` of `file:` is supported on Node ≥ 21 and Bun
  natively, and is the canonical universal-tier surface.
- ADDED: `StorageLike` shim implementing `get`, `exists`, `getMetadata`, `getPartial`,
  `createReadStream`, and explicitly-throwing `set`/`setPartial`/`delete`/`clear`/`list` (bundles
  are immutable; `READ_ONLY`).
- ADDED: Range reads via HTTP `Range: bytes=<start>-<end>` header on the fetch init; `206 Partial
  Content` returned verbatim, `200 OK` slow-pathed (full body sliced client-side) with a
  `bundle_uri.range_fallback_total{root_kind}` counter increment, `416 Range Not Satisfiable` →
  `RANGE_INVALID`. Underlying transports without range support (`data:`, `blob:` from some
  browsers) increment `range_fallback_total` and slice.
- ADDED: Streaming via `createReadStream(key, signal)` returning `Response.body` directly when
  present; falls back to a one-chunk stream wrapping the buffered bytes when `body` is null.
- ADDED: Optional in-memory LRU cache keyed by full URI. Off by default; opt-in via
  `options.cache = { maxBytes }`. Eviction policy: oldest-first when total bytes >
  `maxBytes`. NO stale-while-revalidate — bundles are content-addressed by package version.
- ADDED: `AbortSignal` threaded into every fetch call. Pre-aborted signals short-circuit with
  `BUNDLE_URI.ABORTED` before any fetch. Mid-flight abort propagates the underlying
  `AbortError` on `cause`.
- ADDED: OTel surface — `bundle_uri.op_duration_ms{op, root_kind, outcome}` histogram;
  `bundle_uri.reads_total{root_kind, outcome}`, `bundle_uri.errors_total{root_kind, code}`,
  `bundle_uri.range_fallback_total{root_kind}`, `bundle_uri.cache_hits_total{root_kind}`,
  `bundle_uri.cache_misses_total{root_kind}` counters; per-op span on
  `@suaveplan/storage-uri-plugin-bundle` tracer with attributes `bundle.package`,
  `bundle.rel_path` (truncated to 256 chars), `bundle.root_kind` (`file` | `http` | `data` |
  `blob` | `other`). Query strings stripped from every attribute (matches
  `storage-uri` precedent).
- ADDED: `runUriPluginConformance` pass — wired into `bundle-uri-plugin.spec-conformance.test.ts`
  with `validUris`, `invalidUris`, and `buildRoundTrip` fixtures derived from a temp-dir
  `file://` root and a localhost HTTP fixture root.

## Out of scope

- **`list(prefix)`.** Bundle roots have no uniform directory protocol (`file:` could `readdir`,
  `https:` cannot). `list` SHALL throw `BUNDLE_URI.READ_ONLY` (capability `listing: false`).
  Reason: a manifest-backed list would couple to a specific build tool's manifest format; the
  consumer can register a `storage-file` plugin if directory listing is needed.
- **Persistent disk cache.** The optional in-memory LRU is per-plugin-instance only. Cross-process
  caches are the consumer's job (compose `storage-plugin-cache` in front).
- **Server-side asset shipping helpers.** Build-tool plugins that copy assets into `dist/` are
  build-config, not runtime. Out of scope here; addressed by consuming packages' own
  build configs.
- **Auth / signed URLs.** If a consumer ships assets behind a signed CDN, they inject a
  `FetchLike` that adds the signature header — same pattern as `storage-http`.
- **Writes of any kind.** Bundles are immutable by nature; `set`/`delete`/`clear`/`setPartial`
  unconditionally throw `READ_ONLY`. There is no write-uploader slot — adding one would invalidate
  the immutability contract that callers (and caches) rely on.

## Source mapping

This is a **genesis-original** package; there is no upstream in `../suaveplan/`. The design
follows the genesis `UriPlugin` contract (`openspec/specs/storage-uri/spec.md`) and the
`drive-uri/plugins/{drive,drive-mesh,drive-template}` three-plugin reference pattern (each owns
one scheme, ships a factory, passes `runUriPluginConformance`).

### Requirements with no upstream source line

| Requirement | Justification |
|---|---|
| `bundle://` scheme name | Short, descriptive, distinct from `file:`/`asset:`/`pkg:`/`npm:` (which all have established meanings); matches the established `<scheme>-uri-plugin-<scheme>` naming convention of the package. |
| Per-package registration with `import.meta.url` | Lets bundlers do their normal URL-rewrite at the consumer's call site; the plugin never needs to know about bundler internals. |
| `fetch`-only resolution (no `fs.readFile` branch) | Keeps the universal tier honest — no Node-only / Bun-only branches. `fetch(file:URL)` works on Node ≥ 21 and Bun natively. |
| Per-package slug enforcement in `parse()` | Catches mis-routed URIs at the boundary (`bundle://other-pkg/x` against this plugin → `PACKAGE_MISMATCH`) before any I/O. |
| `..` traversal rejected both raw and post-decode | Prevents an attacker from escaping the rootUrl via `%2E%2E/...` after URL decoding. |
| Bundles immutable — every write throws `READ_ONLY` | Lets consumers and caches rely on the URI being content-addressed by package version; relaxing this would silently invalidate downstream caches. |
| Range reads via HTTP `Range` header | Universal across `file:`/`http:`/`https:` on Node ≥ 21 / Bun (fetch honours `Range` against `file:`); falls back transparently when origin returns 200. |
| In-memory LRU off by default | Bundle reads are typically rare-once / many-cached upstream by a `storage-plugin-cache`; baking a default LRU would mask that composition and burn memory on cold pages. |
| `BUNDLE_URI.ABORTED` distinct from `FETCH_FAILED` | Lets retry / circuit-breaker classifiers distinguish caller-initiated cancellation from transport failure. |

## ≥2-consumer justification

`@suaveplan/types` rule (AGENTS.md §0 item 6): a new shared abstraction must serve ≥2 packages.
The `bundle://` plugin will be consumed by:

1. **`@suaveplan/audio-ir-room-plugin-club`** (sibling-session, in-flight) — ships a club-room
   impulse response (`assets/club.wav`) inside its tarball; resolves it via
   `bundle://audio-ir-room-plugin-club/assets/club.wav`.
2. **`@suaveplan/audio-ir-room-plugin-pool`** (sibling-session, in-flight) — ships a swimming-pool
   impulse response (`assets/pool.wav`) on the same pattern.
3. **Future consumers** explicitly anticipated: `font-subset` sample-font shipping,
   `compress-image` reference-image bundles, `qrcode` reference-fixture bundles,
   `audio-sample-pack-plugin-*` family. Every package that needs to address its own shipped
   assets through a URI-routed dispatcher gains the same plumbing for free.

The factory is per-package — slug-scoped — so multiple consumers register parallel plugin
instances against the same resolver without conflict, each owning its own slug.

## Verification approach

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

- `src/factory/factory.test.ts` — option validation, slug regex, rootUrl normalisation
  (trailing-slash enforced), required `fetch` default = `globalThis.fetch`.
- `src/parse/parse.test.ts` — well-formed URIs accepted, scheme mismatch → `INVALID_URI`,
  empty rel-path → `INVALID_URI`, slug mismatch → `PACKAGE_MISMATCH`, raw `..` →
  `PATH_TRAVERSAL`, encoded `%2E%2E` → `PATH_TRAVERSAL` after decode, `build()` round-trips.
- `src/storage-shim/storage-shim.test.ts` — `get` against real `file://` temp dir, `get` against
  a real `node:http` localhost fixture server, `exists` HEAD path, `getMetadata` parses
  `content-length` / `content-type` / `last-modified` / `etag`, every write method throws
  `READ_ONLY`, `list` throws `READ_ONLY`.
- `src/range/range.test.ts` — `getPartial(offset, length)` issues `Range: bytes=offset-end`
  header against a real HTTP fixture, 206 path returns slice, 200 fallback path slices
  client-side and increments `range_fallback_total`, 416 → `RANGE_INVALID`.
- `src/streaming/streaming.test.ts` — `createReadStream` returns `Response.body` for HTTP root,
  returns a one-chunk stream wrapping the buffered bytes when `body` is null.
- `src/abort/abort.test.ts` — pre-aborted signal → `BUNDLE_URI.ABORTED` without fetch call;
  mid-flight abort propagates the underlying `AbortError` on `cause`.
- `src/cache/cache.test.ts` — LRU off by default (cache hits counter stays at 0); LRU on
  evicts oldest entry when `maxBytes` exceeded; cache hit returns the same bytes without
  re-fetching.
- `src/error-codes/error-codes.test.ts` — every `BUNDLE_URI.*` code is reachable from a real
  call site; `defineCodes` registry exhaustion test.
- `src/otel/otel.test.ts` — `op_duration_ms`, counters, span attributes against an in-memory
  `MeterProvider` + `SpanExporter`; query strings stripped from `bundle.rel_path` attribute.
- `src/conformance/conformance.test.ts` — `runUriPluginConformance(bundleUriPlugin(...), {...})`
  passes against both a `file://` temp-dir root and an `http://localhost:<port>/` fixture root.

## Impact

### Affected dependents

Run `bunx turbo ls --filter=...@suaveplan/storage-uri-plugin-bundle` to enumerate. The package is
new — no dependents currently. The two named future consumers (`audio-ir-room-plugin-club`,
`audio-ir-room-plugin-pool`) are in flight in a parallel session and will wire this in as part
of their own change.

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

### Affected upstreams

- `@suaveplan/storage-uri` — consumed as the `UriPlugin` contract source + `parseUri` helper +
  `runUriPluginConformance` harness. Pure consumer; no changes required to `storage-uri` itself.
  [x] no action needed (purely additive consumer).
- `@suaveplan/types` — consumed for `FetchLike`, `LoggerLike`, `Clock`, `StorageLike`,
  `StatResult` (latter via `storage-uri`'s `StreamingStorageExtensions`). Pure consumer; no
  changes required. [x] no action needed (purely additive consumer).
- `@suaveplan/error` — `defineCodes` + `SuaveplanError` base. Pure consumer. [x] no action needed.