project-mgr 0.4.0 → 0.5.1

package/dist/db.js

@@ -1,3 +1,4 @@
+import assert from "node:assert/strict";
 import { randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import Database from "better-sqlite3";
@@ -88,6 +89,10 @@ export function openLedger(path = databasePath()) {
       CREATE INDEX idx_todos_project ON todos(project);
       INSERT INTO schema_migrations(version) VALUES (4);`);
         }
+        if (!db.prepare("SELECT 1 FROM schema_migrations WHERE version = 5").get()) {
+            db.exec(`ALTER TABLE status_entries ADD COLUMN next_todo_uids_json TEXT;
+        INSERT INTO schema_migrations(version) VALUES (5);`);
+        }
     }).immediate();
     return db;
 }
@@ -101,6 +106,12 @@ function entryFromRow(row) {
         ...(row.progress ? { progress: row.progress } : {}),
         blockers: JSON.parse(row.blockers_json),
         nextSteps: JSON.parse(row.next_steps_json),
+        // NULL means legacy (field absent). An explicit JSON array, including [], is new format.
+        ...(row.next_todo_uids_json == null
+            ? {}
+            : {
+                nextTodoUids: JSON.parse(row.next_todo_uids_json),
+            }),
         ...(row.next_steps_source_uid
             ? { nextStepsSourceUid: row.next_steps_source_uid }
             : {}),
@@ -215,20 +226,11 @@ export function listProjects(db, options = {}) {
         return false;
     });
 }
-export function addStatus(db, value, defaultSource = "human", completes = []) {
-    const input = validateStatusEntry(value, defaultSource);
-    return db
-        .transaction(() => {
-        const result = addValidatedStatus(db, input);
-        if (result.inserted && !result.entry.nextStepsSourceUid)
-            result.entry.nextSteps.forEach((_, index) => convertNextStep(db, result.entry.uid, index));
-        for (const target of completes)
-            changeCompletion(db, target, result.entry.uid, "complete", undefined, input.source);
-        return result;
-    })
-        .immediate();
+function linkCompletions(db, targets, byUid, source) {
+    for (const target of targets)
+        changeCompletion(db, target, byUid, "complete", undefined, source);
 }
-function addValidatedStatus(db, input, recordedAt) {
+function existingIdentity(db, input, recordedAt, textRetry = false, carry = false) {
     if (input.uid) {
         const existing = one(db, `${select} WHERE e.uid = ?`, input.uid);
         if (existing) {
@@ -237,7 +239,10 @@ function addValidatedStatus(db, input, recordedAt) {
                 id: existing.id,
                 recordedAt: existing.recordedAt,
             });
-            if (!isDeepStrictEqual(toPortableStatusEntry(existing), candidate) ||
+            // Text/ref equivalence is only for addStatus sugar retries, not imports.
+            const sameWrite = isDeepStrictEqual(toPortableStatusEntry(existing), candidate) ||
+                (textRetry && textRefEquivalent(db, existing, input, carry));
+            if (!sameWrite ||
                 (recordedAt !== undefined && recordedAt !== existing.recordedAt))
                 throw new ValidationError("conflicting entry uid");
             return { entry: existing, inserted: false };
@@ -253,6 +258,161 @@ function addValidatedStatus(db, input, recordedAt) {
             return { entry: existing, inserted: false };
         }
     }
+    return undefined;
+}
+function textRefEquivalent(db, existing, input, carry = false) {
+    // Retry against stored pins, never today's open status or latest snapshot.
+    if (existing.nextTodoUids === undefined) {
+        if (!carry || input.nextTodoUids !== undefined || input.nextSteps?.length)
+            return false;
+        return isDeepStrictEqual(toPortableStatusEntry(existing), toPortableStatusEntry({
+            ...input,
+            nextSteps: existing.nextSteps,
+            nextStepsSourceUid: existing.nextStepsSourceUid,
+        }));
+    }
+    if (!carry && input.nextTodoUids !== undefined)
+        return false;
+    assert.ok(input.nextSteps);
+    const titles = input.nextSteps;
+    const size = input.nextTodoUids?.length ?? titles.length;
+    if (carry
+        ? size > existing.nextTodoUids.length
+        : size !== existing.nextTodoUids.length)
+        return false;
+    const candidate = toPortableStatusEntry({
+        ...input,
+        nextSteps: [],
+        nextTodoUids: existing.nextTodoUids,
+        id: existing.id,
+        recordedAt: existing.recordedAt,
+    });
+    if (!isDeepStrictEqual(toPortableStatusEntry(existing), candidate))
+        return false;
+    const suffix = existing.nextTodoUids.slice(existing.nextTodoUids.length - size);
+    return suffix.every((uid, index) => {
+        if (input.nextTodoUids !== undefined)
+            return uid === input.nextTodoUids[index];
+        const todo = todoByUid(db, uid);
+        return todo !== undefined && todo.title === titles[index];
+    });
+}
+export function addStatus(db, value, defaultSource = "human", completes = []) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new ValidationError("entry must be an object");
+    const { nextMode = "replace", closeTodos = [], ...fields } = value;
+    if (nextMode !== "carry" && nextMode !== "replace")
+        throw new ValidationError("invalid nextMode");
+    if (!Array.isArray(closeTodos))
+        throw new ValidationError("closeTodos must be an array");
+    const input = validateStatusEntry(fields, defaultSource);
+    if (input.nextStepsSourceUid)
+        throw new ValidationError("new snapshots cannot set nextStepsSourceUid");
+    return db
+        .transaction(() => {
+        const replay = existingIdentity(db, input, undefined, true, nextMode === "carry");
+        if (replay) {
+            linkCompletions(db, completes, replay.entry.uid, input.source);
+            return replay;
+        }
+        const latest = current(db, input.project)[0];
+        const preserved = latest
+            ? preservedNextWork(db, latest)
+            : { nextSteps: [], nextTodoUids: [] };
+        // Without refs, latest is a pending legacy snapshot: pin its converted indices.
+        const legacy = preserved.nextTodoUids === undefined
+            ? legacySource(db, latest)
+            : undefined;
+        const pins = preserved.nextTodoUids ??
+            legacy.nextSteps.flatMap((_, index) => {
+                const todo = stepTodo(db, legacy.uid, index);
+                return todo ? [todo.uid] : [];
+            });
+        const closing = new Map();
+        for (const value of closeTodos) {
+            const close = record(value, ["uid", "status"]);
+            const uid = validateUid(close.uid);
+            if (close.status !== "completed" && close.status !== "cancelled")
+                throw new ValidationError("invalid closeTodos status");
+            if ((closing.has(uid) && closing.get(uid) !== close.status) ||
+                input.nextTodoUids?.includes(uid))
+                throw new ValidationError("cannot close a Todo in both statuses or also pin it");
+            const todo = todoByUid(db, uid);
+            if (!todo || (todo.project !== input.project && !pins.includes(uid)))
+                throw new ValidationError(`todo ${uid} does not belong to project ${input.project} or its current pins`);
+            closing.set(uid, close.status);
+        }
+        for (const [uid, status] of closing)
+            updateTodo(db, uid, { status });
+        if (nextMode === "carry" && preserved.nextTodoUids === undefined) {
+            if (input.nextSteps.length || input.nextTodoUids !== undefined)
+                throw new ValidationError(`project ${input.project} has unconverted legacy next steps; run pmgr todo-convert --project ${input.project} or pass --replace-next`);
+            const result = addValidatedStatus(db, { ...input, ...preserved });
+            linkCompletions(db, completes, result.entry.uid, input.source);
+            return result;
+        }
+        if (input.nextTodoUids !== undefined)
+            assertSnapshotRefs(db, input.project, input.nextTodoUids);
+        // Freeze candidates before creating this write's Todos: repeated new titles stay separate.
+        // Same-project open Todos plus unassigned open Todos already pinned here.
+        const candidates = [
+            ...listTodos(db, input.project, { status: "open" }),
+            ...pins.flatMap((pin) => {
+                const todo = todoByUid(db, pin);
+                return todo?.project === null && todo.status === "open" ? [todo] : [];
+            }),
+        ];
+        candidates.sort((a, b) => Number(pins.includes(b.uid)) - Number(pins.includes(a.uid)) ||
+            a.createdAt.localeCompare(b.createdAt) ||
+            a.uid.localeCompare(b.uid));
+        const uid = input.uid ?? randomUUID();
+        const newTodos = [];
+        const resolved = input.nextTodoUids ??
+            input.nextSteps.map((title, index) => {
+                const match = input.nextSteps.indexOf(title) === index
+                    ? candidates.find((todo) => todo.title === title)
+                    : undefined;
+                if (match)
+                    return match.uid;
+                const uid = randomUUID();
+                newTodos.push({ uid, title });
+                return uid;
+            });
+        const nextTodoUids = [
+            ...new Set([
+                ...(nextMode === "carry"
+                    ? pins.filter((uid) => todoByUid(db, uid)?.status === "open")
+                    : []),
+                ...resolved,
+            ]),
+        ];
+        if (nextTodoUids.length > 100)
+            throw new ValidationError("nextTodoUids must be an array of at most 100 uuids");
+        const recordedAt = new Date().toISOString();
+        const result = addValidatedStatus(db, { ...input, uid, nextSteps: [], nextTodoUids }, recordedAt);
+        assert.equal(result.inserted, true);
+        newTodos.forEach(({ uid, title }) => {
+            insertTodo(db, {
+                uid,
+                title,
+                project: result.entry.project,
+                entryUid: result.entry.uid,
+                // Provenance indexes the final snapshot, including carried/reused pins.
+                stepIndex: nextTodoUids.indexOf(uid),
+                status: "open",
+                createdAt: recordedAt,
+                completedAt: null,
+            });
+        });
+        linkCompletions(db, completes, result.entry.uid, input.source);
+        return result;
+    })
+        .immediate();
+}
+function addValidatedStatus(db, input, recordedAt) {
+    const existing = existingIdentity(db, input, recordedAt);
+    if (existing)
+        return existing;
     if (input.nextStepsSourceUid) {
         const origin = getEntry(db, input.nextStepsSourceUid);
         if (!origin ||
@@ -268,9 +428,11 @@ function addValidatedStatus(db, input, recordedAt) {
         .prepare("SELECT id FROM projects WHERE slug = ?")
         .get(input.project);
     const result = db
-        .prepare(`INSERT INTO status_entries(project_id, status, summary, progress, blockers_json, next_steps_json, decisions_json, tags_json, occurred_at, recorded_at, source, external_ref, uid, next_steps_source_uid)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-        .run(project.id, input.status, input.summary, input.progress ?? null, JSON.stringify(input.blockers), JSON.stringify(input.nextSteps), JSON.stringify(input.decisions), JSON.stringify(input.tags), input.occurredAt, now, input.source, input.externalRef ?? null, input.uid ?? randomUUID(), input.nextStepsSourceUid ?? null);
+        .prepare(`INSERT INTO status_entries(project_id, status, summary, progress, blockers_json, next_steps_json, decisions_json, tags_json, occurred_at, recorded_at, source, external_ref, uid, next_steps_source_uid, next_todo_uids_json)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(project.id, input.status, input.summary, input.progress ?? null, JSON.stringify(input.blockers), JSON.stringify(input.nextSteps), JSON.stringify(input.decisions), JSON.stringify(input.tags), input.occurredAt, now, input.source, input.externalRef ?? null, input.uid ?? randomUUID(), input.nextStepsSourceUid ?? null, input.nextTodoUids === undefined
+        ? null
+        : JSON.stringify(input.nextTodoUids));
     return {
         entry: one(db, `${select} WHERE e.id = ?`, result.lastInsertRowid),
         inserted: true,
@@ -278,7 +440,14 @@ function addValidatedStatus(db, input, recordedAt) {
 }
 export function importStatuses(db, values) {
     const inputs = values.map((value) => validateStatusEntry(value, "import"));
-    return db.transaction(() => inputs.map((input) => addValidatedStatus(db, input)))();
+    return db.transaction(() => {
+        const results = inputs.map((input) => addValidatedStatus(db, input));
+        // Entry-only imports declare no Todos, so every ref is an omitted dependency.
+        const payloadTodos = new Set();
+        for (const result of results)
+            assertSnapshotRefs(db, result.entry.project, result.entry.nextTodoUids, payloadTodos);
+        return results;
+    })();
 }
 export function current(db, project) {
     const where = project ? " AND p.slug = ?" : "";
@@ -287,6 +456,109 @@ export function current(db, project) {
         .all(...(project ? [project] : []));
     return rows.map((row) => annotateEntry(db, entryFromRow(row)));
 }
+/** Per-project open work from one current() and one Todo scan; no cross-project dedupe. */
+export function openWorkByProject(db, project) {
+    const latest = current(db, project);
+    const byProject = new Map();
+    const unassigned = [];
+    for (const todo of listTodos(db, project)) {
+        if (todo.project === null)
+            unassigned.push(todo);
+        else
+            byProject.set(todo.project, [
+                ...(byProject.get(todo.project) ?? []),
+                todo,
+            ]);
+    }
+    const names = project !== undefined
+        ? [project]
+        : [
+            ...latest.map((entry) => entry.project),
+            ...[...byProject.keys()]
+                .filter((name) => !latest.some((entry) => entry.project === name))
+                .sort(),
+        ];
+    const groups = new Map();
+    for (const name of names) {
+        const items = [];
+        const seen = new Set();
+        const add = (todo, pinIndex) => {
+            if (todo.status !== "open" || seen.has(todo.uid))
+                return;
+            seen.add(todo.uid);
+            items.push({
+                kind: "todo",
+                uid: todo.uid,
+                title: todo.title,
+                project: name,
+                pinned: pinIndex !== null,
+                pinIndex,
+                createdAt: todo.createdAt,
+                entryUid: todo.entryUid,
+            });
+        };
+        const entry = latest.find((entry) => entry.project === name);
+        if (entry?.nextTodoUids !== undefined) {
+            entry.nextTodoUids.forEach((uid, index) => {
+                const todo = todoByUid(db, uid);
+                if (todo)
+                    add(todo, index);
+            });
+        }
+        else if (entry) {
+            const source = legacySource(db, entry);
+            source.nextSteps.forEach((title, index) => {
+                const todo = stepTodo(db, source.uid, index);
+                if (todo)
+                    add(todo, index);
+                else
+                    items.push({
+                        kind: "legacy-step",
+                        project: name,
+                        entryUid: source.uid,
+                        stepIndex: index,
+                        title,
+                        pinned: true,
+                        pinIndex: index,
+                    });
+            });
+        }
+        for (const todo of byProject.get(name) ?? [])
+            add(todo, null);
+        groups.set(name, items);
+    }
+    return { groups, unassigned };
+}
+export function openWork(db, project) {
+    const { groups, unassigned } = openWorkByProject(db, project);
+    if (project !== undefined)
+        return groups.get(project);
+    // Globally, a Todo pinned by several projects appears only under the first.
+    const items = [];
+    const seen = new Set();
+    for (const group of groups.values())
+        for (const item of group) {
+            if (item.kind === "todo") {
+                if (seen.has(item.uid))
+                    continue;
+                seen.add(item.uid);
+            }
+            items.push(item);
+        }
+    for (const todo of unassigned)
+        if (todo.status === "open" && !seen.has(todo.uid))
+            items.push({
+                kind: "todo",
+                uid: todo.uid,
+                title: todo.title,
+                project: null,
+                pinned: false,
+                pinIndex: null,
+                createdAt: todo.createdAt,
+                entryUid: todo.entryUid,
+            });
+    return items;
+}
 export function history(db, project, options = {}) {
     const clauses = [];
     const params = [];
@@ -310,6 +582,7 @@ export function history(db, project, options = {}) {
     return rows.map((row) => annotateEntry(db, entryFromRow(row)));
 }
 export function at(db, project, occurredAt) {
+    // Stored snapshot only. Refs may be present; live Todo titles are not historical.
     return one(db, `${select} WHERE p.slug = ? AND e.occurred_at <= ? ORDER BY e.occurred_at DESC, e.id DESC LIMIT 1`, project, occurredAt);
 }
 export function countEntries(db, project) {
@@ -358,6 +631,9 @@ function annotateEntry(db, entry) {
         ...entry,
         effectiveStatus: followUp ? "completed" : entry.status,
         isCurrent: newest?.id === entry.id,
+        ...(entry.nextTodoUids !== undefined
+            ? { nextTodos: entry.nextTodoUids.map((uid) => resolveNextTodo(db, uid)) }
+            : {}),
         ...(followUp && latest
             ? {
                 completedBy: {
@@ -450,16 +726,13 @@ export function exportLedger(db, project) {
         const rows = db
             .prepare(`SELECT c.* FROM completion_events c JOIN status_entries e ON e.uid = c.target_uid JOIN projects p ON p.id = e.project_id ${project ? "WHERE p.slug = ?" : ""} ORDER BY c.id`)
             .all(...(project ? [project] : []));
-        const todos = listTodos(db, project);
+        const todos = project ? todosVisibleToProject(db, project) : listTodos(db);
+        const version = ledgerVersion(entries, todos);
         return {
-            version: todos.length || entries.some((entry) => entry.nextStepsSourceUid)
-                ? 3
-                : 2,
+            version,
             entries,
             completions: rows.map(completionFromRow),
-            ...(todos.length || entries.some((entry) => entry.nextStepsSourceUid)
-                ? { todos }
-                : {}),
+            ...(version >= 3 ? { todos } : {}),
         };
     })();
 }
@@ -505,11 +778,31 @@ function validateCompletionEvent(value) {
         source: row.source,
     };
 }
+function declaredTodoUids(values) {
+    const uids = new Set();
+    for (const value of values) {
+        if (!value || typeof value !== "object" || !("todos" in value))
+            continue;
+        const todos = value.todos;
+        if (!Array.isArray(todos))
+            continue;
+        for (const todo of todos) {
+            if (todo &&
+                typeof todo === "object" &&
+                "uid" in todo &&
+                typeof todo.uid === "string")
+                uids.add(todo.uid);
+        }
+    }
+    return uids;
+}
 export function importLedger(db, values) {
     // Both legacy entries and versioned bundles are accepted atomically, including JSONL.
     return db
         .transaction(() => {
         const results = [];
+        // Refs must name Todos declared in this payload, not only rows already stored.
+        const payloadTodos = declaredTodoUids(values);
         for (const value of values) {
             if (value && typeof value === "object" && "version" in value) {
                 const bundle = record(value, [
@@ -518,27 +811,37 @@ export function importLedger(db, values) {
                     "completions",
                     "todos",
                 ]);
-                if ((bundle.version !== 2 && bundle.version !== 3) ||
-                    (bundle.version === 3 && !Array.isArray(bundle.todos)) ||
-                    (bundle.version === 2 && bundle.todos !== undefined) ||
+                const version = bundle.version;
+                if ((version !== 2 && version !== 3 && version !== 4) ||
+                    ((version === 3 || version === 4) &&
+                        !Array.isArray(bundle.todos)) ||
+                    (version === 2 && bundle.todos !== undefined) ||
                     !Array.isArray(bundle.entries) ||
                     !Array.isArray(bundle.completions))
                     throw new ValidationError("invalid ledger bundle");
+                const imported = [];
                 for (const item of bundle.entries) {
                     if (!item || typeof item !== "object" || Array.isArray(item))
                         throw new ValidationError("entry must be an object");
                     const { recordedAt, ...input } = item;
                     validateUid(input.uid);
-                    results.push(addValidatedStatus(db, validateStatusEntry(input, "import"), parseTime(recordedAt, "recordedAt")));
+                    const result = addValidatedStatus(db, validateStatusEntry(input, "import"), parseTime(recordedAt, "recordedAt"));
+                    imported.push(result.entry);
+                    results.push(result);
                 }
                 for (const event of bundle.completions)
                     insertCompletion(db, validateCompletionEvent(event));
-                if (bundle.version === 3)
+                if (version === 3 || version === 4)
                     for (const todo of bundle.todos)
                         importTodo(db, todo);
+                for (const entry of imported)
+                    assertSnapshotRefs(db, entry.project, entry.nextTodoUids, payloadTodos);
+            }
+            else {
+                const result = addValidatedStatus(db, validateStatusEntry(value, "import"));
+                results.push(result);
+                assertSnapshotRefs(db, result.entry.project, result.entry.nextTodoUids, payloadTodos);
             }
-            else
-                results.push(addValidatedStatus(db, validateStatusEntry(value, "import")));
         }
         return results;
     })
@@ -546,12 +849,121 @@ export function importLedger(db, values) {
 }
 const todoSelect = `SELECT uid, title, project, entry_uid AS entryUid,
   step_index AS stepIndex, status, created_at AS createdAt, completed_at AS completedAt FROM todos`;
-export function listTodos(db, project) {
+function ledgerVersion(entries, todos) {
+    if (entries.some((entry) => entry.nextTodoUids !== undefined))
+        return 4;
+    if (todos.length > 0 ||
+        entries.some((entry) => entry.nextStepsSourceUid !== undefined))
+        return 3;
+    return 2;
+}
+function todosVisibleToProject(db, project) {
+    return db
+        .prepare(`${todoSelect} WHERE project = ?
+        OR uid IN (
+          SELECT j.value FROM status_entries e
+          JOIN projects p ON p.id = e.project_id
+          JOIN json_each(e.next_todo_uids_json) j
+          WHERE p.slug = ? AND e.next_todo_uids_json IS NOT NULL
+        )
+        ORDER BY created_at, uid`)
+        .all(project, project);
+}
+function todoByUid(db, uid) {
+    return db.prepare(todoSelect + " WHERE uid = ?").get(uid);
+}
+function resolveNextTodo(db, uid) {
+    const todo = todoByUid(db, uid);
+    if (!todo)
+        return { uid, title: uid, status: "open", project: null };
+    return {
+        uid: todo.uid,
+        title: todo.title,
+        status: todo.status,
+        project: todo.project,
+    };
+}
+function assertSnapshotRefs(db, project, uids, payloadTodos) {
+    if (uids === undefined)
+        return;
+    for (const uid of uids) {
+        const todo = todoByUid(db, uid);
+        if (!todo)
+            throw new ValidationError("dangling next todo uid");
+        if (todo.project !== null && todo.project !== project)
+            throw new ValidationError("cross-project next todo ref");
+        if (payloadTodos && !payloadTodos.has(uid))
+            throw new ValidationError("dangling next todo uid");
+    }
+}
+function todoIsReferenced(db, uid) {
+    return (db
+        .prepare(`SELECT 1 AS found FROM status_entries, json_each(next_todo_uids_json)
+         WHERE next_todo_uids_json IS NOT NULL AND json_each.value = ? LIMIT 1`)
+        .get(uid) !== undefined);
+}
+function stepTodo(db, entryUid, index) {
     return db
+        .prepare(todoSelect + " WHERE entry_uid = ? AND step_index = ?")
+        .get(entryUid, index);
+}
+function legacySource(db, entry) {
+    if (!entry.nextStepsSourceUid)
+        return entry;
+    const origin = getEntry(db, entry.nextStepsSourceUid);
+    assert.ok(origin);
+    assert.equal(origin.nextStepsSourceUid, undefined);
+    return origin;
+}
+function preservedNextWork(db, latest) {
+    if (latest.nextTodoUids !== undefined)
+        return { nextSteps: [], nextTodoUids: [...latest.nextTodoUids] };
+    const source = legacySource(db, latest);
+    const pending = source.nextSteps.some((_, index) => stepTodo(db, source.uid, index) === undefined);
+    if (pending)
+        return {
+            nextSteps: [...source.nextSteps],
+            nextStepsSourceUid: source.uid,
+        };
+    return {
+        nextSteps: [],
+        nextTodoUids: source.nextSteps.map((_, index) => {
+            const todo = stepTodo(db, source.uid, index);
+            assert.ok(todo);
+            return todo.uid;
+        }),
+    };
+}
+export function listTodos(db, project, options = {}) {
+    const clauses = [];
+    const params = [];
+    if (project) {
+        clauses.push("project = ?");
+        params.push(project);
+    }
+    if (options.status !== undefined) {
+        if (!["open", "completed", "cancelled"].includes(options.status))
+            throw new ValidationError("invalid todo status");
+        clauses.push("status = ?");
+        params.push(options.status);
+    }
+    const rows = db
         .prepare(todoSelect +
-        (project ? " WHERE project = ?" : "") +
+        (clauses.length ? ` WHERE ${clauses.join(" AND ")}` : "") +
         " ORDER BY created_at, uid")
-        .all(...(project ? [project] : []));
+        .all(...params);
+    const pins = options.status === "open" && project
+        ? current(db, project)[0]?.nextTodoUids
+        : undefined;
+    if (pins?.length) {
+        const rank = new Map(pins.map((uid, index) => [uid, index]));
+        rows.sort((left, right) => {
+            const leftRank = rank.get(left.uid) ?? pins.length;
+            const rightRank = rank.get(right.uid) ?? pins.length;
+            return leftRank - rightRank;
+        });
+    }
+    return rows;
 }
 function insertTodo(db, todo) {
     db.prepare(`INSERT INTO todos(uid,title,project,entry_uid,step_index,status,created_at,completed_at)
@@ -638,15 +1050,21 @@ export function updateTodo(db, uid, value) {
             }
         }
         if (input.project !== undefined) {
-            if (todo.entryUid)
-                throw new ValidationError("source-linked todo project cannot change");
-            todo.project =
-                input.project === null
-                    ? null
-                    : validateProjectMetadataInput({ project: input.project }).project;
-            if (todo.project &&
-                !db.prepare("SELECT 1 FROM projects WHERE slug = ?").get(todo.project))
-                throw new ValidationError("project not found");
+            const nextProject = input.project === null
+                ? null
+                : validateProjectMetadataInput({ project: input.project }).project;
+            if (nextProject !== todo.project) {
+                if (todo.entryUid || todoIsReferenced(db, todo.uid))
+                    throw new ValidationError(todo.entryUid
+                        ? "source-linked todo project cannot change"
+                        : "referenced todo project cannot change");
+                if (nextProject &&
+                    !db
+                        .prepare("SELECT 1 FROM projects WHERE slug = ?")
+                        .get(nextProject))
+                    throw new ValidationError("project not found");
+                todo.project = nextProject;
+            }
         }
         db.prepare("UPDATE todos SET status=?, completed_at=?, project=? WHERE uid=?").run(todo.status, todo.completedAt, todo.project, uid);
         return todo;
@@ -684,11 +1102,17 @@ function importTodo(db, value) {
         const entry = getEntry(db, validateUid(input.entryUid));
         if (!entry || entry.project !== input.project)
             throw new ValidationError("invalid todo source");
-        if (input.stepIndex !== null &&
-            (!Number.isInteger(input.stepIndex) ||
-                Number(input.stepIndex) < 0 ||
-                entry.nextSteps[Number(input.stepIndex)] !== input.title))
-            throw new ValidationError("invalid next step index");
+        if (input.stepIndex !== null) {
+            if (!Number.isInteger(input.stepIndex) || Number(input.stepIndex) < 0)
+                throw new ValidationError("invalid next step index");
+            const index = Number(input.stepIndex);
+            if (entry.nextTodoUids !== undefined) {
+                if (entry.nextTodoUids[index] !== input.uid)
+                    throw new ValidationError("invalid next step index");
+            }
+            else if (entry.nextSteps[index] !== input.title)
+                throw new ValidationError("invalid next step index");
+        }
     }
     else if (input.stepIndex !== null)
         throw new ValidationError("next step requires a source");
@@ -711,18 +1135,18 @@ export function completeActivity(db, ref) {
             return entry;
         const latest = current(db, entry.project)[0];
         const occurredAt = new Date(Math.max(Date.now(), Date.parse(latest.occurredAt) + 1)).toISOString();
-        // Preserve current context without generating another set of next-step Todos.
+        // Copy refs, or keep the full legacy string list until every index is converted.
+        const preserved = preservedNextWork(db, latest);
         const followUp = addValidatedStatus(db, validateStatusEntry({
             project: entry.project,
             status: latest.status,
             summary: `Completed activity #${entry.id}`,
             progress: latest.progress,
             blockers: latest.blockers,
-            nextSteps: latest.nextSteps,
-            nextStepsSourceUid: latest.nextStepsSourceUid ?? latest.uid,
             decisions: latest.decisions,
             tags: latest.tags,
             occurredAt,
+            ...preserved,
         }));
         changeCompletion(db, entry.uid, followUp.entry.uid);
         return getEntry(db, entry.uid);