@drm3/sdk 0.1.2

package/dist/meter/core.js

@@ -0,0 +1,49 @@
+/** available = balance - held, floored at 0 (a hold never makes it negative). */
+export function available(balance, held) {
+    const a = balance - held;
+    return a > 0n ? a : 0n;
+}
+/** Can a hold of `amount` be placed against this scope? The Visa pre-auth check. */
+export function canHold(balance, held, amount) {
+    return amount >= 0n && balance - held >= amount;
+}
+/**
+ * The Visa guarantee: you are never charged more than you reserved.
+ * charged = min(quotedActual, held). Always.
+ */
+export function captureAmount(held, quotedActual) {
+    const q = quotedActual < 0n ? 0n : quotedActual;
+    return q < held ? q : held;
+}
+/** Whether a reservation is in a state that can still be captured/voided. */
+export function isOpen(state) {
+    return state === "held";
+}
+/**
+ * Decide the result of capturing a held reservation. Returns the next
+ * reservation shape + how much to debit balance + how much hold to release.
+ * Pure: caller persists. Capturing a non-open reservation is a no-op echo
+ * (idempotent at the state-machine level; storage enforces idem by key too).
+ */
+export function applyCapture(r, quotedActual, idemKey) {
+    if (!isOpen(r.state)) {
+        return { reservation: r, debit: 0n, releaseHold: 0n };
+    }
+    const charged = captureAmount(r.held, quotedActual);
+    return {
+        reservation: { ...r, state: "captured", charged, captureIdemKey: idemKey ?? r.captureIdemKey },
+        debit: charged, // balance -= charged
+        releaseHold: r.held, // the whole hold leaves `held`; `charged` of it became spend
+    };
+}
+/** Voiding/expiring an open reservation releases the entire hold, charges nothing. */
+export function applyRelease(r, state) {
+    if (!isOpen(r.state))
+        return { reservation: r, releaseHold: 0n };
+    return { reservation: { ...r, state, charged: 0n }, releaseHold: r.held };
+}
+/** Has a reservation passed its TTL and is still holding credits? */
+export function isReclaimable(r, now) {
+    return r.state === "held" && r.expiresAt <= now;
+}
+//# sourceMappingURL=core.js.map

package/dist/meter/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../src/meter/core.ts"],"names":[],"mappings":"AAQA,iFAAiF;AACjF,MAAM,UAAU,SAAS,CAAC,OAAgB,EAAE,IAAa;IACvD,MAAM,CAAC,GAAG,OAAO,GAAG,IAAI,CAAC;IACzB,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACzB,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,OAAO,CAAC,OAAgB,EAAE,IAAa,EAAE,MAAe;IACtE,OAAO,MAAM,IAAI,EAAE,IAAI,OAAO,GAAG,IAAI,IAAI,MAAM,CAAC;AAClD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,IAAa,EAAE,YAAqB;IAChE,MAAM,CAAC,GAAG,YAAY,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC;IAChD,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7B,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,MAAM,CAAC,KAAuB;IAC5C,OAAO,KAAK,KAAK,MAAM,CAAC;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,CAAc,EAAE,YAAqB,EAAE,OAAgB;IAClF,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,EAAE,WAAW,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;IACxD,CAAC;IACD,MAAM,OAAO,GAAG,aAAa,CAAC,CAAC,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IACpD,OAAO;QACL,WAAW,EAAE,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,IAAI,CAAC,CAAC,cAAc,EAAE;QAC9F,KAAK,EAAE,OAAO,EAAE,qBAAqB;QACrC,WAAW,EAAE,CAAC,CAAC,IAAI,EAAE,6DAA6D;KACnF,CAAC;AACJ,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,YAAY,CAAC,CAAc,EAAE,KAA2B;IACtE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;IACjE,OAAO,EAAE,WAAW,EAAE,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAC5E,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,aAAa,CAAC,CAAc,EAAE,GAAW;IACvD,OAAO,CAAC,CAAC,KAAK,KAAK,MAAM,IAAI,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC;AAClD,CAAC"}

package/dist/meter/gate-client.d.ts

@@ -0,0 +1,94 @@
+/**
+ * gate-client - the bus→authority client over HTTP.
+ *
+ * The bus has no ledger; it calls the queue's internal credit endpoints. bigint
+ * amounts cross the wire as strings (JSON has no bigint). The endpoints are
+ * internal-keyed (X-Internal-Key). The queue implements them over MeterStore.
+ */
+import type { Demand } from "./resolve.js";
+/** `POST /api/internal/meter/preflight` - resolve a consumer's inf_ key to its
+ *  tenant + credits + ban state in one call, so a direct-call surface (the bus)
+ *  can run `decide()` before serving. */
+export interface PreflightResult {
+    /** The resolved tenant, or null = invalid/revoked key (→ unauthenticated). */
+    readonly tenant: string | null;
+    /** Spendable µcredits, or null = ledger error (fail-open signal). */
+    readonly available: bigint | null;
+    readonly suspended: boolean;
+}
+/** `GET /api/internal/meter/available?tenant=&scope=` */
+export interface AvailableResult {
+    /** Spendable µcredits, or null = the authority hit a ledger error. null is a
+     *  fail-open SIGNAL, not zero: the caller decides whether to serve through it. */
+    readonly available: bigint | null;
+    readonly suspended: boolean;
+}
+/** `POST /api/internal/meter/charge` - the token-based inference charge the queue
+ *  prices through its own matrix (the bus knows tokens, the queue owns the rate).
+ *  This is the shape the queue implements today and the bus's hot path. */
+export interface InferenceChargeWire {
+    readonly tenant: string;
+    readonly scope: string;
+    readonly idemKey?: string;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly tokensIn: number;
+    readonly tokensOut: number;
+}
+/** `POST /api/internal/meter/charge` (Demand form) - a pre-resolved feature/credit
+ *  demand priced by the CALLER. For app-level feature metering; the queue's
+ *  inference endpoint uses the token form above. */
+export interface ChargeRequestWire {
+    readonly tenant: string;
+    readonly scope: string;
+    readonly idemKey?: string;
+    readonly demand: {
+        readonly feature: string;
+        readonly units?: string;
+        readonly creditPricePerUnit: string;
+    } | {
+        readonly ucredits: string;
+    };
+}
+export interface ChargeResult {
+    readonly charged: bigint;
+    readonly overdraft: bigint;
+    readonly replay: boolean;
+    readonly byBucket: Readonly<Record<string, bigint>>;
+}
+export interface MeterClientOptions {
+    /** Queue base URL, e.g. https://queue.drm3.network */
+    readonly baseUrl: string;
+    /** Shared internal key (X-Internal-Key), same secret the queue checks. */
+    readonly internalKey: string;
+    /** Injectable fetch (Bun/Workers/Node global by default). */
+    readonly fetch?: typeof fetch;
+}
+/** Thin typed client the bus (and any non-CF surface) uses to gate + meter against
+ *  the queue's one ledger. Stateless; one per surface. */
+export declare class MeterClient {
+    private readonly base;
+    private readonly key;
+    private readonly f;
+    constructor(opts: MeterClientOptions);
+    /** Read spendable credits + ban state for the credits plane of `decide()`.
+     *  `available` is null when the authority hit a ledger error (the bus fails open). */
+    available(tenant: string, scope?: string): Promise<AvailableResult>;
+    /** Resolve a direct caller's inf_ key → tenant + credits + ban, for `decide()`.
+     *  The bus's first call on a consumer request. tenant=null ⇒ unauthenticated. */
+    preflight(key: string): Promise<PreflightResult>;
+    private postCharge;
+    /** Meter one direct inference request: the QUEUE prices provider/model/tokens
+     *  through its matrix and debits the one ledger. This is the bus's hot path -
+     *  call it AFTER the response with the real token counts. Idempotent on idemKey. */
+    chargeInference(tenant: string, usage: {
+        provider?: string;
+        model?: string;
+        tokensIn: number;
+        tokensOut: number;
+    }, idemKey?: string, scope?: string): Promise<ChargeResult>;
+    /** Debit a pre-priced demand (caller-priced feature/credit metering). For app
+     *  surfaces; the queue's inference endpoint uses chargeInference. Idempotent. */
+    charge(tenant: string, demand: Demand, idemKey?: string, scope?: string): Promise<ChargeResult>;
+}
+//# sourceMappingURL=gate-client.d.ts.map

package/dist/meter/gate-client.d.ts.map

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

package/dist/meter/gate-client.js

@@ -0,0 +1,77 @@
+const wireDemand = (d) => "feature" in d
+    ? { feature: d.feature, units: (d.units ?? 1n).toString(), creditPricePerUnit: d.creditPricePerUnit.toString() }
+    : { ucredits: d.ucredits.toString() };
+/** Thin typed client the bus (and any non-CF surface) uses to gate + meter against
+ *  the queue's one ledger. Stateless; one per surface. */
+export class MeterClient {
+    base;
+    key;
+    f;
+    constructor(opts) {
+        this.base = opts.baseUrl.replace(/\/+$/, "");
+        this.key = opts.internalKey;
+        const f = opts.fetch ?? globalThis.fetch;
+        if (!f)
+            throw new Error("MeterClient: no fetch available; pass opts.fetch");
+        this.f = f;
+    }
+    /** Read spendable credits + ban state for the credits plane of `decide()`.
+     *  `available` is null when the authority hit a ledger error (the bus fails open). */
+    async available(tenant, scope = "") {
+        const u = `${this.base}/api/internal/meter/available?tenant=${encodeURIComponent(tenant)}&scope=${encodeURIComponent(scope)}`;
+        const res = await this.f(u, { headers: { "X-Internal-Key": this.key } });
+        if (!res.ok)
+            throw new Error(`meter available ${res.status}`);
+        const j = (await res.json());
+        return { available: j.available == null ? null : BigInt(j.available), suspended: Boolean(j.suspended) };
+    }
+    /** Resolve a direct caller's inf_ key → tenant + credits + ban, for `decide()`.
+     *  The bus's first call on a consumer request. tenant=null ⇒ unauthenticated. */
+    async preflight(key) {
+        const res = await this.f(`${this.base}/api/internal/meter/preflight`, {
+            method: "POST",
+            headers: { "X-Internal-Key": this.key, "content-type": "application/json" },
+            body: JSON.stringify({ key }),
+        });
+        if (!res.ok)
+            throw new Error(`meter preflight ${res.status}`);
+        const j = (await res.json());
+        return { tenant: j.tenant ?? null, available: j.available == null ? null : BigInt(j.available), suspended: Boolean(j.suspended) };
+    }
+    async postCharge(body) {
+        const res = await this.f(`${this.base}/api/internal/meter/charge`, {
+            method: "POST",
+            headers: { "X-Internal-Key": this.key, "content-type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            throw new Error(`meter charge ${res.status}`);
+        const j = (await res.json());
+        const byBucket = {};
+        for (const [k, v] of Object.entries(j.byBucket ?? {}))
+            byBucket[k] = BigInt(v);
+        return { charged: BigInt(j.charged ?? "0"), overdraft: BigInt(j.overdraft ?? "0"), replay: Boolean(j.replay), byBucket };
+    }
+    /** Meter one direct inference request: the QUEUE prices provider/model/tokens
+     *  through its matrix and debits the one ledger. This is the bus's hot path -
+     *  call it AFTER the response with the real token counts. Idempotent on idemKey. */
+    async chargeInference(tenant, usage, idemKey, scope = "") {
+        const body = {
+            tenant,
+            scope,
+            idemKey,
+            provider: usage.provider,
+            model: usage.model,
+            tokensIn: Math.max(0, Math.trunc(usage.tokensIn || 0)),
+            tokensOut: Math.max(0, Math.trunc(usage.tokensOut || 0)),
+        };
+        return this.postCharge(body);
+    }
+    /** Debit a pre-priced demand (caller-priced feature/credit metering). For app
+     *  surfaces; the queue's inference endpoint uses chargeInference. Idempotent. */
+    async charge(tenant, demand, idemKey, scope = "") {
+        const body = { tenant, scope, idemKey, demand: wireDemand(demand) };
+        return this.postCharge(body);
+    }
+}
+//# sourceMappingURL=gate-client.js.map

package/dist/meter/gate-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate-client.js","sourceRoot":"","sources":["../../src/meter/gate-client.ts"],"names":[],"mappings":"AAmEA,MAAM,UAAU,GAAG,CAAC,CAAS,EAA+B,EAAE,CAC5D,SAAS,IAAI,CAAC;IACZ,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE,kBAAkB,EAAE,CAAC,CAAC,kBAAkB,CAAC,QAAQ,EAAE,EAAE;IAChH,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC;AAE1C;0DAC0D;AAC1D,MAAM,OAAO,WAAW;IACL,IAAI,CAAS;IACb,GAAG,CAAS;IACZ,CAAC,CAAe;IAEjC,YAAY,IAAwB;QAClC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC7C,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC;QAC5B,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,IAAK,UAAU,CAAC,KAAkC,CAAC;QACvE,IAAI,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;QAC5E,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IACb,CAAC;IAED;0FACsF;IACtF,KAAK,CAAC,SAAS,CAAC,MAAc,EAAE,KAAK,GAAG,EAAE;QACxC,MAAM,CAAC,GAAG,GAAG,IAAI,CAAC,IAAI,wCAAwC,kBAAkB,CAAC,MAAM,CAAC,UAAU,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9H,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,EAAE,gBAAgB,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACzE,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QAC9D,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAsD,CAAC;QAClF,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC;IAC1G,CAAC;IAED;qFACiF;IACjF,KAAK,CAAC,SAAS,CAAC,GAAW;QACzB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,+BAA+B,EAAE;YACpE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,gBAAgB,EAAE,IAAI,CAAC,GAAG,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC3E,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,CAAC;SAC9B,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QAC9D,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA6E,CAAC;QACzG,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC;IACpI,CAAC;IAEO,KAAK,CAAC,UAAU,CAAC,IAAY;QACnC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,4BAA4B,EAAE;YACjE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,gBAAgB,EAAE,IAAI,CAAC,GAAG,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC3E,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SAC3B,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,gBAAgB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QAC3D,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAiG,CAAC;QAC7H,MAAM,QAAQ,GAA2B,EAAE,CAAC;QAC5C,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC;YAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QAC/E,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,IAAI,GAAG,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;IAC3H,CAAC;IAED;;wFAEoF;IACpF,KAAK,CAAC,eAAe,CACnB,MAAc,EACd,KAAiF,EACjF,OAAgB,EAChB,KAAK,GAAG,EAAE;QAEV,MAAM,IAAI,GAAwB;YAChC,MAAM;YACN,KAAK;YACL,OAAO;YACP,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC;YACtD,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC;SACzD,CAAC;QACF,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED;qFACiF;IACjF,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,MAAc,EAAE,OAAgB,EAAE,KAAK,GAAG,EAAE;QACvE,MAAM,IAAI,GAAsB,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACvF,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;CACF"}

package/dist/meter/gate-decide.d.ts

@@ -0,0 +1,61 @@
+/**
+ * gate-decide - the shared admission decision as a pure function.
+ *
+ * DRM3 has TWO metered front doors onto ONE ledger: the async queue and the
+ * synchronous bus. A consumer (human or service) may call either directly. Both
+ * must answer the same two questions before serving, in the same order:
+ *
+ *   1. MAY you?   identity + entitlement  → the access plane
+ *   2. CAN you?   credits available       → the credits plane
+ *
+ * `decide()` is that answer as a pure function over already-resolved facts, so the
+ * queue and the bus return identical typed denials (the four reason codes). Each
+ * surface assembles the GateInput from what it knows: authentication + app claims
+ * + unlimited come from the SSO token / tenant record; `available` comes from the
+ * ledger (the queue reads it locally; the bus fetches it via MeterClient).
+ *
+ * The double-charge trap. The queue drains TO the bus using the service key, so a
+ * request can reach the bus already metered. A metered surface therefore classes
+ * its caller: a CONSUMER is gated + metered; an UPSTREAM (the queue, an already-
+ * metered hop) passes straight through - provenance only, no second charge. Use
+ * `callerClass()` with the surface's own trusted-key set.
+ */
+export type DenyReason = "unauthenticated" | "not_authorized_app" | "no_credits" | "suspended";
+/** Already-resolved facts about one request. Each surface fills these in. */
+export interface GateInput {
+    /** A valid identity was presented (SSO token / tenant key). */
+    readonly authenticated: boolean;
+    /** Banned (revocation feed). The one punitive state - checked before entitlement. */
+    readonly suspended: boolean;
+    /** Holds the product/app claim for what's being called. */
+    readonly entitled: boolean;
+    /** An unlimited gate for this call → serve and LOG the cost, never debit. */
+    readonly unlimited: boolean;
+    /** Spendable µcredits now (allowances + purse). Ignored when unlimited. */
+    readonly available: bigint;
+}
+export type GateDecision = 
+/** Serve. `meter` is false for an unlimited grant (log the cost, don't debit). */
+{
+    readonly allow: true;
+    readonly meter: boolean;
+}
+/** Refuse, with the typed reason the surface renders. */
+ | {
+    readonly allow: false;
+    readonly reason: DenyReason;
+};
+/**
+ * The shared admission decision. Order matters: a banned account hears "suspended"
+ * even where it lacks a claim; an entitled account with no credits hears "no_credits",
+ * not "not authorized". Identity → ban → access → unlimited → credits.
+ */
+export declare function decide(g: GateInput): GateDecision;
+export type CallerClass = "consumer" | "upstream";
+/**
+ * Classify a caller of a metered surface. An UPSTREAM presented a key in the
+ * surface's trusted set (e.g. the bus trusting the queue's BUS_API_KEY) → it has
+ * already metered, so pass through. Anything else is a CONSUMER to gate + meter.
+ */
+export declare function callerClass(presentedKey: string | null | undefined, upstreamKeys: Iterable<string>): CallerClass;
+//# sourceMappingURL=gate-decide.d.ts.map

package/dist/meter/gate-decide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate-decide.d.ts","sourceRoot":"","sources":["../../src/meter/gate-decide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,MAAM,UAAU,GAAG,iBAAiB,GAAG,oBAAoB,GAAG,YAAY,GAAG,WAAW,CAAC;AAE/F,6EAA6E;AAC7E,MAAM,WAAW,SAAS;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,qFAAqF;IACrF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,YAAY;AACtB,kFAAkF;AAChF;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE;AACnD,yDAAyD;GACvD;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC;AAE3D;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,SAAS,GAAG,YAAY,CAOjD;AAED,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,UAAU,CAAC;AAElD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,WAAW,CAIhH"}

package/dist/meter/gate-decide.js

@@ -0,0 +1,54 @@
+/**
+ * gate-decide - the shared admission decision as a pure function.
+ *
+ * DRM3 has TWO metered front doors onto ONE ledger: the async queue and the
+ * synchronous bus. A consumer (human or service) may call either directly. Both
+ * must answer the same two questions before serving, in the same order:
+ *
+ *   1. MAY you?   identity + entitlement  → the access plane
+ *   2. CAN you?   credits available       → the credits plane
+ *
+ * `decide()` is that answer as a pure function over already-resolved facts, so the
+ * queue and the bus return identical typed denials (the four reason codes). Each
+ * surface assembles the GateInput from what it knows: authentication + app claims
+ * + unlimited come from the SSO token / tenant record; `available` comes from the
+ * ledger (the queue reads it locally; the bus fetches it via MeterClient).
+ *
+ * The double-charge trap. The queue drains TO the bus using the service key, so a
+ * request can reach the bus already metered. A metered surface therefore classes
+ * its caller: a CONSUMER is gated + metered; an UPSTREAM (the queue, an already-
+ * metered hop) passes straight through - provenance only, no second charge. Use
+ * `callerClass()` with the surface's own trusted-key set.
+ */
+/**
+ * The shared admission decision. Order matters: a banned account hears "suspended"
+ * even where it lacks a claim; an entitled account with no credits hears "no_credits",
+ * not "not authorized". Identity → ban → access → unlimited → credits.
+ */
+export function decide(g) {
+    if (!g.authenticated)
+        return { allow: false, reason: "unauthenticated" };
+    if (g.suspended)
+        return { allow: false, reason: "suspended" };
+    if (!g.entitled)
+        return { allow: false, reason: "not_authorized_app" };
+    if (g.unlimited)
+        return { allow: true, meter: false }; // all-you-can-eat: serve, log only
+    if (g.available <= 0n)
+        return { allow: false, reason: "no_credits" };
+    return { allow: true, meter: true };
+}
+/**
+ * Classify a caller of a metered surface. An UPSTREAM presented a key in the
+ * surface's trusted set (e.g. the bus trusting the queue's BUS_API_KEY) → it has
+ * already metered, so pass through. Anything else is a CONSUMER to gate + meter.
+ */
+export function callerClass(presentedKey, upstreamKeys) {
+    if (!presentedKey)
+        return "consumer";
+    for (const k of upstreamKeys)
+        if (k && k === presentedKey)
+            return "upstream";
+    return "consumer";
+}
+//# sourceMappingURL=gate-decide.js.map

package/dist/meter/gate-decide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate-decide.js","sourceRoot":"","sources":["../../src/meter/gate-decide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAwBH;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,CAAY;IACjC,IAAI,CAAC,CAAC,CAAC,aAAa;QAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IACzE,IAAI,CAAC,CAAC,SAAS;QAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAC9D,IAAI,CAAC,CAAC,CAAC,QAAQ;QAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAC;IACvE,IAAI,CAAC,CAAC,SAAS;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,mCAAmC;IAC1F,IAAI,CAAC,CAAC,SAAS,IAAI,EAAE;QAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC;IACrE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACtC,CAAC;AAID;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,YAAuC,EAAE,YAA8B;IACjG,IAAI,CAAC,YAAY;QAAE,OAAO,UAAU,CAAC;IACrC,KAAK,MAAM,CAAC,IAAI,YAAY;QAAE,IAAI,CAAC,IAAI,CAAC,KAAK,YAAY;YAAE,OAAO,UAAU,CAAC;IAC7E,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/meter/gate.d.ts

@@ -0,0 +1,10 @@
+/**
+ * gate - the shared admission decision + the bus→authority client.
+ *
+ * Barrel over two concerns:
+ *   - gate-decide.ts: the pure `decide()` / `callerClass()` admission logic.
+ *   - gate-client.ts: the `MeterClient` HTTP client onto the queue's ledger.
+ */
+export { decide, callerClass, type DenyReason, type GateInput, type GateDecision, type CallerClass } from "./gate-decide.js";
+export { MeterClient, type PreflightResult, type AvailableResult, type InferenceChargeWire, type ChargeRequestWire, type ChargeResult, type MeterClientOptions, } from "./gate-client.js";
+//# sourceMappingURL=gate.d.ts.map

package/dist/meter/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/meter/gate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC7H,OAAO,EACL,WAAW,EACX,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,kBAAkB,GACxB,MAAM,kBAAkB,CAAC"}

package/dist/meter/gate.js

@@ -0,0 +1,10 @@
+/**
+ * gate - the shared admission decision + the bus→authority client.
+ *
+ * Barrel over two concerns:
+ *   - gate-decide.ts: the pure `decide()` / `callerClass()` admission logic.
+ *   - gate-client.ts: the `MeterClient` HTTP client onto the queue's ledger.
+ */
+export { decide, callerClass } from "./gate-decide.js";
+export { MeterClient, } from "./gate-client.js";
+//# sourceMappingURL=gate.js.map

package/dist/meter/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../src/meter/gate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,MAAM,EAAE,WAAW,EAAwE,MAAM,kBAAkB,CAAC;AAC7H,OAAO,EACL,WAAW,GAOZ,MAAM,kBAAkB,CAAC"}

package/dist/meter/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @drm3/sdk/meter - a non-custodial usage-metering ledger.
+ * authorize → capture → void → settle. Pure core, pluggable storage + settlement,
+ * no overdraft by construction. An external ledger only appears behind SettlementSink.
+ *
+ * Wallet is the multi-bucket layer on top: allowances (daily/weekly/monthly,
+ * refill-to-cap, burned first) over the existing ledger as the overdraftable
+ * purse (burned last). Purely additive - single-balance consumers are unaffected.
+ */
+export * from "./types.js";
+export * from "./core.js";
+export { cascade, type CascadeNode, type CascadeDraw, type CascadeResult } from "./cascade.js";
+export { resolveCharge, creditCost, type MeterState, type Demand, type MeterDraw, type ResolveResult, } from "./resolve.js";
+export { MeterStore, CREDITS_METER, type MeterBucketDef, type MeterStoreOptions } from "./meters.js";
+export { PlanStore, type PlanDef, type PlanStoreOptions } from "./plans.js";
+export { decide, callerClass, MeterClient, type DenyReason, type GateInput, type GateDecision, type CallerClass, type AvailableResult, type PreflightResult, type ChargeRequestWire, type InferenceChargeWire, type ChargeResult as RemoteChargeResult, type MeterClientOptions, } from "./gate.js";
+export { PriceBook, type Rate } from "./pricebook.js";
+export { CREDIT, CREDIT_DECIMALS, formatCredits, parseCredits } from "./units.js";
+export { type StorageAdapter, InMemoryAdapter } from "./adapter.js";
+export { SqlStorageAdapter } from "./sql/sql-adapter.js";
+export { ddl } from "./sql/schema.js";
+export { type SqlDriver, type Dialect, toBig, toPgPlaceholders } from "./sql/driver.js";
+export { type D1Like, d1Driver, d1Adapter } from "./sql/d1.js";
+export { type PgLike, pgDriver, pgAdapter } from "./sql/postgres.js";
+export { type SettlementSink, type SettlementBatch, NullSink } from "./sink.js";
+export { CreditsClient, type ClientOptions, type AuthorizeInput, type CaptureInput } from "./client.js";
+export { Wallet, type Cadence, type BucketDef, type BucketBalance, type WalletBalance, type ChargeResult, type WalletOptions, } from "./wallet.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/meter/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/meter/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAC/F,OAAO,EACL,aAAa,EACb,UAAU,EACV,KAAK,UAAU,EACf,KAAK,MAAM,EACX,KAAK,SAAS,EACd,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrG,OAAO,EAAE,SAAS,EAAE,KAAK,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,EACL,MAAM,EACN,WAAW,EACX,WAAW,EACX,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,YAAY,IAAI,kBAAkB,EACvC,KAAK,kBAAkB,GACxB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,SAAS,EAAE,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAClF,OAAO,EAAE,KAAK,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AACtC,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxF,OAAO,EAAE,KAAK,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,KAAK,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AACxG,OAAO,EACL,MAAM,EACN,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC"}

package/dist/meter/index.js

@@ -0,0 +1,28 @@
+/**
+ * @drm3/sdk/meter - a non-custodial usage-metering ledger.
+ * authorize → capture → void → settle. Pure core, pluggable storage + settlement,
+ * no overdraft by construction. An external ledger only appears behind SettlementSink.
+ *
+ * Wallet is the multi-bucket layer on top: allowances (daily/weekly/monthly,
+ * refill-to-cap, burned first) over the existing ledger as the overdraftable
+ * purse (burned last). Purely additive - single-balance consumers are unaffected.
+ */
+export * from "./types.js";
+export * from "./core.js";
+export { cascade } from "./cascade.js";
+export { resolveCharge, creditCost, } from "./resolve.js";
+export { MeterStore, CREDITS_METER } from "./meters.js";
+export { PlanStore } from "./plans.js";
+export { decide, callerClass, MeterClient, } from "./gate.js";
+export { PriceBook } from "./pricebook.js";
+export { CREDIT, CREDIT_DECIMALS, formatCredits, parseCredits } from "./units.js";
+export { InMemoryAdapter } from "./adapter.js";
+export { SqlStorageAdapter } from "./sql/sql-adapter.js";
+export { ddl } from "./sql/schema.js";
+export { toBig, toPgPlaceholders } from "./sql/driver.js";
+export { d1Driver, d1Adapter } from "./sql/d1.js";
+export { pgDriver, pgAdapter } from "./sql/postgres.js";
+export { NullSink } from "./sink.js";
+export { CreditsClient } from "./client.js";
+export { Wallet, } from "./wallet.js";
+//# sourceMappingURL=index.js.map

package/dist/meter/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/meter/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,OAAO,EAA0D,MAAM,cAAc,CAAC;AAC/F,OAAO,EACL,aAAa,EACb,UAAU,GAKX,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,UAAU,EAAE,aAAa,EAA+C,MAAM,aAAa,CAAC;AACrG,OAAO,EAAE,SAAS,EAAuC,MAAM,YAAY,CAAC;AAC5E,OAAO,EACL,MAAM,EACN,WAAW,EACX,WAAW,GAWZ,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,SAAS,EAAa,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAClF,OAAO,EAAuB,eAAe,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AACtC,OAAO,EAAgC,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxF,OAAO,EAAe,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAe,QAAQ,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAA6C,QAAQ,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,aAAa,EAA8D,MAAM,aAAa,CAAC;AACxG,OAAO,EACL,MAAM,GAOP,MAAM,aAAa,CAAC"}

package/dist/meter/meters-buckets.d.ts

@@ -0,0 +1,56 @@
+/**
+ * meters-buckets - the persisted-cascade config layer: types, DDL, refill.
+ *
+ * Free functions over a SqlDriver for the credits_bucket table's config/refill
+ * half. The load + resolve + charge round trip lives in meters-charge.ts; the
+ * MeterStore class (meters.ts) composes both.
+ */
+import type { SqlDriver } from "./sql/driver.js";
+import type { Cadence } from "./wallet.js";
+export declare const GLOBAL = "";
+/** The terminal meter's key. Always sorted last so it is the overdraftable buck-stop. */
+export declare const CREDITS_METER = "credits";
+/** Config for one bucket of one meter. The (meter, bucket) pair is unique per
+ *  (tenant, scope). */
+export interface MeterBucketDef {
+    /** Meter key: a feature ('smart_query') or the terminal 'credits' meter. */
+    meter: string;
+    /** Bucket name within the meter: 'daily' | 'monthly' | 'buyup'. */
+    bucket: string;
+    /** Refill ceiling (µcredits for credits, calls for a feature). */
+    cap: bigint;
+    /** Auto-refill cadence. 'none' = dormant (defined, never auto-refills). */
+    cadence: Cadence;
+    /** Billing unit, audit/display: 'call' for a feature, 'credit' for credits. */
+    unit: string;
+    /** Burn order WITHIN the meter (daily < monthly < buyup). */
+    priority: number;
+    /** Burn order ACROSS meters. Feature meters low; the credits meter must be
+     *  highest so it sorts terminal/last. */
+    meterPriority: number;
+    /** Carries forward across epochs (buyups true; daily/monthly false → reset-to-cap). */
+    carry?: boolean;
+    /** May overdraft (go negative). Only the credits buyup is true. */
+    overdraft?: boolean;
+    /** Optional upstream allocation this bucket is backed by (e.g. 'venice'). */
+    source?: string;
+}
+/** Period key for a cadence at an instant (UTC). Refill fires when it differs from
+ *  the stored key. (Local copy - keeps this module independent of Wallet.) */
+export declare function periodKey(cadence: Cadence, nowMs: number): string;
+/** Idempotent DDL: the generalized bucket table + a charge idempotency guard. */
+export declare function init(d: SqlDriver): Promise<void>;
+/** Define / update a bucket's config. Sets balance to cap on first insert so a
+ *  freshly-defined allowance starts full; an existing bucket keeps its balance
+ *  (the next refill() applies the cap). */
+export declare function setBucket(d: SqlDriver, tenant: string, scope: string, def: MeterBucketDef): Promise<void>;
+/** Refill every non-carry bucket whose epoch has rolled, reset-to-cap. Buyups
+ *  (carry=1) never auto-refill. Returns the topped (meter,bucket) pairs. */
+export declare function refill(d: SqlDriver, now: () => number, tenant: string, scope: string): Promise<{
+    topped: string[];
+    granted: bigint;
+}>;
+/** Add µcredits to the credits buyup (Stripe deposit / admin top-up). Nets
+ *  against any overdraft automatically. */
+export declare function deposit(d: SqlDriver, tenant: string, scope: string, ucredits: bigint): Promise<void>;
+//# sourceMappingURL=meters-buckets.d.ts.map

package/dist/meter/meters-buckets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meters-buckets.d.ts","sourceRoot":"","sources":["../../src/meter/meters-buckets.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,eAAO,MAAM,MAAM,KAAK,CAAC;AACzB,yFAAyF;AACzF,eAAO,MAAM,aAAa,YAAY,CAAC;AAEvC;uBACuB;AACvB,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,OAAO,EAAE,OAAO,CAAC;IACjB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB;6CACyC;IACzC,aAAa,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;8EAC8E;AAC9E,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CASjE;AAED,iFAAiF;AACjF,wBAAsB,IAAI,CAAC,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BtD;AAED;;2CAE2C;AAC3C,wBAAsB,SAAS,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB/G;AAED;4EAC4E;AAC5E,wBAAsB,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CA2B3I;AAED;2CAC2C;AAC3C,wBAAsB,OAAO,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS1G"}

package/dist/meter/meters-buckets.js

@@ -0,0 +1,111 @@
+import { toBig } from "./sql/driver.js";
+export const GLOBAL = "";
+/** The terminal meter's key. Always sorted last so it is the overdraftable buck-stop. */
+export const CREDITS_METER = "credits";
+/** Period key for a cadence at an instant (UTC). Refill fires when it differs from
+ *  the stored key. (Local copy - keeps this module independent of Wallet.) */
+export function periodKey(cadence, nowMs) {
+    if (cadence === "none")
+        return "none";
+    const d = new Date(nowMs);
+    const iso = d.toISOString();
+    if (cadence === "monthly")
+        return iso.slice(0, 7);
+    if (cadence === "daily")
+        return iso.slice(0, 10);
+    const start = Date.UTC(d.getUTCFullYear(), 0, 1);
+    const week = Math.floor((nowMs - start) / (7 * 24 * 3600 * 1000));
+    return `${d.getUTCFullYear()}-W${week}`;
+}
+/** Idempotent DDL: the generalized bucket table + a charge idempotency guard. */
+export async function init(d) {
+    const INT = d.dialect === "postgres" ? "BIGINT" : "INTEGER";
+    await d.exec(`CREATE TABLE IF NOT EXISTS credits_bucket (
+       tenant_id      TEXT NOT NULL,
+       scope          TEXT NOT NULL,
+       meter          TEXT NOT NULL,
+       bucket         TEXT NOT NULL,
+       balance        ${INT} NOT NULL DEFAULT 0,
+       cap            ${INT} NOT NULL DEFAULT 0,
+       cadence        TEXT NOT NULL DEFAULT 'none',
+       unit           TEXT NOT NULL DEFAULT 'credit',
+       priority       ${INT} NOT NULL DEFAULT 100,
+       meter_priority ${INT} NOT NULL DEFAULT 100,
+       carry          ${INT} NOT NULL DEFAULT 0,
+       overdraft      ${INT} NOT NULL DEFAULT 0,
+       source         TEXT,
+       period         TEXT,
+       refilled_at    ${INT},
+       PRIMARY KEY (tenant_id, scope, meter, bucket)
+     )`);
+    await d.exec(`CREATE TABLE IF NOT EXISTS bucket_txn (
+       idem_key  TEXT PRIMARY KEY,
+       tenant_id TEXT NOT NULL,
+       scope     TEXT NOT NULL,
+       charged   ${INT} NOT NULL,
+       at        ${INT} NOT NULL
+     )`);
+}
+/** Define / update a bucket's config. Sets balance to cap on first insert so a
+ *  freshly-defined allowance starts full; an existing bucket keeps its balance
+ *  (the next refill() applies the cap). */
+export async function setBucket(d, tenant, scope, def) {
+    const s = scope || GLOBAL;
+    const existing = await d.all("SELECT bucket FROM credits_bucket WHERE tenant_id=? AND scope=? AND meter=? AND bucket=?", [
+        tenant,
+        s,
+        def.meter,
+        def.bucket,
+    ]);
+    const carry = def.carry ? 1 : 0;
+    const overdraft = def.overdraft ? 1 : 0;
+    if (existing.length) {
+        await d.run("UPDATE credits_bucket SET cap=?, cadence=?, unit=?, priority=?, meter_priority=?, carry=?, overdraft=?, source=? WHERE tenant_id=? AND scope=? AND meter=? AND bucket=?", [def.cap, def.cadence, def.unit, def.priority, def.meterPriority, carry, overdraft, def.source ?? null, tenant, s, def.meter, def.bucket]);
+    }
+    else {
+        await d.run("INSERT INTO credits_bucket (tenant_id, scope, meter, bucket, balance, cap, cadence, unit, priority, meter_priority, carry, overdraft, source) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)", [tenant, s, def.meter, def.bucket, def.cap, def.cap, def.cadence, def.unit, def.priority, def.meterPriority, carry, overdraft, def.source ?? null]);
+    }
+}
+/** Refill every non-carry bucket whose epoch has rolled, reset-to-cap. Buyups
+ *  (carry=1) never auto-refill. Returns the topped (meter,bucket) pairs. */
+export async function refill(d, now, tenant, scope) {
+    const s = scope || GLOBAL;
+    const nowMs = now();
+    const rows = await d.all("SELECT meter, bucket, cap, cadence, carry, period FROM credits_bucket WHERE tenant_id=? AND scope=?", [tenant, s]);
+    const topped = [];
+    let granted = 0n;
+    for (const r of rows) {
+        if (r.cadence === "none" || toBig(r.carry) !== 0n)
+            continue; // dormant or a carry buyup
+        const key = periodKey(r.cadence, nowMs);
+        if (r.period === key)
+            continue;
+        const cap = toBig(r.cap);
+        await d.run("UPDATE credits_bucket SET balance=?, period=?, refilled_at=? WHERE tenant_id=? AND scope=? AND meter=? AND bucket=?", [
+            cap,
+            key,
+            nowMs,
+            tenant,
+            s,
+            r.meter,
+            r.bucket,
+        ]);
+        topped.push(`${r.meter}.${r.bucket}`);
+        granted += cap;
+    }
+    return { topped, granted };
+}
+/** Add µcredits to the credits buyup (Stripe deposit / admin top-up). Nets
+ *  against any overdraft automatically. */
+export async function deposit(d, tenant, scope, ucredits) {
+    if (ucredits <= 0n)
+        return;
+    const s = scope || GLOBAL;
+    await d.run("UPDATE credits_bucket SET balance = balance + ? WHERE tenant_id=? AND scope=? AND meter=? AND bucket='buyup'", [
+        ucredits,
+        tenant,
+        s,
+        CREDITS_METER,
+    ]);
+}
+//# sourceMappingURL=meters-buckets.js.map