@gr8ful/spf 0.15.0 → 0.16.0

package/dist/core/data_types.d.ts

@@ -671,7 +671,7 @@ export interface SandboxSpec {
 }
 export declare const AgentConfigSchema: v.ObjectSchema<{
     readonly name: v.StringSchema<undefined>;
-    readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
+    readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code", "opencode"], undefined>, "flue">;
     readonly model: v.OptionalSchema<v.StringSchema<undefined>, "google/gemini-3.6-flash">;
     readonly thinking: v.OptionalSchema<v.PicklistSchema<["off", "minimal", "low", "medium", "high", "xhigh", "max"], undefined>, "medium">;
     readonly color: v.OptionalSchema<v.StringSchema<undefined>, "">;
@@ -688,7 +688,7 @@ export declare const AgentConfigSchema: v.ObjectSchema<{
 }, undefined>;
 export type AgentConfig = v.InferOutput<typeof AgentConfigSchema>;
 export declare const ConfigDefaultsSchema: v.ObjectSchema<{
-    readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
+    readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code", "opencode"], undefined>, "flue">;
     readonly model: v.OptionalSchema<v.StringSchema<undefined>, "google/gemini-3.6-flash">;
     readonly thinking: v.OptionalSchema<v.PicklistSchema<["off", "minimal", "low", "medium", "high", "xhigh", "max"], undefined>, "medium">;
     readonly color: v.OptionalSchema<v.StringSchema<undefined>, "">;
@@ -763,8 +763,106 @@ export declare const OTelConfigSchema: v.ObjectSchema<{
     readonly service_name: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
 }, undefined>;
 export type OTelConfig = v.InferOutput<typeof OTelConfigSchema>;
+/**
+ * MIGRATION NOTE (BT-issue #66, 3 PRs): `observability.db` used to be ONLY a
+ * bare string (a local sqlite path, defaulting to ".spf/data/spf.db"). This
+ * is now a discriminated shape that additionally accepts an explicit
+ * `{ kind: "sqlite", path? }` object (equivalent to the string form, just
+ * spelled out) and a `{ kind: "d1", database_id, ... }` object that names a
+ * remote Cloudflare D1 database instead of a local file. The bare-string
+ * form is unchanged and remains the default for every existing config —
+ * nothing in the wild needs to change. `resolveObservabilityDb` below
+ * normalizes all three accepted forms to one shape.
+ *
+ * PR 1 (this schema + normalizer + `paths.resolveDataPaths` plumbing) left
+ * `resolveDataPaths` refusing a `kind: "d1"` config outright — no adapter
+ * existed yet. PR 2 (`core/trace_db.ts`'s `TraceDb` interface, `LocalTraceDb`,
+ * `D1TraceDb`, and `createTraceDb()`, wired through `Tracer`/`SfDb`) removes
+ * that refusal: `resolveDataPaths` now returns a usable descriptor for
+ * either kind, and both backends are real. PR 3 wires `spf doctor`/`spf
+ * init`'s interview flow to the new option.
+ */
+export declare const SqliteDbConfigSchema: v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"sqlite", undefined>;
+    readonly path: v.OptionalSchema<v.StringSchema<undefined>, ".spf/data/spf.db">;
+}, undefined>;
+export type SqliteDbConfig = v.InferOutput<typeof SqliteDbConfigSchema>;
+/**
+ * `account_id_env`/`api_token_env` default to the SAME env var names
+ * `core/cloudflare_provider.ts` already reads for the Cloudflare Workers AI
+ * provider (`CLOUDFLARE_ACCOUNT_ID`/`CLOUDFLARE_API_TOKEN`, see
+ * `core/providers.ts`'s `PROVIDER_ENV_KEYS.cloudflare`) — one Cloudflare
+ * account's credentials, read from the same two env vars, cover both
+ * Workers AI and a D1-backed trace db unless a config explicitly points
+ * elsewhere (e.g. a second Cloudflare account) by naming different env vars.
+ */
+export declare const D1DbConfigSchema: v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"d1", undefined>;
+    readonly database_id: v.StringSchema<undefined>;
+    readonly account_id_env: v.OptionalSchema<v.StringSchema<undefined>, "CLOUDFLARE_ACCOUNT_ID">;
+    readonly api_token_env: v.OptionalSchema<v.StringSchema<undefined>, "CLOUDFLARE_API_TOKEN">;
+}, undefined>;
+export type D1DbConfig = v.InferOutput<typeof D1DbConfigSchema>;
+export declare const ObservabilityDbSchema: v.SchemaWithPipe<readonly [v.UnknownSchema, v.RawTransformAction<unknown, string | {
+    kind: "sqlite";
+    path: string;
+} | {
+    kind: "d1";
+    database_id: string;
+    account_id_env: string;
+    api_token_env: string;
+}>]>;
+export type ObservabilityDbConfig = v.InferOutput<typeof ObservabilityDbSchema>;
+/**
+ * What `resolveObservabilityDb` ACCEPTS — deliberately more permissive than
+ * `ObservabilityDbConfig` (that type is the schema's OUTPUT, post-default,
+ * so every optional field reads as required). This is the pre-default INPUT
+ * shape — `path`/`account_id_env`/`api_token_env` all optional, exactly
+ * what a hand-written `{kind:"sqlite"}` or `{kind:"d1", database_id:"..."}`
+ * literal looks like before `v.parse` fills its defaults in. An already-
+ * parsed `ObservabilityDbConfig` (every optional field present) satisfies
+ * this too, so the one normalizer works on config fresh off `v.parse` AND
+ * on a literal built by hand (e.g. in a test, or by a future caller that
+ * hasn't gone through the schema).
+ */
+export type ObservabilityDbInput = string | {
+    kind: "sqlite";
+    path?: string;
+} | {
+    kind: "d1";
+    database_id: string;
+    account_id_env?: string;
+    api_token_env?: string;
+};
+/** What `resolveObservabilityDb` normalizes any of the three accepted `db:` forms to. PR 2's D1 adapter is built against this shape. */
+export type NormalizedObservabilityDb = {
+    kind: "sqlite";
+    path: string;
+} | {
+    kind: "d1";
+    database_id: string;
+    account_id_env: string;
+    api_token_env: string;
+};
+/**
+ * Normalizes `observability.db` — bare string, `{kind:"sqlite",...}`, or
+ * `{kind:"d1",...}` — to one shape. Pure and side-effect-free: does NOT
+ * resolve `path` to an absolute path (that's `paths.resolveDataPaths`'s job,
+ * which needs `repo_root` to do it) and does NOT read the D1 env vars it
+ * names (that's PR 2's adapter's job, at the point it actually needs to
+ * authenticate).
+ */
+export declare function resolveObservabilityDb(db: ObservabilityDbInput): NormalizedObservabilityDb;
 export declare const ObservabilityConfigSchema: v.ObjectSchema<{
-    readonly db: v.OptionalSchema<v.StringSchema<undefined>, ".spf/data/spf.db">;
+    readonly db: v.OptionalSchema<v.SchemaWithPipe<readonly [v.UnknownSchema, v.RawTransformAction<unknown, string | {
+        kind: "sqlite";
+        path: string;
+    } | {
+        kind: "d1";
+        database_id: string;
+        account_id_env: string;
+        api_token_env: string;
+    }>]>, ".spf/data/spf.db">;
     readonly poll_ms: v.OptionalSchema<v.NumberSchema<undefined>, 500>;
     readonly otel: v.OptionalSchema<v.ObjectSchema<{
         readonly endpoint: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>;
@@ -1304,7 +1402,7 @@ export type ReviewConfig = v.InferOutput<typeof ReviewConfigSchema>;
  */
 export declare const TierSchema: v.ObjectSchema<{
     readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
-    readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
+    readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code", "opencode"], undefined>, "flue">;
     readonly model: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
 }, undefined>;
 export type Tier = v.InferOutput<typeof TierSchema>;
@@ -1339,7 +1437,7 @@ export declare const TieringConfigSchema: v.ObjectSchema<{
     readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
     readonly tiers: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
         readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
-        readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
+        readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code", "opencode"], undefined>, "flue">;
         readonly model: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
     }, undefined>, undefined>, () => never[]>;
     readonly roles: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, () => {}>;
@@ -1348,7 +1446,7 @@ export type TieringConfig = v.InferOutput<typeof TieringConfigSchema>;
 export declare const SFConfigSchema: v.ObjectSchema<{
     readonly env: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, () => {}>;
     readonly defaults: v.OptionalSchema<v.ObjectSchema<{
-        readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
+        readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code", "opencode"], undefined>, "flue">;
         readonly model: v.OptionalSchema<v.StringSchema<undefined>, "google/gemini-3.6-flash">;
         readonly thinking: v.OptionalSchema<v.PicklistSchema<["off", "minimal", "low", "medium", "high", "xhigh", "max"], undefined>, "medium">;
         readonly color: v.OptionalSchema<v.StringSchema<undefined>, "">;
@@ -1401,7 +1499,7 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         readonly max_run_cost: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.GtValueAction<number, 0, undefined>]>, undefined>;
         readonly max_run_tokens: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.GtValueAction<number, 0, undefined>]>, undefined>;
     }, undefined>, () => {
-        coding_agent: "claude_code" | "flue";
+        coding_agent: "claude_code" | "flue" | "opencode";
         model: string;
         thinking: "high" | "low" | "max" | "medium" | "minimal" | "off" | "xhigh";
         color: string;
@@ -1413,7 +1511,15 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         max_run_tokens?: number | undefined;
     }>;
     readonly observability: v.OptionalSchema<v.ObjectSchema<{
-        readonly db: v.OptionalSchema<v.StringSchema<undefined>, ".spf/data/spf.db">;
+        readonly db: v.OptionalSchema<v.SchemaWithPipe<readonly [v.UnknownSchema, v.RawTransformAction<unknown, string | {
+            kind: "sqlite";
+            path: string;
+        } | {
+            kind: "d1";
+            database_id: string;
+            account_id_env: string;
+            api_token_env: string;
+        }>]>, ".spf/data/spf.db">;
         readonly poll_ms: v.OptionalSchema<v.NumberSchema<undefined>, 500>;
         readonly otel: v.OptionalSchema<v.ObjectSchema<{
             readonly endpoint: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>;
@@ -1421,7 +1527,15 @@ export declare const SFConfigSchema: v.ObjectSchema<{
             readonly service_name: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
         }, undefined>, undefined>;
     }, undefined>, () => {
-        db: string;
+        db: string | {
+            kind: "sqlite";
+            path: string;
+        } | {
+            kind: "d1";
+            database_id: string;
+            account_id_env: string;
+            api_token_env: string;
+        };
         poll_ms: number;
         otel?: {
             endpoint: string;
@@ -1433,7 +1547,7 @@ export declare const SFConfigSchema: v.ObjectSchema<{
     }>;
     readonly agents: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
         readonly name: v.StringSchema<undefined>;
-        readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
+        readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code", "opencode"], undefined>, "flue">;
         readonly model: v.OptionalSchema<v.StringSchema<undefined>, "google/gemini-3.6-flash">;
         readonly thinking: v.OptionalSchema<v.PicklistSchema<["off", "minimal", "low", "medium", "high", "xhigh", "max"], undefined>, "medium">;
         readonly color: v.OptionalSchema<v.StringSchema<undefined>, "">;
@@ -1694,7 +1808,7 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
         readonly tiers: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
             readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
-            readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
+            readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code", "opencode"], undefined>, "flue">;
             readonly model: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
         }, undefined>, undefined>, () => never[]>;
         readonly roles: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, () => {}>;
@@ -1702,7 +1816,7 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         enabled: boolean;
         tiers: {
             name: string;
-            coding_agent: "claude_code" | "flue";
+            coding_agent: "claude_code" | "flue" | "opencode";
             model: string;
         }[];
         roles: {

package/dist/core/data_types.js

@@ -475,7 +475,7 @@ export const SandboxConfigSchema = v.object({
 });
 export const AgentConfigSchema = v.object({
     name: v.string(),
-    coding_agent: v.optional(v.picklist(["flue", "claude_code"]), "flue"),
+    coding_agent: v.optional(v.picklist(["flue", "claude_code", "opencode"]), "flue"),
     model: v.optional(v.string(), "google/gemini-3.6-flash"),
     thinking: v.optional(ThinkingLevelSchema, "medium"),
     color: v.optional(v.string(), ""), // hex swatch for this agent's lane in the UI
@@ -510,7 +510,7 @@ export const AgentConfigSchema = v.object({
     sandbox: v.optional(v.nullable(SandboxBackendSchema)),
 });
 export const ConfigDefaultsSchema = v.object({
-    coding_agent: v.optional(v.picklist(["flue", "claude_code"]), "flue"),
+    coding_agent: v.optional(v.picklist(["flue", "claude_code", "opencode"]), "flue"),
     model: v.optional(v.string(), "google/gemini-3.6-flash"),
     thinking: v.optional(ThinkingLevelSchema, "medium"),
     color: v.optional(v.string(), ""),
@@ -587,8 +587,97 @@ export const OTelConfigSchema = v.object({
     headers: v.optional(v.record(v.string(), v.string()), undefined),
     service_name: v.optional(v.string(), "spf"),
 });
+/**
+ * MIGRATION NOTE (BT-issue #66, 3 PRs): `observability.db` used to be ONLY a
+ * bare string (a local sqlite path, defaulting to ".spf/data/spf.db"). This
+ * is now a discriminated shape that additionally accepts an explicit
+ * `{ kind: "sqlite", path? }` object (equivalent to the string form, just
+ * spelled out) and a `{ kind: "d1", database_id, ... }` object that names a
+ * remote Cloudflare D1 database instead of a local file. The bare-string
+ * form is unchanged and remains the default for every existing config —
+ * nothing in the wild needs to change. `resolveObservabilityDb` below
+ * normalizes all three accepted forms to one shape.
+ *
+ * PR 1 (this schema + normalizer + `paths.resolveDataPaths` plumbing) left
+ * `resolveDataPaths` refusing a `kind: "d1"` config outright — no adapter
+ * existed yet. PR 2 (`core/trace_db.ts`'s `TraceDb` interface, `LocalTraceDb`,
+ * `D1TraceDb`, and `createTraceDb()`, wired through `Tracer`/`SfDb`) removes
+ * that refusal: `resolveDataPaths` now returns a usable descriptor for
+ * either kind, and both backends are real. PR 3 wires `spf doctor`/`spf
+ * init`'s interview flow to the new option.
+ */
+export const SqliteDbConfigSchema = v.object({
+    kind: v.literal("sqlite"),
+    path: v.optional(v.string(), ".spf/data/spf.db"),
+});
+/**
+ * `account_id_env`/`api_token_env` default to the SAME env var names
+ * `core/cloudflare_provider.ts` already reads for the Cloudflare Workers AI
+ * provider (`CLOUDFLARE_ACCOUNT_ID`/`CLOUDFLARE_API_TOKEN`, see
+ * `core/providers.ts`'s `PROVIDER_ENV_KEYS.cloudflare`) — one Cloudflare
+ * account's credentials, read from the same two env vars, cover both
+ * Workers AI and a D1-backed trace db unless a config explicitly points
+ * elsewhere (e.g. a second Cloudflare account) by naming different env vars.
+ */
+export const D1DbConfigSchema = v.object({
+    kind: v.literal("d1"),
+    database_id: v.string(),
+    account_id_env: v.optional(v.string(), "CLOUDFLARE_ACCOUNT_ID"),
+    api_token_env: v.optional(v.string(), "CLOUDFLARE_API_TOKEN"),
+});
+/**
+ * A plain `v.union([v.string(), v.variant("kind", [...])])` was tried first
+ * and rejected: valibot's plain union reports every failed branch with the
+ * same generic "Expected (string | Object) but received Object", swallowing
+ * `v.variant`'s own precise "kind must be sqlite or d1" / "database_id is
+ * required" messages. This `rawTransform` dispatches on `typeof value`
+ * itself — string passes through unchanged (the back-compat form), anything
+ * else is handed to `v.variant("kind", ...)` and ITS issues (which already
+ * name the offending field) are re-surfaced verbatim, prefixed with
+ * `observability.db:` so a nested failure is still easy to place in a large
+ * config file. See `src/test/data_types.test.ts` for the exact messages
+ * this produces for each rejected shape.
+ */
+const ObservabilityDbVariantSchema = v.variant("kind", [SqliteDbConfigSchema, D1DbConfigSchema]);
+export const ObservabilityDbSchema = v.pipe(v.unknown(), v.rawTransform(({ dataset, addIssue, NEVER }) => {
+    const value = dataset.value;
+    if (typeof value === "string")
+        return value;
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        const result = v.safeParse(ObservabilityDbVariantSchema, value);
+        if (result.success)
+            return result.output;
+        for (const issue of result.issues)
+            addIssue({ message: `observability.db: ${issue.message}` });
+        return NEVER;
+    }
+    addIssue({
+        message: `observability.db must be a string path, or an object with kind: "sqlite" or kind: "d1" (got ${JSON.stringify(value)})`,
+    });
+    return NEVER;
+}));
+/**
+ * Normalizes `observability.db` — bare string, `{kind:"sqlite",...}`, or
+ * `{kind:"d1",...}` — to one shape. Pure and side-effect-free: does NOT
+ * resolve `path` to an absolute path (that's `paths.resolveDataPaths`'s job,
+ * which needs `repo_root` to do it) and does NOT read the D1 env vars it
+ * names (that's PR 2's adapter's job, at the point it actually needs to
+ * authenticate).
+ */
+export function resolveObservabilityDb(db) {
+    if (typeof db === "string")
+        return { kind: "sqlite", path: db };
+    if (db.kind === "sqlite")
+        return { kind: "sqlite", path: db.path ?? ".spf/data/spf.db" };
+    return {
+        kind: "d1",
+        database_id: db.database_id,
+        account_id_env: db.account_id_env ?? "CLOUDFLARE_ACCOUNT_ID",
+        api_token_env: db.api_token_env ?? "CLOUDFLARE_API_TOKEN",
+    };
+}
 export const ObservabilityConfigSchema = v.object({
-    db: v.optional(v.string(), ".spf/data/spf.db"),
+    db: v.optional(ObservabilityDbSchema, ".spf/data/spf.db"),
     poll_ms: v.optional(v.number(), 500),
     // Absent by default. `agents.ts`'s mergeRawConfig spreads `observability`
     // field-by-field, so this nested object merges as a WHOLE-OBJECT replace on
@@ -596,6 +685,14 @@ export const ObservabilityConfigSchema = v.object({
     // which is the semantics you want for an endpoint + its headers (a
     // half-merged pair of the two would send tokens to the wrong collector).
     // Pinned by a merge-survival test in src/test/data_types.test.ts.
+    //
+    // `db` merges the same whole-value way: `mergeRawConfig`'s `observability`
+    // spread is key-by-key over `observability`'s OWN keys (db/poll_ms/otel),
+    // never deeper — an override's `db:` (string or object, either kind)
+    // replaces the base's `db:` in full, so a `{kind:"d1",...}` override can
+    // never end up with a stray `path` key leaked in from a `{kind:"sqlite",
+    // path:...}` base (or vice versa). See the merge-survival test for `db` in
+    // src/test/data_types.test.ts.
     otel: v.optional(OTelConfigSchema),
 });
 /**
@@ -962,7 +1059,7 @@ export const ReviewConfigSchema = v.object({
  */
 export const TierSchema = v.object({
     name: v.pipe(v.string(), v.minLength(1)),
-    coding_agent: v.optional(v.picklist(["flue", "claude_code"]), "flue"),
+    coding_agent: v.optional(v.picklist(["flue", "claude_code", "opencode"]), "flue"),
     model: v.pipe(v.string(), v.minLength(1)),
 });
 /**

package/dist/core/fanout.d.ts

@@ -204,7 +204,7 @@ export interface FanoutDeps {
     /** Run one attempt's chain in `cwd`, returning its exit code. */
     runAttempt: (dispatch: AttemptDispatch) => Promise<number>;
     /** Read this adw_id's gate/usage rows from the SHARED db. Must not throw — return `ZERO_METRICS` on any hiccup. */
-    readMetrics: (adwId: string) => AttemptMetrics;
+    readMetrics: (adwId: string) => Promise<AttemptMetrics>;
     log: (message: string) => void;
     /**
      * Opt-in first-past-the-post. Default (unset/false): every attempt that

package/dist/core/fanout.js

@@ -239,7 +239,7 @@ export async function runBestOf(deps) {
             decided = true;
         let metrics = ZERO_METRICS;
         try {
-            metrics = deps.readMetrics(adwId);
+            metrics = await deps.readMetrics(adwId);
         }
         catch (caught) {
             // Metrics are for RANKING, never for correctness — an attempt whose

package/dist/core/gates.js

@@ -96,7 +96,20 @@ export function diffMatchesClaims(envelope, run) {
             continue;
         }
         const exists = existsSync(resolved);
-        report.check(f, exists, exists ? `exists, ${size(resolved)}` : "claimed changed file does not exist");
+        // A bulk/mechanical change (a repo-wide formatter, a codemod) tempts an
+        // agent to compress many identical edits into one descriptive sentence
+        // ("139 files reformatted (app/, components/, ...)") instead of listing
+        // each path — that string obviously never resolves, but the plain
+        // "does not exist" message gives no hint why, so a retry repeats the
+        // same mistake. Whitespace inside an otherwise-nonexistent claim is the
+        // cheap, cheap-to-check signal: a real repo-relative path is never a
+        // prose fragment. Never suppresses the failure itself, only clarifies it.
+        const looksLikeProse = !exists && /\s/.test(f);
+        report.check(f, exists, exists
+            ? `exists, ${size(resolved)}`
+            : looksLikeProse
+                ? "claimed changed file does not exist — this looks like a summary sentence, not a path; list every changed file individually, even for a bulk/mechanical change"
+                : "claimed changed file does not exist");
     }
     return report;
 }

package/dist/core/paths.d.ts

@@ -16,6 +16,7 @@
  * levels below the package root, so the same relative path resolves either
  * way), with `assets/` a direct child of it.
  */
+import { type NormalizedObservabilityDb, type ObservabilityDbInput } from "./data_types.ts";
 export declare const PACKAGE_ROOT: string;
 export declare const ASSETS_DIR: string;
 /** The prebuilt SPA — a sibling of dist/ and assets/, built once at publish time (see app/). */
@@ -54,9 +55,22 @@ export interface DataPaths {
     data_dir: string;
     /** Repo-root-relative, forward-slash — for matching against git's own path output. */
     data_dir_rel: string;
-    /** Absolute. */
-    db_path: string;
-    /** Absolute. ALWAYS a sibling of `db_path` — relocating `data_dir` must never break this. */
+    /**
+     * The normalized `observability.db` descriptor — `core/trace_db.ts`'s
+     * `createTraceDb()` (called by both `Tracer` and `SfDb`) is built against
+     * exactly this shape. For `kind: "sqlite"`, `path` here is already
+     * resolved ABSOLUTE (byte-for-byte the same value as `db_path` below); for
+     * `kind: "d1"` there is no local path at all.
+     */
+    db: NormalizedObservabilityDb;
+    /** Absolute local sqlite path, or `null` for a `kind: "d1"` config — there is no local file to open. */
+    db_path: string | null;
+    /**
+     * Absolute. Anchored directly off `data_dir` (NOT off `db_path`) — session
+     * JSONL/envelope artifact files always live on the local filesystem
+     * regardless of where the queryable trace mirror (`db` above) lives, so
+     * this must resolve even when `db_path` is `null` for a d1-backed repo.
+     */
     sessions_dir: string;
 }
 /**
@@ -70,8 +84,31 @@ export interface DataPaths {
  *
  * Not otherwise side-effect-free: see `healBrokenDataDir` above, which every
  * caller needs run before its own first `mkdirSync` against `data_dir`.
+ *
+ * `rawDb` accepts every form `ObservabilityConfigSchema.db` accepts (bare
+ * string, `{kind:"sqlite",...}`, `{kind:"d1",...}`) — normalized here via
+ * `resolveObservabilityDb` — so every existing call site
+ * (`resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db)`)
+ * keeps compiling and behaving unchanged with no call-site edit needed.
+ *
+ * For a `"sqlite"`-kind db, `db_path`/`db.path` resolve BYTE-FOR-BYTE
+ * identically to before this PR: `path.resolve(repo_root, path)`.
+ *
+ * For a `"d1"`-kind db there is no local file at all — `db_path` is `null`,
+ * and `db` carries the resolved `{kind:"d1", database_id, account_id_env,
+ * api_token_env}` for `core/trace_db.ts`'s `createTraceDb()` to open (PR 2:
+ * SPF #66). `sessions_dir` has no `db_path` to anchor off in this case, so it
+ * falls back to `data_dir/sessions` — session JSONL/envelope artifacts still
+ * always live on disk regardless of where the queryable trace mirror lives.
+ *
+ * For a `"sqlite"`-kind db, `sessions_dir` stays what it always was — ALWAYS
+ * a sibling of `db_path` (`dirname(db_path)/sessions`), never `data_dir`
+ * directly — `migrate.ts` and `SfDb` both depend on that: a repo whose db
+ * lives outside `data_dir` (`observability.db: elsewhere/custom.db` next to
+ * `defaults.data_dir: .spf/data`) still has its sessions found. Relocating
+ * `data_dir` alone must never orphan an existing db's session artifacts.
  */
-export declare function resolveDataPaths(anchor: RepoAnchor, rawDataDir: string, rawDbPath: string): DataPaths;
+export declare function resolveDataPaths(anchor: RepoAnchor, rawDataDir: string, rawDb: ObservabilityDbInput): DataPaths;
 /**
  * Resolve a prompt ref (a `prompt_engineering.system`/`.user` value from
  * config) to an absolute path, trying every root a ref could sensibly be

package/dist/core/paths.js

@@ -19,6 +19,7 @@
 import { existsSync, lstatSync, realpathSync, rmSync, statSync } from "node:fs";
 import path from "node:path";
 import { findRepoRoot } from "./git_helper.js";
+import { resolveObservabilityDb } from "./data_types.js";
 export const PACKAGE_ROOT = path.resolve(import.meta.dirname, "..", "..");
 export const ASSETS_DIR = path.join(PACKAGE_ROOT, "assets");
 /** The prebuilt SPA — a sibling of dist/ and assets/, built once at publish time (see app/). */
@@ -121,14 +122,42 @@ function healBrokenDataDir(data_dir) {
  *
  * Not otherwise side-effect-free: see `healBrokenDataDir` above, which every
  * caller needs run before its own first `mkdirSync` against `data_dir`.
+ *
+ * `rawDb` accepts every form `ObservabilityConfigSchema.db` accepts (bare
+ * string, `{kind:"sqlite",...}`, `{kind:"d1",...}`) — normalized here via
+ * `resolveObservabilityDb` — so every existing call site
+ * (`resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db)`)
+ * keeps compiling and behaving unchanged with no call-site edit needed.
+ *
+ * For a `"sqlite"`-kind db, `db_path`/`db.path` resolve BYTE-FOR-BYTE
+ * identically to before this PR: `path.resolve(repo_root, path)`.
+ *
+ * For a `"d1"`-kind db there is no local file at all — `db_path` is `null`,
+ * and `db` carries the resolved `{kind:"d1", database_id, account_id_env,
+ * api_token_env}` for `core/trace_db.ts`'s `createTraceDb()` to open (PR 2:
+ * SPF #66). `sessions_dir` has no `db_path` to anchor off in this case, so it
+ * falls back to `data_dir/sessions` — session JSONL/envelope artifacts still
+ * always live on disk regardless of where the queryable trace mirror lives.
+ *
+ * For a `"sqlite"`-kind db, `sessions_dir` stays what it always was — ALWAYS
+ * a sibling of `db_path` (`dirname(db_path)/sessions`), never `data_dir`
+ * directly — `migrate.ts` and `SfDb` both depend on that: a repo whose db
+ * lives outside `data_dir` (`observability.db: elsewhere/custom.db` next to
+ * `defaults.data_dir: .spf/data`) still has its sessions found. Relocating
+ * `data_dir` alone must never orphan an existing db's session artifacts.
  */
-export function resolveDataPaths(anchor, rawDataDir, rawDbPath) {
+export function resolveDataPaths(anchor, rawDataDir, rawDb) {
     const data_dir = path.resolve(anchor.repo_root, rawDataDir);
     healBrokenDataDir(data_dir);
     const data_dir_rel = path.relative(anchor.repo_root, data_dir).split(path.sep).join("/");
-    const db_path = path.resolve(anchor.repo_root, rawDbPath);
+    const normalized = resolveObservabilityDb(rawDb);
+    if (normalized.kind === "d1") {
+        const sessions_dir = path.resolve(data_dir, "sessions");
+        return { data_dir, data_dir_rel, db: normalized, db_path: null, sessions_dir };
+    }
+    const db_path = path.resolve(anchor.repo_root, normalized.path);
     const sessions_dir = path.resolve(path.dirname(db_path), "sessions");
-    return { data_dir, data_dir_rel, db_path, sessions_dir };
+    return { data_dir, data_dir_rel, db: { kind: "sqlite", path: db_path }, db_path, sessions_dir };
 }
 /**
  * Resolve a prompt ref (a `prompt_engineering.system`/`.user` value from

package/dist/core/quality.d.ts

@@ -22,10 +22,10 @@ export interface RunLike {
     context_handoff_dir: string;
     repo_root: string;
     console: {
-        note: (message: string) => void;
+        note: (message: string) => Promise<void>;
     };
     tracer: {
-        event: (record: EventRecord) => string;
+        event: (record: EventRecord) => Promise<string>;
     };
     adw_id: string;
 }
@@ -41,7 +41,7 @@ export declare function resolveSuite(run: RunLike, suiteName: string): QualityCh
  * QualityNotConfigured (via resolveSuite) if the suite or any of its checks
  * isn't in the config — before any check runs, let alone any agent spawns.
  */
-export declare function runSuite(run: RunLike, suiteName: string): QualityResult;
+export declare function runSuite(run: RunLike, suiteName: string): Promise<QualityResult>;
 /**
  * The `test` suite alone — the deterministic test phase most chains use.
  *
@@ -50,9 +50,9 @@ export declare function runSuite(run: RunLike, suiteName: string): QualityResult
  * subprocess already knows; the repair loop is unchanged, because a failure
  * still reaches the builder through `asEnvelope` below.
  */
-export declare function runTests(run: RunLike): QualityResult;
+export declare function runTests(run: RunLike): Promise<QualityResult>;
 /** Every configured check, across every configured suite's union — the `all` suite. */
-export declare function runQuality(run: RunLike): QualityResult;
+export declare function runQuality(run: RunLike): Promise<QualityResult>;
 /**
  * Log a deterministic block's verdict — the same shape every chain uses.
  *
@@ -60,8 +60,8 @@ export declare function runQuality(run: RunLike): QualityResult;
  * hand; one copy here instead of one per chain.
  */
 export declare function record(ph: {
-    log: (payload: Record<string, unknown>) => void;
-}, result: QualityResult): void;
+    log: (payload: Record<string, unknown>) => Promise<void>;
+}, result: QualityResult): Promise<void>;
 /**
  * Wrap a deterministic result so an agent can be handed it directly.
  *

package/dist/core/quality.js

@@ -56,13 +56,13 @@ function shellJoin(argv) {
         .map((arg) => (/[\s"'$`\\!*?[\](){}<>|&;#~]/.test(arg) ? `'${arg.replace(/'/g, `'\\''`)}'` : arg))
         .join(" ");
 }
-function runCheck(spec, run) {
+async function runCheck(spec, run) {
     const phase = run.phases[run.phases.length - 1];
     const outputDir = checkDir(run, spec.name);
     const outputArtifact = path.join(outputDir, "command.log");
     const command = shellJoin(spec.argv);
     const env = operatorEnv(); // the engineer's own shell environment
-    run.console.note(`quality ${spec.name}: ${command}`);
+    await run.console.note(`quality ${spec.name}: ${command}`);
     const startedAt = nowIso();
     const clock = performance.now();
     let stdout = "";
@@ -100,7 +100,7 @@ function runCheck(spec, run) {
     writeFileSync(outputArtifact, `$ ${command}\nexit: ${returncode}\nduration_seconds: ${duration.toFixed(3)}\n` +
         `\n--- stdout ---\n${stdout}\n--- stderr ---\n${stderr}\n`);
     const passed = returncode === 0;
-    run.tracer.event(makeEventRecord({
+    await run.tracer.event(makeEventRecord({
         adw_id: run.adw_id,
         phase_id: phase.phase_id,
         type: "tool_call",
@@ -116,7 +116,7 @@ function runCheck(spec, run) {
         started_at: startedAt,
         ended_at: nowIso(),
     }));
-    run.console.note(`quality ${spec.name}: ${passed ? "passed" : "failed"} (exit ${returncode}, ${duration.toFixed(1)}s)`);
+    await run.console.note(`quality ${spec.name}: ${passed ? "passed" : "failed"} (exit ${returncode}, ${duration.toFixed(1)}s)`);
     return {
         name: spec.name,
         area: spec.area,
@@ -139,9 +139,15 @@ function runCheck(spec, run) {
  * QualityNotConfigured (via resolveSuite) if the suite or any of its checks
  * isn't in the config — before any check runs, let alone any agent spawns.
  */
-export function runSuite(run, suiteName) {
+export async function runSuite(run, suiteName) {
     const specs = resolveSuite(run, suiteName);
-    const checks = specs.map((spec) => runCheck(spec, run));
+    // Sequential, not Promise.all: check output/duration/tool_call ordering has
+    // always been one-at-a-time (spawnSync itself was always sequential) — a
+    // parallel run would interleave `run.console.note`/`run.tracer.event`
+    // calls across checks with no ordering guarantee.
+    const checks = [];
+    for (const spec of specs)
+        checks.push(await runCheck(spec, run));
     // A failure is the command, its exit code, and what it actually printed —
     // everything a builder needs to repair without opening a log or being told
     // what the error "means" by a parser that guessed.
@@ -163,11 +169,11 @@ export function runSuite(run, suiteName) {
  * subprocess already knows; the repair loop is unchanged, because a failure
  * still reaches the builder through `asEnvelope` below.
  */
-export function runTests(run) {
+export async function runTests(run) {
     return runSuite(run, "test");
 }
 /** Every configured check, across every configured suite's union — the `all` suite. */
-export function runQuality(run) {
+export async function runQuality(run) {
     return runSuite(run, "all");
 }
 /**
@@ -176,9 +182,9 @@ export function runQuality(run) {
  * Every quality/test phase in every chain reported this same summary by
  * hand; one copy here instead of one per chain.
  */
-export function record(ph, result) {
+export async function record(ph, result) {
     const passed = result.checks.filter((c) => c.passed).length;
-    ph.log({ passed: result.passed, checks: `${passed}/${result.checks.length}`, artifacts: result.artifacts.join(", ") });
+    await ph.log({ passed: result.passed, checks: `${passed}/${result.checks.length}`, artifacts: result.artifacts.join(", ") });
 }
 /**
  * Wrap a deterministic result so an agent can be handed it directly.