@cross-deck/buckets 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Crossdeck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,449 @@
+<div align="center">
+
+# Buckets
+
+### Know exactly what every database read costs you — and who caused it.
+
+**Buckets is a zero-overhead cost attribution layer for your backend.**
+Every read, write, and delete is tagged to the feature that served it and the
+user who triggered it — automatically, with no blind spots, and without ever
+becoming a cost itself.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](LICENSE)
+[![npm](https://img.shields.io/badge/npm-%40cross-deck%2Fbuckets-black)](https://www.npmjs.com/package/@cross-deck/buckets)
+[![Firestore](https://img.shields.io/badge/datastore-Firestore-black)](#datastore-support)
+[![Made by Crossdeck](https://img.shields.io/badge/made%20by-Crossdeck-black)](https://cross-deck.com)
+
+</div>
+
+---
+
+## The 4am problem
+
+You ship a feature. A week later your database bill is up 5×. Your provider's
+console shows you *one number*: **9.6M reads today.** It does not tell you which
+feature, which query, or which users are responsible. So you start guessing —
+adding logs, bisecting deploys, staring at dashboards at 4am.
+
+We lived this. On our own product, one tile was quietly issuing 15,000 reads
+*per render*. It was hiding in plain sight for a day. When we finally instrumented
+our read sites by hand, we *still* missed the path that mattered most — the
+ingest pipeline, **1.4M reads a day, the majority of our entire bill, invisible.**
+
+The lesson: **humans instrument what they're looking at, and miss the path that
+matters.** Manual cost tracking doesn't fail loudly. It fails silently, and you
+find out on the invoice.
+
+Buckets fixes this by construction.
+
+---
+
+## Quickstart
+
+```bash
+npm install @cross-deck/buckets
+```
+
+**1. Install the meter once, at process start.** From this line on, *every*
+operation on *every* code path is counted — no per-call-site work — and a coalesced
+summary is reported to your Crossdeck project about once a minute. Your `cd_sk_`
+secret key is all the wiring there is.
+
+```ts
+import { init, installFirestoreMeter } from "@cross-deck/buckets";
+import { getFirestore, Firestore, Query, DocumentReference } from "firebase-admin/firestore";
+
+init({ apiKey: process.env.CROSSDECK_SECRET_KEY });   // reports up to Crossdeck (~1/min)
+installFirestoreMeter({ Firestore, Query, DocumentReference });   // the trap
+```
+
+That's the whole setup. The collector now sits in your path to your database,
+counts in memory, and reports a tiny summary up — **it never reads your data and
+never adds a query.**
+
+**2. Name the paths that matter** with `bucket()` — every operation inside is
+attributed to that name (anything you don't name still shows up, labelled by its
+collection).
+
+```ts
+import { bucket } from "@cross-deck/buckets";
+
+await bucket("pulse-map", async () => {
+  const dots  = await db.collection("visitors").where("live", "==", true).get(); // → pulse-map
+  const owner = await db.doc(`projects/${appId}`).get();                          // → pulse-map
+});
+```
+
+**3. That's it.** Open your Crossdeck dashboard and your operations are there —
+`pulse-map`, every other bucket you named, and an `unknown` row for anything you
+haven't named yet. Buckets counted them at the database driver, not in your code.
+
+---
+
+## What you get
+
+A small, cheap, daily document per app — the **rollup**. This is the entire output,
+and it's a stable, public schema you can read with or without this library:
+
+```jsonc
+// costRollups/production_2026-06-18_proj_3a8f137
+{
+  "env": "production",
+  "date": "2026-06-18",
+  "appId": "proj_3a8f137",
+
+  // who caused it → which feature → op type
+  "ops": {
+    "runtime":  { "pulse-map": { "read": 412000, "write": 8 },
+                  "dashboard": { "read": 765000 } },
+    "internal": { "reconcile": { "read": 1200, "write": 96 } }
+  },
+
+  // the fine grain: which surface / layer spent the reads
+  "byLabel": {
+    "people-feed":     { "read": 412000 },
+    "people-journey":  { "read": 3000 },
+    "col:events":      { "read": 21000 }
+  }
+}
+```
+
+Now "9.6M reads today" becomes *"765k of them are the dashboard, on the runtime
+path — and within that, the people-feed layer is 137× heavier than the
+journey-detail layer."* That's the difference between a number and an answer.
+
+---
+
+## "Did my fix work?" — the one-click loop
+
+Buckets keeps reads at **hourly** grain for one reason: so you can ship a change
+and *watch it land the same hour*, not guess from tomorrow's bill.
+
+The loop:
+
+1. You ship a fix to a heavy read path.
+2. You click **I shipped a fix** on the dashboard. That stamps the exact moment.
+3. Buckets splits the timeline there and shows the verdict in **reads / hour** —
+   the hours *before* your fix vs the hours *after* it:
+
+   ```
+   since your fix · 2h ago
+   1,240  →  310   reads / hour      −75%   930 fewer reads / hour · 2h observed
+   ```
+
+4. The first full hour after you click gives a real number; it settles as more
+   hours land. No marker set yet? The header shows the plain day-over-day rate and
+   a button to start the loop.
+
+It is just a marker — a timestamp the dashboard remembers per project. Click it
+again when you ship again (it moves to *now*); **clear** it to go back to the
+day-over-day view. Nothing about the marker touches your read path or your bill;
+it only changes where the dashboard draws the *before/after* line.
+
+> Why a button and not a date field: a fix isn't a *day*, it's a *moment*. A date
+> picker can't tell you whether the deploy you pushed twenty minutes ago worked —
+> hourly before/after can.
+
+---
+
+## How it works
+
+Three ideas, stacked. Understand these and you understand the whole library.
+
+```
+   request boundary                    every read, anywhere
+        │                                       │
+        ▼                                       ▼
+ ┌──────────────┐    AsyncLocalStorage   ┌──────────────────┐
+ │  ① THE TAG   │ ─────────────────────▶ │   ② THE TRAP     │
+ │  tag once,   │     ambient context    │  patch the SDK   │
+ │  at the edge │                        │  once, not your  │
+ └──────────────┘                        │  call sites      │
+                                         └────────┬─────────┘
+                                                  ▼
+                                         ┌──────────────────┐
+                                         │  ③ THE METER     │
+                                         │  count in memory,│
+                                         │  flush ~1×/min   │
+                                         └────────┬─────────┘
+                                                  ▼
+                                            the rollup doc
+```
+
+**① Tag once at the edge, attribute at the leaf.** Set the tag when a request
+arrives; it propagates through every async fan-out automatically. Attribution
+happens where the read *executes*, not where you guessed at the boundary.
+
+**② Trap at the SDK, not at the call site.** Buckets patches the database driver's
+read methods once. From then on every read is counted under the ambient tag — the
+ingest job, the cron, the trigger, the path you forgot. **No blind spots, by
+construction.** This is the part hand-rolled instrumentation can never get right.
+
+**③ Count in memory, write rarely.** Counts accumulate in-process and flush to one
+incremented document per (app, day) about once a minute — regardless of whether
+you served 10 operations or 10 million. **The monitor never becomes the thing it
+monitors.**
+
+---
+
+## Safe to put on your read path
+
+Buckets patches your database driver. That demands a higher bar than most
+libraries, so every wrapper is defensive by construction:
+
+1. it calls the **real** method first and captures the result,
+2. it counts inside a `try/catch` that **cannot throw into your code**,
+3. it **always returns the real result, untouched.**
+
+It physically cannot break a read, change a result, or add latency beyond a single
+in-memory counter increment. If a count is ever wrong, it's a *measurement* error —
+never a correctness or availability one. Install is idempotent. A failed flush
+drops one window of counts rather than risk corrupting anything.
+
+> Buckets is observability, not a transactional ledger. It is built to be wrong
+> by a rounding error under catastrophe, and never, ever to take your app down.
+
+| Guarantee | How |
+|---|---|
+| **Every read is caught** | SDK-level trap — no read on any path is ever uncounted or silent |
+| **Every read is labeled** | Path-based cascade always tags the collection + project, even untagged |
+| **Untagged is loud, never hidden** | Reads outside a tagged context surface as `unknown` coverage — surfaced, never dropped |
+| **Never a cost driver** | In-memory buffers, ~1 write/min per app, tiny daily docs |
+| **Never breaks a read** | Real-method-first · count-in-try/catch · always-return-untouched |
+| **Concurrency-safe** | Atomic increments; snapshot-and-clear before each flush |
+| **Honest under failure** | A dropped flush loses a window, never double-counts |
+
+### What "no blind spots" actually means
+
+Be precise, because the difference matters: **the trap guarantees every read is
+*caught* and labeled by its collection — none is ever silent.** Sorting a read into
+a *feature* and an *origin* ("this was the pulse-map, on a user's behalf") requires a
+tag set at the request boundary. A read that runs outside any tagged context is
+still caught and still labeled by collection (`col:events`) and project — it simply
+lands in the **`unknown`** origin until you tag that entry point.
+
+`unknown` is **first-class and loud**, never folded away and never filtered out of
+the surface. A growing `unknown` bucket is the meter telling you "there's a real
+read path here you haven't tagged yet" — which is exactly the signal you want, and
+the opposite of a blind spot. Tag the entry point and it resolves into a named
+feature. The one thing that never happens is a read going *uncounted*.
+
+---
+
+## From `unknown` to named — tagging
+
+The trap catches every read for free and labels it by collection (`col:events`) —
+that answers *what's being read.* Buckets becomes genuinely useful the moment you
+**name the read path yourself** — wrap it in a bucket:
+
+```ts
+import { bucket } from "@cross-deck/buckets";
+
+// every read inside here is attributed to "nightly-export"
+await bucket("nightly-export", async () => {
+  const rows = await db.collection("events").where("exported", "==", null).get();
+  // …
+});
+```
+
+Now those `col:events` reads that were sitting under `unknown` show up as
+`nightly-export` on the dashboard. See an `unknown` bucket you can't explain?
+**Drill in, wrap that path in a `bucket()`, ship, look again** — and keep going,
+coarse to fine, until the read is named all the way down to the line you care
+about. Two grains:
+
+- **Tag a bucket** (coarse) — a whole handler or job: `bucket("pulse-map", handler)`
+- **Tag a single read** (fine) — one query: `bucket("owner-lookup", () => db.doc(id).get())`
+
+`unknown` is never a dead end. It's a to-do with a one-line fix — exactly like a
+custom analytics event you haven't named yet. You tag until you've found your
+source; Buckets just shows the names resolving in.
+
+---
+
+## What Buckets is — and what it deliberately isn't
+
+Buckets is **telemetry, done right.** It tells you *what* your costs are and
+*exactly where they come from.* It does **not** tell you *why* a number changed or
+*what to do about it* — and that restraint is intentional.
+
+The labels Buckets emits are deliberately low-level: the collection, the feature,
+the origin, the count. **It will never write an interpretation** — no
+`scan-on-load`, no `regression`, no `anomaly`. Those are judgements, and judgement
+is a separate concern that lives in a separate layer.
+
+We think that's the honest line. Collection should be a free, open, commodity
+primitive that the whole ecosystem can build on — so we open-sourced it, and we
+publish the rollup schema so you can consume it with any tool you like, including
+your own. **The best place to read Buckets data should be earned, never locked.**
+
+### Cost should page you like an exception — not surprise you like an invoice
+
+You already know what your code *should* do. You wrote the analytics pipeline; you
+know it should read ~20k times a day, not 2M. The problem has never been a lack of
+knowledge — it's that when reality departs from what you know, **nothing tells
+you.** You find out at month-end, on a bill that's already due.
+
+That's the difference between the two developers who hit the same bug. One reviews
+the console at the end of the month and finds read volume that's been running ~100×
+normal for weeks — a *verdict*, already billed, no cause attached. The other gets a
+message ninety seconds in — *"analytics is at 2M reads, expected 20k"* — opens the
+dashboard, sees which bucket, knows the code, and ships the fix before lunch. The
+spike never gets a month to run. Same bug. The only difference is *when they found
+out*.
+
+A report is something you remember to open. An error is something that finds you.
+Buckets gives you the open measurement that makes the difference possible — every
+read attributed, in real time, with no blind spots.
+
+### Get paged in Slack before the bill is in the post
+
+This is the part that turns Buckets from a dashboard you remember to open into a
+system that *finds you*. Connect Slack to [Crossdeck](https://cross-deck.com) and it
+watches your buckets for you:
+
+1. **It learns your normal.** For ~7 days it quietly builds a baseline of what each
+   hour looks like — *per hour-of-day*, so a busy 2pm is judged against other 2pms,
+   never against 3am. No alerts during this; it's collecting.
+2. **It follows your fixes.** The baseline is recency-weighted: arrive bleeding 2M
+   reads, fix down to 50k, and it forgets the 2M and settles at your new normal. So
+   a later 50k→500k spike is a *real* deviation, not lost under an old number.
+3. **It pings only on a real surge.** When a completed hour breaks the baseline (a
+   big statistical jump *and* a meaningful multiple — both gates, so a tiny bucket
+   jittering never pages you), you get a Slack message:
+   > 🟡 **Read spike detected** — *512,000 reads* in the last hour, about *10×* your
+   > normal for this time of day (~50,000). Open Buckets to see which bucket moved.
+4. **You stay in control.** Shipped a feature you *know* adds reads? One click —
+   **"Expected — quiet for 24h"** — and it hushes while the baseline re-bases. Your
+   knowledge of your own roadmap is the final authority; it never pretends to know
+   better.
+
+An ongoing spike pings **once**, not every hour. Cold-start means it never cries
+wolf before it knows you. And — the rule that holds the whole system together — the
+thing that watches your read bill **never runs one up**: every check reads a small
+maintained summary, never scans your data.
+
+> The open collector in this repo produces the buckets. The baseline, the anomaly
+> detection, and the Slack alert are the layer [Crossdeck](https://cross-deck.com)
+> builds on top. The collector stands alone, free, forever — Crossdeck is where the
+> buckets start paging you.
+
+---
+
+## Counting model
+
+| Operation | Counted as |
+|---|---|
+| Query returning N docs | N reads |
+| Empty query | 1 read *(your provider bills a minimum of one)* |
+| `doc.get()` | 1 read |
+| `getAll(...refs)` | one read per ref |
+| Write / delete | 1 each |
+
+Counts are **defensible** — every one traces to a billed operation, so the rollup
+reconciles against your provider's invoice instead of drifting from it.
+
+---
+
+## Datastore support
+
+| Datastore | Status |
+|---|---|
+| **Google Cloud Firestore** (firebase-admin) | ✅ Supported |
+| Postgres · DynamoDB · MongoDB | 🔜 Adapter interface is public — contributions welcome |
+
+The trap *pattern* generalises to any driver with interceptable read methods, and
+the storage `Sink` interface is datastore-agnostic. Firestore is the only adapter
+we ship and support today — we'd rather support one datastore excellently than
+five badly.
+
+---
+
+## API
+
+```ts
+init({ apiKey, endpoint?, flushIntervalMs? })   // configure once; reports up to Crossdeck
+
+bucket(name, fn)               // ← the one verb you'll use: attribute everything inside to `name`
+
+installFirestoreMeter(classes) // the Firestore trap (the only adapter today)
+flush()                        // force a flush (tests / shutdown)
+
+// lower-level, if you need it:
+runWithCostTag(tag, fn) · enterCostTag(tag) · refineCostTag(patch) · currentCostTag()
+recordReads(n) · recordWrites(n) · recordDeletes(n)
+```
+
+One import to set up, one call to install, one verb to name a path. That's the
+whole footprint. The reporting (collector → `POST /v1/buckets/report` → your
+maintained rollup → dashboard) happens automatically — you never touch it.
+
+---
+
+## Roadmap
+
+- [x] Core: tag · trap · meter · rollup
+- [x] Firestore adapter
+- [x] Public, versioned rollup schema
+- [ ] Postgres adapter
+- [ ] `compute` (invocation + CPU-ms) attribution in the public build
+- [ ] OpenTelemetry export
+- [ ] Community sink adapters (BigQuery, ClickHouse, S3)
+
+The *intelligence* on top of these rollups — regression detection, deploy
+attribution, forecasting, suggested fixes — is **not** on this roadmap by design.
+That's the line between the open primitive and the product built on it.
+
+---
+
+## FAQ
+
+**Is this really free, or is there a catch?**
+Genuinely free, MIT, forever. The collector and the schema are the open primitive.
+We make money on the *interpretation* layer (Crossdeck), not on locking up your
+own cost data. Your rollups are yours, in your datastore, readable by anything.
+
+**Won't patching the SDK slow down my reads?**
+No. The overhead is one in-memory map increment per read. No I/O is added to the
+read path; writes happen in a batched flush roughly once a minute.
+
+**What if Buckets crashes or its sink is down?**
+Your reads are unaffected — every wrapper returns the real result no matter what
+happens inside the meter. You lose at most one ~60-second window of *counts*.
+
+**Why not just read my cloud provider's billing export?**
+Billing exports tell you the total. They can't tell you *which feature* or *which
+user* — the attribution that lets you actually fix the cost. That's the entire
+point of Buckets.
+
+**Does it work with `firebase-functions` / serverless cold starts?**
+Yes. The meter flushes on `SIGTERM` and `beforeExit`, so a scaling-to-zero
+instance writes its final window before it dies.
+
+---
+
+## Contributing
+
+Adapters, tests, and docs are the highest-leverage contributions. The bar for
+anything touching the read path is the safety contract above — real-method-first,
+never-throws, always-returns-untouched, with a test that proves it. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Who's behind this
+
+Buckets is built and battle-tested by **[Crossdeck](https://cross-deck.com)** —
+revenue, analytics, identity, and cost intelligence for app developers. We run
+Buckets in production on every read our own platform serves. If it's good enough
+to protect our invoice, it's good enough for yours.
+
+## License
+
+[MIT](LICENSE). Use it anywhere, including commercially. No attribution required
+(though a ⭐ is always appreciated).
+
+<div align="center">
+<br>
+<strong>Stop guessing what your database costs. Start knowing.</strong>
+<br><br>
+<code>npm install @cross-deck/buckets</code>
+</div>

package/dist/adapters/firestore.d.ts

@@ -0,0 +1,41 @@
+type AnyFn = (...args: any[]) => any;
+/**
+ * The firebase-admin Firestore classes to patch. Pass the module namespace from
+ * `firebase-admin/firestore` — only the prototypes present are patched.
+ */
+export interface FirestoreClasses {
+    Query?: {
+        prototype: {
+            get?: AnyFn;
+        };
+    };
+    DocumentReference?: {
+        prototype: {
+            get?: AnyFn;
+        };
+    };
+    Transaction?: {
+        prototype: {
+            get?: AnyFn;
+            getAll?: AnyFn;
+        };
+    };
+    Firestore?: {
+        prototype: {
+            getAll?: AnyFn;
+        };
+    };
+}
+/**
+ * Install the universal read meter on the firebase-admin Firestore classes. Call
+ * ONCE at process start, before any reads. Pass the namespace from
+ * `firebase-admin/firestore` so the exact prototypes the SDK uses are patched:
+ *
+ *   import * as Firestore from "firebase-admin/firestore";
+ *   installFirestoreMeter(Firestore);
+ */
+export declare function installFirestoreMeter(classes: FirestoreClasses): void;
+/** Test-only: reset the install guard so a suite can re-patch fresh prototypes. */
+export declare function __resetFirestoreMeterForTests(): void;
+export {};
+//# sourceMappingURL=firestore.d.ts.map

package/dist/adapters/firestore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"firestore.d.ts","sourceRoot":"","sources":["../../src/adapters/firestore.ts"],"names":[],"mappings":"AA+BA,KAAK,KAAK,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;AAErC;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE;QAAE,SAAS,EAAE;YAAE,GAAG,CAAC,EAAE,KAAK,CAAA;SAAE,CAAA;KAAE,CAAC;IACvC,iBAAiB,CAAC,EAAE;QAAE,SAAS,EAAE;YAAE,GAAG,CAAC,EAAE,KAAK,CAAA;SAAE,CAAA;KAAE,CAAC;IACnD,WAAW,CAAC,EAAE;QAAE,SAAS,EAAE;YAAE,GAAG,CAAC,EAAE,KAAK,CAAC;YAAC,MAAM,CAAC,EAAE,KAAK,CAAA;SAAE,CAAA;KAAE,CAAC;IAC7D,SAAS,CAAC,EAAE;QAAE,SAAS,EAAE;YAAE,MAAM,CAAC,EAAE,KAAK,CAAA;SAAE,CAAA;KAAE,CAAC;CAC/C;AAwDD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAsDrE;AAED,mFAAmF;AACnF,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD"}

package/dist/adapters/firestore.js

@@ -0,0 +1,145 @@
+/**
+ * adapters/firestore — the universal Firestore read meter (the trap).
+ *
+ * THE LESSON (learned on a real product): per-call-site `recordReads()`
+ * instrumentation MISSES paths. You meter the read sites you're looking at and
+ * leave the cron / trigger / ingest path uncounted — often the majority of reads,
+ * invisible. Humans tag what they see and miss the path that matters.
+ *
+ * THE FIX: patch the admin SDK's read methods ONCE. From install onward, EVERY
+ * read — anywhere, on any code path — is counted under the ambient tag, with zero
+ * per-call-site work and no blind spots.
+ *
+ * SAFETY CONTRACT — this sits on your production read path, so it is defensive by
+ * construction. Each wrapper:
+ *   1. calls the REAL method first and captures the result,
+ *   2. counts in a try/catch that can never throw into the caller,
+ *   3. ALWAYS returns the real result, untouched.
+ * It cannot break a read, change a result, or add latency beyond one in-memory
+ * counter increment. A wrong count is a measurement error, never a correctness or
+ * availability one. Idempotent — calling it twice patches once.
+ *
+ * COUNTING MODEL — a query returning N docs = N reads (an empty result still bills
+ * 1, which the meter enforces). A document get = 1. getAll(...) = the ref count.
+ * CollectionReference.get IS Query.get (shared prototype method), so patching Query
+ * covers collections with no double-count.
+ */
+import { recordReads } from "../cost-meter.js";
+let installed = false;
+/** `projects/{id}/…` → the project id, else undefined. Pure string op. */
+function projectFromPath(path) {
+    const parts = path.split("/");
+    const i = parts.indexOf("projects");
+    return i >= 0 && parts[i + 1] ? parts[i + 1] : undefined;
+}
+/**
+ * Derive { collection, projectId } from the read target's path so an UNtagged read
+ * cascades to `col:<collection>` instead of "uncategorized". PURE CPU; never reads,
+ * never throws. Falls back to firebase-admin's internal `_queryOptions` for filtered
+ * queries (which don't expose `.path`).
+ */
+function hintFrom(target) {
+    try {
+        const p = typeof target?.path === "string" ? target.path : "";
+        if (p) {
+            const parts = p.split("/").filter(Boolean);
+            const collection = parts.length % 2 === 0 ? parts[parts.length - 2] : parts[parts.length - 1];
+            return { collection, projectId: projectFromPath(p) };
+        }
+        const qo = target?._queryOptions;
+        if (qo) {
+            const collection = typeof qo.collectionId === "string" ? qo.collectionId : undefined;
+            const parent = typeof qo.parentPath?.relativeName === "string"
+                ? qo.parentPath.relativeName
+                : typeof qo.parentPath?.toString === "function"
+                    ? String(qo.parentPath.toString())
+                    : "";
+            return { collection, projectId: parent ? projectFromPath(parent) : undefined };
+        }
+    }
+    catch {
+        /* the meter must never throw */
+    }
+    return undefined;
+}
+function meterSnap(snap, hint) {
+    try {
+        const size = snap?.size;
+        recordReads(typeof size === "number" ? size : 1, hint);
+    }
+    catch {
+        /* best-effort */
+    }
+}
+function meterCount(n, hint) {
+    try {
+        recordReads(n, hint);
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/**
+ * Install the universal read meter on the firebase-admin Firestore classes. Call
+ * ONCE at process start, before any reads. Pass the namespace from
+ * `firebase-admin/firestore` so the exact prototypes the SDK uses are patched:
+ *
+ *   import * as Firestore from "firebase-admin/firestore";
+ *   installFirestoreMeter(Firestore);
+ */
+export function installFirestoreMeter(classes) {
+    if (installed)
+        return;
+    installed = true;
+    const { Query, DocumentReference, Transaction, Firestore } = classes;
+    // Query.get — covers Query AND CollectionReference (shared prototype method).
+    const qGet = Query?.prototype?.get;
+    if (qGet) {
+        Query.prototype.get = async function (...args) {
+            const snap = await qGet.apply(this, args);
+            meterSnap(snap, hintFrom(this));
+            return snap;
+        };
+    }
+    // DocumentReference.get — a single doc = 1 read.
+    const dGet = DocumentReference?.prototype?.get;
+    if (dGet) {
+        DocumentReference.prototype.get = async function (...args) {
+            const snap = await dGet.apply(this, args);
+            meterCount(1, hintFrom(this));
+            return snap;
+        };
+    }
+    // Transaction.get — query or doc; size when present, else 1.
+    const tGet = Transaction?.prototype?.get;
+    if (tGet) {
+        Transaction.prototype.get = async function (...args) {
+            const res = await tGet.apply(this, args);
+            meterSnap(res, hintFrom(args[0]));
+            return res;
+        };
+    }
+    // Transaction.getAll(...refs) — one read per ref.
+    const tGetAll = Transaction?.prototype?.getAll;
+    if (tGetAll) {
+        Transaction.prototype.getAll = async function (...args) {
+            const res = await tGetAll.apply(this, args);
+            meterCount(Array.isArray(res) ? res.length : args.length || 1, hintFrom(args[0]));
+            return res;
+        };
+    }
+    // Firestore.getAll(...refs) — batched doc reads.
+    const fGetAll = Firestore?.prototype?.getAll;
+    if (fGetAll) {
+        Firestore.prototype.getAll = async function (...args) {
+            const res = await fGetAll.apply(this, args);
+            meterCount(Array.isArray(res) ? res.length : args.length || 1, hintFrom(args[0]));
+            return res;
+        };
+    }
+}
+/** Test-only: reset the install guard so a suite can re-patch fresh prototypes. */
+export function __resetFirestoreMeterForTests() {
+    installed = false;
+}
+//# sourceMappingURL=firestore.js.map

package/dist/adapters/firestore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"firestore.js","sourceRoot":"","sources":["../../src/adapters/firestore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,WAAW,EAAiB,MAAM,kBAAkB,CAAC;AAE9D,IAAI,SAAS,GAAG,KAAK,CAAC;AAgBtB,0EAA0E;AAC1E,SAAS,eAAe,CAAC,IAAY;IACnC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACpC,OAAO,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3D,CAAC;AAED;;;;;GAKG;AACH,SAAS,QAAQ,CAAC,MAAW;IAC3B,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,OAAO,MAAM,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,IAAI,CAAC,EAAE,CAAC;YACN,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAC3C,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAC9F,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,CAAC;QACD,MAAM,EAAE,GAAG,MAAM,EAAE,aAAa,CAAC;QACjC,IAAI,EAAE,EAAE,CAAC;YACP,MAAM,UAAU,GAAG,OAAO,EAAE,CAAC,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC;YACrF,MAAM,MAAM,GACV,OAAO,EAAE,CAAC,UAAU,EAAE,YAAY,KAAK,QAAQ;gBAC7C,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,YAAY;gBAC5B,CAAC,CAAC,OAAO,EAAE,CAAC,UAAU,EAAE,QAAQ,KAAK,UAAU;oBAC7C,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC;oBAClC,CAAC,CAAC,EAAE,CAAC;YACX,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;QACjF,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,gCAAgC;IAClC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,SAAS,CAAC,IAAa,EAAE,IAAe;IAC/C,IAAI,CAAC;QACH,MAAM,IAAI,GAAI,IAAiC,EAAE,IAAI,CAAC;QACtD,WAAW,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,iBAAiB;IACnB,CAAC;AACH,CAAC;AACD,SAAS,UAAU,CAAC,CAAS,EAAE,IAAe;IAC5C,IAAI,CAAC;QACH,WAAW,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,iBAAiB;IACnB,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAyB;IAC7D,IAAI,SAAS;QAAE,OAAO;IACtB,SAAS,GAAG,IAAI,CAAC;IACjB,MAAM,EAAE,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAErE,8EAA8E;IAC9E,MAAM,IAAI,GAAG,KAAK,EAAE,SAAS,EAAE,GAAG,CAAC;IACnC,IAAI,IAAI,EAAE,CAAC;QACT,KAAM,CAAC,SAAS,CAAC,GAAG,GAAG,KAAK,WAA0B,GAAG,IAAW;YAClE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC1C,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;YAChC,OAAO,IAAI,CAAC;QACd,CAAC,CAAC;IACJ,CAAC;IAED,iDAAiD;IACjD,MAAM,IAAI,GAAG,iBAAiB,EAAE,SAAS,EAAE,GAAG,CAAC;IAC/C,IAAI,IAAI,EAAE,CAAC;QACT,iBAAkB,CAAC,SAAS,CAAC,GAAG,GAAG,KAAK,WAA0B,GAAG,IAAW;YAC9E,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC1C,UAAU,CAAC,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;YAC9B,OAAO,IAAI,CAAC;QACd,CAAC,CAAC;IACJ,CAAC;IAED,6DAA6D;IAC7D,MAAM,IAAI,GAAG,WAAW,EAAE,SAAS,EAAE,GAAG,CAAC;IACzC,IAAI,IAAI,EAAE,CAAC;QACT,WAAY,CAAC,SAAS,CAAC,GAAG,GAAG,KAAK,WAA0B,GAAG,IAAW;YACxE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACzC,SAAS,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAClC,OAAO,GAAG,CAAC;QACb,CAAC,CAAC;IACJ,CAAC;IAED,kDAAkD;IAClD,MAAM,OAAO,GAAG,WAAW,EAAE,SAAS,EAAE,MAAM,CAAC;IAC/C,IAAI,OAAO,EAAE,CAAC;QACZ,WAAY,CAAC,SAAS,CAAC,MAAM,GAAG,KAAK,WAA0B,GAAG,IAAW;YAC3E,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC5C,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAClF,OAAO,GAAG,CAAC;QACb,CAAC,CAAC;IACJ,CAAC;IAED,iDAAiD;IACjD,MAAM,OAAO,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC;IAC7C,IAAI,OAAO,EAAE,CAAC;QACZ,SAAU,CAAC,SAAS,CAAC,MAAM,GAAG,KAAK,WAA0B,GAAG,IAAW;YACzE,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC5C,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAClF,OAAO,GAAG,CAAC;QACb,CAAC,CAAC;IACJ,CAAC;AACH,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,6BAA6B;IAC3C,SAAS,GAAG,KAAK,CAAC;AACpB,CAAC"}

package/dist/cost-context.d.ts

@@ -0,0 +1,25 @@
+export interface CostTag {
+    /** Optional coarse grouping (a caller-defined surface name). */
+    feature?: string;
+    /** The bucket name — what `bucket()` sets. Drives the report's `byLabel`. */
+    label?: string;
+}
+/** Run `fn` with `tag` bound for its entire async subtree. */
+export declare function runWithCostTag<T>(tag: CostTag, fn: () => T): T;
+/** Bind a tag for the remainder of the current async context (no closure to wrap). */
+export declare function enterCostTag(tag: CostTag): void;
+/** Refine the live tag in place (e.g. stamp a feature after the boundary). */
+export declare function refineCostTag(patch: Partial<CostTag>): void;
+/** The current tag, or a safe empty default outside any bound context. */
+export declare function currentCostTag(): CostTag;
+/**
+ * `bucket(name, fn)` — the headline verb, the `track()` of cost. Run `fn` with
+ * every operation inside it attributed to the bucket `name`; the attribution
+ * rides the async subtree automatically. The one verb most developers ever touch:
+ *
+ *   await bucket("nightly-export", async () => {
+ *     const rows = await db.collection("events").where(...).get(); // → "nightly-export"
+ *   });
+ */
+export declare function bucket<T>(name: string, fn: () => T): T;
+//# sourceMappingURL=cost-context.d.ts.map

package/dist/cost-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-context.d.ts","sourceRoot":"","sources":["../src/cost-context.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,OAAO;IACtB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAKD,8DAA8D;AAC9D,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE9D;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAE/C;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAG3D;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEtD"}

package/dist/cost-context.js

@@ -0,0 +1,46 @@
+/**
+ * cost-context — the request-scoped tag every counted operation attributes
+ * itself to. Set it ONCE at a boundary (or wrap a path with `bucket()`); it
+ * rides Node's AsyncLocalStorage down through every async fan-out, so one
+ * handler that triggers 15 reads attributes all 15 to the same bucket — with
+ * zero per-call-site work.
+ *
+ * Generic by design: unlike a hardcoded product taxonomy, the only meaningful
+ * field a consumer sets is the free-form `label` (the bucket name). `feature`
+ * is an optional coarse grouping if you want one; nothing here is
+ * Crossdeck-specific.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+const DEFAULT_TAG = {};
+const store = new AsyncLocalStorage();
+/** Run `fn` with `tag` bound for its entire async subtree. */
+export function runWithCostTag(tag, fn) {
+    return store.run({ ...tag }, fn);
+}
+/** Bind a tag for the remainder of the current async context (no closure to wrap). */
+export function enterCostTag(tag) {
+    store.enterWith({ ...tag });
+}
+/** Refine the live tag in place (e.g. stamp a feature after the boundary). */
+export function refineCostTag(patch) {
+    const cur = store.getStore();
+    if (cur)
+        Object.assign(cur, patch);
+}
+/** The current tag, or a safe empty default outside any bound context. */
+export function currentCostTag() {
+    return store.getStore() ?? DEFAULT_TAG;
+}
+/**
+ * `bucket(name, fn)` — the headline verb, the `track()` of cost. Run `fn` with
+ * every operation inside it attributed to the bucket `name`; the attribution
+ * rides the async subtree automatically. The one verb most developers ever touch:
+ *
+ *   await bucket("nightly-export", async () => {
+ *     const rows = await db.collection("events").where(...).get(); // → "nightly-export"
+ *   });
+ */
+export function bucket(name, fn) {
+    return runWithCostTag({ ...currentCostTag(), label: name }, fn);
+}
+//# sourceMappingURL=cost-context.js.map

package/dist/cost-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-context.js","sourceRoot":"","sources":["../src/cost-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AASrD,MAAM,WAAW,GAAY,EAAE,CAAC;AAChC,MAAM,KAAK,GAAG,IAAI,iBAAiB,EAAW,CAAC;AAE/C,8DAA8D;AAC9D,MAAM,UAAU,cAAc,CAAI,GAAY,EAAE,EAAW;IACzD,OAAO,KAAK,CAAC,GAAG,CAAC,EAAE,GAAG,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC;AACnC,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,KAAK,CAAC,SAAS,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,aAAa,CAAC,KAAuB;IACnD,MAAM,GAAG,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;IAC7B,IAAI,GAAG;QAAE,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;AACrC,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,cAAc;IAC5B,OAAO,KAAK,CAAC,QAAQ,EAAE,IAAI,WAAW,CAAC;AACzC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,MAAM,CAAI,IAAY,EAAE,EAAW;IACjD,OAAO,cAAc,CAAC,EAAE,GAAG,cAAc,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;AAClE,CAAC"}

package/dist/cost-meter.d.ts

@@ -0,0 +1,28 @@
+import type { Sink } from "./sink.js";
+export type OpType = "read" | "write" | "delete";
+/** Optional read-site hint — the collection touched, derived at the trap from the
+ *  path. Lets an UNtagged read cascade to `col:<collection>` instead of vanishing. */
+export interface CostHint {
+    collection?: string;
+    projectId?: string;
+}
+export interface MeterConfig {
+    sink: Sink;
+    flushIntervalMs?: number;
+    onError?: (e: unknown) => void;
+}
+/** Point the meter at a sink. Called by `init()`; pass your own sink to self-host. */
+export declare function configureMeter(config: MeterConfig): void;
+/** Count `n` ops of `op` against the live tag. Never throws. */
+export declare function recordFirestore(op: OpType, n: number, hint?: CostHint): void;
+/** Firestore bills a minimum of one read even for an empty result, so 0 counts as 1. */
+export declare function recordReads(n: number, hint?: CostHint): void;
+export declare function recordWrites(n?: number): void;
+export declare function recordDeletes(n?: number): void;
+/**
+ * Coalesce the buffer into one report per UTC day and hand each to the Sink.
+ * Snapshots + clears up front so concurrent records land in the next window.
+ * Never throws; a sink failure drops that window (surfaced via `onError`).
+ */
+export declare function flush(): Promise<void>;
+//# sourceMappingURL=cost-meter.d.ts.map

package/dist/cost-meter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-meter.d.ts","sourceRoot":"","sources":["../src/cost-meter.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,IAAI,EAA2B,MAAM,WAAW,CAAC;AAE/D,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEjD;sFACsF;AACtF,MAAM,WAAW,QAAQ;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAmBD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,IAAI,CAAC;IACX,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CAChC;AAED,sFAAsF;AACtF,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAIxD;AAeD,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAkB5E;AAED,wFAAwF;AACxF,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAE5D;AACD,wBAAgB,YAAY,CAAC,CAAC,SAAI,GAAG,IAAI,CAExC;AACD,wBAAgB,aAAa,CAAC,CAAC,SAAI,GAAG,IAAI,CAEzC;AAOD;;;;GAIG;AACH,wBAAsB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CA2C3C"}

package/dist/cost-meter.js

@@ -0,0 +1,137 @@
+/**
+ * cost-meter — counts operations against the ambient tag and flushes them to the
+ * configured Sink cheaply.
+ *
+ * LOW-OVERHEAD CONTRACT (the thing that warns you about reads must not run them
+ * up): counts accumulate in an in-memory buffer and flush periodically — NEVER one
+ * network call per counted operation. A flush coalesces the whole window into one
+ * report per UTC day and hands it to the Sink. At steady state that is ~1 small
+ * request a minute, regardless of how many ops you served.
+ *
+ * BEST-EFFORT CONTRACT: metering must never throw into your code. Every recorder
+ * swallows its own errors; a failed flush drops that window's counts (surfaced via
+ * `onError` if you pass one) rather than disturbing the app.
+ */
+import { currentCostTag } from "./cost-context.js";
+// NUL separator — a bucket/collection name can contain almost anything except
+// this, so the key never collides with a name that has a "|" or ":" in it.
+const SEP = "\u001f"; // ASCII Unit Separator
+/** key = date <NUL> op <NUL> label → count */
+const labelBuffer = new Map();
+/** key = date <NUL> op <NUL> hour → count */
+const hourBuffer = new Map();
+let sink = null;
+let flushIntervalMs = 60_000;
+let onError = null;
+let timer = null;
+let flushing = false;
+/** Safety valve — flush early if a burst fills the buffer between intervals. */
+const MAX_BUFFER_KEYS = 5_000;
+/** Point the meter at a sink. Called by `init()`; pass your own sink to self-host. */
+export function configureMeter(config) {
+    sink = config.sink;
+    if (config.flushIntervalMs && config.flushIntervalMs > 0)
+        flushIntervalMs = config.flushIntervalMs;
+    onError = config.onError ?? null;
+}
+const utcDate = () => new Date().toISOString().slice(0, 10);
+const utcHour = () => new Date().toISOString().slice(11, 13);
+function ensureFlushLoop() {
+    if (timer)
+        return;
+    timer = setInterval(() => void flush(), flushIntervalMs);
+    // Don't keep the event loop alive just for metering.
+    timer.unref?.();
+    // Flush the last window on shutdown.
+    process.once?.("SIGTERM", () => void flush());
+    process.once?.("beforeExit", () => void flush());
+}
+/** Count `n` ops of `op` against the live tag. Never throws. */
+export function recordFirestore(op, n, hint) {
+    try {
+        if (!Number.isFinite(n) || n <= 0)
+            return;
+        const t = currentCostTag();
+        const date = utcDate();
+        // CASCADE — every op gets a label, by design (no blind spots): the bucket name
+        // wins; else the collection it actually touched (`col:posts`); else
+        // "uncategorized" as a loud last resort. A read is never invisible.
+        const label = t.label || (hint?.collection ? `col:${hint.collection}` : "uncategorized");
+        const lk = date + SEP + op + SEP + label;
+        labelBuffer.set(lk, (labelBuffer.get(lk) ?? 0) + n);
+        const hk = date + SEP + op + SEP + utcHour();
+        hourBuffer.set(hk, (hourBuffer.get(hk) ?? 0) + n);
+        ensureFlushLoop();
+        if (labelBuffer.size + hourBuffer.size > MAX_BUFFER_KEYS)
+            void flush();
+    }
+    catch {
+        /* metering is best-effort — never disturb the caller */
+    }
+}
+/** Firestore bills a minimum of one read even for an empty result, so 0 counts as 1. */
+export function recordReads(n, hint) {
+    recordFirestore("read", Math.max(n, 1), hint);
+}
+export function recordWrites(n = 1) {
+    recordFirestore("write", n);
+}
+export function recordDeletes(n = 1) {
+    recordFirestore("delete", n);
+}
+function add(target, key, op, n) {
+    const bag = (target[key] ??= {});
+    bag[op] = (bag[op] ?? 0) + n;
+}
+/**
+ * Coalesce the buffer into one report per UTC day and hand each to the Sink.
+ * Snapshots + clears up front so concurrent records land in the next window.
+ * Never throws; a sink failure drops that window (surfaced via `onError`).
+ */
+export async function flush() {
+    if (flushing)
+        return;
+    // Not configured (init not called) — drop, don't grow unbounded.
+    if (!sink) {
+        labelBuffer.clear();
+        hourBuffer.clear();
+        return;
+    }
+    if (labelBuffer.size === 0 && hourBuffer.size === 0)
+        return;
+    flushing = true;
+    const labels = new Map(labelBuffer);
+    const hours = new Map(hourBuffer);
+    labelBuffer.clear();
+    hourBuffer.clear();
+    try {
+        const byDate = new Map();
+        const reportFor = (date) => {
+            let r = byDate.get(date);
+            if (!r) {
+                r = { date, byLabel: {}, byHour: {} };
+                byDate.set(date, r);
+            }
+            return r;
+        };
+        for (const [k, n] of labels) {
+            const [date, op, label] = k.split(SEP);
+            add(reportFor(date).byLabel, label, op, n);
+        }
+        for (const [k, n] of hours) {
+            const [date, op, hour] = k.split(SEP);
+            add(reportFor(date).byHour, hour, op, n);
+        }
+        for (const report of byDate.values()) {
+            await sink.flush(report);
+        }
+    }
+    catch (e) {
+        // Drop this window rather than risk a partial/double report on retry.
+        onError?.(e);
+    }
+    finally {
+        flushing = false;
+    }
+}
+//# sourceMappingURL=cost-meter.js.map

package/dist/cost-meter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-meter.js","sourceRoot":"","sources":["../src/cost-meter.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @cross-deck/buckets — know exactly what every database read costs you, and who
+ * caused it. A tiny, never-throws collector for Firestore.
+ *
+ * The whole footprint a consumer sees:
+ *   1. init({ apiKey, firestore })  — configure once, install the trap once
+ *   2. bucket(name, fn)             — name the read paths that matter
+ *   3. (the dashboard shows the rest — and names the ones you haven't yet)
+ */
+import { type MeterConfig } from "./cost-meter.js";
+import { type Sink } from "./sink.js";
+import { type FirestoreClasses } from "./adapters/firestore.js";
+export interface InitOptions {
+    /** The project's `cd_sk_` SECRET key. Server-to-server only — never a browser key. */
+    apiKey: string;
+    /**
+     * Pass the namespace from `firebase-admin/firestore` to auto-install the read
+     * trap (recommended — this is what makes every read count with no per-call work).
+     * Omit it if you'd rather call `installFirestoreMeter()` yourself, or you only
+     * use the manual `recordReads()` recorders.
+     */
+    firestore?: FirestoreClasses;
+    /** Override the report endpoint (defaults to Crossdeck's ingest). */
+    endpoint?: string;
+    /** How often to flush coalesced counts (ms). Default 60_000. */
+    flushIntervalMs?: number;
+    /** Bring your own sink (self-host the rollups). Defaults to reporting up to Crossdeck. */
+    sink?: Sink;
+    /** Notified when a flush fails, so a dropped window is never silent. Best-effort. */
+    onError?: MeterConfig["onError"];
+}
+/**
+ * Configure Buckets once, at process start. Points the meter at a sink (Crossdeck's
+ * ingest by default) and — if you pass `firestore` — installs the universal read
+ * trap so every read counts automatically.
+ */
+export declare function init(options: InitOptions): void;
+/** Alias — reads well next to `bucket()` at a call site. */
+export { init as initBuckets };
+export { bucket, runWithCostTag, enterCostTag, refineCostTag, currentCostTag, type CostTag, } from "./cost-context.js";
+export { recordReads, recordWrites, recordDeletes, flush, type CostHint, type OpType, type MeterConfig, } from "./cost-meter.js";
+export { installFirestoreMeter, type FirestoreClasses } from "./adapters/firestore.js";
+export { ReportSink, type Sink, type BucketsReport, type OpCounts, type ReportSinkConfig } from "./sink.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAc,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAyB,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEvF,MAAM,WAAW,WAAW;IAC1B,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0FAA0F;IAC1F,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,qFAAqF;IACrF,OAAO,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAI/C;AAED,4DAA4D;AAC5D,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,CAAC;AAG/B,OAAO,EACL,MAAM,EACN,cAAc,EACd,YAAY,EACZ,aAAa,EACb,cAAc,EACd,KAAK,OAAO,GACb,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,WAAW,EACX,YAAY,EACZ,aAAa,EACb,KAAK,EACL,KAAK,QAAQ,EACb,KAAK,MAAM,EACX,KAAK,WAAW,GACjB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,qBAAqB,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGvF,OAAO,EAAE,UAAU,EAAE,KAAK,IAAI,EAAE,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,34 @@
+/**
+ * @cross-deck/buckets — know exactly what every database read costs you, and who
+ * caused it. A tiny, never-throws collector for Firestore.
+ *
+ * The whole footprint a consumer sees:
+ *   1. init({ apiKey, firestore })  — configure once, install the trap once
+ *   2. bucket(name, fn)             — name the read paths that matter
+ *   3. (the dashboard shows the rest — and names the ones you haven't yet)
+ */
+import { configureMeter } from "./cost-meter.js";
+import { ReportSink } from "./sink.js";
+import { installFirestoreMeter } from "./adapters/firestore.js";
+/**
+ * Configure Buckets once, at process start. Points the meter at a sink (Crossdeck's
+ * ingest by default) and — if you pass `firestore` — installs the universal read
+ * trap so every read counts automatically.
+ */
+export function init(options) {
+    const sink = options.sink ?? new ReportSink({ apiKey: options.apiKey, endpoint: options.endpoint });
+    configureMeter({ sink, flushIntervalMs: options.flushIntervalMs, onError: options.onError });
+    if (options.firestore)
+        installFirestoreMeter(options.firestore);
+}
+/** Alias — reads well next to `bucket()` at a call site. */
+export { init as initBuckets };
+// The headline verb + the lower-level tag controls it is sugar over.
+export { bucket, runWithCostTag, enterCostTag, refineCostTag, currentCostTag, } from "./cost-context.js";
+// Manual recorders (for non-Firestore ops, or when you don't install the trap).
+export { recordReads, recordWrites, recordDeletes, flush, } from "./cost-meter.js";
+// The trap (the only datastore adapter today) + its class shape.
+export { installFirestoreMeter } from "./adapters/firestore.js";
+// The sink seam — for self-hosting rollups instead of reporting to Crossdeck.
+export { ReportSink } from "./sink.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,cAAc,EAAoB,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,UAAU,EAAa,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAyB,MAAM,yBAAyB,CAAC;AAsBvF;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAAC,OAAoB;IACvC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,UAAU,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACpG,cAAc,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC,eAAe,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC7F,IAAI,OAAO,CAAC,SAAS;QAAE,qBAAqB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClE,CAAC;AAED,4DAA4D;AAC5D,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,CAAC;AAE/B,qEAAqE;AACrE,OAAO,EACL,MAAM,EACN,cAAc,EACd,YAAY,EACZ,aAAa,EACb,cAAc,GAEf,MAAM,mBAAmB,CAAC;AAE3B,gFAAgF;AAChF,OAAO,EACL,WAAW,EACX,YAAY,EACZ,aAAa,EACb,KAAK,GAIN,MAAM,iBAAiB,CAAC;AAEzB,iEAAiE;AACjE,OAAO,EAAE,qBAAqB,EAAyB,MAAM,yBAAyB,CAAC;AAEvF,8EAA8E;AAC9E,OAAO,EAAE,UAAU,EAAuE,MAAM,WAAW,CAAC"}

package/dist/sink.d.ts

@@ -0,0 +1,56 @@
+/**
+ * sink — where the meter sends a coalesced rollup, and the wire shape it sends.
+ *
+ * Abstracting the sink is what makes Buckets storage-agnostic: the meter never
+ * knows where counts go. The DEFAULT sink (`ReportSink`) reports up to Crossdeck's
+ * ingest endpoint so the numbers surface on your Crossdeck dashboard. A team that
+ * wants to self-host can implement `Sink` against anything (Postgres, a file, your
+ * own API) without touching the meter.
+ */
+export interface OpCounts {
+    read?: number;
+    write?: number;
+    delete?: number;
+}
+/**
+ * One coalesced report — the wire contract (see docs/ROLLUP_SCHEMA.md). The meter
+ * produces one of these per UTC day in a flush window (usually exactly one).
+ */
+export interface BucketsReport {
+    /** UTC day "YYYY-MM-DD". */
+    date: string;
+    /** bucket name → counts. The heart of the report. */
+    byLabel: Record<string, OpCounts>;
+    /** UTC hour "HH" → counts, for the hourly "did my fix land this hour?" view. */
+    byHour?: Record<string, OpCounts>;
+}
+/**
+ * A destination for coalesced rollups. `flush` MAY throw on failure — the meter
+ * catches it, drops that one window, and never lets it reach your app.
+ */
+export interface Sink {
+    flush(report: BucketsReport): Promise<void>;
+}
+export interface ReportSinkConfig {
+    /** The project's `cd_sk_` secret key. Server-to-server only. */
+    apiKey: string;
+    /** Defaults to https://api.cross-deck.com/v1/buckets/report */
+    endpoint?: string;
+    /** Request timeout (ms); a slow Crossdeck must never stall your flush. */
+    timeoutMs?: number;
+}
+/**
+ * The default sink: POST one coalesced rollup to Crossdeck's ingest endpoint.
+ * The ingest folds it into the day's maintained doc with `increment`, so many
+ * reports a minute coalesce safely. This path does ZERO database reads — it sends
+ * a summary, it does not read. Throws on a non-202 so the meter can log/drop the
+ * window; the meter guarantees it never reaches your app.
+ */
+export declare class ReportSink implements Sink {
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    constructor(config: ReportSinkConfig);
+    flush(report: BucketsReport): Promise<void>;
+}
+//# sourceMappingURL=sink.d.ts.map

package/dist/sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sink.d.ts","sourceRoot":"","sources":["../src/sink.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAClC,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,IAAI;IACnB,KAAK,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID;;;;;;GAMG;AACH,qBAAa,UAAW,YAAW,IAAI;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,MAAM,EAAE,gBAAgB;IAM9B,KAAK,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;CAclD"}

package/dist/sink.js

@@ -0,0 +1,42 @@
+/**
+ * sink — where the meter sends a coalesced rollup, and the wire shape it sends.
+ *
+ * Abstracting the sink is what makes Buckets storage-agnostic: the meter never
+ * knows where counts go. The DEFAULT sink (`ReportSink`) reports up to Crossdeck's
+ * ingest endpoint so the numbers surface on your Crossdeck dashboard. A team that
+ * wants to self-host can implement `Sink` against anything (Postgres, a file, your
+ * own API) without touching the meter.
+ */
+const DEFAULT_ENDPOINT = "https://api.cross-deck.com/v1/buckets/report";
+/**
+ * The default sink: POST one coalesced rollup to Crossdeck's ingest endpoint.
+ * The ingest folds it into the day's maintained doc with `increment`, so many
+ * reports a minute coalesce safely. This path does ZERO database reads — it sends
+ * a summary, it does not read. Throws on a non-202 so the meter can log/drop the
+ * window; the meter guarantees it never reaches your app.
+ */
+export class ReportSink {
+    endpoint;
+    apiKey;
+    timeoutMs;
+    constructor(config) {
+        this.endpoint = config.endpoint ?? DEFAULT_ENDPOINT;
+        this.apiKey = config.apiKey;
+        this.timeoutMs = config.timeoutMs ?? 5000;
+    }
+    async flush(report) {
+        const res = await fetch(this.endpoint, {
+            method: "POST",
+            signal: AbortSignal.timeout(this.timeoutMs),
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify(report),
+        });
+        if (res.status !== 202) {
+            throw new Error(`Buckets report rejected: HTTP ${res.status}`);
+        }
+    }
+}
+//# sourceMappingURL=sink.js.map

package/dist/sink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sink.js","sourceRoot":"","sources":["../src/sink.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAsCH,MAAM,gBAAgB,GAAG,8CAA8C,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,OAAO,UAAU;IACJ,QAAQ,CAAS;IACjB,MAAM,CAAS;IACf,SAAS,CAAS;IAEnC,YAAY,MAAwB;QAClC,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,gBAAgB,CAAC;QACpD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,IAAI,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,MAAqB;QAC/B,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE;YACrC,MAAM,EAAE,MAAM;YACd,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC;YAC3C,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;aACvC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;SAC7B,CAAC,CAAC;QACH,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,iCAAiC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;CACF"}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@cross-deck/buckets",
+  "version": "0.1.0",
+  "description": "Know exactly what every database read costs you — and who caused it. A tiny, never-throws read-cost collector for Firestore.",
+  "license": "MIT",
+  "author": "Crossdeck",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./adapters/firestore": {
+      "types": "./dist/adapters/firestore.d.ts",
+      "import": "./dist/adapters/firestore.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "firestore",
+    "firebase",
+    "cost",
+    "observability",
+    "database",
+    "reads",
+    "attribution",
+    "finops",
+    "crossdeck"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Crossdeckhq/buckets-oss.git"
+  },
+  "homepage": "https://github.com/Crossdeckhq/buckets-oss#readme",
+  "bugs": {
+    "url": "https://github.com/Crossdeckhq/buckets-oss/issues"
+  },
+  "peerDependencies": {
+    "firebase-admin": ">=11"
+  },
+  "peerDependenciesMeta": {
+    "firebase-admin": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "firebase-admin": "^12.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}