@usagekit/store 0.3.0 → 0.5.0

package/dist/billing.d.ts

@@ -0,0 +1,22 @@
+import type { BillingImportInput, BillingImportRecord, BillingImportResult, BillingImportsPage, BillingImportsQuery, BillingOperationChange, Operation, ValidationFailure } from "@usagekit/core";
+export type StoredBillingImport = {
+    identity: string;
+    record: BillingImportRecord;
+};
+export type BillingSnapshot = {
+    operations: readonly Operation[];
+    imports: readonly StoredBillingImport[];
+    latestImportId: string | null;
+};
+export type BillingPreparation = {
+    result: BillingImportResult;
+    changes: readonly BillingOperationChange[];
+    stored?: StoredBillingImport;
+    familyId: string;
+};
+export declare function validateBillingImportInput(i: BillingImportInput): ValidationFailure | null;
+export declare function validateBillingImportsQuery(q: BillingImportsQuery): ValidationFailure | null;
+export declare const billingFamilyId: (i: BillingImportInput) => string;
+/** Pure preparation. Adapters commit every change, projection and journal in one transaction. */
+export declare function prepareBillingImport(i: BillingImportInput, snapshot: BillingSnapshot, now: Date): BillingPreparation;
+export declare function readBillingImports(records: readonly BillingImportRecord[], q: BillingImportsQuery, now: Date): BillingImportsPage;

package/dist/billing.js

@@ -0,0 +1,352 @@
+import { normalizeTags } from "@usagekit/core";
+import { canonical, copy, maxMoneyUnits } from "./memory/state.js";
+const invalid = (field, reason) => ({
+    outcome: "invalid",
+    field,
+    reason,
+});
+const name = (value) => typeof value === "string" && value.trim().length > 0 && value.length <= 256;
+const date = (value) => typeof value === "string" && Number.isFinite(Date.parse(value));
+const interval = (value) => {
+    if (!value || typeof value !== "object")
+        return false;
+    const w = value;
+    return date(w.from) && date(w.to) && Date.parse(w.from) < Date.parse(w.to);
+};
+const normalizedWindow = (w) => ({
+    from: new Date(w.from).toISOString(),
+    to: new Date(w.to).toISOString(),
+});
+export function validateBillingImportInput(i) {
+    if (!i || typeof i !== "object")
+        return invalid("input", "expected billing import");
+    if (!i.scope || !name(i.scope.namespace) || !name(i.scope.principal) || !name(i.scope.connection))
+        return invalid("scope", "namespace, principal and connection are required");
+    for (const field of ["actor", "group", "providerCredentialVersion"])
+        if (i.scope[field] !== undefined && !name(i.scope[field]))
+            return invalid("scope." + field, "nonempty identifier required");
+    if (i.scope.accessCredential !== undefined &&
+        (!i.scope.accessCredential ||
+            !name(i.scope.accessCredential.kind) ||
+            !name(i.scope.accessCredential.id)))
+        return invalid("scope.accessCredential", "credential kind and id required");
+    if (i.scope.tags !== undefined && !normalizeTags(i.scope.tags))
+        return invalid("scope.tags", "invalid tags");
+    if (!name(i.provider))
+        return invalid("provider", "provider is required");
+    if (typeof i.fileHash !== "string" || !/^[a-f0-9]{64}$/.test(i.fileHash))
+        return invalid("fileHash", "expected lower-case SHA-256");
+    if (!interval(i.window))
+        return invalid("window", "expected a nonempty half-open interval");
+    if (i.expectedPreviousImportId !== null &&
+        (typeof i.expectedPreviousImportId !== "string" || !i.expectedPreviousImportId))
+        return invalid("expectedPreviousImportId", "explicit null or current import id required");
+    if (!i.attribution ||
+        !["byok", "platform"].includes(i.attribution.fundingSource) ||
+        !name(i.attribution.costOwner))
+        return invalid("attribution", "trusted historical funding and cost owner required");
+    for (const field of ["creditAccountRef", "customerPriceVersion", "providerPriceVersion"])
+        if (i.attribution[field] !== undefined && !name(i.attribution[field]))
+            return invalid("attribution." + field, "nonempty identifier required");
+    if (i.attribution.platformPools !== undefined &&
+        (!Array.isArray(i.attribution.platformPools) ||
+            i.attribution.platformPools.some((p) => !name(p)) ||
+            new Set(i.attribution.platformPools).size !== i.attribution.platformPools.length))
+        return invalid("attribution.platformPools", "unique pool ids required");
+    if (!Array.isArray(i.lines) || i.lines.length > 1000)
+        return invalid("lines", "at most 1000 export lines per atomic import");
+    const requestIds = new Set();
+    const aggregateWindows = [];
+    for (const [n, line] of i.lines.entries()) {
+        const field = "lines." + n;
+        if (!line ||
+            !date(line.occurredAt) ||
+            Date.parse(line.occurredAt) < Date.parse(i.window.from) ||
+            Date.parse(line.occurredAt) >= Date.parse(i.window.to))
+            return invalid(field, "occurrence must belong to the import window");
+        if (!line.cost ||
+            line.cost.currency !== "USD" ||
+            typeof line.cost.units !== "bigint" ||
+            line.cost.units < 0n ||
+            line.cost.units > maxMoneyUnits)
+            return invalid(field + ".cost", "exact nonnegative USD within storage capability required");
+        if (line.operation !== undefined && !name(line.operation))
+            return invalid(field + ".operation", "invalid operation");
+        if (line.providerRequestId !== undefined) {
+            if (!name(line.providerRequestId) || requestIds.has(line.providerRequestId))
+                return invalid(field + ".providerRequestId", "unique nonempty request id required");
+            if (line.window !== undefined)
+                return invalid(field, "a request line cannot also be an aggregate");
+            requestIds.add(line.providerRequestId);
+        }
+        else {
+            if (!interval(line.window) ||
+                Date.parse(line.window.from) < Date.parse(i.window.from) ||
+                Date.parse(line.window.to) > Date.parse(i.window.to))
+                return invalid(field + ".window", "an aggregate line needs a contained window");
+            if (aggregateWindows.some((w) => Date.parse(w.from) < Date.parse(line.window.to) &&
+                Date.parse(line.window.from) < Date.parse(w.to) &&
+                (w.operation === undefined ||
+                    line.operation === undefined ||
+                    w.operation === line.operation)))
+                return invalid(field + ".window", "overlapping aggregate lines double-count evidence");
+            aggregateWindows.push({
+                ...line.window,
+                ...(line.operation === undefined ? {} : { operation: line.operation }),
+            });
+        }
+    }
+    if (i.lines.some((line) => line.providerRequestId !== undefined &&
+        aggregateWindows.some((w) => Date.parse(line.occurredAt) >= Date.parse(w.from) &&
+            Date.parse(line.occurredAt) < Date.parse(w.to) &&
+            (w.operation === undefined ||
+                line.operation === undefined ||
+                w.operation === line.operation))))
+        return invalid("lines", "itemized and aggregate evidence cannot overlap");
+    return null;
+}
+export function validateBillingImportsQuery(q) {
+    if (!q || !q.scope || !name(q.scope.namespace) || !name(q.scope.principal) || !name(q.connection))
+        return invalid("scope", "namespace, principal and connection required");
+    if (!interval(q))
+        return invalid("window", "expected a nonempty interval");
+    if (q.limit !== undefined && (!Number.isInteger(q.limit) || q.limit < 1 || q.limit > 1000))
+        return invalid("limit", "1 to 1000 required");
+    if (q.history !== undefined && typeof q.history !== "boolean")
+        return invalid("history", "boolean required");
+    return null;
+}
+export const billingFamilyId = (i) => canonical([i.scope.namespace, i.scope.connection, i.provider, normalizedWindow(i.window)]);
+const currentReceipt = (op) => {
+    const superseded = new Set(op.receipts.map((r) => r.supersedes));
+    return [...op.receipts].reverse().find((r) => !superseded.has(r.id));
+};
+/** Billing comparisons retain the application's own evidence rather than echoing a prior invoice. */
+const observedReceipt = (op) => {
+    const receipts = op.receipts.filter((r) => r.source !== "import");
+    const superseded = new Set(receipts.map((r) => r.supersedes));
+    return [...receipts].reverse().find((r) => !superseded.has(r.id));
+};
+function ledger(operations, window, operation) {
+    let units = 0n, unknown = 0n, estimated = false;
+    for (const op of operations) {
+        if (op.source === "import" ||
+            op.state === "released" ||
+            (operation !== undefined && op.operation !== operation))
+            continue;
+        const r = observedReceipt(op);
+        const occurredAt = r?.occurredAt ?? op.createdAt;
+        if (Date.parse(occurredAt) < Date.parse(window.from) ||
+            Date.parse(occurredAt) >= Date.parse(window.to))
+            continue;
+        if (!r || r.cost.certainty === "unknown") {
+            unknown++;
+            continue;
+        }
+        units += r.cost.money.units;
+        if (r.cost.certainty === "estimated")
+            estimated = true;
+    }
+    return {
+        total: unknown > 0n
+            ? { certainty: "unknown", money: null }
+            : { certainty: estimated ? "estimated" : "measured", money: { units, currency: "USD" } },
+        unknown,
+    };
+}
+/** Pure preparation. Adapters commit every change, projection and journal in one transaction. */
+export function prepareBillingImport(i, snapshot, now) {
+    const error = validateBillingImportInput(i);
+    if (error)
+        return { result: error, changes: [], familyId: "" };
+    const window = normalizedWindow(i.window), familyId = billingFamilyId(i);
+    const id = canonical([familyId, i.fileHash]);
+    // expectedPreviousImportId is a concurrency precondition, not imported content.
+    const { expectedPreviousImportId: _, ...content } = i;
+    const identity = canonical({ ...content, window });
+    const reject = (reason, line) => ({
+        familyId,
+        changes: [],
+        result: {
+            outcome: "rejected",
+            reason,
+            latestImportId: snapshot.latestImportId,
+            ...(line === undefined ? {} : { line }),
+        },
+    });
+    const previous = snapshot.imports.find((x) => x.record.id === id);
+    if (previous)
+        return previous.identity === identity
+            ? {
+                familyId,
+                changes: [],
+                result: { outcome: "imported", replayed: true, record: copy(previous.record) },
+            }
+            : reject("payload_conflict");
+    if (snapshot.latestImportId !== i.expectedPreviousImportId)
+        return reject("previous_import_conflict");
+    // A retained export cannot change its accounting owner when a connection transfers.
+    if (snapshot.imports.some((x) => x.record.scope.principal !== i.scope.principal))
+        return reject("evidence_conflict");
+    const scope = {
+        ...copy(i.scope),
+        ...(i.scope.tags ? { tags: normalizeTags(i.scope.tags) } : {}),
+    };
+    const operations = snapshot.operations.filter((op) => op.scope.namespace === scope.namespace &&
+        op.scope.principal === scope.principal &&
+        op.scope.connection === scope.connection &&
+        op.provider === i.provider);
+    const recordedAt = now.toISOString();
+    const changes = [], matched = [], unobserved = [];
+    const reconciliation = (kind, entryWindow, units, suffix, operation) => {
+        const { total, unknown } = ledger(operations, entryWindow, operation);
+        return {
+            id: id + ":" + suffix,
+            importId: id,
+            scope: copy(scope),
+            provider: i.provider,
+            ...(operation === undefined ? {} : { operation }),
+            window: normalizedWindow(entryWindow),
+            kind,
+            ledgerTotal: total,
+            evidenceTotal: { units, currency: "USD" },
+            differenceUnits: total.money === null ? null : units - total.money.units,
+            unknownOperations: unknown,
+            evidenceRef: id,
+        };
+    };
+    const reconciliations = [];
+    for (const [n, line] of i.lines.entries()) {
+        if (line.providerRequestId === undefined) {
+            reconciliations.push(reconciliation("aggregate", line.window, line.cost.units, "aggregate:" + n, line.operation));
+            continue;
+        }
+        const candidates = operations.filter((op) => op.receipts.some((r) => r.providerRequestId === line.providerRequestId));
+        if (candidates.length > 1)
+            return reject("ambiguous_request", n);
+        const before = candidates[0] ?? null;
+        // Historical receipts may carry different request ids for the same operation.
+        // Two lines must never create competing updates from the same version.
+        if (before && matched.includes(before.operationId))
+            return reject("ambiguous_request", n);
+        if (before?.lease && Date.parse(before.lease.expiresAt) > now.getTime())
+            return reject("active_operation", n);
+        if (before && !["pending", "settled"].includes(before.state))
+            return reject("operation_state", n);
+        if (before && line.operation !== undefined && before.operation !== line.operation)
+            return reject("evidence_conflict", n);
+        const effective = before ? currentReceipt(before) : undefined;
+        if (before?.state === "settled" && !effective)
+            return reject("evidence_conflict", n);
+        const receipt = {
+            id: id + ":receipt:" + n,
+            source: "import",
+            ...(effective ? { supersedes: effective.id } : {}),
+            measurements: copy(effective?.measurements ?? [{ unit: "requests", quantity: null, certainty: "unknown" }]),
+            cost: { certainty: "measured", money: copy(line.cost) },
+            providerRequestId: line.providerRequestId,
+            evidenceRef: id,
+            occurredAt: new Date(line.occurredAt).toISOString(),
+            recordedAt,
+            cached: effective?.cached ?? false,
+            failed: effective?.failed ?? false,
+            ...(effective?.providerPriceVersion
+                ? { providerPriceVersion: effective.providerPriceVersion }
+                : {}),
+        };
+        // cents is a cost measurement, never a customer credit-price measurement.
+        receipt.measurements = receipt.measurements.map((m) => m.unit === "cents"
+            ? {
+                unit: "cents",
+                certainty: "measured",
+                quantity: { value: line.cost.units, scale: 4, unit: "cents" },
+            }
+            : m);
+        if (before?.estimate.some((q) => q.unit === "cents") &&
+            !receipt.measurements.some((m) => m.unit === "cents"))
+            receipt.measurements = [
+                ...receipt.measurements,
+                {
+                    unit: "cents",
+                    certainty: "measured",
+                    quantity: { value: line.cost.units, scale: 4, unit: "cents" },
+                },
+            ];
+        const state = receipt.measurements.some((m) => m.certainty === "unknown") ||
+            before?.estimate.some((q) => !receipt.measurements.some((m) => m.unit === q.unit && m.quantity !== null))
+            ? "pending"
+            : "settled";
+        const after = before
+            ? {
+                ...copy(before),
+                state,
+                version: before.version + 1,
+                updatedAt: recordedAt,
+                lease: null,
+                receipts: [...copy(before.receipts), receipt],
+            }
+            : {
+                ...copy(i.attribution),
+                operationId: id + ":unobserved:" + n,
+                scope: copy(scope),
+                source: "import",
+                surface: "programmatic",
+                provider: i.provider,
+                operation: line.operation ?? "unobserved",
+                estimate: [],
+                budgetEpochs: [],
+                state,
+                version: 1,
+                reservationExpiresAt: recordedAt,
+                createdAt: recordedAt,
+                updatedAt: recordedAt,
+                lease: null,
+                receipts: [receipt],
+            };
+        if (before)
+            matched.push(before.operationId);
+        else
+            unobserved.push(after.operationId);
+        changes.push({ before: before ? copy(before) : null, after, receipt });
+    }
+    reconciliations.push(reconciliation("import_total", window, i.lines.reduce((sum, line) => sum + line.cost.units, 0n), "total"));
+    const record = {
+        id,
+        scope,
+        provider: i.provider,
+        fileHash: i.fileHash,
+        window,
+        recordedAt,
+        ...(snapshot.latestImportId ? { supersedes: snapshot.latestImportId } : {}),
+        matchedOperationIds: matched,
+        unobservedOperationIds: unobserved,
+        reconciliations,
+        alerts: [],
+    };
+    return {
+        familyId,
+        changes,
+        stored: { identity, record },
+        result: { outcome: "imported", replayed: false, record },
+    };
+}
+export function readBillingImports(records, q, now) {
+    const successors = new Map(records.filter((r) => r.supersedes).map((r) => [r.supersedes, r.id]));
+    const scoped = records
+        .filter((r) => r.scope.namespace === q.scope.namespace &&
+        r.scope.principal === q.scope.principal &&
+        r.scope.connection === q.connection &&
+        Date.parse(r.window.from) < Date.parse(q.to) &&
+        Date.parse(q.from) < Date.parse(r.window.to) &&
+        (q.history || !successors.has(r.id)))
+        .sort((a, b) => b.recordedAt.localeCompare(a.recordedAt) || a.id.localeCompare(b.id));
+    const limit = q.limit ?? 1000;
+    return {
+        records: scoped.slice(0, limit).map((r) => ({
+            ...copy(r),
+            ...(successors.has(r.id) ? { supersededBy: successors.get(r.id) } : {}),
+        })),
+        asOf: now.toISOString(),
+        truncated: scoped.length > limit,
+    };
+}

package/dist/conformance/billing.d.ts

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

package/dist/conformance/billing.js

@@ -0,0 +1,372 @@
+import { beforeEach, afterEach, describe, expect, test } from "vitest";
+import { input, receipt, command, ref, quantity, budget } from "./helpers.js";
+export function billingTests(factory, capabilities) {
+    describe("billing import guarantees", () => {
+        let f;
+        beforeEach(async () => {
+            f = await factory();
+        });
+        afterEach(async () => f.close());
+        const window = { from: "2026-09-01T00:00:00.000Z", to: "2026-10-01T00:00:00.000Z" };
+        const bill = (overrides = {}) => ({
+            scope: { namespace: "test", principal: "u1", connection: "c1" },
+            provider: "search",
+            fileHash: "a".repeat(64),
+            window,
+            expectedPreviousImportId: null,
+            attribution: { fundingSource: "byok", costOwner: "u1" },
+            lines: [
+                {
+                    providerRequestId: "request-a",
+                    operation: "search",
+                    occurredAt: "2026-09-23T12:00:00.000Z",
+                    cost: { units: 100n, currency: "USD" },
+                },
+            ],
+            ...overrides,
+        });
+        const read = (history = false) => f.store.billingImports({
+            scope: { namespace: "test", principal: "u1" },
+            connection: "c1",
+            ...window,
+            history,
+        });
+        const imported = async (i = bill()) => {
+            const result = await f.store.importBilling(i);
+            if (result.outcome !== "imported")
+                throw new Error("Import fixture: " + result.outcome);
+            return result.record;
+        };
+        const observed = async (id = "request-a", r = receipt(), overrides = {}) => {
+            const i = input(overrides), reservation = await f.store.reserve(i);
+            if (reservation.outcome !== "reserved")
+                throw new Error("Reservation fixture");
+            const grant = await f.store.markDispatchIntent({
+                ...command(reservation.operation),
+                holder: "h",
+                leaseTtlMs: 1000,
+            });
+            if (!("granted" in grant) || !grant.granted)
+                throw new Error("Dispatch fixture");
+            const result = await f.store.settle({
+                ...command(grant.operation),
+                authority: { kind: "lease", leaseId: grant.lease.leaseId },
+                receipt: { ...r, providerRequestId: id },
+            });
+            if (result.outcome !== "settled")
+                throw new Error("Settlement fixture");
+            return result.operation;
+        };
+        test("exact correction preserves frozen funding, customer price and quantity certainty", async () => {
+            const before = await observed("request-a", receipt({
+                measurements: [
+                    { unit: "requests", quantity: quantity(3n), certainty: "estimated" },
+                    {
+                        unit: "customer_cents",
+                        quantity: quantity(900n, "customer_cents", 4),
+                        certainty: "measured",
+                    },
+                ],
+            }), {
+                fundingSource: "platform",
+                costOwner: "platform",
+                creditAccountRef: "original-wallet",
+                customerPriceVersion: "tariff-v1",
+                providerPriceVersion: "provider-v1",
+                platformPools: ["original-pool"],
+                scope: {
+                    namespace: "test",
+                    principal: "u1",
+                    connection: "c1",
+                    providerCredentialVersion: "key-v1",
+                    accessCredential: { kind: "api_key", id: "caller-v1" },
+                },
+            });
+            const record = await imported(bill({
+                attribution: {
+                    fundingSource: "byok",
+                    costOwner: "new-owner",
+                    customerPriceVersion: "tariff-v2",
+                },
+                lines: [{ ...bill().lines[0], cost: { units: 9007199254740993n, currency: "USD" } }],
+            }));
+            const after = (await f.store.getOperation(ref(before)));
+            expect(after).toMatchObject({
+                fundingSource: "platform",
+                costOwner: "platform",
+                creditAccountRef: "original-wallet",
+                customerPriceVersion: "tariff-v1",
+                providerPriceVersion: "provider-v1",
+                platformPools: ["original-pool"],
+                scope: before.scope,
+                budgetEpochs: before.budgetEpochs,
+            });
+            expect(after.receipts).toHaveLength(2);
+            expect(after.receipts[0]).toEqual(before.receipts[0]);
+            expect(after.receipts[1]).toMatchObject({
+                source: "import",
+                supersedes: before.receipts[0].id,
+                evidenceRef: record.id,
+                cost: { certainty: "measured", money: { units: 9007199254740993n, currency: "USD" } },
+                measurements: before.receipts[0].measurements,
+            });
+            expect(after.version).toBe(before.version + 1);
+        });
+        test("identical replay survives new commands and does not reapply any receipt", async () => {
+            const before = await observed(), first = await imported(), after = await f.store.getOperation(ref(before));
+            const replay = await f.store.importBilling(bill());
+            expect(replay).toEqual({ outcome: "imported", replayed: true, record: first });
+            expect(await f.store.getOperation(ref(before))).toEqual(after);
+            expect((await read(true)).records).toHaveLength(1);
+            expect(await f.store.importBilling(bill({ lines: [{ ...bill().lines[0], cost: { units: 101n, currency: "USD" } }] }))).toMatchObject({ outcome: "rejected", reason: "payload_conflict" });
+            expect(await f.store.getOperation(ref(before))).toEqual(after);
+        });
+        test("revisions supersede journal evidence; replay of an older file cannot restore old costs", async () => {
+            const op = await observed(), first = await imported();
+            const second = await imported(bill({
+                fileHash: "b".repeat(64),
+                expectedPreviousImportId: first.id,
+                lines: [{ ...bill().lines[0], cost: { units: 200n, currency: "USD" } }],
+            }));
+            expect(second.supersedes).toBe(first.id);
+            expect((await read()).records.map((r) => r.id)).toEqual([second.id]);
+            const history = (await read(true)).records;
+            expect(history).toHaveLength(2);
+            expect(history.find((r) => r.id === first.id)?.supersededBy).toBe(second.id);
+            await f.store.importBilling(bill());
+            expect((await f.store.getOperation(ref(op))).receipts.at(-1).cost.money?.units).toBe(200n);
+            expect(await f.store.importBilling(bill({ fileHash: "c".repeat(64), expectedPreviousImportId: first.id }))).toMatchObject({
+                outcome: "rejected",
+                reason: "previous_import_conflict",
+                latestImportId: second.id,
+            });
+        });
+        test("concurrent same-file replays and competing first imports each write once", async () => {
+            await observed();
+            const results = await Promise.all([
+                f.store.importBilling(bill()),
+                f.store.importBilling(bill()),
+            ]);
+            expect(results.filter((r) => r.outcome === "imported" && !r.replayed)).toHaveLength(1);
+            expect(results.filter((r) => r.outcome === "imported" && r.replayed)).toHaveLength(1);
+            const first = (await read()).records[0];
+            const revisions = await Promise.all(["b", "c"].map((h) => f.store.importBilling(bill({ fileHash: h.repeat(64), expectedPreviousImportId: first.id }))));
+            expect(revisions.filter((r) => r.outcome === "imported")).toHaveLength(1);
+            expect(revisions.filter((r) => r.outcome === "rejected" && r.reason === "previous_import_conflict")).toHaveLength(1);
+        });
+        test.each([
+            { scope: { namespace: "test", principal: "u2", connection: "c1" } },
+            { scope: { namespace: "test", principal: "u1", connection: "c2" } },
+            { provider: "other-provider" },
+            { scope: { namespace: "other", principal: "u1", connection: "c1" } },
+        ])("request ids are scoped independently to owner, connection, provider and namespace", async (foreignScope) => {
+            const own = await observed("request-a", receipt({ cost: { certainty: "estimated", money: { units: 20n, currency: "USD" } } }));
+            const foreign = await observed("request-a", receipt(), foreignScope);
+            const record = await imported();
+            expect(record.matchedOperationIds).toEqual([own.operationId]);
+            expect(await f.store.getOperation(ref(foreign))).toEqual(foreign);
+            expect((await f.store.billingImports({
+                scope: { namespace: "test", principal: "u2" },
+                connection: "c1",
+                ...window,
+            })).records).toEqual([]);
+        });
+        test("ambiguous matching rejects the complete batch before any accounting mutation", async () => {
+            const good = await observed("good"), a = await observed("duplicate"), b = await observed("duplicate");
+            const result = await f.store.importBilling(bill({
+                lines: [
+                    { ...bill().lines[0], providerRequestId: "good" },
+                    { ...bill().lines[0], providerRequestId: "duplicate" },
+                ],
+            }));
+            expect(result).toMatchObject({ outcome: "rejected", reason: "ambiguous_request", line: 1 });
+            for (const op of [good, a, b])
+                expect(await f.store.getOperation(ref(op))).toEqual(op);
+            expect((await read(true)).records).toEqual([]);
+        });
+        test("aggregate lines report exact signed differences without allocating cost to operations", async () => {
+            const a = await observed("a", receipt({ cost: { certainty: "measured", money: { units: 700n, currency: "USD" } } }));
+            const b = await observed("b", receipt({ cost: { certainty: "estimated", money: { units: 300n, currency: "USD" } } }));
+            const record = await imported(bill({
+                lines: [{ occurredAt: window.from, window, cost: { units: 900n, currency: "USD" } }],
+            }));
+            expect(record.reconciliations.find((e) => e.kind === "aggregate")).toMatchObject({
+                ledgerTotal: { certainty: "estimated", money: { units: 1000n } },
+                evidenceTotal: { units: 900n },
+                differenceUnits: -100n,
+                unknownOperations: 0n,
+            });
+            expect(record.matchedOperationIds).toEqual([]);
+            expect(record.unobservedOperationIds).toEqual([]);
+            expect(await f.store.getOperation(ref(a))).toEqual(a);
+            expect(await f.store.getOperation(ref(b))).toEqual(b);
+        });
+        test("two historical request ids cannot apply competing corrections to one operation", async () => {
+            const original = await observed("old-id");
+            const corrected = await f.store.correct({
+                ...command(original),
+                replacesReceiptId: original.receipts[0].id,
+                reason: "corrected provider identity",
+                authority: { kind: "late_evidence", source: "provider correction" },
+                receipt: receipt({ providerRequestId: "new-id" }),
+            });
+            if (corrected.outcome !== "settled")
+                throw new Error("Correction fixture");
+            const result = await f.store.importBilling(bill({
+                lines: [
+                    { ...bill().lines[0], providerRequestId: "old-id" },
+                    { ...bill().lines[0], providerRequestId: "new-id" },
+                ],
+            }));
+            expect(result).toMatchObject({ outcome: "rejected", reason: "ambiguous_request", line: 1 });
+            expect(await f.store.getOperation(ref(corrected.operation))).toEqual(corrected.operation);
+            expect((await read(true)).records).toEqual([]);
+        });
+        test("operation-specific aggregate comparisons exclude other operations and allow disjoint categories", async () => {
+            const search = await observed("search-a", receipt({ cost: { certainty: "measured", money: { units: 700n, currency: "USD" } } }));
+            const images = await observed("images-a", receipt({ cost: { certainty: "measured", money: { units: 300n, currency: "USD" } } }), { operation: "images" });
+            const record = await imported(bill({
+                lines: [
+                    {
+                        occurredAt: window.from,
+                        window,
+                        operation: "search",
+                        cost: { units: 600n, currency: "USD" },
+                    },
+                    {
+                        occurredAt: window.from,
+                        window,
+                        operation: "images",
+                        cost: { units: 350n, currency: "USD" },
+                    },
+                ],
+            }));
+            expect(record.reconciliations.filter((e) => e.kind === "aggregate")).toMatchObject([
+                { operation: "search", ledgerTotal: { money: { units: 700n } }, differenceUnits: -100n },
+                { operation: "images", ledgerTotal: { money: { units: 300n } }, differenceUnits: 50n },
+            ]);
+            expect(await f.store.getOperation(ref(search))).toEqual(search);
+            expect(await f.store.getOperation(ref(images))).toEqual(images);
+        });
+        test("unknown ledger costs remain unknown and an omitted revised line does not manufacture zero", async () => {
+            const a = await observed("a", receipt({ cost: { certainty: "unknown", money: null } }));
+            const record = await imported(bill({
+                lines: [{ occurredAt: window.from, window, cost: { units: 900n, currency: "USD" } }],
+            }));
+            expect(record.reconciliations[0]).toMatchObject({
+                ledgerTotal: { certainty: "unknown", money: null },
+                differenceUnits: null,
+                unknownOperations: 1n,
+            });
+            expect(await f.store.getOperation(ref(a))).toEqual(a);
+            const revision = await imported(bill({ fileHash: "b".repeat(64), expectedPreviousImportId: record.id, lines: [] }));
+            expect(revision.reconciliations[0]).toMatchObject({
+                evidenceTotal: { units: 0n },
+                ledgerTotal: { certainty: "unknown", money: null },
+                differenceUnits: null,
+            });
+            expect(await f.store.getOperation(ref(a))).toEqual(a);
+        });
+        test("unobserved calls retain unknown quantity, never gain dispatch and revise without duplicate operations", async () => {
+            const first = await imported(), id = first.unobservedOperationIds[0];
+            const op = (await f.store.getOperation({
+                namespace: "test",
+                principal: "u1",
+                operationId: id,
+            }));
+            expect(op).toMatchObject({
+                source: "import",
+                surface: "programmatic",
+                state: "pending",
+                budgetEpochs: [],
+                estimate: [],
+                lease: null,
+            });
+            expect(op.receipts[0]).toMatchObject({
+                source: "import",
+                cost: { certainty: "measured" },
+                measurements: [{ unit: "requests", certainty: "unknown", quantity: null }],
+            });
+            expect(await f.store.markDispatchIntent({ ...command(op), holder: "h", leaseTtlMs: 1000 })).toMatchObject({ granted: false });
+            const second = await imported(bill({ fileHash: "b".repeat(64), expectedPreviousImportId: first.id }));
+            expect(second.unobservedOperationIds).toEqual([]);
+            expect(second.matchedOperationIds).toEqual([id]);
+            expect((await f.store.getOperation(ref(op))).receipts).toHaveLength(2);
+        });
+        test("known invoice cost does not release unresolved quantities or original customer exposure", async () => {
+            const before = await observed("request-a", receipt({
+                measurements: [
+                    { unit: "requests", certainty: "unknown", quantity: null },
+                    {
+                        unit: "customer_cents",
+                        certainty: "measured",
+                        quantity: quantity(99n, "customer_cents"),
+                    },
+                ],
+                cost: { certainty: "unknown", money: null },
+            }));
+            const record = await imported(), after = (await f.store.getOperation(ref(before)));
+            expect(after.state).toBe("pending");
+            expect(after.receipts.at(-1)).toMatchObject({
+                measurements: before.receipts[0].measurements,
+                cost: { certainty: "measured", money: { units: 100n } },
+                evidenceRef: record.id,
+            });
+            expect(after.budgetEpochs).toEqual(before.budgetEpochs);
+        });
+        test("cost import updates existing budget exposure and reports threshold crossings once", async () => {
+            f.budgets.push(budget({
+                unit: "cents",
+                limit: quantity(20n, "cents"),
+                onExceed: "allow",
+                alerts: [{ at: { percent: 50 } }, { at: { percent: 100 } }],
+            }));
+            const before = await observed("request-a", receipt({
+                cost: { certainty: "measured", money: { units: 100000n, currency: "USD" } },
+                measurements: [
+                    { unit: "requests", certainty: "measured", quantity: quantity() },
+                    { unit: "cents", certainty: "measured", quantity: quantity(10n, "cents") },
+                ],
+            }), { estimate: [quantity(), quantity(5n, "cents")] });
+            const i = bill({
+                lines: [{ ...bill().lines[0], cost: { units: 300000n, currency: "USD" } }],
+            }), first = await imported(i);
+            expect(first.alerts).toHaveLength(1);
+            expect(first.alerts[0].at).toEqual({ percent: 100 });
+            const [status] = await f.store.applicableBudgets({
+                scope: before.scope,
+                surface: before.surface,
+                source: before.source,
+                units: ["cents"],
+            });
+            expect(status.used).toEqual(quantity(300000n, "cents", 4));
+            expect(await f.store.importBilling(i)).toMatchObject({
+                outcome: "imported",
+                replayed: true,
+                record: { alerts: first.alerts },
+            });
+            const second = await imported({
+                ...i,
+                fileHash: "b".repeat(64),
+                expectedPreviousImportId: first.id,
+            });
+            expect(second.alerts).toEqual([]);
+        });
+        test.skipIf(!capabilities.durable)("durable import and revision survive runtime recreation", async () => {
+            const before = await observed(), first = await imported();
+            if (!f.restart)
+                throw new Error("Durable billing adapter must provide restart");
+            f.store = await f.restart();
+            expect(await f.store.importBilling(bill())).toEqual({
+                outcome: "imported",
+                replayed: true,
+                record: first,
+            });
+            expect((await f.store.getOperation(ref(before))).receipts).toHaveLength(2);
+            const second = await imported(bill({ fileHash: "b".repeat(64), expectedPreviousImportId: first.id }));
+            f.store = await f.restart();
+            expect((await read()).records[0].id).toBe(second.id);
+            expect((await f.store.getOperation(ref(before))).receipts).toHaveLength(3);
+        });
+    });
+}

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,8 @@ 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";
+import { billingTests } from "./billing.js";
 export function runStoreConformance(factory, capabilities) {
     describe("store conformance", () => {
         reserveTests(factory);
@@ -23,6 +25,8 @@ export function runStoreConformance(factory, capabilities) {
         recoveryTests(factory);
         readsTests(factory, capabilities);
         operationsTests(factory);
+        counterTests(factory);
+        billingTests(factory, capabilities);
         propertyTests(factory);
         capabilityTests(factory, capabilities);
         afterAll(() => console.info("Skipped guarantees: " +

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 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 { BillingImportInput, BillingImportResult, BillingImportsQuery, BillingImportsPage } 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.
@@ -12,6 +13,8 @@ import type { ExpireReservationsInput, ExpireReservationsResult, Budget, Applica
  * Adapters prove these guarantees through one conformance suite, without callback locks.
  */
 export interface Store {
+    importBilling(input: BillingImportInput): Promise<BillingImportResult>;
+    billingImports(query: BillingImportsQuery): Promise<BillingImportsPage>;
     expireReservations(input: ExpireReservationsInput): Promise<ExpireReservationsResult>;
     reserve(input: ReserveInput, policy?: AdmissionPolicy): Promise<ReserveResult>;
     markDispatchIntent(input: DispatchIntentInput): Promise<DispatchGrant>;
@@ -20,9 +23,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 +37,7 @@ 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";
+export { prepareBillingImport, billingFamilyId, readBillingImports, validateBillingImportInput, validateBillingImportsQuery, } from "./billing.js";
+export type { StoredBillingImport, BillingSnapshot, BillingPreparation } from "./billing.js";

package/dist/index.js

@@ -2,3 +2,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";
+export { prepareBillingImport, billingFamilyId, readBillingImports, validateBillingImportInput, validateBillingImportsQuery, } from "./billing.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,6 +1,10 @@
 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";
+import { billingFamilyId, prepareBillingImport, readBillingImports, validateBillingImportInput, validateBillingImportsQuery, } from "../billing.js";
+import { reachedBySettlement, recordAlerts } from "./admission.js";
+import { InvalidInput, key, semantics } from "./state.js";
 export function createMemoryStore({ clock, budgets }) {
     const state = {
         clock,
@@ -15,6 +19,51 @@ export function createMemoryStore({ clock, budgets }) {
         identities: new Map(),
     };
     return {
+        importBilling: async (i) => {
+            const invalid = validateBillingImportInput(i);
+            if (invalid)
+                return invalid;
+            const family = billingFamilyId(i), imports = (state.billingImports ??= new Map()), families = (state.billingFamilies ??= new Map());
+            const preparation = prepareBillingImport(i, {
+                operations: [...state.operations.values()],
+                imports: [...imports.values()].filter((x) => billingFamilyId({
+                    ...i,
+                    scope: x.record.scope,
+                    provider: x.record.provider,
+                    window: x.record.window,
+                }) === family),
+                latestImportId: families.get(family) ?? null,
+            }, clock.now());
+            if (preparation.stored) {
+                const staged = {
+                    ...state,
+                    operations: new Map(state.operations),
+                    alerts: new Set(state.alerts),
+                };
+                for (const change of preparation.changes) {
+                    const op = copy(change.after), pk = key(op.scope.namespace, op.operationId);
+                    staged.operations.set(pk, op);
+                }
+                preparation.stored.record.alerts = preparation.changes.flatMap((change) => recordAlerts(staged, i.scope.namespace, reachedBySettlement(staged, change.after)));
+                state.operations = staged.operations;
+                state.alerts = staged.alerts;
+                for (const change of preparation.changes) {
+                    if (!change.before)
+                        state.identities.set(key(change.after.scope.namespace, change.after.operationId), semantics(change.after));
+                    if (change.before?.lease)
+                        state.leaseKinds.delete(change.before.lease.leaseId);
+                }
+                imports.set(preparation.stored.record.id, copy(preparation.stored));
+                families.set(family, preparation.stored.record.id);
+            }
+            return copy(preparation.result);
+        },
+        billingImports: async (q) => {
+            const invalid = validateBillingImportsQuery(q);
+            if (invalid)
+                throw new InvalidInput(invalid.field, invalid.reason);
+            return readBillingImports([...(state.billingImports?.values() ?? [])].map((x) => x.record), q, clock.now());
+        },
         expireReservations: async (i) => expireReservations(state, i),
         reserve: async (i, policy) => reserve(state, i, policy),
         getOperation: async (ref) => copy(find(state, ref)),
@@ -24,6 +73,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,13 +13,15 @@ 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;
 export declare const maxMoneyUnits: bigint;
 export declare function validateQuantity(q: Quantity): void;
 export type State = {
+    billingImports?: Map<string, import("../billing.js").StoredBillingImport>;
+    billingFamilies?: Map<string, string>;
     /** Optional adapter projection, read in the same transaction as admission. */
     readBudgetUsage?: (budget: Budget, epoch: string) => {
         used: Quantity;
@@ -53,5 +56,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.5.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.5.0"
   },
   "sideEffects": false,
   "publishConfig": {