@drm3/sdk 0.1.2

package/dist/meter/meters-buckets.js.map

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

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

@@ -0,0 +1,13 @@
+import { type Demand, type MeterState, type ResolveResult } from "./resolve.js";
+import { type SqlDriver } from "./sql/driver.js";
+/** Load this (tenant, scope) as the ordered `MeterState[]` resolveCharge wants:
+ *  feature meters by meter_priority, the credits meter forced terminal/last. */
+export declare function loadMeters(d: SqlDriver, tenant: string, scope: string): Promise<MeterState[]>;
+/** Charge a demand: load → resolveCharge → persist the draws. Idempotent on
+ *  idemKey across the whole charge. Floored buckets decrement under a
+ *  `balance >= amount` guard; the terminal credits buyup decrements unguarded
+ *  (it is the one node allowed to go negative). */
+export declare function charge(d: SqlDriver, now: () => number, tenant: string, scope: string, demand: Demand, idemKey?: string): Promise<ResolveResult & {
+    replay: boolean;
+}>;
+//# sourceMappingURL=meters-charge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"meters-charge.d.ts","sourceRoot":"","sources":["../../src/meter/meters-charge.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,UAAU,EAAE,KAAK,aAAa,EAAiB,MAAM,cAAc,CAAC;AAC/F,OAAO,EAAE,KAAK,SAAS,EAAS,MAAM,iBAAiB,CAAC;AAiBxD;gFACgF;AAChF,wBAAsB,UAAU,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAwBnG;AAED;;;mDAGmD;AACnD,wBAAsB,MAAM,CAC1B,CAAC,EAAE,SAAS,EACZ,GAAG,EAAE,MAAM,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,aAAa,GAAG;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC,CA4C9C"}

package/dist/meter/meters-charge.js

@@ -0,0 +1,76 @@
+import { CREDITS_METER, GLOBAL } from "./meters-buckets.js";
+import { resolveCharge } from "./resolve.js";
+import { toBig } from "./sql/driver.js";
+/** Load this (tenant, scope) as the ordered `MeterState[]` resolveCharge wants:
+ *  feature meters by meter_priority, the credits meter forced terminal/last. */
+export async function loadMeters(d, tenant, scope) {
+    const s = scope || GLOBAL;
+    const rows = await d.all("SELECT meter, bucket, balance, unit, priority, meter_priority FROM credits_bucket WHERE tenant_id=? AND scope=? ORDER BY meter_priority ASC, priority ASC", [tenant, s]);
+    const order = [];
+    const byMeter = new Map();
+    for (const r of rows) {
+        let m = byMeter.get(r.meter);
+        if (!m) {
+            m = { unit: r.unit || "credit", buckets: [] };
+            byMeter.set(r.meter, m);
+            order.push(r.meter);
+        }
+        m.buckets.push({ key: r.bucket, balance: toBig(r.balance) });
+    }
+    // Credits meter is always terminal: drop it from its sorted slot and re-append.
+    const featureKeys = order.filter((k) => k !== CREDITS_METER);
+    const ordered = byMeter.has(CREDITS_METER) ? [...featureKeys, CREDITS_METER] : featureKeys;
+    return ordered.map((key) => {
+        const m = byMeter.get(key);
+        return { key, unit: m.unit, buckets: m.buckets };
+    });
+}
+/** Charge a demand: load → resolveCharge → persist the draws. Idempotent on
+ *  idemKey across the whole charge. Floored buckets decrement under a
+ *  `balance >= amount` guard; the terminal credits buyup decrements unguarded
+ *  (it is the one node allowed to go negative). */
+export async function charge(d, now, tenant, scope, demand, idemKey) {
+    const s = scope || GLOBAL;
+    const empty = { meters: [], creditsCharged: 0n, overdraft: 0n, shortfall: 0n, byBucket: {} };
+    if (idemKey) {
+        const nowMs = now();
+        const guard = await d.run("INSERT INTO bucket_txn (idem_key, tenant_id, scope, charged, at) VALUES (?,?,?,?,?) ON CONFLICT (idem_key) DO NOTHING", [
+            idemKey,
+            tenant,
+            s,
+            0,
+            nowMs,
+        ]);
+        if (guard.rowsAffected === 0)
+            return { ...empty, replay: true };
+    }
+    const meters = await loadMeters(d, tenant, s);
+    if (meters.length === 0)
+        return { ...empty, replay: false };
+    const r = resolveCharge(meters, demand);
+    for (const [key, amount] of Object.entries(r.byBucket)) {
+        if (amount <= 0n)
+            continue;
+        const dot = key.indexOf(".");
+        const meter = key.slice(0, dot);
+        const bucket = key.slice(dot + 1);
+        // Floor guard first; if it loses (would go negative), this is the overdraft
+        // bucket - re-apply unguarded so the terminal credits buyup can go negative.
+        const guarded = await d.run("UPDATE credits_bucket SET balance = balance - ? WHERE tenant_id=? AND scope=? AND meter=? AND bucket=? AND balance >= ?", [
+            amount,
+            tenant,
+            s,
+            meter,
+            bucket,
+            amount,
+        ]);
+        if (guarded.rowsAffected === 0) {
+            await d.run("UPDATE credits_bucket SET balance = balance - ? WHERE tenant_id=? AND scope=? AND meter=? AND bucket=?", [amount, tenant, s, meter, bucket]);
+        }
+    }
+    if (idemKey) {
+        await d.run("UPDATE bucket_txn SET charged=? WHERE idem_key=?", [r.creditsCharged, idemKey]);
+    }
+    return { ...r, replay: false };
+}
+//# sourceMappingURL=meters-charge.js.map

package/dist/meter/meters-charge.js.map

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

package/dist/meter/meters.d.ts

@@ -0,0 +1,63 @@
+/**
+ * MeterStore - the persisted cascade. The schema half of the entitlement model.
+ *
+ * `resolve.ts` is pure math over an in-memory `MeterState[]`. This is its storage
+ * shape: ONE generalized bucket table that carries the META dimension the flat
+ * `credits_allowance` lacks, so a tenant can hold feature meters (smart_query,
+ * tts, …) AND the terminal credits meter, each a cascade of daily/monthly/buyup
+ * buckets:
+ *
+ *   credits_bucket(tenant, scope, meter, bucket → balance, cap, cadence, unit,
+ *                  priority, meter_priority, carry, overdraft, …)
+ *
+ * `loadMeters()` reads the rows into the exact `MeterState[]` order `resolveCharge`
+ * wants (feature meters by meter_priority, the credits meter terminal/last).
+ * `charge()` loads, resolves, and writes the draws back idempotently. Refill is
+ * reset-to-cap for the non-carry buckets whose epoch rolled.
+ *
+ * Deliberately SELF-CONTAINED: it does not read or write the live `credits_ledger`
+ * the queue ships today. Wiring the two is a later, coordinated step; this proves
+ * the round trip first. Pure integer (µcredit) bigint, single-conditional-UPDATE
+ * atomicity (same row-lock pattern as the rest of the package).
+ *
+ * This file is the barrel: the class composes meters-buckets.ts (config, refill,
+ * deposit) and meters-charge.ts (load, resolve, charge), and re-exports the API.
+ */
+import type { Demand, MeterState, ResolveResult } from "./resolve.js";
+import type { SqlDriver } from "./sql/driver.js";
+export { CREDITS_METER, type MeterBucketDef } from "./meters-buckets.js";
+import type { MeterBucketDef } from "./meters-buckets.js";
+export interface MeterStoreOptions {
+    now?: () => number;
+}
+export declare class MeterStore {
+    private readonly d;
+    private readonly now;
+    constructor(driver: SqlDriver, opts?: MeterStoreOptions);
+    /** Idempotent DDL: the generalized bucket table + a charge idempotency guard. */
+    init(): 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). */
+    setBucket(tenant: string, scope: string, def: MeterBucketDef): Promise<void>;
+    /** Load this (tenant, scope) as the ordered `MeterState[]` resolveCharge wants:
+     *  feature meters by meter_priority, the credits meter forced terminal/last. */
+    loadMeters(tenant: string, scope: string): Promise<MeterState[]>;
+    /** Refill every non-carry bucket whose epoch has rolled, reset-to-cap. Buyups
+     *  (carry=1) never auto-refill. Returns the topped (meter,bucket) pairs. */
+    refill(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. */
+    deposit(tenant: string, scope: string, ucredits: bigint): Promise<void>;
+    /** Charge a demand: load → resolveCharge → persist the draws. Idempotent on
+     *  idemKey across the whole charge. Floored buckets decrement under a
+     *  `balance >= amount` guard; the terminal credits buyup decrements unguarded
+     *  (it is the one node allowed to go negative). */
+    charge(tenant: string, scope: string, demand: Demand, idemKey?: string): Promise<ResolveResult & {
+        replay: boolean;
+    }>;
+}
+//# sourceMappingURL=meters.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"meters.d.ts","sourceRoot":"","sources":["../../src/meter/meters.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAY;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEvB,MAAM,EAAE,SAAS,EAAE,IAAI,GAAE,iBAAsB;IAK3D,iFAAiF;IAC3E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;+CAE2C;IACrC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlF;oFACgF;IAC1E,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAItE;gFAC4E;IACtE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAI3F;+CAC2C;IACrC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7E;;;uDAGmD;IAC7C,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;CAG5H"}

package/dist/meter/meters.js

@@ -0,0 +1,44 @@
+import * as buckets from "./meters-buckets.js";
+import * as chargeMod from "./meters-charge.js";
+export { CREDITS_METER } from "./meters-buckets.js";
+export class MeterStore {
+    d;
+    now;
+    constructor(driver, opts = {}) {
+        this.d = driver;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    /** Idempotent DDL: the generalized bucket table + a charge idempotency guard. */
+    async init() {
+        return buckets.init(this.d);
+    }
+    /** 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). */
+    async setBucket(tenant, scope, def) {
+        return buckets.setBucket(this.d, tenant, scope, def);
+    }
+    /** Load this (tenant, scope) as the ordered `MeterState[]` resolveCharge wants:
+     *  feature meters by meter_priority, the credits meter forced terminal/last. */
+    async loadMeters(tenant, scope) {
+        return chargeMod.loadMeters(this.d, tenant, scope);
+    }
+    /** Refill every non-carry bucket whose epoch has rolled, reset-to-cap. Buyups
+     *  (carry=1) never auto-refill. Returns the topped (meter,bucket) pairs. */
+    async refill(tenant, scope) {
+        return buckets.refill(this.d, this.now, tenant, scope);
+    }
+    /** Add µcredits to the credits buyup (Stripe deposit / admin top-up). Nets
+     *  against any overdraft automatically. */
+    async deposit(tenant, scope, ucredits) {
+        return buckets.deposit(this.d, tenant, scope, ucredits);
+    }
+    /** Charge a demand: load → resolveCharge → persist the draws. Idempotent on
+     *  idemKey across the whole charge. Floored buckets decrement under a
+     *  `balance >= amount` guard; the terminal credits buyup decrements unguarded
+     *  (it is the one node allowed to go negative). */
+    async charge(tenant, scope, demand, idemKey) {
+        return chargeMod.charge(this.d, this.now, tenant, scope, demand, idemKey);
+    }
+}
+//# sourceMappingURL=meters.js.map

package/dist/meter/meters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meters.js","sourceRoot":"","sources":["../../src/meter/meters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,qBAAqB,CAAC;AAC/C,OAAO,KAAK,SAAS,MAAM,oBAAoB,CAAC;AA6BhD,OAAO,EAAE,aAAa,EAAuB,MAAM,qBAAqB,CAAC;AAOzE,MAAM,OAAO,UAAU;IACJ,CAAC,CAAY;IACb,GAAG,CAAe;IAEnC,YAAY,MAAiB,EAAE,OAA0B,EAAE;QACzD,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC;QAChB,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,iFAAiF;IACjF,KAAK,CAAC,IAAI;QACR,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9B,CAAC;IAED;;+CAE2C;IAC3C,KAAK,CAAC,SAAS,CAAC,MAAc,EAAE,KAAa,EAAE,GAAmB;QAChE,OAAO,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;IACvD,CAAC;IAED;oFACgF;IAChF,KAAK,CAAC,UAAU,CAAC,MAAc,EAAE,KAAa;QAC5C,OAAO,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IACrD,CAAC;IAED;gFAC4E;IAC5E,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,KAAa;QACxC,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IACzD,CAAC;IAED;+CAC2C;IAC3C,KAAK,CAAC,OAAO,CAAC,MAAc,EAAE,KAAa,EAAE,QAAgB;QAC3D,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC1D,CAAC;IAED;;;uDAGmD;IACnD,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,KAAa,EAAE,MAAc,EAAE,OAAgB;QAC1E,OAAO,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5E,CAAC;CACF"}

package/dist/meter/plans.d.ts

@@ -0,0 +1,63 @@
+/**
+ * PlanStore - a plan is a named cascade config; the tier catalog is data.
+ *
+ * `MeterStore` holds one tenant's live cascade (their `credits_bucket` rows). A
+ * PLAN is the template those rows are stamped from: a named bundle of bucket
+ * configs (caps, cadences, priorities) for the feature meters and the credits
+ * meter. Assigning a plan to a tenant MATERIALIZES it - writes their bucket rows
+ * via MeterStore.setBucket, so a fresh allowance starts full and re-assigning
+ * re-stamps the config. This is where pricing lives: a TIER *is* its plan, and
+ * changing a cap is changing the price. No new math - plans only choose which
+ * cascade a tenant runs; resolveCharge does the rest.
+ *
+ *   plan(id, name, description)
+ *   plan_bucket(plan, meter, bucket → cap, cadence, unit, priority, …)  -- the config
+ *   tenant_plan(tenant, scope → plan_id, assigned_at)                   -- who's on what
+ *
+ * Self-contained like MeterStore; the admin portal CRUDs these, and the queue
+ * assigns one when provisioning a tenant.
+ */
+import type { MeterBucketDef, MeterStore } from "./meters.js";
+import { type SqlDriver } from "./sql/driver.js";
+/** A named plan: metadata + the bucket configs it confers. */
+export interface PlanDef {
+    id: string;
+    name: string;
+    description?: string;
+    /** The cascade this plan stamps onto a tenant (feature meters + credits). */
+    buckets: MeterBucketDef[];
+}
+export interface PlanStoreOptions {
+    now?: () => number;
+}
+export declare class PlanStore {
+    private readonly d;
+    private readonly now;
+    constructor(driver: SqlDriver, opts?: PlanStoreOptions);
+    /** Idempotent DDL: the plan catalog + its bucket configs + tenant assignments. */
+    init(): Promise<void>;
+    /** Upsert a plan and REPLACE its bucket set (so removing a bucket from the def
+     *  removes it from the plan). Does not touch any tenant already on the plan; a
+     *  re-assign re-materializes. */
+    setPlan(plan: PlanDef): Promise<void>;
+    /** The bucket configs for a plan, as MeterBucketDefs ready to materialize. */
+    bucketsFor(planId: string): Promise<MeterBucketDef[]>;
+    /** Full plan (metadata + buckets), or null if absent. */
+    getPlan(planId: string): Promise<PlanDef | null>;
+    /** Plan catalog (metadata only). */
+    listPlans(): Promise<{
+        id: string;
+        name: string;
+        description: string | null;
+    }[]>;
+    /** The plan a tenant is currently assigned, or null. */
+    assignedPlan(tenant: string, scope?: string): Promise<string | null>;
+    /** Assign a plan to a tenant and MATERIALIZE it: record the assignment and stamp
+     *  the plan's buckets onto the tenant via MeterStore.setBucket (fresh allowances
+     *  start full; existing buckets keep their balance, config re-stamped). Throws on
+     *  an unknown plan. Returns how many buckets were materialized. */
+    assign(store: MeterStore, tenant: string, scope: string, planId: string): Promise<{
+        materialized: number;
+    }>;
+}
+//# sourceMappingURL=plans.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plans.d.ts","sourceRoot":"","sources":["../../src/meter/plans.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,KAAK,SAAS,EAAS,MAAM,iBAAiB,CAAC;AAKxD,8DAA8D;AAC9D,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAeD,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAY;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEvB,MAAM,EAAE,SAAS,EAAE,IAAI,GAAE,gBAAqB;IAK1D,kFAAkF;IAC5E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAoC3B;;qCAEiC;IAC3B,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB3C,8EAA8E;IACxE,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAmB3D,yDAAyD;IACnD,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAOtD,oCAAoC;IAC9B,SAAS,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,EAAE,CAAC;IAItF,wDAAwD;IAClD,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAK1E;;;uEAGmE;IAC7D,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;CAiBlH"}

package/dist/meter/plans.js

@@ -0,0 +1,114 @@
+import { toBig } from "./sql/driver.js";
+const GLOBAL = "";
+export class PlanStore {
+    d;
+    now;
+    constructor(driver, opts = {}) {
+        this.d = driver;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    /** Idempotent DDL: the plan catalog + its bucket configs + tenant assignments. */
+    async init() {
+        const INT = this.d.dialect === "postgres" ? "BIGINT" : "INTEGER";
+        await this.d.exec(`CREATE TABLE IF NOT EXISTS plan (
+         id          TEXT PRIMARY KEY,
+         name        TEXT NOT NULL,
+         description TEXT
+       )`);
+        await this.d.exec(`CREATE TABLE IF NOT EXISTS plan_bucket (
+         plan           TEXT NOT NULL,
+         meter          TEXT NOT NULL,
+         bucket         TEXT NOT NULL,
+         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,
+         PRIMARY KEY (plan, meter, bucket)
+       )`);
+        await this.d.exec(`CREATE TABLE IF NOT EXISTS tenant_plan (
+         tenant_id   TEXT NOT NULL,
+         scope       TEXT NOT NULL,
+         plan_id     TEXT NOT NULL,
+         assigned_at ${INT} NOT NULL,
+         PRIMARY KEY (tenant_id, scope)
+       )`);
+    }
+    /** Upsert a plan and REPLACE its bucket set (so removing a bucket from the def
+     *  removes it from the plan). Does not touch any tenant already on the plan; a
+     *  re-assign re-materializes. */
+    async setPlan(plan) {
+        const exists = await this.d.all("SELECT id FROM plan WHERE id=?", [plan.id]);
+        if (exists.length) {
+            await this.d.run("UPDATE plan SET name=?, description=? WHERE id=?", [plan.name, plan.description ?? null, plan.id]);
+        }
+        else {
+            await this.d.run("INSERT INTO plan (id, name, description) VALUES (?,?,?)", [plan.id, plan.name, plan.description ?? null]);
+        }
+        await this.d.run("DELETE FROM plan_bucket WHERE plan=?", [plan.id]);
+        for (const b of plan.buckets) {
+            await this.d.run("INSERT INTO plan_bucket (plan, meter, bucket, cap, cadence, unit, priority, meter_priority, carry, overdraft, source) VALUES (?,?,?,?,?,?,?,?,?,?,?)", [plan.id, b.meter, b.bucket, b.cap, b.cadence, b.unit, b.priority, b.meterPriority, b.carry ? 1 : 0, b.overdraft ? 1 : 0, b.source ?? null]);
+        }
+    }
+    /** The bucket configs for a plan, as MeterBucketDefs ready to materialize. */
+    async bucketsFor(planId) {
+        const rows = await this.d.all("SELECT meter, bucket, cap, cadence, unit, priority, meter_priority, carry, overdraft, source FROM plan_bucket WHERE plan=? ORDER BY meter_priority ASC, priority ASC", [planId]);
+        return rows.map((r) => ({
+            meter: r.meter,
+            bucket: r.bucket,
+            cap: toBig(r.cap),
+            cadence: r.cadence,
+            unit: r.unit,
+            priority: Number(toBig(r.priority)),
+            meterPriority: Number(toBig(r.meter_priority)),
+            carry: toBig(r.carry) !== 0n,
+            overdraft: toBig(r.overdraft) !== 0n,
+            source: r.source ?? undefined,
+        }));
+    }
+    /** Full plan (metadata + buckets), or null if absent. */
+    async getPlan(planId) {
+        const rows = await this.d.all("SELECT id, name, description FROM plan WHERE id=?", [planId]);
+        const p = rows[0];
+        if (!p)
+            return null;
+        return { id: p.id, name: p.name, description: p.description ?? undefined, buckets: await this.bucketsFor(planId) };
+    }
+    /** Plan catalog (metadata only). */
+    async listPlans() {
+        return this.d.all("SELECT id, name, description FROM plan ORDER BY id");
+    }
+    /** The plan a tenant is currently assigned, or null. */
+    async assignedPlan(tenant, scope = GLOBAL) {
+        const rows = await this.d.all("SELECT plan_id FROM tenant_plan WHERE tenant_id=? AND scope=?", [tenant, scope || GLOBAL]);
+        return rows[0]?.plan_id ?? null;
+    }
+    /** Assign a plan to a tenant and MATERIALIZE it: record the assignment and stamp
+     *  the plan's buckets onto the tenant via MeterStore.setBucket (fresh allowances
+     *  start full; existing buckets keep their balance, config re-stamped). Throws on
+     *  an unknown plan. Returns how many buckets were materialized. */
+    async assign(store, tenant, scope, planId) {
+        const defs = await this.bucketsFor(planId);
+        if (defs.length === 0) {
+            const known = await this.getPlan(planId);
+            if (!known)
+                throw new Error(`assign: unknown plan '${planId}'`);
+        }
+        const s = scope || GLOBAL;
+        const now = this.now();
+        const existing = await this.d.all("SELECT tenant_id FROM tenant_plan WHERE tenant_id=? AND scope=?", [tenant, s]);
+        if (existing.length) {
+            await this.d.run("UPDATE tenant_plan SET plan_id=?, assigned_at=? WHERE tenant_id=? AND scope=?", [planId, now, tenant, s]);
+        }
+        else {
+            await this.d.run("INSERT INTO tenant_plan (tenant_id, scope, plan_id, assigned_at) VALUES (?,?,?,?)", [tenant, s, planId, now]);
+        }
+        for (const def of defs)
+            await store.setBucket(tenant, s, def);
+        return { materialized: defs.length };
+    }
+}
+//# sourceMappingURL=plans.js.map

package/dist/meter/plans.js.map

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

package/dist/meter/pricebook.d.ts

@@ -0,0 +1,32 @@
+import type { Credits } from "./types.js";
+/**
+ * Converts any metered unit into integer µcredits (base units). Inference
+ * tokens, a DB query, a refinement run, bytes of egress, compute-ms - all just
+ * units with a rate.
+ *
+ * Rates are integers in µcredits, never floats, and a quote is `rate × qty`
+ * (+ optional flat base) - pure integer arithmetic. So a quote is ALWAYS an
+ * exact whole number of µcredits: rounding cannot occur. Author rates against
+ * the `CREDIT` scale, e.g. `{ perUnit: CREDIT / 10_000n }` = 1 credit / 10k
+ * units = 100 µcredits/unit. Pick ratios that divide CREDIT cleanly (they do
+ * for any sane price) and there is never anything to round.
+ */
+import { CREDIT } from "./units.js";
+export interface Rate {
+    /** µcredits charged per unit of work - an INTEGER, never a float.
+     *  Author against CREDIT, e.g. `CREDIT / 1_000n` (0.001 credit/unit). */
+    perUnit: bigint;
+    /** optional flat µcredits added per quote (e.g. a base request fee). */
+    base?: bigint;
+}
+export declare class PriceBook {
+    private rates;
+    constructor(initial?: Record<string, Rate>);
+    set(unit: string, rate: Rate): this;
+    has(unit: string): boolean;
+    /** Quote `qty` of `unit` as integer µcredits - exact, never rounded.
+     *  Unknown unit or qty ≤ 0 → 0n (caller may guard). */
+    quote(unit: string, qty: number): Credits;
+}
+export { CREDIT };
+//# sourceMappingURL=pricebook.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pricebook.d.ts","sourceRoot":"","sources":["../../src/meter/pricebook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEpC,MAAM,WAAW,IAAI;IACnB;6EACyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,KAAK,CAA2B;gBAE5B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC;IAI1C,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI;IAKnC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;2DACuD;IACvD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;CAK1C;AAED,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/dist/meter/pricebook.js

@@ -0,0 +1,38 @@
+/**
+ * Converts any metered unit into integer µcredits (base units). Inference
+ * tokens, a DB query, a refinement run, bytes of egress, compute-ms - all just
+ * units with a rate.
+ *
+ * Rates are integers in µcredits, never floats, and a quote is `rate × qty`
+ * (+ optional flat base) - pure integer arithmetic. So a quote is ALWAYS an
+ * exact whole number of µcredits: rounding cannot occur. Author rates against
+ * the `CREDIT` scale, e.g. `{ perUnit: CREDIT / 10_000n }` = 1 credit / 10k
+ * units = 100 µcredits/unit. Pick ratios that divide CREDIT cleanly (they do
+ * for any sane price) and there is never anything to round.
+ */
+import { CREDIT } from "./units.js";
+export class PriceBook {
+    rates = new Map();
+    constructor(initial) {
+        if (initial)
+            for (const [unit, rate] of Object.entries(initial))
+                this.rates.set(unit, rate);
+    }
+    set(unit, rate) {
+        this.rates.set(unit, rate);
+        return this;
+    }
+    has(unit) {
+        return this.rates.has(unit);
+    }
+    /** Quote `qty` of `unit` as integer µcredits - exact, never rounded.
+     *  Unknown unit or qty ≤ 0 → 0n (caller may guard). */
+    quote(unit, qty) {
+        const r = this.rates.get(unit);
+        if (!r || qty <= 0)
+            return 0n;
+        return (r.base ?? 0n) + r.perUnit * BigInt(Math.trunc(qty));
+    }
+}
+export { CREDIT };
+//# sourceMappingURL=pricebook.js.map

package/dist/meter/pricebook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricebook.js","sourceRoot":"","sources":["../../src/meter/pricebook.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAUpC,MAAM,OAAO,SAAS;IACZ,KAAK,GAAG,IAAI,GAAG,EAAgB,CAAC;IAExC,YAAY,OAA8B;QACxC,IAAI,OAAO;YAAE,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;gBAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC9F,CAAC;IAED,GAAG,CAAC,IAAY,EAAE,IAAU;QAC1B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED;2DACuD;IACvD,KAAK,CAAC,IAAY,EAAE,GAAW;QAC7B,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC;YAAE,OAAO,EAAE,CAAC;QAC9B,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9D,CAAC;CACF;AAED,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/dist/meter/resolve.d.ts

@@ -0,0 +1,103 @@
+/**
+ * resolve - the OUTER cascade: a wallet is a cascade of meters.
+ *
+ * The inner `cascade()` draws across the BUCKETS of one meter (daily → monthly →
+ * buyup). This layer draws across the METERS of a wallet: the feature meters
+ * first (most-specific), then the generic credits meter as the terminal fallback.
+ * It is the same floor-and-spill idea one level up, with ONE subtlety the inner
+ * cascade doesn't have - the UNIT SEAM.
+ *
+ *   Feature meters count CALLS. The credits meter counts µCREDITS. So when a
+ *   feature call spills past its own meter (the allowance is exhausted), it does
+ *   not carry "calls" into the credits meter - it converts: each unmet call costs
+ *   `creditPricePerUnit` µcredits, and that credit demand flows into the credits
+ *   cascade. "Use the feature allowance first because it's more specific; only
+ *   what it can't cover costs credits."
+ *
+ * Resolution for one request:
+ *   1. Feature demand + a matching feature meter? Draw the calls from its buckets
+ *      (daily → monthly → buyup), FLOORED (overdraft is terminal-only, so a
+ *      feature buyup floors and spills rather than going negative). The unmet
+ *      calls convert to a credit demand.
+ *   2. Feature demand + NO matching meter? The whole call bills credits directly
+ *      (units × creditPricePerUnit) - features without an allowance just cost
+ *      credits.
+ *   3. Generic credit demand? That µcredit amount IS the credit demand.
+ *   4. Draw the credit demand from the credits meter's buckets (daily → monthly →
+ *      buyup), with the buyup OVERDRAFTING (it is the one terminal node).
+ *
+ * Gating (entitlement, "unlimited") and the always-on cost accounting live ABOVE
+ * this: see `creditCost()` for the cost that is logged on every call regardless of
+ * what (if anything) is debited. This module is pure integer math - no I/O, no
+ * storage, no clock. The DB-backed Wallet composes it.
+ */
+import { type CascadeDraw, type CascadeNode } from "./cascade.js";
+/** One meter in the wallet cascade. Its buckets are the inner cascade, ordered
+ *  (daily → monthly → buyup). The LAST meter in a wallet is the terminal credits
+ *  meter; every earlier meter is a feature meter that floors and spills. */
+export interface MeterState {
+    /** Feature key (e.g. 'smart_query'), or the terminal meter's key (e.g. 'credits'). */
+    readonly key: string;
+    /** Billing unit, for the audit/display only ('call', 'credit', …). The math is
+     *  unit-agnostic; conversion happens via the demand's `creditPricePerUnit`. */
+    readonly unit: string;
+    /** Ordered buckets - daily, monthly, buyup. The inner cascade draws these. */
+    readonly buckets: readonly CascadeNode[];
+}
+/** What a request wants to consume. Either a feature call (drawn from that
+ *  feature's meter, overflow priced into credits) or a raw credit charge. */
+export type Demand = {
+    /** The feature meter this call consumes. */
+    readonly feature: string;
+    /** Calls this request consumes. Default 1. */
+    readonly units?: bigint;
+    /** µcredits one unmet call costs - the price that converts overflow (and the
+     *  whole call when the feature has no meter) into credit demand. */
+    readonly creditPricePerUnit: bigint;
+} | {
+    /** µcredits to charge directly to the credits meter (generic inference). */
+    readonly ucredits: bigint;
+};
+/** Per-meter outcome, in resolution order. */
+export interface MeterDraw {
+    readonly key: string;
+    readonly unit: string;
+    /** Per-bucket draws within this meter. */
+    readonly draws: readonly CascadeDraw[];
+    /** Units this meter covered (in its own unit: calls for a feature, µcredits for credits). */
+    readonly applied: bigint;
+    /** Units this meter could NOT cover and passed on (converted to credits for a
+     *  feature meter; unmet credit demand for a non-overdrafting credits meter). */
+    readonly overflow: bigint;
+}
+export interface ResolveResult {
+    /** Per-meter breakdown, resolution order: feature meter (if any), then credits. */
+    readonly meters: readonly MeterDraw[];
+    /** µcredits actually drawn from the credits meter (allowances + buyup overdraft). */
+    readonly creditsCharged: bigint;
+    /** New negative incurred on the credits buyup this charge (>= 0). 0 unless the
+     *  buyup overdrafted. */
+    readonly overdraft: bigint;
+    /** Unmet credit demand - always 0 when the terminal buyup overdrafts (default). */
+    readonly shortfall: bigint;
+    /** Flat per-bucket map keyed `meter.bucket` (nonzero draws only), for the audit row. */
+    readonly byBucket: Readonly<Record<string, bigint>>;
+}
+/** The credit cost of a demand, independent of any balance or meter - the meter
+ *  reading that is ALWAYS logged (accounting ≠ debiting). For a feature call this
+ *  is `units × price` even when an allowance will cover it for free; for a credit
+ *  demand it is the amount itself. */
+export declare function creditCost(demand: Demand): bigint;
+/**
+ * Draw a demand across the wallet's meters. Pure: input meters are never mutated.
+ *
+ * @param meters ordered meters - feature meters first, the terminal credits meter LAST.
+ * @param demand a feature call or a raw credit charge.
+ * @param opts.terminalOverdraft whether the credits buyup may go negative (default
+ *   true - the production rail buys-back-up). false makes the whole wallet floor
+ *   and report the unmet amount as `shortfall` (useful for a dry-run gate check).
+ */
+export declare function resolveCharge(meters: readonly MeterState[], demand: Demand, opts?: {
+    terminalOverdraft?: boolean;
+}): ResolveResult;
+//# sourceMappingURL=resolve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/meter/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAW,MAAM,cAAc,CAAC;AAE3E;;4EAE4E;AAC5E,MAAM,WAAW,UAAU;IACzB,sFAAsF;IACtF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;mFAC+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;CAC1C;AAED;6EAC6E;AAC7E,MAAM,MAAM,MAAM,GACd;IACE,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;wEACoE;IACpE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC,GACD;IACE,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEN,8CAA8C;AAC9C,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,6FAA6F;IAC7F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;oFACgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,qFAAqF;IACrF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;6BACyB;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,mFAAmF;IACnF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wFAAwF;IACxF,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAID;;;sCAGsC;AACtC,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGjD;AAQD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,aAAa,CAwCtI"}