gsd-pi 2.79.0-dev.5c910bb05 → 2.79.0-dev.ece5fd8ba

package/src/resources/extensions/gsd/tests/workflow-tool-executors.test.ts

@@ -692,7 +692,18 @@ test("executeSummarySave supports root-level deep planning artifacts", async ()
 
     const project = await inProjectDir(base, () => executeSummarySave({
       artifact_type: "PROJECT",
-      content: "# Project\n\n## What This Is\n\nA root project artifact.",
+      content: [
+        "# Project",
+        "",
+        "## What This Is",
+        "",
+        "A root project artifact.",
+        "",
+        "## Milestone Sequence",
+        "",
+        "- [ ] M001: Foundation - Establish the first runnable slice.",
+        "",
+      ].join("\n"),
     }, base));
     assert.equal(project.isError, undefined);
     assert.equal(project.details.path, "PROJECT.md");
@@ -794,7 +805,7 @@ test("executeSummarySave registers PROJECT milestone sequence for the next run",
   }
 });
 
-test("executeSummarySave keeps PROJECT artifact save successful if milestone registration fails", async () => {
+test("executeSummarySave hard-fails when milestone registration throws so silent No-Active-Milestone is impossible", async () => {
   const base = makeTmpBase();
   try {
     openTestDb(base);
@@ -824,10 +835,15 @@ test("executeSummarySave keeps PROJECT artifact save successful if milestone reg
       ].join("\n"),
     }, base));
 
-    assert.equal(result.isError, undefined);
+    // The artifact is persisted before registration runs, but registration must
+    // surface as isError so the LLM retries (INSERT OR IGNORE makes it idempotent)
+    // instead of announcing "ready" while the DB has zero milestone rows.
+    assert.equal(result.isError, true);
     assert.equal(result.details.path, "PROJECT.md");
-    assert.equal(result.details.registeredMilestones, undefined);
-    assert.match(String(result.details.warning), /milestone registration failed/);
+    assert.equal(result.details.error, "milestone_registration_threw");
+    assert.match(String(result.details.registration_error), /simulated milestone registration failure/);
+    assert.match(result.content[0].text, /milestone registration failed/);
+    assert.match(result.content[0].text, /idempotent/);
     assert.ok(existsSync(join(base, ".gsd", "PROJECT.md")));
     const artifact = originalPrepare("SELECT path FROM artifacts WHERE path = ?").get("PROJECT.md");
     assert.equal(artifact?.path, "PROJECT.md");
@@ -872,9 +888,22 @@ test("executeSummarySave requires verified root approval in deep mode", async ()
     writeFileSync(join(base, ".gsd", "PREFERENCES.md"), "---\nplanning_depth: deep\n---\n");
     openTestDb(base);
 
+    const projectFixture = [
+      "# Project",
+      "",
+      "## What This Is",
+      "",
+      "A root project artifact.",
+      "",
+      "## Milestone Sequence",
+      "",
+      "- [ ] M001: Foundation - Establish the first runnable slice.",
+      "",
+    ].join("\n");
+
     const blocked = await inProjectDir(base, () => executeSummarySave({
       artifact_type: "PROJECT",
-      content: "# Project\n\n## What This Is\n\nA root project artifact.",
+      content: projectFixture,
     }, base));
 
     assert.equal(blocked.isError, true);
@@ -886,7 +915,7 @@ test("executeSummarySave requires verified root approval in deep mode", async ()
 
     const unblocked = await inProjectDir(base, () => executeSummarySave({
       artifact_type: "PROJECT",
-      content: "# Project\n\n## What This Is\n\nA root project artifact.",
+      content: projectFixture,
     }, base));
 
     assert.equal(unblocked.isError, undefined);

package/src/resources/extensions/gsd/tools/workflow-tool-executors.ts

@@ -190,19 +190,63 @@ export async function executeSummarySave(
     );
 
     let registeredMilestones: string[] = [];
-    let registrationWarning: string | undefined;
     if (params.artifact_type === "PROJECT") {
       try {
         registeredMilestones = registerProjectMilestoneSequence(contentToSave);
         if (registeredMilestones.length > 0) invalidateStateCache();
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        registrationWarning = `PROJECT artifact saved, but milestone registration failed: ${msg}`;
-        logWarning("tool", registrationWarning, {
+        logError("tool", `gsd_summary_save: PROJECT artifact persisted but milestone registration threw: ${msg}`, {
           tool: "gsd_summary_save",
           error: String(err),
           stack: err instanceof Error ? err.stack ?? "" : "",
         });
+        // PROJECT.md was persisted by saveArtifactToDb above; the artifacts row
+        // changed even though no milestones registered. Invalidate so subsequent
+        // /gsd reads see the persisted artifact instead of the pre-save cache.
+        invalidateStateCache();
+        return {
+          content: [{
+            type: "text",
+            text:
+              `Error: PROJECT.md was saved to ${relativePath} but milestone registration failed: ${msg}. ` +
+              `The DB has no milestone rows for this project, so /gsd will report "No Active Milestone". ` +
+              `Re-call gsd_summary_save(PROJECT) once the underlying error is resolved — INSERT OR IGNORE makes registration idempotent.`,
+          }],
+          details: {
+            operation: "save_summary",
+            path: relativePath,
+            artifact_type: params.artifact_type,
+            error: "milestone_registration_threw",
+            registration_error: msg,
+          },
+          isError: true,
+        };
+      }
+      if (registeredMilestones.length === 0) {
+        logError("tool", `gsd_summary_save: PROJECT.md saved to ${relativePath} but parsed zero milestones — registration produced no DB rows`, {
+          tool: "gsd_summary_save",
+        });
+        // PROJECT.md was persisted; invalidate so subsequent reads see the new
+        // artifacts row even though no milestones registered.
+        invalidateStateCache();
+        return {
+          content: [{
+            type: "text",
+            text:
+              `Error: PROJECT.md was saved to ${relativePath} but contains zero parseable milestone lines, ` +
+              `so no milestones were registered in the DB. /gsd will report "No Active Milestone". ` +
+              `Rewrite PROJECT.md so the "Milestone Sequence" section uses canonical lines: ` +
+              `\`- [ ] M001: <Title> — <One-liner>\` (em-dash, double-dash \`--\`, or single-dash \`-\` separator), then re-call gsd_summary_save(PROJECT).`,
+          }],
+          details: {
+            operation: "save_summary",
+            path: relativePath,
+            artifact_type: params.artifact_type,
+            error: "milestone_registration_empty_parse",
+          },
+          isError: true,
+        };
       }
     }
 
@@ -225,7 +269,6 @@ export async function executeSummarySave(
         artifact_type: params.artifact_type,
         content_source: contentSource,
         ...(registeredMilestones.length > 0 ? { registeredMilestones } : {}),
-        ...(registrationWarning ? { warning: registrationWarning } : {}),
       },
     };
   } catch (err) {

package/src/resources/extensions/gsd/uok/audit.ts

@@ -1,3 +1,5 @@
+// GSD2 UOK Audit Events and DB-First Projection Writes
+
 import { appendFileSync, closeSync, existsSync, mkdirSync, openSync } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
@@ -6,7 +8,7 @@ import { isStaleWrite } from "../auto/turn-epoch.js";
 import { withFileLockSync } from "../file-lock.js";
 import { gsdRoot } from "../paths.js";
 import { isDbAvailable, insertAuditEvent } from "../gsd-db.js";
-import type { AuditEventEnvelope } from "./contracts.js";
+import { CURRENT_UOK_CONTRACT_VERSION, validateAuditEvent, type AuditEventEnvelope } from "./contracts.js";
 
 function auditLogPath(basePath: string): string {
   return join(gsdRoot(basePath), "audit", "events.jsonl");
@@ -25,6 +27,7 @@ export function buildAuditEnvelope(args: {
   payload?: Record<string, unknown>;
 }): AuditEventEnvelope {
   return {
+    version: CURRENT_UOK_CONTRACT_VERSION,
     eventId: randomUUID(),
     traceId: args.traceId,
     turnId: args.turnId,
@@ -39,6 +42,26 @@ export function buildAuditEnvelope(args: {
 export function emitUokAuditEvent(basePath: string, event: AuditEventEnvelope): void {
   // Drop writes from a turn superseded by timeout recovery / cancellation.
   if (isStaleWrite("uok-audit")) return;
+  const validation = validateAuditEvent(event);
+  if (!validation.ok) {
+    throw new Error(`Invalid UOK audit event: ${validation.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`);
+  }
+  const canonical = validation.value;
+
+  if (isDbAvailable()) {
+    try {
+      insertAuditEvent({
+        ...canonical,
+        payload: {
+          ...canonical.payload,
+          contractVersion: canonical.version ?? CURRENT_UOK_CONTRACT_VERSION,
+        },
+      });
+    } catch (err) {
+      throw new Error(`DB authoritative audit write failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
   try {
     ensureAuditDir(basePath);
     const path = auditLogPath(basePath);
@@ -52,18 +75,11 @@ export function emitUokAuditEvent(basePath: string, event: AuditEventEnvelope):
     withFileLockSync(
       path,
       () => {
-        appendFileSync(path, `${JSON.stringify(event)}\n`, "utf-8");
+        appendFileSync(path, `${JSON.stringify(canonical)}\n`, "utf-8");
       },
       { onLocked: "skip" },
     );
   } catch {
     // Best-effort: audit writes must never break orchestration.
   }
-
-  if (!isDbAvailable()) return;
-  try {
-    insertAuditEvent(event);
-  } catch {
-    // Projection failures are non-fatal while legacy readers are still active.
-  }
 }

package/src/resources/extensions/gsd/uok/contracts.ts

@@ -1,3 +1,9 @@
+// GSD2 UOK Contract Types and Versioning
+
+export const CURRENT_UOK_CONTRACT_VERSION = "1" as const;
+
+export type UokContractVersion = "0" | typeof CURRENT_UOK_CONTRACT_VERSION;
+
 export type FailureClass =
   | "none"
   | "policy"
@@ -77,6 +83,7 @@ export interface TurnCloseoutRecord {
 }
 
 export interface TurnResult {
+  version?: UokContractVersion;
   traceId: string;
   turnId: string;
   iteration: number;
@@ -109,6 +116,7 @@ export interface DispatchExplanation {
 }
 
 export interface UokDispatchEnvelope {
+  version?: UokContractVersion;
   action: "dispatch" | "stop" | "skip";
   nodeKind?: UokNodeKind;
   unitType?: string;
@@ -130,6 +138,7 @@ export interface UokDispatchEnvelope {
 }
 
 export interface AuditEventEnvelope {
+  version?: UokContractVersion;
   eventId: string;
   traceId: string;
   turnId?: string;
@@ -199,3 +208,99 @@ export interface UokTurnObserver {
   ): void;
   onTurnResult(result: TurnResult): void;
 }
+
+export interface ContractValidationIssue {
+  path: string;
+  message: string;
+}
+
+export interface ContractValidationResult<T> {
+  ok: boolean;
+  value: T;
+  issues: ContractValidationIssue[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeVersion(value: unknown): UokContractVersion {
+  return value === CURRENT_UOK_CONTRACT_VERSION ? CURRENT_UOK_CONTRACT_VERSION : "0";
+}
+
+function requireString(
+  value: Record<string, unknown>,
+  key: string,
+  issues: ContractValidationIssue[],
+): void {
+  if (typeof value[key] !== "string" || value[key] === "") {
+    issues.push({ path: key, message: `${key} must be a non-empty string` });
+  }
+}
+
+function requireRecord(
+  value: Record<string, unknown>,
+  key: string,
+  issues: ContractValidationIssue[],
+): void {
+  if (!isRecord(value[key])) {
+    issues.push({ path: key, message: `${key} must be an object` });
+  }
+}
+
+export function normalizeTurnResult(value: TurnResult): TurnResult {
+  return { ...value, version: normalizeVersion(value.version) };
+}
+
+export function normalizeDispatchEnvelope(value: UokDispatchEnvelope): UokDispatchEnvelope {
+  return { ...value, version: normalizeVersion(value.version) };
+}
+
+export function normalizeAuditEvent(value: AuditEventEnvelope): AuditEventEnvelope {
+  return { ...value, version: normalizeVersion(value.version) };
+}
+
+export function validateTurnResult(value: TurnResult): ContractValidationResult<TurnResult> {
+  const normalized = normalizeTurnResult(value);
+  const record = normalized as unknown as Record<string, unknown>;
+  const issues: ContractValidationIssue[] = [];
+  requireString(record, "traceId", issues);
+  requireString(record, "turnId", issues);
+  if (!Number.isInteger(record.iteration)) {
+    issues.push({ path: "iteration", message: "iteration must be an integer" });
+  }
+  requireString(record, "status", issues);
+  requireString(record, "failureClass", issues);
+  if (!Array.isArray(record.phaseResults)) {
+    issues.push({ path: "phaseResults", message: "phaseResults must be an array" });
+  }
+  requireString(record, "startedAt", issues);
+  requireString(record, "finishedAt", issues);
+  return { ok: issues.length === 0, value: normalized, issues };
+}
+
+export function validateDispatchEnvelope(value: UokDispatchEnvelope): ContractValidationResult<UokDispatchEnvelope> {
+  const normalized = normalizeDispatchEnvelope(value);
+  const record = normalized as unknown as Record<string, unknown>;
+  const issues: ContractValidationIssue[] = [];
+  requireString(record, "action", issues);
+  requireRecord(record, "reason", issues);
+  if (isRecord(record.reason)) {
+    requireString(record.reason, "reasonCode", issues);
+    requireString(record.reason, "summary", issues);
+  }
+  return { ok: issues.length === 0, value: normalized, issues };
+}
+
+export function validateAuditEvent(value: AuditEventEnvelope): ContractValidationResult<AuditEventEnvelope> {
+  const normalized = normalizeAuditEvent(value);
+  const record = normalized as unknown as Record<string, unknown>;
+  const issues: ContractValidationIssue[] = [];
+  requireString(record, "eventId", issues);
+  requireString(record, "traceId", issues);
+  requireString(record, "category", issues);
+  requireString(record, "type", issues);
+  requireString(record, "ts", issues);
+  requireRecord(record, "payload", issues);
+  return { ok: issues.length === 0, value: normalized, issues };
+}

package/src/resources/extensions/gsd/uok/dispatch-envelope.ts

@@ -1,3 +1,5 @@
+// GSD2 UOK Dispatch Envelope Builder
+
 import type {
   DispatchExplanation,
   DispatchReasonCode,
@@ -5,6 +7,7 @@ import type {
   UokDispatchEnvelope,
   UokGraphNode,
 } from "./contracts.js";
+import { CURRENT_UOK_CONTRACT_VERSION } from "./contracts.js";
 
 export interface BuildDispatchEnvelopeInput {
   action: UokDispatchEnvelope["action"];
@@ -22,6 +25,7 @@ export interface BuildDispatchEnvelopeInput {
 
 export function buildDispatchEnvelope(input: BuildDispatchEnvelopeInput): UokDispatchEnvelope {
   return {
+    version: CURRENT_UOK_CONTRACT_VERSION,
     action: input.action,
     nodeKind: input.node?.kind,
     unitType: input.unitType,

package/src/resources/extensions/gsd/uok/loop-adapter.ts

@@ -1,9 +1,12 @@
+// GSD2 UOK Turn Observer and DB-Backed Lifecycle Emission
+
 import type {
   TurnCloseoutRecord,
   TurnContract,
   TurnResult,
   UokTurnObserver,
 } from "./contracts.js";
+import { CURRENT_UOK_CONTRACT_VERSION, validateTurnResult } from "./contracts.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
 import { writeTurnCloseoutGitRecord, writeTurnGitTransaction } from "./gitops.js";
 import { acquireWriterToken, nextWriteRecord, releaseWriterToken } from "./writer.js";
@@ -142,56 +145,68 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
     },
 
     onTurnResult(result): void {
-      const merged: TurnResult = {
-        ...result,
-        phaseResults: result.phaseResults.length > 0 ? result.phaseResults : [...phaseResults],
+      const cleanup = (): void => {
+        if (writerToken) {
+          releaseWriterToken(options.basePath, writerToken);
+        }
+        writerToken = null;
+        current = null;
+        phaseResults.length = 0;
       };
 
-      if (options.enableAudit) {
-        emitUokAuditEvent(
-          options.basePath,
-          buildAuditEnvelope({
-            traceId: merged.traceId,
-            turnId: merged.turnId,
-            category: "orchestration",
-            type: "turn-result",
-            payload: nextSequenceMetadata("audit", "append", {
-              unitType: merged.unitType,
-              unitId: merged.unitId,
-              status: merged.status,
-              failureClass: merged.failureClass,
-              error: merged.error,
-              phaseCount: merged.phaseResults.length,
-            }),
-          }),
-        );
-      }
-
-      if (options.enableGitops) {
-        const closeout: TurnCloseoutRecord = merged.closeout ?? {
-          traceId: merged.traceId,
-          turnId: merged.turnId,
-          unitType: merged.unitType,
-          unitId: merged.unitId,
-          status: merged.status,
-          failureClass: merged.failureClass,
-          gitAction: options.gitAction,
-          gitPushed: options.gitPush,
-          finishedAt: merged.finishedAt,
+      try {
+        const merged: TurnResult = {
+          ...result,
+          version: CURRENT_UOK_CONTRACT_VERSION,
+          phaseResults: Array.isArray(result.phaseResults) && result.phaseResults.length > 0 ? result.phaseResults : [...phaseResults],
         };
-        writeTurnCloseoutGitRecord(
-          options.basePath,
-          closeout,
-          nextSequenceMetadata("gitops", "update", { action: "record" }),
-        );
-      }
+        const validation = validateTurnResult(merged);
+        if (!validation.ok) {
+          throw new Error(`Invalid UOK turn result: ${validation.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`);
+        }
 
-      if (writerToken) {
-        releaseWriterToken(options.basePath, writerToken);
+        if (options.enableAudit) {
+          emitUokAuditEvent(
+            options.basePath,
+            buildAuditEnvelope({
+              traceId: validation.value.traceId,
+              turnId: validation.value.turnId,
+              category: "orchestration",
+              type: "turn-result",
+              payload: nextSequenceMetadata("audit", "append", {
+                contractVersion: validation.value.version,
+                unitType: validation.value.unitType,
+                unitId: validation.value.unitId,
+                status: validation.value.status,
+                failureClass: validation.value.failureClass,
+                error: validation.value.error,
+                phaseCount: validation.value.phaseResults.length,
+              }),
+            }),
+          );
+        }
+
+        if (options.enableGitops) {
+          const closeout: TurnCloseoutRecord = merged.closeout ?? {
+            traceId: merged.traceId,
+            turnId: merged.turnId,
+            unitType: merged.unitType,
+            unitId: merged.unitId,
+            status: merged.status,
+            failureClass: merged.failureClass,
+            gitAction: options.gitAction,
+            gitPushed: options.gitPush,
+            finishedAt: merged.finishedAt,
+          };
+          writeTurnCloseoutGitRecord(
+            options.basePath,
+            closeout,
+            nextSequenceMetadata("gitops", "update", { action: "record" }),
+          );
+        }
+      } finally {
+        cleanup();
       }
-      writerToken = null;
-      current = null;
-      phaseResults.length = 0;
     },
   };
 }

package/src/resources/extensions/gsd/uok/timeline.ts

@@ -0,0 +1,158 @@
+// GSD2 UOK Timeline Reconstruction from Authoritative DB Records
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { _getAdapter, isDbAvailable } from "../gsd-db.js";
+import { gsdRoot } from "../paths.js";
+
+export interface TurnTimelineFilter {
+  traceId?: string;
+  turnId?: string;
+}
+
+export interface TurnTimelineEntry {
+  source: "audit_events" | "unit_dispatches" | "turn_git_transactions" | "audit_jsonl";
+  ts: string;
+  traceId?: string;
+  turnId?: string | null;
+  type: string;
+  payload: Record<string, unknown>;
+}
+
+export interface TurnTimeline {
+  authoritative: "db" | "degraded-fallback";
+  degraded: boolean;
+  entries: TurnTimelineEntry[];
+}
+
+function parseJsonRecord(value: unknown): Record<string, unknown> {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  if (typeof value !== "string" || value.trim() === "") return {};
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+      ? parsed as Record<string, unknown>
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+function matchesFilter(entry: Pick<TurnTimelineEntry, "traceId" | "turnId">, filter: TurnTimelineFilter): boolean {
+  if (filter.traceId && entry.traceId !== filter.traceId) return false;
+  if (filter.turnId && entry.turnId !== filter.turnId) return false;
+  return true;
+}
+
+function byTimestamp(a: TurnTimelineEntry, b: TurnTimelineEntry): number {
+  return a.ts.localeCompare(b.ts);
+}
+
+function readDbTimeline(filter: TurnTimelineFilter): TurnTimelineEntry[] {
+  const db = _getAdapter();
+  if (!db) return [];
+  const entries: TurnTimelineEntry[] = [];
+  const where: string[] = [];
+  const params: Record<string, string> = {};
+  if (filter.traceId) {
+    where.push("trace_id = :trace_id");
+    params[":trace_id"] = filter.traceId;
+  }
+  if (filter.turnId) {
+    where.push("turn_id = :turn_id");
+    params[":turn_id"] = filter.turnId;
+  }
+  const suffix = where.length > 0 ? ` WHERE ${where.join(" AND ")}` : "";
+
+  const auditRows = db.prepare(
+    `SELECT trace_id, turn_id, type, ts, payload_json FROM audit_events${suffix}`,
+  ).all(params) as Array<{ trace_id: string; turn_id: string | null; type: string; ts: string; payload_json: string }>;
+  for (const row of auditRows) {
+    entries.push({
+      source: "audit_events",
+      ts: row.ts,
+      traceId: row.trace_id,
+      turnId: row.turn_id,
+      type: row.type,
+      payload: parseJsonRecord(row.payload_json),
+    });
+  }
+
+  const dispatchRows = db.prepare(
+    `SELECT trace_id, turn_id, unit_type, unit_id, status, started_at, ended_at, exit_reason,
+            error_summary, retry_after_ms, attempt_n, max_attempts
+     FROM unit_dispatches${suffix}`,
+  ).all(params) as Array<Record<string, unknown>>;
+  for (const row of dispatchRows) {
+    entries.push({
+      source: "unit_dispatches",
+      ts: String(row.ended_at ?? row.started_at ?? ""),
+      traceId: String(row.trace_id ?? ""),
+      turnId: typeof row.turn_id === "string" ? row.turn_id : null,
+      type: `dispatch-${String(row.status ?? "unknown")}`,
+      payload: { ...row },
+    });
+  }
+
+  const gitRows = db.prepare(
+    `SELECT trace_id, turn_id, unit_type, unit_id, stage, action, push, status, error,
+            metadata_json, updated_at
+     FROM turn_git_transactions${suffix}`,
+  ).all(params) as Array<Record<string, unknown>>;
+  for (const row of gitRows) {
+    entries.push({
+      source: "turn_git_transactions",
+      ts: String(row.updated_at ?? ""),
+      traceId: String(row.trace_id ?? ""),
+      turnId: typeof row.turn_id === "string" ? row.turn_id : null,
+      type: `gitops-${String(row.stage ?? "unknown")}`,
+      payload: {
+        ...row,
+        metadata: parseJsonRecord(row.metadata_json),
+      },
+    });
+  }
+
+  return entries.filter((entry) => entry.ts !== "").sort(byTimestamp);
+}
+
+function readJsonlTimeline(basePath: string, filter: TurnTimelineFilter): TurnTimelineEntry[] {
+  const path = join(gsdRoot(basePath), "audit", "events.jsonl");
+  if (!existsSync(path)) return [];
+  return readFileSync(path, "utf-8")
+    .split("\n")
+    .filter(Boolean)
+    .map((line): TurnTimelineEntry | null => {
+      const event = parseJsonRecord(line);
+      const entry: TurnTimelineEntry = {
+        source: "audit_jsonl",
+        ts: String(event.ts ?? ""),
+        traceId: typeof event.traceId === "string" ? event.traceId : undefined,
+        turnId: typeof event.turnId === "string" ? event.turnId : null,
+        type: String(event.type ?? "audit"),
+        payload: parseJsonRecord(event.payload),
+      };
+      return entry.ts && matchesFilter(entry, filter) ? entry : null;
+    })
+    .filter((entry): entry is TurnTimelineEntry => entry !== null)
+    .sort(byTimestamp);
+}
+
+export function buildTurnTimeline(basePath: string, filter: TurnTimelineFilter = {}): TurnTimeline {
+  if (isDbAvailable()) {
+    return {
+      authoritative: "db",
+      degraded: false,
+      entries: readDbTimeline(filter),
+    };
+  }
+
+  return {
+    authoritative: "degraded-fallback",
+    degraded: true,
+    entries: readJsonlTimeline(basePath, filter),
+  };
+}