@usagekit/store 0.1.0 → 0.4.0

package/dist/conformance/reads.js

@@ -15,7 +15,7 @@ export function readsTests(factory, capabilities) {
             groupBy: ["provider"],
             ...overrides,
         });
-        const settled = async (r = receipt(), principal = "u1", provider = "search") => {
+        const settled = async (r = receipt(), principal = "u1", provider = "search", overrides = {}) => {
             const result = await f.store.reserve(input({
                 scope: {
                     namespace: "test",
@@ -23,9 +23,11 @@ export function readsTests(factory, capabilities) {
                     connection: "c1",
                     group: "g1",
                     accessCredential: { kind: "api_key", id: "k1" },
+                    tags: ["t1"],
                 },
                 platformPools: ["p1"],
                 provider,
+                ...overrides,
             }));
             if (result.outcome !== "reserved")
                 throw new Error("fixture");
@@ -52,6 +54,8 @@ export function readsTests(factory, capabilities) {
             "day",
             "access_credential",
             "platform_pool",
+            "funding_source",
+            "tag",
         ])("group by %s uses only requested dimensions", async (dim) => {
             await settled();
             const page = await f.store.aggregate(query({ groupBy: [dim] }));
@@ -59,6 +63,65 @@ export function readsTests(factory, capabilities) {
             expect(Object.keys(page.rows[0].dimensions)).toEqual([dim]);
             expect(page.rows[0].measurements[0].quantity?.value).toBe(1n);
         });
+        const cost = (units) => receipt({ cost: { certainty: "measured", money: { units, currency: "USD" } } });
+        const tagged = (tags) => ({
+            scope: {
+                namespace: "test",
+                principal: "u1",
+                connection: "c1",
+                ...(tags ? { tags } : {}),
+            },
+        });
+        test("funding source totals equal the sum of their operations", async () => {
+            await settled(cost(1n));
+            await settled(cost(2n));
+            await settled(cost(4n), "u1", "search", { fundingSource: "platform", costOwner: "platform" });
+            const page = await f.store.aggregate(query({ groupBy: ["funding_source"] }));
+            expect(page.rows).toEqual([
+                expect.objectContaining({
+                    dimensions: { funding_source: "byok" },
+                    fundingSource: "byok",
+                    cost: { certainty: "measured", money: { units: 3n, currency: "USD" } },
+                    measurements: [{ unit: "requests", certainty: "measured", quantity: quantity(2n) }],
+                }),
+                expect.objectContaining({
+                    dimensions: { funding_source: "platform" },
+                    fundingSource: "platform",
+                    cost: { certainty: "measured", money: { units: 4n, currency: "USD" } },
+                }),
+            ]);
+        });
+        test("tag rows count a two-tag operation twice, so they are not additive across tags", async () => {
+            await settled(cost(3n), "u1", "search", tagged(["a", "b"]));
+            await settled(cost(5n), "u1", "search", tagged(undefined));
+            const page = await f.store.aggregate(query({ groupBy: ["tag"] }));
+            expect(page.rows.map((r) => [r.dimensions.tag, r.cost.money?.units])).toEqual([
+                ["", 5n],
+                ["a", 3n],
+                ["b", 3n],
+            ]);
+            expect((await f.store.aggregate(query({ groupBy: ["provider"] }))).rows[0]).toMatchObject({
+                cost: { money: { units: 8n } },
+            });
+        });
+        test.each(["funding_source", "tag"])("cursor pagination is stable when grouping by %s", async (dim) => {
+            await settled(cost(1n), "u1", "search", tagged(["a", "b"]));
+            await settled(cost(2n), "u1", "search", {
+                ...tagged(["c"]),
+                fundingSource: "platform",
+                costOwner: "platform",
+            });
+            const all = await f.store.aggregate(query({ groupBy: [dim, "connection"] }));
+            const pages = [];
+            let cursor;
+            do {
+                const page = await f.store.aggregate(query({ groupBy: [dim, "connection"], limit: 1, ...(cursor ? { cursor } : {}) }));
+                pages.push(...page.rows);
+                cursor = page.nextCursor;
+            } while (cursor);
+            expect(pages).toEqual(all.rows);
+            expect(pages.length).toBe(dim === "tag" ? 3 : 2);
+        });
         test("late receipt groups by occurrence; corrected history is not double-counted", async () => {
             const r = receipt({ occurredAt: "2026-09-02T10:00:00.000Z" });
             const op = await settled(r);
@@ -129,6 +192,7 @@ export function readsTests(factory, capabilities) {
                 accessCredential: { kind: "api_key", id: "k1" },
             },
             { kind: "platform_pool", namespace: "test", poolId: "p1" },
+            { kind: "tag", namespace: "test", tag: "t1" },
         ];
         test.each(scopes)("defined budgets are exact: $kind", async (scope) => {
             const b = budget({ scope });

package/dist/conformance/reserve.js

@@ -29,8 +29,8 @@ export function reserveTests(factory) {
             { costOwner: "other" },
             { creditAccountRef: "wallet" },
             { customerPriceVersion: "v2" },
-            { surface: "programmatic" },
-            { source: "mcp" },
+            { surface: "programmatic", source: "api" },
+            { source: "worker" },
             { provider: "other" },
             { operation: "other" },
             { estimate: [quantity(2n)] },

package/dist/conformance/suite.js

@@ -2,21 +2,29 @@ import { describe, afterAll } from "vitest";
 import { expirationTests } from "./expiration.js";
 import { reserveTests } from "./reserve.js";
 import { admissionTests } from "./admission.js";
+import { alertTests } from "./alerts.js";
+import { tagTests } from "./tags.js";
 import { dispatchTests } from "./dispatch.js";
 import { authorityTests } from "./authority.js";
 import { recoveryTests } from "./recovery.js";
 import { readsTests } from "./reads.js";
+import { operationsTests } from "./operations.js";
 import { propertyTests } from "./properties.js";
 import { capabilityTests } from "./capabilities.js";
+import { counterTests } from "./counters.js";
 export function runStoreConformance(factory, capabilities) {
     describe("store conformance", () => {
         reserveTests(factory);
         expirationTests(factory);
         admissionTests(factory);
+        alertTests(factory);
+        tagTests(factory);
         dispatchTests(factory);
         authorityTests(factory);
         recoveryTests(factory);
         readsTests(factory, capabilities);
+        operationsTests(factory);
+        counterTests(factory);
         propertyTests(factory);
         capabilityTests(factory, capabilities);
         afterAll(() => console.info("Skipped guarantees: " +

package/dist/conformance/tags.d.ts

@@ -0,0 +1,2 @@
+import type { StoreFactory } from "./factory.js";
+export declare function tagTests(factory: StoreFactory): void;

package/dist/conformance/tags.js

@@ -0,0 +1,101 @@
+import { beforeEach, afterEach, describe, expect, test } from "vitest";
+import { input, budget, quantity } from "./helpers.js";
+export function tagTests(factory) {
+    describe("connection tags", () => {
+        let f;
+        beforeEach(async () => {
+            f = await factory();
+        });
+        afterEach(async () => f.close());
+        const tagged = (tags, principal = "u1") => input({
+            scope: {
+                namespace: "test",
+                principal,
+                connection: `c_${principal}`,
+                ...(tags ? { tags } : {}),
+            },
+        });
+        const prod = { kind: "tag", namespace: "test", tag: "prod" };
+        test("a tag budget spans principals and blocks the call that exhausts it", async () => {
+            const b = budget({ scope: prod, limit: quantity(2n) });
+            f.budgets.push(b);
+            expect(await f.store.reserve(tagged(["prod"], "u1"))).toMatchObject({ outcome: "reserved" });
+            expect(await f.store.reserve(tagged(["eu", "prod"], "u2"))).toMatchObject({
+                outcome: "reserved",
+                operation: { budgetEpochs: [{ budgetId: b.id }] },
+            });
+            expect(await f.store.reserve(tagged(["prod"], "u3"))).toMatchObject({
+                outcome: "exceeded",
+                exceeded: { budget: { id: b.id } },
+            });
+        });
+        test("operations without the tag are not bounded by tag budgets", async () => {
+            f.budgets.push(budget({ scope: prod, limit: quantity(0n) }));
+            expect(await f.store.reserve(tagged(undefined))).toMatchObject({
+                outcome: "reserved",
+                operation: { budgetEpochs: [] },
+            });
+            expect(await f.store.reserve(tagged(["staging"]))).toMatchObject({
+                outcome: "reserved",
+                operation: { budgetEpochs: [] },
+            });
+            expect(await f.store.reserve(tagged(["prod"]))).toMatchObject({ outcome: "exceeded" });
+        });
+        test("tag budgets sort after group and before connection in the default order", async () => {
+            const tag = budget({ scope: prod, limit: quantity(0n) }), connection = budget({
+                scope: { kind: "connection", namespace: "test", connection: "c_u1" },
+                limit: quantity(0n),
+            }), group = budget({
+                scope: { kind: "group", namespace: "test", group: "g1" },
+                limit: quantity(0n),
+            });
+            f.budgets.push(connection, tag);
+            expect(await f.store.reserve(tagged(["prod"]))).toMatchObject({
+                exceeded: { budget: { id: tag.id } },
+            });
+            f.budgets.push(group);
+            const i = tagged(["prod"]);
+            i.scope.group = "g1";
+            expect(await f.store.reserve(i)).toMatchObject({ exceeded: { budget: { id: group.id } } });
+        });
+        test.each([
+            { name: "empty list", tags: [] },
+            { name: "empty tag", tags: [""] },
+            { name: "upper case", tags: ["Prod"] },
+            { name: "leading punctuation", tags: ["-prod"] },
+            { name: "whitespace", tags: ["pro d"] },
+            { name: "duplicate", tags: ["prod", "prod"] },
+            { name: "too long", tags: ["a".repeat(65)] },
+            { name: "too many", tags: Array.from({ length: 17 }, (_, n) => `t${n}`) },
+        ])("invalid tags are a validation failure: $name", async ({ tags }) => {
+            await expect(f.store.reserve(tagged(tags))).rejects.toThrow("InvalidInput");
+        });
+        test("tags are stored sorted and unique up to the limits", async () => {
+            const tags = ["z9", "a", "team-x", "eu:west", "v1.2", "under_score"];
+            const r = await f.store.reserve(tagged(tags));
+            expect(r).toMatchObject({
+                outcome: "reserved",
+                operation: { scope: { tags: [...tags].sort() } },
+            });
+            const sixteen = Array.from({ length: 16 }, (_, n) => `t${String(n).padStart(2, "0")}`);
+            expect(await f.store.reserve(tagged(sixteen))).toMatchObject({ outcome: "reserved" });
+            expect(await f.store.reserve(tagged(["a".repeat(64)]))).toMatchObject({
+                outcome: "reserved",
+            });
+        });
+        test("tags are attribution: replay with other tags keeps the first reservation's tags", async () => {
+            const i = tagged(["b", "a"]);
+            const first = await f.store.reserve(i);
+            if (first.outcome !== "reserved")
+                throw new Error("fixture");
+            expect(first.operation.scope.tags).toEqual(["a", "b"]);
+            const replay = await f.store.reserve({ ...i, scope: { ...i.scope, tags: ["c"] } });
+            expect(replay).toEqual({ ...first, replayed: true });
+            const { tags: _, ...untagged } = i.scope;
+            expect(await f.store.reserve({ ...i, scope: untagged })).toEqual({
+                ...first,
+                replayed: true,
+            });
+        });
+    });
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { AdmissionPolicy } from "@usagekit/core";
-import type { ExpireReservationsInput, ExpireReservationsResult, Budget, ApplicableBudgetsQuery, BudgetStatus, DefinedBudgetsQuery, CorrectionInput, DispatchGrant, DispatchIntentInput, LeaseRenewal, LeaseRenewalInput, Operation, OperationRef, RecoveryClaim, RecoveryClaimInput, ReleaseInput, ReleaseResult, ReserveInput, ReserveResult, SettleInput, SettleResult, UsagePage, UsageQuery } from "@usagekit/core";
+import type { ExpireReservationsInput, ExpireReservationsResult, Budget, ApplicableBudgetsQuery, BudgetStatus, DefinedBudgetsQuery, CorrectionInput, DispatchGrant, DispatchIntentInput, LeaseRenewal, LeaseRenewalInput, Operation, OperationRef, RecoveryClaim, RecoveryClaimInput, ReleaseInput, ReleaseResult, ReserveInput, ReserveResult, SettleInput, SettleResult, UsagePage, UsageQuery, OperationsQuery, OperationsPage, CountRequestInput, CountRequestResult, RequestCountsQuery, RequestCountsPage } from "@usagekit/core";
 /**
  * Authorization is the Meter's job; atomic condition checks are the Store's job.
  * Store does not take AccessContext. Meter resolves applicable budgets, funding and price policy.
@@ -20,8 +20,12 @@ export interface Store {
     settle(input: SettleInput): Promise<SettleResult>;
     correct(input: CorrectionInput): Promise<SettleResult>;
     releaseUndispatched(input: ReleaseInput): Promise<ReleaseResult>;
+    /** Atomic, replay-safe count of one non-operation request; never reserves or touches budgets. */
+    countRequest(input: CountRequestInput): Promise<CountRequestResult>;
     getOperation(input: OperationRef): Promise<Operation | null>;
     aggregate(query: UsageQuery): Promise<UsagePage>;
+    listOperations(query: OperationsQuery): Promise<OperationsPage>;
+    requestCounts(query: RequestCountsQuery): Promise<RequestCountsPage>;
     definedBudgets(query: DefinedBudgetsQuery): Promise<readonly Budget[]>;
     applicableBudgets(query: ApplicableBudgetsQuery): Promise<readonly BudgetStatus[]>;
 }
@@ -29,3 +33,6 @@ export { createMemoryStore } from "./memory/memory-store.js";
 export { createManualClock } from "./clock.js";
 export type { Clock, ManualClock } from "./clock.js";
 export { InvalidInput } from "./memory/state.js";
+export { validateBudget, reachedAlerts, alertKey } from "./memory/admission.js";
+export { validateCountRequest, validateRequestCountsQuery, countIdentity, countRows, bucketOf, requestCountDimensions, } from "./memory/counters.js";
+export type { CountBucket } from "./memory/counters.js";

package/dist/index.js

@@ -1,3 +1,5 @@
 export { createMemoryStore } from "./memory/memory-store.js";
 export { createManualClock } from "./clock.js";
 export { InvalidInput } from "./memory/state.js";
+export { validateBudget, reachedAlerts, alertKey } from "./memory/admission.js";
+export { validateCountRequest, validateRequestCountsQuery, countIdentity, countRows, bucketOf, requestCountDimensions, } from "./memory/counters.js";

package/dist/memory/admission.d.ts

@@ -1,13 +1,36 @@
 import type { AdmissionPolicy } from "@usagekit/core";
-import type { Budget, ReserveInput, ApplicableBudgetsQuery, Quantity, BudgetStatus, AllowanceExceeded, Operation } from "@usagekit/core";
+import type { Budget, BudgetAlert, BudgetAlertCrossed, ReserveInput, ApplicableBudgetsQuery, Quantity, BudgetStatus, AllowanceExceeded, Operation } from "@usagekit/core";
 import type { State } from "./state.js";
-export declare function currentBudgets(s: State): Budget[];
-export declare function matches(b: Budget, i: Pick<ReserveInput, "scope" | "surface" | "platformPools">): boolean;
 export declare function plus(a: Quantity, b: Quantity): Quantity;
 export declare const greater: (a: Quantity, b: Quantity) => boolean;
+/** Absolute threshold of one alert; percent thresholds need the limit. */
+export declare function alertThreshold(b: Budget, at: BudgetAlert["at"]): Quantity;
+export declare const alertKey: (at: BudgetAlert["at"]) => string;
+/** Thresholds at or below used plus reserved, in declaration order. Callers drop recorded ones. */
+export declare function reachedAlerts(b: Budget, used: Quantity, reserved: Quantity): BudgetAlert["at"][];
+/** Definition rules every adapter applies before a budget takes part in admission. */
+export declare function validateBudget(b: Budget): void;
+export declare function currentBudgets(s: State): Budget[];
+/** The budget version an operation snapshotted, or its current definition when that version is gone. */
+export declare function budgetAt(s: State, namespace: string, epoch: Operation["budgetEpochs"][number]): Budget | undefined;
+export declare function matches(b: Budget, i: Pick<ReserveInput, "scope" | "surface" | "platformPools"> & Pick<ApplicableBudgetsQuery, "source">): boolean;
 export declare function effective(op: Operation): import("@usagekit/core").Receipt | undefined;
+/** Settled use and outstanding reservations of one budget epoch. */
+export declare function usage(s: State, b: Budget, epoch: string): {
+    used: Quantity;
+    reserved: Quantity;
+};
 export declare function status(s: State, b: Budget): BudgetStatus;
 export declare function applicable(s: State, i: ApplicableBudgetsQuery): BudgetStatus[];
+/** Which bound a projected total crosses and whether that denies admission. */
+export declare function crossing(b: Budget, total: Quantity): {
+    boundary: AllowanceExceeded["boundary"];
+    denied: boolean;
+} | null;
+/** Records unseen crossings atomically with the calling command and returns only those. */
+export declare function recordAlerts(s: State, namespace: string, reached: readonly BudgetAlertCrossed[]): BudgetAlertCrossed[];
+/** Crossings reached by an operation's current figures in its snapshotted epochs. */
+export declare function reachedBySettlement(s: State, op: Operation): BudgetAlertCrossed[];
 export declare function admission(s: State, i: ReserveInput, policy?: AdmissionPolicy): {
     invalid: string;
     warnings: AllowanceExceeded[];
@@ -18,6 +41,7 @@ export declare function admission(s: State, i: ReserveInput, policy?: AdmissionP
         startsAt: string;
         endsAt: string | null;
     }[];
+    alerts: BudgetAlertCrossed[];
     exceeded?: never;
 } | {
     exceeded: AllowanceExceeded;
@@ -29,6 +53,7 @@ export declare function admission(s: State, i: ReserveInput, policy?: AdmissionP
         startsAt: string;
         endsAt: string | null;
     }[];
+    alerts: BudgetAlertCrossed[];
     invalid?: never;
 } | {
     warnings: AllowanceExceeded[];
@@ -39,6 +64,7 @@ export declare function admission(s: State, i: ReserveInput, policy?: AdmissionP
         startsAt: string;
         endsAt: string | null;
     }[];
+    alerts: BudgetAlertCrossed[];
     invalid?: never;
     exceeded?: never;
 };

package/dist/memory/admission.js

@@ -1,6 +1,62 @@
-import { defaultBudgetOrder } from "@usagekit/core";
+import { defaultBudgetOrder, surfaceMatches } from "@usagekit/core";
 import { resolveWindow } from "@usagekit/core";
-import { canonical } from "./state.js";
+import { canonical, InvalidInput, validateQuantity } from "./state.js";
+export function plus(a, b) {
+    const scale = Math.max(a.scale, b.scale);
+    return {
+        unit: a.unit,
+        scale,
+        value: a.value * 10n ** BigInt(scale - a.scale) + b.value * 10n ** BigInt(scale - b.scale),
+    };
+}
+export const greater = (a, b) => a.value * 10n ** BigInt(b.scale) > b.value * 10n ** BigInt(a.scale);
+/** Absolute threshold of one alert; percent thresholds need the limit. */
+export function alertThreshold(b, at) {
+    if (!("percent" in at))
+        return at;
+    return { unit: b.unit, value: b.limit.value * BigInt(at.percent), scale: b.limit.scale + 2 };
+}
+export const alertKey = (at) => canonical(at);
+/** Thresholds at or below used plus reserved, in declaration order. Callers drop recorded ones. */
+export function reachedAlerts(b, used, reserved) {
+    const total = plus(used, reserved);
+    return (b.alerts ?? []).map((a) => a.at).filter((at) => !greater(alertThreshold(b, at), total));
+}
+/** Definition rules every adapter applies before a budget takes part in admission. */
+export function validateBudget(b) {
+    if (b.onExceed !== "block" && b.onExceed !== "allow")
+        throw new InvalidInput("budget.onExceed", "expected block or allow");
+    if (b.limit)
+        validateQuantity(b.limit);
+    if (b.hardLimit !== undefined) {
+        validateQuantity(b.hardLimit);
+        if (b.onExceed !== "allow")
+            throw new InvalidInput("budget.hardLimit", "requires onExceed allow");
+        if (!b.limit || b.hardLimit.unit !== b.limit.unit || !greater(b.hardLimit, b.limit))
+            throw new InvalidInput("budget.hardLimit", "must exceed limit in the same unit");
+    }
+    const alerts = b.alerts ?? [];
+    if (alerts.length > 8)
+        throw new InvalidInput("budget.alerts", "at most eight thresholds");
+    let previous = null;
+    for (const { at } of alerts) {
+        if ("percent" in at) {
+            if (!Number.isSafeInteger(at.percent) || at.percent < 1 || at.percent > 100)
+                throw new InvalidInput("budget.alerts", "percent must be an integer from 1 to 100");
+            if (!b.limit)
+                throw new InvalidInput("budget.alerts", "percent requires a limit");
+        }
+        else {
+            validateQuantity(at);
+            if (at.unit !== b.unit)
+                throw new InvalidInput("budget.alerts", "unit must match the budget");
+        }
+        const threshold = alertThreshold(b, at);
+        if (previous && !greater(threshold, previous))
+            throw new InvalidInput("budget.alerts", "thresholds must ascend");
+        previous = threshold;
+    }
+}
 export function currentBudgets(s) {
     const map = new Map();
     for (const b of s.budgets) {
@@ -10,8 +66,14 @@ export function currentBudgets(s) {
     }
     return [...map.values()];
 }
+/** The budget version an operation snapshotted, or its current definition when that version is gone. */
+export function budgetAt(s, namespace, epoch) {
+    return (s.budgets.find((b) => b.scope.namespace === namespace &&
+        b.id === epoch.budgetId &&
+        b.version === epoch.budgetVersion) ?? currentBudgets(s).find((b) => b.scope.namespace === namespace && b.id === epoch.budgetId));
+}
 export function matches(b, i) {
-    if (b.scope.namespace !== i.scope.namespace || (b.surface !== "any" && b.surface !== i.surface))
+    if (b.scope.namespace !== i.scope.namespace || !surfaceMatches(b.surface, i.surface, i.source))
         return false;
     switch (b.scope.kind) {
         case "principal":
@@ -24,46 +86,41 @@ export function matches(b, i) {
             return canonical(b.scope.accessCredential) === canonical(i.scope.accessCredential);
         case "platform_pool":
             return i.platformPools?.includes(b.scope.poolId) ?? false;
+        case "tag":
+            return i.scope.tags?.includes(b.scope.tag) ?? false;
     }
 }
-export function plus(a, b) {
-    const scale = Math.max(a.scale, b.scale);
-    return {
-        unit: a.unit,
-        scale,
-        value: a.value * 10n ** BigInt(scale - a.scale) + b.value * 10n ** BigInt(scale - b.scale),
-    };
-}
-export const greater = (a, b) => a.value * 10n ** BigInt(b.scale) > b.value * 10n ** BigInt(a.scale);
 export function effective(op) {
     return [...op.receipts]
         .reverse()
         .find((r) => !op.receipts.some((next) => next.supersedes === r.id));
 }
-export function status(s, b) {
-    const epoch = resolveWindow(b.window, s.clock.now());
+/** Settled use and outstanding reservations of one budget epoch. */
+export function usage(s, b, epoch) {
+    const projected = s.readBudgetUsage?.(b, epoch);
+    if (projected)
+        return projected;
     let used = { value: 0n, scale: 0, unit: b.unit }, reserved = { ...used };
-    const projected = s.readBudgetUsage?.(b, epoch.epoch);
-    if (projected) {
-        used = projected.used;
-        reserved = projected.reserved;
-    }
-    else
-        for (const op of s.operations.values()) {
-            if (op.scope.namespace !== b.scope.namespace ||
-                !op.budgetEpochs.some((e) => e.budgetId === b.id && e.epoch === epoch.epoch))
-                continue;
-            if (op.state === "settled") {
-                const m = effective(op)?.measurements.find((m) => m.unit === b.unit);
-                if (m?.quantity)
-                    used = plus(used, m.quantity);
-            }
-            else if (op.state !== "released") {
-                const q = op.estimate.find((q) => q.unit === b.unit);
-                if (q)
-                    reserved = plus(reserved, q);
-            }
+    for (const op of s.operations.values()) {
+        if (op.scope.namespace !== b.scope.namespace ||
+            !op.budgetEpochs.some((e) => e.budgetId === b.id && e.epoch === epoch))
+            continue;
+        if (op.state === "settled") {
+            const m = effective(op)?.measurements.find((m) => m.unit === b.unit);
+            if (m?.quantity)
+                used = plus(used, m.quantity);
         }
+        else if (op.state !== "released") {
+            const q = op.estimate.find((q) => q.unit === b.unit);
+            if (q)
+                reserved = plus(reserved, q);
+        }
+    }
+    return { used, reserved };
+}
+export function status(s, b) {
+    const epoch = resolveWindow(b.window, s.clock.now());
+    const { used, reserved } = usage(s, b, epoch.epoch);
     const total = plus(used, reserved);
     const remaining = b.limit ? plus(b.limit, { ...total, value: -total.value }) : null;
     return { budget: b, epoch, used, reserved, remaining };
@@ -73,33 +130,77 @@ export function applicable(s, i) {
         .filter((b) => matches(b, i))
         .map((b) => status(s, b));
 }
+/** Which bound a projected total crosses and whether that denies admission. */
+export function crossing(b, total) {
+    if (!b.limit || !greater(total, b.limit))
+        return null;
+    if (b.onExceed === "block")
+        return { boundary: "limit", denied: true };
+    if (b.hardLimit && greater(total, b.hardLimit))
+        return { boundary: "hardLimit", denied: true };
+    return { boundary: "limit", denied: false };
+}
+const candidates = (b, epoch, used, reserved) => reachedAlerts(b, used, reserved).map((at) => ({
+    budgetId: b.id,
+    budgetVersion: b.version,
+    epoch,
+    at,
+    used,
+    reserved,
+}));
+/** Records unseen crossings atomically with the calling command and returns only those. */
+export function recordAlerts(s, namespace, reached) {
+    const recorded = [];
+    for (const a of reached) {
+        const k = canonical([namespace, a.budgetId, a.epoch, alertKey(a.at)]);
+        if (s.alerts.has(k))
+            continue;
+        s.alerts.add(k);
+        recorded.push(a);
+    }
+    return recorded;
+}
+/** Crossings reached by an operation's current figures in its snapshotted epochs. */
+export function reachedBySettlement(s, op) {
+    return op.budgetEpochs.flatMap((e) => {
+        const b = budgetAt(s, op.scope.namespace, e);
+        if (!b?.alerts?.length)
+            return [];
+        const { used, reserved } = usage(s, b, e.epoch);
+        return candidates(b, e.epoch, used, reserved);
+    });
+}
 export function admission(s, i, policy) {
     const order = policy?.budgetOrder ?? defaultBudgetOrder;
     const budgets = currentBudgets(s)
         .filter((b) => matches(b, i))
         .sort((a, b) => order.indexOf(a.scope.kind) - order.indexOf(b.scope.kind) || a.id.localeCompare(b.id));
-    const warnings = [], epochs = [];
+    const warnings = [], epochs = [], alerts = [];
+    budgets.forEach(validateBudget);
     for (const b of budgets) {
         const estimate = i.estimate.find((q) => q.unit === b.unit);
         if (!estimate)
-            return { invalid: b.unit, warnings, epochs };
+            return { invalid: b.unit, warnings, epochs, alerts };
     }
     for (const b of budgets) {
         const st = status(s, b);
         epochs.push({ budgetId: b.id, budgetVersion: b.version, ...st.epoch });
         const estimate = i.estimate.find((q) => q.unit === b.unit);
-        if (b.limit && greater(plus(plus(st.used, st.reserved), estimate), b.limit)) {
+        const reserved = plus(st.reserved, estimate), outcome = crossing(b, plus(st.used, reserved));
+        if (outcome) {
             const exceeded = {
                 code: "allowance_exceeded",
                 budget: b,
+                boundary: outcome.boundary,
                 used: st.used,
                 reserved: st.reserved,
                 resetsAt: st.epoch.endsAt,
             };
-            if (b.onExceed === "block")
-                return { exceeded, warnings, epochs };
+            if (outcome.denied)
+                return { exceeded, warnings, epochs, alerts };
             warnings.push(exceeded);
         }
+        alerts.push(...candidates(b, st.epoch.epoch, st.used, reserved));
     }
-    return { warnings, epochs };
+    return { warnings, epochs, alerts };
 }

package/dist/memory/commands.d.ts

@@ -1,7 +1,7 @@
 import type { AdmissionPolicy } from "@usagekit/core";
 import type { ReserveInput, ReserveResult, Operation } from "@usagekit/core";
 import type { State } from "./state.js";
-export declare function reserve(s: State, i: ReserveInput, policy?: AdmissionPolicy): ReserveResult;
+export declare function reserve(s: State, raw: ReserveInput, policy?: AdmissionPolicy): ReserveResult;
 import type { DispatchIntentInput, DispatchGrant, LeaseRenewalInput, LeaseRenewal } from "@usagekit/core";
 export declare function active(s: State, op: Operation): boolean;
 export declare function touch(s: State, op: Operation): void;

package/dist/memory/commands.js

@@ -1,10 +1,11 @@
-import { admission } from "./admission.js";
-import { copy, key, semantics, validateQuantity, InvalidInput } from "./state.js";
-export function reserve(s, i, policy) {
-    validTtl(i.reservationTtlMs ?? 300000, "reservationTtlMs");
-    i.estimate.forEach(validateQuantity);
-    if (new Set(i.estimate.map((q) => q.unit)).size !== i.estimate.length)
+import { admission, recordAlerts, reachedBySettlement } from "./admission.js";
+import { copy, key, semantics, validateQuantity, withNormalizedTags, InvalidInput, } from "./state.js";
+export function reserve(s, raw, policy) {
+    validTtl(raw.reservationTtlMs ?? 300000, "reservationTtlMs");
+    raw.estimate.forEach(validateQuantity);
+    if (new Set(raw.estimate.map((q) => q.unit)).size !== raw.estimate.length)
         throw new InvalidInput("estimate", "duplicate unit");
+    const i = withNormalizedTags(raw);
     expireReservations(s, { namespace: i.scope.namespace });
     const k = key(i.scope.namespace, i.operationId), existing = s.operations.get(k);
     if (existing)
@@ -13,9 +14,12 @@ export function reserve(s, i, policy) {
                 outcome: "reserved",
                 replayed: true,
                 warnings: copy(s.warnings.get(k) ?? []),
+                alerts: copy(s.reserveAlerts.get(k) ?? []),
                 operation: copy(existing),
             }
             : { outcome: "conflict", reason: "semantic_mismatch", operation: copy(existing) };
+    if (s.requestCommands?.has(k))
+        throw new InvalidInput("operationId", "already counted without a reservation");
     const check = admission(s, i, policy);
     if (check.invalid)
         return {
@@ -41,10 +45,13 @@ export function reserve(s, i, policy) {
     s.operations.set(k, operation);
     s.identities.set(k, semantics(i));
     s.warnings.set(k, copy(check.warnings));
+    const alerts = recordAlerts(s, i.scope.namespace, check.alerts);
+    s.reserveAlerts.set(k, copy(alerts));
     return {
         outcome: "reserved",
         replayed: false,
         warnings: copy(check.warnings),
+        alerts: copy(alerts),
         operation: copy(operation),
     };
 }
@@ -187,7 +194,13 @@ export function settle(s, i, correction = false) {
             : "settled";
     op.lease = null;
     touch(s, op);
-    const result = { outcome: "settled", replayed: false, operation: copy(op) };
+    const alerts = recordAlerts(s, op.scope.namespace, reachedBySettlement(s, op));
+    const result = {
+        outcome: "settled",
+        replayed: false,
+        operation: copy(op),
+        alerts: copy(alerts),
+    };
     s.commands.set(ck, { identity, result: copy(result) });
     return result;
 }