@cloudbitmaps/core 0.19.0 → 0.20.0

package/dist/core/audit.d.ts

@@ -3,7 +3,7 @@
  * from the metrics sink (`IMetricsSink`). Different audience (an audit log / SIEM, not a dashboard), different
  * retention, and only the compliance-relevant *state changes* — never routine reads/writes (that's the metrics
  * sink). It doubles as the GDPR Art. 30 "record of processing" surface: publishes, refused loads, rollbacks,
- * rewrites, erasures and disposals.
+ * rewrites, an erasure's deletion of the generations holding an id, crypto-shreds and disposals.
  *
  * Like `Clock`/`Rng`/`IMetricsSink`, it's injected (into the operations that emit — a load, the `*Into`
  * verbs, a rollback, the erasure rewrite, crypto-shred, disposal and the retention sweep) and wrapped
@@ -16,12 +16,24 @@
  * wrappings, no data re-encryption), so there is no library call to hook. A future `rewrapSegment()` op would
  * add a `kek.rotate` variant; until then, audit key changes at your keystore-config layer.
  */
-/** A security/compliance-relevant state change. Vendor-neutral; the sink adds its own timestamp/actor. */
+/**
+ * A security/compliance-relevant state change. Vendor-neutral; the sink adds its own timestamp/actor.
+ *
+ * Every event about a segment carries `incarnation`: the id of the registry row's incarnation the operation acted on.
+ * A segment's name can be purged and created again, and its generations then start again at `0`; the incarnation
+ * tells those lives of the name apart, and every write of a row keeps it. It does not make a generation number name
+ * one object for good: within one incarnation, a number whose object was deleted (a refused load's object, or a
+ * generation an erasure deleted above the pointer) can be taken again by a later load. It is absent when the row's
+ * token carries no incarnation id, for example from a registry of the caller's own that issues tokens in another
+ * form, and on a `segment.load-refused` from a load that found no row.
+ */
 export type AuditEvent = {
     /** A new immutable Storage generation *became the segment's current generation*, by a load's publish. */
     readonly kind: 'segment.publish';
     readonly namespace?: string;
     readonly segment: string;
+    /** The incarnation of the row whose pointer the publish moved. */
+    readonly incarnation?: string;
     readonly generation: number;
 } | {
     /**
@@ -38,6 +50,8 @@ export type AuditEvent = {
     readonly kind: 'segment.rollback';
     readonly namespace?: string;
     readonly segment: string;
+    /** The incarnation of the row whose pointer the rollback moved. */
+    readonly incarnation?: string;
     readonly fromGeneration: number | null;
     readonly generation: number;
 } | {
@@ -59,6 +73,8 @@ export type AuditEvent = {
     readonly kind: 'segment.load-refused';
     readonly namespace?: string;
     readonly segment: string;
+    /** The incarnation of the row the load read before it wrote; absent when it found no row. */
+    readonly incarnation?: string;
     readonly generation: number;
     readonly reason: 'empty' | 'min-cardinality' | 'min-retained' | 'max-growth' | 'superseded';
     readonly cardinality: number;
@@ -69,13 +85,46 @@ export type AuditEvent = {
      * place. Today the one emitter is `eraseIdFromSegment` (a subject erasure clearing one id), and the event is
      * emitted at the publish — before the superseded generation is collected — so the record exists the moment
      * the generation without the id is authoritative. A `segment.publish` is NOT also emitted for a rewrite: a
-     * rewrite derives its content from the segment itself, a publish brings content in from outside.
+     * rewrite derives its content from the segment itself, a publish brings content in from outside. An erasure
+     * that finds the id only outside the current generation, or deletes only objects no read of the segment can
+     * open, rewrites nothing and emits `segment.collect`.
      */
     readonly kind: 'segment.rewrite';
     readonly namespace?: string;
     readonly segment: string;
+    /** The incarnation of the row the rewrite read `fromGeneration` from and published on. */
+    readonly incarnation?: string;
     readonly fromGeneration: number;
     readonly generation: number;
+} | {
+    /**
+     * An erasure of one id **deleted objects** no reader resolves, and rewrote none. It found the id only in such
+     * objects, or deleted only objects no read of the segment can open, which it cannot search and deletes whatever
+     * the id. The cases: an id that only generations other than the current one hold (someone who left the segment,
+     * whose bit the reader grace window or a rollback target keeps); objects left under a tombstone (a cleartext
+     * destroy, or a drop whose sweep left one); a first load's object on a segment with no generation yet (its load
+     * still running, or one that crashed before its publish); and an object sealed under a key the segment's row does
+     * not hold, or an encrypted one under a cleartext row (a first load's that lost the race, or crashed). The one
+     * emitter is `eraseIdFromSegment`, once a listing of the bucket shows nothing left holding the id, so the record
+     * exists only for a finished erasure. A call that ends otherwise throws or reports `erased: false` with another
+     * reason and emits nothing, even when it had deleted a holder; its re-run emits when it finishes, and reports
+     * `'not-member'` with no event when another collection deleted the last holder meanwhile, as its ledger entry
+     * does.
+     *
+     * `fromGeneration` is the newest generation the call found holding the id, and is absent when it found the id in
+     * none and deleted only objects it could not search: then the ledger lists no entry for the segment, and this
+     * event is the record of the deletion. `collected` is every generation the call deleted, ascending, and the same
+     * list as its result's: below the pointer, when a searched generation held the id, that is every generation,
+     * holder or not, since the deletion takes them all; above it, and wherever none did, only the holders and the
+     * objects it could not search. A holder another collection deleted first is not in it, so the list can be empty.
+     */
+    readonly kind: 'segment.collect';
+    readonly namespace?: string;
+    readonly segment: string;
+    /** The incarnation of the row the erasure read: the active row, or the tombstone. */
+    readonly incarnation?: string;
+    readonly fromGeneration?: number;
+    readonly collected: readonly number[];
 } | {
     /**
      * A segment was **crypto-shredded** — its wrapped DEK(s) are gone, so its at-rest Storage bytes are now
@@ -85,6 +134,8 @@ export type AuditEvent = {
     readonly kind: 'segment.erase';
     readonly namespace?: string;
     readonly segment: string;
+    /** The incarnation of the row the shred turned into a tombstone. */
+    readonly incarnation?: string;
 } | {
     /**
      * A segment was **disposed of** — tombstoned and its storage reclaimed (its Storage generations deleted) by
@@ -106,6 +157,8 @@ export type AuditEvent = {
     readonly kind: 'segment.dispose';
     readonly namespace?: string;
     readonly segment: string;
+    /** The incarnation of the tombstone the drop wrote or found. */
+    readonly incarnation?: string;
     readonly generationsDeleted: number;
 } | {
     /** A namespace erasure was executed. `segmentsShredded` is the count actually crypto-shredded (may be 0). */

package/dist/core/combine-many.d.ts

@@ -26,16 +26,19 @@ export interface CombineManyOperand {
     /** The generation the operand is pinned to: `null` when pinned to a segment with none, `undefined` when not pinned. */
     readonly pinnedGeneration?: number | null;
     /**
-     * The pin's version: the generation and the registry row's token it was taken under (`<generation>:<token>`), or just
-     * the generation where there is no row. It is what tells a name deleted and created again, which restarts at
+     * The pin's version: the generation and the registry row's `pointerId` it was taken under (`<generation>:<pointerId>`),
+     * or just the generation where there is no row. It is what tells a name deleted and created again, which restarts at
      * generation 0, from the one that was pinned.
      */
     readonly pinnedVersion?: string | null;
     /** The fingerprint of the object the pin holds: the identity of the generation's bytes, where a number can be taken again. */
     readonly pinnedFingerprint?: string | null;
     /**
-     * A fresh read of the segment's registry row: its current generation and token, or `null` when it has no row. Read
-     * for every subtracted pinned operand just before the publishes, and once more at the end of the call for the rest.
+     * A fresh read of the segment's registry row: its current generation and, as `token`, its `pointerId` (the token of the
+     * last write that named a field a read resolves through, so a lease or a policy write does not change it), or `null`
+     * when it
+     * has no row. Read for every subtracted pinned operand just before the publishes, and once more at the end of the call
+     * for the rest.
      */
     readonly current?: (options?: {
         readonly fingerprint?: boolean;
@@ -310,3 +313,9 @@ export declare class GroupCost {
  * budget, both before any chunk is read.
  */
 export declare function runCombineMany<R>(compiled: CompiledCombineMany<R>, deps: CombineManyDeps): Promise<CombineManyRun<R>>;
+/**
+ * The `pointerId` of a row's version (`<generation>:<pointerId>`, as a pin holds it), or `undefined` where the version
+ * names no row. A live version from the `.crbm` source ends with the opened object's fingerprint: read it through
+ * `rowVersionOf` first.
+ */
+export declare function tokenOfVersion(version: string | null | undefined): string | undefined;

package/dist/core/consistency.d.ts

@@ -37,9 +37,13 @@ export interface ConsistencyIssue {
     readonly currentGen: number;
     /**
      * `missing-storage-generation`: `currentGen` references a Storage generation that is not present (torn restore).
-     * `summary-mismatch` (only when asked for): the generation is there, but its row's summary says a different id
-     * count or metadata than the object holds (a row restored from another point than its bucket, or a number re-taken
-     * since). A count answers from that summary until a read opens the object, so it is what a restore leaves wrong.
+     * `summary-mismatch` (only when asked for): the generation is there, but its row's summary names another object
+     * than the one under its number, says a different id count or metadata than the object holds (a row restored from
+     * another point than its bucket, or an object put back from outside the library), or records a fingerprint that
+     * names no object. A summary that names another object is what a count and a `stat()` answer from while every read
+     * that opens the object refuses it; one whose count or metadata disagrees is answered from until a read opens the
+     * object, which stops that store using it; one whose fingerprint names no object is not used, so every read opens the
+     * object unchecked.
      */
     readonly issue: 'missing-storage-generation' | 'summary-mismatch';
 }
@@ -75,7 +79,9 @@ export interface ConsistencyReport {
  * `errored`.
  *
  * With `summaries: true` it also opens each segment's current object (one tail read, and a second for an index longer
- * than it) and holds the row's summary against it, reporting `summary-mismatch` where they disagree. A sealed summary
+ * than it) and holds the row's summary against it: the object it names by its fingerprint, and the count and metadata it
+ * says, reporting `summary-mismatch` where they disagree, and for a clear summary whose fingerprint names no object,
+ * which no read uses. A sealed summary
  * needs `deps.keystore`; without it the segment is counted in `summariesUnchecked`. Off by default, since the
  * default check only lists.
  */

package/dist/core/crbm/fingerprint.d.ts

@@ -0,0 +1,18 @@
+/** What names an object: its size, then its footer's CRC. One spelling, for an open reader and a footer read alone. */
+export declare const sizePart: (size: number) => string;
+/** An object's fingerprint, from its size and its footer's CRC (see `CrbmReader.fingerprint`). */
+export declare const fingerprintFor: (size: number, footerCrc: number) => string;
+/**
+ * A fingerprint taken apart, or `undefined` for text that is not one an object can have: a size that is a safe integer
+ * no smaller than a `.crbm` preamble and footer, and a footer CRC that fits in 32 bits. For a row's summary, which
+ * names its object by it and reports the size from it.
+ */
+export declare function fingerprintParts(fingerprint: unknown): {
+    readonly size: number;
+    readonly footerCrc: number;
+} | undefined;
+/**
+ * A fingerprint spelled short, for a key a read builds on every chunk: its size and its footer's CRC in base 36,
+ * `<size>.<crc>`. Two compact spellings are equal exactly when the fingerprints are.
+ */
+export declare function compactFingerprint(fingerprint: string): string;

package/dist/core/crbm/format.d.ts

@@ -4,16 +4,14 @@
  * These byte widths/offsets are pinned by the golden corpus and must never change for v1 —
  * a new layout is a new format version. All multi-byte integers are little-endian (v1 fixes LE).
  */
+import { FOOTER_BYTES, PREAMBLE_BYTES } from './frame.js';
 /** 4-byte magic at both file ends: "CRBM". */
 export declare const MAGIC: Uint8Array<ArrayBuffer>;
 export declare const VERSION_MAJOR = 1;
 export declare const VERSION_MINOR = 0;
-/** Front preamble: magic(4) + version_major(1) + version_minor(1) + reserved(2). */
-export declare const PREAMBLE_BYTES = 8;
+export { FOOTER_BYTES, PREAMBLE_BYTES };
 /** Payloads begin immediately after the preamble. */
 export declare const PAYLOAD_START = 8;
-/** Fixed footer size (v1.0). */
-export declare const FOOTER_BYTES = 104;
 /** Byte offsets of each field within the 104-byte footer. */
 export declare const FOOTER: {
     readonly indexOffset: 0;

package/dist/core/crbm/frame.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The two widths every `.crbm` v1 object is framed by: its front preamble and its footer. Frozen with the rest of the
+ * layout in `format.ts`, which re-exports them. They live in a module of their own, with no imports, so that what needs
+ * only the smallest size an object can have (the registry's check of a summary's fingerprint) does not bring the
+ * format's other constants, or the reader, with it.
+ */
+/** Front preamble: magic(4) + version_major(1) + version_minor(1) + reserved(2). */
+export declare const PREAMBLE_BYTES = 8;
+/** Fixed footer size (v1.0). */
+export declare const FOOTER_BYTES = 104;

package/dist/core/crbm/reader.d.ts

@@ -49,8 +49,6 @@ export interface CrbmReaderOptions {
      */
     readonly lineage?: unknown;
 }
-/** An object's fingerprint, from its size and its footer's CRC (see {@link CrbmReader.fingerprint}). */
-export declare const fingerprintFor: (size: number, footerCrc: number) => string;
 /**
  * Whether the object behind `blob` says it is encrypted, from one tail read of a footer's worth, with no key and no
  * index; a footer that fails its own checks throws, as an open would. For a caller that must not open an object with
@@ -102,7 +100,7 @@ export declare class CrbmReader {
      * the object it reopens is the one it pinned, since a purged and reloaded name reuses the generation number.
      */
     get fingerprint(): string;
-    /** Total object bytes (from the one-GET tail read) — for grounded storage cost. */
+    /** Total object bytes (from the one-GET tail read): the `sizeBytes` a segment's `stat()` reports. */
     get sizeBytes(): number;
     /**
      * Retained JS heap of this reader's parsed index — the weight the storage reader cache bounds on (a wide