gsd-pi 2.79.0-dev.579e14e9b → 2.79.0-dev.bbb2f88ce

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),
+  };
+}

package/src/resources/extensions/shared/gsd-phase-state.ts

@@ -1,5 +1,5 @@
 /**
- * GSD Phase State — cross-extension coordination
+ * GSD2 Phase State — cross-extension coordination
  * Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
  *
  * Lightweight module-level state that GSD auto-mode writes to and the
@@ -7,28 +7,81 @@
  * a module variable is sufficient — no file I/O needed.
  */
 
+import { buildAuditEnvelope, emitUokAuditEvent } from "../gsd/uok/audit.js";
+
 let _active = false;
 let _currentPhase: string | null = null;
 
+export interface GSDPhaseAuditContext {
+	basePath: string;
+	traceId: string;
+	turnId?: string;
+	causedBy?: string;
+}
+
+let _auditContext: GSDPhaseAuditContext | null = null;
+
+function emitPhaseChange(action: string, previousPhase: string | null, nextPhase: string | null): void {
+	if (!_auditContext) return;
+	emitUokAuditEvent(
+		_auditContext.basePath,
+		buildAuditEnvelope({
+			traceId: _auditContext.traceId,
+			turnId: _auditContext.turnId,
+			causedBy: _auditContext.causedBy,
+			category: "orchestration",
+			type: "phase_changed",
+			payload: {
+				action,
+				active: _active,
+				previousPhase,
+				nextPhase,
+			},
+		}),
+	);
+}
+
+export function configureGSDPhaseAudit(context: GSDPhaseAuditContext | null): void {
+	_auditContext = context;
+}
+
 /** Mark GSD auto-mode as active. */
-export function activateGSD(): void {
+export function activateGSD(context?: GSDPhaseAuditContext): void {
+	if (context) _auditContext = context;
+	const previousPhase = _currentPhase;
 	_active = true;
+	emitPhaseChange("activate", previousPhase, _currentPhase);
 }
 
 /** Mark GSD auto-mode as inactive and clear the current phase. */
 export function deactivateGSD(): void {
+	const previousPhase = _currentPhase;
 	_active = false;
 	_currentPhase = null;
+	emitPhaseChange("deactivate", previousPhase, _currentPhase);
+	_auditContext = null;
 }
 
 /** Set the currently dispatched GSD phase (e.g. "plan-milestone"). */
-export function setCurrentPhase(phase: string): void {
+export function setCurrentPhase(phase: string, context?: GSDPhaseAuditContext): boolean {
+	if (context) _auditContext = context;
+	if (!_active) {
+		process.emitWarning(`Ignoring GSD phase "${phase}" while GSD auto-mode is inactive`, {
+			code: "GSD_PHASE_INACTIVE",
+		});
+		return false;
+	}
+	const previousPhase = _currentPhase;
 	_currentPhase = phase;
+	emitPhaseChange("set", previousPhase, _currentPhase);
+	return true;
 }
 
 /** Clear the current phase (unit completed or aborted). */
 export function clearCurrentPhase(): void {
+	const previousPhase = _currentPhase;
 	_currentPhase = null;
+	emitPhaseChange("clear", previousPhase, _currentPhase);
 }
 
 /** Returns true if GSD auto-mode is currently active. */

package/src/resources/extensions/shared/tests/gsd-phase-state.test.ts

@@ -1,7 +1,13 @@
+// GSD2 Shared Phase State Coordination Tests
+
 import { describe, it, beforeEach } from "node:test";
 import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import {
 	activateGSD,
+	configureGSDPhaseAudit,
 	deactivateGSD,
 	setCurrentPhase,
 	clearCurrentPhase,
@@ -25,12 +31,18 @@ describe("gsd-phase-state", () => {
 	it("tracks the current phase when active", () => {
 		activateGSD();
 		assert.equal(getCurrentPhase(), null);
-		setCurrentPhase("plan-milestone");
+		assert.equal(setCurrentPhase("plan-milestone"), true);
 		assert.equal(getCurrentPhase(), "plan-milestone");
 		clearCurrentPhase();
 		assert.equal(getCurrentPhase(), null);
 	});
 
+	it("rejects phase changes while inactive", () => {
+		assert.equal(setCurrentPhase("plan-milestone"), false);
+		activateGSD();
+		assert.equal(getCurrentPhase(), null);
+	});
+
 	it("returns null phase when inactive even if phase was set", () => {
 		activateGSD();
 		setCurrentPhase("plan-milestone");
@@ -45,4 +57,34 @@ describe("gsd-phase-state", () => {
 		activateGSD();
 		assert.equal(getCurrentPhase(), null);
 	});
+
+	it("deactivation clears the audit context so later events do not carry stale trace data", () => {
+		const basePath = mkdtempSync(join(tmpdir(), "gsd-phase-state-audit-"));
+		try {
+			activateGSD({ basePath, traceId: "stale-trace", causedBy: "test" });
+			setCurrentPhase("plan-milestone");
+			deactivateGSD();
+
+			// Re-activate WITHOUT a context. If deactivate did not clear the
+			// stored context, this setCurrentPhase would emit an audit event
+			// using "stale-trace".
+			activateGSD();
+			setCurrentPhase("execute-task");
+
+			const eventsPath = join(basePath, ".gsd", "audit", "events.jsonl");
+			if (existsSync(eventsPath)) {
+				const contents = readFileSync(eventsPath, "utf-8");
+				assert.equal(
+					contents.includes("stale-trace") &&
+						contents.split("\n").filter((line) => line.includes("stale-trace") && line.includes("execute-task")).length > 0,
+					false,
+					"execute-task phase change must not be emitted under the deactivated trace",
+				);
+			}
+		} finally {
+			configureGSDPhaseAudit(null);
+			deactivateGSD();
+			rmSync(basePath, { recursive: true, force: true });
+		}
+	});
 });