trekoon 0.4.1 → 0.4.3

package/src/domain/tracker-domain.ts

@@ -6,7 +6,6 @@ import {
   type CompactEpicExpandResult,
   type CompactDependencyBatchAddResult,
   type CompactDependencySpec,
-  type CompactEntityRef,
   type CompactSubtaskBatchCreateResult,
   type CompactSubtaskSpec,
   type CompactTaskBatchCreateResult,
@@ -21,14 +20,10 @@ import {
   type ReverseDependencyNode,
   type SearchEntityMatch,
   type SearchField,
-  type SearchFieldMatch,
   type SearchNode,
   type SearchSummary,
-  type StatusCascadeBlocker,
-  type StatusCascadeChange,
   type StatusCascadePlan,
   type StatusCascadeRootKind,
-  type StatusCascadeScopeNode,
   type SubtaskRecord,
   type TaskTreeDetailed,
   type TaskRecord,
@@ -36,9 +31,22 @@ import {
   VALID_TRANSITIONS,
   type ValidStatus,
 } from "./types";
+import { buildMatchSnippet, collectSearchMatches, countMatches, summarizeMatches } from "./search";
+import { loadCascadeDependencyTargetStatuses, planStatusCascade as planStatusCascadeImpl } from "./cascade-planner";
+import { DEPENDENCY_GATED_STATUSES } from "./dependency-rules";
+import {
+  type BatchValidationReader,
+  type DependencyBatchResolution,
+  type DependencyBatchValidationIssue,
+  type ResolvedDependencyBatchSpec,
+  buildDependencyAdjacency as buildDependencyAdjacencyFn,
+  collectDependencyBatchIssues as collectDependencyBatchIssuesFn,
+  resolveDependencyBatchSpec as resolveDependencyBatchSpecFn,
+  resolveEpicExpandDependencySpecs as resolveEpicExpandDependencySpecsFn,
+  resolveEpicExpandSubtaskSpecs as resolveEpicExpandSubtaskSpecsFn,
+} from "./batch-validation";
 
 const DEFAULT_STATUS = "todo";
-const DEPENDENCY_GATED_STATUSES = new Set<string>(["in_progress", "done"]);
 const SQLITE_MAX_VARIABLES = 999;
 
 interface EpicRow {
@@ -48,6 +56,7 @@ interface EpicRow {
   status: string;
   created_at: number;
   updated_at: number;
+  version: number;
 }
 
 interface TaskRow extends EpicRow {
@@ -97,32 +106,6 @@ interface ValidatedSubtaskBatchSpec {
   readonly status: string;
 }
 
-interface ResolvedDependencyBatchSpec {
-  readonly index: number;
-  readonly sourceId: string;
-  readonly sourceKind: "task" | "subtask";
-  readonly dependsOnId: string;
-  readonly dependsOnKind: "task" | "subtask";
-}
-
-interface DependencyBatchValidationIssue {
-  readonly index: number;
-  readonly type: "missing_id" | "duplicate" | "cycle";
-  readonly sourceId: string;
-  readonly dependsOnId: string;
-  readonly details: Record<string, unknown>;
-}
-
-interface DependencyBatchResolution {
-  readonly spec?: ResolvedDependencyBatchSpec;
-  readonly issues: readonly DependencyBatchValidationIssue[];
-}
-
-interface ResolvedCompactEntity {
-  readonly id: string;
-  readonly kind: "task" | "subtask";
-}
-
 interface TaskDeletionPlan {
   readonly subtaskIds: readonly string[];
   readonly touchingDependencies: readonly DependencyRecord[];
@@ -226,6 +209,7 @@ function mapEpic(row: EpicRow): EpicRecord {
     status: row.status,
     createdAt: row.created_at,
     updatedAt: row.updated_at,
+    version: row.version,
   };
 }
 
@@ -239,6 +223,7 @@ function mapTask(row: TaskRow): TaskRecord {
     owner: row.owner ?? null,
     createdAt: row.created_at,
     updatedAt: row.updated_at,
+    version: row.version,
   };
 }
 
@@ -252,6 +237,7 @@ function mapSubtask(row: SubtaskRow): SubtaskRecord {
     owner: row.owner ?? null,
     createdAt: row.created_at,
     updatedAt: row.updated_at,
+    version: row.version,
   };
 }
 
@@ -267,55 +253,6 @@ function mapDependency(row: DependencyRow): DependencyRecord {
   };
 }
 
-function countMatches(value: string, searchText: string): number {
-  if (searchText.length === 0) {
-    return 0;
-  }
-
-  let count = 0;
-  let offset = 0;
-  while (offset <= value.length - searchText.length) {
-    const nextIndex = value.indexOf(searchText, offset);
-    if (nextIndex === -1) {
-      return count;
-    }
-
-    count += 1;
-    offset = nextIndex + searchText.length;
-  }
-
-  return count;
-}
-
-function buildMatchSnippet(value: string, searchText: string, contextSize = 24): string {
-  if (searchText.length === 0) {
-    return "";
-  }
-
-  const matchIndex = value.indexOf(searchText);
-  if (matchIndex === -1) {
-    return "";
-  }
-
-  const start = Math.max(0, matchIndex - contextSize);
-  const end = Math.min(value.length, matchIndex + searchText.length + contextSize);
-  const rawSnippet = value.slice(start, end).replace(/\s+/g, " ").trim();
-  const prefix = start > 0 ? "…" : "";
-  const suffix = end < value.length ? "…" : "";
-  return `${prefix}${rawSnippet}${suffix}`;
-}
-
-function summarizeMatches(matches: readonly SearchEntityMatch[]): SearchSummary {
-  return {
-    matchedEntities: matches.length,
-    matchedFields: matches.reduce((total, match) => total + match.fields.length, 0),
-    totalMatches: matches.reduce(
-      (total, match) => total + match.fields.reduce((fieldTotal, field) => fieldTotal + field.count, 0),
-      0,
-    ),
-  };
-}
-
 export class TrackerDomain {
   readonly #db: Database;
 
@@ -323,7 +260,32 @@ export class TrackerDomain {
     this.#db = db;
   }
 
+  #assertInTransaction(opName: string): void {
+    if (!this.#db.inTransaction) {
+      throw new DomainError({
+        code: "invalid_state",
+        message: `${opName} must be called inside a writeTransaction`,
+        details: { op: opName },
+      });
+    }
+  }
+
+  #makeBatchValidationReader(): BatchValidationReader {
+    return {
+      getTask: (id) => this.getTask(id),
+      getSubtask: (id) => this.getSubtask(id),
+      getDependencyByEdge: (sourceId, dependsOnId) => this.#getDependencyByEdge(sourceId, dependsOnId),
+      buildDependencyAdjacency: () => {
+        const rows = this.#db
+          .query("SELECT source_id, depends_on_id FROM dependencies ORDER BY source_id ASC, depends_on_id ASC;")
+          .all() as Array<{ source_id: string; depends_on_id: string }>;
+        return buildDependencyAdjacencyFn(rows);
+      },
+    };
+  }
+
   createEpic(input: { title: string; description: string; status?: string | undefined }): EpicRecord {
+    this.#assertInTransaction("createEpic");
     const now: number = Date.now();
     const id: string = randomUUID();
     const title: string = assertNonEmpty("title", input.title);
@@ -341,14 +303,61 @@ export class TrackerDomain {
 
   listEpics(): readonly EpicRecord[] {
     const rows = this.#db
-      .query("SELECT id, title, description, status, created_at, updated_at FROM epics ORDER BY created_at ASC, id ASC;")
+      .query("SELECT id, title, description, status, created_at, updated_at, version FROM epics ORDER BY created_at ASC, id ASC;")
       .all() as EpicRow[];
     return rows.map(mapEpic);
   }
 
+  /**
+   * Returns the count of all epics without fetching rows.
+   */
+  countEpics(): number {
+    const row = this.#db.query("SELECT COUNT(*) AS n FROM epics;").get() as { n: number };
+    return row.n;
+  }
+
+  /**
+   * Returns the single "active" epic without fetching all rows:
+   * 1. First in_progress epic (any order — there should be at most one).
+   * 2. Fallback: most-recently-updated todo epic.
+   * 3. Fallback: oldest epic by created_at / id (matches epics[0] from listEpics).
+   * 4. null when the table is empty.
+   *
+   * Note: no index on (status, updated_at) exists on the epics table as of this
+   * writing, so the query uses a table scan. For typical epic counts this is
+   * negligible; add idx_epics_status_updated_at if it becomes a concern.
+   */
+  findActiveEpic(): EpicRecord | null {
+    const inProgress = this.#db
+      .query(
+        "SELECT id, title, description, status, created_at, updated_at, version FROM epics WHERE status = 'in_progress' LIMIT 1;",
+      )
+      .get() as EpicRow | null;
+    if (inProgress) {
+      return mapEpic(inProgress);
+    }
+
+    const todo = this.#db
+      .query(
+        "SELECT id, title, description, status, created_at, updated_at, version FROM epics WHERE status = 'todo' ORDER BY updated_at DESC LIMIT 1;",
+      )
+      .get() as EpicRow | null;
+    if (todo) {
+      return mapEpic(todo);
+    }
+
+    // Fallback: oldest epic regardless of status (mirrors epics[0] from listEpics).
+    const oldest = this.#db
+      .query(
+        "SELECT id, title, description, status, created_at, updated_at, version FROM epics ORDER BY created_at ASC, id ASC LIMIT 1;",
+      )
+      .get() as EpicRow | null;
+    return oldest ? mapEpic(oldest) : null;
+  }
+
   getEpic(id: string): EpicRecord | null {
     const row = this.#db
-      .query("SELECT id, title, description, status, created_at, updated_at FROM epics WHERE id = ?;")
+      .query("SELECT id, title, description, status, created_at, updated_at, version FROM epics WHERE id = ?;")
       .get(id) as EpicRow | null;
     return row ? mapEpic(row) : null;
   }
@@ -370,6 +379,7 @@ export class TrackerDomain {
     id: string,
     input: { title?: string | undefined; description?: string | undefined; status?: string | undefined },
   ): EpicRecord {
+    this.#assertInTransaction("updateEpic");
     const existing: EpicRecord = this.getEpicOrThrow(id);
     const nextTitle: string = input.title !== undefined ? assertNonEmpty("title", input.title) : existing.title;
     const nextDescription: string =
@@ -385,11 +395,13 @@ export class TrackerDomain {
   }
 
   deleteEpic(id: string): void {
+    this.#assertInTransaction("deleteEpic");
     this.getEpicOrThrow(id);
     this.#db.query("DELETE FROM epics WHERE id = ?;").run(id);
   }
 
   createTask(input: { epicId: string; title: string; description: string; status?: string | undefined }): TaskRecord {
+    this.#assertInTransaction("createTask");
     const now: number = Date.now();
     const id: string = randomUUID();
     const epicId: string = assertNonEmpty("epicId", input.epicId);
@@ -428,13 +440,7 @@ export class TrackerDomain {
       };
     }
 
-    if (!this.#db.inTransaction) {
-      throw new DomainError({
-        code: "invalid_state",
-        message: "createTaskBatch must be called inside a writeTransaction",
-        details: { entity: "task" },
-      });
-    }
+    this.#assertInTransaction("createTaskBatch");
 
     const TASK_COLS_PER_ROW = 7; // id, epic_id, title, description, status, created_at, updated_at (version is literal 1)
     const WRITE_CHUNK_SIZE: number = Math.floor(SQLITE_MAX_VARIABLES / TASK_COLS_PER_ROW);
@@ -467,7 +473,7 @@ export class TrackerDomain {
       const inPlaceholders: string = chunkIds.map(() => "?").join(", ");
       const chunkRows = this.#db
         .query(
-          `SELECT id, epic_id, title, description, status, owner, created_at, updated_at FROM tasks WHERE id IN (${inPlaceholders});`,
+          `SELECT id, epic_id, title, description, status, owner, created_at, updated_at, version FROM tasks WHERE id IN (${inPlaceholders});`,
         )
         .all(...chunkIds) as TaskRow[];
       fetchedRows.push(...chunkRows);
@@ -499,21 +505,21 @@ export class TrackerDomain {
       this.getEpicOrThrow(epicId);
       const rows = this.#db
         .query(
-          "SELECT id, epic_id, title, description, status, owner, created_at, updated_at FROM tasks WHERE epic_id = ? ORDER BY created_at ASC, id ASC;",
+          "SELECT id, epic_id, title, description, status, owner, created_at, updated_at, version FROM tasks WHERE epic_id = ? ORDER BY created_at ASC, id ASC;",
         )
         .all(epicId) as TaskRow[];
       return rows.map(mapTask);
     }
 
     const rows = this.#db
-      .query("SELECT id, epic_id, title, description, status, owner, created_at, updated_at FROM tasks ORDER BY created_at ASC, id ASC;")
+      .query("SELECT id, epic_id, title, description, status, owner, created_at, updated_at, version FROM tasks ORDER BY created_at ASC, id ASC;")
       .all() as TaskRow[];
     return rows.map(mapTask);
   }
 
   getTask(id: string): TaskRecord | null {
     const row = this.#db
-      .query("SELECT id, epic_id, title, description, status, owner, created_at, updated_at FROM tasks WHERE id = ?;")
+      .query("SELECT id, epic_id, title, description, status, owner, created_at, updated_at, version FROM tasks WHERE id = ?;")
       .get(id) as TaskRow | null;
     return row ? mapTask(row) : null;
   }
@@ -535,6 +541,7 @@ export class TrackerDomain {
     id: string,
     input: { title?: string | undefined; description?: string | undefined; status?: string | undefined; owner?: string | null | undefined },
   ): TaskRecord {
+    this.#assertInTransaction("updateTask");
     const existing: TaskRecord = this.getTaskOrThrow(id);
     const nextTitle: string = input.title !== undefined ? assertNonEmpty("title", input.title) : existing.title;
     const nextDescription: string =
@@ -552,6 +559,7 @@ export class TrackerDomain {
   }
 
   deleteTask(id: string): void {
+    this.#assertInTransaction("deleteTask");
     const normalizedTaskId: string = assertNonEmpty("id", id);
     this.getTaskOrThrow(normalizedTaskId);
 
@@ -575,6 +583,7 @@ export class TrackerDomain {
   createSubtask(
     input: { taskId: string; title: string; description?: string | undefined; status?: string | undefined },
   ): SubtaskRecord {
+    this.#assertInTransaction("createSubtask");
     const now: number = Date.now();
     const id: string = randomUUID();
     const taskId: string = assertNonEmpty("taskId", input.taskId);
@@ -623,13 +632,7 @@ export class TrackerDomain {
       };
     }
 
-    if (!this.#db.inTransaction) {
-      throw new DomainError({
-        code: "invalid_state",
-        message: "createSubtaskBatch must be called inside a writeTransaction",
-        details: { entity: "subtask" },
-      });
-    }
+    this.#assertInTransaction("createSubtaskBatch");
 
     const SUBTASK_COLS_PER_ROW = 7; // id, task_id, title, description, status, created_at, updated_at (version is literal 1)
     const WRITE_CHUNK_SIZE: number = Math.floor(SQLITE_MAX_VARIABLES / SUBTASK_COLS_PER_ROW);
@@ -662,7 +665,7 @@ export class TrackerDomain {
       const inPlaceholders: string = chunkIds.map(() => "?").join(", ");
       const chunkRows = this.#db
         .query(
-          `SELECT id, task_id, title, description, status, owner, created_at, updated_at FROM subtasks WHERE id IN (${inPlaceholders});`,
+          `SELECT id, task_id, title, description, status, owner, created_at, updated_at, version FROM subtasks WHERE id IN (${inPlaceholders});`,
         )
         .all(...chunkIds) as SubtaskRow[];
       fetchedRows.push(...chunkRows);
@@ -738,7 +741,7 @@ export class TrackerDomain {
       this.getTaskOrThrow(taskId);
       const rows = this.#db
         .query(
-          "SELECT id, task_id, title, description, status, owner, created_at, updated_at FROM subtasks WHERE task_id = ? ORDER BY created_at ASC, id ASC;",
+          "SELECT id, task_id, title, description, status, owner, created_at, updated_at, version FROM subtasks WHERE task_id = ? ORDER BY created_at ASC, id ASC;",
         )
         .all(taskId) as SubtaskRow[];
       return rows.map(mapSubtask);
@@ -746,7 +749,7 @@ export class TrackerDomain {
 
     const rows = this.#db
       .query(
-        "SELECT id, task_id, title, description, status, owner, created_at, updated_at FROM subtasks ORDER BY created_at ASC, id ASC;",
+        "SELECT id, task_id, title, description, status, owner, created_at, updated_at, version FROM subtasks ORDER BY created_at ASC, id ASC;",
       )
       .all() as SubtaskRow[];
     return rows.map(mapSubtask);
@@ -756,7 +759,7 @@ export class TrackerDomain {
     this.getTaskOrThrow(taskId);
     const rows = this.#db
       .query(
-        "SELECT id, task_id, title, description, status, owner, created_at, updated_at FROM subtasks WHERE task_id = ? AND status != 'done' ORDER BY created_at ASC, id ASC;",
+        "SELECT id, task_id, title, description, status, owner, created_at, updated_at, version FROM subtasks WHERE task_id = ? AND status != 'done' ORDER BY created_at ASC, id ASC;",
       )
       .all(taskId) as SubtaskRow[];
     return rows.map(mapSubtask);
@@ -764,7 +767,7 @@ export class TrackerDomain {
 
   getSubtask(id: string): SubtaskRecord | null {
     const row = this.#db
-      .query("SELECT id, task_id, title, description, status, owner, created_at, updated_at FROM subtasks WHERE id = ?;")
+      .query("SELECT id, task_id, title, description, status, owner, created_at, updated_at, version FROM subtasks WHERE id = ?;")
       .get(id) as SubtaskRow | null;
     return row ? mapSubtask(row) : null;
   }
@@ -786,6 +789,7 @@ export class TrackerDomain {
     id: string,
     input: { title?: string | undefined; description?: string | undefined; status?: string | undefined; owner?: string | null | undefined },
   ): SubtaskRecord {
+    this.#assertInTransaction("updateSubtask");
     const existing: SubtaskRecord = this.getSubtaskOrThrow(id);
     const nextTitle: string = input.title !== undefined ? assertNonEmpty("title", input.title) : existing.title;
     const nextDescription: string =
@@ -803,6 +807,7 @@ export class TrackerDomain {
   }
 
   deleteSubtask(id: string): void {
+    this.#assertInTransaction("deleteSubtask");
     this.getSubtaskOrThrow(id);
     this.#db.query("DELETE FROM dependencies WHERE source_id = ? OR depends_on_id = ?;").run(id, id);
     this.#db.query("DELETE FROM subtasks WHERE id = ?;").run(id);
@@ -861,7 +866,7 @@ export class TrackerDomain {
     const taskIds = new Set(tasks.map((task) => task.id));
     const subtasks = this.#db
       .query(
-        "SELECT id, task_id, title, description, status, owner, created_at, updated_at FROM subtasks WHERE task_id IN (SELECT id FROM tasks WHERE epic_id = ?) ORDER BY created_at ASC, id ASC;",
+        "SELECT id, task_id, title, description, status, owner, created_at, updated_at, version FROM subtasks WHERE task_id IN (SELECT id FROM tasks WHERE epic_id = ?) ORDER BY created_at ASC, id ASC;",
       )
       .all(epicId) as SubtaskRow[];
 
@@ -941,37 +946,17 @@ export class TrackerDomain {
   }
 
   planStatusCascade(rootKind: StatusCascadeRootKind, rootId: string, targetStatus: string): StatusCascadePlan {
-    const normalizedTargetStatus = assertNonEmpty("status", targetStatus);
-    const scope = this.#collectStatusCascadeScope(rootKind, rootId);
-    const scopeIdSet = new Set(scope.map((node) => node.id));
-    const orderedChanges = this.#orderStatusCascadeChanges(scope, normalizedTargetStatus);
-    const changedIds = orderedChanges.map((change) => change.id);
-    const changedIdSet = new Set(changedIds);
-    const unchangedIds = scope
-      .filter((node) => !changedIdSet.has(node.id))
-      .map((node) => node.id);
-    const blockers = this.#collectStatusCascadeBlockers(orderedChanges, scopeIdSet, changedIdSet, normalizedTargetStatus);
-
-    return {
+    return planStatusCascadeImpl(
+      {
+        buildEpicTreeDetailed: (id) => this.buildEpicTreeDetailed(id),
+        buildTaskTreeDetailed: (id) => this.buildTaskTreeDetailed(id),
+        listDependenciesBySourceIds: (ids) => this.listDependenciesBySourceIds(ids),
+        loadDependencyTargetStatuses: (ids) => loadCascadeDependencyTargetStatuses(this.#db, ids),
+      },
       rootKind,
       rootId,
-      targetStatus: normalizedTargetStatus,
-      atomic: true,
-      scope,
-      orderedChanges,
-      changedIds,
-      unchangedIds,
-      blockers,
-      counts: {
-        scope: scope.length,
-        changed: orderedChanges.length,
-        unchanged: unchangedIds.length,
-        blockers: blockers.length,
-        changedEpics: orderedChanges.filter((change) => change.kind === "epic").length,
-        changedTasks: orderedChanges.filter((change) => change.kind === "task").length,
-        changedSubtasks: orderedChanges.filter((change) => change.kind === "subtask").length,
-      },
-    };
+      targetStatus,
+    );
   }
 
   collectEpicSearchScope(epicId: string): readonly SearchNode[] {
@@ -1076,6 +1061,7 @@ export class TrackerDomain {
   }
 
   addDependency(sourceId: string, dependsOnId: string): DependencyRecord {
+    this.#assertInTransaction("addDependency");
     const normalizedSourceId: string = assertNonEmpty("sourceId", sourceId);
     const normalizedDependsOnId: string = assertNonEmpty("dependsOnId", dependsOnId);
 
@@ -1121,6 +1107,7 @@ export class TrackerDomain {
   }
 
   addDependencyBatch(input: { specs: readonly CompactDependencySpec[] }): CompactDependencyBatchAddResult {
+    this.#assertInTransaction("addDependencyBatch");
     const resolutions = input.specs.map((spec, index) => this.#resolveDependencyBatchSpec(index, spec));
     const resolvedSpecs = resolutions.flatMap((resolution) => (resolution.spec === undefined ? [] : [resolution.spec]));
     const issues = resolutions.flatMap((resolution) => resolution.issues).concat(this.#collectDependencyBatchIssues(resolvedSpecs));
@@ -1207,6 +1194,7 @@ export class TrackerDomain {
   }
 
   removeDependency(sourceId: string, dependsOnId: string): number {
+    this.#assertInTransaction("removeDependency");
     const normalizedSourceId: string = assertNonEmpty("sourceId", sourceId);
     const normalizedDependsOnId: string = assertNonEmpty("dependsOnId", dependsOnId);
     const result = this.#db
@@ -1282,7 +1270,7 @@ export class TrackerDomain {
       const inPlaceholders: string = chunkIds.map(() => "?").join(", ");
       const rows = this.#db
         .query(
-          `SELECT id, task_id, title, description, status, owner, created_at, updated_at
+          `SELECT id, task_id, title, description, status, owner, created_at, updated_at, version
            FROM subtasks
            WHERE task_id IN (${inPlaceholders})
            ORDER BY created_at ASC, id ASC;`,
@@ -1300,44 +1288,56 @@ export class TrackerDomain {
   }
 
   /**
-   * Resolves dependency statuses for multiple tasks using a single prepared
-   * statement executed once per task ID.  This avoids the previous N+1 pattern
-   * where each task required separate getTaskOrThrow/getSubtaskOrThrow calls
-   * per dependency.
+   * Resolves dependency statuses for multiple tasks using chunked
+   * WHERE source_id IN (?...) queries — the same pattern as
+   * #collectStatusCascadeBlockers.  This reduces N queries to
+   * ceil(N/999), eliminating the previous per-ID N+1 loop.
    */
   batchResolveDependencyStatuses(
     taskIds: readonly string[],
   ): Map<string, { totalDependencies: number; blockers: Array<{ id: string; kind: "task" | "subtask"; status: string }> }> {
+    type DepStatusRow = {
+      source_id: string;
+      depends_on_id: string;
+      depends_on_kind: "task" | "subtask";
+      dep_status: string | null;
+    };
+
     const result = new Map<string, { totalDependencies: number; blockers: Array<{ id: string; kind: "task" | "subtask"; status: string }> }>();
 
     if (taskIds.length === 0) {
       return result;
     }
 
-    // Use a static parameterised query per task ID rather than interpolating
-    // a dynamic IN-list into the SQL string.  This is consistent with every
-    // other query in TrackerDomain and avoids any placeholder-count confusion.
-    const stmt = this.#db.query(
-      `SELECT d.source_id, d.depends_on_id, d.depends_on_kind, COALESCE(t.status, s.status) AS dep_status
-       FROM dependencies d
-       LEFT JOIN tasks t ON d.depends_on_kind = 'task' AND d.depends_on_id = t.id
-       LEFT JOIN subtasks s ON d.depends_on_kind = 'subtask' AND d.depends_on_id = s.id
-       WHERE d.source_id = ?
-       ORDER BY d.created_at ASC, d.id ASC;`,
-    );
-
+    // Pre-populate so every requested ID has an entry, even with no deps.
     for (const taskId of taskIds) {
-      const entry = { totalDependencies: 0, blockers: [] as Array<{ id: string; kind: "task" | "subtask"; status: string }> };
-      result.set(taskId, entry);
+      result.set(taskId, { totalDependencies: 0, blockers: [] });
+    }
 
-      const rows = stmt.all(taskId) as Array<{
-        source_id: string;
-        depends_on_id: string;
-        depends_on_kind: "task" | "subtask";
-        dep_status: string | null;
-      }>;
+    // Batch-fetch all dependency rows with their target statuses using chunked
+    // IN queries with JOINs.  ceil(N/999) queries instead of N.
+    for (let offset = 0; offset < taskIds.length; offset += SQLITE_MAX_VARIABLES) {
+      const chunkIds = taskIds.slice(offset, offset + SQLITE_MAX_VARIABLES);
+      const inPlaceholders: string = chunkIds.map(() => "?").join(", ");
+
+      const rows = this.#db
+        .query(
+          `SELECT d.source_id, d.depends_on_id, d.depends_on_kind,
+                  COALESCE(t.status, s.status) AS dep_status
+           FROM dependencies d
+           LEFT JOIN tasks t ON d.depends_on_kind = 'task' AND d.depends_on_id = t.id
+           LEFT JOIN subtasks s ON d.depends_on_kind = 'subtask' AND d.depends_on_id = s.id
+           WHERE d.source_id IN (${inPlaceholders})
+           ORDER BY d.created_at ASC, d.id ASC;`,
+        )
+        .all(...chunkIds) as DepStatusRow[];
 
       for (const row of rows) {
+        const entry = result.get(row.source_id);
+        if (entry === undefined) {
+          continue;
+        }
+
         entry.totalDependencies += 1;
 
         // Skip orphaned dependency rows (target deleted).
@@ -1420,279 +1420,25 @@ export class TrackerDomain {
   }
 
   #resolveDependencyBatchSpec(index: number, spec: CompactDependencySpec): DependencyBatchResolution {
-    const sourceResolution = this.#resolveDependencyBatchId(spec.source, "source", index);
-    const dependsOnResolution = this.#resolveDependencyBatchId(spec.dependsOn, "dependsOn", index);
-    const issues = [...sourceResolution.issues, ...dependsOnResolution.issues];
-    const sourceId = sourceResolution.id;
-    const dependsOnId = dependsOnResolution.id;
-
-    if (sourceId === undefined || dependsOnId === undefined) {
-      return {
-        issues,
-      };
-    }
-
-    if (sourceId === dependsOnId) {
-      return {
-        issues: [
-          ...issues,
-          {
-            index,
-            type: "cycle",
-            sourceId,
-            dependsOnId,
-            details: { sourceId, dependsOnId, reason: "self_reference" },
-          },
-        ],
-      };
-    }
-
-    return {
-      spec: {
-        index,
-        sourceId,
-        sourceKind: this.resolveNodeKind(sourceId),
-        dependsOnId,
-        dependsOnKind: this.resolveNodeKind(dependsOnId),
-      },
-      issues,
-    };
-  }
-
-  #resolveDependencyBatchId(
-    reference: CompactEntityRef,
-    field: "source" | "dependsOn",
-    index: number,
-  ): { readonly id?: string; readonly issues: readonly DependencyBatchValidationIssue[] } {
-    if (reference.kind === "temp_key") {
-      return {
-        issues: [
-          {
-            index,
-            type: "missing_id",
-            sourceId: field === "source" ? `@${reference.tempKey}` : "",
-            dependsOnId: field === "dependsOn" ? `@${reference.tempKey}` : "",
-            details: {
-              field,
-              tempKey: reference.tempKey,
-              message: `Unresolved temp key @${reference.tempKey}`,
-            },
-          },
-        ],
-      };
-    }
-
-    const id = assertNonEmpty(field === "source" ? "sourceId" : "dependsOnId", reference.id);
-    const task = this.getTask(id);
-    const subtask = this.getSubtask(id);
-    if (!task && !subtask) {
-      return {
-        issues: [
-          {
-            index,
-            type: "missing_id",
-            sourceId: field === "source" ? id : "",
-            dependsOnId: field === "dependsOn" ? id : "",
-            details: {
-              field,
-              id,
-              message: `Node not found: ${id}`,
-            },
-          },
-        ],
-      };
-    }
-
-    return { id, issues: [] };
+    return resolveDependencyBatchSpecFn(index, spec, this.#makeBatchValidationReader());
   }
 
   #resolveEpicExpandSubtaskSpecs(
     specs: readonly CompactSubtaskSpec[],
     mappings: readonly { tempKey: string; id: string; kind: "task" | "subtask" }[],
   ): CompactSubtaskSpec[] {
-    return specs.map((spec, index) => {
-      const parent = this.#resolveEpicExpandEntityRef(spec.parent, mappings, "subtask", index, "parent");
-      if (parent.kind !== "task") {
-        throw new DomainError({
-          code: "invalid_input",
-          message: `Subtask parent must resolve to a task in --subtask spec ${index + 1}`,
-          details: {
-            index,
-            field: "parent",
-            kind: parent.kind,
-            id: parent.id,
-          },
-        });
-      }
-
-      return {
-        ...spec,
-        parent: {
-          kind: "id",
-          id: parent.id,
-        },
-      };
-    });
+    return resolveEpicExpandSubtaskSpecsFn(specs, mappings, this.#makeBatchValidationReader());
   }
 
   #resolveEpicExpandDependencySpecs(
     specs: readonly CompactDependencySpec[],
     mappings: readonly { tempKey: string; id: string; kind: "task" | "subtask" }[],
   ): CompactDependencySpec[] {
-    return specs.map((spec, index) => ({
-      source: {
-        kind: "id",
-        id: this.#resolveEpicExpandEntityRef(spec.source, mappings, "dep", index, "source").id,
-      },
-      dependsOn: {
-        kind: "id",
-        id: this.#resolveEpicExpandEntityRef(spec.dependsOn, mappings, "dep", index, "dependsOn").id,
-      },
-    }));
-  }
-
-  #resolveEpicExpandEntityRef(
-    reference: CompactEntityRef,
-    mappings: readonly { tempKey: string; id: string; kind: "task" | "subtask" }[],
-    option: "subtask" | "dep",
-    index: number,
-    field: "parent" | "source" | "dependsOn",
-  ): ResolvedCompactEntity {
-    if (reference.kind === "temp_key") {
-      const mapping = mappings.find((candidate) => candidate.tempKey === reference.tempKey);
-      if (mapping === undefined) {
-        throw new DomainError({
-          code: "invalid_input",
-          message: `Unknown temp key @${reference.tempKey} in --${option} spec ${index + 1}`,
-          details: {
-            index,
-            field,
-            tempKey: reference.tempKey,
-            option,
-          },
-        });
-      }
-
-      return {
-        id: mapping.id,
-        kind: mapping.kind,
-      };
-    }
-
-    const id = assertNonEmpty(field === "parent" ? "taskId" : `${field}Id`, reference.id);
-    return {
-      id,
-      kind: this.resolveNodeKind(id),
-    };
+    return resolveEpicExpandDependencySpecsFn(specs, mappings, this.#makeBatchValidationReader());
   }
 
   #collectDependencyBatchIssues(specs: readonly ResolvedDependencyBatchSpec[]): DependencyBatchValidationIssue[] {
-    const issues: DependencyBatchValidationIssue[] = [];
-    const seenEdges = new Map<string, number>();
-    const adjacency = this.#buildDependencyAdjacency();
-
-    for (const spec of specs) {
-      const edgeKey = `${spec.sourceId}->${spec.dependsOnId}`;
-      const existingIndex = seenEdges.get(edgeKey);
-      if (existingIndex !== undefined) {
-        issues.push({
-          index: spec.index,
-          type: "duplicate",
-          sourceId: spec.sourceId,
-          dependsOnId: spec.dependsOnId,
-          details: {
-            sourceId: spec.sourceId,
-            dependsOnId: spec.dependsOnId,
-            firstIndex: existingIndex,
-            duplicateIndex: spec.index,
-            duplicateKind: "batch",
-          },
-        });
-        continue;
-      }
-
-      if (this.#getDependencyByEdge(spec.sourceId, spec.dependsOnId) !== null) {
-        issues.push({
-          index: spec.index,
-          type: "duplicate",
-          sourceId: spec.sourceId,
-          dependsOnId: spec.dependsOnId,
-          details: {
-            sourceId: spec.sourceId,
-            dependsOnId: spec.dependsOnId,
-            duplicateKind: "existing",
-          },
-        });
-        continue;
-      }
-
-      if (this.#wouldCreateCycleInAdjacency(adjacency, spec.sourceId, spec.dependsOnId)) {
-        issues.push({
-          index: spec.index,
-          type: "cycle",
-          sourceId: spec.sourceId,
-          dependsOnId: spec.dependsOnId,
-          details: {
-            sourceId: spec.sourceId,
-            dependsOnId: spec.dependsOnId,
-          },
-        });
-        continue;
-      }
-
-      const nextNeighbors = adjacency.get(spec.sourceId) ?? new Set<string>();
-      nextNeighbors.add(spec.dependsOnId);
-      adjacency.set(spec.sourceId, nextNeighbors);
-      seenEdges.set(edgeKey, spec.index);
-    }
-
-    return issues.sort((left, right) => left.index - right.index || left.type.localeCompare(right.type));
-  }
-
-  #buildDependencyAdjacency(): Map<string, Set<string>> {
-    const rows = this.#db.query("SELECT source_id, depends_on_id FROM dependencies ORDER BY source_id ASC, depends_on_id ASC;").all() as Array<{
-      source_id: string;
-      depends_on_id: string;
-    }>;
-    const adjacency = new Map<string, Set<string>>();
-
-    for (const row of rows) {
-      const neighbors = adjacency.get(row.source_id) ?? new Set<string>();
-      neighbors.add(row.depends_on_id);
-      adjacency.set(row.source_id, neighbors);
-    }
-
-    return adjacency;
-  }
-
-  #wouldCreateCycleInAdjacency(adjacency: ReadonlyMap<string, ReadonlySet<string>>, sourceId: string, dependsOnId: string): boolean {
-    const visited = new Set<string>();
-    const queue: string[] = [dependsOnId];
-
-    while (queue.length > 0) {
-      const current = queue.shift();
-      if (current === undefined || visited.has(current)) {
-        continue;
-      }
-
-      if (current === sourceId) {
-        return true;
-      }
-
-      visited.add(current);
-      const neighbors = adjacency.get(current);
-      if (neighbors === undefined) {
-        continue;
-      }
-
-      for (const neighbor of neighbors) {
-        if (!visited.has(neighbor)) {
-          queue.push(neighbor);
-        }
-      }
-    }
-
-    return false;
+    return collectDependencyBatchIssuesFn(specs, this.#makeBatchValidationReader());
   }
 
   private collectSearchMatches(
@@ -1700,33 +1446,7 @@ export class TrackerDomain {
     searchText: string,
     fields: readonly SearchField[],
   ): readonly SearchEntityMatch[] {
-    const matches: SearchEntityMatch[] = [];
-
-    for (const node of nodes) {
-      const matchedFields: SearchFieldMatch[] = [];
-      for (const field of fields) {
-        const count = countMatches(node[field], searchText);
-        if (count > 0) {
-          matchedFields.push({
-            field,
-            count,
-            snippet: buildMatchSnippet(node[field], searchText),
-          });
-        }
-      }
-
-      if (matchedFields.length === 0) {
-        continue;
-      }
-
-      matches.push({
-        kind: node.kind,
-        id: node.id,
-        fields: matchedFields,
-      });
-    }
-
-    return matches;
+    return collectSearchMatches(nodes, searchText, fields);
   }
 
   private wouldCreateCycle(sourceId: string, dependsOnId: string): boolean {
@@ -1751,253 +1471,7 @@ export class TrackerDomain {
     return row !== null;
   }
 
-  #collectStatusCascadeScope(rootKind: StatusCascadeRootKind, rootId: string): StatusCascadeScopeNode[] {
-    if (rootKind === "task") {
-      const tree = this.buildTaskTreeDetailed(rootId);
-      return [
-        {
-          kind: "task",
-          id: tree.id,
-          parentId: tree.epicId,
-          status: tree.status,
-        },
-        ...tree.subtasks.map((subtask) => ({
-          kind: "subtask" as const,
-          id: subtask.id,
-          parentId: subtask.taskId,
-          status: subtask.status,
-        })),
-      ];
-    }
-
-    const tree = this.buildEpicTreeDetailed(rootId);
-    return [
-      {
-        kind: "epic",
-        id: tree.id,
-        status: tree.status,
-      },
-      ...tree.tasks.flatMap((task) => [
-        {
-          kind: "task" as const,
-          id: task.id,
-          parentId: task.epicId,
-          status: task.status,
-        },
-        ...task.subtasks.map((subtask) => ({
-          kind: "subtask" as const,
-          id: subtask.id,
-          parentId: subtask.taskId,
-          status: subtask.status,
-        })),
-      ]),
-    ];
-  }
-
-  #orderStatusCascadeChanges(scope: readonly StatusCascadeScopeNode[], targetStatus: string): StatusCascadeChange[] {
-    const changes = scope
-      .filter((node) => node.status !== targetStatus)
-      .map((node) => {
-        const change: StatusCascadeChange = {
-          kind: node.kind,
-          id: node.id,
-          previousStatus: node.status,
-          nextStatus: targetStatus,
-          ...(node.parentId === undefined ? {} : { parentId: node.parentId }),
-        };
-        return change;
-      });
-
-    if (targetStatus !== "done") {
-      return changes;
-    }
-
-    return this.#topologicallyOrderDoneCascadeChanges(changes);
-  }
-
-  #topologicallyOrderDoneCascadeChanges(changes: readonly StatusCascadeChange[]): StatusCascadeChange[] {
-    const indexById = new Map<string, number>();
-    const changeById = new Map<string, StatusCascadeChange>();
-    const dependencyTargetsBySource = new Map<string, Set<string>>();
-    const dependents = new Map<string, Set<string>>();
-    const indegree = new Map<string, number>();
-    const dependencyMap = this.listDependenciesBySourceIds(
-      changes.filter((change) => change.kind === "task" || change.kind === "subtask").map((change) => change.id),
-    );
-
-    changes.forEach((change, index) => {
-      indexById.set(change.id, index);
-      changeById.set(change.id, change);
-      indegree.set(change.id, 0);
-
-      if (change.kind !== "task" && change.kind !== "subtask") {
-        return;
-      }
-
-      const dependencyTargets = new Set((dependencyMap.get(change.id) ?? []).map((dependency) => dependency.dependsOnId));
-      dependencyTargetsBySource.set(change.id, dependencyTargets);
-    });
-
-    const addEdge = (fromId: string, toId: string): void => {
-      if (fromId === toId || !changeById.has(fromId) || !changeById.has(toId)) {
-        return;
-      }
-
-      const neighbors = dependents.get(fromId) ?? new Set<string>();
-      if (neighbors.has(toId)) {
-        return;
-      }
-
-      neighbors.add(toId);
-      dependents.set(fromId, neighbors);
-      indegree.set(toId, (indegree.get(toId) ?? 0) + 1);
-    };
-
-    for (const change of changes) {
-      const dependencyTargets = dependencyTargetsBySource.get(change.id);
-
-      if (change.kind === "subtask" && change.parentId !== undefined && !dependencyTargets?.has(change.parentId)) {
-        addEdge(change.id, change.parentId);
-      }
-
-      if (change.kind === "task" && change.parentId !== undefined && !dependencyTargets?.has(change.parentId)) {
-        addEdge(change.id, change.parentId);
-      }
-
-      if (change.kind !== "task" && change.kind !== "subtask") {
-        continue;
-      }
-
-      for (const dependencyTargetId of dependencyTargets ?? []) {
-        addEdge(dependencyTargetId, change.id);
-      }
-    }
-
-    const ordered: StatusCascadeChange[] = [];
-    const ready = changes
-      .filter((change) => (indegree.get(change.id) ?? 0) === 0)
-      .sort((left, right) => (indexById.get(left.id) ?? 0) - (indexById.get(right.id) ?? 0));
-
-    while (ready.length > 0) {
-      const next = ready.shift();
-      if (next === undefined) {
-        continue;
-      }
-
-      ordered.push(next);
-      for (const dependentId of dependents.get(next.id) ?? []) {
-        const remaining = (indegree.get(dependentId) ?? 0) - 1;
-        indegree.set(dependentId, remaining);
-        if (remaining !== 0) {
-          continue;
-        }
-
-        const dependent = changeById.get(dependentId);
-        if (dependent === undefined) {
-          continue;
-        }
-
-        ready.push(dependent);
-        ready.sort((left, right) => (indexById.get(left.id) ?? 0) - (indexById.get(right.id) ?? 0));
-      }
-    }
-
-    if (ordered.length !== changes.length) {
-      throw new DomainError({
-        code: "invalid_dependency",
-        message: "unable to determine dependency-safe cascade order",
-        details: {
-          changedIds: changes.map((change) => change.id),
-        },
-      });
-    }
-
-    return ordered;
-  }
-
-  #collectStatusCascadeBlockers(
-    changes: readonly StatusCascadeChange[],
-    scopeIdSet: ReadonlySet<string>,
-    changedIdSet: ReadonlySet<string>,
-    targetStatus: string,
-  ): StatusCascadeBlocker[] {
-    if (!DEPENDENCY_GATED_STATUSES.has(targetStatus)) {
-      return [];
-    }
-
-    // Collect all dependency-eligible change IDs upfront.
-    const eligibleIds: string[] = [];
-    for (const change of changes) {
-      if (change.kind === "task" || change.kind === "subtask") {
-        eligibleIds.push(change.id);
-      }
-    }
-
-    if (eligibleIds.length === 0) {
-      return [];
-    }
-
-    // Batch-fetch all dependency rows with their target statuses using a
-    // chunked IN query with JOINs.  This replaces the previous per-ID
-    // prepared statement approach, reducing N queries to ceil(N/999).
-    type DepStatusRow = {
-      source_id: string;
-      source_kind: "task" | "subtask";
-      depends_on_id: string;
-      depends_on_kind: "task" | "subtask";
-      dep_status: string | null;
-    };
-
-    const blockers: StatusCascadeBlocker[] = [];
-
-    for (let offset = 0; offset < eligibleIds.length; offset += SQLITE_MAX_VARIABLES) {
-      const chunkIds = eligibleIds.slice(offset, offset + SQLITE_MAX_VARIABLES);
-      const inPlaceholders: string = chunkIds.map(() => "?").join(", ");
-      const rows = this.#db
-        .query(
-          `SELECT d.source_id, d.source_kind, d.depends_on_id, d.depends_on_kind,
-                  COALESCE(t.status, s.status) AS dep_status
-           FROM dependencies d
-           LEFT JOIN tasks t ON d.depends_on_kind = 'task' AND d.depends_on_id = t.id
-           LEFT JOIN subtasks s ON d.depends_on_kind = 'subtask' AND d.depends_on_id = s.id
-           WHERE d.source_id IN (${inPlaceholders})
-           ORDER BY d.created_at ASC, d.id ASC;`,
-        )
-        .all(...chunkIds) as DepStatusRow[];
-
-      for (const row of rows) {
-        // Skip orphaned dependency rows where the referenced node no longer exists.
-        if (row.dep_status === null) {
-          continue;
-        }
-
-        const inScope = scopeIdSet.has(row.depends_on_id);
-        const willCascade = targetStatus === "done" && changedIdSet.has(row.depends_on_id);
-        if (row.dep_status === "done" || willCascade) {
-          continue;
-        }
-
-        blockers.push({
-          sourceId: row.source_id,
-          sourceKind: row.source_kind,
-          dependsOnId: row.depends_on_id,
-          dependsOnKind: row.depends_on_kind,
-          dependsOnStatus: row.dep_status,
-          inScope,
-          willCascade,
-        });
-      }
-    }
-
-    return blockers.sort(
-      (left, right) =>
-        left.sourceId.localeCompare(right.sourceId) ||
-        left.dependsOnId.localeCompare(right.dependsOnId) ||
-        left.dependsOnKind.localeCompare(right.dependsOnKind),
-    );
-  }
-
-  private assertNoUnresolvedDependenciesForStatusTransition(
+  assertNoUnresolvedDependenciesForStatusTransition(
     id: string,
     kind: DependencyNodeKind,
     existingStatus: string,