sparta_worlds 0.6.0

package/server/dist/admin/schemas.js

@@ -0,0 +1,243 @@
+import { z } from "zod";
+import { ScenarioSchema } from "../scenario/engine.js";
+export const CreateWorldBody = z
+    .object({
+    seed: z.string().optional().describe("Name of a library seed (see GET /admin/seeds)."),
+    seed_doc: z.unknown().optional().describe("Inline seed document (JSON). Mutually exclusive with `seed`."),
+})
+    .describe("Create a world from a seed. Returns world_id, base_url, api_key, seed_hash. base_url is WORLDS_PUBLIC_URL when the server has one, else the origin this request reached the server at (its Host header; X-Forwarded-Host/Proto under WORLDS_TRUST_PROXY=1) — point your Stripe SDK there.");
+export const MintKeyBody = z
+    .object({})
+    .describe("Mint an additional twin API key (sk_twin_…) for the world — what the agent under test holds. Never an admin credential.");
+export const MintAdminTokenBody = z
+    .object({})
+    .describe("Mint an additional admin token (tlw_<world>_…) for this world. Rotation is mint → switch → revoke the old one; any number may be active.");
+export const MarkBody = z
+    .object({
+    name: z.string().min(1).describe("Mark name. Re-using a name moves the mark."),
+})
+    .describe("Set a named mark at the world's current state, for later diffing.");
+export const DiffQuery = z
+    .object({
+    from: z.string().min(1).describe("Mark name to diff from."),
+})
+    .describe("Diff of world state since a mark: {created, updated, deleted} grouped by resource, plus a `money` block summarizing dollars moved per currency (charges_created, refunds_created, invoices_paid, net_movement — amounts in cents), plus `before`: for every updated or deleted object, its image at the mark, keyed by resource then id — the material for exact field-delta assertions. Events are excluded — query /events instead.");
+export const ClockAdvanceBody = z
+    .object({
+    duration: z
+        .union([z.string(), z.number()])
+        .describe('Duration to advance: "30d", "12h", "45m", "10s", or a number of seconds.'),
+})
+    .describe("Advance the world's logical clock. Due subscription renewals bill immediately, at most 1000 periods per subscription per advance: `renewals_pending` counts the subscriptions still due after that cap, and the next advance continues them. A renewal the twin cannot bill — an invoice whose negative total would be a credit in a currency other than the customer's balance (docs/scope.md, semantics simplifications) — rolls the whole advance back and answers 409 naming the subscription. Due webhook retries dispatch. Returns {clock, advanced_from, advanced_by, renewals_billed, renewals_pending, iso}.");
+export const ApplyScenarioBody = z
+    .object({
+    name: z.string().optional().describe("Name of a library scenario (see GET /admin/scenarios)."),
+    scenario_doc: ScenarioSchema.optional().describe("Inline scenario document. Mutually exclusive with `name`."),
+})
+    .describe("Apply a failure-injection scenario to the world. Replaces any active scenario and resets its counters.");
+export const WebhookEndpointBody = z
+    .object({
+    url: z.string().url().describe("URL to POST events to (e.g. your test harness's localhost listener)."),
+    max_retries: z
+        .number()
+        .int()
+        .min(0)
+        .max(10)
+        .default(3)
+        .describe("Retry attempts after a failed delivery. Backoff is deterministic in logical time: 60s * 2^(attempt-1)."),
+    auto_deliver: z
+        .boolean()
+        .default(true)
+        .describe("Deliver in the background after each request/clock advance. Set false for full manual control via POST .../webhooks/flush."),
+    signature_time: z
+        .enum(["wall", "logical"])
+        .default("wall")
+        .describe('What the Stripe-Signature t= carries. "wall": delivery time, so stock verifiers (stripe-node, stripe-python) accept deliveries with their default 5-minute tolerance. "logical": the world clock, replayable across runs — pass a large tolerance to your verifier (stripe-node: the 4th argument of constructEvent, in seconds; stripe-python: tolerance= on Webhook.construct_event).'),
+})
+    .describe("Configure the world's webhook endpoint. Returns the signing secret (whsec_twin_...).");
+export const ExportSeedQuery = z
+    .object({
+    name: z
+        .string()
+        .regex(/^[a-z0-9][a-z0-9-]*$/)
+        .optional()
+        .describe("Name for the exported seed (kebab-case). Default: <original seed name>-export."),
+})
+    .describe("Export a world's live state as a seed document.");
+export const StateQuery = z
+    .object({
+    limit: z.number().int().min(1).max(1000).optional().describe("Max objects to return (default: all)."),
+})
+    .describe("Query live objects of one resource. Any other query param is an equality filter on a top-level field, e.g. ?customer=cus_x&amount=4000.");
+export const SeedValidateBody = z
+    .object({
+    seed_doc: z.unknown().describe("Seed document to validate."),
+})
+    .describe("Validate a seed document (structure + referential integrity) without creating a world.");
+export const ADMIN_ENDPOINTS = [
+    {
+        method: "GET",
+        path: "/admin/health",
+        summary: 'Liveness check. Returns {ok: true, worlds: <count>, auth: "off" | "required", protocol: <int>, resources: [...]} — clients compare protocol before grading.',
+        auth: "public",
+    },
+    {
+        method: "GET",
+        path: "/admin/seeds",
+        summary: "List library seeds with name, version, hash, and object counts.",
+        auth: "operator",
+    },
+    {
+        method: "GET",
+        path: "/admin/seeds/:name",
+        summary: "One library seed's document with its hash — what `passk --tasks` compiles a tasks file against, so the build sees the bytes this server would load. 404 for a name the library does not hold.",
+        auth: "operator",
+    },
+    {
+        method: "POST",
+        path: "/admin/seeds/validate",
+        summary: "Validate a seed document.",
+        auth: "operator",
+        body: SeedValidateBody,
+    },
+    { method: "GET", path: "/admin/scenarios", summary: "List library scenarios.", auth: "operator" },
+    {
+        method: "POST",
+        path: "/admin/worlds",
+        summary: "Create a world from a seed. Returns world_id, base_url, api_key (for the agent), and admin_token (for the harness — shown once).",
+        auth: "operator",
+        body: CreateWorldBody,
+    },
+    {
+        method: "GET",
+        path: "/admin/worlds",
+        summary: "List worlds. `unreadable` names world files this runtime refuses (another schema version, or not a readable world file) and why; destroy them.",
+        auth: "operator",
+    },
+    {
+        method: "GET",
+        path: "/admin/worlds/:id",
+        summary: "World info: seed, clock, twin keys, admin-token count, webhook config, active scenario.",
+        auth: "world",
+    },
+    {
+        method: "POST",
+        path: "/admin/worlds/:id/reset",
+        summary: "Reset the world to its seed. Keeps API keys (their use counters restart), admin tokens, and the webhook endpoint config; wipes objects, events, idempotency records, marks, counters, the scenario, deliveries and the request log. Waits (up to 5 s) for twin requests already in flight, admits new ones only once it is done, and fences off a webhook delivery in flight — so a reset world replays byte-identically to a fresh one, quiescent or not.",
+        auth: "world",
+    },
+    {
+        method: "DELETE",
+        path: "/admin/worlds/:id",
+        summary: "Destroy the world and its SQLite file (its tokens die with it).",
+        auth: "world",
+    },
+    {
+        method: "POST",
+        path: "/admin/worlds/:id/keys",
+        summary: "Mint an additional twin API key.",
+        auth: "world",
+        body: MintKeyBody,
+    },
+    {
+        method: "POST",
+        path: "/admin/worlds/:id/admin-tokens",
+        summary: "Mint an additional admin token for this world. Returns {admin_token, active}.",
+        auth: "world",
+        body: MintAdminTokenBody,
+    },
+    {
+        method: "DELETE",
+        path: "/admin/worlds/:id/admin-tokens/:token",
+        summary: "Revoke one of this world's admin tokens. Returns {revoked: true, active}; 404 if it was not active.",
+        auth: "world",
+    },
+    {
+        method: "GET",
+        path: "/admin/worlds/:id/state/:resource",
+        summary: "Query live objects of a resource with equality filters.",
+        auth: "world",
+        query: StateQuery,
+    },
+    {
+        method: "GET",
+        path: "/admin/worlds/:id/events",
+        summary: "The world's event log, in creation order. Filter with ?type=, and ?after_seq=<mark seq> for the events emitted after a mark (the seq a mark reports; objects created in one shift share a clock second, so this order is the only order).",
+        auth: "world",
+    },
+    {
+        method: "GET",
+        path: "/admin/worlds/:id/requests",
+        summary: "Every twin API request this world served: method, path, status, whether the response was scenario-injected, whether the route is implemented, and `unsupported` — the parameter the twin refused on an implemented route (docs/scope.md, Refused parameters), null otherwise. ?unmatched=true returns the coverage view — un-twinned endpoints the agent tried to call and parameters the twin refused, grouped and ranked.",
+        auth: "world",
+    },
+    { method: "POST", path: "/admin/worlds/:id/marks", summary: "Set a named mark.", auth: "world", body: MarkBody },
+    { method: "GET", path: "/admin/worlds/:id/marks", summary: "List marks.", auth: "world" },
+    {
+        method: "GET",
+        path: "/admin/worlds/:id/diff",
+        summary: "Diff world state since a mark.",
+        auth: "world",
+        query: DiffQuery,
+    },
+    { method: "GET", path: "/admin/worlds/:id/clock", summary: "Read the logical clock.", auth: "world" },
+    {
+        method: "POST",
+        path: "/admin/worlds/:id/clock/advance",
+        summary: "Advance the logical clock.",
+        auth: "world",
+        body: ClockAdvanceBody,
+    },
+    {
+        method: "POST",
+        path: "/admin/worlds/:id/scenario",
+        summary: "Apply a failure-injection scenario.",
+        auth: "world",
+        body: ApplyScenarioBody,
+    },
+    { method: "GET", path: "/admin/worlds/:id/scenario", summary: "Read the active scenario.", auth: "world" },
+    {
+        method: "DELETE",
+        path: "/admin/worlds/:id/scenario",
+        summary: "Clear the active scenario and its counters.",
+        auth: "world",
+    },
+    {
+        method: "POST",
+        path: "/admin/worlds/:id/webhook-endpoint",
+        summary: "Configure the webhook endpoint.",
+        auth: "world",
+        body: WebhookEndpointBody,
+    },
+    {
+        method: "DELETE",
+        path: "/admin/worlds/:id/webhook-endpoint",
+        summary: "Remove the webhook endpoint.",
+        auth: "world",
+    },
+    {
+        method: "GET",
+        path: "/admin/worlds/:id/webhook-deliveries",
+        summary: "Webhook delivery queue with statuses and attempt counts.",
+        auth: "world",
+    },
+    {
+        method: "POST",
+        path: "/admin/worlds/:id/webhooks/flush",
+        summary: "Synchronously deliver all currently-eligible pending webhooks. Returns per-delivery results.",
+        auth: "world",
+    },
+    {
+        method: "GET",
+        path: "/admin/worlds/:id/export-seed",
+        summary: "Export the world's live state back into a valid seed document (fork a world). ?name= sets the seed name (kebab-case; default <seed>-export). Response includes the seed_doc, its hash, counts, and a lossy report (refunds, PIs, events, and other non-seedable history are dropped and counted).",
+        auth: "world",
+        query: ExportSeedQuery,
+    },
+    {
+        method: "GET",
+        path: "/admin/worlds/:id/dump",
+        summary: "Canonical JSON export of all world-visible state (the determinism artifact). Admin tokens and twin keys are not world-visible and never appear here.",
+        auth: "world",
+    },
+];

package/server/dist/app.js

@@ -0,0 +1,112 @@
+import { chmodSync, existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import Fastify from "fastify";
+import { adminAuthHook, OPERATOR_TOKEN_MIN_LENGTH, resolveAuthMode, } from "./admin/auth.js";
+import { registerAdminApi } from "./admin/routes.js";
+import { WorldManager } from "./core/manager.js";
+import { newOperatorToken } from "./core/nondeterministic.js";
+import { resolveLibraryDirs } from "./core/paths.js";
+import { normalizePublicUrl, resolvePublicUrl } from "./core/publicUrl.js";
+import { createLayeredScenarioLibrary } from "./scenario/library.js";
+import { registerTwinApi } from "./twin/router.js";
+import { WebhookDispatcher } from "./webhooks/dispatcher.js";
+function firstForwardedEntry(value) {
+    if (value === undefined)
+        return undefined;
+    const raw = Array.isArray(value) ? value[0] : value;
+    const first = raw.split(",")[0]?.trim();
+    return first ? first : undefined;
+}
+export function buildServer(opts = {}) {
+    const explicitUrl = opts.publicUrl !== undefined && opts.publicUrl !== "" ? normalizePublicUrl(opts.publicUrl) : undefined;
+    const manager = new WorldManager({ dataDir: opts.dataDir, seedsDir: opts.seedsDir });
+    const dispatcher = new WebhookDispatcher();
+    const scenarios = createLayeredScenarioLibrary(resolveLibraryDirs("scenarios", opts.scenariosDir));
+    const app = Fastify({ logger: opts.logger ?? false, trustProxy: opts.trustProxy ?? false });
+    app.addContentTypeParser("application/x-www-form-urlencoded", { parseAs: "string" }, (_req, body, done) => {
+        done(null, body);
+    });
+    app.addContentTypeParser("application/json", { parseAs: "string" }, (_req, body, done) => {
+        if (typeof body !== "string" || body.trim() === "")
+            return done(null, undefined);
+        try {
+            done(null, JSON.parse(body));
+        }
+        catch (err) {
+            done(err, undefined);
+        }
+    });
+    let bound = { host: "127.0.0.1", port: 4242 };
+    const requestOrigin = (req) => {
+        const socket = req.raw.socket;
+        const own = { protocol: socket?.encrypted ? "https" : "http", hostname: req.headers.host };
+        if (!opts.trustProxy)
+            return own;
+        return {
+            protocol: firstForwardedEntry(req.headers["x-forwarded-proto"]) ?? own.protocol,
+            hostname: firstForwardedEntry(req.headers["x-forwarded-host"]) ?? own.hostname,
+        };
+    };
+    const publicUrl = (req) => resolvePublicUrl({
+        explicit: explicitUrl,
+        request: req ? requestOrigin(req) : undefined,
+        listen: bound,
+    });
+    let authState = {
+        mode: resolveAuthMode({ host: "127.0.0.1", mode: opts.auth?.mode, operatorToken: opts.auth?.operatorToken }),
+        operatorToken: opts.auth?.operatorToken,
+        host: "127.0.0.1",
+    };
+    const auth = () => authState;
+    app.addHook("onRequest", adminAuthHook(auth, manager));
+    registerTwinApi(app, manager, dispatcher);
+    registerAdminApi(app, { manager, dispatcher, scenarios, publicUrl, auth });
+    return {
+        app,
+        manager,
+        dispatcher,
+        scenarios,
+        async listen(port = 4242, host = "127.0.0.1") {
+            const trustProxy = opts.trustProxy ?? false;
+            const mode = resolveAuthMode({
+                host,
+                mode: opts.auth?.mode,
+                operatorToken: opts.auth?.operatorToken,
+                trustProxy,
+            });
+            let operatorToken = opts.auth?.operatorToken;
+            let provisioned;
+            if (mode === "required" && !operatorToken) {
+                const file = join(manager.dataDir, "operator-token");
+                if (existsSync(file)) {
+                    operatorToken = readFileSync(file, "utf8").trim() || undefined;
+                    if (operatorToken && operatorToken.length < OPERATOR_TOKEN_MIN_LENGTH) {
+                        throw new Error(`operator token in ${file} must be at least ${OPERATOR_TOKEN_MIN_LENGTH} characters (got ${operatorToken.length}); fix or delete the file`);
+                    }
+                    if ((statSync(file).mode & 0o077) !== 0)
+                        chmodSync(file, 0o600);
+                }
+                if (operatorToken) {
+                    provisioned = { file, created: false };
+                }
+                else {
+                    operatorToken = newOperatorToken();
+                    writeFileSync(file, `${operatorToken}\n`, { mode: 0o600 });
+                    provisioned = { file, created: true };
+                }
+            }
+            authState = { mode, operatorToken, host, provisioned, trustProxy };
+            const address = await app.listen({ port, host });
+            const actual = app.server.address();
+            bound = { host, port: actual && typeof actual === "object" ? actual.port : port };
+            return address;
+        },
+        port: () => bound.port,
+        publicUrl: () => publicUrl(),
+        auth,
+        async close() {
+            await app.close();
+            manager.closeAll();
+        },
+    };
+}

package/server/dist/core/canonical.js

@@ -0,0 +1,22 @@
+import { createHash } from "node:crypto";
+export function canonicalJson(value) {
+    return JSON.stringify(sortValue(value));
+}
+function sortValue(value) {
+    if (Array.isArray(value))
+        return value.map(sortValue);
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            out[key] = sortValue(value[key]);
+        }
+        return out;
+    }
+    return value;
+}
+export function sha256Hex(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+export function canonicalHash(value) {
+    return sha256Hex(canonicalJson(value));
+}

package/server/dist/core/db.js

@@ -0,0 +1,294 @@
+import { DatabaseSync } from "node:sqlite";
+export const SCHEMA_VERSION = 4;
+export const SCHEMA = `
+CREATE TABLE IF NOT EXISTS meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS objects (
+  id TEXT PRIMARY KEY,
+  resource TEXT NOT NULL,
+  data TEXT NOT NULL,
+  created INTEGER NOT NULL,
+  created_seq INTEGER NOT NULL,
+  updated_seq INTEGER NOT NULL,
+  deleted_seq INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_objects_resource ON objects(resource, created_seq);
+CREATE TABLE IF NOT EXISTS events (
+  id TEXT PRIMARY KEY,
+  seq INTEGER NOT NULL,
+  type TEXT NOT NULL,
+  created INTEGER NOT NULL,
+  data TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_events_seq ON events(seq);
+CREATE TABLE IF NOT EXISTS idempotency (
+  key TEXT PRIMARY KEY,
+  method TEXT NOT NULL,
+  path TEXT NOT NULL,
+  params_hash TEXT NOT NULL,
+  status INTEGER NOT NULL,
+  body TEXT NOT NULL,
+  created INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS api_keys (
+  key TEXT PRIMARY KEY,
+  requests_used INTEGER NOT NULL DEFAULT 0,
+  expired INTEGER NOT NULL DEFAULT 0
+);
+CREATE TABLE IF NOT EXISTS admin_tokens (
+  token TEXT PRIMARY KEY
+);
+CREATE TABLE IF NOT EXISTS marks (
+  name TEXT PRIMARY KEY,
+  seq INTEGER NOT NULL,
+  clock INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS counters (
+  name TEXT PRIMARY KEY,
+  value INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS scenario (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  doc TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS webhook_config (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  url TEXT NOT NULL,
+  secret TEXT NOT NULL,
+  max_retries INTEGER NOT NULL DEFAULT 3,
+  auto_deliver INTEGER NOT NULL DEFAULT 1,
+  signature_time TEXT NOT NULL DEFAULT 'wall' CHECK (signature_time IN ('wall', 'logical'))
+);
+CREATE TABLE IF NOT EXISTS request_log (
+  seq INTEGER PRIMARY KEY AUTOINCREMENT,
+  method TEXT NOT NULL,
+  path TEXT NOT NULL,
+  status INTEGER NOT NULL,
+  injected INTEGER NOT NULL DEFAULT 0,
+  matched INTEGER NOT NULL DEFAULT 1,
+  unsupported TEXT,
+  clock INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS webhook_deliveries (
+  seq INTEGER PRIMARY KEY,
+  event_id TEXT NOT NULL,
+  url TEXT NOT NULL,
+  status TEXT NOT NULL,
+  attempts INTEGER NOT NULL DEFAULT 0,
+  next_attempt_at INTEGER,
+  last_status_code INTEGER,
+  last_error TEXT
+);
+CREATE TABLE IF NOT EXISTS object_versions (
+  id TEXT NOT NULL,
+  resource TEXT NOT NULL,
+  data TEXT NOT NULL,
+  valid_from_seq INTEGER NOT NULL,
+  valid_to_seq INTEGER NOT NULL,
+  PRIMARY KEY (id, valid_to_seq)
+);
+`;
+export function countPlaceholders(sql) {
+    let n = 0;
+    let i = 0;
+    const len = sql.length;
+    while (i < len) {
+        const c = sql[i];
+        if (c === "'" || c === '"' || c === "`") {
+            i++;
+            while (i < len) {
+                if (sql[i] === c) {
+                    if (sql[i + 1] === c) {
+                        i += 2;
+                        continue;
+                    }
+                    break;
+                }
+                i++;
+            }
+            i++;
+            continue;
+        }
+        if (c === "[") {
+            const end = sql.indexOf("]", i + 1);
+            i = end < 0 ? len : end + 1;
+            continue;
+        }
+        if (c === "-" && sql[i + 1] === "-") {
+            const end = sql.indexOf("\n", i);
+            i = end < 0 ? len : end + 1;
+            continue;
+        }
+        if (c === "/" && sql[i + 1] === "*") {
+            const end = sql.indexOf("*/", i + 2);
+            i = end < 0 ? len : end + 2;
+            continue;
+        }
+        if (c === "?") {
+            const next = sql.charCodeAt(i + 1);
+            if (next >= 48 && next <= 57)
+                throw new TypeError(`WorldDb: numbered placeholders (?NNN) are not supported: ${sqlPrefix(sql)}`);
+            n++;
+            i++;
+            continue;
+        }
+        if (c === ":" || c === "@" || c === "$") {
+            const next = sql[i + 1] ?? "";
+            if (/[A-Za-z_]/.test(next))
+                throw new TypeError(`WorldDb: named placeholders (${c}name) are not supported: ${sqlPrefix(sql)}`);
+        }
+        i++;
+    }
+    return n;
+}
+function sqlPrefix(sql) {
+    const flat = sql.replace(/\s+/g, " ").trim();
+    return flat.length > 80 ? `${flat.slice(0, 77)}...` : flat;
+}
+function checkArity(sql, expected, got) {
+    if (got !== expected) {
+        throw new RangeError(`WorldDb: statement expects ${expected} bind parameter${expected === 1 ? "" : "s"}, got ${got}: ${sqlPrefix(sql)}`);
+    }
+}
+function bind(params) {
+    return params.map((p) => {
+        if (p === undefined)
+            return null;
+        if (typeof p === "boolean")
+            return p ? 1 : 0;
+        return p;
+    });
+}
+function plain(row) {
+    const out = {};
+    for (const key in row) {
+        const v = row[key];
+        out[key] = typeof v === "bigint" ? Number(v) : v;
+    }
+    return out;
+}
+class NodeSqliteDb {
+    db;
+    depth = 0;
+    stmts = new Map();
+    constructor(db) {
+        this.db = db;
+    }
+    prepare(sql) {
+        const cached = this.stmts.get(sql);
+        if (cached)
+            return cached;
+        const expected = countPlaceholders(sql);
+        const stmt = this.db.prepare(sql);
+        stmt.setReadBigInts(true);
+        const wrapped = {
+            get: (...params) => {
+                checkArity(sql, expected, params.length);
+                const row = stmt.get(...bind(params));
+                return row === undefined ? undefined : plain(row);
+            },
+            all: (...params) => {
+                checkArity(sql, expected, params.length);
+                return stmt.all(...bind(params)).map((r) => plain(r));
+            },
+            run: (...params) => {
+                checkArity(sql, expected, params.length);
+                const res = stmt.run(...bind(params));
+                return { changes: Number(res.changes), lastInsertRowid: Number(res.lastInsertRowid) };
+            },
+        };
+        this.stmts.set(sql, wrapped);
+        return wrapped;
+    }
+    exec(sql) {
+        this.db.exec(sql);
+    }
+    transaction(fn) {
+        if (this.depth > 0) {
+            const sp = `sp_${this.depth}`;
+            this.db.exec(`SAVEPOINT ${sp}`);
+            this.depth++;
+            try {
+                const out = fn();
+                this.db.exec(`RELEASE ${sp}`);
+                return out;
+            }
+            catch (err) {
+                if (this.db.isTransaction) {
+                    this.db.exec(`ROLLBACK TO ${sp}`);
+                    this.db.exec(`RELEASE ${sp}`);
+                }
+                throw err;
+            }
+            finally {
+                this.depth--;
+            }
+        }
+        this.db.exec("BEGIN");
+        this.depth = 1;
+        try {
+            const out = fn();
+            this.db.exec("COMMIT");
+            return out;
+        }
+        catch (err) {
+            if (this.db.isTransaction)
+                this.db.exec("ROLLBACK");
+            throw err;
+        }
+        finally {
+            this.depth = 0;
+        }
+    }
+    close() {
+        this.stmts.clear();
+        this.db.close();
+    }
+}
+export function openWorldDb(file) {
+    const raw = new DatabaseSync(file);
+    raw.exec("PRAGMA journal_mode = WAL");
+    raw.exec("PRAGMA synchronous = OFF");
+    raw.exec(SCHEMA);
+    return new NodeSqliteDb(raw);
+}
+export function peekSchemaVersion(file) {
+    let raw;
+    try {
+        raw = new DatabaseSync(file, { readOnly: true });
+    }
+    catch (err) {
+        if (!isSqliteError(err))
+            throw err;
+        return { kind: "unreadable", reason: err.message };
+    }
+    try {
+        const tables = raw
+            .prepare("SELECT name FROM sqlite_master WHERE type = 'table'")
+            .all()
+            .map((r) => r.name);
+        if (tables.length === 0)
+            return { kind: "unreadable", reason: "empty file" };
+        if (!tables.includes("meta"))
+            return { kind: "version", version: 1 };
+        const row = raw.prepare("SELECT CAST(value AS TEXT) AS value FROM meta WHERE key = 'schema_version'").get();
+        if (!row)
+            return { kind: "version", version: 1 };
+        if (row.value === null || !/^\d+$/.test(row.value))
+            return { kind: "unreadable", reason: `schema_version is ${JSON.stringify(row.value)}, not a number` };
+        return { kind: "version", version: Number(row.value) };
+    }
+    catch (err) {
+        if (!isSqliteError(err))
+            throw err;
+        return { kind: "unreadable", reason: err.message };
+    }
+    finally {
+        raw.close();
+    }
+}
+function isSqliteError(err) {
+    return err instanceof Error && err.code === "ERR_SQLITE_ERROR";
+}