@opengsd/gsd-pi 1.2.0-dev.fb12b103 → 1.2.0-dev.fbdca60b

package/src/resources/extensions/gsd/db/queries.ts

@@ -5,6 +5,7 @@
 // Read-only callers (forensics, dashboard, doctor) depend on this seam, not on
 // the single-writer surface.
 import { getDbOrNull } from "./engine.js";
+import { isClosedStatus } from "../status-guards.js";
 import { getGateIdsForTurn, type OwnerTurn } from "../gate-registry.js";
 import type { Decision, Requirement, GateRow, GateScope } from "../types.js";
 import {
@@ -269,6 +270,71 @@ export function getMilestoneSlices(milestoneId: string): SliceRow[] {
   return rows.map(rowToSlice);
 }
 
+/**
+ * Load slices for many milestones in a single query. Returns a Map keyed by
+ * milestone_id, preserving `ORDER BY sequence, id` within each bucket.
+ */
+export function getSlicesByMilestoneIds(milestoneIds: readonly string[]): Map<string, SliceRow[]> {
+  const db = getDbOrNull();
+  if (!db || milestoneIds.length === 0) return new Map();
+  const idList = [...milestoneIds];
+  const placeholders = idList.map((_, i) => `:mid${i}`).join(",");
+  const params: Record<string, unknown> = {};
+  idList.forEach((id, i) => {
+    params[`:mid${i}`] = id;
+  });
+  const rows = db
+    .prepare(`SELECT * FROM slices WHERE milestone_id IN (${placeholders}) ORDER BY milestone_id, sequence, id`)
+    .all(params) as Record<string, unknown>[];
+  const byMilestone = new Map<string, SliceRow[]>();
+  for (const row of rows) {
+    const slice = rowToSlice(row);
+    const bucket = byMilestone.get(slice.milestone_id);
+    if (bucket) {
+      bucket.push(slice);
+    } else {
+      byMilestone.set(slice.milestone_id, [slice]);
+    }
+  }
+  return byMilestone;
+}
+
+/** Dispatch-eligibility shape consumed by decision-path callers (ADR-017). */
+export interface MilestoneSliceSummary {
+  id: string;
+  title: string;
+  /** Closed per the canonical status vocabulary (complete/done/skipped/closed). */
+  done: boolean;
+  depends: string[];
+}
+
+/**
+ * Consolidated DB read for dispatch/gate/completion decisions (ADR-017).
+ * `done` uses the canonical closed-status predicate (`isClosedStatus`) — the
+ * same vocabulary the SQL terminal-status fragment derives from. Decision
+ * paths must consume this instead of parsing `.gsd/*.md` projections.
+ * Rows keep `getMilestoneSlices` ordering (sequence, then id).
+ */
+export function getMilestoneSliceSummaries(milestoneId: string): MilestoneSliceSummary[] {
+  return getMilestoneSlices(milestoneId).map((s) => ({
+    id: s.id,
+    title: s.title,
+    done: isClosedStatus(s.status),
+    depends: s.depends ?? [],
+  }));
+}
+
+/**
+ * Ids of slices closed per the canonical status vocabulary (ADR-017), in
+ * milestone order. Thin wrapper over `getMilestoneSliceSummaries` for the
+ * common "which slices are done?" decision-path read.
+ */
+export function getClosedSliceIds(milestoneId: string): string[] {
+  return getMilestoneSliceSummaries(milestoneId)
+    .filter((s) => s.done)
+    .map((s) => s.id);
+}
+
 export function getArtifact(path: string): ArtifactRow | null {
   if (!getDbOrNull()!) return null;
   const row = getDbOrNull()!.prepare("SELECT * FROM artifacts WHERE path = :path").get({ ":path": path });

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

@@ -9,6 +9,26 @@ export interface MigrationBackupDeps {
   logWarning(scope: string, message: string): void;
 }
 
+/** Marks pre-migration backup failures so DB-open recovery cannot mask them. */
+export class MigrationBackupError extends Error {
+  constructor(message: string, cause?: unknown) {
+    super(message, { cause });
+    this.name = "MigrationBackupError";
+  }
+}
+
+/** Returns true for errors raised while checkpointing or copying a migration backup. */
+export function isMigrationBackupError(err: unknown): err is MigrationBackupError {
+  return err instanceof MigrationBackupError;
+}
+
+/**
+ * Creates a same-version backup before file-backed schema migrations.
+ *
+ * Existing same-version backups are reused. New backups fail closed: WAL
+ * checkpoint failures, incomplete checkpoints, and copy failures are logged
+ * and then rethrown before migration DDL runs.
+ */
 export function backupDatabaseBeforeMigration(
   db: DbAdapter,
   dbPath: string | null,
@@ -21,14 +41,43 @@ export function backupDatabaseBeforeMigration(
     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.
-    }
+    checkpointWal(db);
     deps.copyFileSync(dbPath, backupPath);
   } catch (backupErr) {
-    const message = backupErr instanceof Error ? backupErr.message : String(backupErr);
-    deps.logWarning("db", `Pre-migration backup failed: ${message}`);
+    const error = toMigrationBackupError(backupErr);
+    deps.logWarning("db", `Pre-migration backup failed: ${error.message}`);
+    throw error;
+  }
+}
+
+function checkpointWal(db: DbAdapter): void {
+  const row = db.prepare("PRAGMA wal_checkpoint(TRUNCATE)").get();
+  if (!isCheckpointComplete(row)) {
+    const busy = formatCheckpointValue(row, "busy");
+    const log = formatCheckpointValue(row, "log");
+    const checkpointed = formatCheckpointValue(row, "checkpointed");
+    throw new MigrationBackupError(
+      `WAL checkpoint incomplete: busy=${busy} log=${log} checkpointed=${checkpointed}`,
+    );
   }
 }
+
+function isCheckpointComplete(row: Record<string, unknown> | undefined): boolean {
+  if (!row) return false;
+  const busy = Number(row["busy"]);
+  const log = Number(row["log"]);
+  const checkpointed = Number(row["checkpointed"]);
+  if (!Number.isFinite(busy) || !Number.isFinite(log) || !Number.isFinite(checkpointed)) return false;
+  return busy === 0 && log === checkpointed;
+}
+
+function formatCheckpointValue(row: Record<string, unknown> | undefined, key: string): string {
+  const value = row?.[key];
+  return value === undefined ? "unknown" : String(value);
+}
+
+function toMigrationBackupError(err: unknown): MigrationBackupError {
+  if (isMigrationBackupError(err)) return err;
+  const message = err instanceof Error ? err.message : String(err);
+  return new MigrationBackupError(message, err);
+}

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

@@ -4,6 +4,8 @@
 export interface DbTransactionControls {
   begin(): void;
   beginRead(): void;
+  /** Starts a write transaction that obtains SQLite's reserved lock up front. */
+  beginImmediate?(): void;
   commit(): void;
   rollback(): void;
 }
@@ -16,45 +18,47 @@ export class DbTransactionRunner {
   }
 
   transaction<T>(controls: DbTransactionControls, fn: () => T): T {
-    if (this.depth > 0) {
-      return this.runNested(fn);
-    }
+    return this.runTransaction(controls, () => controls.begin(), fn);
+  }
 
-    controls.begin();
-    this.depth++;
-    try {
-      const result = fn();
-      controls.commit();
-      return result;
-    } catch (err) {
-      controls.rollback();
-      throw err;
-    } finally {
-      this.depth--;
+  /**
+   * Run a BEGIN IMMEDIATE transaction through the same depth counter as regular
+   * transactions so callers can compose it inside existing transaction scopes.
+   */
+  immediateTransaction<T>(controls: DbTransactionControls, fn: () => T): T {
+    if (!controls.beginImmediate) {
+      throw new Error("db transaction controls do not support immediate transactions");
     }
+
+    return this.runTransaction(controls, () => controls.beginImmediate!(), fn);
   }
 
   readTransaction<T>(
     controls: DbTransactionControls,
     fn: () => T,
     logRollbackError: (error: Error) => void,
+  ): T {
+    return this.runTransaction(controls, () => controls.beginRead(), fn, logRollbackError);
+  }
+
+  private runTransaction<T>(
+    controls: DbTransactionControls,
+    begin: () => void,
+    fn: () => T,
+    logRollbackError?: (error: Error) => void,
   ): T {
     if (this.depth > 0) {
       return this.runNested(fn);
     }
 
-    controls.beginRead();
+    begin();
     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)));
-      }
+      this.rollback(controls, logRollbackError);
       throw err;
     } finally {
       this.depth--;
@@ -69,6 +73,19 @@ export class DbTransactionRunner {
       this.depth--;
     }
   }
+
+  private rollback(controls: DbTransactionControls, logRollbackError?: (error: Error) => void): void {
+    if (!logRollbackError) {
+      controls.rollback();
+      return;
+    }
+
+    try {
+      controls.rollback();
+    } catch (rollbackErr) {
+      logRollbackError(rollbackErr instanceof Error ? rollbackErr : new Error(String(rollbackErr)));
+    }
+  }
 }
 
 export function createDbTransactionRunner(): DbTransactionRunner {

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

@@ -714,31 +714,23 @@ async function mirrorDecisionToMemory(
 /**
  * Extract a milestone/slice reference from a deferral decision.
  *
- * Detects deferrals by checking:
- *   - scope contains "defer" (e.g., "deferral", "defer")
- *   - choice or decision contains "defer" + an M###/S## pattern
+ * Detects deferrals when the slice reference is part of the deferral phrase.
  *
  * Returns { milestoneId, sliceId } if found, null otherwise.
  */
 export function extractDeferredSliceRef(
   fields: Pick<SaveDecisionFields, 'scope' | 'decision' | 'choice'>,
 ): { milestoneId: string; sliceId: string } | null {
-  const isDeferral =
-    /\bdefer(?:ral|red|ring|s)?\b/i.test(fields.scope) ||
-    /\bdefer(?:ral|red|ring|s)?\b/i.test(fields.choice) ||
-    /\bdefer(?:ral|red|ring|s)?\b/i.test(fields.decision);
-
-  if (!isDeferral) return null;
-
-  // Look for M###/S## pattern in choice first, then decision
-  const slicePattern = /\b(M\d{3,4})\/(S\d{2,3})\b/;
-  const choiceMatch = fields.choice.match(slicePattern);
-  if (choiceMatch) {
-    return { milestoneId: choiceMatch[1], sliceId: choiceMatch[2] };
-  }
-  const decisionMatch = fields.decision.match(slicePattern);
-  if (decisionMatch) {
-    return { milestoneId: decisionMatch[1], sliceId: decisionMatch[2] };
+  const defersSlicePattern =
+    /\bdefer(?:ral|red|ring|s)?\b\s+(?:(?:of|the)\s+)*(?:slice\s+)?\b(M\d{3,4})\/(S\d{2,3})\b/i;
+  const sliceIsDeferredPattern =
+    /\b(M\d{3,4})\/(S\d{2,3})\b\s+(?:is|was|will be|should be|can be)\s+defer(?:red|ring)?\b/i;
+
+  for (const text of [fields.choice, fields.decision, fields.scope]) {
+    const match = text.match(defersSlicePattern) ?? text.match(sliceIsDeferredPattern);
+    if (match) {
+      return { milestoneId: match[1], sliceId: match[2] };
+    }
   }
 
   return null;

package/src/resources/extensions/gsd/dispatch-guard.ts

@@ -3,9 +3,8 @@
 import { resolveMilestoneFile } from "./paths.js";
 import { findMilestoneIds } from "./guided-flow.js";
 import { parseUnitId } from "./unit-id.js";
-import { isDbAvailable, getMilestoneSlices, getMilestone } from "./gsd-db.js";
-import { parseRoadmap } from "./parsers-legacy.js";
-import { isClosedStatus, isSkippedForDispatch } from "./status-guards.js";
+import { isDbAvailable, getMilestoneSliceSummaries, getMilestone } from "./gsd-db.js";
+import { isSkippedForDispatch } from "./status-guards.js";
 import { classifyMilestoneSummaryContent } from "./milestone-summary-classifier.js";
 import { readFileSync } from "node:fs";
 import type { LoopState } from "./auto/types.js";
@@ -117,34 +116,12 @@ export function getPriorSliceCompletionBlocker(
       }
     }
 
-    // Normalised slice list from DB or file fallback
-    type NormSlice = { id: string; done: boolean; depends: string[] };
-    let slices: NormSlice[] | null = null;
-
-    if (isDbAvailable()) {
-      const rows = getMilestoneSlices(mid);
-      if (rows.length > 0) {
-        slices = rows.map((r) => ({
-          id: r.id,
-          done: isClosedStatus(r.status),
-          depends: r.depends ?? [],
-        }));
-      }
-    }
-    if (!slices) {
-      // File-based fallback: parse roadmap checkboxes
-      const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
-      if (!roadmapPath) continue;
-      let roadmapContent: string;
-      try { roadmapContent = readFileSync(roadmapPath, "utf-8"); } catch { continue; }
-      const parsed = parseRoadmap(roadmapContent);
-      if (parsed.slices.length === 0) continue;
-      slices = parsed.slices.map((s) => ({
-        id: s.id,
-        done: s.done,
-        depends: s.depends ?? [],
-      }));
-    }
+    // DB-authoritative eligibility list (ADR-017) — markdown projections are
+    // never parsed for dispatch decisions. No DB / no rows → skip this
+    // milestone's check (unknown is not a blocker).
+    if (!isDbAvailable()) continue;
+    const slices = getMilestoneSliceSummaries(mid);
+    if (slices.length === 0) continue;
 
     if (mid !== targetMid) {
       const incomplete = slices.find((slice) => !slice.done);

package/src/resources/extensions/gsd/doctor-engine-checks.ts

@@ -6,8 +6,9 @@ import { isDbAvailable, _getAdapter } from "./gsd-db.js";
 import { isAfter, latestExplicitReopenAt } from "./milestone-reopen-events.js";
 import { resolveGsdPathContract, resolveMilestoneFile } from "./paths.js";
 import { deriveState } from "./state.js";
+import { workflowEventLogPath } from "./workflow-event-ledger.js";
 import { readEvents } from "./workflow-events.js";
-import { renderAllProjections } from "./workflow-projections.js";
+import { flushWorkflowProjections } from "./projection-flush.js";
 
 export async function checkEngineHealth(
   basePath: string,
@@ -260,7 +261,7 @@ export async function checkEngineHealth(
   // relative to the event log and re-render them.
   try {
     if (isDbAvailable()) {
-      const eventLogPath = join(basePath, ".gsd", "event-log.jsonl");
+      const eventLogPath = workflowEventLogPath(basePath);
       const events = readEvents(eventLogPath);
       if (events.length > 0) {
         const lastEventTs = new Date(events[events.length - 1]!.ts).getTime();
@@ -270,7 +271,7 @@ export async function checkEngineHealth(
           const roadmapPath = resolveMilestoneFile(basePath, milestone.id, "ROADMAP");
           if (!roadmapPath || !existsSync(roadmapPath)) {
             try {
-              await renderAllProjections(basePath, milestone.id);
+              await flushWorkflowProjections(basePath, { milestoneId: milestone.id });
               fixesApplied.push(`re-rendered missing projections for ${milestone.id}`);
             } catch {
               // Non-fatal — projection re-render failed
@@ -280,7 +281,7 @@ export async function checkEngineHealth(
           const projectionMtime = statSync(roadmapPath).mtimeMs;
           if (lastEventTs > projectionMtime) {
             try {
-              await renderAllProjections(basePath, milestone.id);
+              await flushWorkflowProjections(basePath, { milestoneId: milestone.id });
               fixesApplied.push(`re-rendered stale projections for ${milestone.id}`);
             } catch {
               // Non-fatal — projection re-render failed