@cloudbitmaps/core 0.11.0 → 0.11.2

package/README.md

@@ -7,7 +7,7 @@ when you install the two packages you want. Install those instead:
 pnpm add @cloudbitmaps/roaring @cloudbitmaps/s3   # the store, and the storage you have (or /gcs, or /azure-blob)
 ```
 
-On pnpm 10 and later, allow the one build script first, or the package throws at `import` while the install exits 0. Put this in your `package.json`: `{ "pnpm": { "onlyBuiltDependencies": ["roaring"] } }`. npm and pnpm 9 need nothing extra. [Details](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/getting-started.md#cannot-find-module-buildreleaseroaringnode-after-a-successful-install).
+On npm 12 and pnpm 10 and later, allow `roaring`'s one install script first, or the install exits 0 and the package throws at `import`. Put this in your `package.json`: `{ "allowScripts": { "roaring": true }, "pnpm": { "onlyBuiltDependencies": ["roaring"] } }`. npm 11 runs the script but warns until you allow it the same way; pnpm 9 needs nothing extra. [Details](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/getting-started.md#cannot-find-module-buildreleaseroaringnode-after-a-successful-install).
 
 Depend on `@cloudbitmaps/core` directly only to write a flavor or a driver.
 

package/dist/core/cost.d.ts

@@ -9,8 +9,8 @@ export interface PricingProfile {
         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.
+         * Default **1**, S3's, whose suffix-range GET returns the size with the bytes. **2** on Azure Blob,
+         * which reads the properties and then the bytes; GCS answers in one request, like S3. A chunk read knows its range, and is one request everywhere.
          */
         readonly requestsPerSizedRead?: number;
     };

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

@@ -1,12 +1,32 @@
 import type { BlobReader } from '../blob.js';
 import type { CrbmCrypto } from '../crypto.js';
-export interface CrbmIndexEntry {
-    readonly chunkKey: number;
-    readonly offset: number;
-    readonly length: number;
-    readonly cardinality: number;
-    readonly crc32c: number;
+/**
+ * A parsed index as parallel typed arrays, one slot per entry, ascending by key. Typed arrays hold each field at
+ * its own width with no per-entry object, so the retained heap is the arrays' byte length and nothing else.
+ * `cardinalityMinusOne` stores `cardinality - 1` because a chunk's cardinality runs `[1, 65536]` and 65,536 does
+ * not fit a `u16`; an offset is a `f64` because an object past 4 GiB puts a payload beyond a `u32`.
+ */
+export interface ParsedIndex {
+    readonly keys: Uint16Array;
+    readonly cardinalityMinusOne: Uint16Array;
+    readonly lengths: Uint32Array;
+    readonly crcs: Uint32Array;
+    readonly offsets: Float64Array;
+    /** Σ cardinality over every entry. */
+    readonly cardinalitySum: number;
 }
+/**
+ * Retained JS heap for one parsed index entry, in bytes: the `u16` key, the `u16` cardinality-minus-one, the `u32`
+ * length, the `u32` CRC and the `f64` offset of {@link ParsedIndex}. It is the exact byte length of the arrays
+ * (checked against the measured heap by a test), and weights the reader-cache byte bound
+ * ({@link CrbmReader.retainedIndexBytes}).
+ */
+export declare const RETAINED_BYTES_PER_INDEX_ENTRY = 20;
+/**
+ * How many entries `parseIndex` makes room for, from the index's length alone: what its bytes could hold at the
+ * smallest record, and never more than one entry per 16-bit key. A hostile index cannot make the reader allocate more.
+ */
+export declare function indexCapacity(indexLength: number): number;
 export interface CrbmReaderOptions {
     /** Speculative tail size in bytes (default 256 KB; clamped up to at least the footer size). */
     readonly tailBytes?: number;
@@ -31,8 +51,7 @@ export declare class CrbmReader {
     /** See {@link CrbmReaderOptions.lineage} — carried, never interpreted. */
     readonly lineage: unknown;
     readonly totalCardinality: number;
-    private readonly entries;
-    private readonly orderedKeys;
+    private readonly index;
     /** True when `open()` satisfied the index from the tail GET alone (no second range read). */
     readonly servedFromTail: boolean;
     /** Set iff the object is encrypted — used to decrypt each chunk payload in {@link getChunk}. */
@@ -49,9 +68,9 @@ export declare class CrbmReader {
     /** Total object bytes (from the one-GET tail read) — for grounded storage cost. */
     get sizeBytes(): number;
     /**
-     * Estimated retained JS heap of this reader's parsed index — the weight the storage reader cache bounds on
-     * (a wide segment's parsed index, not its payloads, dominates the reader's footprint). `entries.size` scales with the number
-     * of resident chunks (≤ 65536), so this is `entries.size × {@link RETAINED_BYTES_PER_INDEX_ENTRY}`.
+     * Retained JS heap of this reader's parsed index — the weight the storage reader cache bounds on (a wide
+     * segment's parsed index, not its payloads, dominates the reader's footprint): the exact byte length of the
+     * arrays that hold it, {@link RETAINED_BYTES_PER_INDEX_ENTRY} per entry.
      */
     get retainedIndexBytes(): number;
     /** Per-chunk cardinality (`chunkKey → count`) from the parsed index — no payload reads. */
@@ -70,6 +89,8 @@ export declare class CrbmReader {
     chunkKeys(): number[];
     /** Segment cardinality from the footer (no payload reads) — the cheap `count()` path. */
     count(): number;
+    /** The slot holding `chunkKey` (binary search over the ascending keys), or -1 when this generation has none. */
+    private slotOf;
     has(chunkKey: number): boolean;
     /**
      * Range-GET one chunk's payload, verifying its CRC32C before returning. Returns `null` if the chunk is
@@ -79,8 +100,4 @@ export declare class CrbmReader {
      */
     getChunk(chunkKey: number): Promise<Uint8Array | null>;
 }
-export declare function parseIndex(indexBytes: Uint8Array, payloadEnd: number, maxPayloadBytes: number, minPayloadBytes?: number): {
-    entries: Map<number, CrbmIndexEntry>;
-    orderedKeys: number[];
-    cardinalitySum: number;
-};
+export declare function parseIndex(indexBytes: Uint8Array, payloadEnd: number, maxPayloadBytes: number, minPayloadBytes?: number): ParsedIndex;

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

@@ -56,7 +56,7 @@ export interface CrbmStorageChunkSourceOptions extends CrbmReaderOptions {
     /**
      * Aggregate byte ceiling on the parsed `.crbm` indices resident in the reader cache (default 64 MiB) — the
      * **second half of that memory bound**. `maxOpenSegments` alone bounds by *count*, but a wide/dense segment's
-     * parsed index can be several MB, so 1024 wide indices could pin ~GBs and blow a small heap (e.g. a 128 MB
+     * parsed index can reach about 1.3 MB, so 1024 wide indices could pin over a GB and blow a small heap (e.g. a 128 MB
      * Lambda) while the count is nominally "in bounds". This caps the summed {@link CrbmReader.retainedIndexBytes}
      * across cached readers; the least-recently-used reader is evicted once the total would exceed it — whichever
      * of the count/byte bounds binds first. Lower it for memory-tight deployments with wide segments; a single

package/dist/core/engine.d.ts

@@ -89,8 +89,11 @@ export declare class SegmentEngine {
     get pointerRefreshMs(): number | undefined;
     /** Grounded Storage size of a segment's current generation (cost reporting), or null if it has no generation. */
     segmentSize(seg: SegmentRef): Promise<SegmentSize | null>;
+    /** The chunks of `seg` at `chunkKeys`, read through a window of {@link DEFAULT_INTERSECT_CONCURRENCY}. */
+    private chunkWindow;
     /**
-     * Every id, ascending, one chunk at a time; with `range`, only the ids in `(after, through]`, fetching only the
+     * Every id, ascending, reading ahead through a window of up to 8 chunk fetches that opens 1, 2, 4, 8 wide, so a
+     * read that stops early has fetched only a handful of chunks past the one it stopped in; with `range`, only the ids in `(after, through]`, fetching only the
      * chunks the range overlaps (see {@link IdRange}).
      *
      * Two generators, not one with a branch: a second `yield` site in the full read's generator grows its frame, and
@@ -124,7 +127,7 @@ export declare class SegmentEngine {
      * up front (before the fan-out) and threaded into every chunk read, so a concurrent load can't corrupt or tear
      * the result — every chunk read is a whole, checksum-verified, immutable generation. The edge a *long* call can
      * hit is invariant 3's: if it straddles a mid-call `cache.genTtlMs` boundary and a load has published, an
-     * operand's not-yet-read chunks may re-resolve forward to the newer generation (a generation hop within one long
+     * operand's not-yet-requested chunks may re-resolve forward to the newer generation (a generation hop within one long
      * call) — the call never crashes or returns a torn object, but may mix generations. Three things hop it without
      * waiting for the TTL, so a shorter call can meet them too: **the reader cache evicting an operand mid-call**
      * (`maxOpenSegments`), whose re-read re-resolves fresh; a sweep deleting the generation it was reading, which

package/dist/driver-kit.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/drivers/_shared/object-registry-keys.ts", "../src/drivers/_shared/object-registry.ts"],
-  "sourcesContent": ["/**\n * The registry object layout, shared by every object-store registry (S3, GCS, Azure Blob).\n *\n * One tiny JSON object per segment at `<prefix>registry/<ns>/<segment>.reg`, **registry-first** \u2014 separate\n * from the namespace-first storage layout (`<prefix><ns>/segments/\u2026`) \u2014 so discovery is a single list over\n * `registry/` for all namespaces, or `registry/<ns>/` for one, never entangled with the `.crbm` payloads.\n *\n * It lives here rather than in a driver because all three object stores encode names the same way\n * (`encodeNameForKey`, `namespaceKeyPart`) and build byte-identical keys. Three copies of this would be\n * three chances for one cloud's layout to drift from the others \u2014 and a drifted key is not a visible bug, it\n * is a segment that quietly cannot be found by a store pointed at the same bucket.\n */\nimport { ValidationError } from '@/core/errors';\nimport { validateSegmentRef } from '@/core/validate';\nimport type { SegmentRef } from '@/core/ports';\nimport { DEFAULT_NAMESPACE, decodeNameFromKey, encodeNameForKey, namespaceKeyPart } from './keys';\n\nconst REGISTRY_SUFFIX = '.reg';\n\n/** Normalize an optional caller prefix to either `''` or `trimmed/` (no leading/trailing slashes). */\nexport function prefixPart(prefix: string | undefined): string {\n  if (prefix === undefined) return '';\n  const trimmed = prefix.replace(/^\\/+|\\/+$/g, '');\n  return trimmed === '' ? '' : `${trimmed}/`;\n}\n\n/**\n * Validate a caller-supplied key prefix (trusted config, but make it a real containment boundary): reject\n * control characters and `.`/`..` path segments so a prefix cannot traverse out of its intended space.\n * Returns it unchanged \u2014 the key builders normalize slashes.\n *\n * The traversal check covers three spellings, because the tools that walk these buckets do. A bare `..` is\n * the obvious one. A **backslash** segment matters on ADLS Gen2 and to Windows-side tooling, which treat it\n * as a separator this code otherwise would not. And a percent-encoded `..` matters because `gsutil`,\n * `s3fs`, `gcsfuse` and `azcopy` decode a key on their way to a local path \u2014 the same reasoning\n * `name-codec.ts` already applies to segment names, which a prefix has no reason to be exempt from.\n */\nexport function normalizeObjectPrefix(prefix: string | undefined): string | undefined {\n  if (prefix === undefined) return undefined;\n  for (const ch of prefix) {\n    const code = ch.charCodeAt(0);\n    // C0 plus DEL: a bare `< 0x20` lets U+007F through, and it is as unprintable as the rest.\n    if (code < 0x20 || code === 0x7f) {\n      throw new ValidationError('prefix must not contain control characters');\n    }\n  }\n  if (prefix.includes('\\\\')) {\n    throw new ValidationError(\n      `prefix must not contain backslashes (a path separator on some backends): ${JSON.stringify(prefix)}`,\n    );\n  }\n  // Check the decoded spelling too, so an encoded `..` cannot slip past the literal comparison.\n  let decoded: string;\n  try {\n    decoded = decodeURIComponent(prefix);\n  } catch {\n    decoded = prefix; // not valid percent-encoding; the literal check still applies\n  }\n  for (const source of decoded === prefix ? [prefix] : [prefix, decoded]) {\n    for (const segment of source.split('/')) {\n      if (segment === '.' || segment === '..') {\n        throw new ValidationError(\n          `prefix must not contain \".\" or \"..\" path segments: ${JSON.stringify(prefix)}`,\n        );\n      }\n    }\n  }\n  return prefix;\n}\n\n/** The key prefix under which every registry object lives: `<prefix>registry/`. */\nexport function registryPrefix(prefix: string | undefined): string {\n  return `${prefixPart(prefix)}registry/`;\n}\n\n/** The full key of one segment's registry object: `<prefix>registry/<ns>/<segment>.reg`. */\nexport function registryObjectKey(prefix: string | undefined, ref: SegmentRef): string {\n  validateSegmentRef(ref);\n  return `${registryPrefix(prefix)}${namespaceKeyPart(ref.namespace)}/${encodeNameForKey(ref.segment)}${REGISTRY_SUFFIX}`;\n}\n\n/** The list prefix for discovery: registry-wide, or scoped to one namespace. */\nexport function registryListPrefix(prefix: string | undefined, namespace?: string): string {\n  const base = registryPrefix(prefix);\n  return namespace === undefined ? base : `${base}${namespaceKeyPart(namespace)}/`;\n}\n\n/**\n * Parse a `<prefix>registry/<ns>/<segment>.reg` key back to its {@link SegmentRef}, or `null` if it does not\n * match \u2014 a stray or foreign object under the prefix, or one whose parsed ref fails the round-trip check.\n * `_default` maps back to the absent namespace. A name is percent-encoded on the way in, so no encoded name\n * can contain `/` and the split stays unambiguous whatever the caller named their segment.\n */\nexport function parseRegistryKey(prefix: string | undefined, objectKey: string): SegmentRef | null {\n  const base = registryPrefix(prefix);\n  if (!objectKey.startsWith(base) || !objectKey.endsWith(REGISTRY_SUFFIX)) return null;\n  const rest = objectKey.slice(base.length, objectKey.length - REGISTRY_SUFFIX.length);\n  const slash = rest.indexOf('/');\n  if (slash < 0) return null;\n  const nsPart = rest.slice(0, slash);\n  const encodedSegment = rest.slice(slash + 1);\n  if (encodedSegment.length === 0 || encodedSegment.includes('/')) return null;\n  const segment = decodeNameFromKey(encodedSegment);\n  const namespace = nsPart === DEFAULT_NAMESPACE ? undefined : decodeNameFromKey(nsPart);\n  // The encoding must ROUND-TRIP, not merely decode: a foreign object placed under our prefix could spell a\n  // name two ways, and reporting both would hand a sweep one segment under two identities.\n  if (encodeNameForKey(segment) !== encodedSegment) return null;\n  if (namespace !== undefined && encodeNameForKey(namespace) !== nsPart) return null;\n  const ref: SegmentRef = { segment, namespace };\n  try {\n    validateSegmentRef(ref); // reject a hostile/foreign key that isn't a valid ref\n  } catch {\n    return null;\n  }\n  return ref;\n}\n", "/**\n * `ObjectStoreRegistry` \u2014 an {@link IRegistryDriver} over any object store with conditional writes.\n *\n * Lets a **read-mostly deployment run on one bucket alone** \u2014 storage `.crbm` generations plus the registry in\n * the same place, with no separate database. One tiny JSON object per segment at\n * `<prefix>registry/<ns>/<segment>.reg` holding the `{ deleted, record }` envelope (the same shape LocalFs\n * persists). The OCC token is a monotonic counter, advanced on every mutation and even across a `delete`\n * (which **tombstones** rather than removes the object) so a deleted-then-recreated row never re-issues an\n * old token (ABA-safe) \u2014 identical semantics to the LocalFs registry, so it passes the same conformance suite.\n *\n * **The atomic swap is offloaded to the store's conditional writes.** `create` writes only if absent (or\n * over a tombstone under its version), and `compareAndSwap`/`delete` write only if the object still carries\n * the version we read \u2014 so a concurrent writer between our read and our write loses, and the loss surfaces\n * as {@link WriteConflictError}. No in-process lock is needed (unlike LocalFs): the precondition fences\n * writers *across processes*.\n *\n * **Why this is shared rather than written per cloud.** Every object store worth using has the same two\n * primitives under different names \u2014 S3 `If-None-Match: *` / `If-Match: <etag>`, GCS `ifGenerationMatch: 0`\n * / `ifGenerationMatch: <generation>`, Azure `If-None-Match: *` / `If-Match: <etag>` \u2014 so the only thing\n * that differs is three I/O calls, which is what {@link ObjectRegistryStore} abstracts. The parts that are\n * genuinely hard (the ABA-safe counter, the tombstone, the bounded delete retry, the round-trip key check)\n * exist once. Three copies would be three chances for one cloud to drift, and a drifted registry is not a\n * visible bug \u2014 it is a lost `currentGen` swap.\n *\n * **Deployment requirements** (a backend that violates these silently corrupts the registry):\n * - The store **must honor the conditional write**. One that accepts the precondition header and ignores it\n *   degrades compare-and-swap to last-write-wins \u2192 lost `currentGen` swaps.\n * - Reads must be **strongly consistent** \u2014 true of S3 (since 2020), GCS and Azure Blob \u2014 since the registry\n *   advertises `strongRead` and generation resolution depends on it.\n * - **Do not apply a lifecycle-expiration rule to the `registry/` prefix that expires a current version.**\n *   `delete` tombstones (keeps the object with an advanced counter) for ABA-safety; expiring a tombstone would let a recreate reset the\n *   token to 0 and re-issue a stale one.\n *\n * **`list()` is fail-closed, and one bad object stops it for everyone.** An object under the `registry/`\n * prefix whose key parses but whose body does not aborts the whole enumeration \u2014 every namespace, not just\n * the affected segment \u2014 and it stays that way until an operator removes the object. The error names the\n * offending key.\n *\n * That is the deliberate choice, and it is the *safer* one rather than the more convenient one. Skipping the\n * unreadable row would keep discovery running, but `list()` is what tells orphan generation collection which\n * segments exist: a row missing from the enumeration makes its storage `.crbm` generations look unreferenced,\n * and the next GC pass would delete them. Silently skipping turns a parse error into data loss. Refusing to\n * enumerate keeps every sweep off a set it cannot vouch for (invariant 5 \u2014 bytes from the tier are\n * untrusted). **Recovery:** read the named object, and either restore a valid envelope or delete it; nothing\n * else is damaged, and discovery resumes on its own.\n */\nimport {\n  IntegrityError,\n  TransientError,\n  ValidationError,\n  WriteConflictError,\n  isWriteConflictError,\n} from '@/core/errors';\nimport type {\n  IRegistryDriver,\n  NewRegistryRecord,\n  RegCaps,\n  RegistryPatch,\n  RegistryRecord,\n  SegmentRef,\n  Token,\n} from '@/core/ports';\nimport { mapWithConcurrency } from '@/core/concurrency';\nimport {\n  applyRegistryPatch,\n  parseRegistryEnvelope,\n  recordFromNew,\n  registryCounterOf,\n  serializeRegistryEnvelope,\n  validateNewRegistryRecord,\n  validateRegistryPatch,\n  type RegistryEnvelope,\n} from './registry';\nimport { parseRegistryKey, registryListPrefix, registryObjectKey } from './object-registry-keys';\n\n/** Defensive cap on a single registry object read from storage, before allocation (rows are tiny; ~1 KB). */\nexport const MAX_ROW_BYTES = 1 * 1024 * 1024;\n/** Bounded retry for `delete`'s read\u2192tombstone under cross-process contention (converges; then fails typed). */\nconst MAX_DELETE_ATTEMPTS = 8;\n/** Bounded re-read when a store's pinned version is overwritten mid-read (see {@link ObjectVersionRaced}). */\nconst MAX_READ_ATTEMPTS = 8;\n/** In-flight reads per `list()` page \u2014 turns the serial N+1 into one list plus bounded parallel reads. */\nconst LIST_READ_CONCURRENCY = 16;\n\n/**\n * Raised by a store when the version it pinned for a read vanished before it could fetch the bytes \u2014\n * a concurrent writer overwrote or deleted the object in between.\n *\n * This is deliberately **neither** of the two things it superficially resembles. It is not absence: the row\n * is very likely still live, just one version further on. And it is not a write conflict: the caller may be\n * a read-only `get()`, which has nothing to conflict with. Either is an easy misreading for a store that reads a\n * row in two calls, as the GCS and Azure Blob stores do, which is why the signal is part of the port rather than\n * left to each store's judgement. {@link ObjectStoreRegistry} answers it the only way that is correct for every\n * caller: it reads again.\n *\n * Stores whose read is atomic (S3 serves bytes and `ETag` from one `GetObject`) can never raise it.\n */\nexport class ObjectVersionRaced extends Error {\n  constructor(objectKey: string) {\n    super(`registry object was overwritten mid-read: ${objectKey}`);\n    this.name = 'ObjectVersionRaced';\n  }\n}\n\n/** One object as read, with the opaque version that fences a later conditional write. */\nexport interface ObjectRow {\n  readonly bytes: Uint8Array;\n  /** The store's version fence \u2014 an S3/Azure ETag, a GCS generation. Opaque to this class. */\n  readonly version: string;\n}\n\n/**\n * The three I/O calls an object store must provide to host a registry. Everything else \u2014 the OCC counter,\n * tombstones, the delete retry, key parsing \u2014 is implemented once above.\n */\nexport interface ObjectRegistryStore {\n  /** A label for error messages, e.g. `GCS` or `Azure Blob`. */\n  readonly label: string;\n  /**\n   * Read one object, or `null` when it is absent.\n   *\n   * **`null` means the object does not exist** \u2014 nothing weaker. A store that reads in two round trips\n   * (metadata for the version fence, then the bytes pinned to it) can find that version already gone; it\n   * MUST report that with {@link ObjectVersionRaced} rather than `null` or {@link WriteConflictError}, and\n   * the caller re-reads. Retryable faults throw {@link TransientError}.\n   *\n   * `bytes` and `version` MUST describe the **same** observation of the object: `version` is the fence a\n   * later conditional write is conditioned on, so a pair drawn from two different versions would either\n   * fail a write that should have succeeded or, worse, pass one that should not.\n   */\n  read(key: string): Promise<ObjectRow | null>;\n  /**\n   * Write one object under a precondition: `'absent'` means create-only, a version means\n   * compare-and-swap against exactly that version. A lost race MUST throw {@link WriteConflictError}.\n   *\n   * A store must not replay this write after a lost response without telling the replay apart: the replay meets\n   * the row it just wrote and its precondition fails, which would read as a lost race. Send it once, or store a\n   * write id with the row and treat a conflict whose stored row carries it as success. Retryable faults throw\n   * {@link TransientError}.\n   */\n  write(key: string, body: Uint8Array, expect: 'absent' | { version: string }): Promise<void>;\n  /** Every object key under `prefix`, paginated internally. */\n  listKeys(prefix: string): AsyncIterable<string>;\n}\n\nexport class ObjectStoreRegistry implements IRegistryDriver {\n  constructor(\n    private readonly store: ObjectRegistryStore,\n    private readonly prefix: string | undefined,\n    private readonly now: () => number,\n  ) {}\n\n  capabilities(): RegCaps {\n    return { strongRead: true };\n  }\n\n  async get(ref: SegmentRef): Promise<RegistryRecord | null> {\n    const current = await this.readRow(registryObjectKey(this.prefix, ref));\n    return current && !current.env.deleted ? current.env.record : null;\n  }\n\n  async create(ref: SegmentRef, record: NewRegistryRecord): Promise<{ token: Token }> {\n    validateNewRegistryRecord(record);\n    const key = registryObjectKey(this.prefix, ref);\n    const current = await this.readRow(key);\n    if (current !== null && !current.env.deleted) {\n      throw new WriteConflictError(`registry row already exists for segment ${ref.segment}`);\n    }\n    // Advance across a tombstone so a recreate never re-issues an old token (ABA-safe).\n    const token = String(current ? registryCounterOf(current.env.record) + 1 : 0);\n    const env: RegistryEnvelope = {\n      deleted: false,\n      record: recordFromNew(ref, record, this.now(), token),\n    };\n    // Create-only when truly absent; overwrite the tombstone under its version when recreating. Either way\n    // a concurrent create loses the precondition and surfaces as a conflict.\n    await this.putRow(key, env, current ? { version: current.version } : 'absent');\n    return { token };\n  }\n\n  async compareAndSwap(\n    ref: SegmentRef,\n    expected: Token,\n    patch: RegistryPatch,\n  ): Promise<{ token: Token }> {\n    validateRegistryPatch(patch);\n    const key = registryObjectKey(this.prefix, ref);\n    const current = await this.readRow(key);\n    if (current === null || current.env.deleted || current.env.record.token !== expected) {\n      throw new WriteConflictError(`OCC token mismatch for registry row ${ref.segment}`);\n    }\n    const token = String(registryCounterOf(current.env.record) + 1);\n    const env: RegistryEnvelope = {\n      deleted: false,\n      record: applyRegistryPatch(current.env.record, patch, this.now(), token),\n    };\n    // The version we read fences a concurrent writer between that read and this write.\n    await this.putRow(key, env, { version: current.version });\n    return { token };\n  }\n\n  async *list(namespace?: string): AsyncIterable<RegistryRecord> {\n    const prefix = registryListPrefix(this.prefix, namespace);\n    // One list plus bounded parallel reads. A serial await-in-loop made this O(N) sequential round trips.\n    let page: string[] = [];\n    const flush = async function* (\n      this: ObjectStoreRegistry,\n      keys: string[],\n    ): AsyncIterable<RegistryRecord> {\n      const rows = await mapWithConcurrency(keys, LIST_READ_CONCURRENCY, (key) =>\n        this.readRow(key),\n      );\n      for (const current of rows) {\n        if (current && !current.env.deleted) yield current.env.record;\n      }\n    }.bind(this);\n\n    for await (const key of this.store.listKeys(prefix)) {\n      if (parseRegistryKey(this.prefix, key) === null) continue; // stray or foreign object\n      page.push(key);\n      if (page.length >= LIST_READ_CONCURRENCY) {\n        yield* flush(page);\n        page = [];\n      }\n    }\n    if (page.length > 0) yield* flush(page);\n  }\n\n  async delete(ref: SegmentRef, expected?: Token): Promise<void> {\n    const key = registryObjectKey(this.prefix, ref);\n    // Tombstone (advance the counter) rather than remove the object \u2014 keeps the token monotonic for\n    // ABA-safety. Retry the read\u2192tombstone on a cross-process race; it converges, then fails typed rather\n    // than silently leaving the row live.\n    for (let attempt = 0; attempt < MAX_DELETE_ATTEMPTS; attempt++) {\n      const current = await this.readRow(key);\n      if (expected !== undefined) {\n        // Fenced: the row must still carry the token the caller read. Re-checked on every attempt, so a row\n        // that was swapped, or deleted and re-created, between two attempts is refused rather than tombstoned.\n        if (current === null || current.env.deleted || current.env.record.token !== expected) {\n          throw new WriteConflictError(`OCC token mismatch for registry row ${ref.segment}`);\n        }\n      } else if (current === null || current.env.deleted) {\n        return; // idempotent \u2014 already gone\n      }\n      const token = String(registryCounterOf(current.env.record) + 1);\n      const env: RegistryEnvelope = {\n        deleted: true,\n        record: { ...current.env.record, token, updatedAt: this.now() },\n      };\n      try {\n        await this.putRow(key, env, { version: current.version });\n        return;\n      } catch (err) {\n        if (isWriteConflictError(err)) continue; // raced \u2014 re-read and re-tombstone\n        throw err;\n      }\n    }\n    throw new WriteConflictError(\n      `registry delete: contention tombstoning \"${ref.segment}\" \u2014 retry`,\n    );\n  }\n\n  /**\n   * Read + parse a registry object, returning its envelope and version fence, or null if absent.\n   *\n   * A store that pins a version to read consistently ({@link ObjectVersionRaced}) loses that pin whenever a\n   * concurrent writer lands mid-read. Re-reading is the whole answer \u2014 the next read simply observes the\n   * newer version \u2014 and it is bounded so a row under permanent write saturation fails typed instead of\n   * spinning. Only a store racing itself gets here; S3 never does.\n   */\n  private async readRow(\n    objectKey: string,\n  ): Promise<{ env: RegistryEnvelope; version: string } | null> {\n    const row = await this.readRaced(objectKey);\n    if (row === null) return null;\n    if (row.bytes.length > MAX_ROW_BYTES) {\n      throw new IntegrityError(\n        `registry object ${row.bytes.length}B exceeds cap ${MAX_ROW_BYTES}B`,\n      );\n    }\n    if (row.version.length === 0) {\n      // The version is the OCC fence for CAS; a backend that omits it cannot be used safely as a registry.\n      throw new IntegrityError(\n        `registry object has no version fence (needed for compare-and-swap): ${objectKey}`,\n      );\n    }\n    const env = parseRegistryEnvelope(new TextDecoder().decode(row.bytes), objectKey);\n    return { env, version: row.version };\n  }\n\n  /** {@link ObjectRegistryStore.read}, retrying the bounded number of times a mid-read overwrite allows. */\n  private async readRaced(objectKey: string): Promise<ObjectRow | null> {\n    for (let attempt = 0; attempt < MAX_READ_ATTEMPTS; attempt++) {\n      try {\n        return await this.store.read(objectKey);\n      } catch (err) {\n        if (!(err instanceof ObjectVersionRaced)) throw err;\n      }\n    }\n    throw new TransientError(\n      `registry read: ${this.store.label} object \"${objectKey}\" was overwritten on every one of ` +\n        `${MAX_READ_ATTEMPTS} attempts \u2014 retry`,\n    );\n  }\n\n  /** Conditional write of an envelope. The store maps a lost precondition to {@link WriteConflictError}. */\n  private async putRow(\n    objectKey: string,\n    env: RegistryEnvelope,\n    expect: 'absent' | { version: string },\n  ): Promise<void> {\n    const body = new TextEncoder().encode(serializeRegistryEnvelope(env));\n    if (body.length > MAX_ROW_BYTES) {\n      // Belt-and-braces: the governance/DEK fields are already capped by validate*, so this cannot fire for\n      // valid input \u2014 but never write a row that would later be unreadable.\n      throw new ValidationError(`registry object ${body.length}B exceeds cap ${MAX_ROW_BYTES}B`);\n    }\n    await this.store.write(objectKey, body, expect);\n  }\n}\n"],
+  "sourcesContent": ["/**\n * The registry object layout, shared by every object-store registry (S3, GCS, Azure Blob).\n *\n * One tiny JSON object per segment at `<prefix>registry/<ns>/<segment>.reg`, **registry-first** \u2014 separate\n * from the namespace-first storage layout (`<prefix><ns>/segments/\u2026`) \u2014 so discovery is a single list over\n * `registry/` for all namespaces, or `registry/<ns>/` for one, never entangled with the `.crbm` payloads.\n *\n * It lives here rather than in a driver because all three object stores encode names the same way\n * (`encodeNameForKey`, `namespaceKeyPart`) and build byte-identical keys. Three copies of this would be\n * three chances for one cloud's layout to drift from the others \u2014 and a drifted key is not a visible bug, it\n * is a segment that quietly cannot be found by a store pointed at the same bucket.\n */\nimport { ValidationError } from '@/core/errors';\nimport { validateSegmentRef } from '@/core/validate';\nimport type { SegmentRef } from '@/core/ports';\nimport { DEFAULT_NAMESPACE, decodeNameFromKey, encodeNameForKey, namespaceKeyPart } from './keys';\n\nconst REGISTRY_SUFFIX = '.reg';\n\n/** Normalize an optional caller prefix to either `''` or `trimmed/` (no leading/trailing slashes). */\nexport function prefixPart(prefix: string | undefined): string {\n  if (prefix === undefined) return '';\n  const trimmed = prefix.replace(/^\\/+|\\/+$/g, '');\n  return trimmed === '' ? '' : `${trimmed}/`;\n}\n\n/**\n * Validate a caller-supplied key prefix (trusted config, but make it a real containment boundary): reject\n * control characters and `.`/`..` path segments so a prefix cannot traverse out of its intended space.\n * Returns it unchanged \u2014 the key builders normalize slashes.\n *\n * The traversal check covers three spellings, because the tools that walk these buckets do. A bare `..` is\n * the obvious one. A **backslash** segment matters on ADLS Gen2 and to Windows-side tooling, which treat it\n * as a separator this code otherwise would not. And a percent-encoded `..` matters because `gsutil`,\n * `s3fs`, `gcsfuse` and `azcopy` decode a key on their way to a local path \u2014 the same reasoning\n * `name-codec.ts` already applies to segment names, which a prefix has no reason to be exempt from.\n */\nexport function normalizeObjectPrefix(prefix: string | undefined): string | undefined {\n  if (prefix === undefined) return undefined;\n  for (const ch of prefix) {\n    const code = ch.charCodeAt(0);\n    // C0 plus DEL: a bare `< 0x20` lets U+007F through, and it is as unprintable as the rest.\n    if (code < 0x20 || code === 0x7f) {\n      throw new ValidationError('prefix must not contain control characters');\n    }\n  }\n  if (prefix.includes('\\\\')) {\n    throw new ValidationError(\n      `prefix must not contain backslashes (a path separator on some backends): ${JSON.stringify(prefix)}`,\n    );\n  }\n  // Check the decoded spelling too, so an encoded `..` cannot slip past the literal comparison.\n  let decoded: string;\n  try {\n    decoded = decodeURIComponent(prefix);\n  } catch {\n    decoded = prefix; // not valid percent-encoding; the literal check still applies\n  }\n  for (const source of decoded === prefix ? [prefix] : [prefix, decoded]) {\n    for (const segment of source.split('/')) {\n      if (segment === '.' || segment === '..') {\n        throw new ValidationError(\n          `prefix must not contain \".\" or \"..\" path segments: ${JSON.stringify(prefix)}`,\n        );\n      }\n    }\n  }\n  return prefix;\n}\n\n/** The key prefix under which every registry object lives: `<prefix>registry/`. */\nexport function registryPrefix(prefix: string | undefined): string {\n  return `${prefixPart(prefix)}registry/`;\n}\n\n/** The full key of one segment's registry object: `<prefix>registry/<ns>/<segment>.reg`. */\nexport function registryObjectKey(prefix: string | undefined, ref: SegmentRef): string {\n  validateSegmentRef(ref);\n  return `${registryPrefix(prefix)}${namespaceKeyPart(ref.namespace)}/${encodeNameForKey(ref.segment)}${REGISTRY_SUFFIX}`;\n}\n\n/** The list prefix for discovery: registry-wide, or scoped to one namespace. */\nexport function registryListPrefix(prefix: string | undefined, namespace?: string): string {\n  const base = registryPrefix(prefix);\n  return namespace === undefined ? base : `${base}${namespaceKeyPart(namespace)}/`;\n}\n\n/**\n * Parse a `<prefix>registry/<ns>/<segment>.reg` key back to its {@link SegmentRef}, or `null` if it does not\n * match \u2014 a stray or foreign object under the prefix, or one whose parsed ref fails the round-trip check.\n * `_default` maps back to the absent namespace. A name is percent-encoded on the way in, so no encoded name\n * can contain `/` and the split stays unambiguous whatever the caller named their segment.\n */\nexport function parseRegistryKey(prefix: string | undefined, objectKey: string): SegmentRef | null {\n  const base = registryPrefix(prefix);\n  if (!objectKey.startsWith(base) || !objectKey.endsWith(REGISTRY_SUFFIX)) return null;\n  const rest = objectKey.slice(base.length, objectKey.length - REGISTRY_SUFFIX.length);\n  const slash = rest.indexOf('/');\n  if (slash < 0) return null;\n  const nsPart = rest.slice(0, slash);\n  const encodedSegment = rest.slice(slash + 1);\n  if (encodedSegment.length === 0 || encodedSegment.includes('/')) return null;\n  const segment = decodeNameFromKey(encodedSegment);\n  const namespace = nsPart === DEFAULT_NAMESPACE ? undefined : decodeNameFromKey(nsPart);\n  // The encoding must ROUND-TRIP, not merely decode: a foreign object placed under our prefix could spell a\n  // name two ways, and reporting both would hand a sweep one segment under two identities.\n  if (encodeNameForKey(segment) !== encodedSegment) return null;\n  if (namespace !== undefined && encodeNameForKey(namespace) !== nsPart) return null;\n  const ref: SegmentRef = { segment, namespace };\n  try {\n    validateSegmentRef(ref); // reject a hostile/foreign key that isn't a valid ref\n  } catch {\n    return null;\n  }\n  return ref;\n}\n", "/**\n * `ObjectStoreRegistry` \u2014 an {@link IRegistryDriver} over any object store with conditional writes.\n *\n * Lets a **read-mostly deployment run on one bucket alone** \u2014 storage `.crbm` generations plus the registry in\n * the same place, with no separate database. One tiny JSON object per segment at\n * `<prefix>registry/<ns>/<segment>.reg` holding the `{ deleted, record }` envelope (the same shape LocalFs\n * persists). The OCC token is a monotonic counter, advanced on every mutation and even across a `delete`\n * (which **tombstones** rather than removes the object) so a deleted-then-recreated row never re-issues an\n * old token (ABA-safe) \u2014 identical semantics to the LocalFs registry, so it passes the same conformance suite.\n *\n * **The atomic swap is offloaded to the store's conditional writes.** `create` writes only if absent (or\n * over a tombstone under its version), and `compareAndSwap`/`delete` write only if the object still carries\n * the version we read \u2014 so a concurrent writer between our read and our write loses, and the loss surfaces\n * as {@link WriteConflictError}. No in-process lock is needed (unlike LocalFs): the precondition fences\n * writers *across processes*.\n *\n * **Why this is shared rather than written per cloud.** Every object store worth using has the same two\n * primitives under different names \u2014 S3 `If-None-Match: *` / `If-Match: <etag>`, GCS `ifGenerationMatch: 0`\n * / `ifGenerationMatch: <generation>`, Azure `If-None-Match: *` / `If-Match: <etag>` \u2014 so the only thing\n * that differs is three I/O calls, which is what {@link ObjectRegistryStore} abstracts. The parts that are\n * genuinely hard (the ABA-safe counter, the tombstone, the bounded delete retry, the round-trip key check)\n * exist once. Three copies would be three chances for one cloud to drift, and a drifted registry is not a\n * visible bug \u2014 it is a lost `currentGen` swap.\n *\n * **Deployment requirements** (a backend that violates these silently corrupts the registry):\n * - The store **must honor the conditional write**. One that accepts the precondition header and ignores it\n *   degrades compare-and-swap to last-write-wins \u2192 lost `currentGen` swaps.\n * - Reads must be **strongly consistent** \u2014 true of S3 (since 2020), GCS and Azure Blob \u2014 since the registry\n *   advertises `strongRead` and generation resolution depends on it.\n * - **Do not apply a lifecycle-expiration rule to the `registry/` prefix that expires a current version.**\n *   `delete` tombstones (keeps the object with an advanced counter) for ABA-safety; expiring a tombstone would let a recreate reset the\n *   token to 0 and re-issue a stale one.\n *\n * **`list()` is fail-closed, and one bad object stops it for everyone.** An object under the `registry/`\n * prefix whose key parses but whose body does not aborts the whole enumeration \u2014 every namespace, not just\n * the affected segment \u2014 and it stays that way until an operator removes the object. The error names the\n * offending key.\n *\n * That is the deliberate choice, and it is the *safer* one rather than the more convenient one. Skipping the\n * unreadable row would keep discovery running, but `list()` is what tells orphan generation collection which\n * segments exist: a row missing from the enumeration makes its storage `.crbm` generations look unreferenced,\n * and the next GC pass would delete them. Silently skipping turns a parse error into data loss. Refusing to\n * enumerate keeps every sweep off a set it cannot vouch for (invariant 5 \u2014 bytes from the tier are\n * untrusted). **Recovery:** read the named object, and either restore a valid envelope or delete it; nothing\n * else is damaged, and discovery resumes on its own.\n */\nimport {\n  IntegrityError,\n  TransientError,\n  ValidationError,\n  WriteConflictError,\n  isWriteConflictError,\n} from '@/core/errors';\nimport type {\n  IRegistryDriver,\n  NewRegistryRecord,\n  RegCaps,\n  RegistryPatch,\n  RegistryRecord,\n  SegmentRef,\n  Token,\n} from '@/core/ports';\nimport { mapWithConcurrency } from '@/core/concurrency';\nimport {\n  applyRegistryPatch,\n  parseRegistryEnvelope,\n  recordFromNew,\n  registryCounterOf,\n  serializeRegistryEnvelope,\n  validateNewRegistryRecord,\n  validateRegistryPatch,\n  type RegistryEnvelope,\n} from './registry';\nimport { parseRegistryKey, registryListPrefix, registryObjectKey } from './object-registry-keys';\n\n/** Defensive cap on a single registry object read from storage, before allocation (rows are tiny; ~1 KB). */\nexport const MAX_ROW_BYTES = 1 * 1024 * 1024;\n/** Bounded retry for `delete`'s read\u2192tombstone under cross-process contention (converges; then fails typed). */\nconst MAX_DELETE_ATTEMPTS = 8;\n/** Bounded re-read when a store's pinned version is overwritten mid-read (see {@link ObjectVersionRaced}). */\nconst MAX_READ_ATTEMPTS = 8;\n/** In-flight reads per `list()` page \u2014 turns the serial N+1 into one list plus bounded parallel reads. */\nconst LIST_READ_CONCURRENCY = 16;\n\n/**\n * Raised by a store when the version it pinned for a read vanished before it could fetch the bytes \u2014\n * a concurrent writer overwrote or deleted the object in between.\n *\n * This is deliberately **neither** of the two things it superficially resembles. It is not absence: the row\n * is very likely still live, just one version further on. And it is not a write conflict: the caller may be\n * a read-only `get()`, which has nothing to conflict with. Either is an easy misreading for a store that reads a\n * row in two calls, as the Azure Blob store does, which is why the signal is part of the port rather than\n * left to each store's judgement. {@link ObjectStoreRegistry} answers it the only way that is correct for every\n * caller: it reads again.\n *\n * Stores whose read is atomic (S3 serves bytes and `ETag` from one `GetObject`, GCS bytes and `generation` from one GET) can never raise it.\n */\nexport class ObjectVersionRaced extends Error {\n  constructor(objectKey: string) {\n    super(`registry object was overwritten mid-read: ${objectKey}`);\n    this.name = 'ObjectVersionRaced';\n  }\n}\n\n/** One object as read, with the opaque version that fences a later conditional write. */\nexport interface ObjectRow {\n  readonly bytes: Uint8Array;\n  /** The store's version fence \u2014 an S3/Azure ETag, a GCS generation. Opaque to this class. */\n  readonly version: string;\n}\n\n/**\n * The three I/O calls an object store must provide to host a registry. Everything else \u2014 the OCC counter,\n * tombstones, the delete retry, key parsing \u2014 is implemented once above.\n */\nexport interface ObjectRegistryStore {\n  /** A label for error messages, e.g. `GCS` or `Azure Blob`. */\n  readonly label: string;\n  /**\n   * Read one object, or `null` when it is absent.\n   *\n   * **`null` means the object does not exist** \u2014 nothing weaker. A store that reads in two round trips\n   * (metadata for the version fence, then the bytes pinned to it) can find that version already gone; it\n   * MUST report that with {@link ObjectVersionRaced} rather than `null` or {@link WriteConflictError}, and\n   * the caller re-reads. Retryable faults throw {@link TransientError}.\n   *\n   * `bytes` and `version` MUST describe the **same** observation of the object: `version` is the fence a\n   * later conditional write is conditioned on, so a pair drawn from two different versions would either\n   * fail a write that should have succeeded or, worse, pass one that should not.\n   */\n  read(key: string): Promise<ObjectRow | null>;\n  /**\n   * Write one object under a precondition: `'absent'` means create-only, a version means\n   * compare-and-swap against exactly that version. A lost race MUST throw {@link WriteConflictError}.\n   *\n   * A store must not replay this write after a lost response without telling the replay apart: the replay meets\n   * the row it just wrote and its precondition fails, which would read as a lost race. Send it once, or store a\n   * write id with the row and treat a conflict whose stored row carries it as success. Retryable faults throw\n   * {@link TransientError}.\n   */\n  write(key: string, body: Uint8Array, expect: 'absent' | { version: string }): Promise<void>;\n  /** Every object key under `prefix`, paginated internally. */\n  listKeys(prefix: string): AsyncIterable<string>;\n}\n\nexport class ObjectStoreRegistry implements IRegistryDriver {\n  constructor(\n    private readonly store: ObjectRegistryStore,\n    private readonly prefix: string | undefined,\n    private readonly now: () => number,\n  ) {}\n\n  capabilities(): RegCaps {\n    return { strongRead: true };\n  }\n\n  async get(ref: SegmentRef): Promise<RegistryRecord | null> {\n    const current = await this.readRow(registryObjectKey(this.prefix, ref));\n    return current && !current.env.deleted ? current.env.record : null;\n  }\n\n  async create(ref: SegmentRef, record: NewRegistryRecord): Promise<{ token: Token }> {\n    validateNewRegistryRecord(record);\n    const key = registryObjectKey(this.prefix, ref);\n    const current = await this.readRow(key);\n    if (current !== null && !current.env.deleted) {\n      throw new WriteConflictError(`registry row already exists for segment ${ref.segment}`);\n    }\n    // Advance across a tombstone so a recreate never re-issues an old token (ABA-safe).\n    const token = String(current ? registryCounterOf(current.env.record) + 1 : 0);\n    const env: RegistryEnvelope = {\n      deleted: false,\n      record: recordFromNew(ref, record, this.now(), token),\n    };\n    // Create-only when truly absent; overwrite the tombstone under its version when recreating. Either way\n    // a concurrent create loses the precondition and surfaces as a conflict.\n    await this.putRow(key, env, current ? { version: current.version } : 'absent');\n    return { token };\n  }\n\n  async compareAndSwap(\n    ref: SegmentRef,\n    expected: Token,\n    patch: RegistryPatch,\n  ): Promise<{ token: Token }> {\n    validateRegistryPatch(patch);\n    const key = registryObjectKey(this.prefix, ref);\n    const current = await this.readRow(key);\n    if (current === null || current.env.deleted || current.env.record.token !== expected) {\n      throw new WriteConflictError(`OCC token mismatch for registry row ${ref.segment}`);\n    }\n    const token = String(registryCounterOf(current.env.record) + 1);\n    const env: RegistryEnvelope = {\n      deleted: false,\n      record: applyRegistryPatch(current.env.record, patch, this.now(), token),\n    };\n    // The version we read fences a concurrent writer between that read and this write.\n    await this.putRow(key, env, { version: current.version });\n    return { token };\n  }\n\n  async *list(namespace?: string): AsyncIterable<RegistryRecord> {\n    const prefix = registryListPrefix(this.prefix, namespace);\n    // One list plus bounded parallel reads. A serial await-in-loop made this O(N) sequential round trips.\n    let page: string[] = [];\n    const flush = async function* (\n      this: ObjectStoreRegistry,\n      keys: string[],\n    ): AsyncIterable<RegistryRecord> {\n      const rows = await mapWithConcurrency(keys, LIST_READ_CONCURRENCY, (key) =>\n        this.readRow(key),\n      );\n      for (const current of rows) {\n        if (current && !current.env.deleted) yield current.env.record;\n      }\n    }.bind(this);\n\n    for await (const key of this.store.listKeys(prefix)) {\n      if (parseRegistryKey(this.prefix, key) === null) continue; // stray or foreign object\n      page.push(key);\n      if (page.length >= LIST_READ_CONCURRENCY) {\n        yield* flush(page);\n        page = [];\n      }\n    }\n    if (page.length > 0) yield* flush(page);\n  }\n\n  async delete(ref: SegmentRef, expected?: Token): Promise<void> {\n    const key = registryObjectKey(this.prefix, ref);\n    // Tombstone (advance the counter) rather than remove the object \u2014 keeps the token monotonic for\n    // ABA-safety. Retry the read\u2192tombstone on a cross-process race; it converges, then fails typed rather\n    // than silently leaving the row live.\n    for (let attempt = 0; attempt < MAX_DELETE_ATTEMPTS; attempt++) {\n      const current = await this.readRow(key);\n      if (expected !== undefined) {\n        // Fenced: the row must still carry the token the caller read. Re-checked on every attempt, so a row\n        // that was swapped, or deleted and re-created, between two attempts is refused rather than tombstoned.\n        if (current === null || current.env.deleted || current.env.record.token !== expected) {\n          throw new WriteConflictError(`OCC token mismatch for registry row ${ref.segment}`);\n        }\n      } else if (current === null || current.env.deleted) {\n        return; // idempotent \u2014 already gone\n      }\n      const token = String(registryCounterOf(current.env.record) + 1);\n      const env: RegistryEnvelope = {\n        deleted: true,\n        record: { ...current.env.record, token, updatedAt: this.now() },\n      };\n      try {\n        await this.putRow(key, env, { version: current.version });\n        return;\n      } catch (err) {\n        if (isWriteConflictError(err)) continue; // raced \u2014 re-read and re-tombstone\n        throw err;\n      }\n    }\n    throw new WriteConflictError(\n      `registry delete: contention tombstoning \"${ref.segment}\" \u2014 retry`,\n    );\n  }\n\n  /**\n   * Read + parse a registry object, returning its envelope and version fence, or null if absent.\n   *\n   * A store that pins a version to read consistently ({@link ObjectVersionRaced}) loses that pin whenever a\n   * concurrent writer lands mid-read. Re-reading is the whole answer \u2014 the next read simply observes the\n   * newer version \u2014 and it is bounded so a row under permanent write saturation fails typed instead of\n   * spinning. Only a store racing itself gets here; S3 never does.\n   */\n  private async readRow(\n    objectKey: string,\n  ): Promise<{ env: RegistryEnvelope; version: string } | null> {\n    const row = await this.readRaced(objectKey);\n    if (row === null) return null;\n    if (row.bytes.length > MAX_ROW_BYTES) {\n      throw new IntegrityError(\n        `registry object ${row.bytes.length}B exceeds cap ${MAX_ROW_BYTES}B`,\n      );\n    }\n    if (row.version.length === 0) {\n      // The version is the OCC fence for CAS; a backend that omits it cannot be used safely as a registry.\n      throw new IntegrityError(\n        `registry object has no version fence (needed for compare-and-swap): ${objectKey}`,\n      );\n    }\n    const env = parseRegistryEnvelope(new TextDecoder().decode(row.bytes), objectKey);\n    return { env, version: row.version };\n  }\n\n  /** {@link ObjectRegistryStore.read}, retrying the bounded number of times a mid-read overwrite allows. */\n  private async readRaced(objectKey: string): Promise<ObjectRow | null> {\n    for (let attempt = 0; attempt < MAX_READ_ATTEMPTS; attempt++) {\n      try {\n        return await this.store.read(objectKey);\n      } catch (err) {\n        if (!(err instanceof ObjectVersionRaced)) throw err;\n      }\n    }\n    throw new TransientError(\n      `registry read: ${this.store.label} object \"${objectKey}\" was overwritten on every one of ` +\n        `${MAX_READ_ATTEMPTS} attempts \u2014 retry`,\n    );\n  }\n\n  /** Conditional write of an envelope. The store maps a lost precondition to {@link WriteConflictError}. */\n  private async putRow(\n    objectKey: string,\n    env: RegistryEnvelope,\n    expect: 'absent' | { version: string },\n  ): Promise<void> {\n    const body = new TextEncoder().encode(serializeRegistryEnvelope(env));\n    if (body.length > MAX_ROW_BYTES) {\n      // Belt-and-braces: the governance/DEK fields are already capped by validate*, so this cannot fire for\n      // valid input \u2014 but never write a row that would later be unreadable.\n      throw new ValidationError(`registry object ${body.length}B exceeds cap ${MAX_ROW_BYTES}B`);\n    }\n    await this.store.write(objectKey, body, expect);\n  }\n}\n"],
   "mappings": "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",
   "names": []
 }

package/dist/drivers/_shared/object-registry.d.ts

@@ -8,11 +8,11 @@ export declare const MAX_ROW_BYTES: number;
  * This is deliberately **neither** of the two things it superficially resembles. It is not absence: the row
  * is very likely still live, just one version further on. And it is not a write conflict: the caller may be
  * a read-only `get()`, which has nothing to conflict with. Either is an easy misreading for a store that reads a
- * row in two calls, as the GCS and Azure Blob stores do, which is why the signal is part of the port rather than
+ * row in two calls, as the Azure Blob store does, which is why the signal is part of the port rather than
  * left to each store's judgement. {@link ObjectStoreRegistry} answers it the only way that is correct for every
  * caller: it reads again.
  *
- * Stores whose read is atomic (S3 serves bytes and `ETag` from one `GetObject`) can never raise it.
+ * Stores whose read is atomic (S3 serves bytes and `ETag` from one `GetObject`, GCS bytes and `generation` from one GET) can never raise it.
  */
 export declare class ObjectVersionRaced extends Error {
     constructor(objectKey: string);

package/dist/index.js

@@ -255,6 +255,37 @@ function keysWithin(keys, w) {
   };
   return keys.slice(firstAtLeast(w.loKey), firstAtLeast(w.hiKey + 1));
 }
+var ChunkWindow = class {
+  constructor(keys, fetch, max, ramp) {
+    this.keys = keys;
+    this.fetch = fetch;
+    this.max = max;
+    this.ramp = ramp;
+  }
+  keys;
+  fetch;
+  max;
+  ramp;
+  open = [];
+  launched = 0;
+  taken = 0;
+  /** The next chunk in key order (null if the source holds none), or the error its read raised. */
+  async take() {
+    const width = this.ramp ? Math.min(this.max, 2 ** Math.min(this.taken, 30)) : this.max;
+    while (this.launched < this.keys.length && this.launched - this.taken < width) {
+      this.open.push(
+        this.fetch(this.keys[this.launched++]).then(
+          (chunk) => ({ chunk }),
+          (cause) => ({ chunk: null, error: { cause } })
+        )
+      );
+    }
+    const slot = await this.open.shift();
+    this.taken += 1;
+    if (slot.error) throw slot.error.cause;
+    return slot.chunk;
+  }
+};
 var SegmentEngine = class {
   storage;
   cache;
@@ -303,10 +334,9 @@ var SegmentEngine = class {
     const chunkKeys = await this.chunkKeys(seg);
     checkBudget(this.budget, chunkKeys.length, "count");
     const gen = await this.cacheVersion(seg);
+    const window = this.chunkWindow(seg, chunkKeys, gen, false);
     let total = 0;
-    for (const chunkKey of chunkKeys) {
-      total += (await this.storageChunk({ ...seg, chunkKey }, gen))?.size ?? 0;
-    }
+    for (let i = 0; i < chunkKeys.length; i++) total += (await window.take())?.size ?? 0;
     return total;
   }
   /** Whether the Storage source can measure segment size (for grounded cost); false ⇒ storage isn't grounded. */
@@ -321,8 +351,18 @@ var SegmentEngine = class {
   segmentSize(seg) {
     return this.storage.sizeOf ? this.storage.sizeOf(seg) : Promise.resolve(null);
   }
+  /** The chunks of `seg` at `chunkKeys`, read through a window of {@link DEFAULT_INTERSECT_CONCURRENCY}. */
+  chunkWindow(seg, chunkKeys, gen, ramp) {
+    return new ChunkWindow(
+      chunkKeys,
+      (chunkKey) => this.storageChunk({ ...seg, chunkKey }, gen),
+      DEFAULT_INTERSECT_CONCURRENCY,
+      ramp
+    );
+  }
   /**
-   * Every id, ascending, one chunk at a time; with `range`, only the ids in `(after, through]`, fetching only the
+   * Every id, ascending, reading ahead through a window of up to 8 chunk fetches that opens 1, 2, 4, 8 wide, so a
+   * read that stops early has fetched only a handful of chunks past the one it stopped in; with `range`, only the ids in `(after, through]`, fetching only the
    * chunks the range overlaps (see {@link IdRange}).
    *
    * Two generators, not one with a branch: a second `yield` site in the full read's generator grows its frame, and
@@ -336,8 +376,9 @@ var SegmentEngine = class {
     const chunkKeys = await this.chunkKeys(seg);
     checkBudget(this.budget, chunkKeys.length, "iterate");
     const gen = await this.cacheVersion(seg);
+    const window = this.chunkWindow(seg, chunkKeys, gen, true);
     for (const chunkKey of chunkKeys) {
-      const chunk = await this.storageChunk({ ...seg, chunkKey }, gen);
+      const chunk = await window.take();
       if (chunk === null) continue;
       for (const remainder of chunk) yield joinId(chunkKey, remainder);
     }
@@ -348,8 +389,9 @@ var SegmentEngine = class {
     const chunkKeys = keysWithin(await this.chunkKeys(seg), w);
     checkBudget(this.budget, chunkKeys.length, "iterate");
     const gen = await this.cacheVersion(seg);
+    const window = this.chunkWindow(seg, chunkKeys, gen, true);
     for (const chunkKey of chunkKeys) {
-      const chunk = await this.storageChunk({ ...seg, chunkKey }, gen);
+      const chunk = await window.take();
       if (chunk === null) continue;
       if (isEdge(chunkKey, w)) {
         for (const id of edgeIds(chunk, chunkKey, w)) yield id;
@@ -382,7 +424,7 @@ var SegmentEngine = class {
    * up front (before the fan-out) and threaded into every chunk read, so a concurrent load can't corrupt or tear
    * the result — every chunk read is a whole, checksum-verified, immutable generation. The edge a *long* call can
    * hit is invariant 3's: if it straddles a mid-call `cache.genTtlMs` boundary and a load has published, an
-   * operand's not-yet-read chunks may re-resolve forward to the newer generation (a generation hop within one long
+   * operand's not-yet-requested chunks may re-resolve forward to the newer generation (a generation hop within one long
    * call) — the call never crashes or returns a torn object, but may mix generations. Three things hop it without
    * waiting for the TTL, so a shorter call can meet them too: **the reader cache evicting an operand mid-call**
    * (`maxOpenSegments`), whose re-read re-resolves fresh; a sweep deleting the generation it was reading, which
@@ -2097,7 +2139,7 @@ function readVarint(bytes, offset) {
     if (i === 4 && byte > 15) {
       throw new IntegrityError("varint exceeds u32 range");
     }
-    result += (byte & 127) * 2 ** shift;
+    result = (result | (byte & 127) << shift) >>> 0;
     if ((byte & 128) === 0) {
       return { value: result, next: pos };
     }
@@ -2171,7 +2213,10 @@ var AEAD_NONCE_BYTES = 12;
 var AEAD_TAG_BYTES = 16;
 
 // src/core/crbm/reader.ts
-var RETAINED_BYTES_PER_INDEX_ENTRY = 160;
+var MIN_INDEX_RECORD_BYTES = 4 + CRC32C_BYTES;
+function indexCapacity(indexLength) {
+  return Math.min(65536, Math.floor(indexLength / MIN_INDEX_RECORD_BYTES));
+}
 function magicMatches(bytes, offset) {
   return bytes[offset] === MAGIC[0] && bytes[offset + 1] === MAGIC[1] && bytes[offset + 2] === MAGIC[2] && bytes[offset + 3] === MAGIC[3];
 }
@@ -2206,14 +2251,13 @@ function readU64(view, offset, field) {
   return Number(big);
 }
 var CrbmReader = class _CrbmReader {
-  constructor(blob, objectSize, generation, lineage, totalCardinality, entries, orderedKeys, servedFromTail, crypto, footerCrc) {
+  constructor(blob, objectSize, generation, lineage, totalCardinality, index, servedFromTail, crypto, footerCrc) {
     this.blob = blob;
     this.objectSize = objectSize;
     this.generation = generation;
     this.lineage = lineage;
     this.totalCardinality = totalCardinality;
-    this.entries = entries;
-    this.orderedKeys = orderedKeys;
+    this.index = index;
     this.servedFromTail = servedFromTail;
     this.crypto = crypto;
     this.footerCrc = footerCrc;
@@ -2223,8 +2267,7 @@ var CrbmReader = class _CrbmReader {
   generation;
   lineage;
   totalCardinality;
-  entries;
-  orderedKeys;
+  index;
   servedFromTail;
   crypto;
   footerCrc;
@@ -2241,17 +2284,19 @@ var CrbmReader = class _CrbmReader {
     return this.objectSize;
   }
   /**
-   * Estimated retained JS heap of this reader's parsed index — the weight the storage reader cache bounds on
-   * (a wide segment's parsed index, not its payloads, dominates the reader's footprint). `entries.size` scales with the number
-   * of resident chunks (≤ 65536), so this is `entries.size × {@link RETAINED_BYTES_PER_INDEX_ENTRY}`.
+   * Retained JS heap of this reader's parsed index — the weight the storage reader cache bounds on (a wide
+   * segment's parsed index, not its payloads, dominates the reader's footprint): the exact byte length of the
+   * arrays that hold it, {@link RETAINED_BYTES_PER_INDEX_ENTRY} per entry.
    */
   get retainedIndexBytes() {
-    return this.entries.size * RETAINED_BYTES_PER_INDEX_ENTRY;
+    const { keys, cardinalityMinusOne, lengths, crcs, offsets } = this.index;
+    return keys.byteLength + cardinalityMinusOne.byteLength + lengths.byteLength + crcs.byteLength + offsets.byteLength;
   }
   /** Per-chunk cardinality (`chunkKey → count`) from the parsed index — no payload reads. */
   cardinalities() {
+    const { keys, cardinalityMinusOne } = this.index;
     const out = /* @__PURE__ */ new Map();
-    for (const [chunkKey, entry] of this.entries) out.set(chunkKey, entry.cardinality);
+    for (let i = 0; i < keys.length; i++) out.set(keys[i], cardinalityMinusOne[i] + 1);
     return out;
   }
   /**
@@ -2348,7 +2393,7 @@ var CrbmReader = class _CrbmReader {
       },
       options.crypto.aadFor("index")
     ) : indexBytes;
-    const { entries, orderedKeys, cardinalitySum } = parseIndex(
+    const index = parseIndex(
       indexForParse,
       indexOffset,
       maxPayloadBytes,
@@ -2361,14 +2406,14 @@ var CrbmReader = class _CrbmReader {
         );
       }
     } else {
-      if (entries.size !== chunkCount) {
+      if (index.keys.length !== chunkCount) {
         throw new IntegrityError(
-          `.crbm chunk_count ${chunkCount} != ${entries.size} index entries`
+          `.crbm chunk_count ${chunkCount} != ${index.keys.length} index entries`
         );
       }
-      if (cardinalitySum !== totalCardinality) {
+      if (index.cardinalitySum !== totalCardinality) {
         throw new IntegrityError(
-          `.crbm total_cardinality ${totalCardinality} != \u03A3 index cardinality ${cardinalitySum}`
+          `.crbm total_cardinality ${totalCardinality} != \u03A3 index cardinality ${index.cardinalitySum}`
         );
       }
     }
@@ -2377,9 +2422,8 @@ var CrbmReader = class _CrbmReader {
       size,
       generation,
       options.lineage,
-      cardinalitySum,
-      entries,
-      orderedKeys,
+      index.cardinalitySum,
+      index,
       servedFromTail,
       options.crypto,
       storedFooterCrc
@@ -2387,14 +2431,28 @@ var CrbmReader = class _CrbmReader {
   }
   /** Chunk keys present in this generation, ascending. */
   chunkKeys() {
-    return this.orderedKeys.slice();
+    return Array.from(this.index.keys);
   }
   /** Segment cardinality from the footer (no payload reads) — the cheap `count()` path. */
   count() {
     return this.totalCardinality;
   }
+  /** The slot holding `chunkKey` (binary search over the ascending keys), or -1 when this generation has none. */
+  slotOf(chunkKey) {
+    const keys = this.index.keys;
+    let lo = 0;
+    let hi = keys.length - 1;
+    while (lo <= hi) {
+      const mid = lo + hi >>> 1;
+      const k = keys[mid];
+      if (k === chunkKey) return mid;
+      if (k < chunkKey) lo = mid + 1;
+      else hi = mid - 1;
+    }
+    return -1;
+  }
   has(chunkKey) {
-    return this.entries.has(chunkKey);
+    return this.slotOf(chunkKey) >= 0;
   }
   /**
    * Range-GET one chunk's payload, verifying its CRC32C before returning. Returns `null` if the chunk is
@@ -2403,13 +2461,15 @@ var CrbmReader = class _CrbmReader {
    * not mutate it.
    */
   async getChunk(chunkKey) {
-    const e = this.entries.get(chunkKey);
-    if (e === void 0) return null;
-    if (e.offset < PAYLOAD_START || e.offset + e.length > this.objectSize - FOOTER_BYTES) {
+    const slot = this.slotOf(chunkKey);
+    if (slot < 0) return null;
+    const offset = this.index.offsets[slot];
+    const length = this.index.lengths[slot];
+    if (offset < PAYLOAD_START || offset + length > this.objectSize - FOOTER_BYTES) {
       throw new IntegrityError(`chunk ${chunkKey} payload out of bounds`);
     }
-    const bytes = await this.blob.getRange(e.offset, e.length);
-    if (crc32c(bytes) !== e.crc32c) {
+    const bytes = await this.blob.getRange(offset, length);
+    if (crc32c(bytes) !== this.index.crcs[slot]) {
       throw new IntegrityError(`chunk ${chunkKey} payload CRC mismatch`);
     }
     if (this.crypto === void 0) return bytes;
@@ -2427,51 +2487,68 @@ var CrbmReader = class _CrbmReader {
   }
 };
 function parseIndex(indexBytes, payloadEnd, maxPayloadBytes, minPayloadBytes = 1) {
-  const entries = /* @__PURE__ */ new Map();
-  const orderedKeys = [];
+  const capacity = indexCapacity(indexBytes.length);
+  const keys = new Uint16Array(capacity);
+  const cardinalityMinusOne = new Uint16Array(capacity);
+  const lengths = new Uint32Array(capacity);
+  const crcs = new Uint32Array(capacity);
+  const offsets = new Float64Array(capacity);
+  let count = 0;
   let pos = 0;
   let prevKey = 0;
   let prevEnd = PAYLOAD_START;
   let cardinalitySum = 0;
   for (let i = 0; pos < indexBytes.length; i++) {
-    const keyDelta = readVarint(indexBytes, pos);
-    const offDelta = readVarint(indexBytes, keyDelta.next);
-    const len = readVarint(indexBytes, offDelta.next);
-    const card = readVarint(indexBytes, len.next);
-    pos = card.next;
+    const keyDeltaRead = readVarint(indexBytes, pos);
+    const offDeltaRead = readVarint(indexBytes, keyDeltaRead.next);
+    const lenRead = readVarint(indexBytes, offDeltaRead.next);
+    const cardRead = readVarint(indexBytes, lenRead.next);
+    const keyDelta = keyDeltaRead.value;
+    const offDelta = offDeltaRead.value;
+    const len = lenRead.value;
+    const card = cardRead.value;
+    pos = cardRead.next;
     if (pos + CRC32C_BYTES > indexBytes.length) {
       throw new IntegrityError(".crbm index truncated (missing payload CRC)");
     }
     const crc = (indexBytes[pos] | indexBytes[pos + 1] << 8 | indexBytes[pos + 2] << 16 | indexBytes[pos + 3] << 24) >>> 0;
     pos += CRC32C_BYTES;
-    const chunkKey = prevKey + keyDelta.value;
-    const offset = prevEnd + offDelta.value;
-    if (i > 0 && keyDelta.value === 0) {
+    const chunkKey = prevKey + keyDelta;
+    const offset = prevEnd + offDelta;
+    if (i > 0 && keyDelta === 0) {
       throw new IntegrityError(`.crbm index has a duplicate chunkKey ${chunkKey}`);
     }
     if (chunkKey > 65535) throw new IntegrityError(`.crbm chunkKey ${chunkKey} out of range`);
-    if (len.value < minPayloadBytes || len.value > maxPayloadBytes) {
-      throw new IntegrityError(`.crbm chunk ${chunkKey} length ${len.value} invalid`);
+    if (len < minPayloadBytes || len > maxPayloadBytes) {
+      throw new IntegrityError(`.crbm chunk ${chunkKey} length ${len} invalid`);
     }
-    if (card.value < 1 || card.value > MAX_CHUNK_CARDINALITY) {
-      throw new IntegrityError(`.crbm chunk ${chunkKey} cardinality ${card.value} invalid`);
+    if (card < 1 || card > MAX_CHUNK_CARDINALITY) {
+      throw new IntegrityError(`.crbm chunk ${chunkKey} cardinality ${card} invalid`);
     }
-    if (offset + len.value > payloadEnd) {
+    if (offset + len > payloadEnd) {
       throw new IntegrityError(`.crbm chunk ${chunkKey} payload out of bounds`);
     }
-    entries.set(chunkKey, {
-      chunkKey,
-      offset,
-      length: len.value,
-      cardinality: card.value,
-      crc32c: crc
-    });
-    orderedKeys.push(chunkKey);
-    cardinalitySum += card.value;
+    keys[count] = chunkKey;
+    cardinalityMinusOne[count] = card - 1;
+    lengths[count] = len;
+    crcs[count] = crc;
+    offsets[count] = offset;
+    count++;
+    cardinalitySum += card;
     prevKey = chunkKey;
-    prevEnd = offset + len.value;
+    prevEnd = offset + len;
+  }
+  if (count === capacity) {
+    return { keys, cardinalityMinusOne, lengths, crcs, offsets, cardinalitySum };
   }
-  return { entries, orderedKeys, cardinalitySum };
+  return {
+    keys: keys.slice(0, count),
+    cardinalityMinusOne: cardinalityMinusOne.slice(0, count),
+    lengths: lengths.slice(0, count),
+    crcs: crcs.slice(0, count),
+    offsets: offsets.slice(0, count),
+    cardinalitySum
+  };
 }
 
 // src/core/crbm/writer.ts