@cloudbitmaps/core 0.9.0 → 0.11.0

package/dist/core/determinism.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The determinism seam.
+ *
+ * `core/` is a pure function of its inputs + injected dependencies — it never reaches for
+ * ambient time or randomness. Production wiring supplies real implementations; the deterministic
+ * tests supply controlled, seeded ones, so any run can be replayed exactly from a seed.
+ *
+ * These are interfaces only: the seam the whole library depends on for reproducibility. Every module that
+ * needs time, randomness or a yield takes one of these rather than reaching for a global.
+ */
+/** Injected time source. `core/` must never call `Date.now()` directly. */
+export interface Clock {
+    /** Milliseconds since the Unix epoch. */
+    now(): number;
+    /**
+     * Resolve after at least `ms` have elapsed. The retry/backoff path's only way to wait — `core/` must
+     * never reach for `setTimeout` directly (it's timer-free, lint-enforced). Production wiring supplies a
+     * `setTimeout`-backed implementation; a test supplies a virtual-time one so a backoff schedule is
+     * replayable. `ms <= 0` resolves on a microtask without scheduling a timer.
+     */
+    sleep(ms: number): Promise<void>;
+    /**
+     * Hand the event loop back once, without asking for any elapsed time.
+     *
+     * This is **not** `sleep(0)`, and the difference is the reason the member exists. `sleep(0)` resolves on a
+     * microtask, and microtasks drain before the loop advances a phase — so awaiting it inside a CPU-bound loop
+     * yields to nothing at all, and a co-resident server stays blocked for the loop's full duration. A real yield
+     * needs a macrotask. `sleep(1)` is one, but it buys the relief at ~1 ms of dead wall-clock per yield.
+     *
+     * **Optional**, so a minimal `Clock` — `now` and `sleep` alone — still satisfies the interface. Callers must
+     * therefore degrade rather than assume: `clock.yieldNow?.() ?? clock.sleep(1)` — correct on any clock, cheap
+     * on one that implements this. `core/` cannot supply it itself (it is timer-free, lint-enforced); production
+     * wiring backs it with `setImmediate`, and a test can make it a no-op so virtual time is not perturbed
+     * by what is purely a scheduling courtesy.
+     */
+    yieldNow?(): Promise<void>;
+}
+/** Injected randomness. `core/` must never call `Math.random()` directly. Seedable for simulation. */
+export interface Rng {
+    /** A float in the half-open interval [0, 1). */
+    next(): number;
+}

package/dist/core/discover.d.ts

@@ -0,0 +1,77 @@
+/**
+ * `segmentExists` and `listSegments` — ask the registry what is there.
+ *
+ * The registry has always known which segments exist; it is what `checkConsistency`, the retention sweep and
+ * `exportSegments` each enumerate. It was simply never exposed, so a user asking "do I already have this?" had
+ * to infer it: `count()` returns `0` for a segment that was never loaded AND for one loaded with no ids, and
+ * `generations()` costs a bucket listing to answer a question the pointer alone settles.
+ *
+ * Inferring it is the expensive kind of wrong. The alternative a user reaches for is keeping their own list of
+ * segment names alongside the store — a second source of truth, updated by hand, drifting from the first the
+ * moment a load fails halfway. The registry is already the list; these two functions read it.
+ */
+import type { IRegistryDriver, RegistryRecord, SegmentRef } from './ports.js';
+/** One segment the registry knows about. */
+export interface SegmentInfo extends SegmentRef {
+    /**
+     * The generation the **pointer names** — not what a read would resolve. On a `destroyed` tombstone this is
+     * still a number while reads answer empty, so read it together with {@link SegmentInfo.status} rather than
+     * alone. `null` means the row exists with no Storage generation yet.
+     */
+    readonly currentGen: number | null;
+    /**
+     * `destroyed` is a tombstone: the row stays so sweeps can still find it, and the generations are gone — on an
+     * encrypted segment the DEK wrappings went with them, which is what makes the bytes unrecoverable rather than
+     * merely deleted.
+     */
+    readonly status: RegistryRecord['status'];
+}
+/**
+ * Whether this segment's pointer resolves a generation — the question behind "does it already exist?".
+ *
+ * One registry point read, on every backend. Deliberately narrower than "is there a row": it is **false** for a
+ * row that exists with `currentGen: null` (a retention policy recorded ahead of the first load) and for a
+ * `destroyed` tombstone, because a read answers empty in both. The predicate mirrors generation resolution
+ * clause for clause, which is what keeps the two from disagreeing.
+ *
+ * It is NOT the same question as `count() > 0`. A segment loaded with no ids exists and counts zero — the
+ * distinction between "never loaded" and "loaded, and genuinely empty" is the one `count()` cannot make and
+ * the main reason this function is worth having.
+ *
+ * Two states answer `true` where a read still gives you nothing, and neither is this call's job to detect: a
+ * **torn restore** (`missing-storage-generation` — a live pointer whose object was deleted) makes reads *throw*
+ * `NotFoundError` rather than answer empty, and `runConsistencyCheck` is the call that looks for it; and a
+ * handle carrying an expired `expiresAt` reads as empty by a rule that lives on the handle, not on the row.
+ *
+ * Not a lock. A segment can be created or dropped between this call and whatever you do next; if the answer
+ * has to hold, use the fences that exist for it — `load`'s guard, or `expectFrom`/`expectToken` on a publish.
+ */
+export declare function segmentExists(ref: SegmentRef, registry: IRegistryDriver): Promise<boolean>;
+/**
+ * Every segment the registry holds, streamed — optionally scoped to one namespace.
+ *
+ * **This is an admin/discovery call, not a request-path one.** It is the registry's own enumeration — a paged
+ * LIST over the `registry/` prefix — so cost grows with the fleet, not with what you are looking for. The
+ * fleet-wide sweeps that *drain* it bound it (`maxScanSegments`); this one streams, so the bound is yours.
+ *
+ * **Scoping to a namespace narrows the LIST prefix**, so it really is the difference between reading one
+ * tenant and reading all of them.
+ *
+ * Streams, so a large fleet need not be held at once, and stopping the iteration stops the scan — as long as the
+ * registry driver's own `list` streams. One that collects its whole enumeration before yielding defeats both
+ * properties, since the scan is then paid for and resident before the first row reaches you, so a custom driver's
+ * `list` should yield each row as it reads it. The registry drivers this library ships all stream; on S3, GCS and
+ * Azure Blob the granularity is a page, so one LIST page and its in-flight row reads complete regardless. Nothing
+ * here retries the scan: a transient fault part-way through ends the iteration with that error, and calling
+ * `listSegments` again scans from the start, since the iterable one call returns is used up.
+ *
+ * Yields `destroyed` tombstones, and rows whose `currentGen` is `null`, because hiding either would make this
+ * disagree with the registry it reports on — a filtered enumeration that looks complete is how a retention
+ * sweep ends up permanently skipping rows nobody can see. Filter on `status`/`currentGen` yourself, or use
+ * {@link segmentExists} for the "does the pointer resolve" question. Internal bookkeeping rows are the one
+ * exclusion, and only on an unscoped scan: they are not segments, and a caller naming their namespace still
+ * sees them.
+ */
+export declare function listSegments(registry: IRegistryDriver, options?: {
+    namespace?: string;
+}): AsyncIterable<SegmentInfo>;

package/dist/core/due-index.d.ts

@@ -0,0 +1,53 @@
+import { MAX_NAME_LENGTH } from './validate.js';
+import type { RegistryRecord, SegmentRef } from './ports.js';
+/** Bucket width. One day: small enough that a cycle reads little, coarse enough that the index stays tiny. */
+export declare const DUE_BUCKET_MS = 86400000;
+/**
+ * The name-length cap, and an index row encodes **both** of the original ref's parts into one name — so a ref
+ * whose encoding would exceed it is simply not indexed (see {@link canIndex}).
+ *
+ * Re-exported from the validator rather than restated. The two were separate constants with the same value
+ * until the validator started measuring the **encoded** length; `canIndex` went on counting raw characters and
+ * began answering `true` for refs the registry then refused, turning a documented graceful degradation into a
+ * guaranteed throw on the retention fast path.
+ */
+export { MAX_NAME_LENGTH };
+/** Which bucket an expiry falls in. Total and reversible; no calendar, no timezone, no ambient time. */
+export declare function dueBucket(expiresAt: number): number;
+/** The namespace holding one bucket's pointers. */
+export declare function dueNamespace(bucket: number): string;
+/** Is this record a due-index pointer rather than a segment? */
+export declare function isDueIndexRow(record: Pick<RegistryRecord, 'namespace'>): boolean;
+/**
+ * Encode a ref into one index-row name, unambiguously.
+ *
+ * `${namespaceLength}.${namespace}${segment}` — a decimal length, a dot, then the two parts concatenated. The
+ * length prefix is what makes it reversible: a name may contain any character, the dot included, so no
+ * separator character could ever be unambiguous on its own. Reading the digits
+ * up to the first dot tells the parser exactly where the namespace ends.
+ */
+export declare function encodeDueName(ref: SegmentRef): string;
+/**
+ * Can this ref be indexed at all? False when the encoded name would exceed the 256-character name cap —
+ * possible only for a ref whose namespace and segment are together near the limit.
+ *
+ * **Not indexable is not "not retired".** The repair scan still sees the segment's own row, so the consequence
+ * is that it expires on the repair cadence instead of the fast one. Callers must not treat `false` as an error.
+ */
+export declare function canIndex(ref: SegmentRef): boolean;
+/** The registry ref of the pointer for `ref` in `bucket`. Throws if the ref cannot be encoded — check first. */
+export declare function dueIndexRef(bucket: number, ref: SegmentRef): SegmentRef;
+/**
+ * Recover the original ref from an index row's name. `null` for anything we did not write — a foreign row in
+ * the reserved namespace is ignored rather than acted upon.
+ */
+export declare function decodeDueName(name: string): SegmentRef | null;
+/**
+ * Which buckets a cycle must read at `now`: everything from `since` up to and including the current one.
+ *
+ * Past buckets are included because a sweep that did not run — a scaled-to-zero worker, a failed deploy, a
+ * paused schedule — must not leave its buckets stranded. `lookbackBuckets` bounds how far back a first run
+ * reaches, so a long outage costs a bounded number of list calls per cycle rather than one per day since the
+ * epoch; anything older is the repair scan's job.
+ */
+export declare function dueBucketsAt(now: number, lookbackBuckets: number): number[];

package/dist/core/engine.d.ts

@@ -0,0 +1,246 @@
+import type { CodecBitmap, CodecInterface } from './codec.js';
+import type { Budget, BudgetOption } from './budget.js';
+import type { Clock } from './determinism.js';
+import type { BoundedLru } from './lru.js';
+import type { IMetricsSink } from './metrics.js';
+import type { StorageChunkSource, SegmentRef, SegmentSize } from './ports.js';
+export interface EngineDeps {
+    readonly storage: StorageChunkSource;
+    /** Optional cache of decoded (immutable) Storage chunks. */
+    readonly cache?: BoundedLru<string, CodecBitmap>;
+    readonly maxBitmapBytes?: number;
+    /**
+     * The bitmap codec — **required**. `core/` is codec-agnostic: it can have no default, because the concrete codec
+     * lives in a *flavor* package that depends on core (a default here would invert that arrow). A flavor's facade
+     * injects it — `@cloudbitmaps/roaring` passes the roaring codec — so applications never see this.
+     */
+    readonly codec: CodecInterface;
+    /** Time source for the `storage.get` latency metric only; defaults to a clock that reads 0. */
+    readonly clock?: Pick<Clock, 'now'>;
+    /** Observability sink; defaults to a no-op. Assumed exception-safe (the facade wraps it). */
+    readonly metrics?: IMetricsSink;
+    /**
+     * Per-op denial-of-wallet budget, already resolved by the facade: a {@link Budget} to enforce, or `null` to
+     * disable. Undefined ⇒ {@link DEFAULT_BUDGET} (a direct engine construction still gets the generous default).
+     * Read ops refuse before fan-out if they'd exceed it.
+     */
+    readonly budget?: Budget | null;
+}
+/**
+ * A range of ids for a read to yield: those greater than `after` and no greater than `through`, `(after, through]`.
+ *
+ * Built for keyset paging: `after` is the last id the caller already has, `through` the end of its window. Each is
+ * optional: left out, the read starts at the first id or runs to the last. Each is an integer in `0..4294967295`, or
+ * the read throws {@link ValidationError} when it is first read. `after >= through` is an empty range, not an error,
+ * because a cursor that has reached the end of its window is normal; an empty range reads nothing, not even whether
+ * a combine's operands exist.
+ *
+ * A read with a range fetches only the chunks the range overlaps, on a combine for every operand and every
+ * `exclude`. The per-op budget is charged once, before the first fetch, for every chunk in the range, so with
+ * `after` alone it is charged to the end of the segment however early the caller stops; pass `through` to bound it.
+ */
+export interface IdRange {
+    /** Exclusive lower bound: the read yields only ids greater than this. */
+    readonly after?: number | undefined;
+    /** Inclusive upper bound: the read yields only ids up to and including this. */
+    readonly through?: number | undefined;
+}
+/** Options common to the chunk-aligned combines. */
+export interface CombineOptions extends IdRange {
+    /** Max chunk keys resolved concurrently — bounds the Storage footprint. A positive integer. */
+    readonly concurrency?: number;
+    /** Override the store's per-op budget for this call (`false` lifts it). */
+    readonly budget?: BudgetOption;
+    /** Segments whose ids are subtracted from the result. */
+    readonly exclude?: readonly SegmentRef[];
+    /**
+     * Allow an operand that names a segment which does not exist. Default `false` — a combine refuses one,
+     * because a misspelled or mis-namespaced operand is indistinguishable from a correct one in the result.
+     * Set `true` when you genuinely intend to combine against a name that may not have been created yet.
+     */
+    readonly allowAbsentOperands?: boolean;
+}
+export declare class SegmentEngine {
+    private readonly storage;
+    private readonly cache;
+    private readonly codec;
+    private readonly maxBitmapBytes;
+    private readonly clock;
+    private readonly metrics;
+    private readonly metricsOn;
+    /** Resolved per-op budget (null = disabled); undefined deps ⇒ the generous default. */
+    private readonly budget;
+    constructor(deps: EngineDeps);
+    /** Membership: one chunk lookup — the cache, else one Storage fetch of that chunk. */
+    has(seg: SegmentRef, id: number): Promise<boolean>;
+    /**
+     * Cardinality. When the Storage source can serve per-chunk cardinality from its `.crbm` index (the `.crbm`
+     * source can), the count is summed from the index with **zero payload reads**. A source without that
+     * capability (the in-memory source) falls back to fetching every chunk.
+     *
+     * The index sum is trusted, not confirmed: the reader checked the index for internal consistency when it opened
+     * the object, and a corrupt index that is still internally consistent yields a wrong count. `iterate()` and the
+     * combines decode the payloads.
+     */
+    count(seg: SegmentRef): Promise<number>;
+    /** Whether the Storage source can measure segment size (for grounded cost); false ⇒ storage isn't grounded. */
+    get supportsStorageSize(): boolean;
+    /** How often the Storage source re-reads a pointer while reading (cost reporting); undefined if it does not say. */
+    get pointerRefreshMs(): number | undefined;
+    /** Grounded Storage size of a segment's current generation (cost reporting), or null if it has no generation. */
+    segmentSize(seg: SegmentRef): Promise<SegmentSize | null>;
+    /**
+     * Every id, ascending, one chunk at a time; with `range`, only the ids in `(after, through]`, fetching only the
+     * chunks the range overlaps (see {@link IdRange}).
+     *
+     * Two generators, not one with a branch: a second `yield` site in the full read's generator grows its frame, and
+     * every id of a read that asked for no range paid for it (measured at about 5% per id). The full read keeps the
+     * loop it always had.
+     */
+    iterate(seg: SegmentRef, range?: IdRange): AsyncGenerator<number>;
+    private iterateAll;
+    private iterateRange;
+    /**
+     * `segs[0] ∩ segs[1] ∩ …`, minus every id in `options.exclude` — streamed ascending.
+     *
+     * The `exclude` operands are what make suppression **compose without materialising**. Applying suppression
+     * afterwards (intersect into a temp segment, then subtract) writes an intermediate segment that nobody wants;
+     * applying it here folds it into the same chunk-aligned pass. It is also cheaper than it looks: an exclude
+     * operand is read **only at the keys that survived the intersection** — the cost is bounded by the
+     * audience's surviving key count and **never scales with the size of the suppression list**. Subtracting a
+     * 61,000-chunk global opt-out list costs at most one read per surviving key, not 61,000.
+     *
+     * ---
+     *
+     * Chunk-skipping intersection. Aligns each segment's chunk-key set (read from the `.crbm` index, no payload),
+     * keeps only keys present in **all** operands (a key missing from any operand can't contribute → its Storage
+     * chunks are never fetched — the core saving), then for each surviving key fetches the operands' chunks in
+     * parallel and hands them to the codec for the AND, streaming results through a bounded in-flight window.
+     *
+     * **Memory:** the Storage payload footprint is bounded by the window (`concurrency × operands × chunk`), not by
+     * segment size — that's the Lambda-friendly property.
+     *
+     * Generation-consistent within the call (normal case): each operand's current generation is resolved **once**
+     * up front (before the fan-out) and threaded into every chunk read, so a concurrent load can't corrupt or tear
+     * the result — every chunk read is a whole, checksum-verified, immutable generation. The edge a *long* call can
+     * hit is invariant 3's: if it straddles a mid-call `cache.genTtlMs` boundary and a load has published, an
+     * operand's not-yet-read chunks may re-resolve forward to the newer generation (a generation hop within one long
+     * call) — the call never crashes or returns a torn object, but may mix generations. Three things hop it without
+     * waiting for the TTL, so a shorter call can meet them too: **the reader cache evicting an operand mid-call**
+     * (`maxOpenSegments`), whose re-read re-resolves fresh; a sweep deleting the generation it was reading, which
+     * heals the read forward; and an invalidation, which this store's own `load`, `rollback` and `eraseSubject` make
+     * and `invalidate()` makes on request. Still whole/immutable per read, never torn.
+     */
+    intersect(segs: readonly SegmentRef[], options?: CombineOptions): AsyncGenerator<number>;
+    /**
+     * `segs[0] ∪ segs[1] ∪ …`, minus every id in `options.exclude` — streamed ascending.
+     *
+     * **Union is the one composite read with no chunk-skipping**, and that is a property of the operation rather
+     * than of this implementation: an id in *any* operand belongs to the result, so every chunk of every operand
+     * has to be read. `intersect` can prune a key absent from any operand; union cannot prune anything. It is
+     * budgeted exactly like `intersect` so a wide union is refused rather than quietly billed.
+     */
+    union(segs: readonly SegmentRef[], options?: CombineOptions): AsyncGenerator<number>;
+    /**
+     * `seg \ (excludes[0] ∪ excludes[1] ∪ …)` — streamed ascending. Suppression on its own.
+     *
+     * Reads every chunk of `seg` (any of them may survive) but each exclude **only where it overlaps `seg`**, so
+     * the cost scales with the segment being filtered rather than with the size of the suppression list.
+     */
+    andNot(seg: SegmentRef, excludes: readonly SegmentRef[], options?: Omit<CombineOptions, 'exclude'>): AsyncGenerator<number>;
+    private combine;
+    /**
+     * The AND (or OR) of one chunk key across all operands, minus the excludes that hold it, or `null` if empty.
+     * Operand chunks are fetched **in parallel** (the spec's parallel byte-range reads).
+     *
+     * The accumulator is a **clone** of the first operand's chunk, and that clone is load-bearing: every other
+     * bitmap here is the cached, shared Storage instance and must never be mutated, or the cache is poisoned for
+     * every later reader. The remaining operands and the excludes are only *read* by the in-place ops, so they are
+     * used as-is — one clone per key, not one per operand.
+     */
+    private combineChunk;
+    /** The segment's chunk keys, ascending — a shape read off the index, no payload. Keys are untrusted (invariant 5). */
+    private chunkKeys;
+    /**
+     * Tier-derived keys are untrusted (invariant 5) — fail fast on a corrupt/out-of-range key rather than
+     * letting it flow into the id-routing step and produce a bogus id.
+     */
+    private assertChunkKeyInRange;
+    /**
+     * The other half of invariant 5: a chunk payload holds **remainders** — 16-bit offsets within one chunk — so
+     * every value must be `<= 0xffff`.
+     *
+     * Nothing upstream establishes that. The byte cap bounds *size*, and CRC/AEAD prove the bytes are the bytes
+     * that were written — which anyone able to write the bucket satisfies trivially. A value `>= 65536` would then
+     * reach the id-routing step, which masks it (`remainder & 0xffff`) and emits a **fabricated id belonging to a different
+     * chunk's id space**: indistinguishable from real data, inflating `count()` and creating spurious `intersect`
+     * matches.
+     *
+     * Costs one `maximum()` per chunk, not per id — `maximum` is optional on the codec seam precisely so a codec
+     * that cannot answer in O(1) opts out instead of making the read path walk every value.
+     *
+     * One value stands for all of them only because the decode is structurally checked. Roaring answers `maximum()`
+     * from its last container, so a payload listing its containers out of order would report the wrong one's
+     * largest value and pass here while holding values above 65,535. The codec's `safeDeserialize` refuses that
+     * payload, and every other shape that would make this answer wrong, before it reaches this check.
+     */
+    private assertChunkPayloadInRange;
+    /**
+     * Refuse a combine whose operand names a segment that was never created.
+     *
+     * A segment that resolves to nothing is ambiguous in a way that matters only here. Read it directly and
+     * "empty" is the right answer either way. Pass it as an **operand** and the two states diverge: a
+     * suppression list with nobody on it correctly suppresses nothing, while one whose namespace you omitted
+     * *silently* suppresses nothing — and the result is not empty and obviously wrong, it is the full audience
+     * and plausibly right. That direction is the dangerous one: the failure mode is mailing the people who
+     * opted out.
+     *
+     * The asymmetry is why this is checked rather than left to the caller. A mistyped **include** collapses an
+     * intersect to nothing, which you notice; a mistyped **exclude** removes a safeguard, which you do not. Both
+     * are refused, because both are wiring errors and one rule is easier to trust than two.
+     *
+     * **Costs nothing on a normal combine.** `exists` is consulted only for an operand that resolved to zero
+     * chunks — a segment with data is self-evidently registered — so the check is a registry read exactly when
+     * a combine was about to do something suspicious, and no reads at all otherwise. A source that cannot answer
+     * `exists` (it has no notion of registration) skips the check rather than guessing. An operand is judged by
+     * all its chunks, not those inside a range: one with nothing in range but data elsewhere is not suspicious.
+     */
+    private refuseAbsentOperands;
+    /**
+     * Drop every piece of state this engine derived from `ref`, and tell the Storage source to do the same.
+     *
+     * The decoded-chunk cache is keyed by generation, which handles a *publish* (the new generation misses) but
+     * not a *destruction*: a segment that was erased from, dropped, shredded or retired has no newer generation
+     * whose key would miss, so its decoded chunks stay resident and keep answering. That is why the erasing
+     * process itself could report `erased: true` and then still answer `true` for the same id, out of RAM, with
+     * no storage read to intercept.
+     *
+     * Called by the destructive verbs on the facade. Synchronous and best-effort — forgetting cannot fail.
+     */
+    invalidate(ref: SegmentRef): void;
+    /** The segment's current generation, resolved once per op (`undefined` ⇒ source can't report it). */
+    private currentGen;
+    /**
+     * The cache-key component identifying **which bytes** this op will read: the source's `currentVersion` when
+     * it has one, else the generation alone.
+     *
+     * The generation alone is not an identity. A load's generation number restarts at 0 once a row is purged
+     * and the bucket emptied, so a retired-and-re-created name serves different data at the same `currentGen` — and a
+     * decoded chunk cached under `(segment, chunk, 0)` is handed straight back to the new incarnation. That is an
+     * erased id reappearing with no read to intercept it, which is why this is keyed on the version rather than
+     * the number.
+     */
+    private cacheVersion;
+    /**
+     * Decode a Storage chunk. `gen` is the segment's current generation, resolved **once per op** by the caller (not
+     * per chunk — that would put a registry re-resolve on every chunk of a count/intersect). The cache is
+     * keyed by it, so a load that advances the generation misses the cache and re-reads the new bytes instead of
+     * serving a stale decoded chunk (an erased id can't resurrect from a cached superseded chunk). `gen === null`
+     * ⇒ the source reports no current generation ⇒ no storage bytes for any chunk, so skip the fetch entirely.
+     * `gen === undefined` ⇒ the source can't report a generation (it only ever serves one) ⇒ the key stays
+     * generation-free. Superseded-generation entries age out under the LRU ceiling — no active purge.
+     *
+     * The returned instance is **shared** (it may be the cached one): callers read it or clone it, never mutate it.
+     */
+    private storageChunk;
+}

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

@@ -0,0 +1,176 @@
+/**
+ * Subject erasure on a loaded segment (GDPR Art. 17): remove **one id** from a segment by rewriting its current
+ * generation without that id.
+ *
+ * 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 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.
+ *
+ * Concurrency. This is a **read-modify-write**, not a plain forward-only publish, and that distinction is where
+ * its correctness lives: the new generation is `from` minus one bit, so it is a valid successor to `from` and to
+ * nothing else. The publish is therefore fenced on `from` **and on the row it was read from**
+ * (`publishGeneration`'s `expectFrom` + `expectToken`) and lands only while the pointer is still exactly there,
+ * on that same row. Both halves are needed: a generation number identifies a generation only within one
+ * incarnation of a name, and a name that is retired and re-created restarts at `0`, so the number alone matched
+ * a different segment entirely. Anything else — a load that published in the meantime, or another
+ * erasure that got there first — is reported as `reason: 'superseded'`, `erased: false`, and the caller re-runs
+ * against the new generation. A writer that claims the same generation *number* first surfaces as a
+ * `WriteConflictError` (write-once).
+ *
+ * The same answer covers the read half, and for the same reason. An erasure collects with `keep: 0`, which takes
+ * every generation below its new pointer — so a racing erasure can delete the generation this call is streaming,
+ * and (once it is below the winner's pointer) the object this call just wrote. All three exposed round trips (the
+ * reader open, any chunk of the whole-segment rewrite, the verify) therefore report a *reason* rather than a bare
+ * `NotFoundError`, which was the same event wearing an unactionable face: through `eraseSubject` it became a note
+ * the facade documents as ambiguous about which side of the publish it landed on, telling an operator to triage
+ * where the truth was to re-run.
+ *
+ * Which reason comes from **re-reading the row**, not from assuming a supersession: a moved pointer is
+ * `'superseded'`, a tombstoned row `'destroyed'`, a purged row `'absent'`, a row with no pointer
+ * `'no-generation'`. A pointer still on `from` means the object it names is genuinely gone — the forbidden
+ * `missing-storage-generation` state — and that throws, because no re-run fixes it. That `NotFoundError` is the only
+ * signal of that state, so a faulting re-read rethrows it rather than replacing it with a transient-looking
+ * registry error.
+ *
+ * **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
+ * load's whole set, and letting two concurrent erasures each return `erased: true` while the second one's
+ * 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.
+ *
+ * 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';
+import type { Yielder } from './cooperative.js';
+import type { IKeystore } from './crypto.js';
+import type { IStorageDriver, IRegistryDriver, SegmentRef } from './ports.js';
+/** What {@link eraseIdFromSegment} needs: the objects, the pointer, the codec, and the key material if encrypted. */
+export interface EraseIdDeps {
+    readonly storage: IStorageDriver;
+    readonly registry: IRegistryDriver;
+    /**
+     * Bitmap codec — the rewrite decodes and re-encodes every chunk through it. Optional in the type so this stays
+     * call-compatible public API; a **flavor** package binds it (see {@link requireCodec}).
+     */
+    readonly codec?: CodecInterface;
+    /**
+     * Keystore for an **encrypted** segment: its registry record carries wrapped DEK(s), and the rewrite reuses
+     * that DEK — unwrapping it to decrypt the old generation and encrypt the new one under a `(segment, generation)`
+     * -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 a load offer). */
+    readonly requireEncryption?: boolean;
+    /** 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;
+}
+export interface EraseIdResult {
+    readonly segment: string;
+    readonly namespace?: string;
+    /**
+     * 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 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, 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 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 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`). A refused
+     * rewrite whose object sits above the winner's pointer deletes that object again before it returns.
+     */
+    readonly generation?: number;
+    /**
+     * 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.
+     *
+     * **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.
+     *
+     * 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.
+     *
+     * **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**: 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>;