@gr8ful/spf 0.15.0 → 0.16.0

package/dist/core/runner.d.ts

@@ -20,13 +20,19 @@ interface AgentMapEntry {
     coding_agent: string;
 }
 export interface PhaseHandle {
-    log(payload: Record<string, unknown>): void;
+    log(payload: Record<string, unknown>): Promise<void>;
     call<T extends EnvelopeBase>(call: AgentCall<T>): Promise<T>;
 }
 export interface RunInit {
     cfg: SFConfig;
     adwId: string;
     tracer: Tracer;
+    /**
+     * `tracer.maxPhaseSeq(adwId)`, resolved by the caller BEFORE constructing
+     * `Run` — a real trace-db read now (a network call for a D1-backed repo),
+     * and `Run`'s own constructor cannot be async. See `session.ts`'s `ensure()`.
+     */
+    startSeq: number;
     engineer: string;
     /** Absolute. Resolved once, upstream, by paths.resolveAnchor(). */
     repoRoot: string;
@@ -75,7 +81,7 @@ export declare class Run {
     private agentMapPath;
     constructor(init: RunInit);
     saveAgentMap(agent: string, entry: AgentMapEntry): void;
-    addUsage(tokens: number, cost: number): void;
+    addUsage(tokens: number, cost: number): Promise<void>;
     phase<T>(params: PhaseParams, fn: (ph: PhaseHandle) => Promise<T>): Promise<T>;
     /**
      * Finalize the run and return its exit code. Call this exactly once.
@@ -86,6 +92,6 @@ export declare class Run {
      * so the exit code, the session status, and the banner are decided
      * together and cannot disagree.
      */
-    finish(accepted?: boolean, reason?: string): number;
+    finish(accepted?: boolean, reason?: string): Promise<number>;
 }
 export {};

package/dist/core/runner.js

@@ -14,8 +14,20 @@ import * as agents from "./agents.js";
 import { makeGit } from "./git_helper.js";
 import { Console } from "./console.js";
 import { Tracer } from "./tracer.js";
-import { makeEventRecord } from "./data_types.js";
+import { makeEventRecord, resolveObservabilityDb } from "./data_types.js";
 import { ensureDir, nowIso } from "./utils.js";
+/**
+ * `Console.sessionFinished`'s trailing `db` row wants a short, human-facing
+ * label, not a filesystem path specifically — `cfg.observability.db` is now
+ * a discriminated shape (see `data_types.ts`'s migration note), so this
+ * normalizes it to whichever of "the sqlite path" or "the D1 database id"
+ * is actually meaningful to show, rather than assuming it's always a path
+ * string the way this call site did before that field existed.
+ */
+function describeObservabilityDb(db) {
+    const resolved = resolveObservabilityDb(db);
+    return resolved.kind === "sqlite" ? resolved.path : `d1:${resolved.database_id}`;
+}
 class PhaseHandleImpl {
     run;
     phase;
@@ -23,17 +35,17 @@ class PhaseHandleImpl {
         this.run = run;
         this.phase = phase;
     }
-    log(payload) {
-        this.run.tracer.event(makeEventRecord({
+    async log(payload) {
+        await this.run.tracer.event(makeEventRecord({
             adw_id: this.run.adw_id,
             phase_id: this.phase.phase_id,
             type: "log",
             name: this.phase.params.name,
             payload,
         }));
-        this.run.console.note(Object.entries(payload).map(([k, v]) => `${k}: ${v}`).join(", "));
+        await this.run.console.note(Object.entries(payload).map(([k, v]) => `${k}: ${v}`).join(", "));
         if (this.phase.params.kind === "engineer" && "input" in payload) {
-            this.run.tracer.sessionRequest(this.run.adw_id, String(payload.input));
+            await this.run.tracer.sessionRequest(this.run.adw_id, String(payload.input));
         }
     }
     async call(call) {
@@ -80,7 +92,7 @@ export class Run {
         this.notify = init.notifier ?? null;
         this.console = new Console(init.tracer, init.adwId, this.notify, init.chainName || "adw", init.sink, init.observer);
         this.engineer = init.engineer;
-        this.seq = init.tracer.maxPhaseSeq(init.adwId);
+        this.seq = init.startSeq;
         this.repo_root = init.repoRoot;
         this.spf_dir = init.sfDir;
         this.git = makeGit(init.repoRoot);
@@ -95,12 +107,12 @@ export class Run {
         this.agent_map[agent] = entry;
         writeFileSync(this.agentMapPath, JSON.stringify(this.agent_map, null, 2));
     }
-    // ── usage (run totals mirror what the tracer accumulates in sqlite) ─────
-    addUsage(tokens, cost) {
+    // ── usage (run totals mirror what the tracer accumulates in the trace db) ─
+    async addUsage(tokens, cost) {
         this.tokens += tokens;
         this.cost += cost;
-        this.tracer.sessionAddUsage(this.adw_id, tokens, cost);
-        this.console.notifyUsage(this.tokens, this.cost);
+        await this.tracer.sessionAddUsage(this.adw_id, tokens, cost);
+        await this.console.notifyUsage(this.tokens, this.cost);
     }
     // ── the phase primitive ─────────────────────────────────────────────────
     async phase(params, fn) {
@@ -117,35 +129,35 @@ export class Run {
             ended_at: null,
         };
         this.phases.push(phase);
-        this.tracer.phaseUpsert(phase);
-        this.tracer.event(makeEventRecord({
+        await this.tracer.phaseUpsert(phase);
+        await this.tracer.event(makeEventRecord({
             adw_id: this.adw_id,
             phase_id: phase.phase_id,
             type: "phase_start",
             name: params.name,
             payload: { kind: params.kind, owner: params.owner, description: params.description },
         }));
-        this.console.phaseStarted(phase);
+        await this.console.phaseStarted(phase);
         const clock = performance.now();
         try {
             const result = await fn(new PhaseHandleImpl(this, phase));
             phase.status = "success";
             phase.ended_at = nowIso();
-            this.tracer.event(makeEventRecord({ adw_id: this.adw_id, phase_id: phase.phase_id, type: "phase_end", name: params.name, payload: { status: "success" } }));
-            this.tracer.phaseUpsert(phase);
-            this.console.phaseEnded(phase, (performance.now() - clock) / 1000);
+            await this.tracer.event(makeEventRecord({ adw_id: this.adw_id, phase_id: phase.phase_id, type: "phase_end", name: params.name, payload: { status: "success" } }));
+            await this.tracer.phaseUpsert(phase);
+            await this.console.phaseEnded(phase, (performance.now() - clock) / 1000);
             return result;
         }
         catch (error) {
             phase.status = "fail"; // success must be earned
             phase.error = String(error?.message ?? error).slice(0, 1000);
             phase.ended_at = nowIso();
-            this.tracer.event(makeEventRecord({ adw_id: this.adw_id, phase_id: phase.phase_id, type: "error", name: params.name, payload: { error: phase.error } }));
-            this.tracer.event(makeEventRecord({ adw_id: this.adw_id, phase_id: phase.phase_id, type: "phase_end", name: params.name, payload: { status: "fail" } }));
-            this.tracer.phaseUpsert(phase);
-            this.tracer.sessionFinish(this.adw_id, false);
-            this.console.phaseEnded(phase, (performance.now() - clock) / 1000);
-            this.console.sessionFinished(false, this.tokens, this.cost, this.cfg.observability.db);
+            await this.tracer.event(makeEventRecord({ adw_id: this.adw_id, phase_id: phase.phase_id, type: "error", name: params.name, payload: { error: phase.error } }));
+            await this.tracer.event(makeEventRecord({ adw_id: this.adw_id, phase_id: phase.phase_id, type: "phase_end", name: params.name, payload: { status: "fail" } }));
+            await this.tracer.phaseUpsert(phase);
+            await this.tracer.sessionFinish(this.adw_id, false);
+            await this.console.phaseEnded(phase, (performance.now() - clock) / 1000);
+            await this.console.sessionFinished(false, this.tokens, this.cost, describeObservabilityDb(this.cfg.observability.db));
             throw error;
         }
     }
@@ -158,22 +170,22 @@ export class Run {
      * so the exit code, the session status, and the banner are decided
      * together and cannot disagree.
      */
-    finish(accepted = true, reason = "") {
+    async finish(accepted = true, reason = "") {
         const phasesOk = this.phases.length > 0 && this.phases.every((p) => p.status === "success");
         const ok = phasesOk && accepted;
         if (phasesOk && !accepted) {
             const note = reason || "the run's acceptance criterion was not met";
-            this.tracer.event(makeEventRecord({
+            await this.tracer.event(makeEventRecord({
                 adw_id: this.adw_id,
                 phase_id: this.phases.length > 0 ? this.phases[this.phases.length - 1].phase_id : "",
                 type: "error",
                 name: "not_accepted",
                 payload: { reason: note },
             }));
-            this.console.note(`not accepted: ${note}`);
+            await this.console.note(`not accepted: ${note}`);
         }
-        this.tracer.sessionFinish(this.adw_id, ok);
-        this.console.sessionFinished(ok, this.tokens, this.cost, this.cfg.observability.db);
+        await this.tracer.sessionFinish(this.adw_id, ok);
+        await this.console.sessionFinished(ok, this.tokens, this.cost, describeObservabilityDb(this.cfg.observability.db));
         return ok ? 0 : 1;
     }
 }

package/dist/core/session.d.ts

@@ -30,7 +30,7 @@ import type { SFConfig } from "./data_types.ts";
  * `releaseOtelExporter`, and harmless for the same reason: that process
  * exits right after anyway.
  */
-export declare function finalize(adwId: string | null | undefined): void;
+export declare function finalize(adwId: string | null | undefined): Promise<void>;
 /** Tests only: which adw_ids the process-wide signal handler currently considers active. */
 export declare function activeRunIdsForTest(): string[];
 /**
@@ -49,4 +49,4 @@ export declare function ensure(cfg: SFConfig, adwId?: string | null, cwd?: strin
 renderHooks?: {
     sink?: (line: string) => void;
     observer?: RunObserver | null;
-}): Run;
+}): Promise<Run>;

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;