@cloudbitmaps/roaring 0.8.2 → 0.10.0

package/dist/moved-options.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The 0.9.x option spellings this release no longer accepts, and what to tell someone who passes one.
+ *
+ * NOT part of the public API. It lives in its own module — rather than as an `export` from the barrel — so
+ * that the gates which must agree with it (the doc-fence scan, the harness scan, and the test that diffs this
+ * table against `CloudRoaringOptions` at the previous tag) can all read ONE copy, without the migration
+ * table becoming a permanent public export in the same release whose point was to shrink that surface.
+ *
+ * Retyping it was tried and is what this replaces: the hand-maintained copies had drifted to naming three
+ * spellings no release ever shipped while omitting the five that actually went away with the live tier.
+ */
+export type MovedOptionKind = 'group' | 'renamed' | 'gone';
+/** `[the 0.9.x key, what to do instead, which kind of answer that is]`. */
+export declare const MOVED_OPTIONS: ReadonlyArray<readonly [string, string, MovedOptionKind]>;

package/dist/portable/decode.d.ts

@@ -0,0 +1,54 @@
+/**
+ * A decoded portable-roaring bitmap that can be queried but not modified.
+ *
+ * Construction parses only the headers — container payloads are read on demand, so a membership test against a
+ * large bitmap touches one container rather than materializing the set.
+ */
+export declare class PortableRoaringReader {
+    private readonly bytes;
+    private readonly view;
+    private readonly containers;
+    private constructor();
+    /**
+     * Parse the headers of a portable-format bitmap.
+     *
+     * @throws {IntegrityError} if the cookie is unrecognized, or any header field runs past the buffer.
+     */
+    static decode(bytes: Uint8Array): PortableRoaringReader;
+    /**
+     * Total cardinality.
+     *
+     * Served entirely from the descriptive header — no container payload is read, so this is O(containers) and
+     * independent of how many values the bitmap holds.
+     */
+    count(): number;
+    /** Is `value` (a `u32`) in the set? */
+    has(value: number): boolean;
+    /** Binary search the descriptive header for the container owning `key`. */
+    private findContainer;
+    /**
+     * 1,024 little-endian `u64` words. Read as `u32` at `(low >> 5) * 4`: a LE `u64` is two LE `u32`s with the
+     * low word first, so the 32-bit view lands on the right half without any 64-bit arithmetic.
+     */
+    private bitmapHas;
+    /**
+     * Sorted `u16` values — binary search.
+     *
+     * The `at === low` early return means the `at < low` below is only ever evaluated when `at !== low`, so
+     * writing it `at <= low` would behave identically. That is recorded because mutation testing surfaced it as
+     * a surviving mutant: it is an *equivalent* one, unkillable by any test rather than a coverage gap — three
+     * non-equivalent mutations of these same lines (inverting the branches, never reporting a hit, dropping the
+     * last element) are all caught. Do not "fix" the survivor, and do not add a test chasing it.
+     */
+    private arrayHas;
+    /**
+     * `u16` run count, then that many `(start, length)` `u16` pairs sorted by start.
+     *
+     * `length` is the number of values **after** `start`, so a run covers the inclusive range
+     * `[start, start + length]` and a single-value run is stored with length 0. Getting this off by one is the
+     * easiest mistake in the format and is why the differential test drives runs specifically.
+     */
+    private runHas;
+}
+/** Convenience wrapper over {@link PortableRoaringReader.decode}. */
+export declare function decodePortableRoaring(bytes: Uint8Array): PortableRoaringReader;

package/dist/roaring-codec.d.ts

@@ -0,0 +1,61 @@
+import type { CodecBitmap, CodecInterface } from '@cloudbitmaps/core';
+export declare class SafeBitmap implements CodecBitmap {
+    private readonly bitmap;
+    private constructor();
+    static empty(): SafeBitmap;
+    static fromValues(values: Iterable<number>): SafeBitmap;
+    /**
+     * Validate size, then deserialize with the **portable** (validated) format.
+     * Throws `IntegrityError` if the input exceeds `maxBytes` or fails to decode — the
+     * native addon is never handed unbounded or unsafe-format input.
+     */
+    static safeDeserialize(bytes: Uint8Array, maxBytes: number): SafeBitmap;
+    serialize(): Uint8Array;
+    /**
+     * Convert containers to run-encoding where that is smaller. Representation only — membership is untouched, and
+     * the portable format still round-trips through {@link RoaringCodec.safeDeserialize}.
+     *
+     * Roaring's third container type is a RUN, and no implementation selects it on its own: it takes an explicit
+     * `runOptimize()` pass. Nothing here made that call, so run-shaped ids paid array or bitset prices — measured
+     * at **570×** for a contiguous 1M-id range (128.1 KiB → 0.2 KiB) and **63×** for a 2,000-run shape
+     * (536.5 KiB → 8.5 KiB). Sparse ids come out byte-identical, so this is never a losing trade; roaring keeps
+     * whichever encoding is smaller per container.
+     *
+     * Those two factors are THIS CALL's own before/after on the same ids. They are not the ones the site quotes
+     * (543× and 63×) — those compare the optimized encoding against the best *fixed* representation at its floor,
+     * a different baseline that happens to land near 63× on the run shape too. `pnpm bench:encoding` prints both
+     * columns; don't carry a figure between them without checking which denominator it had.
+     *
+     * Called only when writing an immutable objects generation — see {@link CodecBitmap.optimize} for why the read
+     * path deliberately does not.
+     */
+    optimize(): void;
+    /**
+     * Largest value, or `undefined` when empty. O(1) — roaring reads it off the container index, so the engine's
+     * per-chunk range assertion costs one call per chunk rather than a walk per id.
+     */
+    maximum(): number | undefined;
+    add(value: number): void;
+    addMany(values: Iterable<number>): void;
+    remove(value: number): void;
+    removeMany(values: Iterable<number>): void;
+    has(value: number): boolean;
+    get size(): number;
+    get isEmpty(): boolean;
+    clone(): SafeBitmap;
+    /** In-place union: `this = this ∪ other`. */
+    orInPlace(other: CodecBitmap): void;
+    /** In-place difference: `this = this \ other`. */
+    andNotInPlace(other: CodecBitmap): void;
+    /** In-place intersection: `this = this ∩ other`. */
+    andInPlace(other: CodecBitmap): void;
+    /** Ascending iterator over the set values. */
+    [Symbol.iterator](): IterableIterator<number>;
+    toArray(): number[];
+}
+/**
+ * The roaring {@link CodecInterface} — the flagship codec, delegating to {@link SafeBitmap}'s statics. This is
+ * the default the `CloudRoaring` facade injects into the engine; `core/` itself never hard-references it once a
+ * caller supplies a codec. Moves to `@cloudbitmaps/roaring` when the package split lands.
+ */
+export declare const roaringCodec: CodecInterface;

package/dist/system-clock.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The default real-time {@link Clock} — the production half of the determinism seam.
+ *
+ * It lives outside `core/`, so `Date.now()`, `setTimeout` and `setImmediate` are allowed here; that separation is
+ * the whole point of the seam, and it is lint-enforced on the other side.
+ *
+ * It sits in its own module rather than in `index.ts` because two places need it — the facade, and
+ * `codec-bound.ts`, which pre-binds it into `bulkLoadCrbmGeneration`. Importing it from `index.ts` would put a
+ * cycle between the barrel and a module the barrel re-exports.
+ */
+import type { Clock } from '@cloudbitmaps/core';
+/** Default real-time clock — lives outside `core/`, so `Date.now()` + timers are allowed here. */
+export declare class SystemClock implements Clock {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+    /**
+     * `setImmediate`, and it has to be — this is the one place where the choice of primitive is the whole feature.
+     *
+     * A long CPU-bound loop in `core/` (bulk-load is the one that matters) periodically hands the loop back so a
+     * co-resident HTTP server keeps answering. Measured on the **synthetic yield-primitive benchmark** — a
+     * 61,035-iteration loop yielding every 1,024, isolating the primitive rather than timing a real load (the
+     * end-to-end figures are 450 ms → 19 ms; see `cooperative.ts`, which lists all three experiments):
+     *
+     * ```text
+     *   no yield         568 ms wall   568.0 ms worst event-loop gap
+     *   sleep(0)         555 ms wall   555.2 ms   ← a microtask. Yields NOTHING.
+     *   setImmediate     569 ms wall    13.8 ms   ← free, and 41x less starvation
+     *   setTimeout(1)    625 ms wall    15.0 ms   ← +10% wall for no extra relief
+     * ```
+     *
+     * `sleep(0)` resolving on a microtask is correct for its own contract and useless for this: microtasks drain
+     * before the loop ever advances a phase, so `await sleep(0)` in a tight loop never lets a single pending I/O
+     * callback run. `setImmediate` fires in the check phase *after* pending I/O, which is exactly the ordering a
+     * server wants — inbound requests are serviced before the loop resumes chewing.
+     *
+     * A timer is not ref'd here (unlike {@link sleep}): a yield expresses "someone else may go first", never
+     * "there is outstanding work" — and `setImmediate` cannot outlive the turn that scheduled it anyway.
+     */
+    yieldNow(): Promise<void>;
+}

package/dist/testing/conformance.d.ts

@@ -0,0 +1,34 @@
+import { SafeBitmap } from '../roaring-codec.js';
+import type { StorageChunkSource, IRegistryDriver } from '@cloudbitmaps/core';
+/**
+ * The segment every conformance seeder must write. Exported so a driver's own test file derives the name
+ * instead of restating it — a second copy that drifts makes the suite query a segment nobody seeded, which
+ * fails as an empty result rather than as the mismatch it actually is.
+ */
+export declare const CONFORMANCE_SEGMENT = "s:v1";
+/**
+ * Contract tests for a {@link StorageChunkSource}. `makeSource` MUST build a fresh source seeded with the
+ * given chunks (each an immutable Storage bitmap) and nothing else.
+ */
+export declare function storageChunkSourceConformance(label: string, makeSource: (chunks: Array<{
+    chunkKey: number;
+    bitmap: SafeBitmap;
+}>) => Promise<StorageChunkSource>): void;
+/**
+ * Contract tests for an {@link IRegistryDriver}. `makeDriver` MUST return a fresh, empty, isolated driver on
+ * each call. The OCC contract (create / token-fenced CAS / ABA) plus the registry's record semantics (forward
+ * currentGen, status, clearable keyId, discovery).
+ */
+export declare function registryConformance(label: string, makeDriver: () => IRegistryDriver): void;
+/**
+ * Contract tests for an {@link IRegistryDriver} under **concurrent writers** — `makeDrivers` MUST return two
+ * independent driver instances over the **same** backing store, as two processes would see it.
+ *
+ * This exists because {@link registryConformance} drives one driver sequentially, and `ObjectStoreRegistry`
+ * checks the OCC token in memory before it ever issues a conditional write. That in-process check answers
+ * every sequential case, so the store-level precondition — the only thing that fences writers *across*
+ * processes, and the entire reason these drivers are built on conditional writes — is never load-bearing
+ * there. A backend that accepted `If-Match` and ignored it passed the full suite; so did a GCS driver whose
+ * writes were not fenced at all. These cases are what make the fence testable.
+ */
+export declare function registryConcurrency(label: string, makeDrivers: () => readonly [IRegistryDriver, IRegistryDriver]): void;

package/dist/testing/fuzz-codec.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Internal surface for the coverage-guided fuzz harness, CODEC half.
+ *
+ * Only the concrete bitmap codec lives here — the core half (`CrbmReader`, the non-public `parseIndex`,
+ * `BufferReader`, `CloudRoaringError`, `DEFAULT_MAX_PAYLOAD_BYTES`) is built from `@cloudbitmaps/core`'s own
+ * `src/testing/fuzz-core.ts` to `fuzz/build/fuzz-core.js`. Splitting it this way keeps the published entries
+ * of both packages free of test-only exports: neither widened its public API to feed the fuzzer.
+ */
+export { SafeBitmap } from '../roaring-codec.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cloudbitmaps/roaring",
-  "version": "0.8.2",
-  "description": "Distributed, cloud-native Roaring Bitmaps — query and intersect billion-scale integer sets over tiered cloud storage (RAM → NoSQL → object store), at a fraction of an always-on cache.",
+  "version": "0.10.0",
+  "description": "Distributed, cloud-native Roaring Bitmaps — query and intersect billion-scale integer sets straight out of object storage, from a bounded RAM cache over immutable objects in your own bucket, at a fraction of an always-on cache.",
   "keywords": [
     "roaring",
     "bitmap",
@@ -16,17 +16,10 @@
     "set",
     "set-intersection",
     "s3",
-    "dynamodb",
     "gcs",
     "azure",
-    "postgres",
-    "redis",
-    "mongodb",
-    "cassandra",
-    "mysql",
-    "mariadb",
     "serverless",
-    "tiered-storage",
+    "object-storage",
     "scale-to-zero",
     "segmentation",
     "audience",
@@ -38,7 +31,8 @@
   "author": "Sharvil Kadam",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/cloudbitmaps/cloudbitmaps.git"
+    "url": "git+https://github.com/cloudbitmaps/cloudbitmaps.git",
+    "directory": "packages/roaring"
   },
   "homepage": "https://github.com/cloudbitmaps/cloudbitmaps#readme",
   "bugs": {
@@ -46,62 +40,15 @@
   },
   "type": "module",
   "engines": {
-    "node": ">=22"
+    "node": ">=22.12"
   },
   "sideEffects": false,
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
+  "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    },
-    "./s3": {
-      "types": "./dist/s3/index.d.ts",
-      "import": "./dist/s3/index.js",
-      "require": "./dist/s3/index.cjs"
-    },
-    "./dynamodb": {
-      "types": "./dist/dynamodb/index.d.ts",
-      "import": "./dist/dynamodb/index.js",
-      "require": "./dist/dynamodb/index.cjs"
-    },
-    "./gcs": {
-      "types": "./dist/gcs/index.d.ts",
-      "import": "./dist/gcs/index.js",
-      "require": "./dist/gcs/index.cjs"
-    },
-    "./azure": {
-      "types": "./dist/azure/index.d.ts",
-      "import": "./dist/azure/index.js",
-      "require": "./dist/azure/index.cjs"
-    },
-    "./postgres": {
-      "types": "./dist/postgres/index.d.ts",
-      "import": "./dist/postgres/index.js",
-      "require": "./dist/postgres/index.cjs"
-    },
-    "./redis": {
-      "types": "./dist/redis/index.d.ts",
-      "import": "./dist/redis/index.js",
-      "require": "./dist/redis/index.cjs"
-    },
-    "./mongodb": {
-      "types": "./dist/mongodb/index.d.ts",
-      "import": "./dist/mongodb/index.js",
-      "require": "./dist/mongodb/index.cjs"
-    },
-    "./cassandra": {
-      "types": "./dist/cassandra/index.d.ts",
-      "import": "./dist/cassandra/index.js",
-      "require": "./dist/cassandra/index.cjs"
-    },
-    "./mysql": {
-      "types": "./dist/mysql/index.d.ts",
-      "import": "./dist/mysql/index.js",
-      "require": "./dist/mysql/index.cjs"
+      "default": "./dist/index.js"
     }
   },
   "files": [
@@ -115,69 +62,17 @@
     "access": "public"
   },
   "bin": {
-    "compact-segments": "./dist/bin/compact-segments.js",
     "export-segments": "./dist/bin/export-segments.js"
   },
   "dependencies": {
-    "roaring": "^2.7.0",
-    "@cloudbitmaps/core": "0.8.2"
-  },
-  "peerDependencies": {
-    "@aws-sdk/client-dynamodb": "^3",
-    "@aws-sdk/client-s3": "^3",
-    "@azure/storage-blob": "^12",
-    "@google-cloud/storage": "^7",
-    "cassandra-driver": "^4",
-    "ioredis": "^5",
-    "mongodb": "^6",
-    "mysql2": "^3",
-    "pg": "^8"
-  },
-  "peerDependenciesMeta": {
-    "@aws-sdk/client-dynamodb": {
-      "optional": true
-    },
-    "@aws-sdk/client-s3": {
-      "optional": true
-    },
-    "@azure/storage-blob": {
-      "optional": true
-    },
-    "@google-cloud/storage": {
-      "optional": true
-    },
-    "cassandra-driver": {
-      "optional": true
-    },
-    "ioredis": {
-      "optional": true
-    },
-    "mongodb": {
-      "optional": true
-    },
-    "mysql2": {
-      "optional": true
-    },
-    "pg": {
-      "optional": true
-    }
+    "roaring": "2.7.0",
+    "@cloudbitmaps/core": "^0.10.0"
   },
   "devDependencies": {
-    "@aws-sdk/client-dynamodb": "^3.1075.0",
-    "@aws-sdk/client-s3": "^3.1075.0",
-    "@azure/storage-blob": "^12",
-    "@google-cloud/storage": "^7.0.0",
-    "cassandra-driver": "^4",
-    "ioredis": "^5",
-    "mongodb": "^6",
-    "mysql2": "^3.23.1",
-    "pg": "^8",
-    "@types/pg": "^8",
     "@types/node": "^22.0.0",
-    "tsup": "^8.0.0",
     "typescript": "^5.5.0"
   },
   "scripts": {
-    "build": "tsup"
+    "build": "node ../../scripts/build.mjs"
   }
 }

package/dist/azure/index.cjs

@@ -1,14 +0,0 @@
-'use strict';
-
-var azure = require('@cloudbitmaps/core/azure');
-
-
-
-Object.keys(azure).forEach(function (k) {
-	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
-		enumerable: true,
-		get: function () { return azure[k]; }
-	});
-});
-//# sourceMappingURL=index.cjs.map
-//# sourceMappingURL=index.cjs.map

package/dist/azure/index.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs","sourcesContent":[]}

package/dist/azure/index.d.cts

@@ -1,9 +0,0 @@
-export * from '@cloudbitmaps/core/azure';
-import '@cloudbitmaps/core/cassandra';
-import '@cloudbitmaps/core/dynamodb';
-import '@cloudbitmaps/core/gcs';
-import '@cloudbitmaps/core/mongodb';
-import '@cloudbitmaps/core/mysql';
-import '@cloudbitmaps/core/postgres';
-import '@cloudbitmaps/core/redis';
-import '@cloudbitmaps/core/s3';

package/dist/azure/index.d.ts

@@ -1,9 +0,0 @@
-export * from '@cloudbitmaps/core/azure';
-import '@cloudbitmaps/core/cassandra';
-import '@cloudbitmaps/core/dynamodb';
-import '@cloudbitmaps/core/gcs';
-import '@cloudbitmaps/core/mongodb';
-import '@cloudbitmaps/core/mysql';
-import '@cloudbitmaps/core/postgres';
-import '@cloudbitmaps/core/redis';
-import '@cloudbitmaps/core/s3';

package/dist/azure/index.js

@@ -1,3 +0,0 @@
-export * from '@cloudbitmaps/core/azure';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/azure/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js","sourcesContent":[]}

package/dist/bin/compact-segments.js

@@ -1,134 +0,0 @@
-#!/usr/bin/env node
-import { SystemClock, src_exports, runCompactionCycle } from '../chunk-4NVOQJGJ.js';
-import { hostname } from 'os';
-import { join } from 'path';
-import { pathToFileURL } from 'url';
-
-function parseConfig(env) {
-  const root = env.CR_COMPACT_ROOT;
-  if (root === void 0 || root === "") {
-    throw new Error("CR_COMPACT_ROOT is required (the local-filesystem storage root)");
-  }
-  const mode = env.CR_COMPACT_MODE ?? "once";
-  if (mode !== "once" && mode !== "loop") {
-    throw new Error(`CR_COMPACT_MODE must be "once" or "loop"; got ${mode}`);
-  }
-  const num = (name, def) => {
-    const raw = env[name];
-    if (raw === void 0 || raw === "") return def;
-    const v = Number(raw);
-    if (!Number.isFinite(v) || v < 0)
-      throw new Error(`${name} must be a non-negative number; got ${raw}`);
-    return v;
-  };
-  const intOpt = (name, min = 0) => {
-    const raw = env[name];
-    if (raw === void 0 || raw === "") return void 0;
-    const v = Number(raw);
-    if (!Number.isInteger(v) || v < min)
-      throw new Error(`${name} must be an integer >= ${min}; got ${raw}`);
-    return v;
-  };
-  const shard = intOpt("CR_COMPACT_SHARD");
-  const totalShards = intOpt("CR_COMPACT_TOTAL_SHARDS");
-  if (shard === void 0 !== (totalShards === void 0)) {
-    throw new Error("set both CR_COMPACT_SHARD and CR_COMPACT_TOTAL_SHARDS, or neither");
-  }
-  return {
-    root,
-    mode,
-    intervalMs: num("CR_COMPACT_INTERVAL_MS", 3e4),
-    namespace: env.CR_COMPACT_NAMESPACE,
-    threshold: num("CR_COMPACT_THRESHOLD", 1),
-    keep: num("CR_COMPACT_KEEP", 1),
-    owner: env.CR_COMPACT_OWNER ?? `${hostname()}:${process.pid}`,
-    shard,
-    totalShards,
-    maxSegments: intOpt("CR_COMPACT_MAX_SEGMENTS", 1)
-  };
-}
-function localFsDeps(root, metrics) {
-  return {
-    cold: new src_exports.LocalFsColdDriver(join(root, "cold")),
-    warm: new src_exports.LocalFsWarmDriver(join(root, "warm")),
-    registry: new src_exports.LocalFsRegistryDriver(join(root, "registry")),
-    // A real clock, not `{ now }`: outside `core/` ambient time is allowed, and a full clock is what lets
-    // the generation write hand the event loop back instead of blocking the daemon for its whole duration.
-    clock: new SystemClock(),
-    ...metrics ? { metrics } : {}
-  };
-}
-async function runOnce(deps, config) {
-  return runCompactionCycle(deps, {
-    owner: config.owner,
-    namespace: config.namespace,
-    threshold: config.threshold,
-    keep: config.keep,
-    shard: config.shard,
-    totalShards: config.totalShards,
-    maxSegments: config.maxSegments
-  });
-}
-var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-var log = (obj) => {
-  process.stdout.write(`${JSON.stringify(obj)}
-`);
-};
-function stdoutMetricsSink() {
-  return {
-    onEvent: (event) => log({ event: "metric", ...event })
-  };
-}
-async function main(env = process.env) {
-  const config = parseConfig(env);
-  const deps = localFsDeps(
-    config.root,
-    env.CR_COMPACT_METRICS === "1" ? stdoutMetricsSink() : void 0
-  );
-  if (config.mode === "once") {
-    const cycle = await runOnce(deps, config);
-    log({
-      event: "cycle",
-      mode: "once",
-      candidates: cycle.candidates,
-      compacted: cycle.compacted,
-      deferred: cycle.deferred,
-      results: cycle.results
-    });
-    return;
-  }
-  let stop = false;
-  const onSignal = () => {
-    stop = true;
-  };
-  process.on("SIGINT", onSignal);
-  process.on("SIGTERM", onSignal);
-  log({ event: "start", mode: "loop", intervalMs: config.intervalMs, owner: config.owner });
-  while (!stop) {
-    try {
-      const cycle = await runOnce(deps, config);
-      log({
-        event: "cycle",
-        candidates: cycle.candidates,
-        compacted: cycle.compacted,
-        deferred: cycle.deferred,
-        results: cycle.results
-      });
-    } catch (err) {
-      log({ event: "error", message: err.message });
-    }
-    if (!stop) await sleep(config.intervalMs);
-  }
-  log({ event: "stopped" });
-}
-if (process.argv[1] !== void 0 && import.meta.url === pathToFileURL(process.argv[1]).href) {
-  main().catch((err) => {
-    process.stderr.write(`${err.message}
-`);
-    process.exit(1);
-  });
-}
-
-export { localFsDeps, main, parseConfig, runOnce };
-//# sourceMappingURL=compact-segments.js.map
-//# sourceMappingURL=compact-segments.js.map

package/dist/bin/compact-segments.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/bin/compact-segments.ts"],"names":[],"mappings":"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","file":"compact-segments.js","sourcesContent":["#!/usr/bin/env node\n/**\n * `compact-segments` — the standalone compaction daemon CLI (Phase 4d).\n *\n * A thin wrapper over {@link runCompactionCycle}: discover dirty segments → 2-phase-commit compact → GC. It\n * ships the **local-filesystem** backend (zero-dependency, the dev/reference target) and two **deploy modes**:\n *\n *   - `once`  — run a single cycle and exit (the **Lambda / one-shot / cron** shape).\n *   - `loop`  — run a cycle every `intervalMs`, until SIGINT/SIGTERM (the **K8s Deployment / ECS service** shape).\n *\n * **Cloud backends:** rather than have the CLI guess your AWS config, production wires its own ~10-line\n * handler that constructs an `S3ColdDriver` + `DynamoDb{Warm,Registry}Driver` and calls `runCompactionCycle`\n * directly (same two modes — call once, or on a `setInterval`). The library exports everything needed; this\n * binary stays SDK-free (so the core install never pulls a cloud SDK). See the getting-started guide.\n *\n * Config is read from the environment (so it's identical across `once`/`loop` and 12-factor-friendly):\n *   CR_COMPACT_ROOT       (required) — the local-filesystem root holding cold/ warm/ registry/\n *   CR_COMPACT_MODE       once | loop                  (default: once)\n *   CR_COMPACT_INTERVAL_MS                              (default: 30000, loop mode)\n *   CR_COMPACT_NAMESPACE  scope discovery to one namespace\n *   CR_COMPACT_THRESHOLD  min dirty chunks to compact   (default: 1)\n *   CR_COMPACT_KEEP       superseded generations to retain as a reader grace window (default: 1)\n *   CR_COMPACT_OWNER      lease owner id                 (default: `<hostname>:<pid>`)\n *   CR_COMPACT_SHARD / CR_COMPACT_TOTAL_SHARDS  run this worker as shard i of N (set both) — partition the\n *                         fleet across N daemons so each drains only ~1/N of Warm per cycle (gap #3)\n *   CR_COMPACT_MAX_SEGMENTS  cap segments compacted per cycle (a time budget for a Lambda window); the rest\n *                         are deferred to the next cycle, most-dirty first\n *   CR_COMPACT_METRICS    1 to emit each per-attempt compaction `MetricEvent` (retries, bytes, ms, faults) as a\n *                         JSON line on stdout — pipe to your metrics pipeline. Off by default (cycle summaries\n *                         still print regardless); the library's `IMetricsSink` seam is what this wires.\n */\nimport { SystemClock } from '../system-clock';\nimport { hostname } from 'node:os';\nimport { join } from 'node:path';\nimport { pathToFileURL } from 'node:url';\nimport {\n  LocalFsColdDriver,\n  LocalFsRegistryDriver,\n  LocalFsWarmDriver,\n  runCompactionCycle,\n} from '../index';\nimport type { CompactionCycleResult, CompactionDeps, IMetricsSink } from '../index';\n\nexport interface CompactConfig {\n  readonly root: string;\n  readonly mode: 'once' | 'loop';\n  readonly intervalMs: number;\n  readonly namespace?: string;\n  readonly threshold: number;\n  readonly keep: number;\n  readonly owner: string;\n  readonly shard?: number;\n  readonly totalShards?: number;\n  readonly maxSegments?: number;\n}\n\n/** Parse + validate config from an environment map. Throws a clear `Error` on misconfiguration. */\nexport function parseConfig(env: Record<string, string | undefined>): CompactConfig {\n  const root = env.CR_COMPACT_ROOT;\n  if (root === undefined || root === '') {\n    throw new Error('CR_COMPACT_ROOT is required (the local-filesystem storage root)');\n  }\n  const mode = env.CR_COMPACT_MODE ?? 'once';\n  if (mode !== 'once' && mode !== 'loop') {\n    throw new Error(`CR_COMPACT_MODE must be \"once\" or \"loop\"; got ${mode}`);\n  }\n  const num = (name: string, def: number): number => {\n    const raw = env[name];\n    if (raw === undefined || raw === '') return def; // unset OR empty (a common unset-var expansion) → default\n    const v = Number(raw);\n    if (!Number.isFinite(v) || v < 0)\n      throw new Error(`${name} must be a non-negative number; got ${raw}`);\n    return v;\n  };\n  const intOpt = (name: string, min = 0): number | undefined => {\n    const raw = env[name];\n    if (raw === undefined || raw === '') return undefined;\n    const v = Number(raw);\n    if (!Number.isInteger(v) || v < min)\n      throw new Error(`${name} must be an integer >= ${min}; got ${raw}`);\n    return v;\n  };\n  const shard = intOpt('CR_COMPACT_SHARD');\n  const totalShards = intOpt('CR_COMPACT_TOTAL_SHARDS');\n  if ((shard === undefined) !== (totalShards === undefined)) {\n    throw new Error('set both CR_COMPACT_SHARD and CR_COMPACT_TOTAL_SHARDS, or neither');\n  }\n  return {\n    root,\n    mode,\n    intervalMs: num('CR_COMPACT_INTERVAL_MS', 30_000),\n    namespace: env.CR_COMPACT_NAMESPACE,\n    threshold: num('CR_COMPACT_THRESHOLD', 1),\n    keep: num('CR_COMPACT_KEEP', 1),\n    owner: env.CR_COMPACT_OWNER ?? `${hostname()}:${process.pid}`,\n    shard,\n    totalShards,\n    maxSegments: intOpt('CR_COMPACT_MAX_SEGMENTS', 1),\n  };\n}\n\n/** Build LocalFs compaction deps rooted at `<root>/{cold,warm,registry}`, optionally with a metrics sink. */\nexport function localFsDeps(root: string, metrics?: IMetricsSink): CompactionDeps {\n  return {\n    cold: new LocalFsColdDriver(join(root, 'cold')),\n    warm: new LocalFsWarmDriver(join(root, 'warm')),\n    registry: new LocalFsRegistryDriver(join(root, 'registry')),\n    // A real clock, not `{ now }`: outside `core/` ambient time is allowed, and a full clock is what lets\n    // the generation write hand the event loop back instead of blocking the daemon for its whole duration.\n    clock: new SystemClock(),\n    ...(metrics ? { metrics } : {}),\n  };\n}\n\n/** Run a single compaction cycle and return the full result (the unit of work for both deploy modes). */\nexport async function runOnce(\n  deps: CompactionDeps,\n  config: CompactConfig,\n): Promise<CompactionCycleResult> {\n  return runCompactionCycle(deps, {\n    owner: config.owner,\n    namespace: config.namespace,\n    threshold: config.threshold,\n    keep: config.keep,\n    shard: config.shard,\n    totalShards: config.totalShards,\n    maxSegments: config.maxSegments,\n  });\n}\n\nconst sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));\nconst log = (obj: unknown): void => {\n  process.stdout.write(`${JSON.stringify(obj)}\\n`);\n};\n\n/** A stdout `IMetricsSink` (opt-in via CR_COMPACT_METRICS) — one JSON line per compaction `MetricEvent`. */\nfunction stdoutMetricsSink(): IMetricsSink {\n  return {\n    onEvent: (event) => log({ event: 'metric', ...event }),\n  };\n}\n\n/** CLI entry: parse env, then run one cycle (`once`) or loop until a termination signal (`loop`). */\nexport async function main(env: Record<string, string | undefined> = process.env): Promise<void> {\n  const config = parseConfig(env);\n  const deps = localFsDeps(\n    config.root,\n    env.CR_COMPACT_METRICS === '1' ? stdoutMetricsSink() : undefined,\n  );\n\n  if (config.mode === 'once') {\n    const cycle = await runOnce(deps, config);\n    log({\n      event: 'cycle',\n      mode: 'once',\n      candidates: cycle.candidates,\n      compacted: cycle.compacted,\n      deferred: cycle.deferred,\n      results: cycle.results,\n    });\n    return;\n  }\n\n  // loop mode: run forever, one cycle per interval, until SIGINT/SIGTERM.\n  let stop = false;\n  const onSignal = (): void => {\n    stop = true;\n  };\n  process.on('SIGINT', onSignal);\n  process.on('SIGTERM', onSignal);\n  log({ event: 'start', mode: 'loop', intervalMs: config.intervalMs, owner: config.owner });\n  while (!stop) {\n    try {\n      const cycle = await runOnce(deps, config);\n      log({\n        event: 'cycle',\n        candidates: cycle.candidates,\n        compacted: cycle.compacted,\n        deferred: cycle.deferred,\n        results: cycle.results,\n      });\n    } catch (err) {\n      log({ event: 'error', message: (err as Error).message }); // a cycle error must not kill the daemon\n    }\n    if (!stop) await sleep(config.intervalMs);\n  }\n  log({ event: 'stopped' });\n}\n\n// Run only when invoked directly (not when imported by tests). `process.argv[1]` is this file when run as a bin;\n// `pathToFileURL` builds a spec-correct file:// URL (drive letters, spaces, UNC paths) for a robust compare.\nif (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {\n  main().catch((err: unknown) => {\n    process.stderr.write(`${(err as Error).message}\\n`);\n    process.exit(1);\n  });\n}\n"]}

package/dist/cassandra/index.cjs

@@ -1,14 +0,0 @@
-'use strict';
-
-var cassandra = require('@cloudbitmaps/core/cassandra');
-
-
-
-Object.keys(cassandra).forEach(function (k) {
-	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
-		enumerable: true,
-		get: function () { return cassandra[k]; }
-	});
-});
-//# sourceMappingURL=index.cjs.map
-//# sourceMappingURL=index.cjs.map

package/dist/cassandra/index.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs","sourcesContent":[]}

package/dist/cassandra/index.d.cts

@@ -1 +0,0 @@
-export * from '@cloudbitmaps/core/cassandra';

package/dist/cassandra/index.d.ts

@@ -1 +0,0 @@
-export * from '@cloudbitmaps/core/cassandra';

package/dist/cassandra/index.js

@@ -1,3 +0,0 @@
-export * from '@cloudbitmaps/core/cassandra';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/cassandra/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js","sourcesContent":[]}