gsd-pi 2.37.1-dev.193bd3d → 2.37.1-dev.49503be

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

@@ -0,0 +1,289 @@
+/**
+ * Reactive Task Graph — derives dependency edges from task plan IO signatures.
+ *
+ * Pure functions that build a DAG from task IO intersections and resolve
+ * which tasks are currently ready for parallel dispatch. Used by the
+ * reactive-execute dispatch path (ADR-004).
+ *
+ * Graph derivation and resolution functions are pure (no filesystem access).
+ * The `loadSliceTaskIO` loader at the bottom is the only async/IO function.
+ */
+
+import type { TaskIO, DerivedTaskNode, ReactiveExecutionState } from "./types.js";
+import { loadFile, parsePlan, parseTaskPlanIO } from "./files.js";
+import { resolveTasksDir, resolveTaskFiles } from "./paths.js";
+import { join } from "node:path";
+import { loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
+import { existsSync, unlinkSync } from "node:fs";
+
+// ─── Graph Construction ───────────────────────────────────────────────────
+
+/**
+ * Build a dependency graph from task IO signatures.
+ *
+ * A task T_b depends on T_a when any of T_b's inputFiles appear in T_a's
+ * outputFiles. Self-references are excluded.
+ *
+ * Tasks are returned in the same order as the input array.
+ */
+export function deriveTaskGraph(tasks: TaskIO[]): DerivedTaskNode[] {
+  // Build output → producer lookup
+  const outputToProducer = new Map<string, string[]>();
+  for (const task of tasks) {
+    for (const outFile of task.outputFiles) {
+      const existing = outputToProducer.get(outFile);
+      if (existing) {
+        existing.push(task.id);
+      } else {
+        outputToProducer.set(outFile, [task.id]);
+      }
+    }
+  }
+
+  return tasks.map((task) => {
+    const deps = new Set<string>();
+    for (const inFile of task.inputFiles) {
+      const producers = outputToProducer.get(inFile);
+      if (producers) {
+        for (const pid of producers) {
+          if (pid !== task.id) deps.add(pid);
+        }
+      }
+    }
+    return {
+      ...task,
+      dependsOn: [...deps].sort(),
+    };
+  });
+}
+
+// ─── Ready Set Resolution ─────────────────────────────────────────────────
+
+/**
+ * Return task IDs whose dependencies are all in `completed`.
+ * Excludes tasks that are already done or in-flight.
+ */
+export function getReadyTasks(
+  graph: DerivedTaskNode[],
+  completed: Set<string>,
+  inFlight: Set<string>,
+): string[] {
+  return graph
+    .filter((node) => {
+      if (node.done || completed.has(node.id) || inFlight.has(node.id)) return false;
+      return node.dependsOn.every((dep) => completed.has(dep));
+    })
+    .map((node) => node.id);
+}
+
+// ─── Conflict-Free Subset Selection ──────────────────────────────────────
+
+/**
+ * Greedy selection of non-conflicting tasks up to `maxParallel`.
+ *
+ * Two tasks conflict if they share any outputFile. We also exclude tasks
+ * whose outputs overlap with `inFlightOutputs` (files being written by
+ * tasks currently in progress).
+ */
+export function chooseNonConflictingSubset(
+  readyIds: string[],
+  graph: DerivedTaskNode[],
+  maxParallel: number,
+  inFlightOutputs: Set<string>,
+): string[] {
+  const nodeMap = new Map(graph.map((n) => [n.id, n]));
+  const claimed = new Set(inFlightOutputs);
+  const selected: string[] = [];
+
+  for (const id of readyIds) {
+    if (selected.length >= maxParallel) break;
+    const node = nodeMap.get(id);
+    if (!node) continue;
+
+    // Check for output overlap with already-selected or in-flight
+    const conflicts = node.outputFiles.some((f) => claimed.has(f));
+    if (conflicts) continue;
+
+    // Claim this task's outputs
+    for (const f of node.outputFiles) claimed.add(f);
+    selected.push(id);
+  }
+
+  return selected;
+}
+
+// ─── Graph Quality Checks ─────────────────────────────────────────────────
+
+/**
+ * Returns true if any incomplete task has 0 inputFiles AND 0 outputFiles.
+ *
+ * An ambiguous graph means IO annotations are too sparse to derive reliable
+ * edges — the dispatcher should fall back to sequential execution.
+ */
+export function isGraphAmbiguous(graph: DerivedTaskNode[]): boolean {
+  return graph.some(
+    (node) =>
+      !node.done &&
+      node.inputFiles.length === 0 &&
+      node.outputFiles.length === 0,
+  );
+}
+
+/**
+ * Detect deadlock: no tasks are ready and none are in-flight, yet incomplete
+ * tasks remain. This indicates a circular dependency or impossible state.
+ */
+export function detectDeadlock(
+  graph: DerivedTaskNode[],
+  completed: Set<string>,
+  inFlight: Set<string>,
+): boolean {
+  const incomplete = graph.filter(
+    (n) => !n.done && !completed.has(n.id) && !inFlight.has(n.id),
+  );
+  if (incomplete.length === 0) return false; // all done
+  if (inFlight.size > 0) return false; // something is running, wait for it
+
+  // Nothing in flight, but incomplete tasks remain — check if any are ready
+  const ready = getReadyTasks(graph, completed, inFlight);
+  return ready.length === 0;
+}
+
+// ─── Graph Metrics ────────────────────────────────────────────────────────
+
+/** Compute summary metrics for logging. */
+export function graphMetrics(graph: DerivedTaskNode[]): {
+  taskCount: number;
+  edgeCount: number;
+  readySetSize: number;
+  ambiguous: boolean;
+} {
+  const completed = new Set(graph.filter((n) => n.done).map((n) => n.id));
+  const ready = getReadyTasks(graph, completed, new Set());
+  const edgeCount = graph.reduce((sum, n) => sum + n.dependsOn.length, 0);
+
+  return {
+    taskCount: graph.length,
+    edgeCount,
+    readySetSize: ready.length,
+    ambiguous: isGraphAmbiguous(graph),
+  };
+}
+
+// ─── IO Loader (async, filesystem) ────────────────────────────────────────
+
+/**
+ * Load TaskIO for all tasks in a slice by reading the slice plan (for done
+ * status and task IDs) and individual task plan files (for IO sections).
+ *
+ * Returns [] when the slice plan or tasks directory doesn't exist.
+ */
+export async function loadSliceTaskIO(
+  basePath: string,
+  mid: string,
+  sid: string,
+): Promise<TaskIO[]> {
+  const { resolveSliceFile } = await import("./paths.js");
+  const slicePlanPath = resolveSliceFile(basePath, mid, sid, "PLAN");
+  const planContent = slicePlanPath ? await loadFile(slicePlanPath) : null;
+  if (!planContent) return [];
+
+  const plan = parsePlan(planContent);
+  const tDir = resolveTasksDir(basePath, mid, sid);
+  if (!tDir) return [];
+
+  const results: TaskIO[] = [];
+
+  for (const taskEntry of plan.tasks) {
+    const planFiles = resolveTaskFiles(tDir, "PLAN");
+    const taskFileName = planFiles.find((f) =>
+      f.toUpperCase().startsWith(taskEntry.id.toUpperCase() + "-"),
+    );
+    if (!taskFileName) {
+      // Task plan file missing — include with empty IO (will trigger ambiguous)
+      results.push({
+        id: taskEntry.id,
+        title: taskEntry.title,
+        inputFiles: [],
+        outputFiles: [],
+        done: taskEntry.done,
+      });
+      continue;
+    }
+
+    const taskContent = await loadFile(join(tDir, taskFileName));
+    if (!taskContent) {
+      results.push({
+        id: taskEntry.id,
+        title: taskEntry.title,
+        inputFiles: [],
+        outputFiles: [],
+        done: taskEntry.done,
+      });
+      continue;
+    }
+
+    const io = parseTaskPlanIO(taskContent);
+    results.push({
+      id: taskEntry.id,
+      title: taskEntry.title,
+      inputFiles: io.inputFiles,
+      outputFiles: io.outputFiles,
+      done: taskEntry.done,
+    });
+  }
+
+  return results;
+}
+
+// ─── State Persistence ────────────────────────────────────────────────────
+
+function reactiveStatePath(basePath: string, mid: string, sid: string): string {
+  return join(basePath, ".gsd", "runtime", `${mid}-${sid}-reactive.json`);
+}
+
+function isReactiveState(data: unknown): data is ReactiveExecutionState {
+  if (!data || typeof data !== "object") return false;
+  const d = data as Record<string, unknown>;
+  return typeof d.sliceId === "string" && Array.isArray(d.completed);
+}
+
+/**
+ * Load persisted reactive execution state for a slice.
+ * Returns null when no state file exists or the file is invalid.
+ */
+export function loadReactiveState(
+  basePath: string,
+  mid: string,
+  sid: string,
+): ReactiveExecutionState | null {
+  return loadJsonFileOrNull(reactiveStatePath(basePath, mid, sid), isReactiveState);
+}
+
+/**
+ * Save reactive execution state to disk.
+ */
+export function saveReactiveState(
+  basePath: string,
+  mid: string,
+  sid: string,
+  state: ReactiveExecutionState,
+): void {
+  saveJsonFile(reactiveStatePath(basePath, mid, sid), state);
+}
+
+/**
+ * Remove the reactive state file when a slice completes.
+ */
+export function clearReactiveState(
+  basePath: string,
+  mid: string,
+  sid: string,
+): void {
+  const path = reactiveStatePath(basePath, mid, sid);
+  try {
+    if (existsSync(path)) unlinkSync(path);
+  } catch {
+    // Non-fatal
+  }
+}

package/src/resources/extensions/gsd/tests/reactive-executor.test.ts

@@ -0,0 +1,367 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  loadSliceTaskIO,
+  deriveTaskGraph,
+  isGraphAmbiguous,
+  getReadyTasks,
+  chooseNonConflictingSubset,
+  loadReactiveState,
+  saveReactiveState,
+  clearReactiveState,
+} from "../reactive-graph.ts";
+import { validatePreferences } from "../preferences-validation.ts";
+import type { ReactiveExecutionState } from "../types.ts";
+
+// ─── Preference Validation ────────────────────────────────────────────────
+
+test("reactive_execution validation accepts valid config", () => {
+  const result = validatePreferences({
+    reactive_execution: {
+      enabled: true,
+      max_parallel: 4,
+      isolation_mode: "same-tree",
+    },
+  });
+  assert.equal(result.errors.length, 0);
+  assert.deepEqual(result.preferences.reactive_execution, {
+    enabled: true,
+    max_parallel: 4,
+    isolation_mode: "same-tree",
+  });
+});
+
+test("reactive_execution validation rejects max_parallel out of range", () => {
+  const result = validatePreferences({
+    reactive_execution: {
+      enabled: true,
+      max_parallel: 10,
+      isolation_mode: "same-tree",
+    } as any,
+  });
+  assert.ok(result.errors.some((e) => e.includes("max_parallel")));
+});
+
+test("reactive_execution validation rejects invalid isolation_mode", () => {
+  const result = validatePreferences({
+    reactive_execution: {
+      enabled: true,
+      max_parallel: 2,
+      isolation_mode: "separate-branch",
+    } as any,
+  });
+  assert.ok(result.errors.some((e) => e.includes("isolation_mode")));
+});
+
+test("reactive_execution validation warns on unknown keys", () => {
+  const result = validatePreferences({
+    reactive_execution: {
+      enabled: true,
+      max_parallel: 2,
+      isolation_mode: "same-tree",
+      unknown_thing: true,
+    } as any,
+  });
+  assert.equal(result.errors.length, 0);
+  assert.ok(result.warnings.some((w) => w.includes("unknown_thing")));
+});
+
+// ─── Dispatch Rule Matching Logic ─────────────────────────────────────────
+
+test("reactive dispatch requires enabled config and multiple ready tasks", async () => {
+  // Build a minimal filesystem with a slice plan and task plans
+  const repo = mkdtempSync(join(tmpdir(), "gsd-reactive-dispatch-"));
+  try {
+    const gsd = join(repo, ".gsd", "milestones", "M001", "slices", "S01");
+    mkdirSync(join(gsd, "tasks"), { recursive: true });
+
+    // Slice plan with 3 tasks
+    writeFileSync(
+      join(gsd, "S01-PLAN.md"),
+      [
+        "# S01: Test Slice",
+        "",
+        "**Goal:** Test reactive execution",
+        "**Demo:** All three tasks run in parallel",
+        "",
+        "## Tasks",
+        "",
+        "- [ ] **T01: First** `est:15m`",
+        "  Create initial types",
+        "- [ ] **T02: Second** `est:15m`",
+        "  Create models",
+        "- [ ] **T03: Third** `est:15m`",
+        "  Create service layer",
+        "",
+      ].join("\n"),
+    );
+
+    // Task plans with non-overlapping IO (all independent)
+    writeFileSync(
+      join(gsd, "tasks", "T01-PLAN.md"),
+      [
+        "# T01: First",
+        "",
+        "## Description",
+        "Create types.",
+        "",
+        "## Inputs",
+        "",
+        "- `src/config.json` — Config schema",
+        "",
+        "## Expected Output",
+        "",
+        "- `src/types.ts` — Type definitions",
+      ].join("\n"),
+    );
+
+    writeFileSync(
+      join(gsd, "tasks", "T02-PLAN.md"),
+      [
+        "# T02: Second",
+        "",
+        "## Description",
+        "Create models.",
+        "",
+        "## Inputs",
+        "",
+        "- `src/schema.json` — Schema file",
+        "",
+        "## Expected Output",
+        "",
+        "- `src/models.ts` — Model definitions",
+      ].join("\n"),
+    );
+
+    writeFileSync(
+      join(gsd, "tasks", "T03-PLAN.md"),
+      [
+        "# T03: Third",
+        "",
+        "## Description",
+        "Create service.",
+        "",
+        "## Inputs",
+        "",
+        "- `src/api.json` — API spec",
+        "",
+        "## Expected Output",
+        "",
+        "- `src/service.ts` — Service layer",
+      ].join("\n"),
+    );
+
+    // Load IO and build graph
+    const basePath = repo;
+    const taskIO = await loadSliceTaskIO(basePath, "M001", "S01");
+    assert.equal(taskIO.length, 3);
+
+    const graph = deriveTaskGraph(taskIO);
+    assert.equal(isGraphAmbiguous(graph), false, "Graph should not be ambiguous");
+
+    // All independent → all should be ready
+    const ready = getReadyTasks(graph, new Set(), new Set());
+    assert.equal(ready.length, 3);
+
+    // Choose subset with max_parallel=2
+    const selected = chooseNonConflictingSubset(ready, graph, 2, new Set());
+    assert.equal(selected.length, 2);
+    assert.deepEqual(selected, ["T01", "T02"]);
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+  }
+});
+
+test("reactive dispatch falls back when graph is ambiguous (task without IO)", async () => {
+  const repo = mkdtempSync(join(tmpdir(), "gsd-reactive-ambiguous-"));
+  try {
+    const gsd = join(repo, ".gsd", "milestones", "M001", "slices", "S01");
+    mkdirSync(join(gsd, "tasks"), { recursive: true });
+
+    writeFileSync(
+      join(gsd, "S01-PLAN.md"),
+      [
+        "# S01: Test",
+        "",
+        "**Goal:** Test",
+        "**Demo:** Test",
+        "",
+        "## Tasks",
+        "",
+        "- [ ] **T01: A** `est:15m`",
+        "- [ ] **T02: B** `est:15m`",
+        "",
+      ].join("\n"),
+    );
+
+    // T01 has IO, T02 has NO IO sections → ambiguous
+    writeFileSync(
+      join(gsd, "tasks", "T01-PLAN.md"),
+      "# T01: A\n\n## Inputs\n\n- `src/a.ts`\n\n## Expected Output\n\n- `src/b.ts`\n",
+    );
+    writeFileSync(
+      join(gsd, "tasks", "T02-PLAN.md"),
+      "# T02: B\n\n## Description\n\nNo IO sections.\n",
+    );
+
+    const taskIO = await loadSliceTaskIO(repo, "M001", "S01");
+    const graph = deriveTaskGraph(taskIO);
+    assert.equal(isGraphAmbiguous(graph), true, "Graph should be ambiguous");
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+  }
+});
+
+test("single ready task falls through to sequential", async () => {
+  const repo = mkdtempSync(join(tmpdir(), "gsd-reactive-single-"));
+  try {
+    const gsd = join(repo, ".gsd", "milestones", "M001", "slices", "S01");
+    mkdirSync(join(gsd, "tasks"), { recursive: true });
+
+    writeFileSync(
+      join(gsd, "S01-PLAN.md"),
+      [
+        "# S01: Linear",
+        "",
+        "**Goal:** Linear chain",
+        "**Demo:** Sequential",
+        "",
+        "## Tasks",
+        "",
+        "- [ ] **T01: First** `est:15m`",
+        "- [ ] **T02: Second** `est:15m`",
+        "",
+      ].join("\n"),
+    );
+
+    writeFileSync(
+      join(gsd, "tasks", "T01-PLAN.md"),
+      "# T01: First\n\n## Inputs\n\n- `src/config.json`\n\n## Expected Output\n\n- `src/a.ts`\n",
+    );
+    writeFileSync(
+      join(gsd, "tasks", "T02-PLAN.md"),
+      "# T02: Second\n\n## Inputs\n\n- `src/a.ts`\n\n## Expected Output\n\n- `src/b.ts`\n",
+    );
+
+    const taskIO = await loadSliceTaskIO(repo, "M001", "S01");
+    const graph = deriveTaskGraph(taskIO);
+    const ready = getReadyTasks(graph, new Set(), new Set());
+    // Only T01 is ready (T02 depends on T01)
+    assert.equal(ready.length, 1);
+    assert.deepEqual(ready, ["T01"]);
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+  }
+});
+
+// ─── State Persistence ────────────────────────────────────────────────────
+
+test("saveReactiveState and loadReactiveState round-trip", () => {
+  const repo = mkdtempSync(join(tmpdir(), "gsd-reactive-state-"));
+  mkdirSync(join(repo, ".gsd", "runtime"), { recursive: true });
+  try {
+    const state: ReactiveExecutionState = {
+      sliceId: "S01",
+      completed: ["T01", "T02"],
+      graphSnapshot: { taskCount: 4, edgeCount: 2, readySetSize: 1, ambiguous: false },
+      updatedAt: "2025-01-01T00:00:00Z",
+    };
+
+    saveReactiveState(repo, "M001", "S01", state);
+    const loaded = loadReactiveState(repo, "M001", "S01");
+    assert.deepEqual(loaded, state);
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+  }
+});
+
+test("clearReactiveState removes the file", () => {
+  const repo = mkdtempSync(join(tmpdir(), "gsd-reactive-clear-"));
+  mkdirSync(join(repo, ".gsd", "runtime"), { recursive: true });
+  try {
+    const state: ReactiveExecutionState = {
+      sliceId: "S01",
+      completed: [],
+      graphSnapshot: { taskCount: 2, edgeCount: 0, readySetSize: 2, ambiguous: false },
+      updatedAt: "2025-01-01T00:00:00Z",
+    };
+
+    saveReactiveState(repo, "M001", "S01", state);
+    assert.ok(existsSync(join(repo, ".gsd", "runtime", "M001-S01-reactive.json")));
+
+    clearReactiveState(repo, "M001", "S01");
+    assert.ok(!existsSync(join(repo, ".gsd", "runtime", "M001-S01-reactive.json")));
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+  }
+});
+
+test("loadReactiveState returns null when no file exists", () => {
+  const repo = mkdtempSync(join(tmpdir(), "gsd-reactive-nofile-"));
+  mkdirSync(join(repo, ".gsd", "runtime"), { recursive: true });
+  try {
+    const loaded = loadReactiveState(repo, "M001", "S01");
+    assert.equal(loaded, null);
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+  }
+});
+
+test("completed tasks are not re-dispatched on next iteration", async () => {
+  const repo = mkdtempSync(join(tmpdir(), "gsd-reactive-reentry-"));
+  try {
+    const gsd = join(repo, ".gsd", "milestones", "M001", "slices", "S01");
+    mkdirSync(join(gsd, "tasks"), { recursive: true });
+    mkdirSync(join(repo, ".gsd", "runtime"), { recursive: true });
+
+    writeFileSync(
+      join(gsd, "S01-PLAN.md"),
+      [
+        "# S01: Reentry Test",
+        "",
+        "**Goal:** Test re-entry",
+        "**Demo:** Correct resumption",
+        "",
+        "## Tasks",
+        "",
+        "- [x] **T01: Done** `est:15m`",
+        "- [ ] **T02: Pending** `est:15m`",
+        "- [ ] **T03: Also Pending** `est:15m`",
+        "",
+      ].join("\n"),
+    );
+
+    writeFileSync(
+      join(gsd, "tasks", "T01-PLAN.md"),
+      "# T01: Done\n\n## Inputs\n\n- `src/config.json`\n\n## Expected Output\n\n- `src/a.ts`\n",
+    );
+    writeFileSync(
+      join(gsd, "tasks", "T02-PLAN.md"),
+      "# T02: Pending\n\n## Inputs\n\n- `src/a.ts`\n\n## Expected Output\n\n- `src/b.ts`\n",
+    );
+    writeFileSync(
+      join(gsd, "tasks", "T03-PLAN.md"),
+      "# T03: Also Pending\n\n## Inputs\n\n- `src/a.ts`\n\n## Expected Output\n\n- `src/c.ts`\n",
+    );
+
+    const taskIO = await loadSliceTaskIO(repo, "M001", "S01");
+    const graph = deriveTaskGraph(taskIO);
+
+    // T01 is done, T02 and T03 depend on T01
+    const completed = new Set(["T01"]);
+    const ready = getReadyTasks(graph, completed, new Set());
+    // Both T02 and T03 should be ready (T01 is complete)
+    assert.deepEqual(ready, ["T02", "T03"]);
+
+    // Simulate T02 completes, re-derive
+    completed.add("T02");
+    const ready2 = getReadyTasks(graph, completed, new Set());
+    // Only T03 should be ready
+    assert.deepEqual(ready2, ["T03"]);
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+  }
+});