@astrosheep/keiyaku 2.9.9 → 2.9.10

package/build/core/task/settlement-git.js

@@ -2,13 +2,17 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { FlowError } from "../../flow-error.js";
 import { runGitProcess } from "../../git/core.js";
+import { openGitStreamingBatch } from "../../git/streaming-batch.js";
 import { parseTaskDocument } from "./task.js";
-async function gitResult(cwd, args, input, env) {
-    return await runGitProcess(cwd, args, { input, env });
+import { parseTaskCoordinate } from "./coordinate.js";
+async function gitResult(cwd, args, input, env, signal) {
+    return await runGitProcess(cwd, args, { input, env, signal });
 }
-async function git(cwd, args, input, env) {
-    const result = await gitResult(cwd, args, input, env);
+async function git(cwd, args, input, env, signal) {
+    const result = await gitResult(cwd, args, input, env, signal);
     if (result.error) {
+        if (result.error.name === "AbortError")
+            throw result.error;
         throw new FlowError("INTERNAL_STATE", `git ${args[0]} failed: ${result.error.message}`, { cause: result.error });
     }
     if (result.status !== 0) {
@@ -23,15 +27,17 @@ function boardPath(root, source) {
     }
     return relative;
 }
-export async function inspectCurrentBranch(cwd) {
-    const branch = await gitResult(cwd, ["symbolic-ref", "--quiet", "HEAD"]);
+export async function inspectCurrentBranch(cwd, signal) {
+    const branch = await gitResult(cwd, ["symbolic-ref", "--quiet", "HEAD"], undefined, undefined, signal);
     if (branch.error) {
+        if (branch.error.name === "AbortError")
+            throw branch.error;
         throw new FlowError("INTERNAL_STATE", `cannot inspect HEAD: ${branch.error.message}`, { cause: branch.error });
     }
     if (branch.status !== 0 || branch.stdout.trim() === "") {
         throw new FlowError("DETACHED_HEAD", "cannot publish task board from detached HEAD");
     }
-    return { ref: branch.stdout.trim(), head: (await git(cwd, ["rev-parse", "HEAD"])).trim() };
+    return { ref: branch.stdout.trim(), head: (await git(cwd, ["rev-parse", "HEAD"], undefined, undefined, signal)).trim() };
 }
 export async function createTaskBoardCommit(input) {
     const temporaryDirectory = fs.mkdtempSync(path.join(input.gitDir, "keiyaku-task-index-"));
@@ -61,55 +67,64 @@ export async function createTaskMutationCommit(input) {
     const temporaryDirectory = fs.mkdtempSync(path.join(input.gitDir, "keiyaku-task-index-"));
     const env = { GIT_INDEX_FILE: path.join(temporaryDirectory, "index") };
     try {
-        await git(input.cwd, ["read-tree", input.parent], undefined, env);
+        await git(input.cwd, ["read-tree", input.parent], undefined, env, input.signal);
         for (const write of input.writes) {
-            const oid = (await git(input.cwd, ["hash-object", "-w", "--stdin"], write.text)).trim();
+            const oid = (await git(input.cwd, ["hash-object", "-w", "--stdin"], write.text, undefined, input.signal)).trim();
             await git(input.cwd, [
                 "update-index",
                 "--add",
                 "--cacheinfo",
                 `100644,${oid},${taskMutationPath(write)}`,
-            ], undefined, env);
+            ], undefined, env, input.signal);
         }
-        const tree = (await git(input.cwd, ["write-tree"], undefined, env)).trim();
-        const parentTree = (await git(input.cwd, ["show", "-s", "--format=%T", input.parent])).trim();
+        const tree = (await git(input.cwd, ["write-tree"], undefined, env, input.signal)).trim();
+        const parentTree = (await git(input.cwd, ["show", "-s", "--format=%T", input.parent], undefined, undefined, input.signal)).trim();
         if (tree === parentTree)
             return input.parent;
-        return (await git(input.cwd, ["commit-tree", tree, "-p", input.parent, "-m", input.subject])).trim();
+        return (await git(input.cwd, ["commit-tree", tree, "-p", input.parent, "-m", input.subject], undefined, undefined, input.signal)).trim();
     }
     finally {
         fs.rmSync(temporaryDirectory, { recursive: true, force: true });
     }
 }
 /** Stage only the mutated task paths into the real index; leave unrelated entries alone. */
-export async function reconcileTaskMutationIndex(cwd, writes) {
+export async function reconcileTaskMutationIndex(cwd, writes, signal) {
     for (const write of writes) {
-        const oid = (await git(cwd, ["hash-object", "-w", "--stdin"], write.text)).trim();
+        const oid = (await git(cwd, ["hash-object", "-w", "--stdin"], write.text, undefined, signal)).trim();
         await git(cwd, [
             "update-index",
             "--add",
             "--cacheinfo",
             `100644,${oid},${taskMutationPath(write)}`,
-        ]);
+        ], undefined, undefined, signal);
     }
 }
 /**
- * Atomically publish a pathspec-scoped task micro-commit under the hub branch.
+ * Atomically publish a pathspec-scoped task micro-commit on the current checkout branch.
  * Unrelated staged and unstaged non-task bytes are never read into the commit.
  */
 export async function publishTaskMutationCommit(input, deps = {}) {
     let lastError;
     for (let attempt = 0; attempt < 4; attempt += 1) {
-        const branch = await inspectCurrentBranch(input.cwd);
+        input.signal?.throwIfAborted();
+        const branch = await inspectCurrentBranch(input.cwd, input.signal);
         const commit = await createTaskMutationCommit({
             cwd: input.cwd,
             gitDir: input.gitDir,
             parent: branch.head,
             writes: input.writes,
             subject: input.subject,
+            signal: input.signal,
         });
         if (commit === branch.head) {
-            await reconcileTaskMutationIndex(input.cwd, input.writes);
+            input.observeEffect?.({ effect: "task-reconciliation", status: "succeeded", commit, detail: "current" });
+            try {
+                await reconcileTaskMutationIndex(input.cwd, input.writes, input.signal);
+                input.observeEffect?.({ effect: "task-index-reconciliation", status: "succeeded", commit });
+            }
+            catch (error) {
+                input.observeEffect?.({ effect: "task-index-reconciliation", status: "failed", commit, error });
+            }
             return commit;
         }
         try {
@@ -118,12 +133,16 @@ export async function publishTaskMutationCommit(input, deps = {}) {
                 ref: branch.ref,
                 next: commit,
                 expected: branch.head,
+                signal: input.signal,
             }, deps);
+            input.observeEffect?.({ effect: "task-reconciliation", status: "succeeded", commit, detail: "published" });
             try {
-                await reconcileTaskMutationIndex(input.cwd, input.writes);
+                await reconcileTaskMutationIndex(input.cwd, input.writes, input.signal);
+                input.observeEffect?.({ effect: "task-index-reconciliation", status: "succeeded", commit });
             }
-            catch {
+            catch (error) {
                 // Branch fact remains authoritative; index may be repaired by a later mutation.
+                input.observeEffect?.({ effect: "task-index-reconciliation", status: "failed", commit, error });
             }
             return commit;
         }
@@ -131,6 +150,7 @@ export async function publishTaskMutationCommit(input, deps = {}) {
             lastError = error;
         }
     }
+    input.observeEffect?.({ effect: "task-reconciliation", status: "failed", error: lastError });
     throw lastError;
 }
 async function taskTreeEntries(cwd, commit) {
@@ -167,23 +187,139 @@ export async function refHead(cwd, ref) {
     return (await git(cwd, ["rev-parse", ref])).trim();
 }
 export async function taskContractAtCommit(cwd, commit, id) {
-    const sourcePath = `.keiyaku/tasks/${id}.md`;
+    const coordinate = parseTaskCoordinate(id).coordinate;
+    const sourcePath = `.keiyaku/tasks/${coordinate}.md`;
     const result = await gitResult(cwd, ["show", `${commit}:${sourcePath}`]);
     if (result.status !== 0)
         return undefined;
     return parseTaskDocument({ path: sourcePath, text: result.stdout }).contractId;
 }
+async function taskDocumentAtCommit(cwd, commit, taskId) {
+    let coordinate;
+    try {
+        coordinate = parseTaskCoordinate(taskId);
+    }
+    catch {
+        throw new FlowError("INTERNAL_STATE", `bind base ${commit} names noncanonical task id ${taskId}`);
+    }
+    const sourcePath = `.keiyaku/tasks/${coordinate.coordinate}.md`;
+    const result = await gitResult(cwd, ["show", `${commit}:${sourcePath}`]);
+    if (result.status !== 0 || result.error) {
+        throw new FlowError("INTERNAL_STATE", `bind base ${commit} is missing task ${taskId}`, { cause: result.error });
+    }
+    const document = parseTaskDocument({ path: sourcePath, text: result.stdout });
+    if (document.id !== coordinate.localId) {
+        throw new FlowError("INTERNAL_STATE", `bind base ${commit} task path ${taskId} contains ${document.id}`);
+    }
+    return document;
+}
+async function readTaskAdmissionEvidence(input, readDocument = taskDocumentAtCommit) {
+    if (input.selectedTaskIds.length === 0 || new Set(input.selectedTaskIds).size !== input.selectedTaskIds.length) {
+        throw new FlowError("INTERNAL_STATE", `task-selected bind ${input.bindObjectId} must name unique selected tasks`);
+    }
+    const cache = new Map();
+    const read = async (taskId) => {
+        const cached = cache.get(taskId);
+        if (cached)
+            return cached;
+        const document = await readDocument(input.cwd, input.base, taskId);
+        cache.set(taskId, document);
+        return document;
+    };
+    const selected = [];
+    for (const taskId of input.selectedTaskIds) {
+        const document = await read(taskId);
+        if (document.contractId !== input.contract || document.state !== "open") {
+            throw new FlowError("INTERNAL_STATE", `bind base ${input.base} task ${taskId} does not carry open linkage to ${input.contract}`);
+        }
+        const needs = [];
+        for (const need of document.needs) {
+            const prerequisite = await read(need);
+            if (prerequisite.state !== "done" && prerequisite.state !== "drop") {
+                throw new FlowError("INTERNAL_STATE", `bind base ${input.base} task ${taskId} has unsatisfied need ${need}`);
+            }
+            needs.push({ taskId: need, state: prerequisite.state });
+        }
+        selected.push({ taskId, needs });
+    }
+    return {
+        bindObjectId: input.bindObjectId,
+        base: input.base,
+        selected,
+    };
+}
+/** Immutable current bind-time task linkage and needs evidence; never reads the current board. */
+export async function readTaskAdmissionEvidenceAtCommit(input) {
+    return await readTaskAdmissionEvidence(input);
+}
+/** Read every bind-time task document in one lifecycle observation through one Git process. */
+export function openTaskAdmissionEvidenceReader(cwd) {
+    const batch = openGitStreamingBatch(cwd);
+    const documents = new Map();
+    let transportFailed = false;
+    const readDocument = async (_cwd, commit, taskId) => {
+        let coordinate;
+        try {
+            coordinate = parseTaskCoordinate(taskId);
+        }
+        catch {
+            throw new FlowError("INTERNAL_STATE", `bind base ${commit} names noncanonical task id ${taskId}`);
+        }
+        const sourcePath = `.keiyaku/tasks/${coordinate.coordinate}.md`;
+        const expression = `${commit}:${sourcePath}`;
+        const cached = documents.get(expression);
+        if (cached)
+            return cached;
+        let result;
+        try {
+            result = await batch.request(expression);
+        }
+        catch (error) {
+            transportFailed = true;
+            throw new FlowError("INTERNAL_STATE", `cannot read bind base ${commit} task ${taskId}`, { cause: error });
+        }
+        if (result.kind !== "object" || result.record.type !== "blob") {
+            throw new FlowError("INTERNAL_STATE", `bind base ${commit} is missing task ${taskId}`);
+        }
+        const document = parseTaskDocument({ path: sourcePath, text: result.record.content.toString("utf8") });
+        if (document.id !== coordinate.localId) {
+            throw new FlowError("INTERNAL_STATE", `bind base ${commit} task path ${taskId} contains ${document.id}`);
+        }
+        documents.set(expression, document);
+        return document;
+    };
+    return {
+        read: async (input) => await readTaskAdmissionEvidence(input, readDocument),
+        close: async () => {
+            try {
+                const fact = await batch.close();
+                if (!transportFailed && (fact.timedOut || fact.code !== 0 || fact.signal !== null)) {
+                    const detail = fact.stderr.toString("utf8").trim() || `exit ${String(fact.code)}`;
+                    throw new FlowError("INTERNAL_STATE", `git cat-file --batch failed while reading task evidence: ${detail}`);
+                }
+            }
+            catch (error) {
+                if (transportFailed)
+                    return;
+                if (error instanceof FlowError)
+                    throw error;
+                throw new FlowError("INTERNAL_STATE", "cannot close task evidence batch reader", { cause: error });
+            }
+        },
+    };
+}
 /** Bound task ids and their complete parent ancestry from the immutable bind base. */
 export async function taskSettlementOwnershipAtCommit(cwd, commit, contractId) {
     const documents = new Map();
     for (const entry of await taskTreeEntries(cwd, commit)) {
         const text = await git(cwd, ["cat-file", "blob", entry.oid]);
         const document = parseTaskDocument({ path: entry.path, text });
-        documents.set(document.id, document);
+        const coordinate = parseTaskCoordinate(entry.path.slice(".keiyaku/tasks/".length, -3)).coordinate;
+        documents.set(coordinate, document);
     }
-    const taskIds = [...documents.values()]
-        .filter((document) => document.contractId === contractId)
-        .map((document) => document.id)
+    const taskIds = [...documents]
+        .filter(([, document]) => document.contractId === contractId)
+        .map(([coordinate]) => coordinate)
         .sort();
     const ownedIds = new Set();
     for (const taskId of taskIds) {
@@ -208,7 +344,7 @@ export async function updateBranch(input, deps) {
     if (deps.updateBranch)
         await deps.updateBranch(input);
     else
-        await git(input.cwd, ["update-ref", input.ref, input.next, input.expected]);
+        await git(input.cwd, ["update-ref", input.ref, input.next, input.expected], undefined, undefined, input.signal);
 }
 export async function publishForwardTaskBoardCommit(input, deps) {
     let lastError;
@@ -229,71 +365,6 @@ export async function publishForwardTaskBoardCommit(input, deps) {
     }
     throw lastError;
 }
-async function treeWithoutTasks(cwd, commit, gitDir) {
-    const temporaryDirectory = fs.mkdtempSync(path.join(gitDir, "keiyaku-landing-index-"));
-    const env = { GIT_INDEX_FILE: path.join(temporaryDirectory, "index") };
-    try {
-        await git(cwd, ["read-tree", commit], undefined, env);
-        await git(cwd, ["rm", "-r", "--cached", "-f", "--ignore-unmatch", "--", ".keiyaku/tasks"], undefined, env);
-        return (await git(cwd, ["write-tree"], undefined, env)).trim();
-    }
-    finally {
-        fs.rmSync(temporaryDirectory, { recursive: true, force: true });
-    }
-}
-export async function composeLandingTree(input) {
-    const baseTree = await treeWithoutTasks(input.cwd, input.base, input.gitDir);
-    const targetTree = await treeWithoutTasks(input.cwd, input.target, input.gitDir);
-    const deliveryTree = await treeWithoutTasks(input.cwd, input.delivery, input.gitDir);
-    let mergedTree;
-    try {
-        mergedTree = (await git(input.cwd, [
-            "merge-tree",
-            "--write-tree",
-            "--merge-base",
-            baseTree,
-            targetTree,
-            deliveryTree,
-        ])).trim();
-    }
-    catch (error) {
-        throw new FlowError("CLOSE_MERGE_CONFLICT", "claim merge conflict outside task board", { cause: error });
-    }
-    const temporaryDirectory = fs.mkdtempSync(path.join(input.gitDir, "keiyaku-landing-index-"));
-    const env = { GIT_INDEX_FILE: path.join(temporaryDirectory, "index") };
-    try {
-        await git(input.cwd, ["read-tree", mergedTree], undefined, env);
-        // merge-tree deliberately excluded task paths. Restore the target board as
-        // the inherited baseline, then overlay only settlement-authorized writes.
-        for (const entry of await taskTreeEntries(input.cwd, input.target)) {
-            await git(input.cwd, [
-                "update-index",
-                "--add",
-                "--cacheinfo",
-                `${entry.mode},${entry.oid},${entry.path}`,
-            ], undefined, env);
-        }
-        for (const source of input.sources) {
-            const oid = (await git(input.cwd, ["hash-object", "-w", "--stdin"], source.text)).trim();
-            await git(input.cwd, [
-                "update-index",
-                "--add",
-                "--cacheinfo",
-                `100644,${oid},${boardPath(input.root, source)}`,
-            ], undefined, env);
-        }
-        return (await git(input.cwd, ["write-tree"], undefined, env)).trim();
-    }
-    finally {
-        fs.rmSync(temporaryDirectory, { recursive: true, force: true });
-    }
-}
-function landingCommitMessage(contractId, targetBranch) {
-    return `keiyaku: claim ${contractId}\n\nMerge contract ${contractId} into ${targetBranch}.\n`;
-}
-async function isAncestor(cwd, ancestor, descendant) {
-    return (await gitResult(cwd, ["merge-base", "--is-ancestor", ancestor, descendant])).status === 0;
-}
 export async function taskSourcesAtCommit(cwd, root, commit, paths) {
     const sources = [];
     for (const sourcePath of paths) {
@@ -304,95 +375,9 @@ export async function taskSourcesAtCommit(cwd, root, commit, paths) {
     }
     return sources;
 }
-/**
- * Find the durable landing receipt on the target's first-parent history.
- * Equivalent trees and lookalike messages are insufficient: the commit must
- * have our parent shape, settle every bind-base-owned task, and exactly match
- * a recomposed landing tree over its own first parent.
- */
-export async function findAcceptedLandingCommit(input) {
-    const commits = (await git(input.cwd, ["rev-list", "--first-parent", input.target, `^${input.base}`]))
-        .trim()
-        .split("\n")
-        .filter(Boolean);
-    for (const commit of commits) {
-        const message = await git(input.cwd, ["show", "-s", "--format=%B", commit]);
-        if (message.trimEnd() !== landingCommitMessage(input.contractId, input.targetBranch).trimEnd())
-            continue;
-        const record = (await git(input.cwd, ["rev-list", "--parents", "-n", "1", commit])).trim().split(/\s+/);
-        const parents = record.slice(1);
-        const parentShapeAccepted = parents.length === 2
-            ? parents[1] === input.delivery
-            : parents.length === 1 && await isAncestor(input.cwd, input.delivery, parents[0]);
-        if (!parentShapeAccepted)
-            continue;
-        const sources = await taskSourcesAtCommit(input.cwd, input.root, commit, input.ownedPaths);
-        if (!sources)
-            continue;
-        let settled = false;
-        try {
-            const sourceByPath = new Map(sources.map((source) => [boardPath(input.root, source), source]));
-            settled = input.settledPaths.every((settledPath) => {
-                const source = sourceByPath.get(settledPath);
-                if (!source)
-                    return false;
-                const document = parseTaskDocument(source);
-                return document.state === "done" && document.contractId === undefined;
-            });
-        }
-        catch {
-            // A malformed lookalike is not this operation's durable receipt.
-        }
-        if (!settled)
-            continue;
-        const expectedTree = await composeLandingTree({
-            cwd: input.cwd,
-            gitDir: input.gitDir,
-            root: input.root,
-            base: input.base,
-            target: parents[0],
-            delivery: input.delivery,
-            sources,
-        });
-        const actualTree = (await git(input.cwd, ["show", "-s", "--format=%T", commit])).trim();
-        if (actualTree === expectedTree)
-            return commit;
-    }
-    return undefined;
-}
-export async function containsCommit(cwd, ancestor, descendant) {
-    return await isAncestor(cwd, ancestor, descendant);
-}
-/** Create the landing commit over a previously composed candidate tree. */
-export async function createLandingCommit(input) {
-    // Once delivery is already reachable from target, a single-parent landing
-    // records this claim without fabricating a redundant merge parent.
-    const parents = input.target === input.delivery || await isAncestor(input.cwd, input.delivery, input.target)
-        ? ["-p", input.target]
-        : ["-p", input.target, "-p", input.delivery];
-    return (await git(input.cwd, [
-        "commit-tree",
-        input.tree,
-        ...parents,
-        "-m",
-        `keiyaku: claim ${input.contractId}`,
-        "-m",
-        `Merge contract ${input.contractId} into ${input.targetBranch}.`,
-    ])).trim();
-}
-export async function updateTargetRef(cwd, ref, next, expected) {
-    await git(cwd, ["update-ref", ref, next, expected]);
-}
-export function sameTaskSourceBytes(root, left, right) {
-    const snapshot = (sources) => new Map(sources.map((source) => [boardPath(root, source), source.text]));
-    const leftSnapshot = snapshot(left);
-    const rightSnapshot = snapshot(right);
-    return leftSnapshot.size === rightSnapshot.size
-        && [...leftSnapshot].every(([sourcePath, sourceText]) => rightSnapshot.get(sourcePath) === sourceText);
-}
 export function taskWritesFromSources(sources) {
     return sources.map((source) => ({
-        id: path.basename(source.path, ".md"),
+        id: parseTaskCoordinate(source.path.replaceAll("\\", "/").split("/.keiyaku/tasks/").at(-1).slice(0, -3)).coordinate,
         text: source.text,
     }));
 }

package/build/core/task/settlement-policy.js

@@ -10,12 +10,16 @@ export function requireHealthySettlementBoard(board) {
 function settlementDocument(task, contractId, updatedAt) {
     return {
         id: task.id,
+        namespace: task.namespace,
+        coordinate: task.coordinate,
         title: task.title,
         state: task.state,
         pri: task.pri,
         needs: [...task.needs],
         parent: task.parent,
         from: [...task.from],
+        supersedes: [...task.supersedes],
+        relatesTo: [...task.relatesTo],
         createdAt: task.createdAt,
         updatedAt: advancedTaskUpdatedAt(task, updatedAt),
         creator: task.creator,
@@ -35,22 +39,22 @@ export function reopenedTaskDocument(task, updatedAt) {
 }
 function validateReadyForBind(board, task) {
     if (task.state === "in_progress") {
-        throw new FlowError("INVALID_TARGET", `task ${task.id} is in_progress; stop it before bind`);
+        throw new FlowError("INVALID_TARGET", `task ${task.coordinate} is in_progress; stop it before bind`);
     }
     if (task.state !== "open") {
-        throw new FlowError("INVALID_TARGET", `task ${task.id} is ${task.state}, not ready for bind`);
+        throw new FlowError("INVALID_TARGET", `task ${task.coordinate} is ${task.state}, not ready for bind`);
     }
     const unsatisfied = task.needs
         .filter((need) => {
         const dependency = board.byId.get(need);
-        return dependency.state === "open" || dependency.state === "in_progress";
+        return dependency.state === "open" || dependency.state === "in_progress" || dependency.state === "on_hold";
     })
         .sort();
     if (unsatisfied.length > 0) {
-        throw new FlowError("INVALID_TARGET", `task ${task.id} is blocked by: ${unsatisfied.join(", ")}`);
+        throw new FlowError("INVALID_TARGET", `task ${task.coordinate} is blocked by: ${unsatisfied.join(", ")}`);
     }
     if (task.contractId !== undefined) {
-        throw new FlowError("INVALID_TARGET", `task ${task.id} is already bound to contract ${task.contractId}`);
+        throw new FlowError("INVALID_TARGET", `task ${task.coordinate} is already bound to contract ${task.contractId}`);
     }
 }
 export function selectReadyTasksForBind(board, taskIds) {
@@ -64,17 +68,17 @@ export function selectReadyTasksForBind(board, taskIds) {
     const tasks = [];
     for (const rootId of rootIds) {
         const root = board.byId.get(rootId);
-        if (!admitted.has(root.id)) {
-            admitted.add(root.id);
+        if (!admitted.has(root.coordinate)) {
+            admitted.add(root.coordinate);
             tasks.push(root);
         }
         for (const candidate of board.tasks) {
-            if (candidate.parent === null || admitted.has(candidate.id))
+            if (candidate.parent === null || admitted.has(candidate.coordinate))
                 continue;
             if (candidate.state === "done" || candidate.state === "drop")
                 continue;
             if (isDescendantOf(board, candidate, rootId)) {
-                admitted.add(candidate.id);
+                admitted.add(candidate.coordinate);
                 tasks.push(candidate);
             }
         }
@@ -96,7 +100,7 @@ export function tasksForContract(board, contractId) {
     requireHealthySettlementBoard(board);
     return board.tasks
         .filter((task) => task.contractId === contractId)
-        .sort((left, right) => left.id.localeCompare(right.id));
+        .sort((left, right) => left.coordinate.localeCompare(right.coordinate));
 }
 export function doneTaskReplacements(board, contractId, taskIds, updatedAt) {
     return taskIds.flatMap((taskId) => {
@@ -104,7 +108,7 @@ export function doneTaskReplacements(board, contractId, taskIds, updatedAt) {
         if (task.state === "done" && task.contractId === undefined)
             return [];
         if (task.contractId !== contractId) {
-            throw new FlowError("INTERNAL_STATE", `task ${task.id} no longer points to contract ${contractId} while settling its immutable bind-base ownership`);
+            throw new FlowError("INTERNAL_STATE", `task ${task.coordinate} no longer points to contract ${contractId} while settling its immutable bind-base ownership`);
         }
         const settled = settlementDocument(task, undefined, updatedAt);
         settled.state = "done";

package/build/core/task/source-board.js

@@ -1,6 +1,7 @@
 import { buildTaskBoardFromDocuments } from "./board.js";
 import { parseTaskDocument } from "./document.js";
 import { invalid } from "./validation.js";
+import { taskCoordinateFromSourcePath } from "./coordinate.js";
 function compareText(left, right) {
     return left < right ? -1 : left > right ? 1 : 0;
 }
@@ -10,18 +11,19 @@ function diseaseSort(left, right) {
         || compareText(left.id ?? "", right.id ?? "")
         || compareText(left.message, right.message);
 }
-function sourceBasename(sourcePath) {
-    return sourcePath.split(/[\\/]/).at(-1) ?? "";
-}
 function taskDocument(parsed) {
     return {
         id: parsed.id,
+        namespace: parsed.namespace ?? null,
+        coordinate: parsed.coordinate ?? parsed.id,
         title: parsed.title,
         state: parsed.state,
         pri: parsed.pri,
         needs: [...parsed.needs],
         parent: parsed.parent,
         from: [...parsed.from],
+        supersedes: [...parsed.supersedes],
+        relatesTo: [...parsed.relatesTo],
         createdAt: parsed.createdAt,
         ...(parsed.updatedAt === undefined ? {} : { updatedAt: parsed.updatedAt }),
         creator: parsed.creator,
@@ -34,36 +36,52 @@ export function buildTaskSourceBoard(sources) {
     const sourceDiseases = [];
     const authoritative = [];
     for (const source of [...sources].sort((a, b) => compareText(a.path, b.path))) {
+        let sourceCoordinate;
         try {
+            const coordinate = taskCoordinateFromSourcePath(source.path);
+            sourceCoordinate = coordinate.coordinate;
             const parsed = parseTaskDocument(source);
-            if (sourceBasename(source.path) !== `${parsed.id}.md`) {
+            if (coordinate.localId !== parsed.id) {
                 invalid(`task source basename must be ${parsed.id}.md`);
             }
-            authoritative.push(parsed);
+            for (const [field, relations] of [
+                ["needs", parsed.needs],
+                ["from", parsed.from],
+                ["supersedes", parsed.supersedes],
+                ["relatesTo", parsed.relatesTo],
+            ]) {
+                if (relations.includes(coordinate.coordinate))
+                    invalid(`task field '${field}' must not reference itself`);
+            }
+            if (parsed.parent === coordinate.coordinate)
+                invalid("task field 'parent' must not reference itself");
+            authoritative.push({ ...parsed, namespace: coordinate.namespace, coordinate: coordinate.coordinate });
         }
         catch (error) {
             sourceDiseases.push({
                 code: "invalid_document",
                 path: source.path,
-                message: error instanceof Error ? error.message : String(error),
+                message: `task ${sourceCoordinate ?? source.path} invalid document: ${error instanceof Error ? error.message : String(error)}`,
+                ...(sourceCoordinate === undefined ? {} : { id: sourceCoordinate }),
             });
         }
     }
     const counts = new Map();
     for (const task of authoritative)
-        counts.set(task.id, (counts.get(task.id) ?? 0) + 1);
+        counts.set(task.coordinate, (counts.get(task.coordinate) ?? 0) + 1);
     const candidates = new Map();
     for (const task of authoritative) {
-        if (counts.get(task.id) > 1) {
+        const coordinate = task.coordinate;
+        if (counts.get(coordinate) > 1) {
             sourceDiseases.push({
                 code: "duplicate_id",
                 path: task.source.path,
-                message: `duplicate authoritative task id ${task.id}`,
-                id: task.id,
+                message: `duplicate authoritative task coordinate ${coordinate}`,
+                id: coordinate,
             });
         }
         else {
-            candidates.set(task.id, task);
+            candidates.set(coordinate, task);
         }
     }
     const domainBoard = buildTaskBoardFromDocuments([...candidates.values()].map(taskDocument));
@@ -73,12 +91,12 @@ export function buildTaskSourceBoard(sources) {
     }));
     const tasks = domainBoard.tasks.map((task) => ({
         ...task,
-        path: candidates.get(task.id).source.path,
+        path: candidates.get(task.coordinate).source.path,
     }));
     return {
         tasks,
         diseases: [...sourceDiseases, ...graphDiseases].sort(diseaseSort),
-        byId: new Map(tasks.map((task) => [task.id, task])),
+        byId: new Map(tasks.map((task) => [task.coordinate, task])),
     };
 }
 /** Compatibility name for source-backed board consumers. */