gsd-pi 2.79.0 → 2.80.0-dev.0aaa4fc17

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

@@ -0,0 +1,109 @@
+// Project/App: GSD-2
+// File Purpose: Auto-mode coordination SQLite schema helper for the GSD database facade.
+
+import type { DbAdapter } from "./db-adapter.js";
+
+/**
+ * Create the v24 coordination tables (workers, milestone_leases,
+ * unit_dispatches, cancellation_requests, command_queue) and their indexes.
+ *
+ * Idempotent — uses IF NOT EXISTS throughout. Called from both the
+ * fresh-install path and the v24 migration block in migrateSchema().
+ *
+ * Single-host invariant: these tables coordinate concurrent auto-mode
+ * workers via shared SQLite WAL on local disk only. NFS / network
+ * filesystems break the coordination semantics — multi-host execution
+ * needs a real coordinator (etcd, Postgres) and is out of scope.
+ */
+export function createCoordinationTablesV24(db: DbAdapter): void {
+  const ddl = [
+    `CREATE TABLE IF NOT EXISTS workers (
+      worker_id TEXT PRIMARY KEY,
+      host TEXT NOT NULL,
+      pid INTEGER NOT NULL,
+      started_at TEXT NOT NULL,
+      version TEXT NOT NULL,
+      last_heartbeat_at TEXT NOT NULL,
+      status TEXT NOT NULL,
+      project_root_realpath TEXT NOT NULL
+    )`,
+    `CREATE TABLE IF NOT EXISTS milestone_leases (
+      milestone_id TEXT PRIMARY KEY,
+      worker_id TEXT NOT NULL,
+      fencing_token INTEGER NOT NULL,
+      acquired_at TEXT NOT NULL,
+      expires_at TEXT NOT NULL,
+      status TEXT NOT NULL,
+      FOREIGN KEY (worker_id) REFERENCES workers(worker_id),
+      FOREIGN KEY (milestone_id) REFERENCES milestones(id)
+    )`,
+    `CREATE TABLE IF NOT EXISTS unit_dispatches (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      trace_id TEXT NOT NULL,
+      turn_id TEXT,
+      worker_id TEXT NOT NULL,
+      milestone_lease_token INTEGER NOT NULL,
+      milestone_id TEXT NOT NULL,
+      slice_id TEXT,
+      task_id TEXT,
+      unit_type TEXT NOT NULL,
+      unit_id TEXT NOT NULL,
+      status TEXT NOT NULL,
+      attempt_n INTEGER NOT NULL DEFAULT 1,
+      started_at TEXT NOT NULL,
+      ended_at TEXT,
+      exit_reason TEXT,
+      error_summary TEXT,
+      verification_evidence_id INTEGER,
+      next_run_at TEXT,
+      retry_after_ms INTEGER,
+      max_attempts INTEGER NOT NULL DEFAULT 3,
+      last_error_code TEXT,
+      last_error_at TEXT,
+      FOREIGN KEY (worker_id) REFERENCES workers(worker_id),
+      FOREIGN KEY (verification_evidence_id) REFERENCES verification_evidence(id)
+    )`,
+    `CREATE TABLE IF NOT EXISTS cancellation_requests (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      requested_at TEXT NOT NULL,
+      requested_by TEXT NOT NULL,
+      scope TEXT NOT NULL,
+      scope_id TEXT NOT NULL,
+      dispatch_id INTEGER,
+      reason TEXT NOT NULL,
+      status TEXT NOT NULL,
+      acked_at TEXT,
+      acked_worker_id TEXT,
+      FOREIGN KEY (dispatch_id) REFERENCES unit_dispatches(id),
+      FOREIGN KEY (acked_worker_id) REFERENCES workers(worker_id)
+    )`,
+    `CREATE TABLE IF NOT EXISTS command_queue (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      target_worker TEXT,
+      command TEXT NOT NULL,
+      args_json TEXT NOT NULL DEFAULT '{}',
+      enqueued_at TEXT NOT NULL,
+      claimed_at TEXT,
+      claimed_by TEXT,
+      completed_at TEXT,
+      result_json TEXT
+    )`,
+  ];
+  for (const stmt of ddl) db.exec(stmt);
+
+  // Indexes — created here so both fresh-install and v24-migration paths
+  // produce identical structure.
+  db.exec("CREATE INDEX IF NOT EXISTS idx_unit_dispatches_active ON unit_dispatches(milestone_id, status)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_unit_dispatches_trace ON unit_dispatches(trace_id, turn_id)");
+  // Partial unique index — prevents two workers from claiming the same
+  // unit concurrently. Codex review MEDIUM B2: enforces double-claim guard
+  // at the DB level.
+  db.exec(
+    "CREATE UNIQUE INDEX IF NOT EXISTS idx_unit_dispatches_active_per_unit "
+    + "ON unit_dispatches(unit_id) WHERE status IN ('claimed','running')",
+  );
+  // command_queue index — SQLite indexes NULLs in B-trees, so this single
+  // index serves both targeted (target_worker = ?) and broadcast
+  // (target_worker IS NULL) queries. Codex review LOW B4 documented.
+  db.exec("CREATE INDEX IF NOT EXISTS idx_command_queue_pending ON command_queue(target_worker, claimed_at)");
+}

package/src/resources/extensions/gsd/db-decision-requirement-rows.ts

@@ -0,0 +1,77 @@
+// Project/App: GSD-2
+// File Purpose: Decision and requirement row mappers for the GSD database facade.
+
+import type { Decision, DecisionMadeBy, Requirement, RequirementCounts } from "./types.js";
+
+type DbRow = Record<string, unknown>;
+
+export function rowToDecision(row: DbRow): Decision {
+  return {
+    seq: row["seq"] as number,
+    id: row["id"] as string,
+    when_context: row["when_context"] as string,
+    scope: row["scope"] as string,
+    decision: row["decision"] as string,
+    choice: row["choice"] as string,
+    rationale: row["rationale"] as string,
+    revisable: row["revisable"] as string,
+    made_by: (row["made_by"] as DecisionMadeBy) ?? "agent",
+    source: (row["source"] as string) ?? "discussion",
+    superseded_by: (row["superseded_by"] as string) ?? null,
+  };
+}
+
+export function rowToActiveDecision(row: DbRow): Decision {
+  return {
+    ...rowToDecision(row),
+    superseded_by: null,
+  };
+}
+
+export function rowToRequirement(row: DbRow): Requirement {
+  return {
+    id: row["id"] as string,
+    class: row["class"] as string,
+    status: row["status"] as string,
+    description: row["description"] as string,
+    why: row["why"] as string,
+    source: row["source"] as string,
+    primary_owner: row["primary_owner"] as string,
+    supporting_slices: row["supporting_slices"] as string,
+    validation: row["validation"] as string,
+    notes: row["notes"] as string,
+    full_content: row["full_content"] as string,
+    superseded_by: (row["superseded_by"] as string) ?? null,
+  };
+}
+
+export function rowToActiveRequirement(row: DbRow): Requirement {
+  return {
+    ...rowToRequirement(row),
+    superseded_by: null,
+  };
+}
+
+export function rowsToRequirementCounts(rows: DbRow[]): RequirementCounts {
+  const counts: RequirementCounts = {
+    active: 0,
+    validated: 0,
+    deferred: 0,
+    outOfScope: 0,
+    blocked: 0,
+    total: 0,
+  };
+
+  for (const row of rows) {
+    const status = String(row["status"] ?? "");
+    const count = Number(row["count"] ?? 0);
+    counts.total += count;
+    if (status === "active") counts.active += count;
+    else if (status === "validated") counts.validated += count;
+    else if (status === "deferred") counts.deferred += count;
+    else if (status === "out-of-scope" || status === "out_of_scope") counts.outOfScope += count;
+    else if (status === "blocked") counts.blocked += count;
+  }
+
+  return counts;
+}

package/src/resources/extensions/gsd/db-gate-rows.ts

@@ -0,0 +1,19 @@
+// Project/App: GSD-2
+// File Purpose: Quality gate row mapper for the GSD database facade.
+
+import type { GateId, GateRow, GateScope, GateStatus, GateVerdict } from "./types.js";
+
+export function rowToGate(row: Record<string, unknown>): GateRow {
+  return {
+    milestone_id: row["milestone_id"] as string,
+    slice_id: row["slice_id"] as string,
+    gate_id: row["gate_id"] as GateId,
+    scope: row["scope"] as GateScope,
+    task_id: (row["task_id"] as string) ?? "",
+    status: row["status"] as GateStatus,
+    verdict: row["status"] === "pending" ? null : (row["verdict"] as GateVerdict),
+    rationale: (row["rationale"] as string) || "",
+    findings: (row["findings"] as string) || "",
+    evaluated_at: (row["evaluated_at"] as string) ?? null,
+  };
+}

package/src/resources/extensions/gsd/db-lightweight-query-rows.ts

@@ -0,0 +1,50 @@
+// Project/App: GSD-2
+// File Purpose: Lightweight DB query row mappers for hot-path status reads.
+
+type DbRow = Record<string, unknown>;
+
+export interface IdStatusSummary {
+  id: string;
+  status: string;
+}
+
+export interface ActiveTaskSummary extends IdStatusSummary {
+  title: string;
+}
+
+export interface TaskStatusCounts {
+  total: number;
+  done: number;
+  pending: number;
+}
+
+export function rowToIdStatusSummary(row: DbRow): IdStatusSummary {
+  return {
+    id: row["id"] as string,
+    status: row["status"] as string,
+  };
+}
+
+export function rowToActiveTaskSummary(row: DbRow): ActiveTaskSummary {
+  return {
+    ...rowToIdStatusSummary(row),
+    title: row["title"] as string,
+  };
+}
+
+export function rowToTaskStatusCounts(row: DbRow | undefined): TaskStatusCounts {
+  if (!row) return emptyTaskStatusCounts();
+  return {
+    total: (row["total"] as number) ?? 0,
+    done: (row["done"] as number) ?? 0,
+    pending: (row["pending"] as number) ?? 0,
+  };
+}
+
+export function emptyTaskStatusCounts(): TaskStatusCounts {
+  return { total: 0, done: 0, pending: 0 };
+}
+
+export function rowsToStringColumn(rows: DbRow[], column: string): string[] {
+  return rows.map((row) => row[column] as string);
+}

package/src/resources/extensions/gsd/db-memory-fts-schema.ts

@@ -0,0 +1,66 @@
+// Project/App: GSD-2
+// File Purpose: Memory FTS5 SQLite schema helpers for the GSD database facade.
+
+import type { DbAdapter } from "./db-adapter.js";
+
+export interface MemoryFtsSchemaOptions {
+  onUnavailable?: (message: string) => void;
+}
+
+function formatFtsUnavailableError(err: unknown): string {
+  const message = err instanceof Error ? err.message : String(err);
+  return message.replace(/\bmoduel\s*:\s*/gi, "module: ");
+}
+
+/**
+ * Create the FTS5 virtual table for memories plus the triggers that keep it
+ * in sync with the base table. FTS5 may be unavailable on stripped-down
+ * SQLite builds — callers should treat failure as non-fatal and fall back
+ * to LIKE-based scans in `memory-store.queryMemoriesRanked`.
+ */
+export function tryCreateMemoriesFtsSchema(
+  db: DbAdapter,
+  options: MemoryFtsSchemaOptions = {},
+): boolean {
+  try {
+    db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts
+      USING fts5(content, content='memories', content_rowid='seq', tokenize='porter unicode61')
+    `);
+    // Triggers mirror inserts / updates / deletes on the base memories table.
+    db.exec(`
+      CREATE TRIGGER IF NOT EXISTS memories_ai
+      AFTER INSERT ON memories BEGIN
+        INSERT INTO memories_fts(rowid, content) VALUES (new.seq, new.content);
+      END
+    `);
+    db.exec(`
+      CREATE TRIGGER IF NOT EXISTS memories_ad
+      AFTER DELETE ON memories BEGIN
+        INSERT INTO memories_fts(memories_fts, rowid, content) VALUES ('delete', old.seq, old.content);
+      END
+    `);
+    db.exec(`
+      CREATE TRIGGER IF NOT EXISTS memories_au
+      AFTER UPDATE OF content ON memories BEGIN
+        INSERT INTO memories_fts(memories_fts, rowid, content) VALUES ('delete', old.seq, old.content);
+        INSERT INTO memories_fts(rowid, content) VALUES (new.seq, new.content);
+      END
+    `);
+    return true;
+  } catch (err) {
+    options.onUnavailable?.(`FTS5 unavailable — memory queries will use LIKE fallback: ${formatFtsUnavailableError(err)}`);
+    return false;
+  }
+}
+
+export function isMemoriesFtsAvailableSchema(db: DbAdapter): boolean {
+  try {
+    const row = db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='memories_fts'")
+      .get();
+    return !!row;
+  } catch {
+    return false;
+  }
+}

package/src/resources/extensions/gsd/db-migration-backup.ts

@@ -0,0 +1,34 @@
+// Project/App: GSD-2
+// File Purpose: Pre-migration backup helper for GSD database schema upgrades.
+
+import type { DbAdapter } from "./db-adapter.js";
+
+export interface MigrationBackupDeps {
+  existsSync(path: string): boolean;
+  copyFileSync(src: string, dest: string): void;
+  logWarning(scope: string, message: string): void;
+}
+
+export function backupDatabaseBeforeMigration(
+  db: DbAdapter,
+  dbPath: string | null,
+  currentVersion: number,
+  deps: MigrationBackupDeps,
+): void {
+  if (!dbPath || dbPath === ":memory:" || !deps.existsSync(dbPath)) return;
+
+  try {
+    const backupPath = `${dbPath}.backup-v${currentVersion}`;
+    if (deps.existsSync(backupPath)) return;
+
+    try {
+      db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+    } catch {
+      // Checkpoint is best effort; copying the base file is still better than no backup.
+    }
+    deps.copyFileSync(dbPath, backupPath);
+  } catch (backupErr) {
+    const message = backupErr instanceof Error ? backupErr.message : String(backupErr);
+    deps.logWarning("db", `Pre-migration backup failed: ${message}`);
+  }
+}