@cloudbitmaps/roaring 0.1.0-rc.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,12 @@
+CloudRoaring
+Copyright 2026 Sharvil Kadam
+
+This product includes software developed as an open-source project.
+Licensed under the Apache License, Version 2.0 (the "License"); see the LICENSE
+file. You may obtain a copy of the License at:
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+CloudRoaring builds on the Roaring Bitmap data structure and is designed to use
+the CRoaring engine (via the `roaring` Node.js binding) for in-memory bit math.
+Those projects are independent works under their own licenses.

package/PRIVACY.md

@@ -0,0 +1,185 @@
+# Privacy, data protection & shared responsibility
+
+> **Engineering guidance, not legal advice.** This document explains CloudRoaring's data-handling posture and
+> the controls it gives you, so you (and your privacy counsel / DPO) can place it correctly in your compliance
+> program. Regulatory references (GDPR, CCPA/CPRA, HIPAA, …) are illustrative. Nothing here is a compliance
+> certification — before deploying against personal data, get it reviewed by qualified counsel.
+
+## TL;DR — the trust boundary
+
+**CloudRoaring is an embedded library.** It runs inside *your* process/function and talks to *your* storage
+accounts (S3, DynamoDB, local disk — whatever drivers you wire). **It has no hosted backend and transmits no
+data to the authors or any third party** — there is no telemetry, no phone-home, no usage ping. The metrics
+and audit sinks are local and off by default; they only go where *you* send them.
+
+Consequently: **you are the data controller (and/or processor); CloudRoaring is not a sub-processor.** There is
+no SaaS relationship and no data-processing agreement to sign with us, because no data ever reaches us. What
+the library gives you is a set of *mechanisms* — you own the *policy*.
+
+## What CloudRoaring processes — and why it's usually personal data
+
+CloudRoaring's job is to store, at scale, **the fact that an integer ID belongs to a named set**. The moment
+that ID is (or can be linked to) a natural person — which is the intended use — that membership bit is
+**personal data**. Often it is behavioural/inference data, and **membership alone can be special-category**:
+a segment that means "pregnant", "in HIV outreach", "flagged for fraud", "likely-LGBTQ", or
+"political-affiliation" makes the single bit `id ∈ segment` GDPR Art. 9 / CPRA sensitive data, needing an
+explicit lawful basis and heightened safeguards.
+
+**The library cannot see this.** It handles opaque integer IDs in named segments and applies uniform controls;
+it has no way to know segment 7 is sensitive. **Classifying your segments is your responsibility** (see the
+matrix below). If a segment holds special-category data, you should pair it with encryption (a keystore) and
+an audit sink, and a short retention.
+
+## Where the data lives — the transfer / residency surface
+
+You choose every storage location by wiring the drivers, so **data residency is under your control — and your
+responsibility.** The library never moves data to a region you didn't configure, but it also won't stop you
+from constructing a cross-region topology. The points where personal data moves or is processed:
+
+| Location | What's there | Residency note |
+|---|---|---|
+| **Cold** (object store) | immutable `.crbm` generations | the region of the bucket you wire |
+| **Warm** (NoSQL) | pending add/remove deltas | the region of the table you wire |
+| **HOT cache** (process RAM) | decoded chunks, bounded LRU | **wherever your process/Lambda runs** — an EU segment queried from a US function is processed in the US |
+| **Compaction** (daemon) | reads Cold+Warm, writes new Cold | runs wherever you run the daemon |
+| **Intersection** | pulls chunks from N segments into one process | co-locates those segments in one region |
+
+**Guidance (not enforced by the library):** to keep EU data in EU infrastructure, wire region-local drivers
+*and* run the process/daemon in-region; keep a segment's Warm, Cold, and the querying compute in one
+jurisdiction; treat the HOT cache and the intersection runtime as **processing locations** in your transfer
+assessment and breach scope (process RAM, and any heap/core dumps, hold personal data). A fail-closed
+residency-enforcement policy in the library was considered and deferred as over-engineering for v1 — the honest
+posture is "you wire it correctly," documented here.
+
+## Erasure — what "delete" actually means
+
+CloudRoaring gives you three erasure levers with different guarantees. Use them deliberately:
+
+| Lever | API | Guarantee | Use for |
+|---|---|---|---|
+| **Logical remove** | `segment.remove(id)` / `removeMany` | *Immediate* — reads exclude the ID at once (tombstone; `effective = (Cold ∪ adds) \ removes`). The bit **physically persists** in the immutable Cold `.crbm` until that chunk is next compacted. | everyday "take this user out of this audience" |
+| **Physical purge** | `store.compact(ref, { owner })` on demand, or the compaction daemon (`compact-segments` / `runCompactionCycle`) on a schedule | A compaction folds the tombstone into a fresh generation and **physically drops** the bit. | meeting a physical-deletion deadline — *run compaction (the daemon on a schedule, or `store.compact` on demand) inside your SLA* |
+| **Crypto-shred** | `destroySegment` / `eraseNamespace` | *Instant + total* — destroys the segment's wrapped key, so **every** copy (current, prior generations, backups, WORM-locked objects) becomes unreadable without touching the bytes. Requires the segment to be encrypted. | whole-segment / tenant offboarding; erasure under immutable backups (see below) |
+
+**Subject-wide erasure** (GDPR Art. 17 — "forget this person everywhere") is `store.eraseSubject(id, { owner })`:
+it removes the id from every **registered** segment it's in *and* force-compacts those segments on the spot, so
+the bit is physically gone from Cold on return — even for idle/archival segments organic compaction would never
+touch. It reuses the store's own drivers (so build the store with a raw cold driver + a registry). It returns an
+**erasure ledger** (per-segment: removed / physically-purged / which generation retired the bit) as your proof
+of deletion; persist it or route it to your audit sink. `store.subjectReport(id)` answers the read side (Art. 15
+— which segments an id is in). Run erasure without concurrently re-adding the same id; any ledger entry with
+`physicallyPurged:false` (a held compaction lease, or an isolated fault) needs a follow-up `store.compact(ref)` —
+re-running `eraseSubject` won't re-purge it.
+
+**Your exit path** (and a building block for a **data-portability / Art. 20** response): `store.exportSegments(sink,
+{ format })` (and the `export-segments` CLI) dumps every registered segment's effective set to a portable file —
+`roaring` (loadable by any roaring library) or `ndjson` (newline ids) — readable without CloudRoaring. It's a
+**controller-side bulk dump** (all segments, opaque ids), not a per-subject deliverable — the per-subject rights
+are `subjectReport` (Art. 15) / `eraseSubject` (Art. 17). Encrypted segments are decrypted transparently if the
+store has the keystore, so the **export is cleartext — protect it** (the CLI writes owner-only files; also encrypt
+the dump at rest, restrict access, and delete it when done).
+
+**Honest limits.** Logical `remove()` is *not* physical deletion on its own — you need compaction (which
+`eraseSubject` forces, or a scheduled daemon), or crypto-shred. **Per-subject crypto-shred is infeasible** (a
+subject's bit is co-mingled with millions of others in one shared container), so single-subject erasure goes
+through remove + compaction (`eraseSubject`), while crypto-shred (`destroySegment`/`eraseNamespace`) cleanly
+handles segment/tenant-level erasure and is the only erasure that survives immutable backups / WORM.
+
+**Erasure vs. backups / WORM (the trap).** If you enable S3 versioning, Object Lock, or DynamoDB PITR for
+durability, a `remove()`+compaction *does not* reach the retained copies — the deleted bit survives in
+noncurrent versions, locked objects, and backups. **Crypto-shred is the only erasure that survives all of
+them**, because it destroys the key, not the bytes. So: use **per-segment/tenant encryption** as your erasure
+posture under immutable storage; reserve S3 Object Lock **COMPLIANCE** mode for data under a genuine legal
+hold (it *cannot* be deleted before its retention date, by anyone — incompatible with on-demand erasure), and
+prefer **GOVERNANCE** mode where erasure must remain possible.
+
+## Retention & data minimization
+
+The library does not age data out for you — segments grow until you prune them, and "cheap to keep forever" is
+a storage-limitation anti-pattern if the data is personal. **Retention policy is yours.** Practical patterns:
+
+- **Rolling windows** (e.g. "active this week"): keep N daily sub-segments, union them for reads, and drop the
+  oldest wholesale — turning retention into cheap whole-segment deletion (an object delete or crypto-shred),
+  not per-bit aging.
+- **Scheduled compaction** enforces any tombstones you've written for aged-out members within your window.
+- Surface segment age/size via the **metrics sink** so unbounded growth is visible, not silent.
+
+## Legal hold
+
+A litigation/regulatory hold *forbids* deletion — the opposite of erasure — and can apply to the same segment.
+**Enforce a hold with S3 Object Lock**, which is the real, tamper-proof mechanism: in **COMPLIANCE** mode a
+locked Cold object *cannot* be deleted before its retention date by anyone (not even the account root); in
+**GOVERNANCE** mode a privileged role can override. To place a hold on a segment:
+
+1. Enable **Object Lock** on the segment's Cold `.crbm` objects (and enable versioning) for the hold period.
+2. **Exclude the segment from your compaction and erasure runs** — don't call `eraseSubject`, `destroySegment`,
+   or the compaction daemon against held segments, so the current generation (and its members) is preserved.
+3. Decide hold-vs-erasure precedence when both apply to the same subject — that is a **legal determination**;
+   under a hold, erasure is suspended.
+
+CloudRoaring deliberately does **not** ship a native `legalHold` flag: Object Lock is a stronger guarantee than
+an in-library flag (which our own daemon could respect but a direct caller could bypass), so a flag would be
+advisory where Object Lock is enforced at rest. If a real deployment needs a library-managed hold that the
+daemon refuses to purge, it's a clean fast-follow — but the enforced posture is Object Lock + operational
+exclusion, documented here (P10).
+
+## Audit & accountability (GDPR Art. 30 / Art. 5(2))
+
+Wire the **audit sink** (`IAuditSink`) to get an append-only, vendor-neutral record of the compliance-relevant
+state changes — `segment.publish`, `segment.compact`, `segment.erase` (a genuine crypto-shred), and
+`namespace.erase` — for your audit log / SIEM. It is off by default and exception-safe. See the
+[dashboards guide](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/dashboards.md). An erasure *ledger* — per-subject-request proof of physical
+deletion — is returned by `subjectReport` / `eraseSubject` (shipped in Phase 6b).
+
+**Log hygiene:** `segment` / `namespace` are *your* strings and may encode sensitive purpose; IDs are personal
+data. The library never logs bitmap contents or raw IDs, but **you** should treat segment names and IDs as PII
+in your own logs, error reporting, and metric/trace tags — hash or redact them, and prefer opaque/coded
+segment names for sensitive segments (keeping the human label in your own classified registry).
+
+## Shared-responsibility matrix
+
+| Concern | CloudRoaring provides | You (the integrator) must |
+|---|---|---|
+| **Controller/processor role** | an embedded library; sends nothing to us | be the controller/processor; run your own DPAs with *your* cloud providers |
+| **Encryption at rest** | AES-256-GCM envelope encryption, BYOK keystore (`InProcessKeystore`), per-segment DEK + active/recovery KEK | hold and protect your keys (KMS/HSM); enable encryption for sensitive segments |
+| **Erasure** | `remove` (logical), compaction (physical), `destroySegment`/`eraseNamespace` (crypto-shred) | run compaction within your SLA; choose crypto-shred under WORM/backups; classify what needs erasing |
+| **Residency** | region-agnostic drivers; you choose every location | wire region-correct drivers; run compute in-region; assess transfers |
+| **Classification** | opaque handling; a place to keep sensitive segments encrypted + audited | classify your segments (the library can't infer sensitivity) |
+| **Retention** | scheduled compaction; rolling-window pattern | set and enforce retention windows |
+| **Legal hold** | Object Lock guidance (the enforced mechanism; no in-library flag) | place holds via Object Lock; exclude held segments from compaction/erasure; decide precedence |
+| **Accountability** | `IAuditSink` (publish/compact/erase events) | route it to durable, append-only storage; keep your Art. 30 record |
+| **Telemetry** | **none** — no phone-home | (nothing — there is nothing to disable) |
+
+## DPIA skeleton (for deployments with sensitive segments)
+
+A minimal Data-Protection-Impact-Assessment outline to adapt:
+
+1. **Processing description** — which segments, what each membership *means*, source of the IDs, volume.
+2. **Necessity & proportionality** — lawful basis per segment (esp. Art. 9 special-category); why membership
+   is retained and for how long.
+3. **Data flow & residency** — Warm/Cold regions, where compute (HOT cache, intersection) runs, cross-border
+   transfers and their safeguards.
+4. **Risks** — re-identification, sensitive inference (incl. *derived* segments from intersections — treat a
+   `paying ∩ pregnant` result as at least as sensitive as its inputs, and note it's a point-in-time snapshot
+   that does not auto-honour later erasures of source members), breach scope (incl. process RAM / dumps).
+5. **Controls** — encryption + crypto-shred, erasure SLA (scheduled compaction), retention windows, audit
+   sink, access control on keys and storage, redaction of names/IDs in logs.
+6. **Residual risk & sign-off** — DPO review.
+
+## Art. 30 record — mapping template
+
+Map CloudRoaring's processing onto the categories a record of processing needs:
+
+| Art. 30 field | CloudRoaring mapping |
+|---|---|
+| Categories of processing | storage of set-membership; set intersection; compaction; caching |
+| Categories of data subjects / data | your IDs' subjects; membership (possibly special-category) |
+| Recipients | none external to your infrastructure (no sub-processor) |
+| Transfers | any cross-region driver/compute topology *you* configure |
+| Retention | your per-segment policy (enforced via scheduled compaction / rolling windows) |
+| Security measures | AES-256-GCM at rest, crypto-shred erasure, audit sink, your access controls |
+
+---
+
+**See also:** the [getting-started guide](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/getting-started.md) (§9 encryption/crypto-shred, §10
+metrics, §12 audit) and the [dashboards guide](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/dashboards.md).

package/README.md

@@ -0,0 +1,40 @@
+# @cloudbitmaps/roaring
+
+**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 — with the fast, familiar in-memory API:
+`add`, `has`, `remove`, `count`, `intersect`.
+
+This is the **flagship flavor** of the [CloudBitmaps](https://github.com/cloudbitmaps/cloudbitmaps) family: the
+roaring codec (CRoaring, via `roaring`) plus the `CloudRoaring` facade, on top of the codec-agnostic
+[`@cloudbitmaps/core`](https://www.npmjs.com/package/@cloudbitmaps/core) engine — which arrives **transitively**,
+so this is the only package you install.
+
+```bash
+npm i @cloudbitmaps/roaring @aws-sdk/client-s3 @aws-sdk/client-dynamodb   # + only the SDK(s) you use
+```
+
+```ts
+import { CloudRoaring } from '@cloudbitmaps/roaring';
+import { S3ColdDriver } from '@cloudbitmaps/roaring/s3';
+import { DynamoDbWarmDriver } from '@cloudbitmaps/roaring/dynamodb';
+```
+
+Every storage driver is re-exported on a matching subpath (`/s3`, `/gcs`, `/azure`, `/dynamodb`, `/postgres`,
+`/redis`, `/mongodb`, `/cassandra`, `/mysql`); each backend SDK is an optional peer dependency, so the main entry
+stays lean. Ships two CLIs: `compact-segments` and `export-segments`.
+
+## Measured, not modeled
+
+Benchmarked against **real** S3 + DynamoDB in `us-east-1`, not an emulator: **$0.75 per million** incremental
+writes, **$0.14 per million** `count()`s, **$5.88 per million** segment publishes — against an always-on Redis-HA
+line of **$346/month, standing**. DynamoDB capacity is taken from AWS's own `ConsumedCapacity` rather than
+estimated. `count()` on a published segment does **0 payload reads**, and intersecting two 2,000,000-id segments
+fetches only the shared chunks.
+
+The trade is stated plainly rather than buried: in-region, a RAM store answers a single membership check 10–20×
+faster than a warm-tier round trip. If you need a sub-millisecond p99 on a working set that won't fit a bounded
+hot cache, use Redis. If your sets are large, mostly read, and shouldn't cost $346/month to keep warm, use this.
+
+Full README, guides, [benchmarks](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/benchmarks.md) (with
+the method and what the numbers do *not* establish), and the design corpus live in the
+[repository](https://github.com/cloudbitmaps/cloudbitmaps). Licensed Apache-2.0.

package/dist/azure/index.cjs

@@ -0,0 +1,14 @@
+'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

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

package/dist/azure/index.d.cts

@@ -0,0 +1,9 @@
+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

@@ -0,0 +1,9 @@
+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

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

package/dist/azure/index.js.map

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

package/dist/bin/compact-segments.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+import { src_exports, runCompactionCycle } from '../chunk-JWCQLJUG.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")),
+    clock: { now: () => Date.now() },
+    // the bin is outside core/, so ambient time is allowed here
+    ...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