@usagekit/store 0.3.0 → 0.4.0

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/suite.js

@@ -11,6 +11,7 @@ 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);
@@ -23,6 +24,7 @@ export function runStoreConformance(factory, capabilities) {
         recoveryTests(factory);
         readsTests(factory, capabilities);
         operationsTests(factory);
+        counterTests(factory);
         propertyTests(factory);
         capabilityTests(factory, capabilities);
         afterAll(() => console.info("Skipped guarantees: " +

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, OperationsQuery, OperationsPage } 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,9 +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[]>;
 }
@@ -31,3 +34,5 @@ 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

@@ -2,3 +2,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";
+export { validateCountRequest, validateRequestCountsQuery, countIdentity, countRows, bucketOf, requestCountDimensions, } from "./memory/counters.js";

package/dist/memory/commands.js

@@ -18,6 +18,8 @@ export function reserve(s, raw, policy) {
                 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 {

package/dist/memory/counters.d.ts

@@ -0,0 +1,33 @@
+import type { CountRequestInput, CountRequestResult, RequestCountsPage, RequestCountsQuery } from "@usagekit/core";
+import type { State } from "./state.js";
+/** Dimensions a request count can be grouped by. */
+export declare const requestCountDimensions: string[];
+/** Throws InvalidInput for a malformed count; every adapter calls it before writing. */
+export declare function validateCountRequest(i: CountRequestInput): void;
+/** Replay identity of a count: the whole input, pools sorted. */
+export declare const countIdentity: (i: CountRequestInput) => string;
+/**
+ * Counts are daily UTC buckets, so a window must start and end at UTC midnight; a narrower
+ * window would silently widen to whole days.
+ */
+export declare function validateRequestCountsQuery(q: RequestCountsQuery): void;
+/** One stored bucket: the counted fields and the UTC day. */
+export type CountBucket = {
+    namespace: string;
+    principal: string;
+    group: string;
+    connection: string;
+    pools: readonly string[];
+    day: string;
+    provider: string;
+    operation: string;
+    source: string;
+    state: CountRequestInput["state"];
+    count: bigint;
+};
+export declare const bucketOf: (i: CountRequestInput, now: Date) => Omit<CountBucket, "count">;
+export declare function bucketInScope(b: Omit<CountBucket, "count">, q: RequestCountsQuery): boolean;
+/** Groups buckets into rows ordered by dimension values in groupBy order, then state. */
+export declare function countRows(buckets: Iterable<CountBucket>, q: RequestCountsQuery, asOf: string): RequestCountsPage;
+export declare function countRequest(s: State, i: CountRequestInput): CountRequestResult;
+export declare function requestCounts(s: State, q: RequestCountsQuery): RequestCountsPage;

package/dist/memory/counters.js

@@ -0,0 +1,113 @@
+import { requestStates } from "@usagekit/core";
+import { canonical, copy, InvalidInput, key } from "./state.js";
+/** Dimensions a request count can be grouped by. */
+export const requestCountDimensions = ["provider", "operation", "connection", "source", "day"];
+const dayMs = 86400000;
+/** Throws InvalidInput for a malformed count; every adapter calls it before writing. */
+export function validateCountRequest(i) {
+    for (const [field, value] of [
+        ["commandId", i.commandId],
+        ["scope.namespace", i.scope?.namespace],
+        ["scope.principal", i.scope?.principal],
+        ["scope.connection", i.scope?.connection],
+        ["provider", i.provider],
+        ["operation", i.operation],
+    ])
+        if (typeof value !== "string" || !value.trim())
+            throw new InvalidInput(field, "empty string");
+    if (!requestStates.includes(i.state))
+        throw new InvalidInput("state", "unknown request state");
+}
+/** Replay identity of a count: the whole input, pools sorted. */
+export const countIdentity = (i) => canonical({ ...i, platformPools: [...(i.platformPools ?? [])].sort() });
+/**
+ * Counts are daily UTC buckets, so a window must start and end at UTC midnight; a narrower
+ * window would silently widen to whole days.
+ */
+export function validateRequestCountsQuery(q) {
+    const from = Date.parse(q.from), to = Date.parse(q.to);
+    if (!Number.isFinite(from) || !Number.isFinite(to) || from > to)
+        throw new InvalidInput("window", "invalid time interval");
+    if (from % dayMs !== 0 || to % dayMs !== 0)
+        throw new InvalidInput("window", "request counts use whole UTC days");
+    if (q.limit !== undefined && (!Number.isInteger(q.limit) || q.limit < 1 || q.limit > 1000))
+        throw new InvalidInput("limit", "must be between 1 and 1000");
+    if (q.groupBy.some((d) => !requestCountDimensions.includes(d)))
+        throw new InvalidInput("groupBy", "unknown request count dimension");
+}
+export const bucketOf = (i, now) => ({
+    namespace: i.scope.namespace,
+    principal: i.scope.principal,
+    group: i.scope.group ?? "",
+    connection: i.scope.connection,
+    pools: [...(i.platformPools ?? [])].sort(),
+    day: now.toISOString().slice(0, 10),
+    provider: i.provider,
+    operation: i.operation,
+    source: i.source,
+    state: i.state,
+});
+export function bucketInScope(b, q) {
+    if (b.namespace !== q.scope.namespace || (q.connection && b.connection !== q.connection))
+        return false;
+    const day = Date.parse(`${b.day}T00:00:00.000Z`);
+    if (day < Date.parse(q.from) || day >= Date.parse(q.to))
+        return false;
+    switch (q.scope.kind) {
+        case "namespace":
+            return true;
+        case "principal":
+            return b.principal === q.scope.principal;
+        case "group":
+            return b.group === q.scope.group;
+        case "platform_pool":
+            return b.pools.includes(q.scope.poolId);
+    }
+}
+/** Groups buckets into rows ordered by dimension values in groupBy order, then state. */
+export function countRows(buckets, q, asOf) {
+    const map = new Map();
+    for (const b of buckets) {
+        if (!bucketInScope(b, q))
+            continue;
+        const dimensions = {};
+        for (const d of q.groupBy)
+            dimensions[d] = b[d];
+        const order = [...q.groupBy.map((d) => dimensions[d]), b.state], k = canonical(order), prev = map.get(k);
+        map.set(k, { dimensions, state: b.state, count: (prev?.count ?? 0n) + b.count, order });
+    }
+    const sorted = [...map.values()].sort((a, b) => compare(a.order, b.order)), limit = q.limit ?? 1000;
+    return {
+        rows: sorted.slice(0, limit).map(({ dimensions, state, count }) => ({
+            dimensions,
+            state,
+            count,
+        })),
+        asOf,
+        truncated: sorted.length > limit,
+    };
+}
+function compare(a, b) {
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return a[i] < b[i] ? -1 : 1;
+    return 0;
+}
+export function countRequest(s, i) {
+    validateCountRequest(i);
+    const commandKey = key(i.scope.namespace, i.commandId), identity = countIdentity(i), commands = (s.requestCommands ??= new Map()), previous = commands.get(commandKey);
+    if (previous !== undefined)
+        return previous === identity
+            ? { outcome: "counted", replayed: true }
+            : { outcome: "conflict", reason: "command_mismatch" };
+    if (s.operations.has(commandKey))
+        return { outcome: "conflict", reason: "command_mismatch" };
+    const bucket = bucketOf(i, s.clock.now()), buckets = (s.requestBuckets ??= new Map()), bucketKey = canonical(bucket);
+    buckets.set(bucketKey, { ...bucket, count: (buckets.get(bucketKey)?.count ?? 0n) + 1n });
+    commands.set(commandKey, identity);
+    return { outcome: "counted", replayed: false };
+}
+export function requestCounts(s, q) {
+    validateRequestCountsQuery(q);
+    return copy(countRows(s.requestBuckets?.values() ?? [], q, s.clock.now().toISOString()));
+}

package/dist/memory/memory-store.js

@@ -1,5 +1,6 @@
 import { aggregate, definedBudgets, applicableBudgets, listOperations } from "./reads.js";
 import { copy, find } from "./state.js";
+import { countRequest, requestCounts } from "./counters.js";
 import { reserve, intent, renew, settle, release, claim, expireReservations } from "./commands.js";
 export function createMemoryStore({ clock, budgets }) {
     const state = {
@@ -24,6 +25,8 @@ export function createMemoryStore({ clock, budgets }) {
         settle: async (i) => settle(state, i),
         correct: async (i) => settle(state, i, true),
         releaseUndispatched: async (i) => release(state, i),
+        countRequest: async (i) => countRequest(state, i),
+        requestCounts: async (q) => requestCounts(state, q),
         aggregate: async (q) => aggregate(state, q),
         listOperations: async (q) => listOperations(state, q),
         definedBudgets: async (q) => definedBudgets(state, q),

package/dist/memory/state.d.ts

@@ -4,6 +4,7 @@ import type { SettleResult, ReleaseResult } from "@usagekit/core";
 import type { AllowanceExceeded, BudgetAlertCrossed } from "@usagekit/core";
 import type { Budget, Operation, ReserveInput, OperationRef, Quantity } from "@usagekit/core";
 import type { Clock } from "../clock.js";
+import type { CountBucket } from "./counters.js";
 export declare class InvalidInput extends Error {
     readonly field: string;
     readonly reason: string;
@@ -12,7 +13,7 @@ export declare class InvalidInput extends Error {
 export declare const copy: <T>(value: T) => T;
 export declare function canonical(value: unknown): string;
 export declare const key: (namespace: string, id: string) => string;
-/** Reserve identity: diagnostic ids and attribution tags are not semantic. */
+/** Reserve identity: diagnostic ids, estimate provenance and attribution tags are not semantic. */
 export declare function semantics(i: ReserveInput): string;
 /** Sorted tags on the stored input, or an InvalidInput when the list breaks the tag rules. */
 export declare function withNormalizedTags(i: ReserveInput): ReserveInput;
@@ -53,5 +54,9 @@ export type State = {
     reserveAlerts: Map<string, readonly BudgetAlertCrossed[]>;
     /** Recorded crossings keyed by namespace, budget id, epoch and threshold. */
     alerts: Set<string>;
+    /** Request counter: replay identities by namespace and command id. */
+    requestCommands?: Map<string, string>;
+    /** Request counter: daily buckets keyed by their canonical fields. */
+    requestBuckets?: Map<string, CountBucket>;
 };
 export declare function find(s: State, ref: OperationRef): Operation | null;

package/dist/memory/state.js

@@ -23,9 +23,9 @@ export function canonical(value) {
     return JSON.stringify(value) ?? "null";
 }
 export const key = (namespace, id) => canonical([namespace, id]);
-/** Reserve identity: diagnostic ids and attribution tags are not semantic. */
+/** Reserve identity: diagnostic ids, estimate provenance and attribution tags are not semantic. */
 export function semantics(i) {
-    const { correlationId: _, parentOperationId: __, scope, ...rest } = i;
+    const { correlationId: _, parentOperationId: __, estimateSource: _source, providerPriceVersion: _priceVersion, scope, ...rest } = i;
     const { tags: ___, ...scopeIdentity } = scope;
     return canonical({
         ...rest,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usagekit/store",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Atomic store commands, reference store and conformance tests.",
@@ -31,7 +31,7 @@
     "prepack": "node ../../scripts/package-license.mjs"
   },
   "dependencies": {
-    "@usagekit/core": "0.3.0"
+    "@usagekit/core": "0.4.0"
   },
   "sideEffects": false,
   "publishConfig": {