@usagekit/store 0.1.0

package/dist/memory/admission.js

@@ -0,0 +1,105 @@
+import { defaultBudgetOrder } from "@usagekit/core";
+import { resolveWindow } from "@usagekit/core";
+import { canonical } from "./state.js";
+export function currentBudgets(s) {
+    const map = new Map();
+    for (const b of s.budgets) {
+        const k = canonical([b.scope.namespace, b.id]);
+        if ((map.get(k)?.version ?? -1) < b.version)
+            map.set(k, b);
+    }
+    return [...map.values()];
+}
+export function matches(b, i) {
+    if (b.scope.namespace !== i.scope.namespace || (b.surface !== "any" && b.surface !== i.surface))
+        return false;
+    switch (b.scope.kind) {
+        case "principal":
+            return b.scope.principal === i.scope.principal;
+        case "group":
+            return b.scope.group === i.scope.group;
+        case "connection":
+            return b.scope.connection === i.scope.connection;
+        case "access_credential":
+            return canonical(b.scope.accessCredential) === canonical(i.scope.accessCredential);
+        case "platform_pool":
+            return i.platformPools?.includes(b.scope.poolId) ?? false;
+    }
+}
+export function plus(a, b) {
+    const scale = Math.max(a.scale, b.scale);
+    return {
+        unit: a.unit,
+        scale,
+        value: a.value * 10n ** BigInt(scale - a.scale) + b.value * 10n ** BigInt(scale - b.scale),
+    };
+}
+export const greater = (a, b) => a.value * 10n ** BigInt(b.scale) > b.value * 10n ** BigInt(a.scale);
+export function effective(op) {
+    return [...op.receipts]
+        .reverse()
+        .find((r) => !op.receipts.some((next) => next.supersedes === r.id));
+}
+export function status(s, b) {
+    const epoch = resolveWindow(b.window, s.clock.now());
+    let used = { value: 0n, scale: 0, unit: b.unit }, reserved = { ...used };
+    const projected = s.readBudgetUsage?.(b, epoch.epoch);
+    if (projected) {
+        used = projected.used;
+        reserved = projected.reserved;
+    }
+    else
+        for (const op of s.operations.values()) {
+            if (op.scope.namespace !== b.scope.namespace ||
+                !op.budgetEpochs.some((e) => e.budgetId === b.id && e.epoch === epoch.epoch))
+                continue;
+            if (op.state === "settled") {
+                const m = effective(op)?.measurements.find((m) => m.unit === b.unit);
+                if (m?.quantity)
+                    used = plus(used, m.quantity);
+            }
+            else if (op.state !== "released") {
+                const q = op.estimate.find((q) => q.unit === b.unit);
+                if (q)
+                    reserved = plus(reserved, q);
+            }
+        }
+    const total = plus(used, reserved);
+    const remaining = b.limit ? plus(b.limit, { ...total, value: -total.value }) : null;
+    return { budget: b, epoch, used, reserved, remaining };
+}
+export function applicable(s, i) {
+    return currentBudgets(s)
+        .filter((b) => matches(b, i))
+        .map((b) => status(s, b));
+}
+export function admission(s, i, policy) {
+    const order = policy?.budgetOrder ?? defaultBudgetOrder;
+    const budgets = currentBudgets(s)
+        .filter((b) => matches(b, i))
+        .sort((a, b) => order.indexOf(a.scope.kind) - order.indexOf(b.scope.kind) || a.id.localeCompare(b.id));
+    const warnings = [], epochs = [];
+    for (const b of budgets) {
+        const estimate = i.estimate.find((q) => q.unit === b.unit);
+        if (!estimate)
+            return { invalid: b.unit, warnings, epochs };
+    }
+    for (const b of budgets) {
+        const st = status(s, b);
+        epochs.push({ budgetId: b.id, budgetVersion: b.version, ...st.epoch });
+        const estimate = i.estimate.find((q) => q.unit === b.unit);
+        if (b.limit && greater(plus(plus(st.used, st.reserved), estimate), b.limit)) {
+            const exceeded = {
+                code: "allowance_exceeded",
+                budget: b,
+                used: st.used,
+                reserved: st.reserved,
+                resetsAt: st.epoch.endsAt,
+            };
+            if (b.onExceed === "block")
+                return { exceeded, warnings, epochs };
+            warnings.push(exceeded);
+        }
+    }
+    return { warnings, epochs };
+}

package/dist/memory/commands.d.ts

@@ -0,0 +1,22 @@
+import type { AdmissionPolicy } from "@usagekit/core";
+import type { ReserveInput, ReserveResult, Operation } from "@usagekit/core";
+import type { State } from "./state.js";
+export declare function reserve(s: State, i: ReserveInput, policy?: AdmissionPolicy): ReserveResult;
+import type { DispatchIntentInput, DispatchGrant, LeaseRenewalInput, LeaseRenewal } from "@usagekit/core";
+export declare function active(s: State, op: Operation): boolean;
+export declare function touch(s: State, op: Operation): void;
+export declare function validTtl(ttl: number, field?: string): void;
+export declare function intent(s: State, i: DispatchIntentInput): DispatchGrant;
+export declare function renew(s: State, i: LeaseRenewalInput): LeaseRenewal;
+import type { SettleInput, CorrectionInput, SettleResult, ReleaseInput, ReleaseResult, Receipt } from "@usagekit/core";
+export declare function validateReceipt(r: Receipt): void;
+export declare function settle(s: State, i: SettleInput | CorrectionInput, correction?: boolean): SettleResult;
+export declare function release(s: State, i: ReleaseInput): ReleaseResult;
+import type { RecoveryClaimInput, RecoveryClaim } from "@usagekit/core";
+export declare function claim(s: State, i: RecoveryClaimInput): RecoveryClaim;
+import type { ExpireReservationsInput } from "@usagekit/core";
+export declare function expireReservations(s: State, i: ExpireReservationsInput): {
+    outcome: "expired";
+    count: number;
+    hasMore: boolean;
+};

package/dist/memory/commands.js

@@ -0,0 +1,249 @@
+import { admission } from "./admission.js";
+import { copy, key, semantics, validateQuantity, InvalidInput } from "./state.js";
+export function reserve(s, i, policy) {
+    validTtl(i.reservationTtlMs ?? 300000, "reservationTtlMs");
+    i.estimate.forEach(validateQuantity);
+    if (new Set(i.estimate.map((q) => q.unit)).size !== i.estimate.length)
+        throw new InvalidInput("estimate", "duplicate unit");
+    expireReservations(s, { namespace: i.scope.namespace });
+    const k = key(i.scope.namespace, i.operationId), existing = s.operations.get(k);
+    if (existing)
+        return s.identities.get(k) === semantics(i)
+            ? {
+                outcome: "reserved",
+                replayed: true,
+                warnings: copy(s.warnings.get(k) ?? []),
+                operation: copy(existing),
+            }
+            : { outcome: "conflict", reason: "semantic_mismatch", operation: copy(existing) };
+    const check = admission(s, i, policy);
+    if (check.invalid)
+        return {
+            outcome: "invalid",
+            reason: "missing_estimate_unit",
+            unit: check.invalid,
+            operation: null,
+        };
+    if (check.exceeded)
+        return { outcome: "exceeded", exceeded: copy(check.exceeded), operation: null };
+    const now = s.clock.now().toISOString();
+    const operation = {
+        ...copy(i),
+        reservationExpiresAt: new Date(s.clock.now().getTime() + (i.reservationTtlMs ?? 300000)).toISOString(),
+        state: "reserved",
+        version: 1,
+        createdAt: now,
+        updatedAt: now,
+        budgetEpochs: copy(check.epochs),
+        receipts: [],
+        lease: null,
+    };
+    s.operations.set(k, operation);
+    s.identities.set(k, semantics(i));
+    s.warnings.set(k, copy(check.warnings));
+    return {
+        outcome: "reserved",
+        replayed: false,
+        warnings: copy(check.warnings),
+        operation: copy(operation),
+    };
+}
+import { find } from "./state.js";
+export function active(s, op) {
+    return !!op.lease && Date.parse(op.lease.expiresAt) > s.clock.now().getTime();
+}
+export function touch(s, op) {
+    op.version++;
+    op.updatedAt = s.clock.now().toISOString();
+}
+export function validTtl(ttl, field = "leaseTtlMs") {
+    if (!Number.isSafeInteger(ttl) || ttl <= 0 || ttl > 86400000)
+        throw new InvalidInput(field);
+}
+export function intent(s, i) {
+    validTtl(i.leaseTtlMs);
+    const op = find(s, i);
+    if (!op)
+        return { granted: false, reason: "not_reserved", operation: null };
+    if (op.state === "released")
+        return { granted: false, reason: "released", operation: copy(op) };
+    if (op.state !== "reserved")
+        return { granted: false, reason: "already_dispatched", operation: copy(op) };
+    if (Date.parse(op.reservationExpiresAt) <= s.clock.now().getTime()) {
+        release(s, {
+            ...i,
+            commandId: crypto.randomUUID(),
+            expectedVersion: op.version,
+            reason: "reservation_expired",
+        });
+        return { granted: false, reason: "reservation_expired", operation: copy(op) };
+    }
+    if (op.version !== i.expectedVersion)
+        return { granted: false, reason: "version_conflict", operation: copy(op) };
+    op.lease = {
+        leaseId: crypto.randomUUID(),
+        holder: i.holder,
+        expiresAt: new Date(s.clock.now().getTime() + i.leaseTtlMs).toISOString(),
+    };
+    op.state = "dispatch_intended";
+    touch(s, op);
+    s.leaseKinds.set(op.lease.leaseId, "lease");
+    const result = { granted: true, operation: copy(op), lease: copy(op.lease) };
+    s.commands.set(canonical([i.namespace, i.operationId, i.commandId]), {
+        identity: canonical({ kind: "intent", input: i }),
+        result: copy(result),
+    });
+    return result;
+}
+export function renew(s, i) {
+    validTtl(i.leaseTtlMs);
+    const op = find(s, i);
+    if (!op?.lease || !["dispatch_intended", "pending"].includes(op.state))
+        return { renewed: false, reason: "not_active" };
+    if (op.lease.leaseId !== i.leaseId)
+        return { renewed: false, reason: "not_holder" };
+    if (!active(s, op))
+        return { renewed: false, reason: "expired" };
+    op.lease.expiresAt = new Date(Math.max(Date.parse(op.lease.expiresAt), s.clock.now().getTime() + i.leaseTtlMs)).toISOString();
+    return { renewed: true, lease: copy(op.lease) };
+}
+import { canonical, maxMoneyUnits } from "./state.js";
+function authorityError(s, op, a, correction) {
+    if (a.kind === "late_evidence")
+        return (op.state === "pending" || (correction && op.state === "settled")) && !active(s, op)
+            ? null
+            : "invalid_state";
+    if (!["dispatch_intended", "pending"].includes(op.state))
+        return "invalid_state";
+    if (op.lease?.leaseId !== a.leaseId || s.leaseKinds.get(a.leaseId) !== a.kind)
+        return "not_holder";
+    return active(s, op) ? null : "lease_expired";
+}
+export function validateReceipt(r) {
+    if (!r.id?.trim() ||
+        !Number.isFinite(Date.parse(r.occurredAt)) ||
+        !Number.isFinite(Date.parse(r.recordedAt)))
+        throw new InvalidInput("receipt");
+    if (r.cost.certainty === "unknown"
+        ? r.cost.money !== null
+        : !r.cost.money ||
+            typeof r.cost.money.units !== "bigint" ||
+            r.cost.money.units < 0n ||
+            r.cost.money.units > maxMoneyUnits ||
+            r.cost.money.currency !== "USD")
+        throw new InvalidInput("receipt.cost");
+    for (const m of r.measurements) {
+        if (m.certainty === "unknown") {
+            if (m.quantity !== null || !m.unit)
+                throw new InvalidInput("measurement");
+        }
+        else {
+            validateQuantity(m.quantity);
+            if (m.unit !== m.quantity.unit)
+                throw new InvalidInput("measurement.unit");
+        }
+    }
+    if (new Set(r.measurements.map((m) => m.unit)).size !== r.measurements.length)
+        throw new InvalidInput("measurements", "duplicate unit");
+}
+export function settle(s, i, correction = false) {
+    validateReceipt(i.receipt);
+    const op = find(s, i);
+    const reject = (reason) => ({ outcome: "rejected", reason, operation: copy(op) });
+    if (!op)
+        return reject("invalid_state");
+    const ck = canonical([i.namespace, i.operationId, i.commandId]), identity = canonical({ kind: correction ? "correct" : "settle", input: i }), previous = s.commands.get(ck);
+    if (previous) {
+        if (previous.identity !== identity)
+            return reject("receipt_conflict");
+        return {
+            ...copy(previous.result),
+            replayed: true,
+        };
+    }
+    if (op.version !== i.expectedVersion)
+        return reject("version_conflict");
+    const denied = authorityError(s, op, i.authority, correction);
+    if (denied)
+        return reject(denied);
+    const target = correction ? i.replacesReceiptId : undefined;
+    if (target && !op.receipts.some((r) => r.id === target))
+        return reject("invalid_state");
+    if (correction && (!target || op.receipts.some((r) => r.supersedes === target)))
+        return reject("invalid_state");
+    if (op.receipts.some((r) => r.id === i.receipt.id))
+        return reject("receipt_conflict");
+    if (i.receipt.supersedes && i.receipt.supersedes !== target)
+        return reject("receipt_conflict");
+    const receipt = copy(i.receipt);
+    if (target)
+        receipt.supersedes = target;
+    op.receipts = [...op.receipts, receipt];
+    op.state =
+        receipt.cost.certainty === "unknown" ||
+            receipt.measurements.some((m) => m.certainty === "unknown") ||
+            op.estimate.some((q) => !receipt.measurements.some((m) => m.unit === q.unit))
+            ? "pending"
+            : "settled";
+    op.lease = null;
+    touch(s, op);
+    const result = { outcome: "settled", replayed: false, operation: copy(op) };
+    s.commands.set(ck, { identity, result: copy(result) });
+    return result;
+}
+export function release(s, i) {
+    const op = find(s, i), ck = canonical([i.namespace, i.operationId, i.commandId]), identity = canonical({ kind: "release", input: i }), previous = s.commands.get(ck);
+    if (previous?.identity === identity)
+        return {
+            ...copy(previous.result),
+            replayed: true,
+        };
+    if (!op || op.state !== "reserved")
+        return { outcome: "rejected", reason: "not_reserved", operation: copy(op) };
+    if (previous || op.version !== i.expectedVersion)
+        return { outcome: "rejected", reason: "version_conflict", operation: copy(op) };
+    op.state = "released";
+    touch(s, op);
+    const result = { outcome: "released", replayed: false, operation: copy(op) };
+    s.commands.set(ck, { identity, result: copy(result) });
+    return result;
+}
+export function claim(s, i) {
+    validTtl(i.leaseTtlMs);
+    const op = find(s, i);
+    if (!op)
+        return { claimed: false, reason: "not_found", operation: null };
+    if (!["dispatch_intended", "pending"].includes(op.state))
+        return { claimed: false, reason: "not_recoverable", operation: copy(op) };
+    if (active(s, op))
+        return { claimed: false, reason: "lease_active", operation: copy(op) };
+    op.lease = {
+        leaseId: crypto.randomUUID(),
+        holder: i.holder,
+        expiresAt: new Date(s.clock.now().getTime() + i.leaseTtlMs).toISOString(),
+    };
+    s.leaseKinds.set(op.lease.leaseId, "recovery");
+    touch(s, op);
+    return { claimed: true, operation: copy(op), lease: copy(op.lease) };
+}
+export function expireReservations(s, i) {
+    const limit = i.limit ?? 100;
+    if (!i.namespace?.trim() || !Number.isInteger(limit) || limit < 1 || limit > 1000)
+        throw new InvalidInput("expiration");
+    const due = [...s.operations.values()]
+        .filter((op) => op.scope.namespace === i.namespace &&
+        op.state === "reserved" &&
+        Date.parse(op.reservationExpiresAt) <= s.clock.now().getTime())
+        .sort((a, b) => a.reservationExpiresAt.localeCompare(b.reservationExpiresAt) ||
+        a.operationId.localeCompare(b.operationId));
+    for (const op of due.slice(0, limit))
+        release(s, {
+            namespace: i.namespace,
+            principal: op.scope.principal,
+            operationId: op.operationId,
+            expectedVersion: op.version,
+            commandId: crypto.randomUUID(),
+            reason: "reservation_expired",
+        });
+    return { outcome: "expired", count: Math.min(limit, due.length), hasMore: due.length > limit };
+}

package/dist/memory/memory-store.d.ts

@@ -0,0 +1,7 @@
+import type { Budget } from "@usagekit/core";
+import type { Store } from "../index.js";
+import type { Clock } from "../clock.js";
+export declare function createMemoryStore({ clock, budgets }: {
+    clock: Clock;
+    budgets: Budget[];
+}): Store;

package/dist/memory/memory-store.js

@@ -0,0 +1,29 @@
+import { aggregate, definedBudgets, applicableBudgets } from "./reads.js";
+import { copy, find } from "./state.js";
+import { reserve, intent, renew, settle, release, claim, expireReservations } from "./commands.js";
+export function createMemoryStore({ clock, budgets }) {
+    const state = {
+        clock,
+        budgets,
+        warnings: new Map(),
+        leaseKinds: new Map(),
+        commands: new Map(),
+        cursors: new Map(),
+        operations: new Map(),
+        identities: new Map(),
+    };
+    return {
+        expireReservations: async (i) => expireReservations(state, i),
+        reserve: async (i, policy) => reserve(state, i, policy),
+        getOperation: async (ref) => copy(find(state, ref)),
+        markDispatchIntent: async (i) => intent(state, i),
+        renewLease: async (i) => renew(state, i),
+        claimForRecovery: async (i) => claim(state, i),
+        settle: async (i) => settle(state, i),
+        correct: async (i) => settle(state, i, true),
+        releaseUndispatched: async (i) => release(state, i),
+        aggregate: async (q) => aggregate(state, q),
+        definedBudgets: async (q) => definedBudgets(state, q),
+        applicableBudgets: async (q) => applicableBudgets(state, q),
+    };
+}

package/dist/memory/reads.d.ts

@@ -0,0 +1,5 @@
+import type { UsageQuery, UsagePage, DefinedBudgetsQuery, ApplicableBudgetsQuery } from "@usagekit/core";
+import type { State } from "./state.js";
+export declare const definedBudgets: (s: State, q: DefinedBudgetsQuery) => import("@usagekit/core").Budget[];
+export declare const applicableBudgets: (s: State, q: ApplicableBudgetsQuery) => import("@usagekit/core").BudgetStatus[];
+export declare function aggregate(s: State, q: UsageQuery): UsagePage;

package/dist/memory/reads.js

@@ -0,0 +1,131 @@
+import { copy, canonical, InvalidInput } from "./state.js";
+import { currentBudgets, applicable, effective, plus } from "./admission.js";
+export const definedBudgets = (s, q) => copy(currentBudgets(s).filter((b) => canonical(b.scope) === canonical(q.scope)));
+export const applicableBudgets = (s, q) => copy(applicable(s, q));
+function inScope(op, q) {
+    if (op.scope.namespace !== q.scope.namespace ||
+        (q.connection && op.scope.connection !== q.connection))
+        return false;
+    switch (q.scope.kind) {
+        case "namespace":
+            return true;
+        case "principal":
+            return op.scope.principal === q.scope.principal;
+        case "group":
+            return op.scope.group === q.scope.group;
+        case "platform_pool":
+            return op.platformPools?.includes(q.scope.poolId) ?? false;
+    }
+}
+function combineCost(a, b) {
+    if (a.certainty === "unknown" || b.certainty === "unknown")
+        return { certainty: "unknown", money: null };
+    return {
+        certainty: a.certainty === "estimated" || b.certainty === "estimated" ? "estimated" : "measured",
+        money: { currency: "USD", units: a.money.units + b.money.units },
+    };
+}
+function combineMeasurements(a, b) {
+    const map = new Map(a.map((m) => [m.unit, copy(m)]));
+    for (const m of b) {
+        const prev = map.get(m.unit);
+        if (!prev) {
+            map.set(m.unit, copy(m));
+            continue;
+        }
+        map.set(m.unit, prev.certainty === "unknown" || m.certainty === "unknown"
+            ? { unit: m.unit, certainty: "unknown", quantity: null }
+            : {
+                unit: m.unit,
+                certainty: prev.certainty === "estimated" || m.certainty === "estimated"
+                    ? "estimated"
+                    : "measured",
+                quantity: plus(prev.quantity, m.quantity),
+            });
+    }
+    return [...map.values()].sort((a, b) => a.unit.localeCompare(b.unit));
+}
+function rows(s, q) {
+    const map = new Map();
+    for (const op of s.operations.values()) {
+        if (!inScope(op, q) || !["pending", "settled"].includes(op.state))
+            continue;
+        const receipt = effective(op);
+        if (!receipt)
+            continue;
+        const occurred = Date.parse(receipt.occurredAt);
+        if (occurred < Date.parse(q.from) || occurred >= Date.parse(q.to))
+            continue;
+        const pools = q.groupBy.includes("platform_pool")
+            ? q.scope.kind === "platform_pool"
+                ? [q.scope.poolId]
+                : op.platformPools?.length
+                    ? op.platformPools
+                    : [""]
+            : [""];
+        for (const pool of pools) {
+            const dimensions = {};
+            for (const dimension of q.groupBy) {
+                switch (dimension) {
+                    case "principal":
+                        dimensions[dimension] = op.scope.principal;
+                        break;
+                    case "connection":
+                        dimensions[dimension] = op.scope.connection;
+                        break;
+                    case "day":
+                        dimensions[dimension] = new Date(receipt.occurredAt).toISOString().slice(0, 10);
+                        break;
+                    case "access_credential":
+                        dimensions[dimension] = op.scope.accessCredential
+                            ? canonical([op.scope.accessCredential.kind, op.scope.accessCredential.id])
+                            : "";
+                        break;
+                    case "platform_pool":
+                        dimensions[dimension] = pool;
+                        break;
+                    default:
+                        dimensions[dimension] = op[dimension];
+                }
+            }
+            const k = canonical([dimensions, op.fundingSource, op.costOwner]), prev = map.get(k), measurements = receipt.measurements.filter((m) => q.units.includes(m.unit));
+            map.set(k, {
+                dimensions,
+                fundingSource: op.fundingSource,
+                costOwner: op.costOwner,
+                measurements: combineMeasurements(prev?.measurements ?? [], measurements),
+                cost: prev ? combineCost(prev.cost, receipt.cost) : copy(receipt.cost),
+                unknownOperations: (prev?.unknownOperations ?? 0n) + (op.state === "pending" ? 1n : 0n),
+            });
+        }
+    }
+    return [...map.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, r]) => r);
+}
+export function aggregate(s, q) {
+    const { cursor, ...query } = q;
+    const identity = canonical(query);
+    let snapshot;
+    if (cursor) {
+        snapshot = s.cursors.get(cursor);
+        if (!snapshot || snapshot.query !== identity)
+            throw new InvalidInput("cursor", "unknown cursor or query mismatch");
+    }
+    else
+        snapshot = {
+            query: identity,
+            rows: rows(s, q),
+            asOf: s.clock.now().toISOString(),
+            watermark: crypto.randomUUID(),
+            offset: 0,
+        };
+    const end = snapshot.offset + (q.limit ?? 1000), page = {
+        rows: copy(snapshot.rows.slice(snapshot.offset, end)),
+        asOf: snapshot.asOf,
+        watermark: snapshot.watermark,
+    };
+    if (end < snapshot.rows.length) {
+        page.nextCursor = crypto.randomUUID();
+        s.cursors.set(page.nextCursor, { ...snapshot, offset: end });
+    }
+    return page;
+}

package/dist/memory/state.d.ts

@@ -0,0 +1,42 @@
+import type { DispatchGrant } from "@usagekit/core";
+import type { UsageRow } from "@usagekit/core";
+import type { SettleResult, ReleaseResult } from "@usagekit/core";
+import type { AllowanceExceeded } from "@usagekit/core";
+import type { Budget, Operation, ReserveInput, OperationRef, Quantity } from "@usagekit/core";
+import type { Clock } from "../clock.js";
+export declare class InvalidInput extends Error {
+    readonly field: string;
+    readonly reason: string;
+    constructor(field: string, reason?: string);
+}
+export declare const copy: <T>(value: T) => T;
+export declare function canonical(value: unknown): string;
+export declare const key: (namespace: string, id: string) => string;
+export declare function semantics(i: ReserveInput): string;
+export declare const maxMoneyUnits: bigint;
+export declare function validateQuantity(q: Quantity): void;
+export type State = {
+    /** Optional adapter projection, read in the same transaction as admission. */
+    readBudgetUsage?: (budget: Budget, epoch: string) => {
+        used: Quantity;
+        reserved: Quantity;
+    };
+    cursors: Map<string, {
+        query: string;
+        rows: UsageRow[];
+        asOf: string;
+        watermark: string;
+        offset: number;
+    }>;
+    clock: Clock;
+    budgets: Budget[];
+    operations: Map<string, Operation>;
+    identities: Map<string, string>;
+    commands: Map<string, {
+        identity: string;
+        result: SettleResult | ReleaseResult | DispatchGrant;
+    }>;
+    leaseKinds: Map<string, "lease" | "recovery">;
+    warnings: Map<string, readonly AllowanceExceeded[]>;
+};
+export declare function find(s: State, ref: OperationRef): Operation | null;

package/dist/memory/state.js

@@ -0,0 +1,48 @@
+export class InvalidInput extends Error {
+    field;
+    reason;
+    constructor(field, reason = "invalid value") {
+        super(`InvalidInput: ${field}: ${reason}`);
+        this.field = field;
+        this.reason = reason;
+    }
+}
+export const copy = (value) => structuredClone(value);
+export function canonical(value) {
+    if (typeof value === "bigint")
+        return `"bigint:${value}"`;
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value && typeof value === "object")
+        return `{${Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`)
+            .join(",")}}`;
+    return JSON.stringify(value) ?? "null";
+}
+export const key = (namespace, id) => canonical([namespace, id]);
+export function semantics(i) {
+    const { correlationId: _, parentOperationId: __, ...rest } = i;
+    return canonical({
+        ...rest,
+        estimate: [...i.estimate].sort((a, b) => a.unit.localeCompare(b.unit)),
+        platformPools: [...(i.platformPools ?? [])].sort(),
+    });
+}
+export const maxMoneyUnits = 2n ** 63n - 1n;
+export function validateQuantity(q) {
+    if (typeof q.value !== "bigint" ||
+        q.value < 0n ||
+        !Number.isInteger(q.scale) ||
+        q.scale < 0 ||
+        q.scale > 18 ||
+        !q.unit?.trim())
+        throw new InvalidInput("quantity");
+    if (q.unit === "cents" && q.value * 10000n > maxMoneyUnits * 10n ** BigInt(q.scale))
+        throw new InvalidInput("quantity", "money storage bound");
+}
+export function find(s, ref) {
+    const op = s.operations.get(key(ref.namespace, ref.operationId));
+    return op?.scope.principal === ref.principal ? op : null;
+}

package/dist/reference.d.ts

@@ -0,0 +1,6 @@
+/** Synchronous reference rules shared by adapters inside their own atomic transactions. */
+export { reserve, intent, renew, claim, settle, release, expireReservations, } from "./memory/commands.js";
+export { aggregate, definedBudgets, applicableBudgets } from "./memory/reads.js";
+export { copy, find, key, canonical, InvalidInput } from "./memory/state.js";
+export type { State } from "./memory/state.js";
+export { plus, effective, currentBudgets } from "./memory/admission.js";

package/dist/reference.js

@@ -0,0 +1,5 @@
+/** Synchronous reference rules shared by adapters inside their own atomic transactions. */
+export { reserve, intent, renew, claim, settle, release, expireReservations, } from "./memory/commands.js";
+export { aggregate, definedBudgets, applicableBudgets } from "./memory/reads.js";
+export { copy, find, key, canonical, InvalidInput } from "./memory/state.js";
+export { plus, effective, currentBudgets } from "./memory/admission.js";