@cloudbitmaps/core 0.22.0 → 0.23.0

package/dist/core/erasure.d.ts

@@ -1,33 +1,51 @@
 /**
  * Whole-segment erasure: crypto-shred (`destroySegment`, `eraseNamespace`) and disposal (`dropSegment`).
  *
- * GDPR "right to erasure" on immutable, backed-up storage: you can't delete a `.crbm` object from every
- * backup, but you can **delete its key**. `destroySegment` drops the segment's wrapped DEK(s) from the registry
- * (a CAS to a `destroyed` tombstone) — the encrypted Storage bytes are then permanently unreadable, everywhere,
- * forever. **Immediate + irreversible**, so it's gated behind an explicit confirmation (name the exact
- * 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.
+ * GDPR "right to erasure" on immutable, backed-up storage: you can't delete a `.crbm` object from every backup, but you
+ * can **delete its key**. `destroySegment` drops the segment's wrapped DEK(s) from its current registry row (a CAS to a
+ * `destroyed` tombstone). Every copy of the encrypted Storage bytes, backups and WORM copies included, is then
+ * unreadable once no retained copy of the row still holds the wrapped key (a noncurrent version, a backup or a
+ * point-in-time copy of the row), or once every KEK that wrapped it is destroyed; until then a registry restore to a
+ * point before the shred makes the segment readable again. **Immediate**, and it cannot be undone through the library
+ * (a registry restore to before it can), so it's gated behind an explicit confirmation (the
+ * segment's name; the namespace is not checked, so build the ref's `namespace` from a value you have checked). A `destroyed` segment reads as empty: no generation resolves through a destroyed row. Only an
+ * **encrypted** segment is crypto-shredded; a cleartext one has no key to shred, and `allowCleartext` tombstones it
+ * with its objects left readable.
  *
- * 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.
+ * 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.
  */
 import { type IAuditSink } from './audit.js';
 import type { ChurnDeps } from './leases.js';
 import type { IStorageDriver, IRegistryDriver, RegistryRecord, SegmentRef } from './ports.js';
+/**
+ * What the erasure calls need: the registry whose rows they tombstone, and, optionally, the clock and rng they wait out
+ * lease churn with.
+ */
 export interface EraseDeps extends ChurnDeps {
+    /** The registry holding the segments' rows. */
     readonly registry: IRegistryDriver;
 }
+/**
+ * What destroying one segment did: a crypto-shred, a cleartext tombstone (the bytes stay readable), nothing for a
+ * segment already destroyed or absent, or, with `destroyed: false` and a `reason`, a segment left as it was, which may
+ * still hold data. The result of `destroySegment`, and one entry of what `eraseNamespace` returns.
+ */
 export interface DestroyResult {
+    /** The segment's name. */
     readonly segment: string;
+    /** The segment's namespace, or `undefined` for the default one. */
     readonly namespace?: string;
     /** True iff the segment is now a `destroyed` tombstone (incl. the idempotent already-destroyed case). */
     readonly destroyed: boolean;
     /**
      * True iff **this call** performed a genuine crypto-shred — an encrypted segment whose wrapped DEK(s) were
-     * dropped, so its Storage bytes are now permanently unreadable. False for a cleartext tombstone (bytes remain
-     * readable), for the idempotent already-destroyed case, and for an absent segment. This is what the
-     * `segment.erase` audit event keys off — a cleartext "erase" is not an irreversible destruction.
+     * dropped from its current registry row, so its Storage bytes, in any copy, are unreadable once no retained copy
+     * of the row holds the key, or every KEK that wrapped it is destroyed. False for a cleartext tombstone (bytes
+     * remain readable), for the idempotent already-destroyed case, and for an absent segment. This is what the
+     * `segment.erase` audit event keys off — a cleartext "erase" destroys no key. A shred that throws `TransientError`
+     * after its read-back also failed may have landed; its re-run answers `'already'` with `cryptoShredded: false`.
      */
     readonly cryptoShredded: boolean;
     /**
@@ -38,14 +56,20 @@ export interface DestroyResult {
      *
      * The last two come with `destroyed: false` and mean **the segment still holds data**. A namespace erase
      * returns them rather than throwing, so its entries have to be inspected — see {@link eraseNamespace}.
+     *
+     * A shred that throws `TransientError` after its read-back also failed may have landed; its re-run answers
+     * `'already'` with `cryptoShredded: false`.
      */
     readonly reason?: string;
 }
 /**
- * Crypto-shred one segment. **Irreversible.** `confirmSegment` must equal `ref.segment` (a guard against an
- * accidental destroy — you must name the exact segment). A non-encrypted segment is rejected unless you opt in
- * via `allowCleartext` (there's no key to shred; its Storage bytes stay readable — the tombstone only stops the
- * segment resolving).
+ * Crypto-shred one segment. It cannot be undone through the library (a registry restore to a point before it can).
+ * `confirmSegment` must equal `ref.segment` (a guard against an accidental destroy of another name; it checks the
+ * name only, not the namespace, so build the ref's `namespace` from a value you have checked). A non-encrypted segment is rejected unless you opt in via `allowCleartext` (there's no key to shred; its
+ * Storage bytes stay readable — the tombstone only stops the segment resolving).
+ *
+ * The options are `confirmSegment`, `allowCleartext` and `audit`. Any other key (`dryRun`, which this call does not
+ * take, included) and an `allowCleartext` that is not a boolean throw `ValidationError` before the registry is read.
  */
 export declare function destroySegment(ref: SegmentRef, deps: EraseDeps, options: {
     confirmSegment: string;
@@ -53,14 +77,16 @@ export declare function destroySegment(ref: SegmentRef, deps: EraseDeps, options
     audit?: IAuditSink;
 }): Promise<DestroyResult>;
 /**
- * Crypto-shred every segment in a namespace. **Irreversible.** `confirmNamespace` must equal `namespace`.
- * Returns a per-segment result (skips cleartext segments unless `allowCleartext`).
+ * Crypto-shred every segment in a namespace. It cannot be undone through the library (a registry restore to a point
+ * before it can). `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 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 safe whole number of at least 1 throws `ValidationError`, again before anything is destroyed.
+ * So does any option it does not take (`dryRun` included) and an `allowCleartext` that is not a boolean.
  */
 export declare function eraseNamespace(namespace: string, deps: EraseDeps, options: {
     confirmNamespace: string;
@@ -76,8 +102,11 @@ export declare function eraseNamespace(namespace: string, deps: EraseDeps, optio
 export interface DropDeps extends EraseDeps {
     readonly storage: IStorageDriver;
 }
+/** What `dropSegment` did to one segment, or, on a dry run, would do. */
 export interface DropResult {
+    /** The segment's name. */
     readonly segment: string;
+    /** The segment's namespace, or `undefined` for the default one. */
     readonly namespace?: string;
     /**
      * **True iff this segment is now empty as a result of this call — or already was.** This is the field a
@@ -111,14 +140,16 @@ export interface DropResult {
     readonly wouldDelete?: readonly number[];
     /**
      * On a dry run, whether the real drop would **also** crypto-shred (i.e. the segment is encrypted).
-     * `undefined` on a real run. This is the one fact in the preview that is irreversible *everywhere*, backups
-     * included — a dry run that did not surface it was previewing the recoverable half only.
+     * `undefined` on a real run. This is the one fact in the preview that reaches every copy of the objects, backups
+     * and WORM copies included (once no retained copy of the row holds the key, or every KEK that wrapped it is
+     * destroyed) — a dry run that did not surface it would preview the recoverable half only.
      */
     readonly wouldCryptoShred?: boolean;
     /**
-     * True iff the segment was encrypted and its wrapped DEK(s) were dropped as part of this call — so its bytes
-     * are unreadable *everywhere*, backups included, not merely deleted from the bucket. Deleting an object does
-     * not reach a noncurrent version, a replica, or a PITR snapshot; discarding the key does.
+     * True iff the segment was encrypted and its wrapped DEK(s) were dropped from its current registry row as part of
+     * this call — so its bytes are unreadable in every copy, backups included, once no retained copy of the row holds
+     * the key or every KEK that wrapped it is destroyed, not merely deleted from the bucket. Deleting an object does
+     * not reach a noncurrent version, a replica, or a PITR snapshot; removing the key does, on those terms.
      */
     readonly cryptoShredded: boolean;
     /**
@@ -133,14 +164,17 @@ export interface DropResult {
     readonly reason?: string;
 }
 /**
- * **Dispose of a segment: tombstone it, then delete its Storage objects.** Irreversible.
+ * **Dispose of a segment: tombstone it, then delete its Storage objects.** It cannot be undone through the library
+ * (a restore from the registry's and the bucket's versions or backups can).
  *
  * WHY THIS EXISTS, given {@link destroySegment} already erases. Because `destroySegment` answers a *compliance*
  * question and this one answers an *operational* question, and they are not the same:
  *
- * - `destroySegment` **crypto-shreds** — it discards the key so the bytes are unreadable everywhere including
- *   immutable backups, which is the only erasure that survives WORM. But it **leaves the objects in the
- *   bucket**, still billed, and it *requires* encryption because a cleartext segment has no key to discard.
+ * - `destroySegment` **crypto-shreds** — it removes the key from the segment's current registry row, so the bytes
+ *   are unreadable everywhere, immutable backups included, once no retained copy of the row holds the key or every
+ *   KEK that wrapped it is destroyed: the only erasure that reaches WORM copies of the objects. But it **leaves the
+ *   objects in the bucket**, still billed, and it *requires* encryption because a cleartext segment has no key to
+ *   discard.
  * - `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.
  *

package/dist/core/errors.d.ts

@@ -24,6 +24,7 @@ declare const TRANSIENT_BRAND: unique symbol;
 export declare class CloudRoaringError extends Error {
     /** Cross-bundle brand — see {@link errorKind}. Non-enumerable-ish (symbol key ⇒ not in JSON). */
     readonly [ERROR_BRAND]: true;
+    /** Builds the error from `message`, and sets `name` to the class's name as written. */
     constructor(message: string);
 }
 /**
@@ -59,6 +60,7 @@ export declare class LeaseExpiredError extends CloudRoaringError {
     readonly until: number;
     /** `'expired'` when the clock reached `until`, `'released'` after `release()`. */
     readonly reason: 'expired' | 'released';
+    /** Builds the error from its `message`, the epoch-ms the lease ran until, and why it ended. */
     constructor(message: string, until: number, reason: 'expired' | 'released');
 }
 /**
@@ -75,11 +77,13 @@ export declare class LeaseLimitError extends CloudRoaringError {
  * `'stale-operand'`. Deterministic: run the call again against the current operand.
  */
 export declare class StaleOperandError extends CloudRoaringError {
+    /** The stable code `'stale-operand'`, to match on. */
     readonly code: "stale-operand";
     /** The operand's name in the call that found it stale. */
     readonly operand: string;
     /** Why it is stale. */
     readonly reason: 'moved' | 'erased';
+    /** Builds the error from its `message`, the operand's name and why it is stale. */
     constructor(message: string, operand: string, reason: 'moved' | 'erased');
 }
 /**
@@ -134,6 +138,7 @@ export declare class BudgetExceededError extends CloudRoaringError {
      * lower bound on the resident bytes it needs (`'maxBufferedBytes'`), or `limit + 1` (`'maxScanSegments'`).
      */
     readonly spent: number;
+    /** Builds the error from its `message` and the `option`, `limit` and `spent` it reports. */
     constructor(message: string, details: {
         readonly option: 'budget.maxRequests' | 'maxBufferedBytes' | 'maxScanSegments';
         readonly limit: number;
@@ -166,6 +171,7 @@ export declare class KeyUnavailableError extends CloudRoaringError {
 export declare class TransientError extends CloudRoaringError {
     /** A second brand so a transient fault is classifiable cross-bundle. */
     readonly [TRANSIENT_BRAND]: true;
+    /** Builds the error from `message`; `options.cause`, when given, is kept as `cause`. */
     constructor(message: string, options?: {
         cause?: unknown;
     });
@@ -174,6 +180,30 @@ export declare class TransientError extends CloudRoaringError {
 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 {@link WriteConflictError} for a registry `create` or `compareAndSwap` that may have landed before it met the
+ * conflict, so the conflict does not prove the write was refused. Throw it for every conflict of a write your backend's
+ * client may have sent more than once and that you cannot prove did not land: the read-back finds another writer's
+ * write over the row (a row is overwritten, so that writer may have swapped in over this write after it landed), or
+ * finds the row gone, or the compare-and-swap itself is answered that the row is gone. Throw a plain
+ * `WriteConflictError` for a conflict that does prove it: a write sent once, or a check your driver made before sending
+ * anything. A registry that wraps another rethrows the conflict it was given, not a new one, which would lose the mark.
+ *
+ * It is a `WriteConflictError` in every other way: `errorKind` names it `'WriteConflictError'`, `instanceof` holds on
+ * the same copy of the package, and every caller that handles a conflict handles it. A load's publish reads the row
+ * again, as after any conflict, and takes the write as its own when the row shows it there. Otherwise the write is
+ * reported to the load, as a write with no answer is, so a load refused after it carries `unanswered: true` on its
+ * `segment.load-refused` audit event. The mark is a registered `Symbol.for` brand, read
+ * across copies of the package. It is lost when the error is cloned or copied into a new one, and a conflict raised
+ * anywhere but a registry write is read as the plain conflict it also is.
+ */
+export declare function unsettledConflict(message: string): WriteConflictError;
+/**
+ * Whether `err` is a conflict a driver raised with {@link unsettledConflict}: a {@link WriteConflictError}, by brand
+ * and name as {@link isWriteConflictError} reads it, that carries the unsettled mark. It reads the registered brand,
+ * so it holds for an error from another copy of the package. Like the other predicates, no entry exports it.
+ */
+export declare function isUnsettledConflict(err: unknown): boolean;
 /** A retryable transient infrastructure fault. The retry layer keys on this. */
 export declare function isTransientError(err: unknown): err is TransientError;
 /** A read came after its pin's lease ended. */

package/dist/core/leases.d.ts

@@ -40,9 +40,11 @@ export declare function liveLeases(record: RegistryRecord | null, now: number):
  * Both are optional; without a sleep a retry follows at once.
  */
 export interface ChurnDeps {
+    /** The clock whose `sleep` waits out lease churn. Without a `sleep`, a retry follows at once. */
     readonly clock?: {
         readonly sleep?: (ms: number) => Promise<void>;
     } | undefined;
+    /** The source that spreads each wait over a share of its bound. Without one, each wait is its whole bound. */
     readonly rng?: Rng | undefined;
 }
 /**

package/dist/core/load-input.d.ts

@@ -17,7 +17,12 @@ import type { CombinedChunk } from './engine.js';
  * (`getSerializationSizeInBytes`) is asked first, so one over the cap is refused before it is serialized.
  */
 export interface PortableBitmap {
+    /** The bitmap in the portable Roaring format. */
     serialize(format: 'portable'): Uint8Array;
+    /**
+     * The size in bytes of `serialize('portable')`, when the bitmap can say without serializing. A load asks it first, so
+     * an input over the size cap is refused before it is serialized.
+     */
     getSerializationSizeInBytes?(format: 'portable'): number;
 }
 /**
@@ -53,6 +58,49 @@ export declare class ChunkLoadInput {
     readonly chunks: AsyncIterable<CombinedChunk>;
     constructor(chunks: AsyncIterable<CombinedChunk>);
 }
+/**
+ * Mark `err` as raised by a load's input (its ids, a bitmap's encoding, a combine's chunks) rather than by the write,
+ * and return it. A write-once conflict is a lost race only when the write raised it: a source that reads another
+ * segment (through a pin, say) can throw this library's own `WriteConflictError`, which is the source's to report.
+ */
+export declare function raisedBySource<T>(err: T): T;
+/** Whether a load's input raised `err` ({@link raisedBySource}). */
+export declare function isSourceError(err: unknown): boolean;
+/**
+ * Ids the caller says ascend (`sorted: true`), written chunk by chunk while they are read, during the object's upload,
+ * so a load holds one chunk and the writer's index rather than the whole generation. Made only by
+ * {@link sortedLoadInput}, from ids.
+ *
+ * The first error the ids raise, or their check raises (an id out of range, or lower than the one before it), or the
+ * chunker raises building a chunk, is kept here, and the load throws that same error. The driver's upload never sees
+ * it: the chunker throws a sentinel of its own into the writer instead, so no driver maps, redacts or probes the
+ * caller's error on its way out.
+ */
+export declare class SortedLoadInput {
+    readonly ids: Iterable<number> | AsyncIterable<number>;
+    private failure;
+    constructor(ids: Iterable<number> | AsyncIterable<number>);
+    /** Keep `error` as what the ids raised, unless an earlier one is kept. */
+    fail(error: unknown): void;
+    /** What the load throws for a write that failed with `err`: the error the ids raised, when they raised one. */
+    thrown(err: unknown): unknown;
+}
+/**
+ * Whether a load was asked for `sorted: true`. `undefined` and `false` mean no; anything else that is not a boolean is
+ * refused before any request, since `sorted: 'yes'` read as absent would hold the whole generation in memory instead.
+ *
+ * @throws {ValidationError} for a value that is not a boolean.
+ */
+export declare function wantsSorted(sorted: unknown): boolean;
+/**
+ * The input a load reads under its `sorted` option: ids as {@link SortedLoadInput} when it is `true`, anything else
+ * unchanged.
+ *
+ * @throws {ValidationError} for a `sorted` that is not a boolean, and for `sorted: true` with `{ serialized }`,
+ * `{ bitmap }` or a bitmap of the flavor's own: those are written from their own chunks already, so the option would
+ * do nothing, and an option that does nothing is refused rather than ignored.
+ */
+export declare function sortedLoadInput(prepared: ReturnType<typeof prepareLoadInput>, sorted: unknown): ReturnType<typeof prepareLoadInput> | SortedLoadInput;
 /**
  * Check a load's input and decode a bitmap input, before the load makes any request.
  *

package/dist/core/load.d.ts

@@ -140,6 +140,26 @@ export interface LoadOptions {
     readonly metadata?: GenerationMetadata;
     /** Audit sink for this load: it receives `segment.publish`, or `segment.load-refused` when the load is refused. */
     readonly audit?: IAuditSink;
+    /**
+     * The ids ascend: write them as they are read, one chunk at a time, while the object uploads, so the load holds one
+     * chunk and the writer's index of the chunks written (up to about 7 MiB, about 8 MiB for an encrypted segment,
+     * derived, at the 65,536 chunks a segment can have) rather than the whole generation, whatever the segment's size.
+     * Repeats are fine (an id equal to the one before is skipped); an id lower than the one before throws
+     * `ValidationError`, naming its position and never the id. The object is the same, byte for byte, as an unsorted load
+     * of the same ids writes under the same write identity.
+     *
+     * For ids only (an iterable or an async iterable): with `{ serialized }`, `{ bitmap }` or a `RoaringBitmap32` of the
+     * flavor's own `roaring` (one from another copy loads as its ids, and takes `sorted`), and on core's
+     * `loadSegmentChunks`, it throws `ValidationError`, as does a value that is not a boolean, before any request.
+     *
+     * The ids are read after the segment's row is read and judged, and after its number and key are settled, so a load
+     * that refuses a destroyed or keyless segment reads none of them. They are read while the object uploads: an error
+     * they raise, or a refused id, fails the upload, and no object is committed, but the parts uploaded before it may
+     * already have been billed (see the production guide). That error reaches the caller as the very object raised,
+     * and the storage driver never sees it. The ids can be read once: a storage driver that runs its write again gets
+     * `IntegrityError`, and nothing is written.
+     */
+    readonly sorted?: boolean;
 }
 /** The bounds a guard can refuse a generation for: every {@link LoadRefusal} but a lost race. */
 export type GuardRefusal = Exclude<LoadRefusal, 'superseded'>;
@@ -170,8 +190,9 @@ export type LoadRefusal = 'empty' | 'min-cardinality' | 'min-retained' | 'max-gr
  * writing: another load published, a retention change, a rollback or an erasure wrote the row, the row was
  * deleted, or a row appeared where the load found none. Once another write has changed the row, the object stays in
  * the bucket, still billed, until a later load's collection deletes it or the segment is dropped, because its
- * generation number may by then name another writer's object; until it goes, a rollback onto it needs `allowUnknown`, as onto any generation the row does not know. Once the row is
- * `destroyed` (dropped or crypto-shredded), the object is deleted; once the row is gone, so is an object whose footer
+ * generation number may by then name another writer's object; until it goes, a rollback onto it needs
+ * `allowUnknown`, as onto any generation the row does not know. Once the row is `destroyed` (crypto-shredded,
+ * destroyed in the clear or dropped), the object is deleted; once the row is gone, so is an object whose footer
  * matches what this load wrote (another load's object of the same ids is not a match: the footer carries each write's
  * own identity), and so is a cleartext one under a row with key material.
  */

package/dist/core/metrics.d.ts

@@ -136,6 +136,10 @@ export type MetricEvent = {
  * caller — `CloudRoaring` wraps a user sink so that a buggy sink can't break I/O.
  */
 export interface IMetricsSink {
+    /**
+     * Receives one event, synchronously. What it throws, or an async one's rejection, is swallowed and never breaks the
+     * call it observes.
+     */
     onEvent(event: MetricEvent): void;
 }
 /** The default sink: discards everything, zero overhead. Used whenever no sink is wired. */
@@ -147,23 +151,37 @@ export declare const NOOP_METRICS: IMetricsSink;
 export declare function safeMetrics(sink: IMetricsSink): IMetricsSink;
 /** Accumulated totals — the shape returned by {@link CountingMetricsSink.snapshot}. */
 export interface MetricsSnapshot {
+    /**
+     * Chunk requests to storage: how many, the bytes they returned, and the time they took in ms, transient-retry backoff
+     * included.
+     */
     readonly storage: {
         readonly gets: number;
         readonly bytes: number;
         readonly totalMs: number;
     };
+    /**
+     * Decoded-chunk cache hits and misses. A chunk counted without a lookup is a miss; `materializeMany` reads no cache, so
+     * it counts none.
+     */
     readonly cache: {
         readonly hits: number;
         readonly misses: number;
     };
+    /** Retries taken after a transient fault. */
     readonly retries: {
         readonly transient: number;
     };
+    /**
+     * Chunk-aligned combines of every operator (intersect, union and andNot): how many ran, the chunk keys they fetched
+     * and the keys they skipped without a fetch.
+     */
     readonly intersect: {
         readonly calls: number;
         readonly fetchedChunks: number;
         readonly skippedChunks: number;
     };
+    /** By operation name, how many calls were timed and their total time in ms. */
     readonly ops: Readonly<Record<MetricOpName, {
         readonly count: number;
         readonly totalMs: number;
@@ -181,7 +199,10 @@ export declare class CountingMetricsSink implements IMetricsSink {
     private intersect;
     private ops;
     private static zeroOps;
+    /** Adds the event to the totals. An `advisory` event is a note, not a quantity, and adds nothing. */
     onEvent(event: MetricEvent): void;
+    /** A copy of the totals so far, which later events do not change. */
     snapshot(): MetricsSnapshot;
+    /** Sets every total back to zero. */
     reset(): void;
 }

package/dist/core/pinned-storage-source.d.ts

@@ -27,15 +27,34 @@ import type { CrbmStorageChunkSource } from './crbm-storage-source.js';
  * What a pin holds for one segment: the generation, the version identifying those exact bytes, and the pinned
  * object's fingerprint, so a read can tell that the generation it opens is still that object.
  *
- * `fingerprint` is required for a pin of a generation (`null` only when `generation` is `null`): without it a read
- * could not tell a name purged and loaded again from the segment it pinned. `seg.pin()` always records it, and a
- * pin of a generation without a string `version` and `fingerprint` is refused with a `ValidationError`.
+ * It is one of two shapes, told apart by `generation`: a pin of a generation holds all three fields, and a pin of a
+ * segment that had no generation holds `null` in all three. Narrowing on `generation` (or on either other field)
+ * narrows the record whole, so a numbered pin passes to `pinAt` as it is:
+ *
+ * ```ts
+ * const at = first.pinnedAt;
+ * if (at !== undefined && at.generation !== null) await store.segment('active-30d').pinAt(at);
+ * ```
+ *
+ * `fingerprint` is never `null` for a pin of a generation: without it a read could not tell a name purged and loaded
+ * again from the segment it pinned. `seg.pin()` always records it, and a pin of a generation without a string
+ * `version` and `fingerprint` is refused with a `ValidationError`.
  */
-export interface PinnedAt {
-    readonly generation: number | null;
-    readonly version: string | null;
-    readonly fingerprint: string | null;
-}
+export type PinnedAt = {
+    /** The pinned generation. */
+    readonly generation: number;
+    /** The version of that generation's object. */
+    readonly version: string;
+    /** The fingerprint of that generation's object. */
+    readonly fingerprint: string;
+} | {
+    /** `null`: the segment had no generation when it was pinned. */
+    readonly generation: null;
+    /** `null`, as `generation` is. */
+    readonly version: null;
+    /** `null`, as `generation` is. */
+    readonly fingerprint: null;
+};
 export declare class PinnedStorageChunkSource implements StorageChunkSource {
     private readonly inner;
     /**

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

@@ -17,3 +17,12 @@ export declare function renewPointer(row: Pick<RegistryRecord, 'currentGen'>): R
  * cannot key a cache on it. A TypeScript registry fails to compile instead; this catches one in JavaScript.
  */
 export declare function pointerIdOf(row: RegistryRecord): Token;
+/**
+ * Whether `now` shows a write this call sent as the one that put the pointer where it is: an active row of the same
+ * incarnation as `before` (a `create` has none to compare), whose pointer names `generation` and whose `pointerId` is
+ * the token of one of the writes in `sent`, which a registry that reports its writes' tokens gave before sending each.
+ * The token decides and nothing else is asked, so another writer's write of the same pointer is not taken for this
+ * call's. A write that renews the `pointerId` over this call's own landed write (an erasure's renewal, or a write of
+ * the pointer back onto the same generation) reads as not this call's: the two cannot be told apart. Pure: no I/O.
+ */
+export declare function pointerSetBy(now: RegistryRecord | null, before: RegistryRecord | null, generation: number, sent: ReadonlySet<Token>): boolean;