@usagekit/store 0.1.0 → 0.3.0

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 } 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.
@@ -22,6 +22,7 @@ export interface Store {
     releaseUndispatched(input: ReleaseInput): Promise<ReleaseResult>;
     getOperation(input: OperationRef): Promise<Operation | null>;
     aggregate(query: UsageQuery): Promise<UsagePage>;
+    listOperations(query: OperationsQuery): Promise<OperationsPage>;
     definedBudgets(query: DefinedBudgetsQuery): Promise<readonly Budget[]>;
     applicableBudgets(query: ApplicableBudgetsQuery): Promise<readonly BudgetStatus[]>;
 }
@@ -29,3 +30,4 @@ 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";

package/dist/index.js

@@ -1,3 +1,4 @@
 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";

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,6 +14,7 @@ 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) };
@@ -41,10 +43,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 +192,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;
 }

package/dist/memory/memory-store.js

@@ -1,4 +1,4 @@
-import { aggregate, definedBudgets, applicableBudgets } from "./reads.js";
+import { aggregate, definedBudgets, applicableBudgets, listOperations } from "./reads.js";
 import { copy, find } from "./state.js";
 import { reserve, intent, renew, settle, release, claim, expireReservations } from "./commands.js";
 export function createMemoryStore({ clock, budgets }) {
@@ -6,6 +6,8 @@ export function createMemoryStore({ clock, budgets }) {
         clock,
         budgets,
         warnings: new Map(),
+        reserveAlerts: new Map(),
+        alerts: new Set(),
         leaseKinds: new Map(),
         commands: new Map(),
         cursors: new Map(),
@@ -23,6 +25,7 @@ export function createMemoryStore({ clock, budgets }) {
         correct: async (i) => settle(state, i, true),
         releaseUndispatched: async (i) => release(state, i),
         aggregate: async (q) => aggregate(state, q),
+        listOperations: async (q) => listOperations(state, q),
         definedBudgets: async (q) => definedBudgets(state, q),
         applicableBudgets: async (q) => applicableBudgets(state, q),
     };

package/dist/memory/reads.d.ts

@@ -1,5 +1,7 @@
-import type { UsageQuery, UsagePage, DefinedBudgetsQuery, ApplicableBudgetsQuery } from "@usagekit/core";
+import type { UsageQuery, UsagePage, DefinedBudgetsQuery, ApplicableBudgetsQuery, OperationsQuery, OperationsPage } from "@usagekit/core";
 import type { State } from "./state.js";
 export declare const definedBudgets: (s: State, q: DefinedBudgetsQuery) => import("@usagekit/core").Budget[];
 export declare const applicableBudgets: (s: State, q: ApplicableBudgetsQuery) => import("@usagekit/core").BudgetStatus[];
 export declare function aggregate(s: State, q: UsageQuery): UsagePage;
+/** Mirrors aggregate: the first page fixes membership and order; pages return current records. */
+export declare function listOperations(s: State, q: OperationsQuery): OperationsPage;

package/dist/memory/reads.js

@@ -63,41 +63,50 @@ function rows(s, q) {
                     ? op.platformPools
                     : [""]
             : [""];
-        for (const pool of pools) {
-            const dimensions = {};
-            for (const dimension of q.groupBy) {
-                switch (dimension) {
-                    case "principal":
-                        dimensions[dimension] = op.scope.principal;
-                        break;
-                    case "connection":
-                        dimensions[dimension] = op.scope.connection;
-                        break;
-                    case "day":
-                        dimensions[dimension] = new Date(receipt.occurredAt).toISOString().slice(0, 10);
-                        break;
-                    case "access_credential":
-                        dimensions[dimension] = op.scope.accessCredential
-                            ? canonical([op.scope.accessCredential.kind, op.scope.accessCredential.id])
-                            : "";
-                        break;
-                    case "platform_pool":
-                        dimensions[dimension] = pool;
-                        break;
-                    default:
-                        dimensions[dimension] = op[dimension];
+        // Pool and tag rows explode per value; an operation without any contributes one empty row.
+        const tags = q.groupBy.includes("tag") && op.scope.tags?.length ? op.scope.tags : [""];
+        for (const pool of pools)
+            for (const tag of tags) {
+                const dimensions = {};
+                for (const dimension of q.groupBy) {
+                    switch (dimension) {
+                        case "principal":
+                            dimensions[dimension] = op.scope.principal;
+                            break;
+                        case "connection":
+                            dimensions[dimension] = op.scope.connection;
+                            break;
+                        case "day":
+                            dimensions[dimension] = new Date(receipt.occurredAt).toISOString().slice(0, 10);
+                            break;
+                        case "access_credential":
+                            dimensions[dimension] = op.scope.accessCredential
+                                ? canonical([op.scope.accessCredential.kind, op.scope.accessCredential.id])
+                                : "";
+                            break;
+                        case "platform_pool":
+                            dimensions[dimension] = pool;
+                            break;
+                        case "funding_source":
+                            dimensions[dimension] = op.fundingSource;
+                            break;
+                        case "tag":
+                            dimensions[dimension] = tag;
+                            break;
+                        default:
+                            dimensions[dimension] = op[dimension];
+                    }
                 }
+                const k = canonical([dimensions, op.fundingSource, op.costOwner]), prev = map.get(k), measurements = receipt.measurements.filter((m) => q.units.includes(m.unit));
+                map.set(k, {
+                    dimensions,
+                    fundingSource: op.fundingSource,
+                    costOwner: op.costOwner,
+                    measurements: combineMeasurements(prev?.measurements ?? [], measurements),
+                    cost: prev ? combineCost(prev.cost, receipt.cost) : copy(receipt.cost),
+                    unknownOperations: (prev?.unknownOperations ?? 0n) + (op.state === "pending" ? 1n : 0n),
+                });
             }
-            const k = canonical([dimensions, op.fundingSource, op.costOwner]), prev = map.get(k), measurements = receipt.measurements.filter((m) => q.units.includes(m.unit));
-            map.set(k, {
-                dimensions,
-                fundingSource: op.fundingSource,
-                costOwner: op.costOwner,
-                measurements: combineMeasurements(prev?.measurements ?? [], measurements),
-                cost: prev ? combineCost(prev.cost, receipt.cost) : copy(receipt.cost),
-                unknownOperations: (prev?.unknownOperations ?? 0n) + (op.state === "pending" ? 1n : 0n),
-            });
-        }
     }
     return [...map.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, r]) => r);
 }
@@ -129,3 +138,48 @@ export function aggregate(s, q) {
     }
     return page;
 }
+const byCreation = (a, b) => a.createdAt === b.createdAt
+    ? a.operationId < b.operationId
+        ? -1
+        : 1
+    : Date.parse(a.createdAt) - Date.parse(b.createdAt);
+/** Mirrors aggregate: the first page fixes membership and order; pages return current records. */
+export function listOperations(s, q) {
+    const { cursor, ...query } = q;
+    const identity = canonical(query), cursors = (s.operationCursors ??= new Map());
+    let snapshot;
+    if (cursor) {
+        snapshot = cursors.get(cursor);
+        if (!snapshot || snapshot.query !== identity)
+            throw new InvalidInput("cursor", "unknown cursor or query mismatch");
+    }
+    else {
+        const from = Date.parse(q.from), to = Date.parse(q.to);
+        const members = [...s.operations.values()]
+            .filter((op) => {
+            const created = Date.parse(op.createdAt);
+            return (inScope(op, q) &&
+                created >= from &&
+                created < to &&
+                (q.states === undefined || q.states.includes(op.state)));
+        })
+            .sort(byCreation);
+        snapshot = {
+            query: identity,
+            keys: members.map((op) => canonical([op.scope.namespace, op.operationId])),
+            asOf: s.clock.now().toISOString(),
+            watermark: crypto.randomUUID(),
+            offset: 0,
+        };
+    }
+    const end = snapshot.offset + (q.limit ?? 1000), page = {
+        operations: snapshot.keys.slice(snapshot.offset, end).map((k) => copy(s.operations.get(k))),
+        asOf: snapshot.asOf,
+        watermark: snapshot.watermark,
+    };
+    if (end < snapshot.keys.length) {
+        page.nextCursor = crypto.randomUUID();
+        cursors.set(page.nextCursor, { ...snapshot, offset: end });
+    }
+    return page;
+}