muonroi-cli 1.2.0

package/dist/usage/ledger.js

@@ -0,0 +1,181 @@
+/**
+ * src/usage/ledger.ts
+ *
+ * Reservation ledger for USAGE-03.
+ * Atomic reserve/commit/release primitives with file-lock via proper-lockfile.
+ *
+ * Invariant: current_usd + sum(reservations.usd) + projected <= cap.monthly_usd
+ * or reserve() returns CapBreachError.
+ *
+ * Pitfall 5 mitigation: callers MUST use try/finally with release() in finally
+ * to prevent reservation leaks on stream abort.
+ *
+ * Pitfall 7 mitigation: proper-lockfile exclusive lock serializes concurrent
+ * reserve() calls so 10-parallel tool-call bursts cannot collectively exceed cap.
+ */
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import lockfile from "proper-lockfile";
+import { atomicReadJSON, atomicWriteJSON } from "../storage/atomic-io.js";
+import { projectCostUSD } from "./estimator.js";
+import { emit, evaluateThresholds } from "./thresholds.js";
+import { CapBreachError } from "./types.js";
+const DEFAULT_CAP_USD = 15;
+function muonroiHome(homeOverride) {
+    return homeOverride ?? process.env.MUONROI_CLI_HOME ?? path.join(os.homedir(), ".muonroi-cli");
+}
+async function loadCapUSD(homeOverride) {
+    const cfg = await atomicReadJSON(path.join(muonroiHome(homeOverride), "config.json"));
+    return cfg?.cap?.monthly_usd ?? DEFAULT_CAP_USD;
+}
+function emptyState() {
+    const d = new Date();
+    const yyyy = d.getUTCFullYear();
+    const mm = String(d.getUTCMonth() + 1).padStart(2, "0");
+    return {
+        current_month_utc: `${yyyy}-${mm}`,
+        current_usd: 0,
+        reservations: [],
+        thresholds_fired_this_month: [],
+    };
+}
+async function ensureUsageFile(filePath) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    try {
+        await fs.access(filePath);
+    }
+    catch {
+        // Race-safe: if another process created the file between access() and writeFile(),
+        // the atomicWriteJSON may fail on rename. Swallow ENOENT/EBUSY and re-check.
+        try {
+            await atomicWriteJSON(filePath, emptyState());
+        }
+        catch {
+            // If file now exists (race loser), that's fine -- proceed.
+            try {
+                await fs.access(filePath);
+            }
+            catch {
+                throw new Error(`Failed to initialize usage file at ${filePath}`);
+            }
+        }
+    }
+}
+/**
+ * Execute a function under exclusive file lock on usage.json.
+ * The lock prevents racing readers/writers across CLI processes.
+ */
+async function withLock(filePath, fn) {
+    await ensureUsageFile(filePath);
+    const releaseLock = await lockfile.lock(filePath, {
+        retries: { retries: 10, minTimeout: 10, maxTimeout: 100 },
+        stale: 5_000,
+        realpath: false,
+    });
+    try {
+        const state = (await atomicReadJSON(filePath)) ?? emptyState();
+        const { next, result } = await fn(state);
+        await atomicWriteJSON(filePath, next);
+        return result;
+    }
+    finally {
+        await releaseLock();
+    }
+}
+/**
+ * Reserve projected token spend against the monthly cap.
+ * Returns ReservationToken on success, CapBreachError if projection would exceed cap.
+ *
+ * Caller contract: MUST call commit() or release() on the token.
+ * Use try/finally: `const tok = await reserve(...); try { ... commit(tok) } finally { release(tok) }`
+ */
+export async function reserve(args) {
+    const filePath = path.join(muonroiHome(args.homeOverride), "usage.json");
+    const cap = await loadCapUSD(args.homeOverride);
+    return withLock(filePath, async (state) => {
+        const projected = projectCostUSD(args.provider, args.model, args.estInputTokens, args.estOutputTokens);
+        const reservedTotal = state.reservations.reduce((s, r) => s + r.usd, 0);
+        if (state.current_usd + reservedTotal + projected > cap) {
+            return {
+                next: state,
+                result: new CapBreachError(state.current_usd, reservedTotal, projected, cap),
+            };
+        }
+        const id = crypto.randomUUID();
+        const tok = {
+            id,
+            model: args.model,
+            provider: args.provider,
+            projected_usd: projected,
+            est_input_tokens: args.estInputTokens,
+            est_output_tokens: args.estOutputTokens,
+            createdAtMs: Date.now(),
+        };
+        const next = {
+            ...state,
+            reservations: [
+                ...state.reservations,
+                {
+                    id,
+                    usd: projected,
+                    createdAtMs: tok.createdAtMs,
+                    model: tok.model,
+                    provider: tok.provider,
+                    est_input_tokens: tok.est_input_tokens,
+                    est_output_tokens: tok.est_output_tokens,
+                },
+            ],
+        };
+        return { next, result: tok };
+    });
+}
+/**
+ * Commit actual token spend. Removes the reservation and increments current_usd.
+ * Idempotent: if the reservation ID is not found, this is a no-op.
+ *
+ * Evaluates thresholds after state mutation and emits events post-lock-release.
+ */
+export async function commit(token, actualInputTokens, actualOutputTokens, homeOverride) {
+    const filePath = path.join(muonroiHome(homeOverride), "usage.json");
+    const cap = await loadCapUSD(homeOverride);
+    const pendingEvents = await withLock(filePath, async (state) => {
+        const idx = state.reservations.findIndex((r) => r.id === token.id);
+        if (idx === -1)
+            return { next: state, result: [] };
+        const actual = projectCostUSD(token.provider, token.model, actualInputTokens, actualOutputTokens);
+        const reservations = state.reservations.filter((r) => r.id !== token.id);
+        const prevUsd = state.current_usd;
+        const nextUsd = state.current_usd + actual;
+        // Evaluate thresholds
+        const thresholdResult = evaluateThresholds({
+            prevUsd,
+            nextUsd,
+            capUsd: cap,
+            firedThisMonth: state.thresholds_fired_this_month ?? [],
+        });
+        const next = {
+            ...state,
+            current_usd: nextUsd,
+            reservations,
+            thresholds_fired_this_month: thresholdResult.nextFired,
+        };
+        return { next, result: thresholdResult.events };
+    });
+    // Emit events AFTER lock release to avoid holding the lock during listener callbacks
+    for (const ev of pendingEvents) {
+        emit(ev);
+    }
+}
+/**
+ * Release a reservation without committing actual cost.
+ * Used on stream abort (Pitfall 5 mitigation).
+ */
+export async function release(token, homeOverride) {
+    const filePath = path.join(muonroiHome(homeOverride), "usage.json");
+    await withLock(filePath, async (state) => {
+        const reservations = state.reservations.filter((r) => r.id !== token.id);
+        return { next: { ...state, reservations }, result: undefined };
+    });
+}
+//# sourceMappingURL=ledger.js.map

package/dist/usage/ledger.js.map

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

package/dist/usage/ledger.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/usage/ledger.test.js

@@ -0,0 +1,171 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { atomicReadJSON } from "../storage/atomic-io.js";
+import { commit, release, reserve } from "./ledger.js";
+import { subscribeThresholds } from "./thresholds.js";
+import { CapBreachError } from "./types.js";
+async function makeTmpHome(capUsd = 15) {
+    const home = await fs.mkdtemp(path.join(os.tmpdir(), "muonroi-ledger-"));
+    await fs.writeFile(path.join(home, "config.json"), JSON.stringify({ cap: { monthly_usd: capUsd } }));
+    return home;
+}
+async function readUsage(home) {
+    return atomicReadJSON(path.join(home, "usage.json"));
+}
+describe("ledger", () => {
+    let home;
+    beforeEach(async () => {
+        home = await makeTmpHome(1.0); // $1.00 cap for easy math
+    });
+    describe("reserve()", () => {
+        it("returns ReservationToken when projection < cap", async () => {
+            const result = await reserve({
+                provider: "anthropic",
+                model: "claude-3-5-haiku-latest",
+                estInputTokens: 1000,
+                estOutputTokens: 500,
+                homeOverride: home,
+            });
+            expect(result).not.toBeInstanceOf(CapBreachError);
+            const tok = result;
+            expect(tok.id).toBeTruthy();
+            expect(tok.model).toBe("claude-3-5-haiku-latest");
+            expect(tok.provider).toBe("anthropic");
+            expect(tok.projected_usd).toBeGreaterThan(0);
+            // usage.json should have a reservation
+            const state = await readUsage(home);
+            expect(state.reservations).toHaveLength(1);
+            expect(state.reservations[0].id).toBe(tok.id);
+        });
+        it("returns CapBreachError when projection would exceed cap", async () => {
+            // claude-3-5-sonnet-latest: $3/M in + $15/M out
+            // 1M input = $3 + 1M output = $15 = $18 total >> $1.00 cap
+            const result = await reserve({
+                provider: "anthropic",
+                model: "claude-3-5-sonnet-latest",
+                estInputTokens: 1_000_000,
+                estOutputTokens: 1_000_000,
+                homeOverride: home,
+            });
+            expect(result).toBeInstanceOf(CapBreachError);
+            // usage.json should be unchanged (no reservation added)
+            const state = await readUsage(home);
+            expect(state.reservations).toHaveLength(0);
+        });
+    });
+    describe("commit()", () => {
+        it("removes reservation and increments current_usd by actual cost", async () => {
+            const tok = (await reserve({
+                provider: "anthropic",
+                model: "claude-3-5-haiku-latest",
+                estInputTokens: 10_000,
+                estOutputTokens: 5_000,
+                homeOverride: home,
+            }));
+            await commit(tok, 8_000, 4_000, home);
+            const state = await readUsage(home);
+            expect(state.reservations).toHaveLength(0);
+            expect(state.current_usd).toBeGreaterThan(0);
+        });
+        it("is idempotent -- second commit on same token is a no-op", async () => {
+            const tok = (await reserve({
+                provider: "anthropic",
+                model: "claude-3-5-haiku-latest",
+                estInputTokens: 10_000,
+                estOutputTokens: 5_000,
+                homeOverride: home,
+            }));
+            await commit(tok, 8_000, 4_000, home);
+            const stateAfterFirst = await readUsage(home);
+            await commit(tok, 8_000, 4_000, home);
+            const stateAfterSecond = await readUsage(home);
+            expect(stateAfterSecond.current_usd).toBe(stateAfterFirst.current_usd);
+        });
+    });
+    describe("release()", () => {
+        it("removes reservation without committing actual cost", async () => {
+            const tok = (await reserve({
+                provider: "anthropic",
+                model: "claude-3-5-haiku-latest",
+                estInputTokens: 10_000,
+                estOutputTokens: 5_000,
+                homeOverride: home,
+            }));
+            await release(tok, home);
+            const state = await readUsage(home);
+            expect(state.reservations).toHaveLength(0);
+            expect(state.current_usd).toBe(0);
+        });
+    });
+    describe("Pitfall 5: try/finally release pattern", () => {
+        it("reserve -> throw -> finally release cleans up reservation", async () => {
+            let tok;
+            try {
+                tok = (await reserve({
+                    provider: "anthropic",
+                    model: "claude-3-5-haiku-latest",
+                    estInputTokens: 10_000,
+                    estOutputTokens: 5_000,
+                    homeOverride: home,
+                }));
+                // Simulate an abort
+                throw new Error("stream aborted");
+            }
+            catch {
+                // expected
+            }
+            finally {
+                if (tok)
+                    await release(tok, home);
+            }
+            const state = await readUsage(home);
+            expect(state.reservations).toHaveLength(0);
+            expect(state.current_usd).toBe(0);
+        });
+    });
+    describe("subscribeThresholds integration", () => {
+        let unsub;
+        afterEach(() => {
+            if (unsub)
+                unsub();
+        });
+        it("fires 80% threshold event when commit pushes past boundary", async () => {
+            // Use a very small cap so haiku costs are meaningful
+            home = await makeTmpHome(0.01); // $0.01 cap
+            const events = [];
+            unsub = subscribeThresholds((e) => events.push(e));
+            // Reserve with haiku: 100k input + 25k output ~ $0.18 >> $0.01 cap
+            // Use smaller tokens to stay under cap for reservation
+            const tok = (await reserve({
+                provider: "anthropic",
+                model: "claude-3-5-haiku-latest",
+                estInputTokens: 1_000,
+                estOutputTokens: 500,
+                homeOverride: home,
+            }));
+            // Commit with actual tokens that push past 50% and 80%
+            // haiku: $0.80/M input, $4.00/M output
+            // 1000 in + 500 out = $0.0008 + $0.002 = $0.0028
+            // $0.0028 / $0.01 = 28% -- not enough for 50%
+            // Let's use a bigger cap scenario
+            await release(tok, home);
+            // Re-create home with better numbers
+            home = await makeTmpHome(0.005); // $0.005 cap
+            const tok2 = (await reserve({
+                provider: "anthropic",
+                model: "claude-3-5-haiku-latest",
+                estInputTokens: 1_000,
+                estOutputTokens: 500,
+                homeOverride: home,
+            }));
+            // Commit: 1000 in + 500 out = $0.0028
+            // $0.0028 / $0.005 = 56% -- should fire 50% threshold
+            await commit(tok2, 1_000, 500, home);
+            expect(events.length).toBeGreaterThanOrEqual(1);
+            expect(events.some((e) => e.level === 50)).toBe(true);
+        });
+    });
+});
+//# sourceMappingURL=ledger.test.js.map

package/dist/usage/ledger.test.js.map

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

package/dist/usage/midstream.d.ts

@@ -0,0 +1,24 @@
+/**
+ * src/usage/midstream.ts
+ *
+ * Mid-stream policy for USAGE-05.
+ * In-flight stream finishes after threshold breach; next reservation refused.
+ * Acceptable single-stream overshoot ~101%.
+ *
+ * Subscribes to threshold events: {level:100} sets refuseNext=true.
+ */
+export declare const midstreamPolicy: {
+    /** Whether the next stream reservation should be refused. */
+    refuseNext(): boolean;
+    /** Force refuse (called when downgrade chain exhausted). */
+    forceRefuseNext(): void;
+    /** Reset state — for tests and month rollover. */
+    clear(): void;
+    /** Current cap percentage from latest threshold event. */
+    currentPct(): number;
+    /**
+     * In-flight stream may finish — caller checks BEFORE starting a new stream.
+     * Always returns true: once a stream is in-flight, it completes.
+     */
+    isStreamFinishAllowed(): boolean;
+};

package/dist/usage/midstream.js

@@ -0,0 +1,45 @@
+/**
+ * src/usage/midstream.ts
+ *
+ * Mid-stream policy for USAGE-05.
+ * In-flight stream finishes after threshold breach; next reservation refused.
+ * Acceptable single-stream overshoot ~101%.
+ *
+ * Subscribes to threshold events: {level:100} sets refuseNext=true.
+ */
+import { subscribeThresholds } from "./thresholds.js";
+let _refuseNext = false;
+let _capPct = 0;
+// Subscribe once at module load
+subscribeThresholds((ev) => {
+    _capPct = ev.current_pct;
+    if (ev.level === 100)
+        _refuseNext = true;
+});
+export const midstreamPolicy = {
+    /** Whether the next stream reservation should be refused. */
+    refuseNext() {
+        return _refuseNext;
+    },
+    /** Force refuse (called when downgrade chain exhausted). */
+    forceRefuseNext() {
+        _refuseNext = true;
+    },
+    /** Reset state — for tests and month rollover. */
+    clear() {
+        _refuseNext = false;
+        _capPct = 0;
+    },
+    /** Current cap percentage from latest threshold event. */
+    currentPct() {
+        return _capPct;
+    },
+    /**
+     * In-flight stream may finish — caller checks BEFORE starting a new stream.
+     * Always returns true: once a stream is in-flight, it completes.
+     */
+    isStreamFinishAllowed() {
+        return true;
+    },
+};
+//# sourceMappingURL=midstream.js.map

package/dist/usage/midstream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"midstream.js","sourceRoot":"","sources":["../../src/usage/midstream.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD,IAAI,WAAW,GAAG,KAAK,CAAC;AACxB,IAAI,OAAO,GAAG,CAAC,CAAC;AAEhB,gCAAgC;AAChC,mBAAmB,CAAC,CAAC,EAAE,EAAE,EAAE;IACzB,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC;IACzB,IAAI,EAAE,CAAC,KAAK,KAAK,GAAG;QAAE,WAAW,GAAG,IAAI,CAAC;AAC3C,CAAC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,6DAA6D;IAC7D,UAAU;QACR,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,4DAA4D;IAC5D,eAAe;QACb,WAAW,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,kDAAkD;IAClD,KAAK;QACH,WAAW,GAAG,KAAK,CAAC;QACpB,OAAO,GAAG,CAAC,CAAC;IACd,CAAC;IAED,0DAA0D;IAC1D,UAAU;QACR,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;OAGG;IACH,qBAAqB;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;CACF,CAAC"}

package/dist/usage/midstream.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/usage/midstream.test.js

@@ -0,0 +1,47 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { midstreamPolicy } from "./midstream.js";
+import { emit } from "./thresholds.js";
+describe("midstreamPolicy", () => {
+    beforeEach(() => {
+        midstreamPolicy.clear();
+    });
+    it("refuseNext() is false initially", () => {
+        expect(midstreamPolicy.refuseNext()).toBe(false);
+    });
+    it("refuseNext() flips to true after {level:100} threshold event", () => {
+        const ev = {
+            level: 100,
+            current_pct: 100,
+            current_usd: 15,
+            cap_usd: 15,
+            atMs: Date.now(),
+        };
+        emit(ev);
+        expect(midstreamPolicy.refuseNext()).toBe(true);
+    });
+    it("does NOT flip on {level:50} or {level:80}", () => {
+        emit({ level: 50, current_pct: 50, current_usd: 7.5, cap_usd: 15, atMs: Date.now() });
+        expect(midstreamPolicy.refuseNext()).toBe(false);
+        emit({ level: 80, current_pct: 80, current_usd: 12, cap_usd: 15, atMs: Date.now() });
+        expect(midstreamPolicy.refuseNext()).toBe(false);
+    });
+    it("isStreamFinishAllowed() always returns true (in-flight finishes)", () => {
+        expect(midstreamPolicy.isStreamFinishAllowed()).toBe(true);
+        // Even after 100% breach
+        emit({ level: 100, current_pct: 101, current_usd: 15.15, cap_usd: 15, atMs: Date.now() });
+        expect(midstreamPolicy.isStreamFinishAllowed()).toBe(true);
+    });
+    it("currentPct() tracks the latest threshold event pct", () => {
+        expect(midstreamPolicy.currentPct()).toBe(0);
+        emit({ level: 50, current_pct: 52.3, current_usd: 7.8, cap_usd: 15, atMs: Date.now() });
+        expect(midstreamPolicy.currentPct()).toBeCloseTo(52.3);
+    });
+    it("clear() resets state (for tests + month rollover)", () => {
+        midstreamPolicy.forceRefuseNext();
+        expect(midstreamPolicy.refuseNext()).toBe(true);
+        midstreamPolicy.clear();
+        expect(midstreamPolicy.refuseNext()).toBe(false);
+        expect(midstreamPolicy.currentPct()).toBe(0);
+    });
+});
+//# sourceMappingURL=midstream.test.js.map

package/dist/usage/midstream.test.js.map

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

package/dist/usage/thresholds.d.ts

@@ -0,0 +1,38 @@
+/**
+ * src/usage/thresholds.ts
+ *
+ * Threshold event system for USAGE-02.
+ * Fires at 50/80/100% of monthly cap crossing.
+ * Events are deduplicated per month via thresholds_fired_this_month in UsageState.
+ *
+ * Plan 06 (status bar) and Plan 05 (downgrade chain) consume these events.
+ */
+import type { ThresholdEvent } from "./types.js";
+type Listener = (e: ThresholdEvent) => void;
+/**
+ * Subscribe to threshold crossing events.
+ * Returns an unsubscribe function.
+ */
+export declare function subscribeThresholds(fn: Listener): () => void;
+/**
+ * Emit a threshold event to all subscribers.
+ * Called by ledger.ts commit() after lock release.
+ */
+export declare function emit(e: ThresholdEvent): void;
+export interface EvalArgs {
+    prevUsd: number;
+    nextUsd: number;
+    capUsd: number;
+    firedThisMonth: number[];
+}
+export interface EvalResult {
+    events: ThresholdEvent[];
+    nextFired: number[];
+}
+/**
+ * Evaluate which threshold boundaries were crossed.
+ * Returns events to emit and the updated fired-this-month array.
+ * Pure function -- no side effects.
+ */
+export declare function evaluateThresholds(args: EvalArgs): EvalResult;
+export {};

package/dist/usage/thresholds.js

@@ -0,0 +1,54 @@
+/**
+ * src/usage/thresholds.ts
+ *
+ * Threshold event system for USAGE-02.
+ * Fires at 50/80/100% of monthly cap crossing.
+ * Events are deduplicated per month via thresholds_fired_this_month in UsageState.
+ *
+ * Plan 06 (status bar) and Plan 05 (downgrade chain) consume these events.
+ */
+const listeners = new Set();
+/**
+ * Subscribe to threshold crossing events.
+ * Returns an unsubscribe function.
+ */
+export function subscribeThresholds(fn) {
+    listeners.add(fn);
+    return () => {
+        listeners.delete(fn);
+    };
+}
+/**
+ * Emit a threshold event to all subscribers.
+ * Called by ledger.ts commit() after lock release.
+ */
+export function emit(e) {
+    for (const l of listeners)
+        l(e);
+}
+const LEVELS = [50, 80, 100];
+/**
+ * Evaluate which threshold boundaries were crossed.
+ * Returns events to emit and the updated fired-this-month array.
+ * Pure function -- no side effects.
+ */
+export function evaluateThresholds(args) {
+    const out = [];
+    const nextFired = [...args.firedThisMonth];
+    for (const lv of LEVELS) {
+        const boundary = (args.capUsd * lv) / 100;
+        if (args.prevUsd < boundary && args.nextUsd >= boundary && !nextFired.includes(lv)) {
+            const ev = {
+                level: lv,
+                current_pct: (args.nextUsd / args.capUsd) * 100,
+                current_usd: args.nextUsd,
+                cap_usd: args.capUsd,
+                atMs: Date.now(),
+            };
+            out.push(ev);
+            nextFired.push(lv);
+        }
+    }
+    return { events: out, nextFired };
+}
+//# sourceMappingURL=thresholds.js.map

package/dist/usage/thresholds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thresholds.js","sourceRoot":"","sources":["../../src/usage/thresholds.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,SAAS,GAAG,IAAI,GAAG,EAAY,CAAC;AAEtC;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAAY;IAC9C,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAClB,OAAO,GAAG,EAAE;QACV,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACvB,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,IAAI,CAAC,CAAiB;IACpC,KAAK,MAAM,CAAC,IAAI,SAAS;QAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,MAAM,GAAqB,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;AAc/C;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAc;IAC/C,MAAM,GAAG,GAAqB,EAAE,CAAC;IACjC,MAAM,SAAS,GAAG,CAAC,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC;IAE3C,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;QACxB,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,GAAG,CAAC;QAC1C,IAAI,IAAI,CAAC,OAAO,GAAG,QAAQ,IAAI,IAAI,CAAC,OAAO,IAAI,QAAQ,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YACnF,MAAM,EAAE,GAAmB;gBACzB,KAAK,EAAE,EAAE;gBACT,WAAW,EAAE,CAAC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,GAAG;gBAC/C,WAAW,EAAE,IAAI,CAAC,OAAO;gBACzB,OAAO,EAAE,IAAI,CAAC,MAAM;gBACpB,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE;aACjB,CAAC;YACF,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACb,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC;AACpC,CAAC"}

package/dist/usage/thresholds.test.d.ts

@@ -0,0 +1 @@
+export {};