@finchip.ai/foga 0.0.0-stage → 0.6.0-alpha.4

package/dist/kernel/store.js

@@ -0,0 +1,470 @@
+import { createRequire } from "node:module";
+import { dirname } from "node:path";
+import { ensureDir } from "../util/fs.js";
+/** Thrown when a key is claimed again with a different request than the one it was claimed with. */
+export class OperationConflict extends Error {
+    key;
+    storedHash;
+    requestHash;
+    constructor(key, storedHash, requestHash) {
+        super(`operation ${key} was claimed with request ${storedHash} and is now asked for with request ${requestHash}: the same key must carry the same request (use another key for another request)`);
+        this.key = key;
+        this.storedHash = storedHash;
+        this.requestHash = requestHash;
+        this.name = "OperationConflict";
+    }
+}
+/**
+ * node:sqlite is unflagged since Node 22.13 but Node 22 still tags it experimental and prints a one-line notice
+ * on first load. The notice is silenced for that one load only; every other warning is left alone.
+ */
+function loadSqlite() {
+    const original = process.emitWarning;
+    process.emitWarning = function (warning, ...args) {
+        const text = typeof warning === "string" ? warning : warning?.message ?? "";
+        const type = typeof args[0] === "string" ? args[0] : args[0]?.type;
+        if (type === "ExperimentalWarning" && /sqlite/i.test(text))
+            return;
+        return original.call(process, warning, ...args);
+    };
+    try {
+        return createRequire(import.meta.url)("node:sqlite");
+    }
+    finally {
+        process.emitWarning = original;
+    }
+}
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS ops (
+  key        TEXT PRIMARY KEY,
+  kind       TEXT NOT NULL,
+  signer     TEXT NOT NULL,
+  status     TEXT NOT NULL,
+  nonce      INTEGER,
+  tx_hash    TEXT,
+  block      INTEGER,
+  result     TEXT,
+  error      TEXT,
+  attempts   INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS facts (
+  key        TEXT PRIMARY KEY,
+  value      TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS journal (
+  seq    INTEGER PRIMARY KEY AUTOINCREMENT,
+  at     TEXT NOT NULL,
+  op_key TEXT,
+  event  TEXT NOT NULL,
+  detail TEXT
+);
+CREATE TABLE IF NOT EXISTS meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS jobs (
+  id         TEXT PRIMARY KEY,
+  kind       TEXT NOT NULL,
+  status     TEXT NOT NULL,
+  caller     TEXT,
+  cell       TEXT,
+  input_hash TEXT NOT NULL,
+  input      TEXT NOT NULL,
+  result     TEXT,
+  error      TEXT,
+  operations TEXT NOT NULL DEFAULT '[]',
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS decisions (
+  id           INTEGER PRIMARY KEY AUTOINCREMENT,
+  at           TEXT NOT NULL,
+  entrance     TEXT NOT NULL,
+  caller       TEXT NOT NULL,
+  capability   TEXT NOT NULL,
+  mode         TEXT NOT NULL,
+  input_hash   TEXT NOT NULL,
+  verdict      TEXT NOT NULL,
+  gate         TEXT NOT NULL,
+  reason       TEXT NOT NULL,
+  job_id       TEXT,
+  operation_id TEXT,
+  model        TEXT
+);
+`;
+/** Columns added after 0.5.0; an older store gains them on open (SQLite's ADD COLUMN is cheap and keeps the rows). */
+const OPS_COLUMNS = [
+    ["replacements", "INTEGER NOT NULL DEFAULT 0"],
+    ["request_hash", "TEXT"],
+    ["capability", "TEXT"],
+    ["caller", "TEXT"],
+    ["cell", "TEXT"],
+    ["value_wei", "TEXT NOT NULL DEFAULT '0'"],
+    ["fee_cap_wei", "TEXT NOT NULL DEFAULT '0'"],
+    ["gas_cost_wei", "TEXT"],
+];
+function now() {
+    return new Date().toISOString();
+}
+/** JSON with bigints as decimal strings, so facts and results round-trip through SQLite text. */
+export function toJson(value) {
+    return JSON.stringify(value, (_k, v) => (typeof v === "bigint" ? v.toString() : v));
+}
+export class OperationStore {
+    db;
+    path;
+    constructor(db, path) {
+        this.db = db;
+        this.path = path;
+    }
+    static open(path) {
+        if (path !== ":memory:")
+            ensureDir(dirname(path));
+        const { DatabaseSync } = loadSqlite();
+        const db = new DatabaseSync(path);
+        // WAL so a one-shot command (a guardian's suspension, a key minted) can write while the node runs; a busy timeout so
+        // the two writers wait for each other instead of failing on SQLITE_BUSY
+        if (path !== ":memory:")
+            db.exec("PRAGMA journal_mode = WAL; PRAGMA synchronous = FULL; PRAGMA busy_timeout = 5000;");
+        db.exec(SCHEMA);
+        const have = new Set(db.prepare("PRAGMA table_info(ops)").all().map((r) => String(r.name)));
+        for (const [name, decl] of OPS_COLUMNS)
+            if (!have.has(name))
+                db.exec(`ALTER TABLE ops ADD COLUMN ${name} ${decl}`);
+        const jobColumns = new Set(db.prepare("PRAGMA table_info(jobs)").all().map((r) => String(r.name)));
+        if (!jobColumns.has("value_wei"))
+            db.exec("ALTER TABLE jobs ADD COLUMN value_wei TEXT NOT NULL DEFAULT '0'");
+        return new OperationStore(db, path);
+    }
+    depth = 0;
+    /** Run `fn` inside one SQLite transaction (a claim and its reservation land together or not at all); nested calls join the outer one. */
+    transaction(fn) {
+        if (this.depth > 0)
+            return fn();
+        this.db.exec("BEGIN IMMEDIATE");
+        this.depth++;
+        try {
+            const out = fn();
+            this.db.exec("COMMIT");
+            return out;
+        }
+        catch (e) {
+            this.db.exec("ROLLBACK");
+            throw e;
+        }
+        finally {
+            this.depth--;
+        }
+    }
+    close() {
+        this.db.close();
+    }
+    // ---------------------------------------------------------------------------- meta
+    getMeta(key) {
+        return this.db.prepare("SELECT value FROM meta WHERE key = ?").get(key)?.value;
+    }
+    setMeta(key, value) {
+        this.db.prepare("INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(key, value);
+    }
+    // ---------------------------------------------------------------------------- operations
+    get(key) {
+        const row = this.db.prepare("SELECT * FROM ops WHERE key = ?").get(key);
+        return row ? rowToOp(row) : undefined;
+    }
+    all() {
+        return this.db.prepare("SELECT * FROM ops ORDER BY created_at, key").all().map(rowToOp);
+    }
+    /**
+     * Claim a key: record the intent to send, bound to the request when the caller binds it. Idempotent for the same
+     * request: an existing row is returned unchanged (and gains the binding if it had none). Another request under
+     * the same key is refused with OperationConflict. The claim and its reservation are one transaction.
+     */
+    prepare(key, kind, signer, binding = {}) {
+        return this.transaction(() => {
+            const existing = this.get(key);
+            if (existing) {
+                if (binding.requestHash && existing.requestHash && existing.requestHash !== binding.requestHash) {
+                    throw new OperationConflict(key, existing.requestHash, binding.requestHash);
+                }
+                if (binding.requestHash && !existing.requestHash) {
+                    this.db
+                        .prepare("UPDATE ops SET request_hash = ?, capability = COALESCE(capability, ?), caller = COALESCE(caller, ?), cell = COALESCE(cell, ?), updated_at = ? WHERE key = ?")
+                        .run(binding.requestHash, binding.capability ?? null, binding.caller ?? null, binding.cell ?? null, now(), key);
+                    return this.get(key);
+                }
+                return existing;
+            }
+            const t = now();
+            this.db
+                .prepare("INSERT INTO ops (key, kind, signer, status, attempts, replacements, request_hash, capability, caller, cell, value_wei, fee_cap_wei, created_at, updated_at) VALUES (?, ?, ?, 'prepared', 0, 0, ?, ?, ?, ?, ?, ?, ?, ?)")
+                .run(key, kind, signer, binding.requestHash ?? null, binding.capability ?? null, binding.caller ?? null, binding.cell ?? null, (binding.valueWei ?? 0n).toString(), (binding.feeCapWei ?? 0n).toString(), t, t);
+            return this.get(key);
+        });
+    }
+    /**
+     * The transaction is signed and its hash known: written before the broadcast. The value it carries replaces the
+     * reservation made at the claim (the reservation was an upper bound; from here on the row says what will move).
+     */
+    markSent(key, txHash, nonce, valueWei) {
+        this.db
+            .prepare("UPDATE ops SET status = 'sent', tx_hash = ?, nonce = ?, error = NULL, attempts = attempts + 1, value_wei = COALESCE(?, value_wei), updated_at = ? WHERE key = ?")
+            .run(txHash, nonce, valueWei === undefined ? null : valueWei.toString(), now(), key);
+    }
+    /** A fee replacement was signed for the operation: its new hash, and one more replacement on the count. */
+    markReplaced(key, txHash, nonce) {
+        this.db.prepare("UPDATE ops SET status = 'sent', tx_hash = ?, nonce = ?, error = NULL, replacements = replacements + 1, updated_at = ? WHERE key = ?").run(txHash, nonce, now(), key);
+    }
+    /** Fees are cumulative over the operation's attempts: a retried operation's reverted first attempt was paid for too. */
+    addedGasCost(key, gasCostWei) {
+        if (gasCostWei === undefined)
+            return null;
+        return ((this.get(key)?.gasCostWei ?? 0n) + gasCostWei).toString();
+    }
+    markConfirmed(key, txHash, block, result, gasCostWei) {
+        this.transaction(() => {
+            this.db
+                .prepare("UPDATE ops SET status = 'confirmed', tx_hash = ?, block = ?, result = ?, error = NULL, gas_cost_wei = COALESCE(?, gas_cost_wei), updated_at = ? WHERE key = ?")
+                .run(txHash, block, toJson(result), this.addedGasCost(key, gasCostWei), now(), key);
+        });
+    }
+    markFailed(key, error, gasCostWei) {
+        this.transaction(() => {
+            this.db
+                .prepare("UPDATE ops SET status = 'failed', error = ?, gas_cost_wei = COALESCE(?, gas_cost_wei), updated_at = ? WHERE key = ?")
+                .run(error, this.addedGasCost(key, gasCostWei), now(), key);
+        });
+    }
+    /** A failed operation the caller explicitly retries: back to prepared, the failure kept in the journal. */
+    markRetry(key) {
+        this.db.prepare("UPDATE ops SET status = 'prepared', tx_hash = NULL, nonce = NULL, block = NULL, error = NULL, updated_at = ? WHERE key = ?").run(now(), key);
+    }
+    /** Operations of a signer that are claimed or in flight (their reservations are still open). */
+    openOps(signer) {
+        return this.db.prepare("SELECT * FROM ops WHERE signer = ? AND status IN ('prepared', 'sent') ORDER BY created_at, key").all(signer).map(rowToOp);
+    }
+    /**
+     * What a signer's operations spent since `sinceIso` (value moved plus fees paid, confirmed and reverted alike) and
+     * what its open operations still reserve: the two numbers a budget is checked against.
+     */
+    budgetUse(signer, sinceIso) {
+        let spent = 0n;
+        for (const r of this.db.prepare("SELECT value_wei, gas_cost_wei, status FROM ops WHERE signer = ? AND updated_at >= ? AND status IN ('confirmed', 'failed')").all(signer, sinceIso)) {
+            if (r.status === "confirmed")
+                spent += BigInt(r.value_wei ?? "0");
+            spent += BigInt(r.gas_cost_wei ?? "0");
+        }
+        let reserved = 0n;
+        for (const r of this.db.prepare("SELECT value_wei, fee_cap_wei FROM ops WHERE signer = ? AND status IN ('prepared', 'sent')").all(signer)) {
+            reserved += BigInt(r.value_wei ?? "0") + BigInt(r.fee_cap_wei ?? "0");
+        }
+        return { spentWei: spent, reservedWei: reserved };
+    }
+    /** The same figures kept apart: value moved and fees paid since `sinceIso`, and what open operations reserve of each. */
+    budgetBooks(signer, sinceIso) {
+        let valueWei = 0n;
+        let gasWei = 0n;
+        for (const r of this.db.prepare("SELECT value_wei, gas_cost_wei, status FROM ops WHERE signer = ? AND updated_at >= ? AND status IN ('confirmed', 'failed')").all(signer, sinceIso)) {
+            if (r.status === "confirmed")
+                valueWei += BigInt(r.value_wei ?? "0");
+            gasWei += BigInt(r.gas_cost_wei ?? "0");
+        }
+        let reservedValueWei = 0n;
+        let reservedFeeWei = 0n;
+        for (const r of this.db.prepare("SELECT value_wei, fee_cap_wei FROM ops WHERE signer = ? AND status IN ('prepared', 'sent')").all(signer)) {
+            reservedValueWei += BigInt(r.value_wei ?? "0");
+            reservedFeeWei += BigInt(r.fee_cap_wei ?? "0");
+        }
+        // a job that was allowed but whose operations are not prepared yet reserves what its plan moves (less what its operations already carry)
+        for (const j of this.db.prepare("SELECT id, value_wei FROM jobs WHERE status IN ('accepted', 'running') AND value_wei <> '0'").all()) {
+            let carried = 0n;
+            for (const o of this.db.prepare("SELECT value_wei FROM ops WHERE key LIKE ? AND signer = ?").all(`job:${j.id}:%`, signer))
+                carried += BigInt(o.value_wei ?? "0");
+            const planned = BigInt(j.value_wei ?? "0");
+            if (planned > carried)
+                reservedValueWei += planned - carried;
+        }
+        return { valueWei, gasWei, reservedValueWei, reservedFeeWei };
+    }
+    /** Jobs of a kind in given states (the running commitments of a cell, for instance). */
+    countJobs(kind, statuses) {
+        if (!statuses.length)
+            return 0;
+        const marks = statuses.map(() => "?").join(", ");
+        return Number(this.db.prepare(`SELECT COUNT(*) AS n FROM jobs WHERE kind = ? AND status IN (${marks})`).get(kind, ...statuses).n);
+    }
+    // ---------------------------------------------------------------------------- jobs
+    /** Create a job, or return the existing one for the id; the same id with another input is a conflict. */
+    createJob(p) {
+        return this.transaction(() => {
+            const existing = this.getJob(p.id);
+            if (existing) {
+                if (existing.inputHash !== p.inputHash)
+                    throw new OperationConflict(p.id, existing.inputHash, p.inputHash);
+                return existing;
+            }
+            const t = now();
+            this.db
+                .prepare("INSERT INTO jobs (id, kind, status, caller, cell, input_hash, input, operations, value_wei, created_at, updated_at) VALUES (?, ?, 'accepted', ?, ?, ?, ?, '[]', ?, ?, ?)")
+                .run(p.id, p.kind, p.caller ?? null, p.cell ?? null, p.inputHash, toJson(p.input), (p.valueWei ?? 0n).toString(), t, t);
+            return this.getJob(p.id);
+        });
+    }
+    getJob(id) {
+        const row = this.db.prepare("SELECT * FROM jobs WHERE id = ?").get(id);
+        return row ? rowToJob(row) : undefined;
+    }
+    updateJob(id, patch) {
+        return this.transaction(() => {
+            const job = this.getJob(id);
+            if (!job)
+                throw new Error(`no job ${id}`);
+            const operations = patch.addOperation && !job.operations.includes(patch.addOperation) ? [...job.operations, patch.addOperation] : job.operations;
+            this.db
+                .prepare("UPDATE jobs SET status = ?, result = ?, error = ?, operations = ?, updated_at = ? WHERE id = ?")
+                .run(patch.status ?? job.status, patch.result === undefined ? (job.result === null ? null : toJson(job.result)) : toJson(patch.result), patch.error === undefined ? job.error : patch.error, JSON.stringify(operations), now(), id);
+            return this.getJob(id);
+        });
+    }
+    /** Jobs visible to a caller (its own), newest first; `caller` null lists every job (the operator's view). */
+    jobs(caller, limit = 50) {
+        const rows = caller === null
+            ? this.db.prepare("SELECT * FROM jobs ORDER BY created_at DESC LIMIT ?").all(limit)
+            : this.db.prepare("SELECT * FROM jobs WHERE caller = ? ORDER BY created_at DESC LIMIT ?").all(caller, limit);
+        return rows.map(rowToJob);
+    }
+    // ---------------------------------------------------------------------------- decisions
+    /** Write a decision record; returns its id. */
+    decide(d) {
+        this.db
+            .prepare("INSERT INTO decisions (at, entrance, caller, capability, mode, input_hash, verdict, gate, reason, job_id, operation_id, model) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)")
+            .run(now(), d.entrance, d.caller, d.capability, d.mode, d.inputHash, d.verdict, d.gate, d.reason, d.jobId ?? null, d.operationId ?? null, d.model ? toJson(d.model) : null);
+        const row = this.db.prepare("SELECT * FROM decisions ORDER BY id DESC LIMIT 1").get();
+        return rowToDecision(row);
+    }
+    /** Decision records, oldest first; `caller` restricts to one caller's own (a caller sees its own attempts, the operator every one). */
+    decisions(filter = {}) {
+        const where = [];
+        const args = [];
+        if (filter.caller) {
+            where.push("caller = ?");
+            args.push(filter.caller);
+        }
+        if (filter.capability) {
+            where.push("capability = ?");
+            args.push(filter.capability);
+        }
+        if (filter.verdict) {
+            where.push("verdict = ?");
+            args.push(filter.verdict);
+        }
+        if (filter.since) {
+            where.push("at >= ?");
+            args.push(filter.since);
+        }
+        const sql = `SELECT * FROM decisions${where.length ? " WHERE " + where.join(" AND ") : ""} ORDER BY id LIMIT ?`;
+        return this.db.prepare(sql).all(...args, filter.limit ?? 1000).map(rowToDecision);
+    }
+    // ---------------------------------------------------------------------------- facts
+    /** Scenario-level values (ids, addresses, hashes) that later steps and a resumed run read back. */
+    setFact(key, value) {
+        this.db.prepare("INSERT INTO facts (key, value, updated_at) VALUES (?, ?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at").run(key, toJson(value), now());
+    }
+    getFact(key) {
+        const row = this.db.prepare("SELECT value FROM facts WHERE key = ?").get(key);
+        return row ? JSON.parse(row.value) : undefined;
+    }
+    requireFact(key) {
+        const v = this.getFact(key);
+        if (v === undefined)
+            throw new Error(`operation store has no fact ${key}`);
+        return v;
+    }
+    facts(prefix = "") {
+        const out = {};
+        for (const row of this.db.prepare("SELECT key, value FROM facts WHERE key LIKE ? ORDER BY key").all(prefix + "%"))
+            out[row.key] = JSON.parse(row.value);
+        return out;
+    }
+    // ---------------------------------------------------------------------------- journal
+    journal(event, detail, opKey) {
+        this.db.prepare("INSERT INTO journal (at, op_key, event, detail) VALUES (?, ?, ?, ?)").run(now(), opKey ?? null, event, detail ? toJson(detail) : null);
+        return Number(this.db.prepare("SELECT seq FROM journal ORDER BY seq DESC LIMIT 1").get().seq);
+    }
+    journalEntries() {
+        return this.db.prepare("SELECT * FROM journal ORDER BY seq").all().map((r) => ({ seq: Number(r.seq), at: r.at, opKey: r.op_key ?? null, event: r.event, detail: r.detail ? JSON.parse(r.detail) : null }));
+    }
+    // ---------------------------------------------------------------------------- summary
+    summary() {
+        const ops = { prepared: 0, sent: 0, confirmed: 0, failed: 0 };
+        for (const r of this.db.prepare("SELECT status, COUNT(*) AS n FROM ops GROUP BY status").all())
+            ops[r.status] = Number(r.n);
+        const facts = Number(this.db.prepare("SELECT COUNT(*) AS n FROM facts").get().n);
+        const journal = Number(this.db.prepare("SELECT COUNT(*) AS n FROM journal").get().n);
+        const jobs = Number(this.db.prepare("SELECT COUNT(*) AS n FROM jobs").get().n);
+        const decisions = { allowed: 0, refused: 0 };
+        for (const r of this.db.prepare("SELECT verdict, COUNT(*) AS n FROM decisions GROUP BY verdict").all())
+            decisions[r.verdict] = Number(r.n);
+        return { ops, facts, journal, jobs, decisions };
+    }
+}
+function rowToOp(row) {
+    return {
+        key: row.key,
+        kind: row.kind,
+        signer: row.signer,
+        status: row.status,
+        nonce: row.nonce === null || row.nonce === undefined ? null : Number(row.nonce),
+        txHash: row.tx_hash ?? null,
+        block: row.block === null || row.block === undefined ? null : Number(row.block),
+        result: row.result ? JSON.parse(row.result) : null,
+        error: row.error ?? null,
+        attempts: Number(row.attempts ?? 0),
+        replacements: Number(row.replacements ?? 0),
+        requestHash: row.request_hash ?? null,
+        capability: row.capability ?? null,
+        caller: row.caller ?? null,
+        cell: row.cell ?? null,
+        valueWei: BigInt(row.value_wei ?? "0"),
+        feeCapWei: BigInt(row.fee_cap_wei ?? "0"),
+        gasCostWei: row.gas_cost_wei === null || row.gas_cost_wei === undefined ? null : BigInt(row.gas_cost_wei),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+function rowToJob(row) {
+    return {
+        id: row.id,
+        kind: row.kind,
+        status: row.status,
+        caller: row.caller ?? null,
+        cell: row.cell ?? null,
+        inputHash: row.input_hash,
+        input: row.input ? JSON.parse(row.input) : null,
+        result: row.result ? JSON.parse(row.result) : null,
+        error: row.error ?? null,
+        operations: row.operations ? JSON.parse(row.operations) : [],
+        valueWei: BigInt(row.value_wei ?? "0"),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+function rowToDecision(row) {
+    return {
+        id: Number(row.id),
+        at: row.at,
+        entrance: row.entrance,
+        caller: row.caller,
+        capability: row.capability,
+        mode: row.mode,
+        inputHash: row.input_hash,
+        verdict: row.verdict,
+        gate: row.gate,
+        reason: row.reason,
+        jobId: row.job_id ?? null,
+        operationId: row.operation_id ?? null,
+        model: row.model ? JSON.parse(row.model) : null,
+    };
+}