@usagekit/store-postgres 0.0.0-stage → 0.6.0

package/dist/command-state.js

@@ -0,0 +1,155 @@
+import { resolveWindow } from "@usagekit/core";
+import { currentBudgets, difference, historicalBudget, lockScopes, matchingScopes, updateUsage, usage, } from "./budgets.js";
+import { canonical, decode, encode, hash, identity, key, plus } from "./codec.js";
+import { appendReceipt, event, hydrate, insert, operationRow, update } from "./records.js";
+import { lock, SQL } from "./sql.js";
+export const newState = (clock) => ({
+    clock,
+    budgets: [],
+    operations: new Map(),
+    identities: new Map(),
+    commands: new Map(),
+    leaseKinds: new Map(),
+    warnings: new Map(),
+    reserveAlerts: new Map(),
+    alerts: new Set(),
+    requestCommands: new Map(),
+    cursors: new Map(),
+});
+export async function load(sql, state, namespace, id) {
+    const row = await operationRow(sql, namespace, id);
+    if (!row)
+        return;
+    const op = await hydrate(sql, row), k = key(namespace, id);
+    state.operations.set(k, op);
+    state.identities.set(k, identity(decode(row.input)));
+    state.warnings.set(k, decode(row.warnings));
+    state.reserveAlerts.set(k, decode(row.alerts));
+    if (op.lease && row.lease_kind)
+        state.leaseKinds.set(op.lease.leaseId, row.lease_kind);
+}
+export async function loadReplay(sql, state, input) {
+    const [row] = await sql.query(SQL.sql `
+    SELECT input_hash,result,kind FROM metering_command WHERE operation_pk=${key(input.namespace, input.operationId)} AND command_id=${input.commandId}`);
+    if (row)
+        state.commands.set(canonical([input.namespace, input.operationId, input.commandId]), {
+            identity: hash(canonical({ kind: row.kind, input })) === row.input_hash
+                ? canonical({ kind: row.kind, input })
+                : "semantic_conflict",
+            result: decode(row.result),
+        });
+}
+export async function loadExpired(sql, state, namespace, limit) {
+    const due = await sql.query(SQL.sql `SELECT operation_id FROM metering_operation
+    WHERE namespace=${namespace} AND state='reserved' AND reservation_expires_at<=${state.clock.now()}
+    ORDER BY reservation_expires_at,operation_id LIMIT ${limit + 1}`);
+    let skipped = false;
+    for (const row of due.slice(0, limit)) {
+        const pk = key(namespace, row.operation_id);
+        if (state.operations.has(pk))
+            continue;
+        if (await lock(sql, `metering:operation:${pk}`, true))
+            await load(sql, state, namespace, row.operation_id);
+        else
+            skipped = true;
+    }
+    return skipped || due.length > limit;
+}
+export async function lockAccounting(sql, state, input) {
+    if (input) {
+        const scopes = matchingScopes(input);
+        await lockScopes(sql, scopes);
+        state.budgets = await currentBudgets(sql, input.scope.namespace, scopes, input.surface, input.source);
+    }
+    const ids = new Set(state.budgets.map((b) => canonical([b.scope.namespace, b.id])));
+    for (const op of state.operations.values())
+        for (const e of op.budgetEpochs)
+            ids.add(canonical([op.scope.namespace, e.budgetId]));
+    for (const id of [...ids].sort())
+        await lock(sql, `metering:budget:${id}`);
+    for (const op of state.operations.values())
+        for (const epoch of op.budgetEpochs)
+            if (!state.budgets.some((b) => b.scope.namespace === op.scope.namespace &&
+                b.id === epoch.budgetId &&
+                b.version === epoch.budgetVersion))
+                state.budgets.push(await historicalBudget(sql, op.scope.namespace, epoch.budgetId, epoch.budgetVersion));
+}
+export async function projectUsage(sql, state, before) {
+    const counters = new Map();
+    for (const budget of state.budgets) {
+        const epochs = new Set([resolveWindow(budget.window, state.clock.now()).epoch]);
+        for (const op of state.operations.values())
+            if (op.scope.namespace === budget.scope.namespace)
+                for (const epoch of op.budgetEpochs)
+                    if (epoch.budgetId === budget.id && epoch.budgetVersion === budget.version)
+                        epochs.add(epoch.epoch);
+        for (const epoch of epochs) {
+            counters.set(canonical([budget.scope.namespace, budget.id, epoch]), await usage(sql, budget, epoch));
+            if (budget.alerts?.length) {
+                const alerts = await sql.query(SQL.sql `SELECT alert_key FROM metering_alert
+          WHERE namespace=${budget.scope.namespace} AND budget_id=${budget.id} AND epoch=${epoch}`);
+                for (const alert of alerts)
+                    state.alerts.add(alert.alert_key);
+            }
+        }
+    }
+    state.readBudgetUsage = (budget, epoch) => {
+        const baseline = counters.get(canonical([budget.scope.namespace, budget.id, epoch]));
+        if (!baseline)
+            throw new Error("Missing locked budget projection");
+        let used = baseline.used, reserved = baseline.reserved;
+        for (const [pk, op] of state.operations) {
+            if (op.scope.namespace !== budget.scope.namespace ||
+                !op.budgetEpochs.some((e) => e.budgetId === budget.id && e.epoch === epoch))
+                continue;
+            const delta = difference(before.get(pk) ?? null, op, budget.unit);
+            used = plus(used, delta.used);
+            reserved = plus(reserved, delta.reserved);
+        }
+        return { used, reserved };
+    };
+}
+export async function persist(sql, before, state, afterOperationWrite) {
+    const changed = [];
+    for (const [pk, op] of state.operations) {
+        const old = before.operations.get(pk);
+        if (old && canonical(old) === canonical(op))
+            continue;
+        if (!old)
+            await insert(sql, op, state.warnings.get(pk) ?? [], state.reserveAlerts.get(pk) ?? []);
+        else if (!(await update(sql, old, op, op.lease ? (state.leaseKinds.get(op.lease.leaseId) ?? null) : null)))
+            throw new VersionConflict();
+        afterOperationWrite?.();
+        for (let n = old?.receipts.length ?? 0; n < op.receipts.length; n++) {
+            const receipt = op.receipts[n];
+            if (!receipt)
+                throw new Error("Missing appended receipt");
+            await appendReceipt(sql, op, receipt, n);
+        }
+        await updateUsage(sql, old ?? null, op);
+        if (!old || old.version !== op.version)
+            changed.push(op);
+    }
+    for (const [commandKey, entry] of state.commands) {
+        if (before.commands.has(commandKey))
+            continue;
+        const [namespace, id, commandId] = JSON.parse(commandKey);
+        if (!namespace || !id || !commandId)
+            throw new Error("Invalid stored command identity");
+        const identityBody = JSON.parse(entry.identity);
+        // Canonical identities encode bigint as strings. The stored identity remains exact for replay.
+        await sql.execute(SQL.sql `INSERT INTO metering_command(operation_pk,command_id,kind,input_hash,input,result)
+      VALUES(${key(namespace, id)},${commandId},${identityBody.kind},${hash(entry.identity)},${encode(identityBody.input)}::jsonb,${encode(entry.result)}::jsonb)`);
+    }
+    for (const op of changed)
+        await event(sql, op);
+    for (const value of state.alerts) {
+        if (before.alerts.has(value))
+            continue;
+        const [namespace, budgetId, epoch, threshold] = JSON.parse(value);
+        await sql.execute(SQL.sql `INSERT INTO metering_alert(alert_key,namespace,budget_id,epoch,threshold)
+      VALUES(${value},${namespace},${budgetId},${epoch},${threshold})`);
+    }
+}
+export class VersionConflict extends Error {
+}

package/dist/commands.d.ts

@@ -0,0 +1,6 @@
+import type { Clock, Store } from "@usagekit/store";
+import { type transactions } from "./sql.js";
+type Transactions = ReturnType<typeof transactions>;
+type CommandStore = Pick<Store, "reserve" | "expireReservations" | "markDispatchIntent" | "renewLease" | "claimForRecovery" | "settle" | "correct" | "releaseUndispatched">;
+export declare function commands(tx: Transactions, clock: Clock, hook?: () => void): CommandStore;
+export {};

package/dist/commands.js

@@ -0,0 +1,80 @@
+import { InvalidInput } from "@usagekit/store";
+import * as reference from "@usagekit/store/reference";
+import { lockConnectionAccounting, lockOperationAccounting } from "./accounting-lock.js";
+import { key } from "./codec.js";
+import { load, loadExpired, loadReplay, lockAccounting, newState, persist, projectUsage, VersionConflict, } from "./command-state.js";
+import { lock, SQL } from "./sql.js";
+const snapshot = (s) => ({
+    ...s,
+    operations: structuredClone(s.operations),
+    commands: structuredClone(s.commands),
+    reserveAlerts: structuredClone(s.reserveAlerts),
+    alerts: new Set(s.alerts),
+});
+export function commands(tx, clock, hook) {
+    const execute = async (sql, s, before, run) => {
+        const result = run();
+        await persist(sql, before, s, hook);
+        return result;
+    };
+    const command = async (input, run, conflict) => {
+        try {
+            return await tx.write(async (sql) => {
+                await lockOperationAccounting(sql, input);
+                await lock(sql, `metering:operation:${key(input.namespace, input.operationId)}`);
+                const s = newState(clock);
+                await load(sql, s, input.namespace, input.operationId);
+                if ("commandId" in input)
+                    await loadReplay(sql, s, input);
+                await lockAccounting(sql, s);
+                await projectUsage(sql, s, snapshot(s).operations);
+                return execute(sql, s, snapshot(s), () => run(s));
+            });
+        }
+        catch (error) {
+            if (!(error instanceof VersionConflict))
+                throw error;
+            // The advisory lock normally prevents this. Preserve typed CAS refusal if another writer ignores it.
+            return tx.read(async (sql) => {
+                const s = newState(clock);
+                await load(sql, s, input.namespace, input.operationId);
+                const operation = reference.find(s, input);
+                return conflict(operation);
+            });
+        }
+    };
+    return {
+        reserve: (input, policy) => tx.write(async (sql) => {
+            await lockConnectionAccounting(sql, input.scope.namespace, input.scope.connection);
+            await lock(sql, `metering:operation:${key(input.scope.namespace, input.operationId)}`);
+            const s = newState(clock);
+            await load(sql, s, input.scope.namespace, input.operationId);
+            const counted = await sql.query(SQL.sql `SELECT identity_hash FROM metering_request_command
+          WHERE namespace=${input.scope.namespace} AND command_id=${input.operationId}`);
+            if (counted[0])
+                s.requestCommands?.set(key(input.scope.namespace, input.operationId), counted[0].identity_hash);
+            await loadExpired(sql, s, input.scope.namespace, 100);
+            await lockAccounting(sql, s, input);
+            await projectUsage(sql, s, snapshot(s).operations);
+            const before = snapshot(s);
+            return execute(sql, s, before, () => reference.reserve(s, input, policy));
+        }),
+        expireReservations: (input) => tx.write(async (sql) => {
+            const limit = input.limit ?? 100;
+            if (!input.namespace.trim() || !Number.isInteger(limit) || limit < 1 || limit > 1000)
+                throw new InvalidInput("expiration");
+            const s = newState(clock), more = await loadExpired(sql, s, input.namespace, limit);
+            await lockAccounting(sql, s);
+            return execute(sql, s, snapshot(s), () => {
+                const result = reference.expireReservations(s, input);
+                return { ...result, hasMore: result.hasMore || more };
+            });
+        }),
+        markDispatchIntent: (input) => command(input, (s) => reference.intent(s, input), (operation) => ({ granted: false, reason: "version_conflict", operation })),
+        renewLease: (input) => command(input, (s) => reference.renew(s, input), () => ({ outcome: "invalid", field: "version", reason: "version_conflict" })),
+        claimForRecovery: (input) => command(input, (s) => reference.claim(s, input), () => ({ outcome: "invalid", field: "version", reason: "version_conflict" })),
+        settle: (input) => command(input, (s) => reference.settle(s, input), (operation) => ({ outcome: "rejected", reason: "version_conflict", operation })),
+        correct: (input) => command(input, (s) => reference.settle(s, input, true), (operation) => ({ outcome: "rejected", reason: "version_conflict", operation })),
+        releaseUndispatched: (input) => command(input, (s) => reference.release(s, input), (operation) => ({ outcome: "rejected", reason: "version_conflict", operation })),
+    };
+}

package/dist/counters.d.ts

@@ -0,0 +1,3 @@
+import type { Clock, Store } from "@usagekit/store";
+import { type transactions } from "./sql.js";
+export declare function requestCounters(tx: ReturnType<typeof transactions>, clock: Clock): Pick<Store, "countRequest" | "requestCounts">;

package/dist/counters.js

@@ -0,0 +1,75 @@
+import { bucketOf, countIdentity, validateCountRequest, validateRequestCountsQuery, } from "@usagekit/store";
+import { canonical, encode, hash, key } from "./codec.js";
+import { lock, SQL } from "./sql.js";
+export function requestCounters(tx, clock) {
+    return {
+        async countRequest(input) {
+            validateCountRequest(input);
+            const identity = hash(countIdentity(input));
+            return tx.write(async (sql) => {
+                await lock(sql, `metering:operation:${key(input.scope.namespace, input.commandId)}`);
+                const [previous] = await sql.query(SQL.sql `
+          SELECT identity_hash FROM metering_request_command
+          WHERE namespace=${input.scope.namespace} AND command_id=${input.commandId}`);
+                if (previous)
+                    return previous.identity_hash === identity
+                        ? { outcome: "counted", replayed: true }
+                        : { outcome: "conflict", reason: "command_mismatch" };
+                const [operation] = await sql.query(SQL.sql `
+          SELECT operation_id FROM metering_operation
+          WHERE namespace=${input.scope.namespace} AND operation_id=${input.commandId}`);
+                if (operation)
+                    return { outcome: "conflict", reason: "command_mismatch" };
+                const bucket = bucketOf(input, clock.now());
+                await sql.execute(SQL.sql `
+          INSERT INTO metering_request_count(bucket_key,namespace,day,body,count)
+          VALUES(${canonical(bucket)},${bucket.namespace},${new Date(`${bucket.day}T00:00:00Z`)},${encode(bucket)}::jsonb,1)
+          ON CONFLICT(bucket_key) DO UPDATE SET count=metering_request_count.count+1`);
+                await sql.execute(SQL.sql `
+          INSERT INTO metering_request_command(namespace,command_id,identity_hash)
+          VALUES(${input.scope.namespace},${input.commandId},${identity})`);
+                return { outcome: "counted", replayed: false };
+            });
+        },
+        async requestCounts(query) {
+            validateRequestCountsQuery(query);
+            return tx.read(async (sql) => {
+                const clauses = [
+                    SQL.sql `namespace=${query.scope.namespace}`,
+                    SQL.sql `day>=${new Date(query.from)}`,
+                    SQL.sql `day<${new Date(query.to)}`,
+                ];
+                if (query.scope.kind === "principal")
+                    clauses.push(SQL.sql `body->>'principal'=${query.scope.principal}`);
+                if (query.scope.kind === "group")
+                    clauses.push(SQL.sql `body->>'group'=${query.scope.group}`);
+                if (query.scope.kind === "platform_pool")
+                    clauses.push(SQL.sql `body->'pools' @> ${JSON.stringify([query.scope.poolId])}::jsonb`);
+                if (query.connection)
+                    clauses.push(SQL.sql `body->>'connection'=${query.connection}`);
+                const dimensions = query.groupBy.flatMap((dimension) => [
+                    SQL.sql `${dimension}::text`,
+                    SQL.sql `body->>${dimension}`,
+                ]);
+                const dimensionsSql = dimensions.length
+                    ? SQL.sql `jsonb_build_object(${SQL.join(dimensions)})`
+                    : SQL.sql `'{}'::jsonb`;
+                const order = [
+                    ...query.groupBy.map((dimension) => SQL.sql `dimensions->>${dimension} COLLATE "C"`),
+                    SQL.sql `state COLLATE "C"`,
+                ];
+                const limit = query.limit ?? 1000;
+                const rows = await sql.query(SQL.sql `
+          SELECT dimensions,state,count FROM (
+            SELECT ${dimensionsSql} AS dimensions,body->>'state' AS state,sum(count)::text AS count
+            FROM metering_request_count WHERE ${SQL.join(clauses, " AND ")} GROUP BY 1,2
+          ) grouped ORDER BY ${SQL.join(order)} LIMIT ${limit + 1}`);
+                return {
+                    rows: rows.slice(0, limit).map((row) => ({ ...row, count: BigInt(row.count) })),
+                    asOf: clock.now().toISOString(),
+                    truncated: rows.length > limit,
+                };
+            });
+        },
+    };
+}

package/dist/driver.d.ts

@@ -0,0 +1,27 @@
+import type { Pool, PoolClient } from "pg";
+import type { ParameterizedQuery } from "./statement.js";
+/** Values are bound separately from text by every driver implementation. */
+export interface PostgresExecutor {
+    query<T>(query: ParameterizedQuery): Promise<T[]>;
+    execute(query: ParameterizedQuery): Promise<number>;
+}
+export interface PostgresDriver {
+    transaction<T>(readOnly: boolean, body: (sql: PostgresExecutor) => Promise<T>): Promise<T>;
+}
+export declare function nodePostgresExecutor(client: PoolClient): PostgresExecutor;
+/** One checked-out connection owns BEGIN, every statement, COMMIT and ROLLBACK. */
+export declare function createNodePostgresDriver(pool: Pool): PostgresDriver;
+export interface PrismaPostgresTransaction {
+    $queryRawUnsafe<T = unknown>(query: string, ...values: unknown[]): Promise<T>;
+    $executeRawUnsafe(query: string, ...values: unknown[]): Promise<number>;
+}
+export interface PrismaPostgresClient {
+    $transaction<T>(body: (transaction: PrismaPostgresTransaction) => Promise<T>, options: {
+        timeout: number;
+        maxWait: number;
+        isolationLevel: "RepeatableRead" | "ReadCommitted";
+    }): Promise<T>;
+}
+/** The Unsafe-named Prisma methods still bind every value as a positional parameter. */
+export declare function prismaPostgresExecutor(transaction: PrismaPostgresTransaction): PostgresExecutor;
+export declare function createPrismaPostgresDriver(prisma: PrismaPostgresClient): PostgresDriver;

package/dist/driver.js

@@ -0,0 +1,64 @@
+export function nodePostgresExecutor(client) {
+    return {
+        async query({ text, values }) {
+            return (await client.query(text, values)).rows;
+        },
+        async execute({ text, values }) {
+            return (await client.query(text, values)).rowCount ?? 0;
+        },
+    };
+}
+/** One checked-out connection owns BEGIN, every statement, COMMIT and ROLLBACK. */
+export function createNodePostgresDriver(pool) {
+    return {
+        async transaction(readOnly, body) {
+            const client = await pool.connect();
+            let destroy = false;
+            try {
+                await client.query(readOnly
+                    ? "BEGIN ISOLATION LEVEL REPEATABLE READ READ ONLY"
+                    : "BEGIN ISOLATION LEVEL READ COMMITTED");
+                await client.query("SET LOCAL statement_timeout = '30s'");
+                await client.query("SET LOCAL lock_timeout = '10s'");
+                const result = await body(nodePostgresExecutor(client));
+                await client.query("COMMIT");
+                return result;
+            }
+            catch (error) {
+                try {
+                    await client.query("ROLLBACK");
+                }
+                catch {
+                    destroy = true;
+                }
+                throw error;
+            }
+            finally {
+                client.release(destroy);
+            }
+        },
+    };
+}
+/** The Unsafe-named Prisma methods still bind every value as a positional parameter. */
+export function prismaPostgresExecutor(transaction) {
+    // Prisma's pg adapter encodes Date without an offset. Preserve the UTC instant for timestamptz
+    // even when a host connection uses a non-UTC TimeZone, including caller-owned transactions.
+    const parameters = (values) => values.map((value) => (value instanceof Date ? value.toISOString() : value));
+    return {
+        query: ({ text, values }) => transaction.$queryRawUnsafe(text, ...parameters(values)),
+        execute: ({ text, values }) => transaction.$executeRawUnsafe(text, ...parameters(values)),
+    };
+}
+export function createPrismaPostgresDriver(prisma) {
+    return {
+        transaction: (readOnly, body) => prisma.$transaction(async (transaction) => {
+            if (readOnly)
+                await transaction.$executeRawUnsafe("SET TRANSACTION READ ONLY");
+            return body(prismaPostgresExecutor(transaction));
+        }, {
+            timeout: 30000,
+            maxWait: 10000,
+            isolationLevel: readOnly ? "RepeatableRead" : "ReadCommitted",
+        }),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+import type { Pool } from "pg";
+import type { Budget } from "@usagekit/core";
+import type { Clock } from "@usagekit/store";
+import { type PostgresDriver, type PostgresExecutor } from "./driver.js";
+import { type Counters } from "./sql.js";
+export { createNodePostgresDriver, createPrismaPostgresDriver, nodePostgresExecutor, prismaPostgresExecutor, } from "./driver.js";
+export type { PostgresDriver, PostgresExecutor, PrismaPostgresClient, PrismaPostgresTransaction, } from "./driver.js";
+export type { ParameterizedQuery } from "./statement.js";
+export type { Counters as PostgresStoreCounters } from "./sql.js";
+export { migratePostgresStore } from "./migrate.js";
+type Storage = {
+    pool: Pool;
+    driver?: never;
+} | {
+    driver: PostgresDriver;
+    pool?: never;
+};
+export type PostgresStoreOptions = Storage & {
+    clock: Clock;
+    schema?: string;
+    counters?: Counters;
+    testHooks?: {
+        afterOperationWrite?: () => void;
+    };
+};
+export declare function createPostgresStore(options: PostgresStoreOptions): Promise<{
+    putBudget: (budget: Budget) => Promise<{
+        outcome: "conflict";
+        reason: "budget_version";
+        budget?: never;
+    } | {
+        outcome: "saved";
+        budget: Budget;
+        reason?: never;
+    }>;
+    listBudgets: (namespace: string) => Promise<Budget[]>;
+    counters: Counters;
+    importBilling(input: import("@usagekit/core").BillingImportInput): Promise<import("@usagekit/core").BillingImportResult>;
+    billingImports(query: import("@usagekit/core").BillingImportsQuery): Promise<import("@usagekit/core").BillingImportsPage>;
+    expireReservations(input: import("@usagekit/core").ExpireReservationsInput): Promise<import("@usagekit/core").ExpireReservationsResult>;
+    reserve(input: import("@usagekit/core").ReserveInput, policy?: import("@usagekit/core").AdmissionPolicy): Promise<import("@usagekit/core").ReserveResult>;
+    markDispatchIntent(input: import("@usagekit/core").DispatchIntentInput): Promise<import("@usagekit/core").DispatchGrant>;
+    renewLease(input: import("@usagekit/core").LeaseRenewalInput): Promise<import("@usagekit/core").LeaseRenewal>;
+    claimForRecovery(input: import("@usagekit/core").RecoveryClaimInput): Promise<import("@usagekit/core").RecoveryClaim>;
+    settle(input: import("@usagekit/core").SettleInput): Promise<import("@usagekit/core").SettleResult>;
+    correct(input: import("@usagekit/core").CorrectionInput): Promise<import("@usagekit/core").SettleResult>;
+    releaseUndispatched(input: import("@usagekit/core").ReleaseInput): Promise<import("@usagekit/core").ReleaseResult>;
+    countRequest(input: import("@usagekit/core").CountRequestInput): Promise<import("@usagekit/core").CountRequestResult>;
+    getOperation(input: import("@usagekit/core").OperationRef): Promise<import("@usagekit/core").Operation | null>;
+    aggregate(query: import("@usagekit/core").UsageQuery): Promise<import("@usagekit/core").UsagePage>;
+    listOperations(query: import("@usagekit/core").OperationsQuery): Promise<import("@usagekit/core").OperationsPage>;
+    requestCounts(query: import("@usagekit/core").RequestCountsQuery): Promise<import("@usagekit/core").RequestCountsPage>;
+    definedBudgets(query: import("@usagekit/core").DefinedBudgetsQuery): Promise<readonly Budget[]>;
+    applicableBudgets(query: import("@usagekit/core").ApplicableBudgetsQuery): Promise<readonly import("@usagekit/core").BudgetStatus[]>;
+}>;
+/** Caller owns the transaction, search_path, isolation, commit and rollback. */
+export declare function createTransactionBoundStore({ transaction, clock, counters, afterOperationWrite, }: {
+    transaction: PostgresExecutor;
+    clock: Clock;
+    counters?: Counters;
+    afterOperationWrite?: () => void;
+}): Promise<{
+    putBudget: (budget: Budget) => Promise<{
+        outcome: "conflict";
+        reason: "budget_version";
+        budget?: never;
+    } | {
+        outcome: "saved";
+        budget: Budget;
+        reason?: never;
+    }>;
+    listBudgets: (namespace: string) => Promise<Budget[]>;
+    counters: Counters;
+    importBilling(input: import("@usagekit/core").BillingImportInput): Promise<import("@usagekit/core").BillingImportResult>;
+    billingImports(query: import("@usagekit/core").BillingImportsQuery): Promise<import("@usagekit/core").BillingImportsPage>;
+    expireReservations(input: import("@usagekit/core").ExpireReservationsInput): Promise<import("@usagekit/core").ExpireReservationsResult>;
+    reserve(input: import("@usagekit/core").ReserveInput, policy?: import("@usagekit/core").AdmissionPolicy): Promise<import("@usagekit/core").ReserveResult>;
+    markDispatchIntent(input: import("@usagekit/core").DispatchIntentInput): Promise<import("@usagekit/core").DispatchGrant>;
+    renewLease(input: import("@usagekit/core").LeaseRenewalInput): Promise<import("@usagekit/core").LeaseRenewal>;
+    claimForRecovery(input: import("@usagekit/core").RecoveryClaimInput): Promise<import("@usagekit/core").RecoveryClaim>;
+    settle(input: import("@usagekit/core").SettleInput): Promise<import("@usagekit/core").SettleResult>;
+    correct(input: import("@usagekit/core").CorrectionInput): Promise<import("@usagekit/core").SettleResult>;
+    releaseUndispatched(input: import("@usagekit/core").ReleaseInput): Promise<import("@usagekit/core").ReleaseResult>;
+    countRequest(input: import("@usagekit/core").CountRequestInput): Promise<import("@usagekit/core").CountRequestResult>;
+    getOperation(input: import("@usagekit/core").OperationRef): Promise<import("@usagekit/core").Operation | null>;
+    aggregate(query: import("@usagekit/core").UsageQuery): Promise<import("@usagekit/core").UsagePage>;
+    listOperations(query: import("@usagekit/core").OperationsQuery): Promise<import("@usagekit/core").OperationsPage>;
+    requestCounts(query: import("@usagekit/core").RequestCountsQuery): Promise<import("@usagekit/core").RequestCountsPage>;
+    definedBudgets(query: import("@usagekit/core").DefinedBudgetsQuery): Promise<readonly Budget[]>;
+    applicableBudgets(query: import("@usagekit/core").ApplicableBudgetsQuery): Promise<readonly import("@usagekit/core").BudgetStatus[]>;
+}>;
+export type PostgresStore = Awaited<ReturnType<typeof createPostgresStore>>;

package/dist/index.js

@@ -0,0 +1,60 @@
+import { randomBytes } from "node:crypto";
+import { billingImports } from "./billing.js";
+import { currentBudgets, matchingScopes, saveBudget, status } from "./budgets.js";
+import { commands } from "./commands.js";
+import { requestCounters } from "./counters.js";
+import { createNodePostgresDriver } from "./driver.js";
+import { operationsReader } from "./operations.js";
+import { usageReader } from "./reads.js";
+import { find } from "./records.js";
+import { createSql, SQL, transactions } from "./sql.js";
+export { createNodePostgresDriver, createPrismaPostgresDriver, nodePostgresExecutor, prismaPostgresExecutor, } from "./driver.js";
+export { migratePostgresStore } from "./migrate.js";
+export async function createPostgresStore(options) {
+    const counters = options.counters ?? { statements: 0, changes: 0n, rowsRead: 0 };
+    const driver = options.driver ?? createNodePostgresDriver(options.pool);
+    return compose(transactions(driver, options.schema ?? "public", counters), options.clock, counters, options.testHooks?.afterOperationWrite);
+}
+/** Caller owns the transaction, search_path, isolation, commit and rollback. */
+export async function createTransactionBoundStore({ transaction, clock, counters = {
+    statements: 0,
+    changes: 0n,
+    rowsRead: 0,
+}, afterOperationWrite, }) {
+    const sql = createSql(transaction, counters);
+    const run = (body) => body(sql);
+    return compose({ read: run, write: run }, clock, counters, afterOperationWrite);
+}
+async function compose(tx, clock, counters, afterOperationWrite) {
+    const secret = await tx.write(async (sql) => {
+        await sql.execute(SQL.sql `INSERT INTO metering_metadata(key,value)
+      VALUES('cursor_key',${randomBytes(32).toString("hex")}) ON CONFLICT(key) DO NOTHING`);
+        const [row] = await sql.query(SQL.sql `SELECT value FROM metering_metadata WHERE key='cursor_key'`);
+        if (!row)
+            throw new Error("Missing metering cursor key");
+        return row.value;
+    });
+    const aggregate = usageReader(clock, secret), operations = operationsReader(clock, secret);
+    const store = {
+        ...billingImports(tx, clock, afterOperationWrite),
+        ...commands(tx, clock, afterOperationWrite),
+        ...requestCounters(tx, clock),
+        listOperations: (query) => tx.read((sql) => operations(sql, query)),
+        getOperation: (ref) => tx.read(async (sql) => (await find(sql, ref))?.op ?? null),
+        aggregate: (query) => tx.read((sql) => aggregate(sql, query)),
+        definedBudgets: (query) => tx.read((sql) => currentBudgets(sql, query.scope.namespace, [query.scope])),
+        applicableBudgets: (query) => tx.read(async (sql) => {
+            const budgets = await currentBudgets(sql, query.scope.namespace, matchingScopes(query), query.surface, query.source);
+            const result = [];
+            for (const budget of budgets)
+                result.push(await status(sql, budget, clock.now()));
+            return result;
+        }),
+    };
+    return {
+        ...store,
+        putBudget: (budget) => tx.write((sql) => saveBudget(sql, budget)),
+        listBudgets: (namespace) => tx.read((sql) => currentBudgets(sql, namespace)),
+        counters,
+    };
+}

package/dist/migrate.d.ts

@@ -0,0 +1,15 @@
+import type { Pool } from "pg";
+import { type PostgresDriver } from "./driver.js";
+type Options = ({
+    pool: Pool;
+    driver?: never;
+} | {
+    driver: PostgresDriver;
+    pool?: never;
+}) & {
+    schema?: string;
+    createSchema?: boolean;
+};
+/** Explicit, atomic and serialized. Store creation never applies migrations implicitly. */
+export declare function migratePostgresStore(options: Options): Promise<void>;
+export {};

package/dist/migrate.js

@@ -0,0 +1,38 @@
+import { createHash } from "node:crypto";
+import { createNodePostgresDriver } from "./driver.js";
+import { schemaStatements } from "./schema.js";
+import { schemaIdentifier } from "./statement.js";
+/** Explicit, atomic and serialized. Store creation never applies migrations implicitly. */
+export async function migratePostgresStore(options) {
+    const schema = options.schema ?? "public", identifier = schemaIdentifier(schema);
+    const driver = options.driver ?? createNodePostgresDriver(options.pool);
+    const checksum = createHash("sha256").update(schemaStatements.join("\n")).digest("hex");
+    await driver.transaction(false, async (sql) => {
+        await sql.query({
+            text: "SELECT 1 AS acquired FROM pg_advisory_xact_lock(hashtextextended($1,0))",
+            values: [`usagekit:migrate:${schema}`],
+        });
+        if (options.createSchema)
+            await sql.execute({ text: `CREATE SCHEMA IF NOT EXISTS ${identifier}`, values: [] });
+        await sql.query({ text: "SELECT set_config('search_path',$1,true)", values: [identifier] });
+        await sql.execute({
+            text: "CREATE TABLE IF NOT EXISTS metering_schema_version (version integer PRIMARY KEY, checksum text NOT NULL)",
+            values: [],
+        });
+        const rows = await sql.query({
+            text: "SELECT version,checksum FROM metering_schema_version ORDER BY version",
+            values: [],
+        });
+        if (rows.length) {
+            if (rows.length !== 1 || rows[0]?.version !== 1 || rows[0]?.checksum !== checksum)
+                throw new Error("Unsupported or modified Postgres Store schema version");
+            return;
+        }
+        for (const text of schemaStatements)
+            await sql.execute({ text, values: [] });
+        await sql.execute({
+            text: "INSERT INTO metering_schema_version(version,checksum) VALUES(1,$1)",
+            values: [checksum],
+        });
+    });
+}

package/dist/operations.d.ts

@@ -0,0 +1,4 @@
+import type { OperationsPage, OperationsQuery } from "@usagekit/core";
+import { type Clock } from "@usagekit/store";
+import { type Sql } from "./sql.js";
+export declare function operationsReader(clock: Clock, secret: string): (sql: Sql, q: OperationsQuery) => Promise<OperationsPage>;