gsd-pi 2.79.0-dev.ece5fd8ba → 2.80.0-dev.4ea7d80e7

package/src/resources/extensions/gsd/db-provider.ts

@@ -0,0 +1,148 @@
+// Project/App: GSD-2
+// File Purpose: SQLite provider loading and fallback helpers for the GSD database facade.
+
+export type DbProviderName = "node:sqlite" | "better-sqlite3";
+
+export const BETTER_SQLITE3_PACKAGE = ["better", "sqlite3"].join("-");
+
+export interface SqliteProviderDeps {
+  requireModule(id: string): unknown;
+  suppressSqliteWarning(): void;
+  nodeVersion: string;
+  writeStderr(message: string): void;
+}
+
+export interface SqliteFallbackOpen {
+  providerName: "better-sqlite3";
+  providerModule: unknown;
+  rawDb: unknown;
+}
+
+type NodeSqliteModule = {
+  DatabaseSync?: new (path: string) => unknown;
+};
+
+type BetterSqliteModule =
+  | (new (path: string) => unknown)
+  | { default?: new (path: string) => unknown };
+
+export function suppressSqliteWarning(): void {
+  const origEmit = process.emit;
+  // Override via loose cast: Node's overloaded emit signature is not directly assignable.
+  (process as any).emit = function (event: string, ...args: unknown[]): boolean {
+    if (
+      event === "warning" &&
+      args[0] &&
+      typeof args[0] === "object" &&
+      "name" in args[0] &&
+      (args[0] as { name: string }).name === "ExperimentalWarning" &&
+      "message" in args[0] &&
+      typeof (args[0] as { message: string }).message === "string" &&
+      (args[0] as { message: string }).message.includes("SQLite")
+    ) {
+      return false;
+    }
+    return origEmit.apply(process, [event, ...args] as Parameters<typeof process.emit>) as unknown as boolean;
+  };
+}
+
+export class SqliteProviderLoader {
+  private providerName: DbProviderName | null = null;
+  private providerModule: unknown = null;
+  private loadAttempted = false;
+  private readonly deps: SqliteProviderDeps;
+
+  constructor(deps: SqliteProviderDeps) {
+    this.deps = deps;
+  }
+
+  load(): void {
+    if (this.loadAttempted) return;
+    this.loadAttempted = true;
+
+    try {
+      this.deps.suppressSqliteWarning();
+      const mod = this.deps.requireModule("node:sqlite") as NodeSqliteModule;
+      if (mod.DatabaseSync) {
+        this.providerModule = mod;
+        this.providerName = "node:sqlite";
+        return;
+      }
+    } catch {
+      // unavailable
+    }
+
+    const betterSqlite = this.loadBetterSqliteModule();
+    if (betterSqlite) {
+      this.providerModule = betterSqlite;
+      this.providerName = "better-sqlite3";
+      return;
+    }
+
+    const nodeMajor = parseInt(this.deps.nodeVersion.split(".")[0], 10);
+    const versionHint = nodeMajor < 22
+      ? ` GSD requires Node >= 22.0.0 (current: v${this.deps.nodeVersion}). Upgrade Node to fix this.`
+      : "";
+    this.deps.writeStderr(
+      `gsd-db: No SQLite provider available (tried node:sqlite, better-sqlite3).${versionHint}\n`,
+    );
+  }
+
+  getProviderName(): DbProviderName | null {
+    return this.providerName;
+  }
+
+  openRaw(path: string): unknown {
+    this.load();
+    if (!this.providerModule || !this.providerName) return null;
+
+    if (this.providerName === "node:sqlite") {
+      const { DatabaseSync } = this.providerModule as {
+        DatabaseSync: new (path: string) => unknown;
+      };
+      return new DatabaseSync(path);
+    }
+
+    const Database = this.providerModule as new (path: string) => unknown;
+    return new Database(path);
+  }
+
+  tryOpenBetterSqliteFallback(path: string): SqliteFallbackOpen | null {
+    if (this.providerName !== "node:sqlite") return null;
+
+    const Database = this.loadBetterSqliteModule();
+    if (!Database) return null;
+
+    return {
+      providerName: "better-sqlite3",
+      providerModule: Database,
+      rawDb: new Database(path),
+    };
+  }
+
+  commitFallback(fallback: SqliteFallbackOpen): void {
+    this.providerName = fallback.providerName;
+    this.providerModule = fallback.providerModule;
+  }
+
+  reset(): void {
+    this.loadAttempted = false;
+    this.providerModule = null;
+    this.providerName = null;
+  }
+
+  private loadBetterSqliteModule(): (new (path: string) => unknown) | null {
+    try {
+      const mod = this.deps.requireModule(BETTER_SQLITE3_PACKAGE) as BetterSqliteModule;
+      if (typeof mod === "function") return mod;
+      if (mod && typeof mod.default === "function") return mod.default;
+    } catch {
+      // unavailable
+    }
+    return null;
+  }
+}
+
+export function createSqliteProviderLoader(deps: SqliteProviderDeps): SqliteProviderLoader {
+  return new SqliteProviderLoader(deps);
+}

package/src/resources/extensions/gsd/db-runtime-kv-schema.ts

@@ -0,0 +1,30 @@
+// Project/App: GSD-2
+// File Purpose: Runtime key-value SQLite schema helper for the GSD database facade.
+
+import type { DbAdapter } from "./db-adapter.js";
+
+/**
+ * Create the v25 runtime_kv table. Idempotent — uses IF NOT EXISTS.
+ *
+ * STRICT INVARIANT: runtime_kv is NON-CORRECTNESS-CRITICAL. UI cursors,
+ * dashboard caches, last-seen-version markers, resume cursors, and other
+ * "soft" state are OK. Anything that drives auto-mode control flow gets
+ * typed columns in unit_dispatches / workers / milestone_leases — never
+ * a bag of JSON in runtime_kv.
+ *
+ * Scope partitioning: ('global', '', key) for project-wide values;
+ * ('worker', worker_id, key) for per-worker state (resume cursors);
+ * ('milestone', milestone_id, key) for per-milestone soft state.
+ */
+export function createRuntimeKvTableV25(db: DbAdapter): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS runtime_kv (
+      scope TEXT NOT NULL,
+      scope_id TEXT NOT NULL DEFAULT '',
+      key TEXT NOT NULL,
+      value_json TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      PRIMARY KEY (scope, scope_id, key)
+    )
+  `);
+}

package/src/resources/extensions/gsd/db-schema-metadata.ts

@@ -0,0 +1,33 @@
+// Project/App: GSD-2
+// File Purpose: SQLite schema metadata helpers for the GSD database facade and migrations.
+
+import type { DbAdapter } from "./db-adapter.js";
+
+export function indexExists(db: DbAdapter, name: string): boolean {
+  return !!db.prepare(
+    "SELECT 1 as present FROM sqlite_master WHERE type = 'index' AND name = ?",
+  ).get(name);
+}
+
+export function columnExists(db: DbAdapter, table: string, column: string): boolean {
+  const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+  return rows.some((row) => row["name"] === column);
+}
+
+export function ensureColumn(db: DbAdapter, table: string, column: string, ddl: string): void {
+  if (!columnExists(db, table, column)) db.exec(ddl);
+}
+
+export function getCurrentSchemaVersion(db: DbAdapter): number {
+  const row = db.prepare("SELECT MAX(version) as v FROM schema_version").get();
+  return row ? (row["v"] as number) : 0;
+}
+
+export function recordSchemaVersion(db: DbAdapter, version: number): void {
+  db.prepare(
+    "INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)",
+  ).run({
+    ":version": version,
+    ":applied_at": new Date().toISOString(),
+  });
+}

package/src/resources/extensions/gsd/db-task-slice-rows.ts

@@ -0,0 +1,146 @@
+// Project/App: GSD-2
+// File Purpose: Task and slice row mappers for the GSD database facade.
+
+export interface SliceRow {
+  milestone_id: string;
+  id: string;
+  title: string;
+  status: string;
+  risk: string;
+  depends: string[];
+  demo: string;
+  created_at: string;
+  completed_at: string | null;
+  full_summary_md: string;
+  full_uat_md: string;
+  goal: string;
+  success_criteria: string;
+  proof_level: string;
+  integration_closure: string;
+  observability_impact: string;
+  sequence: number;
+  replan_triggered_at: string | null;
+  is_sketch: number;
+  sketch_scope: string;
+}
+
+export interface TaskRow {
+  milestone_id: string;
+  slice_id: string;
+  id: string;
+  title: string;
+  status: string;
+  one_liner: string;
+  narrative: string;
+  verification_result: string;
+  duration: string;
+  completed_at: string | null;
+  blocker_discovered: boolean;
+  deviations: string;
+  known_issues: string;
+  key_files: string[];
+  key_decisions: string[];
+  full_summary_md: string;
+  description: string;
+  estimate: string;
+  files: string[];
+  verify: string;
+  inputs: string[];
+  expected_output: string[];
+  observability_impact: string;
+  full_plan_md: string;
+  sequence: number;
+  blocker_source: string;
+  escalation_pending: number;
+  escalation_awaiting_review: number;
+  escalation_artifact_path: string | null;
+  escalation_override_applied_at: string | null;
+}
+
+type DbRow = Record<string, unknown>;
+
+export function parseTaskArrayColumn(raw: unknown): string[] {
+  if (Array.isArray(raw)) {
+    return raw.filter((entry): entry is string => typeof entry === "string");
+  }
+  if (typeof raw !== "string") return [];
+
+  const trimmed = raw.trim();
+  if (!trimmed) return [];
+
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (Array.isArray(parsed)) {
+      return parsed.filter((entry): entry is string => typeof entry === "string");
+    }
+    if (typeof parsed === "string" && parsed.trim()) {
+      return [parsed.trim()];
+    }
+    if (parsed === null || parsed === undefined || parsed === "") {
+      return [];
+    }
+    return [String(parsed)];
+  } catch {
+    return trimmed.split(",").map((entry) => entry.trim()).filter(Boolean);
+  }
+}
+
+export function rowToSlice(row: DbRow): SliceRow {
+  return {
+    milestone_id: row["milestone_id"] as string,
+    id: row["id"] as string,
+    title: row["title"] as string,
+    status: row["status"] as string,
+    risk: row["risk"] as string,
+    depends: JSON.parse((row["depends"] as string) || "[]"),
+    demo: (row["demo"] as string) ?? "",
+    created_at: row["created_at"] as string,
+    completed_at: (row["completed_at"] as string) ?? null,
+    full_summary_md: (row["full_summary_md"] as string) ?? "",
+    full_uat_md: (row["full_uat_md"] as string) ?? "",
+    goal: (row["goal"] as string) ?? "",
+    success_criteria: (row["success_criteria"] as string) ?? "",
+    proof_level: (row["proof_level"] as string) ?? "",
+    integration_closure: (row["integration_closure"] as string) ?? "",
+    observability_impact: (row["observability_impact"] as string) ?? "",
+    sequence: (row["sequence"] as number) ?? 0,
+    replan_triggered_at: (row["replan_triggered_at"] as string) ?? null,
+    is_sketch: (row["is_sketch"] as number) ?? 0,
+    sketch_scope: (row["sketch_scope"] as string) ?? "",
+  };
+}
+
+export function rowToTask(row: DbRow): TaskRow {
+  return {
+    milestone_id: row["milestone_id"] as string,
+    slice_id: row["slice_id"] as string,
+    id: row["id"] as string,
+    title: row["title"] as string,
+    status: row["status"] as string,
+    one_liner: row["one_liner"] as string,
+    narrative: row["narrative"] as string,
+    verification_result: row["verification_result"] as string,
+    duration: row["duration"] as string,
+    completed_at: (row["completed_at"] as string) ?? null,
+    blocker_discovered: (row["blocker_discovered"] as number) === 1,
+    deviations: row["deviations"] as string,
+    known_issues: row["known_issues"] as string,
+    key_files: parseTaskArrayColumn(row["key_files"]),
+    key_decisions: parseTaskArrayColumn(row["key_decisions"]),
+    full_summary_md: row["full_summary_md"] as string,
+    description: (row["description"] as string) ?? "",
+    estimate: (row["estimate"] as string) ?? "",
+    files: parseTaskArrayColumn(row["files"]),
+    verify: (row["verify"] as string) ?? "",
+    inputs: parseTaskArrayColumn(row["inputs"]),
+    expected_output: parseTaskArrayColumn(row["expected_output"]),
+    observability_impact: (row["observability_impact"] as string) ?? "",
+    full_plan_md: (row["full_plan_md"] as string) ?? "",
+    sequence: (row["sequence"] as number) ?? 0,
+    blocker_source: (row["blocker_source"] as string) ?? "",
+    escalation_pending: (row["escalation_pending"] as number) ?? 0,
+    escalation_awaiting_review: (row["escalation_awaiting_review"] as number) ?? 0,
+    escalation_artifact_path: (row["escalation_artifact_path"] as string) ?? null,
+    escalation_override_applied_at: (row["escalation_override_applied_at"] as string) ?? null,
+  };
+}

package/src/resources/extensions/gsd/db-transaction.ts

@@ -0,0 +1,76 @@
+// Project/App: GSD-2
+// File Purpose: Transaction depth helper for the GSD database facade.
+
+export interface DbTransactionControls {
+  begin(): void;
+  beginRead(): void;
+  commit(): void;
+  rollback(): void;
+}
+
+export class DbTransactionRunner {
+  private depth = 0;
+
+  isInTransaction(): boolean {
+    return this.depth > 0;
+  }
+
+  transaction<T>(controls: DbTransactionControls, fn: () => T): T {
+    if (this.depth > 0) {
+      return this.runNested(fn);
+    }
+
+    controls.begin();
+    this.depth++;
+    try {
+      const result = fn();
+      controls.commit();
+      return result;
+    } catch (err) {
+      controls.rollback();
+      throw err;
+    } finally {
+      this.depth--;
+    }
+  }
+
+  readTransaction<T>(
+    controls: DbTransactionControls,
+    fn: () => T,
+    logRollbackError: (error: Error) => void,
+  ): T {
+    if (this.depth > 0) {
+      return this.runNested(fn);
+    }
+
+    controls.beginRead();
+    this.depth++;
+    try {
+      const result = fn();
+      controls.commit();
+      return result;
+    } catch (err) {
+      try {
+        controls.rollback();
+      } catch (rollbackErr) {
+        logRollbackError(rollbackErr instanceof Error ? rollbackErr : new Error(String(rollbackErr)));
+      }
+      throw err;
+    } finally {
+      this.depth--;
+    }
+  }
+
+  private runNested<T>(fn: () => T): T {
+    this.depth++;
+    try {
+      return fn();
+    } finally {
+      this.depth--;
+    }
+  }
+}
+
+export function createDbTransactionRunner(): DbTransactionRunner {
+  return new DbTransactionRunner();
+}

package/src/resources/extensions/gsd/db-verification-evidence-rows.ts

@@ -0,0 +1,14 @@
+// Project/App: GSD-2
+// File Purpose: Verification evidence row contract for GSD workflow database consumers.
+
+export interface VerificationEvidenceRow {
+  id: number;
+  task_id: string;
+  slice_id: string;
+  milestone_id: string;
+  command: string;
+  exit_code: number | null;
+  verdict: string;
+  duration_ms: number | null;
+  created_at: string;
+}

package/src/resources/extensions/gsd/db-verification-evidence-schema.ts

@@ -0,0 +1,22 @@
+// Project/App: GSD-2
+// File Purpose: Verification evidence SQLite schema helpers for the GSD database facade.
+
+import type { DbAdapter } from "./db-adapter.js";
+import { indexExists } from "./db-schema-metadata.js";
+
+export function dedupeVerificationEvidenceRows(db: DbAdapter): void {
+  db.exec(`
+    DELETE FROM verification_evidence
+    WHERE rowid NOT IN (
+      SELECT MIN(rowid)
+      FROM verification_evidence
+      GROUP BY task_id, slice_id, milestone_id, command, verdict
+    )
+  `);
+}
+
+export function ensureVerificationEvidenceDedupIndex(db: DbAdapter): void {
+  if (indexExists(db, "idx_verification_evidence_dedup")) return;
+  dedupeVerificationEvidenceRows(db);
+  db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_verification_evidence_dedup ON verification_evidence(task_id, slice_id, milestone_id, command, verdict)");
+}

package/src/resources/extensions/gsd/escalation.ts

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Mid-execution escalation artifact and state helpers for GSD tasks.
 // GSD Extension — ADR-011 Phase 2 Mid-Execution Escalation
 //
 // A single module that owns: escalation artifact I/O, detection, resolution,
@@ -19,8 +21,8 @@ import {
   findUnappliedEscalationOverride,
   setTaskBlockerSource,
   listEscalationArtifacts,
-  type TaskRow,
 } from "./gsd-db.js";
+import type { TaskRow } from "./db-task-slice-rows.js";
 import { emitUokAuditEvent, buildAuditEnvelope } from "./uok/audit.js";
 import { logWarning } from "./workflow-logger.js";
 

package/src/resources/extensions/gsd/graph.ts

@@ -31,7 +31,7 @@ export interface GraphStep {
   status: "pending" | "active" | "complete" | "expanded";
   /** The prompt to dispatch for this step. */
   prompt: string;
-  /** IDs of steps that must be "complete" before this step can run. */
+  /** IDs of steps that must be terminal before this step can run. */
   dependsOn: string[];
   /** For iteration instances: ID of the parent step that was expanded. */
   parentStepId?: string;
@@ -152,10 +152,17 @@ export function writeGraph(runDir: string, graph: WorkflowGraph): void {
 }
 
 /**
- * Get the next pending step whose dependencies are all complete.
+ * Return whether a graph step status satisfies dependency edges.
+ */
+export function isTerminalStepStatus(status: GraphStep["status"] | undefined): boolean {
+  return status === "complete" || status === "expanded";
+}
+
+/**
+ * Get the next pending step whose dependencies are all terminal.
  *
  * Returns the first step (in array order) with status "pending" where
- * every step in its `dependsOn` list has status "complete".
+ * every step in its `dependsOn` list has status "complete" or "expanded".
  *
  * @param graph — the workflow graph to query
  * @returns The next dispatchable step, or null if none available
@@ -165,8 +172,8 @@ export function getNextPendingStep(graph: WorkflowGraph): GraphStep | null {
 
   for (const step of graph.steps) {
     if (step.status !== "pending") continue;
-    const depsComplete = step.dependsOn.every(
-      (depId) => statusMap.get(depId) === "complete",
+    const depsComplete = step.dependsOn.every((depId) =>
+      isTerminalStepStatus(statusMap.get(depId)),
     );
     if (depsComplete) return step;
   }