first commit

docs/foundation/flow/streams-chunk-queue/src/queue/storage-ops.md

@@ -0,0 +1,57 @@
+# queue / storage-ops
+
+## Purpose
+
+Holds the storage-related guards used by `StreamingChunkQueue.loadChunk`
+and `loadAllChunks`. Both methods need the same "is the persister
+configured?" check and the same "is the chunk actually in storage?"
+check, so factoring them out keeps the queue file from duplicating the
+guards and from spilling past the per-file line budget.
+
+## Features
+
+- `loadChunkBytes` throws `STORAGE_NOT_CONFIGURED` when no persister is
+  set, `STORAGE_CHUNK_MISSING` when the chunk is absent, and returns
+  the bytes otherwise.
+- `listStoredChunkIds` throws `STORAGE_NOT_CONFIGURED` when no
+  persister is set, otherwise forwards to `persister.listChunkIds()`.
+- Both helpers preserve a stringified `chunkId` in
+  `error.context` so logs are scannable.
+
+## Usage: Basic
+
+```ts
+const bytes = await loadChunkBytes(this.persister, chunkId);
+```
+
+## Usage: Advanced
+
+```ts
+const ids = await listStoredChunkIds(this.persister);
+for (const id of ids) await this.loadChunk(id);
+```
+
+## API Reference
+
+### `loadChunkBytes(persister, chunkId)` → `Promise<Uint8Array>`
+
+Throws `StreamsChunkQueueError(STORAGE_NOT_CONFIGURED)` if `persister`
+is `undefined`, `StreamsChunkQueueError(STORAGE_CHUNK_MISSING)` if the
+backend returns `undefined`, otherwise resolves with the bytes.
+
+### `listStoredChunkIds(persister)` → `Promise<bigint[]>`
+
+Throws `StreamsChunkQueueError(STORAGE_NOT_CONFIGURED)` if `persister`
+is `undefined`, otherwise forwards to `persister.listChunkIds()`.
+
+## Implementation Notes
+
+These helpers are pure functions instead of methods so they can be
+unit-tested without spinning up a queue. The queue's `loadChunk`
+delegates to `loadChunkBytes` and then re-uses `addChunk` to push the
+bytes into the in-memory map; this means storage-loaded chunks travel
+through the same validator / decryptor / hook pipeline as
+network-arrived chunks. The two helpers throw a `StreamsChunkQueueError`
+rather than a `TypeError` because the missing-persister condition is
+an operational fault (the caller forgot to wire storage) and should be
+filterable by error code in dashboards.