@usagekit/store 0.4.0 → 0.6.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/properties.js

@@ -2,8 +2,10 @@ import { describe, expect, test } from "vitest";
 import fc from "fast-check";
 import { input, command, ref, receipt, unknownReceipt, budget, quantity } from "./helpers.js";
 const numRuns = globalThis.process?.env?.CI === "true" ? 1000 : 200;
+// CI executes five times as many cases, including isolated durable database fixtures.
+const timeout = numRuns * 300;
 export function propertyTests(factory) {
-    describe("generated command interleavings", () => {
+    describe("generated command interleavings", { timeout }, () => {
         test("holders never reacquire dispatch and mutations preserve state invariants", async () => {
             await fc.assert(fc.asyncProperty(fc.integer({ min: 2, max: 5 }), fc.array(fc.record({
                 kind: fc.constantFrom("intent", "renew", "settle", "correct", "release", "claim", "advanceClock"),

package/dist/conformance/suite.js

@@ -12,6 +12,7 @@ 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);
@@ -25,6 +26,7 @@ export function runStoreConformance(factory, capabilities) {
         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,4 +1,5 @@
 import type { AdmissionPolicy } 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.
@@ -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>;
@@ -36,3 +39,5 @@ 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

@@ -3,3 +3,4 @@ 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/memory-store.js

@@ -2,6 +2,9 @@ import { aggregate, definedBudgets, applicableBudgets, listOperations } from "./
 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,
@@ -16,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)),

package/dist/memory/state.d.ts

@@ -20,6 +20,8 @@ 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usagekit/store",
-  "version": "0.4.0",
+  "version": "0.6.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.4.0"
+    "@usagekit/core": "0.6.0"
   },
   "sideEffects": false,
   "publishConfig": {
@@ -49,5 +49,14 @@
     "fast-check": {
       "optional": true
     }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/msniezynski/usagekit.git",
+    "directory": "packages/store"
+  },
+  "homepage": "https://usagekit.dev",
+  "bugs": {
+    "url": "https://github.com/msniezynski/usagekit/issues"
   }
 }