@contextgit/store 0.1.9 → 0.2.0

package/dist/local/queries.js

@@ -1,6 +1,8 @@
 // All SQL queries for LocalStore.
 // Dates are stored as INTEGER (Unix ms) and converted to/from Date at this layer.
 // IDs are generated by the caller (nanoid).
+import { nanoid } from 'nanoid';
+import { classifyThread, normalizeThreadSubject } from '@contextgit/core';
 // ─── Row → domain type converters ───────────────────────────────────────────
 function toProject(row) {
     return {
@@ -53,8 +55,10 @@ function toThread(row) {
         branchId: row.branch_id,
         description: row.description,
         status: row.status,
+        kind: row.kind,
         workflowType: row.workflow_type ?? undefined,
         openedInCommit: row.opened_in_commit,
+        lastTouchedCommit: row.last_touched_commit ?? undefined,
         closedInCommit: row.closed_in_commit ?? undefined,
         closedNote: row.closed_note ?? undefined,
         createdAt: new Date(row.created_at),
@@ -76,6 +80,37 @@ function toClaim(row) {
         threadId: row.thread_id ?? undefined,
     };
 }
+function toTraceEntry(row) {
+    return {
+        id: row.id,
+        projectId: row.project_id,
+        branchId: row.branch_id,
+        note: row.note,
+        gitCommitSha: row.git_commit_sha ?? undefined,
+        createdAt: new Date(row.created_at),
+    };
+}
+function toArchivedThread(row) {
+    return {
+        ...toThread(row),
+        archivedAt: new Date(row.archived_at),
+        archivedReason: row.archived_reason,
+    };
+}
+function toPlanNode(row) {
+    return {
+        id: row.id,
+        projectId: row.project_id,
+        parentId: row.parent_id ?? undefined,
+        level: row.level,
+        title: row.title,
+        status: row.status,
+        position: row.position,
+        gitCommitSha: row.git_commit_sha ?? undefined,
+        createdAt: new Date(row.created_at),
+        completedAt: row.completed_at ? new Date(row.completed_at) : undefined,
+    };
+}
 function toAgent(row) {
     return {
         id: row.id,
@@ -136,28 +171,100 @@ export class Queries {
             // Threads
             insertThread: db.prepare(`
         INSERT INTO threads
-          (id, project_id, branch_id, description, status, workflow_type,
-           opened_in_commit, created_at)
+          (id, project_id, branch_id, description, status, kind, workflow_type,
+           opened_in_commit, last_touched_commit, created_at)
         VALUES
-          (@id, @project_id, @branch_id, @description, 'open', @workflow_type,
-           @opened_in_commit, @created_at)
+          (@id, @project_id, @branch_id, @description, 'open', @kind, @workflow_type,
+           @opened_in_commit, @opened_in_commit, @created_at)
       `),
             syncThread: db.prepare(`
         INSERT OR IGNORE INTO threads
-          (id, project_id, branch_id, description, status, workflow_type,
-           opened_in_commit, created_at)
+          (id, project_id, branch_id, description, status, kind, workflow_type,
+           opened_in_commit, last_touched_commit, created_at)
         VALUES
-          (@id, @project_id, @branch_id, @description, @status, @workflow_type,
-           @opened_in_commit, @created_at)
+          (@id, @project_id, @branch_id, @description, @status, @kind, @workflow_type,
+           @opened_in_commit, @last_touched_commit, @created_at)
       `),
             closeThread: db.prepare(`
         UPDATE threads
         SET status = 'closed', closed_in_commit = ?, closed_note = ?
         WHERE id = ?
+      `),
+            updateThreadLastTouched: db.prepare(`
+        UPDATE threads SET last_touched_commit = ? WHERE id = ?
       `),
             selectOpenThreads: db.prepare(`SELECT * FROM threads WHERE project_id = ? AND status = 'open' ORDER BY created_at ASC`),
             selectOpenThreadsByBranch: db.prepare(`SELECT * FROM threads WHERE branch_id = ? AND status = 'open' ORDER BY created_at ASC`),
             reassignThreads: db.prepare(`UPDATE threads SET branch_id = ? WHERE branch_id = ? AND status = 'open'`),
+            // thread_archive (03 DELTA)
+            insertThreadArchive: db.prepare(`
+        INSERT INTO thread_archive
+          (id, project_id, branch_id, description, status, kind, workflow_type,
+           opened_in_commit, last_touched_commit, closed_in_commit, closed_note,
+           created_at, updated_at, archived_at, archived_reason)
+        SELECT
+           id, project_id, branch_id, description, status, kind, workflow_type,
+           opened_in_commit, last_touched_commit, ?, ?,
+           created_at, updated_at, ?, ?
+        FROM threads WHERE id = ?
+      `),
+            deleteThread: db.prepare(`DELETE FROM threads WHERE id = ?`),
+            selectArchivedThread: db.prepare(`SELECT * FROM thread_archive WHERE id = ?`),
+            restoreFromArchive: db.prepare(`
+        INSERT INTO threads
+          (id, project_id, branch_id, description, status, kind, workflow_type,
+           opened_in_commit, last_touched_commit, closed_in_commit, closed_note,
+           created_at, updated_at)
+        SELECT
+           id, project_id, branch_id, description, 'open', kind, workflow_type,
+           opened_in_commit, last_touched_commit, NULL, NULL,
+           created_at, ?
+        FROM thread_archive WHERE id = ?
+      `),
+            deleteFromArchive: db.prepare(`DELETE FROM thread_archive WHERE id = ?`),
+            selectThread: db.prepare(`SELECT * FROM threads WHERE id = ?`),
+            listArchivedByProject: db.prepare(`
+        SELECT * FROM thread_archive WHERE project_id = ? ORDER BY archived_at DESC
+      `),
+            findOpenByHandle: db.prepare(`
+        SELECT * FROM threads
+        WHERE project_id = ? AND status = 'open' AND id LIKE ? || '%'
+        LIMIT 2
+      `),
+            findArchivedByHandle: db.prepare(`
+        SELECT * FROM thread_archive
+        WHERE project_id = ? AND id LIKE ? || '%'
+        LIMIT 2
+      `),
+            // plan_nodes (04 DELTA)
+            insertPlanNode: db.prepare(`
+        INSERT INTO plan_nodes
+          (id, project_id, parent_id, level, title, status, position, git_commit_sha, created_at, completed_at)
+        VALUES
+          (@id, @project_id, @parent_id, @level, @title, @status, @position, @git_commit_sha, @created_at, @completed_at)
+      `),
+            selectPlanNode: db.prepare(`SELECT * FROM plan_nodes WHERE id = ?`),
+            listPlanNodesByProject: db.prepare(`
+        SELECT * FROM plan_nodes WHERE project_id = ? ORDER BY level, position
+      `),
+            updatePlanNodeStatus: db.prepare(`
+        UPDATE plan_nodes
+        SET status = @status,
+            completed_at = @completed_at,
+            git_commit_sha = COALESCE(@git_commit_sha, git_commit_sha)
+        WHERE id = @id
+      `),
+            updatePlanNodeTitle: db.prepare(`UPDATE plan_nodes SET title = ? WHERE id = ?`),
+            findPlanByHandle: db.prepare(`
+        SELECT * FROM plan_nodes
+        WHERE project_id = ? AND id LIKE ? || '%'
+        LIMIT 2
+      `),
+            findPlanByTitle: db.prepare(`
+        SELECT * FROM plan_nodes
+        WHERE project_id = ? AND title = ?
+        LIMIT 2
+      `),
             // Agents
             insertAgent: db.prepare(`
         INSERT INTO agents
@@ -214,6 +321,26 @@ export class Queries {
       `),
             selectThreadChangesSince: db.prepare(`
         SELECT * FROM threads WHERE project_id = ? AND (created_at > ? OR updated_at > ?) ORDER BY created_at ASC
+      `),
+            selectCommitCreatedAt: db.prepare(`
+        SELECT created_at FROM commits WHERE id = ?
+      `),
+            countProjectCommitsSince: db.prepare(`
+        SELECT COUNT(*) AS n FROM commits c
+        JOIN branches b ON c.branch_id = b.id
+        WHERE b.project_id = ? AND c.created_at > ?
+      `),
+            countBranchCommitsSince: db.prepare(`
+        SELECT COUNT(*) AS n FROM commits WHERE branch_id = ? AND created_at > ?
+      `),
+            insertTraceEntry: db.prepare(`
+        INSERT INTO trace (id, project_id, branch_id, note, git_commit_sha, created_at)
+        VALUES (@id, @project_id, @branch_id, @note, @git_commit_sha, @created_at)
+      `),
+            selectTraceEntries: db.prepare(`
+        SELECT * FROM trace WHERE project_id = ?
+        ORDER BY created_at DESC, rowid DESC
+        LIMIT ? OFFSET ?
       `),
         };
     }
@@ -339,13 +466,14 @@ export class Queries {
         return row ? toCommit(row) : null;
     }
     // ─── Threads ──────────────────────────────────────────────────────────────
-    insertThread(id, description, projectId, branchId, openedInCommit, workflowType) {
+    insertThread(id, description, projectId, branchId, openedInCommit, workflowType, kind = 'open') {
         const now = Date.now();
         this.stmts.insertThread.run({
             id,
             project_id: projectId,
             branch_id: branchId,
             description,
+            kind,
             workflow_type: workflowType,
             opened_in_commit: openedInCommit,
             created_at: now,
@@ -356,8 +484,10 @@ export class Queries {
             branchId,
             description,
             status: 'open',
+            kind,
             workflowType: workflowType ?? undefined,
             openedInCommit,
+            lastTouchedCommit: openedInCommit,
             createdAt: new Date(now),
         };
     }
@@ -368,8 +498,10 @@ export class Queries {
             branch_id: thread.branchId,
             description: thread.description,
             status: thread.status,
+            kind: thread.kind ?? 'open',
             workflow_type: thread.workflowType ?? null,
             opened_in_commit: thread.openedInCommit,
+            last_touched_commit: thread.lastTouchedCommit ?? thread.openedInCommit,
             created_at: thread.createdAt.getTime(),
         });
         return thread;
@@ -377,18 +509,196 @@ export class Queries {
     closeThread(threadId, closedInCommit, note) {
         this.stmts.closeThread.run(closedInCommit, note, threadId);
     }
+    /**
+     * Move an open thread from `threads` to `thread_archive`. Single transaction.
+     * `closedInCommit` is the commit triggering the archive (the save's new commit
+     * for manual closes; the last-touched commit for sweep-based archival).
+     */
+    archiveThread(threadId, reason, closedInCommit) {
+        const now = Date.now();
+        this.db.transaction(() => {
+            this.stmts.insertThreadArchive.run(closedInCommit, null, now, reason, threadId);
+            this.stmts.deleteThread.run(threadId);
+        })();
+        const row = this.stmts.selectArchivedThread.get(threadId);
+        if (!row)
+            throw new Error(`archiveThread: thread ${threadId} not found after move`);
+        return toArchivedThread(row);
+    }
+    /**
+     * Move a row from `thread_archive` back to `threads` with `status='open'`,
+     * clearing closed_in_commit and closed_note (the restore semantically reopens it).
+     */
+    restoreThread(threadId) {
+        const now = Date.now();
+        this.db.transaction(() => {
+            this.stmts.restoreFromArchive.run(now, threadId);
+            this.stmts.deleteFromArchive.run(threadId);
+        })();
+        const row = this.stmts.selectThread.get(threadId);
+        if (!row)
+            throw new Error(`restoreThread: thread ${threadId} not found after move`);
+        return toThread(row);
+    }
+    listArchivedThreads(projectId) {
+        const rows = this.stmts.listArchivedByProject.all(projectId);
+        return rows.map(toArchivedThread);
+    }
+    /**
+     * Bulk restore: move every archived row matching one of the given reasons back
+     * to `threads`. Returns the number of rows moved. Used to recover from a wrong
+     * one-time-sweep (e.g. the 0.2.1 calibration bug that archived live threads on
+     * long-lived branches via the old OR-of-distance rule).
+     */
+    restoreAllArchivedByReason(projectId, reasons) {
+        if (reasons.length === 0)
+            return 0;
+        const rows = this.stmts.listArchivedByProject.all(projectId);
+        const targets = rows.filter((r) => reasons.includes(r.archived_reason));
+        if (targets.length === 0)
+            return 0;
+        const now = Date.now();
+        this.db.transaction(() => {
+            for (const r of targets) {
+                this.stmts.restoreFromArchive.run(now, r.id);
+                this.stmts.deleteFromArchive.run(r.id);
+            }
+        })();
+        return targets.length;
+    }
+    /**
+     * Find an open thread on this project whose normalized description matches.
+     * Used by dedupe-on-save (02 DELTA spec §A) — open-thread count per project is
+     * bounded by the decay system being built, so a JS-side scan is acceptable.
+     */
+    findOpenThreadByNormalizedDescription(projectId, normalized) {
+        const rows = this.stmts.selectOpenThreads.all(projectId);
+        for (const row of rows) {
+            if (normalizeThreadSubject(row.description) === normalized)
+                return toThread(row);
+        }
+        return undefined;
+    }
+    /**
+     * Resolve a 6-char handle to an open thread on the project.
+     * Returns undefined if no match; throws if multiple match (collision).
+     */
+    findOpenThreadByHandle(projectId, handle) {
+        const rows = this.stmts.findOpenByHandle.all(projectId, handle);
+        if (rows.length === 0)
+            return undefined;
+        if (rows.length > 1) {
+            throw new Error(`findOpenThreadByHandle: handle '${handle}' matches ${rows.length} threads`);
+        }
+        const now = Date.now();
+        return this.attachDecayFlags(toThread(rows[0]), now);
+    }
+    findArchivedThreadByHandle(projectId, handle) {
+        const rows = this.stmts.findArchivedByHandle.all(projectId, handle);
+        if (rows.length === 0)
+            return undefined;
+        if (rows.length > 1) {
+            throw new Error(`findArchivedThreadByHandle: handle '${handle}' matches ${rows.length} threads`);
+        }
+        return toArchivedThread(rows[0]);
+    }
+    /**
+     * Project-scoped sweep run by createCommit at the end of every save: any open
+     * thread on this project that classifies as `stale` or `expired` is moved to
+     * `thread_archive`. Returns counts by reason for the save response.
+     */
+    sweepStaleThreads(projectId, now) {
+        const threads = this.listOpenThreads(projectId);
+        const byReason = { 'stale-age': 0, 'stale-distance': 0, 'watch-expired': 0 };
+        let archived = 0;
+        for (const t of threads) {
+            if (!t.stale && !t.expired)
+                continue;
+            let reason;
+            if (t.expired) {
+                reason = 'watch-expired';
+            }
+            else {
+                const touchId = t.lastTouchedCommit ?? t.openedInCommit;
+                const tsRow = this.stmts.selectCommitCreatedAt.get(touchId);
+                const touchTs = tsRow?.created_at ?? t.createdAt.getTime();
+                const branchN = this.stmts.countBranchCommitsSince.get(t.branchId, touchTs).n;
+                reason = branchN >= 30 ? 'stale-distance' : 'stale-age';
+            }
+            this.stmts.insertThreadArchive.run(null, null, now, reason, t.id);
+            this.stmts.deleteThread.run(t.id);
+            byReason[reason]++;
+            archived++;
+        }
+        return { archived, byReason };
+    }
+    updateThreadLastTouched(threadId, commitId) {
+        this.stmts.updateThreadLastTouched.run(commitId, threadId);
+    }
     listOpenThreads(projectId) {
         const rows = this.stmts.selectOpenThreads.all(projectId);
-        return rows.map(toThread);
+        const now = Date.now();
+        return rows.map(toThread).map((t) => this.attachDecayFlags(t, now));
     }
     listOpenThreadsByBranch(branchId) {
         const rows = this.stmts.selectOpenThreadsByBranch.all(branchId);
-        return rows.map(toThread);
+        const now = Date.now();
+        return rows.map(toThread).map((t) => this.attachDecayFlags(t, now));
+    }
+    /**
+     * Set the derived `stale` (open) or `expired` (watch) flag on a thread by
+     * looking up the touched commit's timestamp and counting project/branch
+     * commits since. Returns a new Thread — never mutates the input.
+     */
+    attachDecayFlags(thread, now) {
+        const touchCommitId = thread.lastTouchedCommit ?? thread.openedInCommit;
+        const touchRow = this.stmts.selectCommitCreatedAt.get(touchCommitId);
+        const touchTs = touchRow?.created_at ?? thread.createdAt.getTime();
+        const projectRow = this.stmts.countProjectCommitsSince.get(thread.projectId, touchTs);
+        const branchRow = this.stmts.countBranchCommitsSince.get(thread.branchId, touchTs);
+        const flag = classifyThread(thread, {
+            touchTs,
+            projectCommitsSince: projectRow.n,
+            branchCommitsSince: branchRow.n,
+            now,
+        });
+        if (flag === 'stale')
+            return { ...thread, stale: true };
+        if (flag === 'expired')
+            return { ...thread, expired: true };
+        return thread;
     }
     /** Move open threads from source branch to target (called during merge). */
     reassignOpenThreads(fromBranchId, toBranchId) {
         this.stmts.reassignThreads.run(toBranchId, fromBranchId);
     }
+    // ─── Trace (fine tier, 02 DELTA) ─────────────────────────────────────────
+    //
+    // Append-only, pull-only. NEVER included in getSessionSnapshot / default load.
+    // Retrieved via project_memory_retrieve(tier: 'trace', window, offset).
+    insertTraceEntry(input) {
+        const now = Date.now();
+        this.stmts.insertTraceEntry.run({
+            id: input.id,
+            project_id: input.projectId,
+            branch_id: input.branchId,
+            note: input.note,
+            git_commit_sha: input.gitCommitSha ?? null,
+            created_at: now,
+        });
+        return {
+            id: input.id,
+            projectId: input.projectId,
+            branchId: input.branchId,
+            note: input.note,
+            gitCommitSha: input.gitCommitSha,
+            createdAt: new Date(now),
+        };
+    }
+    listTraceEntries(projectId, pagination) {
+        const rows = this.stmts.selectTraceEntries.all(projectId, pagination.limit, pagination.offset);
+        return rows.map(toTraceEntry);
+    }
     // ─── Agents ───────────────────────────────────────────────────────────────
     upsertAgent(input) {
         const now = Date.now();
@@ -463,17 +773,37 @@ export class Queries {
         const branchSummary = branch?.headCommitId
             ? (this.getCommit(branch.headCommitId)?.summary ?? '')
             : '';
-        // Last 3 commits on current branch (optionally filtered by agent role)
+        // Recent commits on current branch — windowed via 02 DELTA commitWindow (default 5).
+        const commitWindow = options?.commitWindow ?? 5;
         const recentCommits = options?.agentRole
-            ? this.stmts.selectCommitsByRole.all(branchId, options.agentRole, 3).map(toCommit)
-            : this.listCommits(branchId, { limit: 3, offset: 0 });
-        // All open threads for the project
-        const openThreads = this.listOpenThreads(projectId);
+            ? this.stmts.selectCommitsByRole.all(branchId, options.agentRole, commitWindow).map(toCommit)
+            : this.listCommits(branchId, { limit: commitWindow, offset: 0 });
+        // All open threads (decorated with stale/expired flags by listOpenThreads).
+        // The default snapshot returns only live threads — the curated load (02 DELTA §B/§C):
+        //   • kind='open' threads filtered out when stale=true → counted in staleThreadCount
+        //   • kind='watch' threads filtered out when expired=true → counted in expiredWatchCount
+        // Stale/expired threads stay retrievable via project_memory_threads tool (Step 5).
+        const allOpenThreads = this.listOpenThreads(projectId);
+        let staleThreadCount = 0;
+        let expiredWatchCount = 0;
+        const openThreads = [];
+        for (const t of allOpenThreads) {
+            if (t.stale) {
+                staleThreadCount++;
+                continue;
+            }
+            if (t.expired) {
+                expiredWatchCount++;
+                continue;
+            }
+            openThreads.push(t);
+        }
         const activeClaims = this.listActiveClaims(projectId);
         // Check if the project has been initiated: true if main/master branch has a head commit
         // OR if the current branch has any commits (covers projects without a named main branch)
         const allCommits = this.listCommits(branchId, { limit: 1, offset: 0 });
         const isInitiated = mainBranch?.headCommitId != null || allCommits.length > 0;
+        const planTree = this.getPlanTree(projectId);
         return {
             projectSummary,
             branchName: branch?.name ?? '',
@@ -482,6 +812,9 @@ export class Queries {
             openThreads,
             activeClaims,
             isInitiated,
+            staleThreadCount,
+            expiredWatchCount,
+            planTree,
         };
     }
     // ─── Semantic search (sqlite-vec) ─────────────────────────────────────────
@@ -545,5 +878,162 @@ export class Queries {
             // sqlite-vec not available
         }
     }
+    // ─── plan_nodes (04 DELTA) ────────────────────────────────────────────────
+    /**
+     * Insert a plan tree of arbitrary depth atomically. `level` is semantic:
+     *   - root (parent_id IS NULL) → 'plan'
+     *   - has children at insert time → 'step' (container)
+     *   - no children at insert time → 'task' (leaf)
+     *
+     * Hierarchy is determined by parent_id, not by depth. The depth-based
+     * mapping from earlier 04 DELTA versions was wrong on trees deeper than 3
+     * (Slice at depth 2 would get labeled 'task' but actually had children).
+     * Content-based labeling is correct at any depth.
+     */
+    insertPlanTree(projectId, input) {
+        const now = Date.now();
+        const levelFor = (isRoot, hasChildren) => {
+            if (isRoot)
+                return 'plan';
+            return hasChildren ? 'step' : 'task';
+        };
+        const insertRecursive = (node, parentId, position) => {
+            const id = nanoid();
+            const isRoot = parentId === null;
+            const hasChildren = (node.children?.length ?? 0) > 0;
+            const level = levelFor(isRoot, hasChildren);
+            this.stmts.insertPlanNode.run({
+                id,
+                project_id: projectId,
+                parent_id: parentId,
+                level,
+                title: node.title,
+                status: node.status ?? 'pending',
+                position,
+                git_commit_sha: null,
+                created_at: now,
+                completed_at: null,
+            });
+            const children = node.children?.map((c, i) => insertRecursive(c, id, i)) ?? [];
+            const inserted = toPlanNode(this.stmts.selectPlanNode.get(id));
+            if (children.length)
+                inserted.children = children;
+            return inserted;
+        };
+        return this.db.transaction(() => insertRecursive(input, null, 0))();
+    }
+    /**
+     * Read the active plan tree for a project. Top-level plans with full child
+     * trees and derived `progress = { done, total }` per node — DIRECT-CHILD
+     * semantics: progress.total = number of direct children; progress.done =
+     * number of direct children that are effectively-done. Effectively-done
+     * propagates recursively: a node is effectively-done if (it has no children
+     * AND status='done') OR (it has children AND every child is effectively-done).
+     *
+     * Plans that are effectively-done are excluded from the active view — they
+     * belong in listCompletedPlans.
+     */
+    getPlanTree(projectId) {
+        return this.buildPlanTrees(projectId, (_n, isDone) => !isDone);
+    }
+    /**
+     * List plans (parent_id IS NULL) that are effectively-done. The completed
+     * delivery record — kept indefinitely, never archived.
+     */
+    listCompletedPlans(projectId) {
+        return this.buildPlanTrees(projectId, (_n, isDone) => isDone);
+    }
+    /** Shared tree builder for getPlanTree / listCompletedPlans. */
+    buildPlanTrees(projectId, includeTop) {
+        const rows = this.stmts.listPlanNodesByProject.all(projectId);
+        const byId = new Map();
+        const childrenByParent = new Map();
+        for (const row of rows) {
+            const node = toPlanNode(row);
+            byId.set(node.id, node);
+            if (node.parentId) {
+                if (!childrenByParent.has(node.parentId))
+                    childrenByParent.set(node.parentId, []);
+                childrenByParent.get(node.parentId).push(node);
+            }
+        }
+        for (const node of byId.values()) {
+            const kids = childrenByParent.get(node.id);
+            if (kids) {
+                kids.sort((a, b) => a.position - b.position);
+                node.children = kids;
+            }
+        }
+        // Walk the subtree. For each container (level='plan'|'step'), set
+        // progress = {done: direct children that are complete, total: direct
+        // children count}. Returns whether this node itself is complete.
+        //
+        // Completeness rule (level-aware, depth-agnostic):
+        //   - level='task' (leaf-by-design): complete iff status='done'.
+        //   - level='plan'|'step' (container): complete iff has at least one
+        //     child AND every child is complete.
+        //
+        // Containers with no children are NEVER complete — status='done' on an
+        // empty container is meaningless for the rollup. The level enum is what
+        // distinguishes "this is a leaf, status drives" from "this is a
+        // container, children drive."
+        const walkAndSetProgress = (node) => {
+            if (node.level === 'task') {
+                return node.status === 'done';
+            }
+            // 'plan' or 'step' — container semantics.
+            if (!node.children || node.children.length === 0) {
+                return false;
+            }
+            let doneCount = 0;
+            for (const c of node.children) {
+                if (walkAndSetProgress(c))
+                    doneCount++;
+            }
+            node.progress = { done: doneCount, total: node.children.length };
+            return doneCount === node.children.length;
+        };
+        const tops = [];
+        for (const node of byId.values()) {
+            if (!node.parentId) {
+                const isDone = walkAndSetProgress(node);
+                if (includeTop(node, isDone))
+                    tops.push(node);
+            }
+        }
+        tops.sort((a, b) => a.position - b.position);
+        return tops;
+    }
+    /**
+     * Set a plan node's status. When transitioning to 'done', stamps completed_at
+     * and optionally git_commit_sha (the commit that completed it).
+     */
+    updatePlanNodeStatus(id, status, gitCommitSha) {
+        const completedAt = status === 'done' ? Date.now() : null;
+        this.stmts.updatePlanNodeStatus.run({ id, status, completed_at: completedAt, git_commit_sha: gitCommitSha });
+    }
+    updatePlanNodeTitle(id, title) {
+        this.stmts.updatePlanNodeTitle.run(title, id);
+    }
+    /** Resolve a 6-char handle to a plan node. Throws on prefix collision. */
+    findPlanNodeByHandle(projectId, handle) {
+        const rows = this.stmts.findPlanByHandle.all(projectId, handle);
+        if (rows.length === 0)
+            return undefined;
+        if (rows.length > 1) {
+            throw new Error(`findPlanNodeByHandle: handle '${handle}' matches ${rows.length} plan nodes`);
+        }
+        return toPlanNode(rows[0]);
+    }
+    /** Resolve an exact title match. Throws when the title is ambiguous across nodes. */
+    findPlanNodeByTitle(projectId, title) {
+        const rows = this.stmts.findPlanByTitle.all(projectId, title);
+        if (rows.length === 0)
+            return undefined;
+        if (rows.length > 1) {
+            throw new Error(`findPlanNodeByTitle: title '${title}' matches ${rows.length} plan nodes`);
+        }
+        return toPlanNode(rows[0]);
+    }
 }
 //# sourceMappingURL=queries.js.map