@cloudbitmaps/core 0.10.0 → 0.11.0

package/dist/core/codec.d.ts

@@ -3,7 +3,7 @@
  *
  * `core/` is **codec-agnostic**: `SegmentEngine`, the erasure rewrite, and the `.crbm` read/write helpers only ever
  * construct and combine bitmaps through the {@link CodecInterface} factory + the {@link CodecBitmap} value type
- * defined here — never a concrete implementation. The flagship codec is roaring (`roaringCodec`, in
+ * defined here — never a concrete implementation. The flagship codec is roaring (in
  * `@cloudbitmaps/roaring`), and another codec would plug in behind the same seam with zero engine or driver
  * changes. That is the seam's value even with one codec shipped: a plain-bitset flavor was measured and
  * **decided against** (above ~6% density a Roaring chunk already *is* an uncompressed bitset), so the seam is
@@ -21,15 +21,14 @@
  * package's own extended value type, not here — the engine never calls them). The one codec-linked concern
  * this seam intentionally leaves in the format layer is the `.crbm` **payload codec id**
  * (`PAYLOAD_CODEC_ROARING_PORTABLE` / `KNOWN_PAYLOAD_CODEC_IDS` in `crbm/format.ts`): it is stamped in the footer
- * and validated on read. That generalization is **done** as of 0.7.0 — the field was `roaringSerializationId`
- * and validated by equality against a single constant, which would have frozen a codec-specific name into the
- * format at `1.0`. It is now a registry the reader checks membership against, so a future codec is a one-line
- * registration rather than a major format version. Still deliberately outside this interface: a codec declares
+ * and validated on read, as membership of a registry rather than equality with one constant, so a codec-specific
+ * name is not frozen into the format at `1.0` and a future codec is a one-line registration rather than a major
+ * format version. Still deliberately outside this interface: a codec declares
  * its bytes, the seam does not.
  */
 /**
  * The value type a codec produces — a mutable set of `u32` with set algebra and portable (de)serialization.
- * This is the shape `SafeBitmap` already has; the engine holds these, caches them, and merges tiers with them.
+ * This is the shape the roaring flavor's bitmap already has; the engine holds these, caches them, and merges tiers with them.
  */
 export interface CodecBitmap {
     /** Serialize with the codec's **stable, portable** format (never a frozen/unsafe variant). */
@@ -61,7 +60,10 @@ export interface CodecBitmap {
      * cannot answer this in better than O(n) should simply omit it — the engine then skips the check rather
      * than walking every value on the read path, which is the one thing this must never cost.
      *
-     * Roaring answers it in O(1) from its container index, so the flagship codec implements it.
+     * Roaring answers it in O(1) from its container index, so the flagship codec implements it. The check is only
+     * as good as the answer: a codec that implements this must return the true largest value of whatever
+     * {@link CodecInterface.safeDeserialize} decoded, which for roaring holds only because that call refuses bytes
+     * whose containers or values are out of order.
      */
     maximum?(): number | undefined;
     /**
@@ -98,16 +100,22 @@ export interface CodecInterface {
     /**
      * Size-cap (`bytes.length <= maxBytes`) then portable-deserialize. Throws `IntegrityError` when the input
      * exceeds the cap or fails to decode — the native decoder is never handed unbounded or unsafe-format input.
+     *
+     * "Fails to decode" includes bytes that are the right length and the wrong shape. A bitmap this returns must
+     * satisfy every invariant its own operations assume (for roaring: containers and values in order, runs
+     * disjoint, cardinalities matching the bits), because the engine trusts `has`, `size`, iteration order and
+     * {@link CodecBitmap.maximum} on what comes back, and a decoder that only bounds its reads guarantees none of
+     * them.
      */
     safeDeserialize(bytes: Uint8Array, maxBytes: number): CodecBitmap;
 }
 /**
  * Resolve a codec that a **public core entry point** was given, failing fast when it is missing.
  *
- * Why these entry points take `codec?` rather than a required field: `bulkLoadCrbmGeneration` /
- * `eraseIdFromSegment` / `runExport` are call-compatible public API, and core cannot supply a default (the concrete
+ * Why these entry points take `codec?` rather than a required field: `loadSegment` / `eraseIdFromSegment` /
+ * `runExport` are call-compatible public API, and core cannot supply a default (the concrete
  * codec lives in a *flavor* package that depends on core — a default here would invert that arrow). A **flavor**
- * package binds the codec for its users (`@cloudbitmaps/roaring` re-exports codec-bound wrappers), so an
+ * package binds the codec for its users (`@cloudbitmaps/roaring`'s store passes its codec to each of these), so an
  * application never reaches this throw; only someone calling `@cloudbitmaps/core` directly — i.e. a flavor or
  * driver author — can, and for them the typed error names exactly what to pass.
  */

package/dist/core/consistency.d.ts

@@ -2,15 +2,15 @@
  * Fail-safe cross-store disaster-recovery check. The registry (`currentGen`) and the immutable `.crbm`
  * generations can be restored **independently**, so a failover can recover the registry *ahead of* the storage
  * objects — leaving `currentGen` pointing at a generation whose `.crbm` isn't present yet. That is likelier
- * than it sounds even now that both usually live in one bucket: a restore scoped to a prefix, or replayed
+ * than it sounds even with both in one bucket: a restore scoped to a prefix, or replayed
  * per-object from a version history, recovers the two prefixes at different points. That's a torn restore: reads of the affected segment then throw. This scan
  * detects it up front (run it at startup after a restore) instead of discovering it on the first read.
  *
  * Read-only; bounded fan-out. `destroyed` (crypto-shredded) segments are skipped — their Storage is intentionally
  * gone/unreadable, not a torn restore. A segment whose Storage/registry can't be read this pass is recorded in
  * `errored` (never aborts the scan). Each segment is checked against its **authoritative live pointer** — one
- * strong `registry.get` per segment — never the enumeration snapshot from `registry.list`, which can be
- * eventually-consistent (an unindexed Scan) and lag a recent in-place pointer advance: trusting it would both
+ * strong `registry.get` per segment — never the enumeration snapshot from `registry.list`, which a driver may
+ * serve eventually-consistently and so lag a recent in-place pointer advance: trusting it would both
  * miss a torn *live* generation and cry torn on a generation the pointer has already advanced past (GC'd during
  * the scan). Residual: a load's publish plus a GC landing in the tiny per-segment get→list gap can still yield a
  * transient false positive — run the scan against a quiesced fleet (the documented restore procedure), or re-run

package/dist/core/cooperative.d.ts

@@ -3,8 +3,8 @@
  *
  * Everything this library does on the hot read path is small. Bulk-load is the exception: it is the one place
  * where a single call legitimately occupies the CPU for hundreds of milliseconds, and Node has exactly one thread
- * to occupy. Measured on a 1M-id load, 62,455 chunks: **442 ms wall, and 450 ms during which the event loop did
- * not turn at all**. Wire that to a request handler and every other in-flight request on the instance — health
+ * to occupy. Measured on a 1M-id load of 65,536 chunks onto in-memory storage, on a loaded Apple M3 Pro: **518 ms
+ * wall, and 519 ms during which the event loop did not turn at all** (medians of 20 fresh-process runs). Wire that to a request handler and every other in-flight request on the instance — health
  * checks included — waits out the whole load.
  *
  * The fix is not to make the work asynchronous. That was measured too, and it is a 7x *regression*: handing each
@@ -29,10 +29,10 @@
  * baseline, with the worst event-loop gap down from 568 ms to 13.8 ms.
  *
  * **Three experiments, three sets of numbers — do not mix them.** (a) The end-to-end 1M-id bulk load:
- * 442 ms wall / 450 ms blocked before, 256 ms / 19 ms after. (b) This synthetic yield-primitive comparison:
+ * 518 ms wall / 519 ms blocked unyielded, 526 ms / 24 ms yielded. (b) This synthetic yield-primitive comparison:
  * 568 ms / 568 ms unyielded, 569 ms / 13.8 ms with `setImmediate`. (c) A per-chunk insert microbenchmark:
- * 92 ms sync versus 636 ms via the threadpool. Quoting a baseline from one against a result from another is
- * how this file previously published a 92 ms operation with 819 ms of starvation inside it.
+ * 92 ms sync versus 636 ms via the threadpool. Quoting a baseline from one against a result from another describes
+ * work none of them did, such as a 92 ms operation with 450 ms of starvation inside it.
  */
 /**
  * The only part of a `Clock` that yielding actually needs.
@@ -70,9 +70,9 @@ export declare const YIELD_EVERY = 1024;
  * The two-line shape is deliberate. `await tick()` would read better and would force a microtask turn on every
  * single iteration — an unconditional cost on the very loop this exists to keep fast.
  *
- * With no `clock` the result always returns `null`: the loop runs exactly as it did before this existed, so
- * adding a yield point to a code path can never change behaviour for a caller who did not opt in. `core/` cannot
- * supply a clock itself — it is timer-free by lint, which is the whole reason scheduling goes through the seam —
- * so `@cloudbitmaps/roaring` pre-binds a real one and flavor users get this with no wiring at all.
+ * With no `clock` the result always returns `null`: the loop runs unbroken, so adding a yield point to a code
+ * path can never change behaviour for a caller who did not opt in. `core/` cannot supply a clock itself — it is
+ * timer-free by lint, which is the whole reason scheduling goes through the seam — so `@cloudbitmaps/roaring`
+ * pre-binds a real one and flavor users get this with no wiring at all.
  */
 export declare function yieldEvery(clock: Yielder | undefined, everyN?: number): () => Promise<void> | null;

package/dist/core/cost.d.ts

@@ -7,38 +7,157 @@ export interface PricingProfile {
         /** Object PUT (per million) — what a load pays, per request. */
         readonly putPerMillion: number;
         readonly storagePerGiBMonth: number;
+        /**
+         * Requests one read costs when it needs the object's size first: a pointer read, and a segment's tail read.
+         * Default **1**, S3's, whose suffix-range GET returns the size with the bytes. **2** on GCS and Azure Blob,
+         * which read the metadata and then the bytes. A chunk read knows its range, and is one request everywhere.
+         */
+        readonly requestsPerSizedRead?: number;
     };
-    /** The always-on baseline to compare against (e.g. an ElastiCache HA cluster). */
+    /**
+     * The always-on Redis the verdict compares against: exactly one of the two. `sizedToData`, the default's, prices
+     * the cheapest cluster that holds the report's stored bytes; `monthlyUSD` is one cluster you name, whatever the
+     * data size. A profile carrying both is refused rather than read one way.
+     */
     readonly redis: {
         readonly monthlyUSD: number;
+        readonly sizedToData?: never;
+    } | {
+        readonly sizedToData: RedisSizing;
+        readonly monthlyUSD?: never;
     };
 }
+/** One node type a Redis cluster can be built from, as its cloud prices it. */
+export interface RedisNodeType {
+    readonly name: string;
+    /** Memory, in GiB, as the cloud publishes it for the node type. */
+    readonly memoryGiB: number;
+    /**
+     * SSD, in GiB, on a data-tiering node (ElastiCache's `r6gd`): keys stay in memory, and the values read least
+     * recently move to the SSD. Counted in full beside the memory, as AWS counts a data-tiering node's capacity.
+     */
+    readonly ssdGiB?: number;
+    /** Price per node-hour, in USD. */
+    readonly hourlyUSD: number;
+    /**
+     * The most shards a cluster of this type is priced at. The default catalogue prices its burstable nodes as one
+     * shard: a cluster sharded across them is not how data anyone queries is held. Default: no limit.
+     */
+    readonly maxShards?: number;
+}
 /**
- * Default profile — **AWS us-east-1, on-demand**, mid-2026, from the fact-checked
- * published pricing rather than copied from a blog post. Override it for your region, cloud, or committed term.
+ * Redis sized to hold the data: enough shards for the bytes, each a primary and its replicas, on whichever node
+ * type in `nodeTypes` makes that cheapest. Prices within a millionth of a dollar of the cheapest are a tie, which
+ * fewer nodes win, then the lower price, then the name, so the answer never depends on the order of the rows. The data is held at its stored,
+ * compressed size, which is a floor on the memory Redis needs for it: a native Redis bitmap is sized by its highest
+ * id, not by how many ids it holds, so sparse ids need more.
+ */
+export interface RedisSizing {
+    /** Where the prices come from, and when; the report's notes quote it. */
+    readonly source: string;
+    readonly nodeTypes: readonly RedisNodeType[];
+    /** Replicas per shard. AWS's best practice is 2; Multi-AZ needs at least 1. */
+    readonly replicasPerShard: number;
+    /** The share of each node's memory kept back from data: ElastiCache's `reserved-memory-percent`, 25% by default. */
+    readonly reservedMemoryFraction: number;
+}
+/**
+ * **ElastiCache for Redis OSS in us-east-1, on-demand**: node prices from AWS's public price list, version
+ * 20260914063714 (published 2026-09-14, effective 2026-09-01,
+ * https://pricing.us-east-1.amazonaws.com/offers/v1.0/aws/AmazonElastiCache/20260914063714/us-east-1/index.json), and the
+ * memory AWS publishes for each node type. Every shard is a primary and two replicas, AWS's best practice, with
+ * ElastiCache's default 25% of each node's memory reserved, and the burstable `t4g` nodes are priced as one shard.
+ *
+ * It lists only rows that are the cheapest fit for some size of data: the data-tiering `r6gd` rows above about
+ * 30 GiB, and the larger in-memory `r6g` rows, `2xlarge` and up, when those are left out. The current `m7g` and `r7g` nodes are not here,
+ * because an `m6g` or `r6g` with the same memory costs less. It is the cheapest cluster of THIS kind; Redis bought
+ * another way costs less — one replica a shard a third less, ElastiCache for Valkey 20% less a node, reserved nodes
+ * less again — so against those the saving the verdict reports is smaller. Pass their prices to compare with them.
+ */
+export declare const ELASTICACHE_REDIS_US_EAST_1_ONDEMAND: RedisSizing;
+/**
+ * One ElastiCache HA cluster, a primary and two replicas of cache.m7g.large — the m7g family's smallest node —
+ * at $0.158 an hour each: 3 × 730 h × $0.158 = $346.02, published to the dollar. The per-request crossovers on the
+ * benchmarks page are drawn against this one cluster, whatever the data size; pass it as `pricing.redis` to compare
+ * with it. It is not the cheapest cluster for any size of data: three cache.m6g.large hold the same memory for less.
+ */
+export declare const ONE_REDIS_HA_CLUSTER: Readonly<{
+    monthlyUSD: number;
+}>;
+/**
+ * Default profile — **AWS us-east-1, on-demand**, mid-2026, from the fact-checked published pricing rather than
+ * copied from a blog post, with Redis sized to the data. Override it for your region, cloud, or committed term.
  */
 export declare const AWS_US_EAST_1_ONDEMAND: PricingProfile;
-export declare const DEFAULT_PRICING: PricingProfile;
 /** Sustained access pattern. All rates default to 0; unspecified ⇒ that op contributes nothing. */
 export interface Workload {
-    /** Point reads (`has`) per second. Each cache miss is one object GET. */
+    /**
+     * Point reads (`has`) per second. Each cache miss is one object GET, once the segment's pointer and index are
+     * read.
+     */
     readonly readsPerSec?: number;
     readonly intersectsPerSec?: number;
-    /** CACHE-cache hit rate in `[0, 1]` — hits are free; only misses cost. Default 0. */
+    /** Cache hit rate in `[0, 1]` — hits are free; only misses cost. Default 0. */
     readonly cacheHitRate?: number;
-    /** Storage chunks fetched per intersection (the chunk-skipping survivors). Default 1. */
+    /**
+     * Storage chunks one intersection fetches, summed over its operands: the chunk-skipping survivors. Default 1.
+     * Two segments sharing `k` chunks fetch `2k`. The model adds each operand's pointer and index reads itself (see
+     * {@link Workload.operandsPerIntersect}), so count chunks only. One more GET per operand whose index outgrows
+     * the reader's tail read (256 KiB by default), which then reads the index whole, belongs here too, and so does a
+     * pointer re-read by an intersect slow enough to outlive {@link Workload.genTtlMs}.
+     */
     readonly chunksPerIntersect?: number;
+    /**
+     * Segments each intersection reads, `exclude` operands included; at least 1. Default 2. An intersection is priced
+     * **cold**: before its chunks, each operand's pointer is read, then its index, in one read of the object's tail —
+     * 2 GETs an operand, so a cold intersect of two segments sharing `k` chunks is `4 + 2k` GETs. `cacheHitRate`
+     * does not apply to intersections, so a long-lived reader that answers a repeat from its cache pays less. Other
+     * combines read their operands the same way and can be priced here too, with the chunks they fetch.
+     */
+    readonly operandsPerIntersect?: number;
     /**
      * Generations published per month across the modeled data — the write side of a loaded store. Default **0**
      * ⇒ loads are not modeled and the report *discloses* the omission rather than silently under-reporting.
      */
     readonly loadsPerMonth?: number;
     /**
-     * PUT-class requests one load issues. Default **1** (a single-object PUT). A multipart load of `P` parts bills
-     * `P + 2` (initiate, the parts, complete) — set it when you know your object sizes. Still small money: at
-     * $5/million, a thousand 100-part loads a month is $0.51.
+     * PUT-class requests one load's object write issues, each priced at the PUT rate. Default **1** (a single-object
+     * PUT). A multipart write of `P` parts bills `P + 2` (initiate, the parts, complete) — set it when you know your
+     * object sizes. The model adds what `store.load()` does around the write: two listings and the pointer's write,
+     * PUT-class on S3, and nine GETs, the pointer read eight times and the current generation's index once. That is
+     * a segment with two generations behind it; its first load makes two fewer GETs, and its second one fewer. On
+     * S3 at the default prices a single-part `store.load()` is then about $23.60 per million. A segment whose index
+     * outgrows the tail read makes one more GET, and a publish that loses a race to another writer reads the
+     * pointer again.
      */
     readonly requestsPerLoad?: number;
+    /**
+     * Segments each long-lived reader process keeps reading. A reader re-reads a segment's pointer when it reads the
+     * segment after {@link Workload.genTtlMs} has passed, so each costs at most one GET per `genTtlMs` in each process
+     * that reads it — 1,314,000 GETs a month at the default 2 s — and the whole term at most one GET per point read
+     * (`readsPerSec`, across the fleet). Intersections are priced cold and pay their own pointer reads. Default **0**
+     * ⇒ the refresh is not modeled, and the report *discloses* the omission when there are reads to refresh for.
+     *
+     * It assumes each hot segment stays open in the reader's cache (`cache.readerMax`, 1,024 segments by default,
+     * and `cache.readerMaxBytes`, 64 MiB of parsed index). A read of a segment the cache evicted opens it again, a
+     * pointer read and a tail read, which is not priced here, and neither is the re-open every reader makes after
+     * each load, for the new generation's index. Size those caches to keep the hot set open; the report says so when
+     * `hotSegments` is more than a store keeps open by default.
+     */
+    readonly hotSegments?: number;
+    /**
+     * Long-lived reader processes, each keeping its own {@link Workload.hotSegments} open and refreshing their
+     * pointers on its own: ten processes reading the same hundred segments pay ten times one process's refresh.
+     * At least 1. Default 1.
+     */
+    readonly readerProcesses?: number;
+    /**
+     * How long the reader trusts a pointer, in ms: the store's `cache.genTtlMs`. Default 2000, the store's own
+     * default; `segment.costReport()` uses the store's. `0` turns the timed refresh off, and the model bills none: a
+     * reader then re-reads a pointer only when its cache evicts the segment, a read finds its generation swept, or a
+     * write invalidates it, none of which this term prices.
+     */
+    readonly genTtlMs?: number;
 }
 /** One (group of) segment(s) for planning. `count` = how many like this (default 1). */
 export interface SegmentSizing {
@@ -58,16 +177,48 @@ export interface CostReport {
             readonly reads: number;
             readonly intersects: number;
             readonly storage: number;
-            /** Loads (object PUTs). 0 unless `loadsPerMonth` is set. */
+            /**
+             * Loads: each its object's `requestsPerLoad` PUT-class requests plus what `store.load()` adds around them.
+             * 0 unless `loadsPerMonth` is set.
+             */
             readonly loads: number;
+            /** The pointer refresh of {@link Workload.hotSegments}. 0 unless `hotSegments` is set. */
+            readonly pointerRefresh: number;
         };
         readonly total: number;
     };
     /**
-     * Sustained read rate at which the pay-per-use model's cost passes the flat Redis baseline (with every other
-     * axis at 0), **evaluated at this report's `cacheHitRate`** — so a higher cache-hit rate raises it (cache hits
-     * are free). `Infinity` means it never crosses (a 100% cache-hit rate). The published anchor (~329 reads/s) is
-     * at `cacheHitRate: 0`.
+     * The Redis the verdict compares against. Sized, the default, it is the cheapest cluster in
+     * `pricing.redis.sizedToData` that holds this report's stored bytes; fixed, it is `pricing.redis.monthlyUSD` as
+     * given.
+     *
+     * **It is not additive across reports.** Each report sizes Redis to its own bytes, so a per-segment report
+     * (`segment.costReport()`) compares with a cluster holding that one segment alone, and the baselines of a store's
+     * segments do not sum to the store's. To judge a store, price all its segments in one `estimateCost`. To alarm on
+     * one, sum `monthlyUSD.total` over its segments and compare the sum with the Redis you would run for it: a
+     * per-segment verdict against that whole price fires only when one segment alone costs more than all of it.
+     */
+    readonly redisBaseline: {
+        readonly basis: 'fixed';
+        readonly monthlyUSD: number;
+    } | {
+        readonly basis: 'sized-to-data';
+        readonly monthlyUSD: number;
+        /** The node type, the shards, the nodes (every shard's primary and replicas), and whether they tier to SSD. */
+        readonly cluster: {
+            readonly nodeType: string;
+            readonly shards: number;
+            readonly nodes: number;
+            readonly dataTiering: boolean;
+        };
+    };
+    /**
+     * Sustained read rate at which the pay-per-use model's cost passes {@link CostReport.redisBaseline}, **evaluated
+     * at this report's `cacheHitRate`** — so a higher cache-hit rate raises it (cache hits are free) — with the other
+     * request axes at 0, and with what keeping the data readable costs taken out of the baseline first: storage, and
+     * this report's pointer refresh. Loads, the write side, are left out of it. `Infinity` means it never crosses (a
+     * 100% cache-hit rate). The published anchor (~329 reads/s) is against {@link ONE_REDIS_HA_CLUSTER}, at
+     * `cacheHitRate: 0` with no refresh modeled.
      */
     readonly redisCrossover: {
         readonly readsPerSec: number;
@@ -79,6 +230,7 @@ export interface CostReport {
         readonly pricingName: string;
         /** True when segment **sizes** were real (grounded `costReport`), false for a pure `estimateCost`. */
         readonly grounded: boolean;
+        /** What the model assumed and what it left out, in words. The last says how the Redis was priced. */
         readonly notes: readonly string[];
     };
 }

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

@@ -59,12 +59,10 @@ export declare const ELEMENT_WIDTH_32 = 32;
  * see the `.crbm` format section of the API reference). This field is what lets one container hold either, the same way ZIP tags each member
  * with a compression method.
  *
- * **Why this is not named `roaringSerializationId` any more.** It was, and the name was a trap waiting for the
- * `1.0` format freeze. A second codec is genuinely expected — `soaring` is a planned Roaring *variant*, so its
- * serialized bytes are unlikely to be roaring-portable, and it lands *after* `1.0`. A field frozen under a
- * codec-specific name cannot be reinterpreted later without a major format version, so generalizing it is a
- * one-line change now and an expensive one after the freeze. The byte layout is untouched: same offset (24),
- * same width (u16), same golden corpus.
+ * **A codec id, not a roaring-specific one.** A second codec is genuinely expected — `soaring` is a planned
+ * Roaring *variant*, so its serialized bytes are unlikely to be roaring-portable, and it lands *after* the `1.0`
+ * format freeze. A field frozen under a codec-specific meaning could not be reinterpreted later without a major
+ * format version.
  *
  * **Ids are permanent once published.** Add to {@link KNOWN_PAYLOAD_CODEC_IDS} when a codec ships; never
  * reuse or renumber. Ids are deliberately *not* pre-allocated for codecs that do not exist — a reserved number
@@ -74,8 +72,8 @@ export declare const PAYLOAD_CODEC_ROARING_PORTABLE = 1;
 /**
  * Every payload codec id this reader can decode.
  *
- * The reader validates membership rather than equality with a single constant. That is the whole point of the
- * generalization: an unknown id is rejected with a typed error naming it, so an old reader meeting a
+ * The reader validates membership rather than equality with a single constant. That is the whole point of an
+ * id registry: an unknown id is rejected with a typed error naming it, so an old reader meeting a
  * future-codec generation **fails closed** — the correct direction, and the reason a store built on one codec
  * can never silently misread another's bytes as its own. (The homogeneity contract means one store is one
  * codec, so meeting a foreign generation implies misconfiguration, and a loud rejection is exactly what you
@@ -107,7 +105,7 @@ export declare const MAX_CHUNK_CARDINALITY = 65536;
 /** Fixed width of a per-chunk CRC32C field in the index (high-entropy → not varint). */
 export declare const CRC32C_BYTES = 4;
 /**
- * v1 AEAD framing sizes (AES-256-GCM), fixed by the format exactly like the roaring serialization id — a
+ * v1 AEAD framing sizes (AES-256-GCM), fixed by the format exactly like the payload codec id — a
  * different cipher is a new format version. An encrypted chunk payload is stored as `nonce ‖ ciphertext ‖ tag`;
  * the encrypted **index**'s nonce/tag live in the footer's reserved `indexNonce`/`indexTag` slots. Matches
  * {@link FOOTER.indexNonce} (12 B) and {@link FOOTER.indexTag} (16 B).

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

@@ -37,7 +37,15 @@ export declare class CrbmReader {
     readonly servedFromTail: boolean;
     /** Set iff the object is encrypted — used to decrypt each chunk payload in {@link getChunk}. */
     private readonly crypto;
+    /** The footer's own CRC, as verified at open: it covers the index's CRC, the chunk count and the generation. */
+    private readonly footerCrc;
     private constructor();
+    /**
+     * Which object this reader opened, as its size and its footer's CRC. The footer covers the index's CRC, so two
+     * objects with the same fingerprint hold the same chunks, as far as a CRC can tell; a pin compares it to know that
+     * 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. */
     get sizeBytes(): number;
     /**
@@ -48,6 +56,15 @@ export declare class CrbmReader {
     get retainedIndexBytes(): number;
     /** Per-chunk cardinality (`chunkKey → count`) from the parsed index — no payload reads. */
     cardinalities(): Map<number, number>;
+    /**
+     * Whether the object behind `blob` is the one `fingerprint` names ({@link fingerprint}), from one tail read of a
+     * footer's worth, with no key and no index, since the footer is stored in the clear and checked by its own CRC.
+     * Another size is another object, whatever its bytes hold: a short one that is no `.crbm` at all is not the one
+     * pinned. At the same size the footer's CRC says, and a footer that fails its own checks says nothing about which
+     * object is there, so this throws, as an open would. What a pin asks, to tell the object it opened from one that
+     * has since been stored under its key, whoever wrote it.
+     */
+    static sameObject(blob: BlobReader, fingerprint: string): Promise<boolean>;
     static open(blob: BlobReader, options?: CrbmReaderOptions): Promise<CrbmReader>;
     /** Chunk keys present in this generation, ascending. */
     chunkKeys(): number[];
@@ -62,7 +79,7 @@ export declare class CrbmReader {
      */
     getChunk(chunkKey: number): Promise<Uint8Array | null>;
 }
-export declare function parseIndex(indexBytes: Uint8Array, objectSize: number, maxPayloadBytes: number): {
+export declare function parseIndex(indexBytes: Uint8Array, payloadEnd: number, maxPayloadBytes: number, minPayloadBytes?: number): {
     entries: Map<number, CrbmIndexEntry>;
     orderedKeys: number[];
     cardinalitySum: number;

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

@@ -6,8 +6,8 @@ export interface CrbmWriterOptions {
     /**
      * Which codec produced the chunk payloads. Defaults to {@link PAYLOAD_CODEC_ROARING_PORTABLE}.
      *
-     * Renamed from `roaringSerializationId` in 0.7.0 — same footer field, same offset and width, generalized
-     * because `.crbm` is a shared container and a second codec is expected before the format freezes.
+     * A codec id rather than a roaring-specific one, because `.crbm` is a shared container and a second codec is
+     * expected before the format freezes.
      */
     readonly payloadCodecId?: number;
     readonly elementWidth?: number;