@cloudbitmaps/core 0.11.2 → 0.12.0

package/dist/core/ports.d.ts

@@ -59,10 +59,18 @@ export interface StorageChunkSource {
     /**
      * Optional: the current generation's **per-chunk cardinality** (`chunkKey → count`), read from the
      * already-parsed `.crbm` index with **no payload reads**, or `null` if the segment has no Storage generation.
-     * Powers the free `count()` — the engine sums the index instead of fetching a single chunk. A source with no
+     * Powers the free `count()` of a source with no {@link StorageChunkSource.summary} — the engine sums the index
+     * instead of fetching a single chunk. A source with no
      * index (e.g. the in-memory source) omits this, and `count()` falls back to fetching every chunk.
      */
     cardinalities?(ref: SegmentRef): Promise<ReadonlyMap<number, number> | null>;
+    /**
+     * Optional: the current generation's number, id count and metadata, or `null` if the segment has no Storage
+     * generation. The `.crbm` source answers from the registry row's summary when it can use it, which is one
+     * registry read and no read of the object, and from the opened generation when it cannot. A source with no
+     * summary omits this, and `count()` keeps its other paths.
+     */
+    summary?(ref: SegmentRef): Promise<GenerationSummary | null>;
     /**
      * Optional: the segment's **current generation number** as this source resolves it right now (registry
      * `currentGen`, or the highest storage generation), or `null` if the segment has no Storage generation. The engine
@@ -105,10 +113,10 @@ export interface StorageChunkSource {
      * the generation *and* the incarnation of the name it belongs to.
      *
      * {@link StorageChunkSource.currentGeneration} is not enough to key a decoded-chunk cache, and the gap is not
-     * theoretical: a load numbers its generation `max(currentGen, highest object) + 1`, so the number **restarts at 0** once
-     * a registry row is purged and the bucket emptied. A retired, re-created name therefore serves different
-     * data at the same `currentGen`, and a cache keyed on `(segment, chunk, generation)` hands back the previous
-     * incarnation's ids — an erased id reappearing, with no read to intercept.
+     * theoretical: a load numbers its generation from the row's pointer and what is in the bucket, so the number
+     * **restarts at 0** once a registry row is purged and the bucket emptied. A retired, re-created name therefore
+     * serves different data at the same `currentGen`, and a cache keyed on `(segment, chunk, generation)` hands back
+     * the previous incarnation's ids — an erased id reappearing, with no read to intercept.
      *
      * Note that putting the incarnation in the *object key* would not fix this: the new incarnation still starts
      * at generation 0, so the cache key collides either way. The identity has to reach the cache.
@@ -160,8 +168,9 @@ export interface StorageCaps {
  *   loses its response, sent again, finds its own object and would report a collision. Either send each write
  *   once, with the backend client's retry off for that request, or recognise your own write when the
  *   precondition fails by reading an id you stored with it back, and treat a match as success. The first is
- *   what the S3 driver and the single-request GCS upload do; the second is what the Azure Blob driver and the
- *   resumable GCS upload do.
+ *   what the registry writes of every shipped driver do; the second is what the Azure Blob driver and the
+ *   resumable GCS upload do, and what the S3 driver and the single-request GCS upload do when they send an object
+ *   again after a throttle, which is the one replay a driver may make on purpose.
  * - **Raise a transient fault as {@link TransientError}** (throttling, a 5xx, a dropped connection), so the read
  *   retry can ride it out and a write's caller can tell it from a deterministic failure.
  */
@@ -212,6 +221,50 @@ export type RegistryStatus = 'active' | 'destroyed';
  * shape-later: stored and round-tripped, no semantics attached.
  */
 export type GovernanceMeta = Record<string, unknown>;
+/**
+ * A cached description of one generation, carried on the registry row: how many ids it holds, and the metadata it
+ * was loaded with. The generation's `.crbm` object stays the truth; this is a copy, written by the same write that
+ * moves the pointer, and it names the generation it describes so a copy left behind by a writer that did not
+ * carry it can never be taken for another generation's.
+ *
+ * Two shapes. On a cleartext segment the values are in the clear. On an encrypted segment (a row with
+ * `wrappedDeks`) they are sealed under the segment's data key, as the generation's index is, so the row reveals
+ * neither the count nor the metadata. A shipped registry refuses a write whose summary disagrees with the row's
+ * keys. It still reads a stored row that disagrees, so that one such row cannot stop every listing: a reader must not
+ * use that row's summary.
+ */
+export type RegistrySummary = ClearRegistrySummary | SealedRegistrySummary;
+/**
+ * A generation's metadata: string keys, string or finite-number values, no nesting, at most 1 KiB as canonical JSON.
+ * The rules are in `core/metadata.ts`.
+ */
+export type GenerationMetadata = Readonly<Record<string, string | number>>;
+/** What a generation is, as one read answers it: its number, its id count and the metadata it was written with. */
+export interface GenerationSummary {
+    readonly generation: number;
+    readonly cardinality: number;
+    /** Absent when the generation has none. */
+    readonly metadata?: GenerationMetadata;
+}
+/** {@link RegistrySummary} on a cleartext segment. */
+export interface ClearRegistrySummary {
+    /** The generation this describes. A non-negative safe integer. */
+    readonly generation: number;
+    /** How many ids the generation holds: an integer from 0 to 2^32. */
+    readonly cardinality: number;
+    /** The generation's metadata, when it has any. Never the empty object. */
+    readonly metadata?: GenerationMetadata;
+}
+/** {@link RegistrySummary} on an encrypted segment. */
+export interface SealedRegistrySummary {
+    /** The generation this describes. A non-negative safe integer. */
+    readonly generation: number;
+    /**
+     * Base64 of `nonce(12) ‖ ciphertext ‖ tag(16)`, sealing the cardinality as a little-endian u64 followed by the
+     * metadata's canonical JSON, if any. The count is fixed-width, so the length reveals only the metadata's size.
+     */
+    readonly sealed: string;
+}
 /**
  * One registry row — the authoritative per-segment record. Exactly one per segment.
  */
@@ -249,10 +302,23 @@ export interface RegistryRecord extends SegmentRef {
      */
     readonly retention?: GovernanceMeta;
     readonly residency?: GovernanceMeta;
+    /**
+     * A cached description of the current generation (see {@link RegistrySummary}). Optional: a row without one is
+     * correct, and a reader then opens the generation instead. Trusted only for the generation it names.
+     */
+    readonly summary?: RegistrySummary;
     /** Epoch-ms of creation / last mutation (from the driver's injected clock). */
     readonly createdAt: number;
     readonly updatedAt: number;
-    /** Opaque OCC token — compare-by-equality, never reused (ABA-safe). */
+    /**
+     * Opaque OCC token — compare-by-equality, ABA-safe. A shipped registry gives no two writes under one name the same
+     * token: not two writes of this row, not a write of an earlier row under the name, and not a write after this row is
+     * restored from a backup. It holds with overwhelming probability rather than by construction, since the token carries random parts: a
+     * 128-bit incarnation id drawn when the row is created, and a 64-bit part drawn for each write. Two incarnations of one
+     * name meet with probability 2^-128 for any pair (about n^2 / 2^129 among n of them), and two writes at one counter,
+     * after a restore, with probability 2^-64. A bare decimal token, on a row no 0.12 or later registry has written,
+     * carries neither part.
+     */
     readonly token: Token;
 }
 /** The caller-settable fields at {@link IRegistryDriver.create} (audit + token are driver-managed). */
@@ -265,14 +331,47 @@ export interface NewRegistryRecord {
     readonly status?: RegistryStatus;
     readonly retention?: GovernanceMeta;
     readonly residency?: GovernanceMeta;
+    /** Must name `currentGen` when given. */
+    readonly summary?: RegistrySummary;
 }
-/** Fields a {@link IRegistryDriver.compareAndSwap} may mutate (identity + audit + token are off-limits). */
-export type RegistryPatch = Partial<Pick<RegistryRecord, 'currentGen' | 'wrappedDeks' | 'keyId' | 'status' | 'retention' | 'residency'>>;
+/**
+ * Fields a {@link IRegistryDriver.compareAndSwap} may mutate (identity + audit + token are off-limits).
+ *
+ * Presence-based: a field the patch does not mention is left as it was. `summary` is the one exception, because it
+ * describes the current generation: a patch that moves `currentGen` and does not mention `summary` drops the old
+ * one rather than keep a description of another generation. A `summary` the patch gives must name the
+ * `currentGen` the row will have.
+ */
+export type RegistryPatch = Partial<Pick<RegistryRecord, 'currentGen' | 'wrappedDeks' | 'keyId' | 'status' | 'retention' | 'residency' | 'summary'>>;
 /** Capabilities a registry driver advertises; validated fail-fast at wiring time. */
 export interface RegCaps {
     /** REQUIRED — `currentGen` feeds read correctness + the publish CAS, so reads must be strongly consistent. */
     readonly strongRead: true;
+    /**
+     * `false` when this registry cannot write a row in this runtime, though it reads: a shipped registry draws random
+     * bytes for every token it issues, and on a runtime with no Web Crypto it has none to draw. A write path that
+     * writes an object before its row (a load, an erasure rewrite) checks it first and refuses with `UnsupportedError`
+     * before it writes anything, rather than leave an object no row names. Absent means the registry can write.
+     */
+    readonly canWrite?: false;
+    /**
+     * `true` when this registry's `delete` removes a row from its backend for good, so that no later `list` reads it, and
+     * removes it only while it is still the exact version the delete read: by a delete the backend applies under a
+     * precondition (an S3 or Azure Blob ETag, a GCS object generation), or under a lock no other writer of the backend
+     * can take. Only a row whose token carries an incarnation id is removed so. A row first written by a release before
+     * 0.12 has a bare decimal token, and a delete still tombstones it: a process on that release, re-creating the name
+     * over nothing, would issue those counters again from 0, so its row could not be told apart from the deleted one.
+     *
+     * `false` or absent: every `delete` leaves a tombstone, which every later full `list` still reads. A shipped registry
+     * says which it is.
+     */
+    readonly conditionalDelete?: boolean;
 }
+/**
+ * Refuse, with `UnsupportedError`, a write that would write an object before its row when the registry reports it
+ * cannot write a row (see {@link RegCaps.canWrite}). Called before the write's first request.
+ */
+export declare function assertRegistryCanWrite(registry: IRegistryDriver, what: string): void;
 /**
  * Brand for {@link StorageBackend}.
  *
@@ -365,8 +464,13 @@ export declare function isStorageBackend(value: unknown): value is StorageBacken
  * - **`create` and `compareAndSwap` are atomic conditional writes.** A `create` over a live row, and a
  *   `compareAndSwap` whose token is not the stored one, throw {@link WriteConflictError} and change nothing.
  *   Two racing writers have exactly one winner.
- * - **Tokens are never reused**, not even across `delete` then `create`: a delete leaves a tombstone (or a
- *   global counter) so a recreated row always carries a fresh token and a stale holder cannot swap into it.
+ * - **A token is not reused, not even across `delete` then `create`**, short of a collision of probability 2^-128 for
+ *   any two incarnations of one name: a recreated row carries a token no earlier incarnation held, so a stale holder
+ *   cannot swap into it. The shipped drivers draw a random 128-bit incarnation id into the token of every row they
+ *   create and a random 64-bit part into the token of every write, beside a counter a tombstone (or a global counter)
+ *   keeps going; where nothing of the earlier row is left, or the row is restored from a backup to an older counter, the
+ *   random parts alone keep the tokens apart: with probability 1 - 2^-128 per pair of incarnations, and 1 - 2^-64 per
+ *   pair of writes at one counter.
  * - **`delete` is idempotent** without an `expected` token: deleting an absent row is a no-op, not an error.
  *   **With `expected` it is fenced**: it lands only while the row still carries that token, and otherwise throws
  *   {@link WriteConflictError} and leaves the row.
@@ -408,7 +512,9 @@ export interface IRegistryDriver {
      */
     list(namespace?: string): AsyncIterable<RegistryRecord>;
     /**
-     * Remove the row (tombstoned for ABA-safety — a later `create` still gets a fresh, greater token).
+     * Remove the row. A registry whose {@link RegCaps.conditionalDelete} is `true` removes a row whose token carries an
+     * incarnation id from its backend; every other row is tombstoned. Either way a later `create` gets a token no
+     * earlier incarnation of the name held, but for a collision of probability 2^-128 per pair of incarnations.
      *
      * Without `expected`, idempotent: deleting an absent row is a no-op.
      *

package/dist/core/registry-scan.d.ts

@@ -27,6 +27,12 @@ export declare function drainRegistry(registry: IRegistryDriver, options: {
      * one namespace, so it passes false and the refusal does not tell it to narrow what it cannot.
      */
     narrowable?: boolean;
+    /**
+     * Told of each bookkeeping row an unscoped scan skips, which the listing has already paid to read. Only the
+     * retention sweep uses it, to find the due-index pointers whose segment has no row. It is not counted against
+     * `maxScanSegments`, and a caller that holds the rows it is given bounds them itself.
+     */
+    onReserved?: (record: RegistryRecord) => void;
 }): Promise<RegistryRecord[]>;
 /**
  * Is this record **bookkeeping** rather than a segment? Covers every reserved family — today the due-index

package/dist/core/retention-sweep.d.ts

@@ -33,11 +33,29 @@
  * once Storage is provably empty for it —
  * because deleting the row is what makes the name reusable and takes the segment out of reach of
  * the generation collection.
+ *
+ * **On a registry that reports `conditionalDelete`, the purge removes the row for good**, so a full scan stops paying a
+ * read for every name a namespace ever held: the scan costs what is live and what is inside its grace. The delete is
+ * fenced on the token the purge judged and applied by the store only to that version of the row. Each retirement
+ * files a pointer in the due index under the day its tombstone's grace ends, so `scan: 'index'` purges as well as
+ * retires; nothing on the row records that day, which the purge derives from the stamp. The purge removes every pointer
+ * it read to the row, and a pointer that outlives its row anyway (a purge that ran with another grace, a delete that
+ * landed and lost its response, a pointer older than an index scan's lookback) is removed by the next scan that reads
+ * it: an index scan in its buckets, and an unscoped fleet scan, which reads every pointer, in all of them. Where a
+ * delete only rewrites the row as a tombstone, none of this is done: nothing is removed for good, so a pointer would
+ * only add a row for every scan to read.
  */
 import { type IAuditSink } from './audit.js';
 import type { DropDeps, DropResult } from './erasure.js';
 /** Default cap on retirements per sweep — a bounded batch, so a policy mistake costs one batch, not the fleet. */
 export declare const DEFAULT_RETIRE_LIMIT = 100;
+/**
+ * How many purges in a row the registry may refuse in one call before the sweep stops purging for the rest of it. A
+ * blanket refusal (a policy that denies delete) costs this many attempts and no more; a refusal particular to one row
+ * (a blob with a snapshot, an object under a legal hold) does not hold the purges behind it, since a purge that succeeds
+ * starts the count again.
+ */
+export declare const MAX_CONSECUTIVE_PURGE_FAULTS = 3;
 /**
  * Default delay before a retirement's own tombstone row is purged: 24 h.
  *
@@ -54,7 +72,11 @@ export interface RetireExpiredOptions {
      * caller, never from the platform — `store.retireExpired()` fills it in from the store's clock.
      */
     readonly now: number;
-    /** Maximum segments to retire in this cycle (default 100). */
+    /**
+     * Maximum segments to retire in this cycle (default 100). It also bounds the purges attempted (a purge the registry
+     * refuses is not charged; {@link RetireExpiredResult.purgeFaults} says how purging stops after refusals) and the
+     * due-index pointers to nothing one call removes.
+     */
     readonly limit?: number;
     /** Report what would be retired and change nothing. */
     readonly dryRun?: boolean;
@@ -75,6 +97,11 @@ export interface RetireExpiredOptions {
      * pointer write failed (`indexed: false`), or whose ref is too long to index, has no pointer — so a
      * deployment that *only* ever runs `'index'` will never retire those. Run `'fleet'` periodically as the
      * repair pass. The default is `'fleet'` because it is complete by construction.
+     *
+     * An index scan purges too, on a registry that reports `conditionalDelete`: each retirement files a pointer to its
+     * tombstone under the day the tombstone's grace ends, and the scan reads it back with the expiry pointers. A pointer
+     * whose segment is gone is removed once read, by an index scan in the buckets it reads, and by an unscoped `'fleet'`
+     * scan (no `namespace`) in every bucket.
      */
     readonly scan?: 'fleet' | 'index';
     /**
@@ -94,7 +121,8 @@ export interface RetireExpiredOptions {
      */
     readonly lookbackBuckets?: number;
     /**
-     * Whether to delete the tombstone rows this sweep's own past retirements left (default `true`). Set `false` to
+     * Whether to delete the tombstone rows this sweep's own past retirements left (default `true`): removed for good on
+     * a registry that reports `conditionalDelete`, tombstoned on one that does not. Set `false` to
      * keep every one of them — the right choice if something outside this library treats the presence of a
      * `destroyed` row as an attestation. That includes the row of a retirement whose drop found no Storage
      * generation to delete and left none behind: with the default that row is deleted in the same pass, since it
@@ -179,6 +207,23 @@ export interface RetireExpiredResult {
     readonly tombstonesPurged: number;
     /** True when `limit` cut the cycle short — **more segments are still eligible**. Re-run. */
     readonly limited: boolean;
+    /**
+     * Deletes this sweep attempted that the registry **refused for a reason other than a lost race**: a tombstone's
+     * purge, or the removal of a due-index pointer. A policy that denies delete, an Azure blob with a snapshot, or any
+     * raw provider error is one; a write that landed between the sweep's read and its fenced delete is not (that is
+     * `failed: contended` in the ledger). Each leaves its row or pointer in place, so a purge that keeps failing never
+     * frees the name.
+     *
+     * A refused purge is not charged to `limit`, so retirements go on: a tombstone that cannot be purged does not hold
+     * the segments behind it past their expiry. **Purging stops for the rest of the call after
+     * {@link MAX_CONSECUTIVE_PURGE_FAULTS} (3) refused purges in a row**, and a purge that succeeds starts the count
+     * again. A blanket refusal therefore costs three attempts a call, and a refusal particular to one row (a blob with a
+     * snapshot, an object under a legal hold) holds nothing behind it. The next call tries again. Check this field; a
+     * ledger entry for each is `skipped`, but a caller that reads only `retired` sees none of it.
+     */
+    readonly purgeFaults: number;
+    /** The first of those faults, as a ledger reason (`failed: …` with the provider's message). Absent when there were none. */
+    readonly firstPurgeFault?: `failed: ${string}`;
     readonly dryRun: boolean;
     /** Per-segment ledger. Inspect it: a `skipped` or failed entry is a segment that still holds data. */
     readonly entries: readonly RetireEntry[];

package/dist/core/retry.d.ts

@@ -61,6 +61,20 @@ export interface RetryDeps {
 export declare function backoffDelayMs(policy: RetryPolicy, attempt: number): number;
 /** Apply the policy's jitter to a computed delay using the injected RNG. */
 export declare function applyJitter(policy: RetryPolicy, delayMs: number, rng: Rng): number;
+/**
+ * The store's read retry, as a write path takes it for the reads it makes along the way: a policy (the default when
+ * absent) and what {@link withRetry} needs to run it.
+ */
+export type ReadRetry = RetryDeps & {
+    readonly policy?: RetryPolicy;
+};
+/**
+ * Run a read under `retry`, or once when there is none. For the reads a write makes along the way (a load guard's
+ * read of the current generation, an erasure's reads of the generations it rewrites and verifies): a read is safe
+ * to repeat, so a transient fault on one is retried under the store's policy rather than failing the whole write.
+ * The write itself is never passed here.
+ */
+export declare function retryRead<T>(op: () => Promise<T>, retry: ReadRetry | undefined): Promise<T>;
 /**
  * Run `op`, retrying transient failures per `policy`. Resolves with `op`'s result, or rejects with the last
  * error once attempts are exhausted (or immediately for a non-retryable error). The thrown error is always

package/dist/core/rollback.d.ts

@@ -17,17 +17,32 @@
  * Art. 30 record or an incident review wants to find.
  */
 import { type IAuditSink } from './audit.js';
-import type { IStorageDriver, IRegistryDriver, SegmentRef } from './ports.js';
+import type { IKeystore } from './crypto.js';
+import type { IStorageDriver, GenerationMetadata, IRegistryDriver, SegmentRef } from './ports.js';
 /** What the generation helpers need: the objects, and the pointer that says which one is current. */
 export interface GenerationListDeps {
     readonly storage: IStorageDriver;
     readonly registry: IRegistryDriver;
+    /**
+     * The key of an encrypted segment, so a rollback can read its target's count and metadata and seal them into the
+     * row. Without it, a rollback of an encrypted segment still works and leaves the row with no summary of the
+     * generation it moves to, which a reader then takes from the object.
+     */
+    readonly keystore?: IKeystore;
 }
 /** One generation present in the bucket. */
 export interface GenerationEntry {
     readonly generation: number;
     /** Whether the registry pointer currently names this generation. */
     readonly current: boolean;
+    /**
+     * The current generation's id count, from its registry row, with no read of the object. Present only on the current
+     * entry, and only when the row's summary can be used: for an encrypted segment that takes a keystore that opens the
+     * segment's key. It is the row's word, not confirmed against the object.
+     */
+    readonly cardinality?: number;
+    /** The metadata the current generation was loaded with, from the same row; absent when it has none. */
+    readonly metadata?: GenerationMetadata;
 }
 /**
  * Every generation still present for a segment, ascending, with the current one marked.
@@ -38,7 +53,8 @@ export interface GenerationEntry {
  *
  * One registry read and one `list` call, whether or not the segment has a registry row, so it also finds the
  * objects a purged row left behind. It does not open the objects, so it costs nothing per generation and tells you
- * nothing about their contents — read the sizes through the store's own report if you need them.
+ * nothing about their contents — read the sizes through the store's own report if you need them. The current entry
+ * carries the id count and metadata its row records, from the same read.
  */
 export declare function listGenerations(ref: SegmentRef, deps: GenerationListDeps): Promise<GenerationEntry[]>;
 export interface RollbackResult {
@@ -58,12 +74,26 @@ export interface RollbackResult {
  *   design exists to avoid;
  * - a **crypto-shredded** segment is refused: every generation of it is unreadable, so a rollback would produce a
  *   segment that resolves and then fails;
+ * - a target that is **not what the row says the segment is** is refused with `IntegrityError`: a cleartext object
+ *   under a row with keys, or an encrypted one under a row with none, either of which every read would then refuse.
+ *   One tail read of the target decides it, as does a footer that fails its own checks;
  * - rolling to the generation **already current** is a no-op that reports itself, not an error.
  *
+ * The same tail read opens the target when the segment's key is at hand, and the rollback writes the target's own id
+ * count and metadata into the row, in the compare-and-swap that moves the pointer: a reader that sees the target as
+ * current sees what describes it. (One tail read, and a range read as well when the target's index is longer than the
+ * tail read: a target of very many chunks.) A store with no keystore, or one that cannot open the segment's key for any
+ * reason, a keystore that is unreachable or timed out included, still rolls an encrypted segment back and leaves the
+ * row with no summary of the target. The undo of a rollback whose target was collected meanwhile puts back the summary
+ * the row had, and so does the undo of an `allowForward` rollback whose target was replaced meanwhile: an object above
+ * the pointer can be deleted by an erasure and its number taken by a load, between the read and the swap, so after the
+ * swap such a target is read once more, and the pointer put back unless it is the object whose summary was written.
+ *
  * What it does **not** do is delete anything. The generations above the new pointer stay in the bucket, which is
  * what makes the rollback reversible — roll forward again by naming one of them. They are also then *above*
- * `currentGen`, where generation collection never looks. They stay until a load numbers above them (collection
- * then keeps the newest `keep` of what is below its pointer), `dropSegment` deletes them, or a subject erasure
+ * `currentGen`, where generation collection never looks. They stay until loads pass them (the first load whose
+ * number one of them holds numbers above them all, and collection then keeps the newest `keep` of what is below its
+ * pointer), `dropSegment` deletes them, or a subject erasure
  * deletes them: all of those present when it rewrites, and only those holding the id when the current generation does not.
  * Not collecting them is a deliberate trade: an operator who has just undone a bad load should not have the
  * evidence collected out from under them, while a rollback target that still holds erased data would make the

package/dist/core/summary.d.ts

@@ -0,0 +1,61 @@
+/**
+ * A generation's summary on its registry row: how a writer builds it, how a reader opens it, and how it is held
+ * against the object it describes.
+ *
+ * The row carries a cached description of the current generation, `{ generation, cardinality, metadata? }`, written by
+ * the same compare-and-swap that moves the pointer. On a cleartext segment the values are in the clear. On an
+ * encrypted one the row holds `{ generation, sealed }` instead: the cardinality as a fixed-width little-endian u64,
+ * then the metadata's canonical JSON if there is any, sealed under the segment's data key with the summary scope of
+ * the associated data, which binds it to its namespace, segment and generation. The count is fixed-width so the
+ * ciphertext's length reveals only the metadata's size, never how many digits the count has. Pure: no I/O.
+ *
+ * The generation's `.crbm` object stays the truth, and the summary is a copy of it. {@link summaryAgrees} is the
+ * comparison of one with the other.
+ */
+import type { Aead } from './crypto.js';
+import type { ClearRegistrySummary, GenerationMetadata, RegistryRecord, RegistrySummary, SealedRegistrySummary, SegmentRef } from './ports.js';
+/** What a summary says about a generation: its id count, and its metadata when it has any. */
+export interface GenerationDescription {
+    readonly cardinality: number;
+    readonly metadata?: GenerationMetadata | undefined;
+}
+/** The clear summary of a generation on a cleartext segment. `metadata` is left off when there is none. */
+export declare function clearSummary(generation: number, cardinality: number, metadata?: GenerationMetadata): ClearRegistrySummary;
+/**
+ * The sealed summary of a generation on an encrypted segment: the cardinality as a u64, then the metadata's canonical
+ * JSON, sealed under `aead` and bound to `ref` and `generation`.
+ */
+export declare function sealSummary(aead: Aead, ref: SegmentRef, generation: number, cardinality: number, metadata?: GenerationMetadata): SealedRegistrySummary;
+/**
+ * What a sealed summary says, opened with `aead` under the summary scope of `ref` and the summary's own generation.
+ * The bytes are untrusted: a blob that is not base64, is the wrong size, fails its authentication (tampered, or moved
+ * from another generation's row), or holds a count outside 0 to 2^32 or metadata that breaks the rules, is an
+ * {@link IntegrityError}.
+ */
+export declare function openSummary(aead: Aead, ref: SegmentRef, summary: SealedRegistrySummary): GenerationDescription;
+/**
+ * What a row's summary says of its current generation, or `undefined` when it says nothing a reader may use. It is
+ * used only for the generation it names, on an active row, and in the shape the row's keys call for: clear on a row
+ * with no wrapped keys, sealed on a row with them. A sealed one is opened with `aead`, and is unusable without it,
+ * or when it does not open, so a summary a tamperer moved or rewrote is never believed. Never throws for a bad
+ * summary: the row's copy is a cache, and a copy that cannot be used is a copy that is not there.
+ */
+export declare function usableSummary(ref: SegmentRef, row: RegistryRecord, aead: Aead | undefined): GenerationDescription | undefined;
+/**
+ * Whether a summary's description of a generation is what its object holds: the same id count and the same metadata,
+ * compared in canonical form, so key order never matters. A summary with metadata over an object with none, and the
+ * reverse, disagree: whether an encrypted object's metadata block is present is not authenticated (stripping it needs
+ * no key), so the row's sealed copy is what a missing block is held against.
+ */
+export declare function summaryAgrees(summary: GenerationDescription, object: GenerationDescription): boolean;
+/**
+ * The metadata an erasure carries into its rewrite of a generation: the object's own, except that an object with none
+ * whose row's authenticated summary of the same generation has some gets the row's. Whether an encrypted object has a
+ * metadata block is not authenticated, so a block stripped from one reads as none, and the sealed summary on the row is
+ * the one copy that says there was a block; carrying it keeps the rewrite from erasing the record of what it dropped.
+ * Pass `authenticated` only for a summary that was opened (a clear one has no more authority than the block it sits
+ * beside). Never refuses: a rewrite over a stripped block is still an erasure.
+ */
+export declare function metadataToCarry(object: GenerationMetadata | undefined, authenticated: GenerationDescription | undefined): GenerationMetadata | undefined;
+/** The summary of a generation of `ref`, clear or sealed under `aead` as the segment's keys call for. */
+export declare function summaryOf(ref: SegmentRef, generation: number, description: GenerationDescription, aead: Aead | undefined): RegistrySummary;

package/dist/core/token.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The registry token's incarnation: the part of a token that says which incarnation of a name a row is.
+ *
+ * A shipped registry gives a row it creates a token `<incarnation>.<counter>.<write>`: 32 lowercase hex digits drawn
+ * from injected entropy when the row is created, a decimal counter, and 16 hex digits drawn for each write. Every write
+ * of the row keeps the incarnation, and a name created again draws a new one, so two incarnations are told apart by it
+ * even when their rows were created in the same millisecond or one is gone. A row a 0.11 build wrote has no incarnation
+ * for as long as it lives (`"7"`, then `"8.<write>"`), and a registry of someone else's issues tokens in any form.
+ *
+ * This lives in `core/` so the publish can read it, and the registry drivers, which build the tokens, import it from
+ * here: the form has one definition.
+ */
+import type { Token } from './ports.js';
+/** An incarnation-form token: the incarnation id, the counter and a write part, `.`-separated, in lowercase hex. */
+export declare const INCARNATION_TOKEN: RegExp;
+/**
+ * The incarnation id in a token, or `undefined` for one that has none: a schema-1-born row's, or any token another
+ * driver issues. Two tokens with the same incarnation are writes of one incarnation of a row.
+ */
+export declare function incarnationOf(token: Token): string | undefined;
+/**
+ * Whether two reads of one name's row are one incarnation of it.
+ *
+ * - Both tokens carry an incarnation id: the ids decide, and the clock stamps do not enter.
+ * - Only one does: different incarnations. A name created again is always given an incarnation id, and a write never
+ *   takes one away, so a row without an id never becomes a row with one, nor the reverse.
+ * - Neither does (a row 0.11 wrote, or a registry of someone else's): there is no id to compare, and the creation stamp
+ *   is the only signal left. It is a clock reading, so a caller that acts on this answer proves its own object too.
+ */
+export declare function sameIncarnation(a: {
+    readonly token: Token;
+    readonly createdAt: number;
+}, b: {
+    readonly token: Token;
+    readonly createdAt: number;
+}): boolean;

package/dist/core/validate.d.ts

@@ -7,6 +7,8 @@ import type { ChunkRef, SegmentRef } from './ports.js';
  * a namespace and a segment at the ceiling.
  */
 export declare const MAX_NAME_LENGTH = 256;
+/** Whether `value` is well-formed UTF-16: no unpaired surrogate, so it survives a round trip through UTF-8. */
+export declare function isWellFormedString(value: string): boolean;
 /**
  * How long a name is once storage has it — the longer of the two encodings.
  *