@cloudbitmaps/core 0.10.0 → 0.11.0

package/dist/core/erase-id.d.ts

@@ -4,11 +4,18 @@
  *
  * There is no per-id delete on an immutable object, and there is no mutable tier to hold a tombstone, so erasure
  * is what every other write in this library is: a new generation. The current generation is streamed chunk by
- * chunk through the ascending writer — every chunk copied through, the one chunk holding the id re-encoded with
- * that bit cleared — then published fenced on the generation it streamed, and that generation is collected immediately
+ * chunk through the ascending writer — every chunk decoded, range-checked and re-encoded, the one holding the id
+ * with that bit cleared — then published fenced on the generation it streamed, and that generation is collected immediately
  * (`keep: 0`), so the bit is **physically gone from the bucket when this returns**. Constant memory: one chunk in
  * flight, never the whole segment.
  *
+ * **`erased: true` is a claim about every generation of the segment, not only the one it replaced.** A rollback
+ * leaves generations above the pointer that were once current and can be made current again, so a holder can sit
+ * above the pointer as well as below it, and there can be several. Before it reports `erased: true` the call
+ * therefore lists the bucket once more and reads every generation it has not already seen to be clean; any that
+ * still holds the id makes it report or throw instead. In the ordinary case that list returns one generation, the
+ * current one, and costs one `list`.
+ *
  * What it does NOT reach: backups, replicas and noncurrent object versions hold the old object until their own
  * lifecycle removes it. For an at-rest guarantee that survives those, use encryption plus crypto-shred
  * (`destroySegment`), which is per segment — a per-id shred is infeasible because one DEK covers the whole segment.
@@ -39,10 +46,12 @@
  * signal of that state, so a faulting re-read rethrows it rather than replacing it with a transient-looking
  * registry error.
  *
- * **No orphan is left behind by a refused rewrite**, and it is worth saying why, because nothing else collects
- * above the pointer: `putImmutable` commits atomically, so a rewrite whose stream throws leaves no object at all;
- * and if the write did complete, the winner's generation is necessarily higher, which puts ours below its pointer
- * where its `keep: 0` takes it. The two orderings are mutually exclusive.
+ * **A refused rewrite deletes its own object when it would outlive the winner above the pointer.** `putImmutable`
+ * commits atomically, so a rewrite whose stream throws leaves no object at all. One that completed is either
+ * below the winner's pointer, where the winner's collection takes it, or above it: the case where this call took
+ * its number after the winner's object was already in the bucket. Up there nothing collects it, and it was derived
+ * from a generation the winner has replaced, so when the winner was another erasure it still holds the id that
+ * erasure has just reported gone. That object is deleted before this call returns — see `discardRefused`.
  *
  * Without that fence the failure was silent and severe, and both halves were reproduced: `nextGeneration` picks a
  * number above everything in the bucket, so a forward-only publish here always won — discarding a concurrent
@@ -50,9 +59,12 @@
  * generation put the first one's id back and collected the generation that had evidenced its removal. A false
  * Art. 17 receipt is the worst output this module can produce.
  *
- * Readers pinned to the collected generation re-resolve on their next read; that is the documented cost of
- * physical deletion on return. **Do not re-load the id while erasing it**: a load that lands after this rewrite
+ * A live read still fetching from the collected generation heals forward to the rewrite, and a pin of it fails with
+ * `NotFoundError` for any chunk it has yet to read: that is the documented cost of physical deletion on return. **Do not re-load the id while erasing it**: a load that lands after this rewrite
  * carries whatever its source held, and the library cannot know that source was meant to exclude the id.
+ * A load already in flight is the same case: it writes its object above the pointer before it publishes, and an
+ * erasure that finds the id in that object deletes it as it does any holder there, so a load that then publishes
+ * leaves the pointer naming a missing object.
  */
 import { type IAuditSink } from './audit.js';
 import type { CodecInterface } from './codec.js';
@@ -74,9 +86,9 @@ export interface EraseIdDeps {
      * -bound AAD. Rewriting an encrypted segment without a keystore throws {@link KeyUnavailableError}.
      */
     readonly keystore?: IKeystore;
-    /** When true, refuse to rewrite a **cleartext** segment (the same guard the read path and bulk-load offer). */
+    /** When true, refuse to rewrite a **cleartext** segment (the same guard the read path and a load offer). */
     readonly requireEncryption?: boolean;
-    /** Supplying a clock that can yield makes the rewrite cooperative — see `bulkLoadCrbmGeneration`. */
+    /** Supplying a clock that can yield makes the rewrite cooperative, as it makes a load. */
     readonly clock?: Yielder;
     /** Per-chunk decode ceiling (invariant 5); defaults to 1 MiB. */
     readonly maxBitmapBytes?: number;
@@ -85,57 +97,80 @@ export interface EraseIdResult {
     readonly segment: string;
     readonly namespace?: string;
     /**
-     * True iff the id **was** a member and a generation without it is now the segment's current generation — and
-     * the generation that held it has been deleted (see `collected`). This is the field an erasure ledger records.
+     * True iff the id **was** in the segment — in its current generation, or in any other generation still in the
+     * bucket, above the pointer or below it — and **no generation of the segment holds it now**. The current
+     * generation is one without it, every generation that held it has been deleted (see `collected`), and the call
+     * listed the bucket and read what was left before saying so. This is the field an erasure ledger records.
      */
     readonly erased: boolean;
     /**
-     * Why nothing was rewritten, when `erased` is false. `'absent'` (no registry row), `'destroyed'` (a crypto-shred
-     * tombstone — already unreadable), `'no-generation'` (a row with no Storage data yet), `'not-member'` (the id is not
-     * in the current generation — the common case across a fleet scan), or `'superseded'`.
+     * Why the id was not erased, when `erased` is false. `'absent'` (no registry row), `'destroyed'` (a crypto-shred
+     * tombstone — already unreadable), `'no-generation'` (a row with no Storage data yet), `'not-member'` (no
+     * generation in the bucket holds the id — the common case across a fleet scan), or `'superseded'`.
      *
      * **`'superseded'` means this call did not erase the id, not that the id is still there.** Another writer — a
-     * load, or another erasure — moved the pointer off the generation this rewrite was derived from, so the
-     * rewrite is not a valid successor to what is now current. Re-run against the new generation: if the id is
-     * still present it is erased then; if the racing writer was another erasure of the *same* id, the re-run
-     * reports `'not-member'` because it is already gone. Either way the re-run settles it, which is why it is the
-     * documented action for this reason and for no other.
+     * load, another erasure, or a rollback — moved the pointer off the generation this call read, so what it was
+     * doing no longer follows from what is current: a rewrite derived from that generation is not a valid successor
+     * to the new one, and a generation it meant to delete above the pointer may be the one the pointer now names.
+     * Re-run against the new generation: if the id is still present it is erased then; if the racing writer was
+     * another erasure of the *same* id, the re-run reports `'not-member'` because it is already gone. Either way the
+     * re-run settles it, which is why it is the documented action for this reason and for no other.
      *
-     * The first four reasons are also returned when the row changes *underneath* a rewrite already in flight,
-     * not only when it is read up front — a concurrent `dropSegment` gives `'destroyed'`, a retention sweep that
-     * purges the row gives `'absent'`. A caller branching on `reason` never has to care which it was.
+     * The first three reasons are also returned when the row changes *underneath* a call already in flight, not
+     * only when it is read up front — a concurrent `dropSegment` gives `'destroyed'`, a retention sweep that purges
+     * the row gives `'absent'`. A caller branching on `reason` never has to care which it was.
      */
     readonly reason?: 'absent' | 'destroyed' | 'no-generation' | 'not-member' | 'superseded';
-    /** The generation the id was found in (present whenever it was read). */
+    /**
+     * The generation the id was found in (present whenever one was read) — the newest of them, when the current
+     * generation did not hold it and several others did.
+     */
     readonly fromGeneration?: number;
-    /** The generation written without the id (present whenever one was written, even if `superseded`). */
+    /**
+     * The generation written without the id (present whenever one was written, even if `superseded`). A refused
+     * rewrite whose object sits above the winner's pointer deletes that object again before it returns.
+     */
     readonly generation?: number;
     /**
-     * Generations deleted after the publish — normally `[fromGeneration]`, plus any older orphans. Empty when nothing
-     * was rewritten. **It is what THIS call deleted, not the proof that the id is gone** — those differ: a
-     * concurrent collector can take the generation holding the id first, and then `erased: true` is returned with
-     * `collected` empty, because the claim is about the bucket rather than about who emptied it. Treat a
-     * non-empty `collected` as evidence and an empty one as "someone else got there", never as a failure.
+     * Generations this call deleted. On a rewrite that is normally `[fromGeneration]`, plus any older orphans. When
+     * the current generation did not hold the id, it is every generation below the pointer (`keep: 0` takes them
+     * together) and each one above the pointer that held the id; the ones above it that did not hold the id stay,
+     * because they are an operator's rollback targets. Empty when nothing was deleted.
      *
-     * A call that cannot establish the claim **throws** rather than report `erased: true` over bytes that are
-     * still there. Three ways that happens: a Storage `delete` fault, a collection pass that could not prove the
-     * segment was still the same one (`WriteConflictError`, which an ordinary retirement landing mid-call is
-     * enough to cause), and the same refusal on the collect-only path below, where nothing was published at all.
+     * **It is what THIS call deleted, not the proof that the id is gone** — those differ: a concurrent collector can
+     * take a generation holding the id first, and then `erased: true` is returned without it in `collected`, because
+     * the claim is about the bucket rather than about who emptied it. Treat a non-empty `collected` as evidence and
+     * a missing holder as "someone else got there", never as a failure.
      *
-     * **Re-run it**, and read what the re-run says rather than assuming it finished the job. The pointer has
-     * moved, so the re-run looks for the id in the *superseded* generations as well as the current one, and there
-     * are three outcomes:
+     * A call that cannot establish the claim **throws** `WriteConflictError` or the underlying fault rather than
+     * report `erased: true` over bytes that are still there. Four ways that happens: a Storage `delete` fault; a
+     * collection pass that could not prove the segment was still the same one (which an ordinary retirement landing
+     * mid-call is enough to cause); the same refusal on the path where the current generation did not hold the id
+     * and nothing was published at all; and a generation still holding the id when the bucket is listed at the end
+     * — one an operator rolled the pointer onto while a rewrite was collecting, say.
      *
-     *  - `erased: true` naming the superseded generation it found the id in and collected — the ordinary case,
-     *    and the one that gives you the receipt the failed call could not;
+     * **Re-run it**, and read what the re-run says rather than assuming it finished the job. The re-run looks for
+     * the id in every generation in the bucket, not only the current one, and there are three outcomes:
+     *
+     *  - `erased: true` naming the generation it found the id in — the ordinary case, and the one that gives you
+     *    the receipt the failed call could not;
      *  - `'not-member'` — a racing collector took that generation first. The bit is gone, but **no run reports a
      *    receipt for it**, so keep the failed call's error alongside your ledger if you need the audit trail;
      *  - `'absent'` — the segment's registry row is gone, so it is no longer a segment at all and
-     *    `store.eraseSubject` will not even scan it. Anything left in the bucket is an **orphan**: find it with
-     *    `checkConsistency()` and collect it with `gcOrphanGenerations`.
+     *    `store.eraseSubject` will not even scan it. Anything left in the bucket is an **orphan**: list it with
+     *    `listGenerations` (`store.generations`) and delete it with `dropSegment` (`store.dropSegment`), which both
+     *    read the bucket as well as the row. `checkConsistency()` and the generation collection start from the row, so
+     *    neither reaches a segment that has none.
      */
     readonly collected: readonly number[];
 }
+/**
+ * Remove `id` from `ref`: rewrite its current generation without it, and delete every other generation that holds
+ * it. See the module note for the contract.
+ *
+ * Emits one `segment.rewrite` audit event at the publish (before the superseded generation is collected), so the
+ * compliance record exists the moment the generation without the id is authoritative.
+ */
 export declare function eraseIdFromSegment(ref: SegmentRef, id: number, deps: EraseIdDeps, options?: {
     audit?: IAuditSink;
 }): Promise<EraseIdResult>;

package/dist/core/erasure.d.ts

@@ -8,7 +8,7 @@
  * segment/namespace). A `destroyed` segment reads as empty (its DEK is gone). Only works on an **encrypted**
  * segment; a cleartext segment has no key to shred.
  *
- * The tombstone is also the fence every writer respects: `publishGeneration` and `bulkLoadCrbmGeneration` refuse
+ * The tombstone is also the fence every writer respects: a load refuses
  * a `destroyed` row, so a load racing an erasure cannot resurrect the segment. A single id's erasure is a different
  * operation — `eraseIdFromSegment` rewrites the generation without it.
  */
@@ -54,11 +54,18 @@ export declare function destroySegment(ref: SegmentRef, deps: EraseDeps, options
 /**
  * Crypto-shred every segment in a namespace. **Irreversible.** `confirmNamespace` must equal `namespace`.
  * Returns a per-segment result (skips cleartext segments unless `allowCleartext`).
+ *
+ * **Bounded.** It lists the whole namespace before it destroys anything, and holds the listing resident, so the
+ * listing is capped at `maxScanSegments` (default {@link DEFAULT_MAX_SCAN_SEGMENTS}, 250,000), the ceiling every
+ * other fleet scan keeps. A namespace over it throws `BudgetExceededError` **before any segment is destroyed**,
+ * never part-way through; raise `maxScanSegments` when the namespace really is that large and the memory is there.
+ * A `maxScanSegments` that is not a finite number >= 1 throws `ValidationError`, again before anything is destroyed.
  */
 export declare function eraseNamespace(namespace: string, deps: EraseDeps, options: {
     confirmNamespace: string;
     allowCleartext?: boolean;
     audit?: IAuditSink;
+    maxScanSegments?: number;
 }): Promise<{
     destroyed: DestroyResult[];
 }>;
@@ -82,12 +89,12 @@ export interface DropResult {
      * Generations still present in Storage when the sweep gave up, ascending. **Empty is the normal outcome** — a
      * non-empty value means the storage was NOT fully reclaimed and the drop should be re-run.
      *
-     * This field exists because its absence was a defect. A drop used to return `dropped: true` with a populated
-     * `generationsDeleted` and no `reason` even when an object holding the **complete set** had just been left in
-     * the bucket by a writer that was already mid-write when the tombstone landed (its publish is refused, but the
-     * object survives). For a cleartext segment those bytes are readable — and `gcOrphanGenerations` only collects
-     * a destroyed segment's generations when something runs it. The result was indistinguishable from a clean
-     * drop, so an operator got no signal to re-run. Now they do.
+     * Without it, a drop would return `dropped: true` with a populated `generationsDeleted` and no `reason` even
+     * when an object holding the **complete set** had just been left in the bucket by a writer that was already
+     * mid-write when the tombstone landed (its publish is refused, but the object survives). For a cleartext
+     * segment those bytes are readable — and the collection only takes a destroyed segment's generations
+     * when something runs it. That result would look like a clean drop, and an operator would get no signal to
+     * re-run.
      */
     readonly generationsRemaining: readonly number[];
     /**
@@ -136,9 +143,8 @@ export interface DropResult {
  * - `dropSegment` **removes the storage**. It works on a cleartext segment, and on an encrypted one it *also*
  *   drops the DEKs, so it is a strict superset there.
  *
- * Before this existed there was no supported way to delete a segment and stop paying for it, and the obvious
- * workaround — an object-store lifecycle rule on the key prefix — deletes the bytes while the registry still
- * points at them. That is exactly the `missing-storage-generation` state the DR runbook says not to serve traffic
+ * It is the supported way to delete a segment and stop paying for it. The obvious workaround — an object-store
+ * lifecycle rule on the key prefix — deletes the bytes while the registry still points at them. That is exactly the `missing-storage-generation` state the DR runbook says not to serve traffic
  * on, and it surfaces *intermittently*, because a read consults the cache before Storage: cached chunks answer
  * correctly and evicted ones throw. The whole value of this function is that the ordering below cannot be got
  * wrong by a caller.
@@ -146,8 +152,8 @@ export interface DropResult {
  * **THE ORDER IS THE CONTRACT — registry first, then Storage.**
  *
  * 1. **Registry first.** After the tombstone nothing resolves a generation for this segment, so no reader can
- *    reach for bytes that are about to disappear, and no writer can publish onto it (`publishGeneration` and
- *    `bulkLoadCrbmGeneration` refuse a `destroyed` row).
+ *    reach for bytes that are about to disappear, and no writer can publish onto it (a
+ *    load refuses a `destroyed` row).
  * 2. **Storage second, best-effort, and re-swept.** Once the pointer is a tombstone the segment resolves as empty,
  *    so a failure part-way through leaves **orphaned bytes, not a wrong answer.** Orphans cost money and are
  *    cleaned up by re-running; a torn pointer costs correctness and is not self-healing. Given the choice, leak
@@ -163,10 +169,10 @@ export interface DropResult {
  * cache for a window. A fresh store, or any reader that had not touched the segment, sees empty at once.
  *
  * That window is bounded by `cache.genTtlMs` (default 2 s) **only for a reader whose storage source has both a clock
- * and a registry and a positive TTL** — expiry needs all three. A source built without a clock, or with
- * `cache.genTtlMs: 0` (documented as "pin forever"), holds its resolved snapshot for its own lifetime; because a
- * cache-LRU hit never reaches Storage, such a reader can answer `true` for a dropped segment **indefinitely** and must
- * be restarted. This is the *same* caching that makes the delete-bytes-first ordering fail intermittently rather
+ * and a registry and a positive TTL** — expiry needs all three. A source built without a clock or a registry, or
+ * with `cache.genTtlMs: 0`, has no timed refresh: it notices the drop only when a read has to fetch from a deleted
+ * generation or its reader cache evicts the segment. Because a cache-LRU hit never reaches Storage, such a reader
+ * can answer `true` for a dropped segment **indefinitely**, and must be invalidated or restarted. This is the *same* caching that makes the delete-bytes-first ordering fail intermittently rather
  * than loudly — it cuts both ways.
  *
  * `confirmSegment` must equal `ref.segment`, matching `destroySegment`/`eraseNamespace`. For an automated

package/dist/core/errors.d.ts

@@ -1,7 +1,7 @@
 /**
- * Typed errors — callers learn *why* something failed, never by parsing strings. Retry is the driver
- * decorators' job, not the engine's: a driver classifies its backend's failures into this vocabulary, and
- * `withRetry` decides what is transient.
+ * Typed errors — callers learn *why* something failed, never by parsing strings. Retry is not the engine's job: a
+ * driver classifies its backend's failures into this vocabulary, and the store's read wrapper retries the
+ * transient ones through `withRetry`.
  */
 /**
  * Registry-symbol brands, so an error stays classifiable when the class object is not shared.
@@ -36,16 +36,16 @@ export declare class WriteConflictError extends CloudRoaringError {
 export declare class IntegrityError extends CloudRoaringError {
 }
 /**
- * A requested object/row does not exist. Part of the driver error vocabulary; thrown by
- * the persistent drivers (S3, GCS, Azure Blob, local filesystem) — the in-memory drivers return
- * `null` instead.
+ * A requested object/row does not exist. Part of the driver error vocabulary: every storage driver this
+ * library ships, the in-memory one included, throws it for a read of a generation object that is not there.
+ * A registry `get` of a row that is not there returns `null` instead.
  */
 export declare class NotFoundError extends CloudRoaringError {
 }
 /**
  * This build/configuration cannot perform the requested operation, though nothing is malformed. Two uses:
- * (1) **format** — the bytes are well-formed but unreadable here (an unknown `.crbm` major version, an
- * encrypted file before the crypto path exists) — distinct from `IntegrityError` (corruption); and (2)
+ * (1) **format** — the bytes are well-formed but unreadable here (an unknown `.crbm` major version) —
+ * distinct from `IntegrityError` (corruption); and (2)
  * **store configuration** — an operation this store's wiring doesn't support (e.g. a lifecycle helper like
  * `eraseSubject`/`retireExpired` called on a store built without a storage backend). Raised at
  * operation time, before any mutation.
@@ -79,8 +79,9 @@ export declare class BudgetExceededError extends CloudRoaringError {
 export declare class KeyUnavailableError extends CloudRoaringError {
 }
 /**
- * A **transient** infrastructure fault that is safe to retry — throttling, a 5xx, a dropped connection,
- * a client-side request timeout. Drivers classify their backend's retryable faults and raise this (the
+ * A **transient** infrastructure fault — throttling, a 5xx, a dropped connection, a client-side request
+ * timeout. Retrying a read that failed this way is safe; a write that failed this way may still have landed, so
+ * its caller re-runs the call rather than replaying the request. Drivers classify their backend's retryable faults and raise this (the
  * SDK-specific knowledge stays in the SDK-specific driver); the retry layer (`core/retry`) retries **only**
  * this class, never a deterministic error like {@link ValidationError}, {@link IntegrityError},
  * {@link NotFoundError}, or {@link WriteConflictError} (retrying those is pointless or wrong). The original
@@ -91,25 +92,17 @@ export declare class KeyUnavailableError extends CloudRoaringError {
  * to log; if you serialize the whole error *chain*, be aware you're including that metadata.
  */
 export declare class TransientError extends CloudRoaringError {
-    /** A second brand so the whole transient subtree (incl. {@link TimeoutError}) is classifiable cross-bundle. */
+    /** A second brand so a transient fault is classifiable cross-bundle. */
     readonly [TRANSIENT_BRAND]: true;
     constructor(message: string, options?: {
         cause?: unknown;
     });
 }
-/**
- * A single attempt exceeded its time budget. Subclass of {@link TransientError} so the retry layer treats a
- * timeout as retryable by default — a stalled request often succeeds on a fresh connection. Raised by a
- * driver whose injected client reports a request timeout — setting one on your injected client is the
- * recommended way to bound a hang.
- */
-export declare class TimeoutError extends TransientError {
-}
 /** Any error thrown by CloudRoaring (any tier, any bundle). */
 export declare function isCloudRoaringError(err: unknown): err is CloudRoaringError;
 /** An OCC conditional write/delete lost the race — retry the read-modify-write, don't fail. */
 export declare function isWriteConflictError(err: unknown): err is WriteConflictError;
-/** A retryable transient infrastructure fault (incl. {@link TimeoutError}). The retry layer keys on this. */
+/** A retryable transient infrastructure fault. The retry layer keys on this. */
 export declare function isTransientError(err: unknown): err is TransientError;
 /** A requested object/row does not exist. */
 export declare function isNotFoundError(err: unknown): err is NotFoundError;

package/dist/core/generation-gc.d.ts

@@ -30,11 +30,14 @@ export declare function nextGeneration(ref: SegmentRef, deps: GenerationDeps): P
  * a pin taken while it was still active re-checks the status on every open — and nothing else in the library
  * would ever collect them, so without this those objects are billed forever.
  *
- * **Throws {@link WriteConflictError} if the segment changed underneath the pass** — not to be confused with
- * the empty array it still returns when there was genuinely nothing to collect (no row at all, or no pointer
- * yet), which is why an empty array is not a receipt. The row is read before the listing and acted on after it, so a name that was purged and
+ * **Throws {@link WriteConflictError} when it cannot act on the row it read**: the row is gone when it is re-read,
+ * after the listing or before a delete; on an active segment, the pointer has fallen below the cutoff before a
+ * delete; on a `destroyed` segment, the row's token has changed. Not to be confused with the empty array it still
+ * returns when there was genuinely nothing to collect (no row at all, or no pointer yet), which is why an empty
+ * array is not a receipt. The row is read before the listing and acted on after it, so a name that was purged and
  * re-created in that window is a *different* segment wearing the same name, and its live object must not be
- * collected on the strength of the old row. Refusing is safe — the objects are not going anywhere and the next
+ * collected on the strength of the old row: on an active segment the lower of the two pointers is what keeps it
+ * safe, and on a `destroyed` one the token. Refusing is safe — the objects are not going anywhere and the next
  * pass reads a consistent row — but it has to be **distinguishable** from "there was nothing to collect", which
  * an empty array is not: `eraseIdFromSegment` reads the returned list as the physical half of its erasure
  * receipt, and would otherwise report `erased: true` over bytes still in the bucket. Re-run it.
@@ -45,7 +48,8 @@ export declare function nextGeneration(ref: SegmentRef, deps: GenerationDeps): P
  * residual, and this is what eventually collects it from the retention sweep.
  *
  * `keep: 0` is how a subject-erasure rewrite makes a bit **physically** gone on return: the generation that held
- * it is collected the moment the rewrite is current. A reader pinned to it re-resolves on its next read.
+ * it is collected the moment the rewrite is current. A live read still fetching from it heals forward to the
+ * rewrite, and a pin of it (`seg.pin()`) fails with `NotFoundError` for any chunk it has yet to read.
  */
 export declare function gcOrphanGenerations(ref: SegmentRef, deps: GenerationDeps, options?: {
     keep?: number;

package/dist/core/keys.d.ts

@@ -3,14 +3,14 @@ export declare function segmentKey(ref: SegmentRef): string;
 export declare function segmentPrefix(ref: SegmentRef): string;
 export declare function chunkRefKey(ref: ChunkRef): string;
 /**
- * CACHE-cache key for a chunk scoped to a specific **version** of the segment — {@link chunkRefKey} plus that
+ * Cache key for a chunk scoped to a specific **version** of the segment — {@link chunkRefKey} plus that
  * version (space-delimited, injection-proof exactly as above — the name parts are already encoded). A publish bumps the version, so it naturally
  * misses the cache instead of serving a stale superseded chunk, and the superseded entries age out under the
  * LRU ceiling (no active purge needed).
  *
  * `version` is whatever the Storage source reports as identifying the bytes a read will see — its
  * `currentVersion` where it has one, otherwise the bare generation number. **A generation number alone is not
- * an identity**: `nextGeneration` restarts at 0 once a registry row is purged and the bucket emptied, so a
+ * an identity**: a load's generation number restarts at 0 once a registry row is purged and the bucket emptied, so a
  * retired-and-re-created name serves different data at the same `currentGen`, and a key built on the number
  * hands the new incarnation the old one's decoded chunks.
  */

package/dist/core/load.d.ts

@@ -2,9 +2,10 @@
  * `loadSegment` — the loaded store's primary write path, as one call.
  *
  * A load is always the same four steps: take the next generation number, write one immutable object, move the
- * pointer, collect what the move superseded. Done by hand they are `nextGeneration` + `bulkLoadCrbmGeneration` +
- * `publishGeneration` + `gcOrphanGenerations`, and the step people leave out is the last one — so stores that
- * compose it themselves accumulate superseded generations they keep paying for. Composing it here is the point.
+ * pointer, collect what the move superseded. Inside the library each is its own internal function, and the
+ * step a hand-composed load leaves out is the last one, so a store that composed it would accumulate superseded
+ * generations it keeps paying for.
+ * Composing it here, once, is the point.
  *
  * The other reason it is one call is the **guard**. A load REPLACES a segment: whatever the stream contains is
  * what the segment contains afterwards. That makes an upstream query returning fewer rows than usual — or none —
@@ -14,10 +15,12 @@
  *
  * Refusing therefore has to clean up after itself. The object is already durable at that point, and it sits
  * ABOVE `currentGen`, where generation collection deliberately never looks (it deletes strictly below the
- * pointer). Nothing else would ever reclaim it, so a refused load deletes its own object before returning.
+ * pointer), so a refused load deletes its own object before returning, while the segment's row is unchanged or
+ * gone. Once another write has changed the row, the object's number may name a re-created segment's live object,
+ * so it stays, and collection takes it like any other generation once one above it is current.
  */
 import { type IAuditSink } from './audit.js';
-import type { CodecInterface } from './codec.js';
+import { type CodecInterface } from './codec.js';
 import type { Clock } from './determinism.js';
 import type { IKeystore } from './crypto.js';
 import type { IStorageDriver, IRegistryDriver, SegmentRef } from './ports.js';
@@ -59,19 +62,35 @@ export interface LoadOptions {
     readonly allowEmpty?: boolean;
     readonly guard?: LoadGuard;
     /**
-     * Generations to keep below the new pointer as a grace window (default 1). Keep at least one: a read that is
+     * Generations to keep below the new pointer as a grace window (default 1). A non-negative integer: anything
+     * else (negative, fractional, `NaN`, infinite) throws `ValidationError` before anything is written. Keep at
+     * least one: a read that is
      * still fetching chunks from the just-superseded generation would otherwise have it deleted out from under it
-     * and pay a re-resolve. A wider window costs storage and buys nothing a pinned read would not do better.
+     * and pay a re-resolve. A wider window costs storage, and it is what a pinned handle needs: a pin is never
+     * re-resolved, so a chunk a pinned read has not fetched fails with `NotFoundError` once its generation is
+     * collected. Keep at least one generation for every one that can be written above the pinned one while your
+     * longest pinned job runs, on every writer that loads the segment — see "Generations and `keep`" in the loading
+     * guide.
      */
     readonly keep?: number;
     readonly audit?: IAuditSink;
 }
 /** Why a load did not become current. */
 export type LoadRefusal = 'empty' | 'min-cardinality' | 'min-retained'
-/** Another writer published a higher generation first. The object was written, then removed. */
+/**
+ * Another writer got there first. Either another load wrote the same generation number first, so the write-once
+ * put refused this one and it wrote nothing (`size: 0`); or the segment's registry row changed while the load was
+ * writing: another load published, a retention change, a rollback or an erasure wrote the row, or the row was
+ * deleted. Once another write has changed the row, the object stays in the bucket, because its generation number
+ * may by then name another incarnation's live object; once the row is gone, the object is deleted.
+ */
  | 'superseded';
 export interface LoadResult {
-    /** The generation written. Present even when refused — it is what was deleted again. */
+    /**
+     * The generation written. Present even when refused: a refusal deletes that object while the segment's row is
+     * unchanged or gone, and leaves it in the bucket once another write has changed the row. A load that lost its
+     * generation number to another wrote nothing, and reports `size: 0`.
+     */
     readonly generation: number;
     /** Whether this generation is now the segment's current one. */
     readonly published: boolean;

package/dist/core/metrics.d.ts

@@ -11,8 +11,8 @@
  * Two caveats for sink authors: `onEvent` runs **synchronously on the I/O path**, so keep it cheap and
  * non-blocking (offload batching/network to your own async queue); and `segment`/`namespace` are
  * caller-controlled strings that may be PII and are **unbounded-cardinality** — do not map them to
- * per-series metric labels unless they're known low-cardinality and PII-free. See the getting-started
- * "Observability" section.
+ * per-series metric labels unless they're known low-cardinality and PII-free. See the observability
+ * guide.
  */
 /** The segment operations that emit an `op` latency event (timed with the injected clock, at the facade). */
 export type MetricOpName = 'has' | 'count' | 'intersectInto' | 'unionInto' | 'andNotInto';
@@ -46,8 +46,7 @@ export type MetricEvent = {
 } | {
     readonly kind: 'intersect';
     /**
-     * Which chunk-aligned combine this was. **Optional for backward compatibility** — absent means
-     * `'intersect'`, which is all this event reported before `union`/`andNot` existed.
+     * Which chunk-aligned combine this was. **Optional** — absent means `'intersect'`.
      *
      * For `'union'` over its *include* operands alone, `skippedChunks` is 0 by construction — union reads
      * every chunk of every operand, so there is nothing to prune. It can still be non-zero when a union
@@ -69,6 +68,11 @@ export type MetricEvent = {
     /**
      * **Distinct** chunk-keys pruned — never fetched (the chunk-skipping saving). Counts distinct keys,
      * not per-operand GETs, so it under-states the true GET saving when 3+ operands partially overlap.
+     *
+     * On a read bounded by `after` / `through`, this and `fetchedChunks` count only the keys inside the range:
+     * the keys outside it are never considered, so they are not counted as pruned either. Both count the keys the
+     * call would fetch if read to the end, so a page that stops early reports every key up to `through`, or to the
+     * end of the segment when `through` is left out.
      */
     readonly skippedChunks: number;
 } | {

package/dist/core/name-codec.d.ts

@@ -5,15 +5,12 @@
  * `node:` builtin — and because `validate.ts` needs it to measure a name against the key budget. Core may
  * not import a driver (invariant 7), and a driver may import core, so this is the only layer both can see.
  *
- * The old grammar was an allowlist — `[A-Za-z0-9._:-]`. Widening it one character at a time is what exposed the
- * real problem: the colon had been missing from it by accident rather than by decision, and nothing in the
- * process would have caught the next omission either. An allowlist rejects names for the storage layer's
- * convenience, and the storage layer's convenience is the library's job, not the caller's. So a name is **any
- * non-empty string**, and each physical boundary escapes what *it* cannot take literally.
- *
- * It also fixes a hazard the allowlist *permitted*: `con`, `nul` and `com1` are Windows device names that
- * validated cleanly and failed only on a user's machine. A grammar can be both too narrow and too permissive
- * at once, which is the argument against having one.
+ * A name is **any non-empty string**, and each physical boundary escapes what *it* cannot take literally. An
+ * allowlist of characters would reject names for the storage layer's convenience, and the storage layer's
+ * convenience is the library's job, not the caller's. It would also let through the names that are actually
+ * dangerous: `con`, `nul` and `com1` are Windows device names made only of letters and digits, which pass any
+ * allowlist and fail only on a user's machine. A grammar can be both too narrow and too permissive at once,
+ * which is the argument against having one.
  *
  * Percent-encoding, because it is the one escape everybody already reads. `%` escapes itself as `%25` and is
  * encoded **first**, which is what makes the transform injective: every `%` in an encoded string starts an
@@ -22,36 +19,30 @@
  * There are two alphabets, because the boundaries differ:
  *
  * - **Object keys** (S3, GCS, Azure Blob) take almost anything. They need `/` escaped so a name cannot
- *   invent hierarchy or break a key parser that splits on it, `#` and `|` (see below), and control characters
- *   because they are not legal in the XML an S3 LIST returns.
+ *   invent hierarchy or break a key parser that splits on it, and control characters because they are not
+ *   legal in the XML an S3 LIST returns. Every other character outside `[A-Za-z0-9._:-]` is escaped as well.
  * - **Filesystem paths** need all of that plus `:` (an NTFS alternate-data-stream separator, where a write can
  *   *succeed* while `readdir` never lists the result), plus three hazards that are about the component as a
  *   whole rather than its characters — see {@link encodeNameForPath}.
  *
- * **`#` and `|` are escaped for compatibility, not for any backend still here.** They were reserved because
- * the DynamoDB registry composed its partition key from `<namespace>#<segment>|…`, and that driver is gone.
- * The escaping stays anyway: it is baked into every key already written, and un-reserving the two characters
- * would change what `encodeNameForKey` emits for a name containing either — silently moving those segments
- * to a key nothing looks up. A cheap two-character reservation is the right price for not migrating a
- * bucket; the property test below pins it.
+ * **The key alphabet is fixed for good.** Adding a character to it would change what `encodeNameForKey` emits
+ * for every name containing that character, silently moving those segments to keys nothing looks up. A test pins
+ * it, one printable ASCII character at a time.
  *
- * **Every name that was legal before encodes to itself on the OBJECT-KEY alphabet** — so S3, GCS and Azure
- * keys are byte-identical and there is nothing to migrate there. That is the property to preserve if this
- * file is ever edited, and a property test asserts it over the whole old grammar.
+ * **A plain name encodes to itself on the OBJECT-KEY alphabet** — one made only of `[A-Za-z0-9._:-]` that
+ * starts with a letter or digit — so S3, GCS and Azure keys read as the names that made them. That is the
+ * property to preserve if this file is ever edited, and a property test asserts it over every plain name.
  *
- * The **path** alphabet is not identical, and the difference is a breaking change for an existing LocalFs
- * store. Two classes move: a Windows device-name stem (`con`, `nul`, `com1`, `con.backup`) and a trailing dot
- * (`a.`). Both were legal before and are escaped now — deliberately, since both silently alias or fail on
- * Windows — but a 0.9 store holding one will not find it after the upgrade, because the readers' round-trip
- * guard skips a spelling the driver would never have written. See the upgrade note in `CHANGELOG.md`.
+ * The **path** alphabet escapes more. Besides `:`, two classes of plain name are escaped on a path: a Windows
+ * device-name stem (`con`, `nul`, `com1`, `con.backup`) and a trailing dot (`a.`), since both silently alias
+ * or fail on Windows.
  */
 /**
  * Encode a name for use inside an **object key** (S3, GCS, Azure Blob).
  *
- * Leaves the historically-legal alphabet literal so existing keys do not move, and escapes everything else —
- * including `/` (which would invent hierarchy and break a parser that splits on it), `#` and `|` (reserved by
- * the former DynamoDB registry and kept reserved so existing keys stay valid), and control characters (not
- * legal in S3's XML responses).
+ * Leaves `[A-Za-z0-9._:-]` literal, except a leading `_` and a name that is only `.` or `..`, so a plain name
+ * reads as itself, and escapes everything else — including `/` (which would invent hierarchy and break a parser
+ * that splits on it) and control characters (not legal in S3's XML responses).
  */
 export declare function encodeNameForKey(name: string): string;
 /** Inverse of {@link encodeNameForKey}. */
@@ -66,8 +57,7 @@ export declare function decodeNameFromKey(encoded: string): string;
  * 1. **`.` and `..`** are traversal. `join(root, '..')` leaves the storage root.
  * 2. **Windows reserved device names** — `CON`, `PRN`, `AUX`, `NUL`, `COM1`–`COM9`, `LPT1`–`LPT9`, case
  *    insensitive and *with or without an extension*, so `con.0.crbm` is reserved too. Opening one addresses a
- *    device rather than a file. Note the old grammar **permitted** these: `store.segment('con')` validated
- *    cleanly and broke only on a user's Windows box.
+ *    device rather than a file, so `store.segment('con')` would break only on a user's Windows box.
  * 3. **A trailing `.` or space**, which Windows silently strips — so `a.` and `a` would become the same
  *    directory, quietly merging two segments.
  *