@gr8ful/spf 0.14.0 → 0.16.0

package/dist/core/session.js

@@ -66,24 +66,41 @@ function handleSignal(signal) {
         process.exit(code);
     draining = true;
     const runs = [...ACTIVE.values()]; // snapshot: finalize() may mutate ACTIVE mid-drain
-    for (const run of runs)
-        run.tracer.sessionFinish(run.adw_id, false); // also closes process rows
+    // `sessionFinish` is now async (see tracer.ts's header — a D1-backed run's
+    // write is a real network call) — a signal handler cannot itself be async,
+    // so this fires every run's finish without awaiting it directly. For the
+    // LOCAL backend that costs nothing: `LocalTraceDb` performs the write
+    // SYNCHRONOUSLY before ever returning the (already-resolved) Promise this
+    // discards, so by the time `sessionFinish(...)` returns here the write has
+    // already landed — same as before this class existed. Only a run whose
+    // `tracer.dbPath` is `null` (d1-backed — see `Tracer.open`) is genuinely
+    // still in flight at this point, so ONLY THEN does this add a bounded wait
+    // (same `SIGNAL_DRAIN_MS` budget the otel/notify drains already use) before
+    // exiting — a killed D1-backed run gets a real chance to land its final
+    // write, and every local-only repo keeps exiting with no extra tick.
+    const finishes = runs.map((run) => run.tracer.sessionFinish(run.adw_id, false).catch(() => { })); // also closes process rows
+    const anyRemote = runs.some((run) => run.tracer.dbPath === null);
     const drains = [];
+    if (anyRemote)
+        drains.push(Promise.race([Promise.all(finishes), sleep(SIGNAL_DRAIN_MS)]).then(() => { }));
     if (runs.some((run) => run.tracer.otel))
         drains.push(otel.flushAll(SIGNAL_DRAIN_MS));
     if (runs.some((run) => run.notify))
         drains.push(drainNotifiers(SIGNAL_DRAIN_MS));
-    // Unconfigured (the default) exits SYNCHRONOUSLY, exactly as it did before
-    // otel/notify existed — no extra tick between the signal and the exit for
-    // the repos that never opted in to either.
+    // Unconfigured, local-only (the default) exits SYNCHRONOUSLY, exactly as it
+    // did before otel/notify/D1 existed — no extra tick between the signal and
+    // the exit for the repos that never opted in to any of the three.
     if (drains.length === 0) {
         process.exit(code);
         return;
     }
-    // Bounded and never-throwing: both drains swallow their own failures and
-    // resolve on their own deadline, so this always reaches process.exit().
+    // Bounded and never-throwing: every drain swallows its own failures and
+    // resolves on its own deadline, so this always reaches process.exit().
     void Promise.all(drains).then(() => process.exit(code), () => process.exit(code));
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms).unref());
+}
 function finalizeWhenKilled(run) {
     ACTIVE.set(run.adw_id, run);
     if (installed)
@@ -114,14 +131,14 @@ function finalizeWhenKilled(run) {
  * `releaseOtelExporter`, and harmless for the same reason: that process
  * exits right after anyway.
  */
-export function finalize(adwId) {
+export async function finalize(adwId) {
     if (!adwId)
         return;
     const run = ACTIVE.get(adwId);
     if (!run)
         return;
     ACTIVE.delete(adwId);
-    run.tracer.close();
+    await run.tracer.close();
 }
 /** Tests only: which adw_ids the process-wide signal handler currently considers active. */
 export function activeRunIdsForTest() {
@@ -138,7 +155,7 @@ export function activeRunIdsForTest() {
  * longer a `process.argv[1]` basename that means anything. Direct callers
  * that have no chain of their own fall back to `"adw"`.
  */
-export function ensure(cfg, adwId, cwd, chainName, 
+export async function ensure(cfg, adwId, cwd, chainName, 
 /** See `RunObserver`'s doc comment (`core/console.ts`). Omitted for every caller except an interactive `cli/commands/run.ts` dispatch — a `spf watch` per-issue run, `spf fanout`'s per-attempt runs, and every test all continue to build a plain, unobserved `Console`. */
 renderHooks) {
     const id = adwId || newId(8);
@@ -147,16 +164,20 @@ renderHooks) {
     // `null` unless `observability.otel` is configured — no environment variable
     // can turn this on (see core/otel.ts's EXPLICIT CONFIG ONLY). Constructed
     // BEFORE the Tracer because the Tracer's write methods are the fan-out
-    // seams: SQLite stays the source of truth, otel is a projection off it, and
-    // registering here (module-level LIVE, exactly like resolveNotifier) is what
-    // lets the CLI's finally block and the signal handler above drain it without
-    // threading a handle through every call site.
+    // seams: the trace db stays the source of truth, otel is a projection off
+    // it, and registering here (module-level LIVE, exactly like
+    // resolveNotifier) is what lets the CLI's finally block and the signal
+    // handler above drain it without threading a handle through every call site.
     const otelExporter = otel.resolveOtelExporter(cfg, { adwId: id, chainName: chainName || "adw" });
-    const tracer = new Tracer(dataPaths.db_path, path.join(dataPaths.sessions_dir, id, "events.jsonl"), otelExporter);
+    const tracer = await Tracer.open(dataPaths.db, path.join(dataPaths.sessions_dir, id, "events.jsonl"), otelExporter);
+    // `maxPhaseSeq` is a real trace-db read now (D1: a network call) — resolved
+    // BEFORE `new Run(...)` because `Run`'s constructor cannot itself be async.
+    const startSeq = await tracer.maxPhaseSeq(id);
     const run = new Run({
         cfg,
         adwId: id,
         tracer,
+        startSeq,
         engineer: engineerName(),
         repoRoot: anchor.repo_root,
         sfDir: anchor.spf_dir,
@@ -167,11 +188,11 @@ renderHooks) {
         observer: renderHooks?.observer,
     });
     const scriptPath = process.argv[1] || "adw";
-    tracer.sessionStart(id, run.engineer, chainName || "adw");
+    await tracer.sessionStart(id, run.engineer, chainName || "adw");
     // This process is the run. Record it before any phase opens, so a run that
     // hangs in its first agent call is still killable by adw_id.
-    tracer.processStart(id, "adw", "", process.pid ?? -1, [path.basename(scriptPath), ...process.argv.slice(2)].join(" "));
+    await tracer.processStart(id, "adw", "", process.pid ?? -1, [path.basename(scriptPath), ...process.argv.slice(2)].join(" "));
     finalizeWhenKilled(run);
-    run.console.sessionStarted(id, run.engineer);
+    await run.console.sessionStarted(id, run.engineer);
     return run;
 }

package/dist/core/sqlite.d.ts

@@ -25,13 +25,20 @@
  *    come back with a null prototype. Both are normalized below so existing
  *    `?? null` / `Object.assign(row, ...)` call sites stay honest.
  *  - node:sqlite defaults `enableForeignKeyConstraints: true` — unlike plain
- *    SQLite and bun:sqlite, which both default FK enforcement OFF. The
- *    tracer's schema uses `REFERENCES` purely as documentation (rows are not
- *    always inserted parent-before-child — e.g. the very first `events` row
- *    for a session lands before that session's own `sessions` row commits),
- *    so this is disabled explicitly to restore the behavior the rest of the
- *    codebase was written against. Confirmed by reproduction: enabling it
- *    throws `FOREIGN KEY constraint failed` on session start.
+ *    SQLite and bun:sqlite, which both default FK enforcement OFF — so this
+ *    is disabled explicitly to restore the behavior the rest of the
+ *    codebase was written against. `tracer.ts`'s SCHEMA carries no
+ *    `REFERENCES` clauses at all (removed for SPF #66: rows are not always
+ *    inserted parent-before-child — e.g. the very first `events` row for a
+ *    session lands before that session's own `sessions` row commits, and an
+ *    event recorded outside any phase carries `phase_id: ""`, never NULL —
+ *    and Cloudflare D1 enforces FKs UNCONDITIONALLY with no way to disable
+ *    them, so a clause that was already only decorative on local sqlite
+ *    would crash every D1 session outright). This setting is now a no-op
+ *    for `tracer.ts`'s own tables specifically, but is kept here as this
+ *    wrapper's general default — `cli/commands/abort.ts` and `migrate.ts`
+ *    also open a plain `Database` against the same db file for their own
+ *    ad-hoc queries, and neither has any reason to want FK enforcement on.
  */
 export interface DatabaseOptions {
     readonly?: boolean;

package/dist/core/sqlite.js

@@ -25,13 +25,20 @@
  *    come back with a null prototype. Both are normalized below so existing
  *    `?? null` / `Object.assign(row, ...)` call sites stay honest.
  *  - node:sqlite defaults `enableForeignKeyConstraints: true` — unlike plain
- *    SQLite and bun:sqlite, which both default FK enforcement OFF. The
- *    tracer's schema uses `REFERENCES` purely as documentation (rows are not
- *    always inserted parent-before-child — e.g. the very first `events` row
- *    for a session lands before that session's own `sessions` row commits),
- *    so this is disabled explicitly to restore the behavior the rest of the
- *    codebase was written against. Confirmed by reproduction: enabling it
- *    throws `FOREIGN KEY constraint failed` on session start.
+ *    SQLite and bun:sqlite, which both default FK enforcement OFF — so this
+ *    is disabled explicitly to restore the behavior the rest of the
+ *    codebase was written against. `tracer.ts`'s SCHEMA carries no
+ *    `REFERENCES` clauses at all (removed for SPF #66: rows are not always
+ *    inserted parent-before-child — e.g. the very first `events` row for a
+ *    session lands before that session's own `sessions` row commits, and an
+ *    event recorded outside any phase carries `phase_id: ""`, never NULL —
+ *    and Cloudflare D1 enforces FKs UNCONDITIONALLY with no way to disable
+ *    them, so a clause that was already only decorative on local sqlite
+ *    would crash every D1 session outright). This setting is now a no-op
+ *    for `tracer.ts`'s own tables specifically, but is kept here as this
+ *    wrapper's general default — `cli/commands/abort.ts` and `migrate.ts`
+ *    also open a plain `Database` against the same db file for their own
+ *    ad-hoc queries, and neither has any reason to want FK enforcement on.
  */
 import { DatabaseSync } from "node:sqlite";
 /**

package/dist/core/trace_db.d.ts

@@ -0,0 +1,118 @@
+/**
+ * TraceDb: the async storage interface the trace database (`Tracer`'s writes,
+ * `SfDb`'s reads) is built against — one interface, two backends.
+ *
+ * WHY ASYNC, WHEN `core/sqlite.ts`'s `Database` IS SYNCHRONOUS: Cloudflare
+ * D1's only way to reach a database from a plain Node process (this CLI —
+ * not a Cloudflare Worker, which would get a real binding) is its HTTP REST
+ * API — a network call, inescapably async. Rather than fake synchrony over
+ * that (shelling out to curl, a busy-wait/sync-XHR trick), every caller
+ * upstream of storage (`Tracer`'s write methods, `SfDb`'s read methods) is
+ * async too — see those modules' own headers for how far that propagates.
+ * `LocalTraceDb` below pays that cost for nothing (every call still runs
+ * synchronously, immediately; only the return value is wrapped as a settled
+ * `Promise`) so the local path stays byte-for-byte the same behavior it
+ * always had, just awaited.
+ *
+ * `query(sql)` mirrors `core/sqlite.ts`'s `Statement` shape exactly, only
+ * every method returns a `Promise` — so a caller migrating from `Database`
+ * changes `.get(...)` to `await .get(...)` and nothing else.
+ */
+import { type DatabaseOptions } from "./sqlite.ts";
+import type { NormalizedObservabilityDb } from "./data_types.ts";
+export interface AsyncStatement<Row, Params extends unknown[]> {
+    get(...params: Params): Promise<Row | null>;
+    all(...params: Params): Promise<Row[]>;
+    run(...params: Params): Promise<{
+        changes: number;
+        lastInsertRowid: number | bigint;
+    }>;
+}
+export interface TraceDb {
+    query<Row = unknown, Params extends unknown[] = unknown[]>(sql: string): AsyncStatement<Row, Params>;
+    /** One or more `;`-separated statements — schema DDL and additive migrations. */
+    exec(sql: string): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * A thin async wrapper over the existing synchronous `Database` — every call
+ * is dispatched immediately, synchronously, and its result (or thrown error)
+ * is handed back as an already-settled `Promise` (via an `async` wrapper, so
+ * a synchronous throw becomes a rejection rather than escaping the `Promise`
+ * contract). Zero behavior change from `Database` itself; only the signature
+ * is async, so this backend and `D1TraceDb` satisfy the exact same `TraceDb`
+ * interface.
+ *
+ * `core/sqlite.ts` is deliberately left untouched — `cli/commands/abort.ts`
+ * and `cli/commands/migrate.ts` still open a plain `Database` directly for
+ * local-file-specific operations (marking a session aborted, physically
+ * relocating the db file) that have no D1 equivalent. See those files' own
+ * D1 guards.
+ */
+export declare class LocalTraceDb implements TraceDb {
+    private readonly db;
+    constructor(dbPath: string, options?: DatabaseOptions);
+    query<Row = unknown, Params extends unknown[] = unknown[]>(sql: string): AsyncStatement<Row, Params>;
+    exec(sql: string): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * D1 IS NOT LOCAL WAL SQLITE — DO NOT ASSUME THE SAME LIVE-READ GUARANTEE.
+ *
+ * `core/tracer.ts`'s header describes the local backend's contract: WAL mode
+ * lets `spf ui` read the trace db WHILE an ADW process is still writing to
+ * it, in the same instant, because both sides share one file on one
+ * filesystem. A D1-backed repo has no such single file to share — `spf ui`
+ * and a running chain each speak to D1 over independent HTTP calls, and (per
+ * Cloudflare's own docs, https://developers.cloudflare.com/d1/best-practices/read-replication/)
+ * a D1 database with read replication enabled offers SEQUENTIAL consistency,
+ * not read-your-own-writes by default: a read immediately after a write can
+ * land on a replica that has not caught up yet. D1's Sessions API closes that
+ * gap with a "bookmark" a caller can pin subsequent reads to, but this
+ * adapter does not use it (a bookmark is a client-scoped promise across ONE
+ * lightweight connection; a Tracer that mints a fresh request per write and
+ * an SfDb serving unrelated browser requests have no session to share it
+ * through). This is a deliberate, documented trade-off (SPF #66) — not a bug
+ * to fix here: a D1-backed repo's UI may briefly show a slightly-stale trace
+ * while a chain is actively writing. Nothing about phase/gate/run OUTCOMES
+ * depends on that live read — see tracer.ts's header, "SQLite is the source
+ * of truth; nothing downstream of it can affect a phase, a gate, or a run
+ * outcome" holds exactly the same way against D1.
+ */
+export declare class D1TraceDb implements TraceDb {
+    private readonly accountId;
+    private readonly apiToken;
+    private readonly databaseId;
+    private readonly fetchImpl;
+    private readonly baseUrl;
+    constructor(config: Extract<NormalizedObservabilityDb, {
+        kind: "d1";
+    }>, 
+    /** Injectable so tests never touch the real network — defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch);
+    query<Row = unknown, Params extends unknown[] = unknown[]>(sql: string): AsyncStatement<Row, Params>;
+    /**
+     * D1's HTTP `/query` endpoint accepts exactly one statement per `sql`
+     * field (see the Workers binding's `prepare()`/`batch()` split — the HTTP
+     * endpoint's single-request shape mirrors `prepare()`, not `exec()`);
+     * `exec()` here — schema DDL and additive `ALTER TABLE` migrations, always
+     * multiple statements — splits the text into individual statements and
+     * sends them as one `batch` request instead, which D1 documents as
+     * running sequentially and atomically. The split is naive (`;` at
+     * statement end, one statement per line-ish chunk) because this only ever
+     * runs against `tracer.ts`'s own hand-written `SCHEMA`/`MIGRATIONS`
+     * constants — never arbitrary or user-supplied SQL.
+     */
+    exec(sql: string): Promise<void>;
+    close(): Promise<void>;
+    private runOne;
+    private post;
+}
+export interface CreateTraceDbOptions {
+    /** Local (`sqlite`) only — opens the connection read-only, matching `SfDb`'s reader. */
+    readonly?: boolean;
+    /** D1 only — injectable for tests. Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/** The one place `Tracer` and `SfDb` both go to get the right backend for `observability.db`'s resolved kind. */
+export declare function createTraceDb(resolved: NormalizedObservabilityDb, options?: CreateTraceDbOptions): TraceDb;

package/dist/core/trace_db.js

@@ -0,0 +1,278 @@
+/**
+ * TraceDb: the async storage interface the trace database (`Tracer`'s writes,
+ * `SfDb`'s reads) is built against — one interface, two backends.
+ *
+ * WHY ASYNC, WHEN `core/sqlite.ts`'s `Database` IS SYNCHRONOUS: Cloudflare
+ * D1's only way to reach a database from a plain Node process (this CLI —
+ * not a Cloudflare Worker, which would get a real binding) is its HTTP REST
+ * API — a network call, inescapably async. Rather than fake synchrony over
+ * that (shelling out to curl, a busy-wait/sync-XHR trick), every caller
+ * upstream of storage (`Tracer`'s write methods, `SfDb`'s read methods) is
+ * async too — see those modules' own headers for how far that propagates.
+ * `LocalTraceDb` below pays that cost for nothing (every call still runs
+ * synchronously, immediately; only the return value is wrapped as a settled
+ * `Promise`) so the local path stays byte-for-byte the same behavior it
+ * always had, just awaited.
+ *
+ * `query(sql)` mirrors `core/sqlite.ts`'s `Statement` shape exactly, only
+ * every method returns a `Promise` — so a caller migrating from `Database`
+ * changes `.get(...)` to `await .get(...)` and nothing else.
+ */
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+import { Database } from "./sqlite.js";
+/**
+ * Bound on one D1 HTTP request, same `AbortController` + unref'd `setTimeout`
+ * pattern `core/otel.ts`'s `flush()` uses for its own fetch calls — mirrored
+ * rather than reinvented (see `D1TraceDb.post` below). Set well above otel's
+ * own `SEND_TIMEOUT_MS` (2s): telemetry there is lossy and fire-and-forget,
+ * so a short timeout just means "drop this batch." A D1 query here is a
+ * REAL trace write/read a caller is awaiting — too short a timeout would
+ * turn ordinary network jitter into spurious failures — but it must still be
+ * BOUNDED, or a hung Cloudflare connection hangs the ADW run indefinitely.
+ */
+const D1_REQUEST_TIMEOUT_MS = 15_000;
+// ── local (sqlite, via core/sqlite.ts's synchronous Database) ──────────────
+/**
+ * A thin async wrapper over the existing synchronous `Database` — every call
+ * is dispatched immediately, synchronously, and its result (or thrown error)
+ * is handed back as an already-settled `Promise` (via an `async` wrapper, so
+ * a synchronous throw becomes a rejection rather than escaping the `Promise`
+ * contract). Zero behavior change from `Database` itself; only the signature
+ * is async, so this backend and `D1TraceDb` satisfy the exact same `TraceDb`
+ * interface.
+ *
+ * `core/sqlite.ts` is deliberately left untouched — `cli/commands/abort.ts`
+ * and `cli/commands/migrate.ts` still open a plain `Database` directly for
+ * local-file-specific operations (marking a session aborted, physically
+ * relocating the db file) that have no D1 equivalent. See those files' own
+ * D1 guards.
+ */
+export class LocalTraceDb {
+    db;
+    constructor(dbPath, options) {
+        if (!options?.readonly)
+            mkdirSync(path.dirname(dbPath), { recursive: true });
+        this.db = new Database(dbPath, options);
+    }
+    query(sql) {
+        const stmt = this.db.query(sql);
+        // `async` (not a bare `Promise.resolve(...)` wrapper) so a synchronous
+        // throw from the underlying `Database` call — a readonly-connection
+        // write, a constraint violation — becomes a REJECTED promise like every
+        // other `TraceDb` method, rather than an exception thrown synchronously
+        // out of a function whose declared return type is `Promise<...>`. A
+        // caller that does `const p = db.query(sql).run(); await p` (not
+        // `await db.query(sql).run()` inline) would otherwise never get the
+        // chance to catch it.
+        return {
+            get: async (...params) => stmt.get(...params),
+            all: async (...params) => stmt.all(...params),
+            run: async (...params) => stmt.run(...params),
+        };
+    }
+    async exec(sql) {
+        this.db.exec(sql);
+    }
+    async close() {
+        this.db.close();
+    }
+}
+// ── remote (Cloudflare D1, via its HTTP REST API) ──────────────────────────
+/**
+ * D1 IS NOT LOCAL WAL SQLITE — DO NOT ASSUME THE SAME LIVE-READ GUARANTEE.
+ *
+ * `core/tracer.ts`'s header describes the local backend's contract: WAL mode
+ * lets `spf ui` read the trace db WHILE an ADW process is still writing to
+ * it, in the same instant, because both sides share one file on one
+ * filesystem. A D1-backed repo has no such single file to share — `spf ui`
+ * and a running chain each speak to D1 over independent HTTP calls, and (per
+ * Cloudflare's own docs, https://developers.cloudflare.com/d1/best-practices/read-replication/)
+ * a D1 database with read replication enabled offers SEQUENTIAL consistency,
+ * not read-your-own-writes by default: a read immediately after a write can
+ * land on a replica that has not caught up yet. D1's Sessions API closes that
+ * gap with a "bookmark" a caller can pin subsequent reads to, but this
+ * adapter does not use it (a bookmark is a client-scoped promise across ONE
+ * lightweight connection; a Tracer that mints a fresh request per write and
+ * an SfDb serving unrelated browser requests have no session to share it
+ * through). This is a deliberate, documented trade-off (SPF #66) — not a bug
+ * to fix here: a D1-backed repo's UI may briefly show a slightly-stale trace
+ * while a chain is actively writing. Nothing about phase/gate/run OUTCOMES
+ * depends on that live read — see tracer.ts's header, "SQLite is the source
+ * of truth; nothing downstream of it can affect a phase, a gate, or a run
+ * outcome" holds exactly the same way against D1.
+ */
+export class D1TraceDb {
+    accountId;
+    apiToken;
+    databaseId;
+    fetchImpl;
+    baseUrl;
+    constructor(config, 
+    /** Injectable so tests never touch the real network — defaults to the global `fetch`. */
+    fetchImpl = fetch) {
+        this.databaseId = config.database_id;
+        this.accountId = readEnv(config.account_id_env, "D1 account id");
+        this.apiToken = readEnv(config.api_token_env, "D1 API token");
+        this.fetchImpl = fetchImpl;
+        this.baseUrl = `https://api.cloudflare.com/client/v4/accounts/${this.accountId}/d1/database/${this.databaseId}/query`;
+    }
+    query(sql) {
+        return {
+            get: async (...params) => {
+                const rows = await this.runOne(sql, params);
+                return rows.results[0] ?? null;
+            },
+            all: async (...params) => {
+                const rows = await this.runOne(sql, params);
+                return rows.results;
+            },
+            run: async (...params) => {
+                const rows = await this.runOne(sql, params);
+                return { changes: rows.meta.changes ?? 0, lastInsertRowid: rows.meta.last_row_id ?? 0 };
+            },
+        };
+    }
+    /**
+     * D1's HTTP `/query` endpoint accepts exactly one statement per `sql`
+     * field (see the Workers binding's `prepare()`/`batch()` split — the HTTP
+     * endpoint's single-request shape mirrors `prepare()`, not `exec()`);
+     * `exec()` here — schema DDL and additive `ALTER TABLE` migrations, always
+     * multiple statements — splits the text into individual statements and
+     * sends them as one `batch` request instead, which D1 documents as
+     * running sequentially and atomically. The split is naive (`;` at
+     * statement end, one statement per line-ish chunk) because this only ever
+     * runs against `tracer.ts`'s own hand-written `SCHEMA`/`MIGRATIONS`
+     * constants — never arbitrary or user-supplied SQL.
+     */
+    async exec(sql) {
+        const statements = splitStatements(sql);
+        if (statements.length === 0)
+            return;
+        const body = { batch: statements.map((s) => ({ sql: s })) };
+        await this.post(body);
+    }
+    close() {
+        // Stateless HTTP — no connection held open to release.
+        return Promise.resolve();
+    }
+    async runOne(sql, params) {
+        const body = { sql, params: params.length > 0 ? params : undefined };
+        const results = await this.post(body);
+        const first = results[0];
+        if (!first)
+            throw new Error(`D1 query returned no result set: ${sql}`);
+        return { results: (first.results ?? []), meta: first.meta ?? {} };
+    }
+    async post(body) {
+        // Same shape as `otel.ts`'s `flush()`: an `AbortController` whose timer
+        // is unref'd (never the reason this process lingers) and always cleared,
+        // win or lose. Unlike otel, a timeout here IS a thrown error — this
+        // request is a real trace read/write a caller is awaiting, not a
+        // best-effort fire-and-forget send.
+        //
+        // The timer is NOT cleared the moment `fetch` resolves with a `Response`
+        // — resolving only means headers have arrived; the body can still be
+        // in flight. `response.text()` is read inside this SAME try, under the
+        // SAME `controller.signal`, so a server that sends headers and then
+        // stalls the body still gets aborted at `D1_REQUEST_TIMEOUT_MS` (per the
+        // fetch spec, aborting a request's signal also aborts an in-progress
+        // body read) instead of hanging forever — exactly what this timeout
+        // exists to prevent.
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), D1_REQUEST_TIMEOUT_MS);
+        timer.unref?.();
+        let response;
+        let text;
+        try {
+            response = await this.fetchImpl(this.baseUrl, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${this.apiToken}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            text = await response.text();
+        }
+        catch (error) {
+            const timedOut = error.name === "AbortError";
+            throw new Error(timedOut
+                ? `D1 request timed out after ${D1_REQUEST_TIMEOUT_MS}ms`
+                : `D1 request failed: ${error.message ?? error}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        let parsed;
+        try {
+            parsed = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            // A non-JSON body (e.g. a Cloudflare edge error page) falls through to
+            // the HTTP-status branch below with the raw text as context.
+        }
+        if (!response.ok) {
+            const message = parsed?.errors?.map((e) => e.message).join("; ") || text.slice(0, 500) || response.statusText;
+            throw new Error(`D1 HTTP ${response.status}: ${message}`);
+        }
+        if (!parsed || parsed.success !== true) {
+            const message = parsed?.errors?.map((e) => e.message).join("; ") || "D1 reported failure with no error message";
+            throw new Error(`D1 query failed: ${message}`);
+        }
+        // A `success:true` envelope that omits `result` entirely (seen from some
+        // D1 edge responses) is still success — treat it as zero statements
+        // rather than throwing `TypeError: parsed.result is not iterable`.
+        const result = parsed.result ?? [];
+        for (const item of result) {
+            if (item.success === false) {
+                throw new Error(`D1 statement failed: ${parsed.errors?.map((e) => e.message).join("; ") || "unknown error"}`);
+            }
+        }
+        return result;
+    }
+}
+/**
+ * Split a `;`-terminated multi-statement string into individual statements,
+ * dropping blanks and comment-only lines.
+ *
+ * `tracer.ts`'s `SCHEMA` carries `--`-style trailing comments on several
+ * column definitions (e.g. `archived INTEGER DEFAULT 0 -- ...; never by a
+ * run`), and those comments themselves contain `;` — a naive `sql.split(";")`
+ * shreds the enclosing `CREATE TABLE` into fragments right in the middle of
+ * a comment, producing statements no SQL engine accepts (an unterminated
+ * `CREATE TABLE ... (`, an orphaned comment tail). This strips every `--` to
+ * end-of-line FIRST, so a `;` inside a comment can no longer be mistaken for
+ * a statement terminator, then splits what's left. Still only sound for
+ * `tracer.ts`'s own hand-written SCHEMA/MIGRATIONS constants — not general
+ * SQL (a `;` or `--` inside a quoted string literal is not accounted for,
+ * and neither constant ever uses one).
+ */
+function splitStatements(sql) {
+    const withoutLineComments = sql
+        .split("\n")
+        .map((line) => {
+        const commentAt = line.indexOf("--");
+        return commentAt === -1 ? line : line.slice(0, commentAt);
+    })
+        .join("\n");
+    return withoutLineComments
+        .split(";")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+function readEnv(name, what) {
+    const value = (process.env[name] ?? "").trim();
+    if (!value) {
+        throw new Error(`${what} is not set — the observability.db config names env var ${JSON.stringify(name)}, but it is empty or unset`);
+    }
+    return value;
+}
+/** The one place `Tracer` and `SfDb` both go to get the right backend for `observability.db`'s resolved kind. */
+export function createTraceDb(resolved, options) {
+    if (resolved.kind === "sqlite") {
+        return new LocalTraceDb(resolved.path, options?.readonly ? { readonly: true } : undefined);
+    }
+    return new D1TraceDb(resolved, options?.fetchImpl);
+}