@usagekit/store 0.1.0 → 0.4.0

package/dist/conformance/admission.js

@@ -17,6 +17,7 @@ export function admissionTests(factory) {
                 accessCredential: { kind: "oauth_client", id: "k1" },
             },
             { kind: "platform_pool", namespace: "test", poolId: "p1" },
+            { kind: "tag", namespace: "test", tag: "t1" },
         ];
         const candidate = () => input({
             scope: {
@@ -25,6 +26,7 @@ export function admissionTests(factory) {
                 group: "g1",
                 connection: "c1",
                 accessCredential: { kind: "oauth_client", id: "k1" },
+                tags: ["t1"],
             },
             fundingSource: "platform",
             platformPools: ["p1"],
@@ -51,11 +53,61 @@ export function admissionTests(factory) {
         test("surface exact and any", async () => {
             f.budgets.push(budget({ surface: "programmatic", limit: quantity(0n) }));
             expect(await f.store.reserve(candidate())).toMatchObject({ outcome: "reserved" });
-            expect(await f.store.reserve({ ...candidate(), surface: "programmatic" })).toMatchObject({
+            expect(await f.store.reserve(programmatic("api"))).toMatchObject({ outcome: "exceeded" });
+            f.budgets[0].surface = "any";
+            expect(await f.store.reserve(candidate())).toMatchObject({ outcome: "exceeded" });
+        });
+        const programmatic = (source) => ({
+            ...candidate(),
+            surface: "programmatic",
+            source,
+        });
+        test("source budgets on one connection admit independently", async () => {
+            const connection = { kind: "connection", namespace: "test", connection: "c1" };
+            const cli = budget({ scope: connection, surface: "cli", limit: quantity(1n) }), api = budget({ scope: connection, surface: "api", limit: quantity(1n) });
+            f.budgets.push(cli, api);
+            expect(await f.store.reserve(programmatic("cli"))).toMatchObject({ outcome: "reserved" });
+            expect(await f.store.reserve(programmatic("cli"))).toMatchObject({
                 outcome: "exceeded",
+                exceeded: { budget: { id: cli.id } },
             });
-            f.budgets[0].surface = "any";
+            expect(await f.store.reserve(programmatic("api"))).toMatchObject({ outcome: "reserved" });
+            expect(await f.store.reserve(programmatic("api"))).toMatchObject({
+                outcome: "exceeded",
+                exceeded: { budget: { id: api.id } },
+            });
+            expect(await f.store.reserve(programmatic("mcp"))).toMatchObject({ outcome: "reserved" });
+        });
+        test("surface budget covers its source group and ignores other sources", async () => {
+            f.budgets.push(budget({ surface: "app", limit: quantity(0n) }));
+            expect(await f.store.reserve(programmatic("api"))).toMatchObject({ outcome: "reserved" });
             expect(await f.store.reserve(candidate())).toMatchObject({ outcome: "exceeded" });
+            expect(await f.store.reserve({ ...candidate(), source: "worker" })).toMatchObject({
+                outcome: "exceeded",
+            });
+        });
+        test("source and surface budgets stack; the first exceeded in default order is reported", async () => {
+            const principal = budget({ surface: "programmatic", limit: quantity(1n) }), connection = budget({
+                scope: { kind: "connection", namespace: "test", connection: "c1" },
+                surface: "cli",
+                limit: quantity(1n),
+            });
+            f.budgets.push(connection, principal);
+            const first = await f.store.reserve(programmatic("cli"));
+            expect(first).toMatchObject({ outcome: "reserved" });
+            if (first.outcome !== "reserved")
+                throw new Error("fixture");
+            expect(first.operation.budgetEpochs.map((e) => e.budgetId).sort()).toEqual([principal.id, connection.id].sort());
+            expect(await f.store.reserve(programmatic("cli"))).toMatchObject({
+                outcome: "exceeded",
+                exceeded: { budget: { id: principal.id } },
+            });
+            principal.limit = quantity(5n);
+            expect(await f.store.reserve(programmatic("cli"))).toMatchObject({
+                outcome: "exceeded",
+                exceeded: { budget: { id: connection.id } },
+            });
+            expect(await f.store.reserve(programmatic("sdk"))).toMatchObject({ outcome: "reserved" });
         });
         for (const scope of scopes)
             for (const n of [2, 5, 20])
@@ -74,14 +126,56 @@ export function admissionTests(factory) {
                 exceeded: { budget: { id: pool.id } },
             });
         });
-        test("warn admits and reports warnings", async () => {
-            const b = budget({ onExceed: "warn", limit: quantity(0n) });
+        test("allow admits and reports warnings at the soft limit", async () => {
+            const b = budget({ onExceed: "allow", limit: quantity(0n) });
             f.budgets.push(b);
             expect(await f.store.reserve(candidate())).toMatchObject({
                 outcome: "reserved",
-                warnings: [{ budget: { id: b.id } }],
+                warnings: [{ budget: { id: b.id }, boundary: "limit", used: quantity(0n) }],
             });
         });
+        test("soft budget warns past limit and blocks past hardLimit", async () => {
+            const b = budget({ onExceed: "allow", limit: quantity(1n), hardLimit: quantity(2n) });
+            f.budgets.push(b);
+            expect(await f.store.reserve(candidate())).toMatchObject({
+                outcome: "reserved",
+                warnings: [],
+            });
+            expect(await f.store.reserve(candidate())).toMatchObject({
+                outcome: "reserved",
+                warnings: [{ budget: { id: b.id }, boundary: "limit", reserved: quantity(1n) }],
+            });
+            const blocked = await f.store.reserve(candidate());
+            expect(blocked).toMatchObject({
+                outcome: "exceeded",
+                exceeded: { budget: { id: b.id }, boundary: "hardLimit", reserved: quantity(2n) },
+            });
+            expect(await f.store.reserve({ ...candidate(), estimate: [quantity(0n)] })).toMatchObject({
+                outcome: "reserved",
+                warnings: [{ boundary: "limit" }],
+            });
+        });
+        test.each([
+            { name: "hardLimit below limit", onExceed: "allow", limit: 2n, hardLimit: quantity(1n) },
+            { name: "hardLimit equal to limit", onExceed: "allow", limit: 2n, hardLimit: quantity(2n) },
+            { name: "block with hardLimit", onExceed: "block", limit: 1n, hardLimit: quantity(2n) },
+            {
+                name: "hardLimit in another unit",
+                onExceed: "allow",
+                limit: 1n,
+                hardLimit: quantity(2n, "tokens"),
+            },
+            { name: "hardLimit without limit", onExceed: "allow", limit: null, hardLimit: quantity(2n) },
+        ])("invalid budget definition is a validation failure: $name", async (c) => {
+            f.budgets.push(budget({
+                onExceed: c.onExceed,
+                limit: c.limit === null ? null : quantity(c.limit),
+                hardLimit: c.hardLimit,
+            }));
+            const i = candidate();
+            await expect(f.store.reserve(i)).rejects.toThrow("InvalidInput");
+            expect(await f.store.getOperation(ref(i))).toBeNull();
+        });
         test("current version only; epochs immutable; unbounded still snapshotted", async () => {
             const b = budget({ limit: null });
             f.budgets.push({ ...b, version: 0, limit: quantity(0n) }, b);

package/dist/conformance/alerts.d.ts

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

package/dist/conformance/alerts.js

@@ -0,0 +1,146 @@
+import { beforeEach, afterEach, describe, expect, test } from "vitest";
+import { input, budget, quantity, command, receipt, ref } from "./helpers.js";
+export function alertTests(factory) {
+    describe("alert thresholds recorded once per epoch", () => {
+        let f;
+        beforeEach(async () => {
+            f = await factory();
+        });
+        afterEach(async () => f.close());
+        const percent = (n) => ({ at: { percent: n } });
+        const reserved = async (estimate) => {
+            const r = await f.store.reserve(input({ estimate: [quantity(estimate)] }));
+            if (r.outcome !== "reserved")
+                throw new Error("fixture");
+            return r;
+        };
+        const settle = async (op, measured) => {
+            const g = await f.store.markDispatchIntent({ ...command(op), holder: "h", leaseTtlMs: 1000 });
+            if (!("granted" in g) || !g.granted)
+                throw new Error("fixture");
+            const c = {
+                ...command(g.operation),
+                authority: { kind: "lease", leaseId: g.lease.leaseId },
+                receipt: receipt({
+                    measurements: [{ unit: "requests", certainty: "measured", quantity: quantity(measured) }],
+                }),
+            };
+            const s = await f.store.settle(c);
+            if (s.outcome !== "settled")
+                throw new Error("fixture");
+            return { result: s, replay: () => f.store.settle(c) };
+        };
+        test("a reserve crossing a threshold reports it once with the projected figures", async () => {
+            const b = budget({ limit: quantity(10n), alerts: [percent(80)] });
+            f.budgets.push(b);
+            const first = await reserved(8n);
+            expect(first.alerts).toEqual([
+                {
+                    budgetId: b.id,
+                    budgetVersion: 1,
+                    epoch: "2026-09",
+                    at: { percent: 80 },
+                    used: quantity(0n),
+                    reserved: quantity(8n),
+                },
+            ]);
+            expect((await reserved(1n)).alerts).toEqual([]);
+            expect(await f.store.reserve(input({ estimate: [quantity(9n)] }))).toMatchObject({
+                outcome: "exceeded",
+            });
+        });
+        test("percent and quantity thresholds report in ascending order on one reserve", async () => {
+            const b = budget({
+                limit: quantity(10n),
+                alerts: [percent(50), { at: quantity(7n) }, percent(90)],
+            });
+            f.budgets.push(b);
+            expect((await reserved(8n)).alerts.map((a) => a.at)).toEqual([{ percent: 50 }, quantity(7n)]);
+            expect((await reserved(1n)).alerts.map((a) => a.at)).toEqual([{ percent: 90 }]);
+        });
+        test("a settlement whose measured amount crosses a threshold reports it on settle", async () => {
+            const b = budget({ limit: quantity(10n), alerts: [percent(80)] });
+            f.budgets.push(b);
+            const r = await reserved(5n);
+            expect(r.alerts).toEqual([]);
+            const { result, replay } = await settle(r.operation, 9n);
+            expect(result.alerts).toEqual([
+                {
+                    budgetId: b.id,
+                    budgetVersion: 1,
+                    epoch: "2026-09",
+                    at: { percent: 80 },
+                    used: quantity(9n),
+                    reserved: quantity(0n),
+                },
+            ]);
+            expect(await replay()).toEqual({ ...result, replayed: true });
+            expect((await reserved(1n)).alerts).toEqual([]);
+        });
+        test("a settlement below the estimate reports nothing and later reserves may still cross", async () => {
+            const b = budget({ limit: quantity(10n), alerts: [percent(50)] });
+            f.budgets.push(b);
+            const r = await reserved(4n);
+            const { result } = await settle(r.operation, 1n);
+            expect(result.alerts).toEqual([]);
+            expect((await reserved(4n)).alerts).toHaveLength(1);
+        });
+        test("concurrent reserves crossing one threshold report it exactly once in total", async () => {
+            f.budgets.push(budget({ limit: quantity(100n), alerts: [percent(5)] }));
+            const results = await Promise.all(Array.from({ length: 6 }, () => f.store.reserve(input({ estimate: [quantity(6n)] }))));
+            const crossings = results.flatMap((r) => (r.outcome === "reserved" ? r.alerts : []));
+            expect(results.every((r) => r.outcome === "reserved")).toBe(true);
+            expect(crossings).toHaveLength(1);
+        });
+        test("a new epoch reports the same threshold again", async () => {
+            const b = budget({
+                limit: quantity(2n),
+                alerts: [percent(50)],
+                window: { kind: "since_reset", epoch: "e1", startsAt: "2026-09-01T00:00:00.000Z" },
+            });
+            f.budgets.push(b);
+            expect((await reserved(1n)).alerts).toMatchObject([{ epoch: "e1" }]);
+            expect((await reserved(1n)).alerts).toEqual([]);
+            b.window = { kind: "since_reset", epoch: "e2", startsAt: f.clock.now().toISOString() };
+            expect((await reserved(1n)).alerts).toMatchObject([{ epoch: "e2", at: { percent: 50 } }]);
+        });
+        test("reserve replay returns the original crossings and records nothing new", async () => {
+            const b = budget({ limit: quantity(10n), alerts: [percent(50), percent(80)] });
+            f.budgets.push(b);
+            const i = input({ estimate: [quantity(6n)] });
+            const first = await f.store.reserve(i);
+            if (first.outcome !== "reserved")
+                throw new Error("fixture");
+            expect(first.alerts.map((a) => a.at)).toEqual([{ percent: 50 }]);
+            expect(await f.store.reserve(i)).toEqual({ ...first, replayed: true });
+            expect((await reserved(2n)).alerts.map((a) => a.at)).toEqual([{ percent: 80 }]);
+            expect(await f.store.reserve(i)).toEqual({ ...first, replayed: true });
+        });
+        test("a denied reserve records no crossing", async () => {
+            const b = budget({ limit: quantity(10n), alerts: [percent(50)] }), blocker = budget({ limit: quantity(0n) });
+            f.budgets.push(b, blocker);
+            expect(await f.store.reserve(input({ estimate: [quantity(6n)] }))).toMatchObject({
+                outcome: "exceeded",
+                exceeded: { budget: { id: blocker.id } },
+            });
+            blocker.limit = quantity(100n);
+            expect((await reserved(6n)).alerts).toHaveLength(1);
+        });
+        const invalid = [
+            { name: "more than eight", alerts: Array.from({ length: 9 }, (_, n) => percent(n + 10)) },
+            { name: "not ascending", alerts: [percent(80), percent(50)] },
+            { name: "equal thresholds", alerts: [percent(50), { at: quantity(5n) }] },
+            { name: "percent below one", alerts: [percent(0)] },
+            { name: "percent above hundred", alerts: [percent(101)] },
+            { name: "fractional percent", alerts: [percent(12.5)] },
+            { name: "quantity in another unit", alerts: [{ at: quantity(1n, "tokens") }] },
+            { name: "percent without a limit", alerts: [percent(50)], limit: null },
+        ];
+        test.each(invalid)("invalid alert definition is a validation failure: $name", async (c) => {
+            f.budgets.push(budget({ limit: c.limit === null ? null : quantity(10n), alerts: c.alerts }));
+            const i = input();
+            await expect(f.store.reserve(i)).rejects.toThrow("InvalidInput");
+            expect(await f.store.getOperation(ref(i))).toBeNull();
+        });
+    });
+}

package/dist/conformance/counters.d.ts

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

package/dist/conformance/counters.js

@@ -0,0 +1,159 @@
+import { beforeEach, afterEach, describe, expect, test } from "vitest";
+import { budget, input, quantity } from "./helpers.js";
+export function counterTests(factory) {
+    describe("request counter", () => {
+        let f;
+        beforeEach(async () => {
+            f = await factory();
+        });
+        afterEach(async () => f.close());
+        const count = (overrides = {}) => ({
+            commandId: crypto.randomUUID(),
+            scope: { namespace: "test", principal: "u1", connection: "c1" },
+            surface: "programmatic",
+            source: "proxy",
+            provider: "search",
+            operation: "search",
+            state: "passthrough",
+            ...overrides,
+        });
+        const month = { from: "2026-09-01T00:00:00.000Z", to: "2026-10-01T00:00:00.000Z" };
+        const principal = { kind: "principal", namespace: "test", principal: "u1" };
+        const query = (overrides = {}) => ({
+            scope: principal,
+            ...month,
+            groupBy: [],
+            ...overrides,
+        });
+        test("counted request ids cannot become reservations after a policy change", async () => {
+            const i = input();
+            await f.store.countRequest(count({ commandId: i.operationId, scope: i.scope }));
+            await expect(f.store.reserve(i)).rejects.toThrow("operationId");
+            const next = input();
+            expect(await f.store.reserve(next)).toMatchObject({ outcome: "reserved" });
+            expect(await f.store.countRequest(count({ commandId: next.operationId, scope: next.scope }))).toMatchObject({ outcome: "conflict" });
+        });
+        test("counts each state separately and reads them back", async () => {
+            for (const state of [
+                "passthrough",
+                "passthrough",
+                "unpriced",
+                "cached",
+                "rate_limited",
+            ])
+                expect(await f.store.countRequest(count({ state }))).toEqual({
+                    outcome: "counted",
+                    replayed: false,
+                });
+            const page = await f.store.requestCounts(query());
+            expect(page.rows).toEqual([
+                { dimensions: {}, state: "cached", count: 1n },
+                { dimensions: {}, state: "passthrough", count: 2n },
+                { dimensions: {}, state: "rate_limited", count: 1n },
+                { dimensions: {}, state: "unpriced", count: 1n },
+            ]);
+            expect(page.truncated).toBe(false);
+            expect(page.asOf).toBe(f.clock.now().toISOString());
+        });
+        test("an identical replay counts once; a changed payload under the same command conflicts", async () => {
+            const c = count();
+            await f.store.countRequest(c);
+            expect(await f.store.countRequest(c)).toEqual({ outcome: "counted", replayed: true });
+            expect(await f.store.countRequest({ ...c, state: "cached" })).toEqual({
+                outcome: "conflict",
+                reason: "command_mismatch",
+            });
+            expect((await f.store.requestCounts(query())).rows).toEqual([
+                { dimensions: {}, state: "passthrough", count: 1n },
+            ]);
+        });
+        test("the window is [from, to) at store time", async () => {
+            f.clock.set("2026-09-30T23:59:59.999Z");
+            await f.store.countRequest(count());
+            f.clock.set("2026-10-01T00:00:00.000Z");
+            await f.store.countRequest(count());
+            expect((await f.store.requestCounts(query())).rows).toEqual([
+                { dimensions: {}, state: "passthrough", count: 1n },
+            ]);
+            expect((await f.store.requestCounts(query({ from: "2026-10-01T00:00:00.000Z", to: "2026-10-02T00:00:00.000Z" }))).rows).toEqual([{ dimensions: {}, state: "passthrough", count: 1n }]);
+        });
+        test("scopes select principal, group, namespace and pool; connection filters", async () => {
+            await f.store.countRequest(count());
+            await f.store.countRequest(count({
+                scope: { namespace: "test", principal: "u2", group: "g1", connection: "c2" },
+                platformPools: ["pool_a"],
+            }));
+            await f.store.countRequest(count({ scope: { namespace: "other", principal: "u1", connection: "c1" } }));
+            const total = async (q) => (await f.store.requestCounts(query(q))).rows.reduce((a, r) => a + r.count, 0n);
+            expect(await total({})).toBe(1n);
+            expect(await total({ scope: { kind: "group", namespace: "test", group: "g1" } })).toBe(1n);
+            expect(await total({ scope: { kind: "namespace", namespace: "test" } })).toBe(2n);
+            expect(await total({ scope: { kind: "namespace", namespace: "test" }, connection: "c2" })).toBe(1n);
+            expect(await total({ scope: { kind: "platform_pool", namespace: "test", poolId: "pool_a" } })).toBe(1n);
+            expect(await total({ scope: { kind: "platform_pool", namespace: "test", poolId: "pool_b" } })).toBe(0n);
+        });
+        test("groupBy provider, operation, connection, source and day", async () => {
+            await f.store.countRequest(count({ operation: "a" }));
+            await f.store.countRequest(count({ operation: "b", source: "cli" }));
+            f.clock.advance(86400000);
+            await f.store.countRequest(count({ operation: "a", state: "unpriced" }));
+            const rows = (await f.store.requestCounts(query({ groupBy: ["provider", "operation", "connection", "source", "day"] }))).rows;
+            expect(rows).toEqual([
+                {
+                    dimensions: {
+                        provider: "search",
+                        operation: "a",
+                        connection: "c1",
+                        source: "proxy",
+                        day: "2026-09-23",
+                    },
+                    state: "passthrough",
+                    count: 1n,
+                },
+                {
+                    dimensions: {
+                        provider: "search",
+                        operation: "a",
+                        connection: "c1",
+                        source: "proxy",
+                        day: "2026-09-24",
+                    },
+                    state: "unpriced",
+                    count: 1n,
+                },
+                {
+                    dimensions: {
+                        provider: "search",
+                        operation: "b",
+                        connection: "c1",
+                        source: "cli",
+                        day: "2026-09-23",
+                    },
+                    state: "passthrough",
+                    count: 1n,
+                },
+            ]);
+        });
+        test("limit truncates the ordered rows", async () => {
+            for (const operation of ["c", "a", "b"])
+                await f.store.countRequest(count({ operation }));
+            const page = await f.store.requestCounts(query({ groupBy: ["operation"], limit: 2 }));
+            expect(page.rows.map((r) => r.dimensions.operation)).toEqual(["a", "b"]);
+            expect(page.truncated).toBe(true);
+        });
+        test("counting never reserves or touches budgets", async () => {
+            f.budgets.push(budget({ limit: quantity(0n) }));
+            expect(await f.store.countRequest(count())).toMatchObject({ outcome: "counted" });
+            expect(await f.store.reserve(input())).toMatchObject({ outcome: "exceeded" });
+            const statuses = await f.store.applicableBudgets({
+                scope: { namespace: "test", principal: "u1", connection: "c1" },
+                surface: "app",
+                units: ["requests"],
+            });
+            expect(statuses[0]).toMatchObject({ used: quantity(0n), reserved: quantity(0n) });
+        });
+        test("an unknown state is a validation failure", async () => {
+            await expect(f.store.countRequest(count({ state: "metered" }))).rejects.toThrow("InvalidInput");
+        });
+    });
+}

package/dist/conformance/operations.d.ts

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

package/dist/conformance/operations.js

@@ -0,0 +1,103 @@
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { command, input, receipt, unknownReceipt } from "./helpers.js";
+export function operationsTests(factory) {
+    describe("operation listing", () => {
+        let f;
+        beforeEach(async () => {
+            f = await factory();
+        });
+        afterEach(async () => f.close());
+        const query = (overrides = {}) => ({
+            scope: { kind: "namespace", namespace: "test" },
+            from: "2026-09-01T00:00:00.000Z",
+            to: "2026-10-01T00:00:00.000Z",
+            ...overrides,
+        });
+        const reserved = async (overrides = {}) => {
+            const r = await f.store.reserve(input(overrides));
+            if (r.outcome !== "reserved")
+                throw new Error("fixture");
+            f.clock.advance(1000);
+            return r.operation;
+        };
+        const dispatched = async (overrides = {}) => {
+            const op = await reserved(overrides);
+            const g = await f.store.markDispatchIntent({
+                ...command(op),
+                holder: "h",
+                leaseTtlMs: 60000,
+            });
+            if (!("granted" in g) || !g.granted)
+                throw new Error("fixture");
+            return g;
+        };
+        const settledWith = async (unknown, overrides = {}) => {
+            const g = await dispatched(overrides);
+            const s = await f.store.settle({
+                ...command(g.operation),
+                authority: { kind: "lease", leaseId: g.lease.leaseId },
+                receipt: unknown ? unknownReceipt() : receipt(),
+            });
+            if (s.outcome !== "settled")
+                throw new Error("fixture");
+            return s.operation;
+        };
+        const ids = (ops) => ops.map((o) => o.operationId);
+        test("lists every state by default and filters by state in creation order", async () => {
+            const a = await reserved(), b = (await dispatched()).operation, c = await settledWith(true), d = await settledWith(false);
+            expect(c.state).toBe("pending");
+            expect(d.state).toBe("settled");
+            const all = await f.store.listOperations(query());
+            expect(ids(all.operations)).toEqual(ids([a, b, c, d]));
+            expect(all.nextCursor).toBeUndefined();
+            expect(all.asOf).toBe(f.clock.now().toISOString());
+            expect(typeof all.watermark).toBe("string");
+            const open = await f.store.listOperations(query({ states: ["reserved", "pending"] }));
+            expect(ids(open.operations)).toEqual([a.operationId, c.operationId]);
+            expect(open.operations[1].state).toBe("pending");
+            expect(open.operations[1].receipts).toHaveLength(1);
+            expect(ids((await f.store.listOperations(query({ states: ["dispatch_intended"] }))).operations)).toEqual([b.operationId]);
+        });
+        test("scope and connection narrow the listing without widening it", async () => {
+            const own = await reserved({
+                scope: { namespace: "test", principal: "u1", connection: "c1", group: "g1" },
+                platformPools: ["p1"],
+            }), other = await reserved({
+                scope: { namespace: "test", principal: "u2", connection: "c2" },
+                costOwner: "u2",
+            });
+            await f.store.reserve(input({ scope: { namespace: "other", principal: "u1", connection: "c1" } }));
+            const list = async (o) => ids((await f.store.listOperations(query(o))).operations);
+            expect(await list({})).toEqual([own.operationId, other.operationId]);
+            expect(await list({ scope: { kind: "principal", namespace: "test", principal: "u2" } })).toEqual([other.operationId]);
+            expect(await list({ scope: { kind: "group", namespace: "test", group: "g1" } })).toEqual([
+                own.operationId,
+            ]);
+            expect(await list({ scope: { kind: "platform_pool", namespace: "test", poolId: "p1" } })).toEqual([own.operationId]);
+            expect(await list({ connection: "c2" })).toEqual([other.operationId]);
+        });
+        test("the window is createdAt from inclusive to exclusive", async () => {
+            const first = await reserved(), second = await reserved();
+            const list = async (from, to) => ids((await f.store.listOperations(query({ from, to }))).operations);
+            expect(await list(first.createdAt, second.createdAt)).toEqual([first.operationId]);
+            expect(await list(second.createdAt, "2026-10-01T00:00:00.000Z")).toEqual([
+                second.operationId,
+            ]);
+            expect(await list("2026-09-01T00:00:00.000Z", first.createdAt)).toEqual([]);
+        });
+        test("pages keep first-page membership and reject a changed query", async () => {
+            const a = await reserved(), b = await reserved(), c = await reserved();
+            const first = await f.store.listOperations(query({ limit: 2 }));
+            expect(ids(first.operations)).toEqual([a.operationId, b.operationId]);
+            expect(first.nextCursor).toBeTruthy();
+            await reserved();
+            const second = await f.store.listOperations(query({ limit: 2, cursor: first.nextCursor }));
+            expect(ids(second.operations)).toEqual([c.operationId]);
+            expect(second.nextCursor).toBeUndefined();
+            expect(second.watermark).toBe(first.watermark);
+            expect(second.asOf).toBe(first.asOf);
+            await expect(f.store.listOperations(query({ limit: 1, cursor: first.nextCursor }))).rejects.toThrow("InvalidInput");
+            await expect(f.store.listOperations(query({ limit: 2, cursor: "forged" }))).rejects.toThrow("InvalidInput");
+        });
+    });
+}

package/dist/conformance/properties.js

@@ -125,11 +125,12 @@ export function propertyTests(factory) {
                 }
             }), { numRuns, verbose: 2 });
         });
-        test("many operations never over-admit any blocking budget", async () => {
+        test("many operations never over-admit any blocking budget or hard limit", async () => {
             await fc.assert(fc.asyncProperty(fc.array(fc.record({
                 kind: fc.constantFrom("principal", "connection", "platform_pool"),
                 limit: fc.integer({ min: 0, max: 30 }),
-                warn: fc.boolean(),
+                allow: fc.boolean(),
+                headroom: fc.option(fc.integer({ min: 1, max: 10 }), { nil: undefined }),
             }), { minLength: 1, maxLength: 4 }), fc.array(fc.record({
                 owner: fc.integer({ min: 1, max: 3 }),
                 amount: fc.integer({ min: 0, max: 5 }),
@@ -145,7 +146,10 @@ export function propertyTests(factory) {
                                     ? { kind: "connection", namespace: "test", connection: "c1" }
                                     : { kind: "platform_pool", namespace: "test", poolId: "pool" },
                             limit: quantity(BigInt(spec.limit)),
-                            onExceed: spec.warn ? "warn" : "block",
+                            onExceed: spec.allow ? "allow" : "block",
+                            ...(spec.allow && spec.headroom !== undefined
+                                ? { hardLimit: quantity(BigInt(spec.limit + spec.headroom)) }
+                                : {}),
                         }));
                     const accepted = [];
                     for (const spec of operations) {
@@ -180,11 +184,14 @@ export function propertyTests(factory) {
                                 });
                             }
                         }
-                        for (const b of f.budgets.filter((b) => b.onExceed === "block")) {
+                        for (const b of f.budgets) {
+                            const ceiling = b.onExceed === "block" ? b.limit : (b.hardLimit ?? null);
+                            if (!ceiling)
+                                continue;
                             const total = accepted
                                 .filter((op) => op.budgetEpochs.some((e) => e.budgetId === b.id))
                                 .reduce((n, op) => n + op.estimate[0].value, 0n);
-                            expect(total).toBeLessThanOrEqual(b.limit.value);
+                            expect(total).toBeLessThanOrEqual(ceiling.value);
                         }
                     }
                 }