@kirrosh/zond 0.23.0 → 0.26.1

package/src/core/workspace/fixture-gaps.ts

@@ -0,0 +1,71 @@
+/**
+ * ARV-324: `.fixture-gaps.yaml` — per-API sidecar recording operations
+ * that `prepare-fixtures`/`discover` already confirmed return a client
+ * error (or an empty list) while hunting for fixture values — e.g. an
+ * empty/under-provisioned test account.
+ *
+ * `checks run` runs as a separate process invocation and, without this
+ * file, has no way to tell "known fixture gap" apart from "new backend
+ * bug" — both would land on the same operation with
+ * `recommended_action: report_backend_bug`. Loading this file lets the
+ * classifier downgrade to `fix_fixture` instead (see
+ * `core/classifier/recommended-action.ts`).
+ *
+ * Not the manifest (`.api-fixtures.yaml` stays spec-derived/read-only,
+ * regenerated only by `refresh-api`) — this is runtime-observed state,
+ * so it gets its own file, rewritten wholesale on every
+ * discover/prepare-fixtures run so a since-fixed gap doesn't linger.
+ */
+
+import { join } from "node:path";
+import { writeFile } from "node:fs/promises";
+
+export interface FixtureGap {
+  method: string;
+  path: string;
+  resource: string;
+  var: string;
+  reason: string;
+}
+
+const FILENAME = ".fixture-gaps.yaml";
+
+export async function readFixtureGaps(apiDir: string): Promise<FixtureGap[]> {
+  const file = Bun.file(join(apiDir, FILENAME));
+  if (!(await file.exists())) return [];
+  let parsed: unknown;
+  try {
+    parsed = Bun.YAML.parse(await file.text());
+  } catch {
+    return [];
+  }
+  if (!parsed || typeof parsed !== "object" || !Array.isArray((parsed as { gaps?: unknown }).gaps)) {
+    return [];
+  }
+  return (parsed as { gaps: FixtureGap[] }).gaps;
+}
+
+export async function writeFixtureGaps(apiDir: string, gaps: FixtureGap[]): Promise<void> {
+  const path = join(apiDir, FILENAME);
+  const header = `# .fixture-gaps.yaml — auto-written by prepare-fixtures/discover (ARV-324)
+#
+# Operations that returned a client error (or an empty list) while zond
+# hunted for a fixture value — a resource that's empty/inaccessible in
+# the target API. Read by \`checks run\` so it doesn't relabel the same
+# known gap as report_backend_bug. Safe to delete — regenerated on the
+# next prepare-fixtures / discover run.
+`;
+  const { stringify } = await import("yaml");
+  const body = stringify({ gaps }, { lineWidth: 0, defaultStringType: "PLAIN" });
+  await writeFile(path, header + "\n" + body, "utf-8");
+}
+
+/** Key an operation the same way on both the write side (discover/bootstrap,
+ *  always GET list-probes) and the read side (`CheckFinding.operation`). */
+export function gapKey(method: string, path: string): string {
+  return `${method.toUpperCase()} ${path}`;
+}
+
+export function gapIndex(gaps: FixtureGap[]): Set<string> {
+  return new Set(gaps.map((g) => gapKey(g.method, g.path)));
+}

package/src/core/workspace/root.ts

@@ -7,11 +7,10 @@ import { homedir } from "node:os";
  * markers win when more than one is present in the same directory.
  *
  *   zond.config.yml — explicit project config (T12)
- *   .zond/          — `zond init --here` subdir convention (T19)
- *   zond.db         — flat layout from `zond init`
- *   apis/           — flat layout (collections directory)
+ *   .zond/          — runtime state subdir (holds zond.db, current-api, …)
+ *   apis/           — collections directory
  */
-export const WORKSPACE_MARKERS = ["zond.config.yml", ".zond", "zond.db", "apis"] as const;
+export const WORKSPACE_MARKERS = ["zond.config.yml", ".zond", "apis"] as const;
 export type WorkspaceMarker = (typeof WORKSPACE_MARKERS)[number];
 
 export interface WorkspaceInfo {
@@ -29,7 +28,7 @@ function hasMarker(dir: string): WorkspaceMarker | null {
   for (const m of WORKSPACE_MARKERS) {
     const p = join(dir, m);
     if (!existsSync(p)) continue;
-    // .zond and apis must be directories; zond.config.yml and zond.db must be files
+    // .zond and apis must be directories; zond.config.yml must be a file
     try {
       const st = statSync(p);
       if (m === ".zond" || m === "apis") {
@@ -47,13 +46,21 @@ function hasMarker(dir: string): WorkspaceMarker | null {
 /**
  * Walk-up from `cwd` (default `process.cwd()`) to the nearest workspace
  * marker. The walk stops at `os.homedir()` to avoid accidentally picking up
- * `~/apis` or `~/zond.db` when the user runs zond from somewhere unrelated.
+ * `~/apis` or `~/.zond` when the user runs zond from somewhere unrelated.
  *
  * When no marker is found, returns `{ root: cwd, fromFallback: true }` and
  * prints a one-time stderr warning so the user knows zond is operating in
  * cwd-mode.
  */
 export function findWorkspaceRoot(cwd?: string): WorkspaceInfo {
+  // Explicit override for headless/CI/workflow runs: skip walk-up entirely and
+  // anchor the workspace at ZOND_WORKSPACE. Lets each run own an isolated root
+  // (its own .zond/zond.db, apis/) without depending on cwd or a parent marker.
+  const override = process.env.ZOND_WORKSPACE?.trim();
+  if (override) {
+    return { root: resolve(override), marker: "", fromFallback: false };
+  }
+
   const start = resolve(cwd ?? process.cwd());
   const stop = resolve(homedir());
 
@@ -83,11 +90,6 @@ export function findWorkspaceRoot(cwd?: string): WorkspaceInfo {
   return { root: start, marker: "", fromFallback: true };
 }
 
-/** Resolve `relative` against the workspace root (auto-detected from `cwd`). */
-export function resolveWorkspacePath(relative: string, cwd?: string): string {
-  return resolve(findWorkspaceRoot(cwd).root, relative);
-}
-
 /** Test helper: reset the one-shot warning latch. */
 export function _resetWorkspaceWarning(): void {
   warned = false;

package/src/db/migrate.ts

@@ -32,6 +32,7 @@
 import type { Database } from "bun:sqlite";
 
 import migration_0001_run_kind from "./migrations/0001_run_kind.sql" with { type: "text" };
+import migration_0002_run_kind_request from "./migrations/0002_run_kind_request.sql" with { type: "text" };
 
 /** Migration manifest. Each entry is a `{ id, sql }` pair; order in
  *  this array is the apply order, matching the lexical sort that the
@@ -40,6 +41,7 @@ import migration_0001_run_kind from "./migrations/0001_run_kind.sql" with { type
  *  list. The runner reads this constant, not the filesystem. */
 const MIGRATIONS: ReadonlyArray<{ id: string; sql: string }> = [
   { id: "0001_run_kind", sql: migration_0001_run_kind },
+  { id: "0002_run_kind_request", sql: migration_0002_run_kind_request },
 ];
 
 /** Pre-existing migration ids that were already applied by the legacy

package/src/db/migrations/0002_run_kind_request.sql

@@ -0,0 +1,59 @@
+-- ARV-265 (m-22): extend `runs.run_kind` CHECK constraint to include
+-- 'request' (zond request in-session) and 'fixture' (prepare-fixtures
+-- cascade list-calls), so audit-coverage can attribute HTTP touches
+-- back to those producers.
+--
+-- The CHECK constraint can't be added with ALTER TABLE in SQLite. Bun's
+-- bun:sqlite also locks `sqlite_master` against direct UPDATEs, so the
+-- usual `PRAGMA writable_schema=1` rewrite is rejected. We use the
+-- canonical SQLite 12-step rebuild: create a parallel table with the
+-- new constraint, copy rows over, drop the old, rename.
+--
+-- The migration runner wraps this in a transaction. FK references from
+-- `results.run_id` to `runs(id)` survive the DROP+RENAME because SQLite
+-- resolves FK targets by name at row-modification time, not at table
+-- definition time — when the new `runs` ends up with the same name the
+-- soft reference is reattached transparently. Indexes are explicitly
+-- recreated post-rename (they don't survive a DROP).
+
+CREATE TABLE runs_new (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  started_at    TEXT NOT NULL,
+  finished_at   TEXT,
+  total         INTEGER NOT NULL DEFAULT 0,
+  passed        INTEGER NOT NULL DEFAULT 0,
+  failed        INTEGER NOT NULL DEFAULT 0,
+  skipped       INTEGER NOT NULL DEFAULT 0,
+  trigger       TEXT DEFAULT 'manual',
+  commit_sha    TEXT,
+  branch        TEXT,
+  environment   TEXT,
+  duration_ms   INTEGER,
+  collection_id INTEGER REFERENCES collections(id),
+  session_id    TEXT,
+  tags          TEXT,
+  run_kind      TEXT NOT NULL DEFAULT 'regular'
+                CHECK (run_kind IN ('regular','probe','check','request','fixture'))
+);
+
+INSERT INTO runs_new (
+  id, started_at, finished_at, total, passed, failed, skipped, trigger,
+  commit_sha, branch, environment, duration_ms, collection_id, session_id,
+  tags, run_kind
+)
+SELECT
+  id, started_at, finished_at, total, passed, failed, skipped, trigger,
+  commit_sha, branch, environment, duration_ms, collection_id, session_id,
+  tags,
+  CASE
+    WHEN run_kind IN ('regular','probe','check','request','fixture') THEN run_kind
+    ELSE 'regular'
+  END
+FROM runs;
+
+DROP TABLE runs;
+ALTER TABLE runs_new RENAME TO runs;
+
+CREATE INDEX IF NOT EXISTS idx_runs_started    ON runs(started_at DESC);
+CREATE INDEX IF NOT EXISTS idx_runs_collection ON runs(collection_id);
+CREATE INDEX IF NOT EXISTS idx_runs_session    ON runs(session_id, started_at DESC);

package/src/db/queries/collections.ts

@@ -29,7 +29,7 @@ export function getCollectionById(id: number): CollectionRecord | null {
 
 export function getLatestRunByCollection(
   collectionId: number,
-  opts: { runKind?: "regular" | "probe" | "check" | "any" } = {},
+  opts: { runKind?: import("../../core/runner/run-kind.ts").RunKind | "any" } = {},
 ): RunRecord | null {
   const db = getDb();
   // ARV-55: 'regular' is the default so coverage skips probe-only runs
@@ -58,7 +58,7 @@ export function getLatestRunByCollection(
   // ARV-55: normalise run_kind alongside tags so RunRecord stays consistent.
   const rk = row.run_kind;
   const run_kind: import("../../core/runner/run-kind.ts").RunKind =
-    rk === "probe" || rk === "check" ? rk : "regular";
+    rk === "probe" || rk === "check" || rk === "request" || rk === "fixture" ? rk : "regular";
   return { ...(row as unknown as RunRecord), tags, run_kind };
 }
 

package/src/db/queries/results.ts

@@ -91,6 +91,94 @@ export function getResultsByRunId(runId: number): StoredStepResult[] {
   }));
 }
 
+/**
+ * Row shape for the fixture-kind POST history matched by
+ * `getRecentFixturePosts`'s SQL LIKE pattern (typically the
+ * create-endpoint URL with `{var}` path params replaced by `%`).
+ */
+export interface LastFixtureAttempt {
+  request_method: string;
+  request_url: string;
+  request_body: string | null;
+  response_status: number | null;
+  response_body: string | null;
+  attempted_at: string;
+}
+
+/**
+ * ARV-278: return the most recent N fixture-POST attempts (most recent
+ * first). Powers `dump --with-last-attempt --history N` so the agent
+ * sees the progression of errors as the overlay was iterated — e.g.
+ * "first 400 said missing X, after fixing the body the next 400 said
+ * resource_missing customer" surfaces the cascade-staleness issue (see
+ * ARV-282) one level earlier than a single-snapshot view.
+ */
+export function getRecentFixturePosts(
+  urlLikePattern: string,
+  limit: number,
+): LastFixtureAttempt[] {
+  if (!Number.isFinite(limit) || limit <= 0) return [];
+  const db = getDb();
+  const rows = db.query(`
+    SELECT
+      r.request_method  AS request_method,
+      r.request_url     AS request_url,
+      r.request_body    AS request_body,
+      r.response_status AS response_status,
+      r.response_body   AS response_body,
+      ru.started_at     AS attempted_at
+    FROM results r
+    JOIN runs ru ON r.run_id = ru.id
+    WHERE ru.run_kind = 'fixture'
+      AND r.request_method = 'POST'
+      AND r.request_url LIKE ?
+    ORDER BY ru.started_at DESC, r.id DESC
+    LIMIT ?
+  `).all(urlLikePattern, Math.floor(limit)) as LastFixtureAttempt[];
+  return rows;
+}
+
+/**
+ * ARV-330: like `getRecentFixturePosts` but across ALL run kinds
+ * (`check`/`probe`/`run`/`request`/`fixture`). A root resource with no
+ * seed_body is `skip-no-create` by prepare-fixtures, so it never records
+ * a fixture-kind POST — yet a depth-check or probe may have POSTed the
+ * same create-path and captured the account-level capability error. The
+ * hard-blocked classifier reads this wider source so it can still
+ * diagnose the gate. Caller is responsible for filtering auth-probe
+ * noise (deliberately-broken-cred 401/403s).
+ */
+export function getRecentCreatePosts(
+  urlLikePattern: string,
+  limit: number,
+  excludeLikePattern?: string,
+): LastFixtureAttempt[] {
+  if (!Number.isFinite(limit) || limit <= 0) return [];
+  const db = getDb();
+  // `excludeLikePattern` filters out child sub-resource POSTs in SQL (e.g.
+  // `%/v1/accounts/%` drops `/v1/accounts/{id}/reject`); without it the
+  // loose trailing wildcard lets a burst of probe sub-calls monopolize the
+  // LIMIT window and starve the real create-path attempts (ARV-330).
+  const rows = excludeLikePattern
+    ? db.query(`
+        SELECT r.request_method AS request_method, r.request_url AS request_url,
+               r.request_body AS request_body, r.response_status AS response_status,
+               r.response_body AS response_body, ru.started_at AS attempted_at
+        FROM results r JOIN runs ru ON r.run_id = ru.id
+        WHERE r.request_method = 'POST' AND r.request_url LIKE ? AND r.request_url NOT LIKE ?
+        ORDER BY ru.started_at DESC, r.id DESC LIMIT ?
+      `).all(urlLikePattern, excludeLikePattern, Math.floor(limit))
+    : db.query(`
+        SELECT r.request_method AS request_method, r.request_url AS request_url,
+               r.request_body AS request_body, r.response_status AS response_status,
+               r.response_body AS response_body, ru.started_at AS attempted_at
+        FROM results r JOIN runs ru ON r.run_id = ru.id
+        WHERE r.request_method = 'POST' AND r.request_url LIKE ?
+        ORDER BY ru.started_at DESC, r.id DESC LIMIT ?
+      `).all(urlLikePattern, Math.floor(limit));
+  return rows as LastFixtureAttempt[];
+}
+
 export function getFilteredResults(
   runId: number,
   filters: {

package/src/db/queries/runs.ts

@@ -77,10 +77,10 @@ function decodeTags(raw: unknown): string[] | null {
   }
 }
 
-function decodeRunKind(raw: unknown): "regular" | "probe" | "check" {
+function decodeRunKind(raw: unknown): import("../../core/runner/run-kind.ts").RunKind {
   // Migration v10 backfills legacy rows; this is a belt-and-suspenders
   // normaliser for any value SQLite returns from `run_kind`.
-  if (raw === "probe" || raw === "check") return raw;
+  if (raw === "probe" || raw === "check" || raw === "request" || raw === "fixture") return raw;
   return "regular";
 }
 
@@ -223,6 +223,60 @@ export function deleteRun(runId: number): boolean {
   });
 }
 
+/** ARV-266: per-run_kind row counts so `zond db stats` can surface DB
+ *  growth. `results` counts the child rows that would be reclaimed. */
+export interface RunKindStat {
+  run_kind: string;
+  runs: number;
+  results: number;
+  oldest?: string;
+  newest?: string;
+}
+
+export function runKindStats(): RunKindStat[] {
+  const db = getDb();
+  const rows = db.query(`
+    SELECT r.run_kind AS run_kind,
+           COUNT(DISTINCT r.id) AS runs,
+           COUNT(res.id) AS results,
+           MIN(r.started_at) AS oldest,
+           MAX(r.started_at) AS newest
+    FROM runs r
+    LEFT JOIN results res ON res.run_id = r.id
+    GROUP BY r.run_kind
+    ORDER BY runs DESC
+  `).all() as Array<{ run_kind: string; runs: number; results: number; oldest: string | null; newest: string | null }>;
+  return rows.map((r) => ({
+    run_kind: r.run_kind,
+    runs: r.runs,
+    results: r.results,
+    ...(r.oldest ? { oldest: r.oldest } : {}),
+    ...(r.newest ? { newest: r.newest } : {}),
+  }));
+}
+
+/** ARV-266: delete runs (and their results) started strictly before
+ *  `cutoffIso`. When `kind` is given, only that run_kind is pruned.
+ *  Returns the number of runs + result rows removed. Caller VACUUMs. */
+export function deleteRunsOlderThan(
+  cutoffIso: string,
+  kind?: string,
+): { runs: number; results: number } {
+  const db = getDb();
+  return withDbRetry("deleteRunsOlderThan", () => {
+    const kindClause = kind ? "AND run_kind = ?" : "";
+    const selParams = kind ? [cutoffIso, kind] : [cutoffIso];
+    const ids = (db.query(
+      `SELECT id FROM runs WHERE started_at < ? ${kindClause}`,
+    ).all(...selParams) as Array<{ id: number }>).map((r) => r.id);
+    if (ids.length === 0) return { runs: 0, results: 0 };
+    const placeholders = ids.map(() => "?").join(",");
+    const res = db.prepare(`DELETE FROM results WHERE run_id IN (${placeholders})`).run(...ids);
+    db.prepare(`DELETE FROM runs WHERE id IN (${placeholders})`).run(...ids);
+    return { runs: ids.length, results: res.changes };
+  });
+}
+
 export function countRuns(filters?: RunFilters): number {
   const db = getDb();
   if (filters && Object.values(filters).some(Boolean)) {

package/src/db/queries.ts

@@ -43,6 +43,9 @@ export {
   listRunsByCollectionFiltered,
   getLatestFailingRunId,
   getLatestRunId,
+  runKindStats,
+  deleteRunsOlderThan,
+  type RunKindStat,
 } from "./queries/runs.ts";
 
 export { listSessions, countSessions, listRunsBySession } from "./queries/sessions.ts";

package/src/db/schema.ts

@@ -9,14 +9,11 @@ let _dbPath: string | null = null;
 
 /**
  * Default DB path lives under `<workspace>/.zond/zond.db` to keep runtime
- * artifacts out of the project root. For back-compat we still recognise a
- * legacy `<workspace>/zond.db` if it exists — old workspaces keep working
- * without migration.
+ * artifacts out of the project root. (The flat `<workspace>/zond.db` layout
+ * was dropped in m-25 — pass an explicit `--db` to target a legacy file.)
  */
 function defaultDbPath(): string {
   const root = findWorkspaceRoot().root;
-  const legacy = resolve(root, "zond.db");
-  if (existsSync(legacy)) return legacy;
   return resolve(root, ".zond", "zond.db");
 }
 
@@ -133,8 +130,11 @@ const SCHEMA = `
     tags          TEXT,
     -- ARV-55: classify a run once at INSERT time so coverage / diagnose
     -- queries don't have to re-derive "is this a probe-only run?" from
-    -- the results' suite_file paths.
-    run_kind      TEXT NOT NULL DEFAULT 'regular' CHECK (run_kind IN ('regular','probe','check'))
+    -- the results' suite_file paths. ARV-265 extends the CHECK list with
+    -- 'request' (zond request in-session) and 'fixture' (prepare-fixtures
+    -- cascade list-calls) so audit-coverage can attribute HTTP touches
+    -- back to the producer.
+    run_kind      TEXT NOT NULL DEFAULT 'regular' CHECK (run_kind IN ('regular','probe','check','request','fixture'))
   );
 
   CREATE TABLE IF NOT EXISTS results (