stellarium-ts 0.19.1 → 0.20.0

package/dist/contract/state.d.ts

@@ -0,0 +1,43 @@
+import type { StateScope, StateWrite, StoredState } from "requestscript";
+import type { NodeDatabase } from "../db/database.js";
+export declare const DEFAULT_MAX_CONTRACT_STATE_BYTES: number;
+/** How a scope is stored: '' for the shared copy, and a prefix keeping the scope's kind, so 3 and "3" differ. */
+export declare function scopeKey(scope: StateScope): string;
+export declare function scopeFromKey(key: string): StateScope;
+export interface ContractStateRow {
+    variable: string;
+    scope: StateScope;
+    value: unknown;
+    updatedAt: string;
+}
+/** Why `commit` saved nothing. */
+export type CommitRefusal = {
+    reason: 'conflict';
+} | {
+    reason: 'too_large';
+    scope: StateScope;
+    bytes: number;
+};
+/**
+ * The state variables of contracts, one row per variable and scope. A row's version counts its writes, so a
+ * call that read an older copy can't save over a newer one.
+ */
+export declare class ContractStateRepository {
+    private readonly db;
+    constructor(db: NodeDatabase);
+    get(path: string, name: string, variable: string, scope: StateScope): Promise<StoredState | undefined>;
+    /**
+     * Saves every write of one call, or none. A write carrying the version its call read saves only over that
+     * version, and one without a version only where nothing is stored, so a copy changed during the call is a
+     * conflict. Each scope written to must stay within `maxBytes`, its variables' encoded values together.
+     */
+    commit(path: string, name: string, writes: StateWrite[], maxBytes: number): Promise<{
+        ok: true;
+    } | ({
+        ok: false;
+    } & CommitRefusal)>;
+    /** Every variable and scope of a contract, with values as stored, ordered by variable then scope. */
+    list(path: string, name: string): Promise<ContractStateRow[]>;
+    deleteContract(path: string, name: string): Promise<void>;
+}
+//# sourceMappingURL=state.d.ts.map

package/dist/contract/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/contract/state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,eAAO,MAAM,gCAAgC,QAAY,CAAC;AAE1D,iHAAiH;AACjH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAKlD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAKpD;AAED,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACrB;AAWD,kCAAkC;AAClC,MAAM,MAAM,aAAa,GAAG;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAQ/G;;;GAGG;AACH,qBAAa,uBAAuB;IACpB,OAAO,CAAC,QAAQ,CAAC,EAAE;IAA/B,YAA6B,EAAE,EAAE,YAAY,EAAI;IAE3C,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAM3G;IAED;;;;OAIG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG,CAAC;QAAE,EAAE,EAAE,KAAK,CAAA;KAAE,GAAG,aAAa,CAAC,CAAC,CAmCxI;IAED,qGAAqG;IAC/F,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAGlE;IAEK,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9D;CACJ"}

package/dist/contract/state.js

@@ -0,0 +1,79 @@
+export const DEFAULT_MAX_CONTRACT_STATE_BYTES = 64 * 1024;
+/** How a scope is stored: '' for the shared copy, and a prefix keeping the scope's kind, so 3 and "3" differ. */
+export function scopeKey(scope) {
+    if (scope === null) {
+        return '';
+    }
+    return `${scope.kind === 'string' ? 's' : 'i'}:${scope.key}`;
+}
+export function scopeFromKey(key) {
+    if (key === '') {
+        return null;
+    }
+    return { kind: key.startsWith('s:') ? 'string' : 'integer', key: key.slice(2) };
+}
+class CommitRefused extends Error {
+    refusal;
+    constructor(refusal) {
+        super(refusal.reason);
+        this.refusal = refusal;
+    }
+}
+/**
+ * The state variables of contracts, one row per variable and scope. A row's version counts its writes, so a
+ * call that read an older copy can't save over a newer one.
+ */
+export class ContractStateRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async get(path, name, variable, scope) {
+        const row = await this.db.get('SELECT value, type, version FROM contract_state WHERE path = ? AND name = ? AND var_name = ? AND scope_key = ?', [path, name, variable, scopeKey(scope)]);
+        return row && { value: JSON.parse(row.value), type: row.type, version: row.version };
+    }
+    /**
+     * Saves every write of one call, or none. A write carrying the version its call read saves only over that
+     * version, and one without a version only where nothing is stored, so a copy changed during the call is a
+     * conflict. Each scope written to must stay within `maxBytes`, its variables' encoded values together.
+     */
+    async commit(path, name, writes, maxBytes) {
+        try {
+            await this.db.transaction(async (tx) => {
+                const now = new Date().toISOString();
+                for (const write of writes) {
+                    const key = scopeKey(write.scope);
+                    const value = JSON.stringify(write.value);
+                    const result = write.version === undefined
+                        ? await tx.run('INSERT INTO contract_state (path, name, var_name, scope_key, value, type, version, updated_at) VALUES (?, ?, ?, ?, ?, ?, 1, ?) ON CONFLICT DO NOTHING', [path, name, write.name, key, value, write.type, now])
+                        : await tx.run('UPDATE contract_state SET value = ?, type = ?, version = version + 1, updated_at = ? WHERE path = ? AND name = ? AND var_name = ? AND scope_key = ? AND version = ?', [value, write.type, now, path, name, write.name, key, write.version]);
+                    if (result.changes === 0) {
+                        throw new CommitRefused({ reason: 'conflict' });
+                    }
+                }
+                for (const key of new Set(writes.map(write => scopeKey(write.scope)))) {
+                    const rows = await tx.all('SELECT value FROM contract_state WHERE path = ? AND name = ? AND scope_key = ?', [path, name, key]);
+                    const bytes = rows.reduce((sum, row) => sum + Buffer.byteLength(row.value), 0);
+                    if (bytes > maxBytes) {
+                        throw new CommitRefused({ reason: 'too_large', scope: scopeFromKey(key), bytes });
+                    }
+                }
+            });
+        }
+        catch (error) {
+            if (error instanceof CommitRefused) {
+                return { ok: false, ...error.refusal };
+            }
+            throw error;
+        }
+        return { ok: true };
+    }
+    /** Every variable and scope of a contract, with values as stored, ordered by variable then scope. */
+    async list(path, name) {
+        const rows = await this.db.all('SELECT var_name, scope_key, value, updated_at FROM contract_state WHERE path = ? AND name = ? ORDER BY var_name, scope_key', [path, name]);
+        return rows.map(row => ({ variable: row.var_name, scope: scopeFromKey(row.scope_key), value: JSON.parse(row.value), updatedAt: row.updated_at }));
+    }
+    async deleteContract(path, name) {
+        await this.db.run('DELETE FROM contract_state WHERE path = ? AND name = ?', [path, name]);
+    }
+}

package/dist/db/database.d.ts

@@ -0,0 +1,25 @@
+export type DatabaseDialect = 'sqlite' | 'postgres';
+export interface RunResult {
+    /** Rows the statement inserted, updated or deleted. */
+    changes: number;
+}
+/**
+ * The node's database, SQLite or Postgres. SQL uses `?` placeholders on both, and sticks to what both
+ * accept: `ON CONFLICT` instead of `INSERT OR IGNORE`, and `RETURNING id` instead of the last insert id.
+ */
+export interface NodeDatabase {
+    readonly dialect: DatabaseDialect;
+    get<T = any>(sql: string, params?: unknown[]): Promise<T | undefined>;
+    all<T = any[]>(sql: string, params?: unknown[]): Promise<T>;
+    run(sql: string, params?: unknown[]): Promise<RunResult>;
+    /** Runs one or more statements without parameters. */
+    exec(sql: string): Promise<void>;
+    /**
+     * Runs `work` in a transaction, committing if it resolves and rolling back if it throws. Transactions
+     * are serialized, so `work` must not start another one, and must query through `tx` only: on a database
+     * with one connection, such as PGlite, a query through the database waits for the transaction to end.
+     */
+    transaction<T>(work: (tx: NodeDatabase) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=database.d.ts.map

package/dist/db/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/db/database.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEpD,MAAM,WAAW,SAAS;IACtB,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACtE,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACzD,sDAAsD;IACtD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC;;;;OAIG;IACH,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACnE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B"}

package/dist/db/database.js

@@ -0,0 +1 @@
+export {};

package/dist/db/db.d.ts

@@ -1,6 +1,14 @@
-import { type Database } from 'sqlite';
+import type { NodeDatabase } from './database.js';
 export declare const DEFAULT_DATABASE_PATH = "./requestscript.db";
-/** Opens (or creates) the node database and brings its schema up to date. Pass ':memory:' for tests. */
-export declare function openDatabase(filename?: string): Promise<Database>;
-export declare function createTables(db: Database): Promise<void>;
+export interface OpenDatabaseOptions {
+    /** Postgres only: the schema the node's tables live in, created if missing. Lets nodes share a database. */
+    schema?: string;
+}
+export declare function isPostgresUrl(location: string): boolean;
+/**
+ * Opens the node database and brings its schema up to date. `location` is a `postgres://` or
+ * `postgresql://` URL, or a SQLite file. Pass ':memory:' for tests.
+ */
+export declare function openDatabase(location?: string, options?: OpenDatabaseOptions): Promise<NodeDatabase>;
+export declare function createTables(db: NodeDatabase): Promise<void>;
 //# sourceMappingURL=db.d.ts.map

package/dist/db/db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/db/db.ts"],"names":[],"mappings":"AAGA,OAAO,EAAQ,KAAK,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAE7C,eAAO,MAAM,qBAAqB,uBAAuB,CAAC;AAc1D,wGAAwG;AACxG,wBAAsB,YAAY,CAAC,QAAQ,GAAE,MAA8B,GAAG,OAAO,CAAC,QAAQ,CAAC,CAO9F;AAED,wBAAsB,YAAY,CAAC,EAAE,EAAE,QAAQ,iBA+I9C"}
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/db/db.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,YAAY,EAAE,MAAM,eAAe,CAAC;AAInE,eAAO,MAAM,qBAAqB,uBAAuB,CAAC;AAgB1D,MAAM,WAAW,mBAAmB;IAChC,4GAA4G;IAC5G,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,QAAQ,GAAE,MAA8B,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,YAAY,CAAC,CAWrI;AA0BD,wBAAsB,YAAY,CAAC,EAAE,EAAE,YAAY,iBAmLlD"}

package/dist/db/db.js

@@ -1,7 +1,5 @@
-import { mkdirSync } from 'node:fs';
-import { dirname } from 'node:path';
-import sqlite3 from 'sqlite3';
-import { open } from 'sqlite';
+import { nodePostgresDriver, PostgresDatabase } from './postgres.js';
+import { SqliteDatabase } from './sqlite.js';
 export const DEFAULT_DATABASE_PATH = './requestscript.db';
 /**
  * Bumped whenever the schema changes in a way `CREATE TABLE IF NOT EXISTS` can't apply.
@@ -12,19 +10,53 @@ export const DEFAULT_DATABASE_PATH = './requestscript.db';
  * Version 5 added `resource_function.kind` and per-token inference pricing, which made `cost_micro_usdc` nullable.
  * Version 6 moved payments to Stripe: `*_micro_usdc` columns became `*_micro_usd`, and `recipient_address`
  * became `recipient_organization_id`.
+ * Version 7 added contract functions: `resource_function.kind` 'contract', priced per million tokens in
+ * `resource_function_payment_manifest.price_micro_usd_per_million_tokens`.
  */
-const SCHEMA_VERSION = 6;
-/** Opens (or creates) the node database and brings its schema up to date. Pass ':memory:' for tests. */
-export async function openDatabase(filename = DEFAULT_DATABASE_PATH) {
-    if (filename !== ':memory:') {
-        mkdirSync(dirname(filename), { recursive: true });
+const SCHEMA_VERSION = 7;
+export function isPostgresUrl(location) {
+    return location.startsWith('postgres://') || location.startsWith('postgresql://');
+}
+/**
+ * Opens the node database and brings its schema up to date. `location` is a `postgres://` or
+ * `postgresql://` URL, or a SQLite file. Pass ':memory:' for tests.
+ */
+export async function openDatabase(location = DEFAULT_DATABASE_PATH, options = {}) {
+    const db = isPostgresUrl(location)
+        ? await PostgresDatabase.open(nodePostgresDriver(location, options.schema), options.schema)
+        : await SqliteDatabase.open(location);
+    try {
+        await createTables(db);
+    }
+    catch (error) {
+        await db.close();
+        throw error;
     }
-    const db = await open({ filename, driver: sqlite3.Database });
-    await createTables(db);
     return db;
 }
+/** Column types that differ between the dialects. */
+function columnTypes(dialect) {
+    return dialect === 'sqlite'
+        ? { id: 'INTEGER PRIMARY KEY AUTOINCREMENT', bigint: 'INTEGER' }
+        : { id: 'BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY', bigint: 'BIGINT' };
+}
+/** SQLite keeps the version in `PRAGMA user_version`; Postgres, which has no equivalent, in a one-row table. */
+async function getSchemaVersion(db) {
+    if (db.dialect === 'sqlite') {
+        return (await db.get('PRAGMA user_version'))?.user_version ?? 0;
+    }
+    await db.exec('CREATE TABLE IF NOT EXISTS stellarium_schema (version INTEGER NOT NULL)');
+    return (await db.get('SELECT version FROM stellarium_schema'))?.version ?? 0;
+}
+async function setSchemaVersion(db, version) {
+    if (db.dialect === 'sqlite') {
+        await db.exec(`PRAGMA user_version = ${version}`);
+        return;
+    }
+    await db.exec(`DELETE FROM stellarium_schema; INSERT INTO stellarium_schema (version) VALUES (${version})`);
+}
 export async function createTables(db) {
-    const { user_version: version } = await db.get('PRAGMA user_version') ?? { user_version: 0 };
+    const version = await getSchemaVersion(db);
     if (version < SCHEMA_VERSION) {
         // Resource rows are a cache of what peers advertise, and are relearned on the next broadcast.
         // SQLite can't drop a constraint in place, so rebuild them. Peers are kept.
@@ -35,9 +67,10 @@ export async function createTables(db) {
             DROP TABLE IF EXISTS resource;
         `);
     }
+    const t = columnTypes(db.dialect);
     await db.exec(`
         CREATE TABLE IF NOT EXISTS peer (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            id ${t.id},
             base_url TEXT NOT NULL,
             public_key TEXT NOT NULL,
             name TEXT NOT NULL,
@@ -50,8 +83,8 @@ export async function createTables(db) {
         );
 
         CREATE TABLE IF NOT EXISTS resource (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            peer_id INTEGER,
+            id ${t.id},
+            peer_id ${t.bigint},
             path TEXT NOT NULL,
             name TEXT NOT NULL,
             base_url TEXT NOT NULL,
@@ -66,8 +99,8 @@ export async function createTables(db) {
         );
 
         CREATE TABLE IF NOT EXISTS resource_function (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            resource_id INTEGER NOT NULL,
+            id ${t.id},
+            resource_id ${t.bigint} NOT NULL,
             name TEXT NOT NULL,
             return_type TEXT NOT NULL,
             description TEXT,
@@ -82,8 +115,8 @@ export async function createTables(db) {
         );
 
         CREATE TABLE IF NOT EXISTS resource_function_parameter (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            resource_function_id INTEGER NOT NULL,
+            id ${t.id},
+            resource_function_id ${t.bigint} NOT NULL,
             name TEXT NOT NULL,
             parameter_type TEXT NOT NULL,
             description TEXT,
@@ -96,12 +129,14 @@ export async function createTables(db) {
         );
 
         CREATE TABLE IF NOT EXISTS resource_function_payment_manifest (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            resource_function_id INTEGER NOT NULL,
-            -- Null for inference functions, which are priced per million tokens instead.
-            cost_micro_usd INTEGER,
-            input_cost_micro_usd_per_million_tokens INTEGER,
-            output_cost_micro_usd_per_million_tokens INTEGER,
+            id ${t.id},
+            resource_function_id ${t.bigint} NOT NULL,
+            -- Null for inference and contract functions, which are priced per million tokens instead.
+            cost_micro_usd ${t.bigint},
+            input_cost_micro_usd_per_million_tokens ${t.bigint},
+            output_cost_micro_usd_per_million_tokens ${t.bigint},
+            -- Set for contract functions, which are charged for the tokens they execute.
+            price_micro_usd_per_million_tokens ${t.bigint},
             -- The hosting node's organization. Null only if a peer advertised the manifest without one.
             recipient_organization_id TEXT,
             created_at TEXT NOT NULL,
@@ -120,7 +155,7 @@ export async function createTables(db) {
             capabilities TEXT NOT NULL,
             parent_grant_issuer TEXT,
             parent_grant_id TEXT,
-            lifetime_ms INTEGER NOT NULL,
+            lifetime_ms ${t.bigint} NOT NULL,
             renewable_until TEXT,
             created_at TEXT NOT NULL
         );
@@ -152,10 +187,43 @@ export async function createTables(db) {
         -- publicKey:nonce of accepted authorizations and grant requests, until they expire.
         CREATE TABLE IF NOT EXISTS seen_nonce (
             key TEXT PRIMARY KEY,
-            expires_at INTEGER NOT NULL
+            expires_at ${t.bigint} NOT NULL
         );
         CREATE INDEX IF NOT EXISTS seen_nonce_expires_at ON seen_nonce (expires_at);
 
+        -- Contracts deployed to this node. Versions are immutable. The latest version of each is one of the
+        -- node's resources, with a single function, run. An owner of null is the node's admin.
+        CREATE TABLE IF NOT EXISTS contract (
+            path TEXT NOT NULL,
+            name TEXT NOT NULL,
+            version TEXT NOT NULL,
+            source TEXT NOT NULL,
+            -- JSON: [{ name, type }]
+            parameters TEXT NOT NULL,
+            return_type TEXT NOT NULL,
+            owner_organization_id TEXT,
+            description TEXT,
+            created_at TEXT NOT NULL,
+
+            PRIMARY KEY (path, name, version)
+        );
+
+        -- The state variables of the contracts deployed to this node, kept across versions. scope_key is ''
+        -- for a variable's shared copy, and 's:<string>' or 'i:<integer>' for a scoped one. value is the
+        -- variable's encoded JSON, and version counts its writes, so a call can't save over a newer copy.
+        CREATE TABLE IF NOT EXISTS contract_state (
+            path TEXT NOT NULL,
+            name TEXT NOT NULL,
+            var_name TEXT NOT NULL,
+            scope_key TEXT NOT NULL,
+            value TEXT NOT NULL,
+            type TEXT NOT NULL,
+            version ${t.bigint} NOT NULL,
+            updated_at TEXT NOT NULL,
+
+            PRIMARY KEY (path, name, var_name, scope_key)
+        );
+
         -- Keys an admin blocked from calling this node or getting grants from it.
         CREATE TABLE IF NOT EXISTS blocked_caller (
             public_key TEXT PRIMARY KEY,
@@ -163,5 +231,5 @@ export async function createTables(db) {
             blocked_at TEXT NOT NULL
         );
     `);
-    await db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+    await setSchemaVersion(db, SCHEMA_VERSION);
 }

package/dist/db/postgres.d.ts

@@ -0,0 +1,39 @@
+import type { NodeDatabase, RunResult } from './database.js';
+/** What `PostgresDatabase` needs from a Postgres client: node-postgres in production, PGlite in tests. */
+export interface PostgresDriver {
+    query(text: string, params: unknown[]): Promise<{
+        rows: any[];
+        rowCount: number;
+    }>;
+    /** Runs one or more statements without parameters. */
+    exec(text: string): Promise<void>;
+    /** Runs `work` on one connection inside BEGIN and COMMIT, or ROLLBACK if it throws. */
+    transaction<T>(work: (driver: PostgresDriver) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+/** Schema names are interpolated into SQL, so only plain identifiers are accepted. */
+export declare function assertSchemaName(schema: string): void;
+/** Rewrites `?` placeholders to `$1`, `$2`, ..., leaving quoted strings and identifiers alone. */
+export declare function numberPlaceholders(sql: string): string;
+/** A node-postgres pool. 64-bit integers come back as numbers, like SQLite's. */
+export declare function nodePostgresDriver(url: string, schema?: string): PostgresDriver;
+export declare class PostgresDatabase implements NodeDatabase {
+    private readonly driver;
+    private readonly inTransaction;
+    readonly dialect = "postgres";
+    /** `inTransaction` is set on the handle a transaction's work receives. */
+    constructor(driver: PostgresDriver, inTransaction?: boolean);
+    /** Creates `schema` if it doesn't exist. The driver must already resolve names in it. */
+    static open(driver: PostgresDriver, schema?: string): Promise<PostgresDatabase>;
+    get<T>(sql: string, params?: unknown[]): Promise<T | undefined>;
+    all<T>(sql: string, params?: unknown[]): Promise<T>;
+    run(sql: string, params?: unknown[]): Promise<RunResult>;
+    exec(sql: string): Promise<void>;
+    /**
+     * Transactions take one advisory lock for the node's schema, so they run one at a time as they do on
+     * SQLite. Their check-then-insert writes rely on that.
+     */
+    transaction<T>(work: (tx: NodeDatabase) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=postgres.d.ts.map

package/dist/db/postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../src/db/postgres.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE7D,0GAA0G;AAC1G,MAAM,WAAW,cAAc;IAC3B,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,GAAG,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnF,sDAAsD;IACtD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,uFAAuF;IACvF,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACzE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAID,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAIrD;AAED,kGAAkG;AAClG,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAoBtD;AAED,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,cAAc,CA8C/E;AAED,qBAAa,gBAAiB,YAAW,YAAY;IAIrC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAAkB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAHnF,QAAQ,CAAC,OAAO,cAAc;IAE9B,0EAA0E;IAC1E,YAA6B,MAAM,EAAE,cAAc,EAAmB,aAAa,UAAQ,EAAI;IAE/F,yFAAyF;IACzF,OAAa,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAMpF;IAEK,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAGxE;IAEK,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAG5D;IAEK,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CAGjE;IAED,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/B;IAED;;;OAGG;IACH,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAQjE;IAED,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAErB;CACJ"}

package/dist/db/postgres.js

@@ -0,0 +1,132 @@
+import pg from 'pg';
+const INT8_OID = 20;
+/** Schema names are interpolated into SQL, so only plain identifiers are accepted. */
+export function assertSchemaName(schema) {
+    if (!/^[a-z_][a-z0-9_]*$/.test(schema)) {
+        throw new Error(`Invalid database schema '${schema}': use lowercase letters, digits and underscores`);
+    }
+}
+/** Rewrites `?` placeholders to `$1`, `$2`, ..., leaving quoted strings and identifiers alone. */
+export function numberPlaceholders(sql) {
+    let index = 0;
+    let quote;
+    let result = '';
+    for (const char of sql) {
+        if (quote) {
+            if (char === quote) {
+                quote = undefined;
+            }
+            result += char;
+        }
+        else if (char === "'" || char === '"') {
+            quote = char;
+            result += char;
+        }
+        else if (char === '?') {
+            result += `$${++index}`;
+        }
+        else {
+            result += char;
+        }
+    }
+    return result;
+}
+/** A node-postgres pool. 64-bit integers come back as numbers, like SQLite's. */
+export function nodePostgresDriver(url, schema) {
+    const pool = new pg.Pool({
+        connectionString: url,
+        // Every connection resolves unqualified names in the node's schema.
+        options: schema ? `-c search_path=${schema}` : undefined,
+        types: { getTypeParser: ((oid, format) => oid === INT8_OID ? Number : pg.types.getTypeParser(oid, format)) },
+    });
+    const onClient = (client) => ({
+        query: async (text, params) => {
+            const result = await client.query(text, params);
+            return { rows: result.rows, rowCount: result.rowCount ?? 0 };
+        },
+        exec: async (text) => {
+            await client.query(text);
+        },
+        transaction: () => {
+            throw new Error('Transactions cannot be nested');
+        },
+        close: async () => { },
+    });
+    return {
+        query: async (text, params) => {
+            const result = await pool.query(text, params);
+            return { rows: result.rows, rowCount: result.rowCount ?? 0 };
+        },
+        exec: async (text) => {
+            await pool.query(text);
+        },
+        transaction: async (work) => {
+            const client = await pool.connect();
+            try {
+                await client.query('BEGIN');
+                try {
+                    const result = await work(onClient(client));
+                    await client.query('COMMIT');
+                    return result;
+                }
+                catch (error) {
+                    await client.query('ROLLBACK');
+                    throw error;
+                }
+            }
+            finally {
+                client.release();
+            }
+        },
+        close: () => pool.end(),
+    };
+}
+export class PostgresDatabase {
+    driver;
+    inTransaction;
+    dialect = 'postgres';
+    /** `inTransaction` is set on the handle a transaction's work receives. */
+    constructor(driver, inTransaction = false) {
+        this.driver = driver;
+        this.inTransaction = inTransaction;
+    }
+    /** Creates `schema` if it doesn't exist. The driver must already resolve names in it. */
+    static async open(driver, schema) {
+        if (schema) {
+            assertSchemaName(schema);
+            await driver.exec(`CREATE SCHEMA IF NOT EXISTS ${schema}`);
+        }
+        return new PostgresDatabase(driver);
+    }
+    async get(sql, params = []) {
+        const { rows } = await this.driver.query(numberPlaceholders(sql), params);
+        return rows[0];
+    }
+    async all(sql, params = []) {
+        const { rows } = await this.driver.query(numberPlaceholders(sql), params);
+        return rows;
+    }
+    async run(sql, params = []) {
+        const { rowCount } = await this.driver.query(numberPlaceholders(sql), params);
+        return { changes: rowCount };
+    }
+    exec(sql) {
+        return this.driver.exec(sql);
+    }
+    /**
+     * Transactions take one advisory lock for the node's schema, so they run one at a time as they do on
+     * SQLite. Their check-then-insert writes rely on that.
+     */
+    transaction(work) {
+        if (this.inTransaction) {
+            throw new Error('Transactions cannot be nested');
+        }
+        return this.driver.transaction(async (driver) => {
+            await driver.query('SELECT pg_advisory_xact_lock(hashtext(current_schema()))', []);
+            return work(new PostgresDatabase(driver, true));
+        });
+    }
+    close() {
+        return this.driver.close();
+    }
+}

package/dist/db/sqlite.d.ts

@@ -0,0 +1,16 @@
+import type { NodeDatabase, RunResult } from './database.js';
+/** A SQLite file, or ':memory:'. */
+export declare class SqliteDatabase implements NodeDatabase {
+    private readonly db;
+    readonly dialect = "sqlite";
+    private writes;
+    private constructor();
+    static open(filename: string): Promise<SqliteDatabase>;
+    get<T>(sql: string, params?: unknown[]): Promise<T | undefined>;
+    all<T>(sql: string, params?: unknown[]): Promise<T>;
+    run(sql: string, params?: unknown[]): Promise<RunResult>;
+    exec(sql: string): Promise<void>;
+    transaction<T>(work: (tx: NodeDatabase) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=sqlite.d.ts.map

package/dist/db/sqlite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../src/db/sqlite.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE7D,oCAAoC;AACpC,qBAAa,cAAe,YAAW,YAAY;IAK3B,OAAO,CAAC,QAAQ,CAAC,EAAE;IAJvC,QAAQ,CAAC,OAAO,YAAY;IAE5B,OAAO,CAAC,MAAM,CAAuC;IAErD,OAAO,eAA8C;IAErD,OAAa,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAK3D;IAED,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAElE;IAED,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAEtD;IAEK,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CAGjE;IAED,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/B;IAED,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAejE;IAED,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAErB;CACJ"}

package/dist/db/sqlite.js

@@ -0,0 +1,53 @@
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import sqlite3 from 'sqlite3';
+import { open } from 'sqlite';
+/** A SQLite file, or ':memory:'. */
+export class SqliteDatabase {
+    db;
+    dialect = 'sqlite';
+    // The connection is shared, so transactions are serialized to keep them from nesting.
+    writes = Promise.resolve();
+    constructor(db) {
+        this.db = db;
+    }
+    static async open(filename) {
+        if (filename !== ':memory:') {
+            mkdirSync(dirname(filename), { recursive: true });
+        }
+        return new SqliteDatabase(await open({ filename, driver: sqlite3.Database }));
+    }
+    get(sql, params = []) {
+        return this.db.get(sql, params);
+    }
+    all(sql, params = []) {
+        return this.db.all(sql, params);
+    }
+    async run(sql, params = []) {
+        const result = await this.db.run(sql, params);
+        return { changes: result.changes ?? 0 };
+    }
+    exec(sql) {
+        return this.db.exec(sql);
+    }
+    transaction(work) {
+        const run = async () => {
+            await this.db.exec('BEGIN IMMEDIATE');
+            try {
+                const result = await work(this);
+                await this.db.exec('COMMIT');
+                return result;
+            }
+            catch (error) {
+                await this.db.exec('ROLLBACK');
+                throw error;
+            }
+        };
+        const result = this.writes.then(run, run);
+        this.writes = result.catch(() => undefined);
+        return result;
+    }
+    close() {
+        return this.db.close();
+    }
+}

package/dist/grant/repository.d.ts

@@ -1,4 +1,4 @@
-import type { Database } from "sqlite";
+import type { NodeDatabase } from "../db/database.js";
 import type { Capability, Grant } from "./grant.js";
 export interface IssuedGrant {
     id: string;
@@ -25,7 +25,7 @@ export interface GrantKey {
 /** Grants this node issued, grants it holds, grants it revoked, nonces it has seen, and caller keys it blocked. */
 export declare class GrantRepository {
     private readonly db;
-    constructor(db: Database);
+    constructor(db: NodeDatabase);
     saveIssued(grant: IssuedGrant): Promise<void>;
     getIssued(id: string): Promise<IssuedGrant | undefined>;
     /** Saves a chain this node holds, replacing an earlier copy of the same leaf grant. */