@astrosheep/keiyaku 2.9.8 → 2.9.10

package/build/core/task/board.js

@@ -1,5 +1,5 @@
 import { FlowError } from "../../flow-error.js";
-import { isTaskId } from "./validation.js";
+import { formatTaskCoordinate, parseTaskCoordinate } from "./coordinate.js";
 function compareText(left, right) {
     return left < right ? -1 : left > right ? 1 : 0;
 }
@@ -14,7 +14,16 @@ function taskSort(left, right) {
     return leftTerminal - rightTerminal
         || left.pri - right.pri
         || compareText(left.createdAt, right.createdAt)
-        || compareText(left.id, right.id);
+        || compareText(left.coordinate ?? left.id, right.coordinate ?? right.id);
+}
+function normalizeDocument(task) {
+    const namespace = task.namespace ?? null;
+    const coordinate = task.coordinate ?? formatTaskCoordinate(namespace, task.id);
+    const parsed = parseTaskCoordinate(coordinate);
+    if (parsed.namespace !== namespace || parsed.localId !== task.id) {
+        throw new FlowError("INVALID_TARGET", `task coordinate ${coordinate} does not match its namespace and local id`);
+    }
+    return { ...task, namespace, coordinate };
 }
 function cycleComponents(tasks) {
     let nextIndex = 0;
@@ -59,6 +68,9 @@ function cycleComponents(tasks) {
             visit(id);
     return cycles;
 }
+function supersedesCycleComponents(tasks) {
+    return cycleComponents(new Map([...tasks].map(([id, task]) => [id, { ...task, needs: task.supersedes }])));
+}
 function parentCycleComponents(tasks) {
     const cycles = [];
     const visited = new Set();
@@ -85,21 +97,23 @@ function parentCycleComponents(tasks) {
 }
 /** Derive the complete storage-neutral board from domain records. */
 export function buildTaskBoardFromDocuments(documents) {
+    documents = documents.map(normalizeDocument);
     const diseases = [];
     const counts = new Map();
     for (const task of documents)
-        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 documents) {
-        if (counts.get(task.id) > 1) {
+        const coordinate = task.coordinate;
+        if (counts.get(coordinate) > 1) {
             diseases.push({
                 code: "duplicate_id",
-                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);
         }
     }
     for (const component of cycleComponents(candidates)) {
@@ -114,6 +128,18 @@ export function buildTaskBoardFromDocuments(documents) {
             candidates.delete(id);
         }
     }
+    for (const component of supersedesCycleComponents(candidates)) {
+        const relatedIds = [...component].sort();
+        for (const id of relatedIds) {
+            diseases.push({
+                code: "supersedes_cycle",
+                message: `task ${id} participates in a supersedes cycle`,
+                id,
+                relatedIds,
+            });
+            candidates.delete(id);
+        }
+    }
     for (const component of parentCycleComponents(candidates)) {
         const relatedIds = [...component].sort();
         for (const id of relatedIds) {
@@ -129,7 +155,7 @@ export function buildTaskBoardFromDocuments(documents) {
     while (changed) {
         changed = false;
         for (const [id, task] of [...candidates].sort(([a], [b]) => compareText(a, b))) {
-            const missing = [...task.needs, ...(task.parent ? [task.parent] : []), ...task.from]
+            const missing = [...task.needs, ...(task.parent ? [task.parent] : []), ...task.from, ...task.supersedes, ...task.relatesTo]
                 .filter((related) => !candidates.has(related));
             if (missing.length === 0)
                 continue;
@@ -145,65 +171,74 @@ export function buildTaskBoardFromDocuments(documents) {
         }
     }
     const blocks = new Map();
+    const supersededBy = new Map();
+    const relatedTasks = new Map();
     for (const task of candidates.values()) {
         for (const need of task.needs)
-            blocks.set(need, [...(blocks.get(need) ?? []), task.id]);
+            blocks.set(need, [...(blocks.get(need) ?? []), task.coordinate]);
+        for (const superseded of task.supersedes)
+            supersededBy.set(superseded, [...(supersededBy.get(superseded) ?? []), task.coordinate]);
+        for (const related of task.relatesTo)
+            relatedTasks.set(related, [...(relatedTasks.get(related) ?? []), task.coordinate]);
     }
     const tasks = [...candidates.values()].sort(taskSort).map((task) => {
         const blockingNeeds = task.needs.filter((id) => {
             const state = candidates.get(id).state;
-            return state === "open" || state === "in_progress";
+            return state === "open" || state === "in_progress" || state === "on_hold";
         });
         return {
             id: task.id,
+            namespace: task.namespace ?? null,
+            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,
             ...(task.updatedAt === undefined ? {} : { updatedAt: task.updatedAt }),
             creator: task.creator,
             ...(task.startedAt === undefined ? {} : { startedAt: task.startedAt }),
             ...(task.contractId === undefined ? {} : { contractId: task.contractId }),
             body: task.body,
-            blocks: [...(blocks.get(task.id) ?? [])].sort(),
+            blocks: [...(blocks.get(task.coordinate) ?? [])].sort(),
             blocked: task.state === "open" && blockingNeeds.length > 0,
             releasedNeeds: task.needs.filter((id) => candidates.get(id).state === "drop").sort(),
+            supersededBy: [...(supersededBy.get(task.coordinate) ?? [])].sort(),
+            relatedTasks: [...new Set([...task.relatesTo, ...(relatedTasks.get(task.coordinate) ?? [])])].sort(),
         };
     });
     return {
         tasks,
         diseases: diseases.sort(diseaseSort),
-        byId: new Map(tasks.map((task) => [task.id, task])),
+        byId: new Map(tasks.map((task) => [task.coordinate, task])),
     };
 }
 export function resolveTaskReadId(board, input) {
     return resolveTaskId(board, input);
 }
 export function resolveTaskId(board, input) {
-    if (!isTaskId(input)) {
-        throw new FlowError("INVALID_TARGET", `invalid task id '${input}'`);
-    }
-    if (board.byId.has(input))
-        return input;
+    const requested = parseTaskCoordinate(input);
+    if (board.byId.has(requested.coordinate))
+        return requested.coordinate;
     const matches = board.tasks
-        .map((task) => task.id)
-        .filter((id) => id.startsWith(input))
+        .filter((task) => task.namespace === requested.namespace && task.id.startsWith(requested.localId))
+        .map((task) => task.coordinate)
         .sort();
     if (matches.length === 0)
         throw new FlowError("INVALID_TARGET", `task '${input}' not found`);
     if (matches.length > 1) {
-        throw Object.assign(new FlowError("CONTRACT_AMBIGUOUS", `task prefix '${input}' is ambiguous: ${matches.join(", ")}`), { candidates: matches });
+        throw Object.assign(new FlowError("TASK_AMBIGUOUS", `task prefix '${input}' is ambiguous: ${matches.join(", ")}`, {
+            facts: { kind: "task_ambiguous", candidates: matches },
+        }), { candidates: matches });
     }
     return matches[0];
 }
 export function requireCanonicalTaskId(input) {
-    if (!isTaskId(input)) {
-        throw new FlowError("INVALID_TARGET", "task mutations require a canonical full task id");
-    }
-    return input;
+    return parseTaskCoordinate(input, "task mutation coordinate").coordinate;
 }
 export function requireHealthy(board) {
     if (board.diseases.length > 0) {

package/build/core/task/commands.js

@@ -1,20 +1,26 @@
 import { FlowError } from "../../flow-error.js";
-import { IdentifierSlugError, normalizeIdentifierSlug, SUFFIXABLE_IDENTIFIER_SLUG_MAX_UTF8_BYTES, } from "../identifier-slug.js";
+import { IdentifierSlugError, taskIdentifierSlug, } from "../identifier-slug.js";
+import { markdownSourceSections } from "../scope.js";
 import { requireCanonicalTaskId, requireHealthy, resolveTaskId, } from "./board.js";
 import { dateTimestamp, invalid, nonblank, } from "./validation.js";
 import { advancedTaskUpdatedAt } from "./model.js";
+import { formatTaskCoordinate, parseTaskCoordinate } from "./coordinate.js";
 export async function readTaskBoard(repository) {
     return repository.read();
 }
 function documentFromView(view) {
     return {
         id: view.id,
+        namespace: view.namespace,
+        coordinate: view.coordinate,
         title: view.title,
         state: view.state,
         pri: view.pri,
         needs: [...view.needs],
         parent: view.parent,
         from: [...view.from],
+        supersedes: [...view.supersedes],
+        relatesTo: [...view.relatesTo],
         createdAt: view.createdAt,
         ...(view.updatedAt === undefined ? {} : { updatedAt: view.updatedAt }),
         creator: view.creator,
@@ -23,14 +29,18 @@ function documentFromView(view) {
         body: view.body,
     };
 }
+function documentCoordinate(document) {
+    return document.coordinate ?? formatTaskCoordinate(document.namespace ?? null, document.id);
+}
 function replaceDocument(document, subject) {
     return {
         replacements: [document],
         subject,
         select(resulting) {
-            const value = resulting.byId.get(document.id);
+            const coordinate = documentCoordinate(document);
+            const value = resulting.byId.get(coordinate);
             if (!value)
-                throw new FlowError("INTERNAL_STATE", `mutated task ${document.id} disappeared from the board`);
+                throw new FlowError("INTERNAL_STATE", `mutated task ${coordinate} disappeared from the board`);
             return value;
         },
     };
@@ -44,24 +54,45 @@ function requireExisting(board, id) {
 function resolveMutationIds(board, ids) {
     return ids.map((id) => resolveTaskId(board, id));
 }
+function validateRelations(board, id, supersedes, relatesTo) {
+    if (supersedes.includes(id) || relatesTo.includes(id))
+        invalid(`task ${id} relations must not reference itself`);
+    const seen = new Set();
+    const reachesSource = (current) => {
+        if (current === id)
+            return true;
+        if (seen.has(current))
+            return false;
+        seen.add(current);
+        return (board.byId.get(current)?.supersedes ?? []).some(reachesSource);
+    };
+    for (const target of supersedes) {
+        seen.clear();
+        if (reachesSource(target))
+            invalid(`task ${id} would create a supersedes cycle`);
+    }
+}
+function updateRelations(board, document, field, additions, removals) {
+    const added = resolveMutationIds(board, additions ?? []);
+    if (new Set(added).size !== added.length)
+        invalid(`task ${field} edges must be unique`);
+    const removed = new Set(resolveMutationIds(board, removals ?? []));
+    const retained = (document[field] ?? []).filter((value) => !removed.has(value));
+    if (added.some((value) => retained.includes(value)))
+        invalid(`task ${field} edges must be unique`);
+    document[field] = [...retained, ...added];
+}
 export async function createTask(repository, input, deps) {
     nonblank("title", input.title);
     nonblank("creator", input.creator);
-    let baseId;
-    try {
-        baseId = normalizeIdentifierSlug(input.title, SUFFIXABLE_IDENTIFIER_SLUG_MAX_UTF8_BYTES);
-    }
-    catch (error) {
-        if (error instanceof IdentifierSlugError) {
-            throw new FlowError("INVALID_TARGET", `task title ${error.message}`, { cause: error });
-        }
-        throw error;
-    }
     const pri = input.pri ?? 2;
     if (!Number.isInteger(pri) || pri < 0 || pri > 3)
         invalid("task priority must be an integer from 0 through 3");
     return repository.mutate((board) => {
         requireHealthy(board);
+        const namespace = input.namespace ?? null;
+        if (namespace !== null)
+            parseTaskCoordinate(`${namespace}/task`, "task namespace");
         const needs = resolveMutationIds(board, input.needs ?? []);
         if (new Set(needs).size !== needs.length)
             invalid("task needs must be unique");
@@ -69,34 +100,64 @@ export async function createTask(repository, input, deps) {
         const from = resolveMutationIds(board, input.from ?? []);
         if (new Set(from).size !== from.length)
             invalid("task from edges must be unique");
-        let id = baseId;
-        for (let ordinal = 2; board.byId.has(id); ordinal += 1) {
+        const supersedes = resolveMutationIds(board, input.supersedes ?? []);
+        if (new Set(supersedes).size !== supersedes.length)
+            invalid("task supersedes edges must be unique");
+        const relatesTo = resolveMutationIds(board, input.relatesTo ?? []);
+        if (new Set(relatesTo).size !== relatesTo.length)
+            invalid("task relatesTo edges must be unique");
+        let ordinal = 1;
+        let id;
+        for (;;) {
             if (!Number.isSafeInteger(ordinal)) {
-                throw new FlowError("INTERNAL_STATE", `task id collision ordinal exceeded the safe integer range for ${baseId}`);
+                throw new FlowError("INTERNAL_STATE", "task id collision ordinal exceeded the safe integer range");
+            }
+            try {
+                id = taskIdentifierSlug(input.title, ordinal === 1 ? "" : `-${ordinal}`);
             }
-            id = `${baseId}-${ordinal}`;
+            catch (error) {
+                if (error instanceof IdentifierSlugError) {
+                    throw new FlowError("INVALID_TARGET", `task title ${error.message}`, { cause: error });
+                }
+                throw error;
+            }
+            if (!board.byId.has(formatTaskCoordinate(namespace, id)))
+                break;
+            ordinal += 1;
         }
+        const coordinate = formatTaskCoordinate(namespace, id);
+        validateRelations(board, coordinate, supersedes, relatesTo);
         const now = deps.now();
         const document = {
             id,
+            namespace,
+            coordinate,
             title: input.title,
             state: "open",
             pri,
             needs,
             parent,
             from,
+            supersedes,
+            relatesTo,
             createdAt: dateTimestamp("createdAt", now),
             updatedAt: dateTimestamp("updatedAt", now),
             creator: input.creator,
             body: input.body ?? "",
         };
-        return replaceDocument(document, `Add task ${id}`);
+        return replaceDocument(document, `Add task ${coordinate}`);
     });
 }
 export async function updateTask(repository, fullIdValue, patch, now = new Date()) {
+    return (await updateTaskWithReceipt(repository, fullIdValue, patch, now)).task;
+}
+export async function updateTaskWithReceipt(repository, fullIdValue, patch, now = new Date()) {
     const hasChange = Object.values(patch).some((value) => value !== undefined);
     if (!hasChange)
         throw new FlowError("EMPTY_PARAM", "task update requires at least one change");
+    if (patch.body !== undefined && patch.appendBody !== undefined) {
+        throw new FlowError("EMPTY_PARAM", "task update cannot combine --body and --append");
+    }
     return repository.mutate((board) => {
         requireHealthy(board);
         const id = resolveTaskId(board, fullIdValue);
@@ -106,6 +167,8 @@ export async function updateTask(repository, fullIdValue, patch, now = new Date(
             document.title = nonblank("title", patch.title);
         if (patch.body !== undefined)
             document.body = patch.body;
+        if (patch.appendBody !== undefined)
+            document.body = appendBody(document.body, patch.appendBody);
         if (patch.pri !== undefined) {
             if (!Number.isInteger(patch.pri) || patch.pri < 0 || patch.pri > 3)
                 invalid("task priority must be an integer from 0 through 3");
@@ -119,18 +182,82 @@ export async function updateTask(repository, fullIdValue, patch, now = new Date(
         if (patch.from !== undefined) {
             document.from = [...new Set([...document.from, ...resolveMutationIds(board, patch.from)])];
         }
+        updateRelations(board, document, "supersedes", patch.addSupersedes, patch.dropSupersedes);
+        updateRelations(board, document, "relatesTo", patch.addRelatesTo, patch.dropRelatesTo);
+        validateRelations(board, document.coordinate, document.supersedes, document.relatesTo);
         if (JSON.stringify(document) === JSON.stringify(documentFromView(current))) {
             throw new FlowError("EMPTY_PARAM", "task update requires at least one change");
         }
         document.updatedAt = advancedTaskUpdatedAt(current, now);
-        return replaceDocument(document, `Update task ${id}`);
+        const bodyChange = patch.body === undefined ? undefined : describeBodyChange(current.body, document.body);
+        return {
+            replacements: [document],
+            subject: `Update task ${id}`,
+            select(resulting) {
+                const coordinate = documentCoordinate(document);
+                const task = resulting.byId.get(coordinate);
+                if (!task)
+                    throw new FlowError("INTERNAL_STATE", `mutated task ${coordinate} disappeared from the board`);
+                return { task, ...(bodyChange === undefined ? {} : { bodyChange }) };
+            },
+        };
     });
 }
+function appendBody(body, addition) {
+    if (!body || !addition || body.endsWith("\n\n") || addition.startsWith("\n"))
+        return body + addition;
+    return `${body}${body.endsWith("\n") ? "\n" : "\n\n"}${addition}`;
+}
+function markdownLevelTwoSections(body) {
+    return markdownSourceSections(body)
+        .filter((section) => section.level === 2)
+        .map((section) => section.title.trim());
+}
+function bodyLines(body) {
+    return body.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+}
+function lineDiffstat(before, after) {
+    const oldLines = bodyLines(before);
+    const newLines = bodyLines(after);
+    const lcs = Array(newLines.length + 1).fill(0);
+    for (const oldLine of oldLines) {
+        let previous = 0;
+        for (let index = 1; index <= newLines.length; index += 1) {
+            const saved = lcs[index];
+            lcs[index] = oldLine === newLines[index - 1]
+                ? previous + 1
+                : Math.max(lcs[index], lcs[index - 1]);
+            previous = saved;
+        }
+    }
+    const unchanged = lcs[newLines.length];
+    return { additions: newLines.length - unchanged, deletions: oldLines.length - unchanged };
+}
+function describeBodyChange(before, after) {
+    const remaining = new Map();
+    for (const section of markdownLevelTwoSections(after)) {
+        remaining.set(section, (remaining.get(section) ?? 0) + 1);
+    }
+    const oldBytes = Buffer.byteLength(before, "utf8");
+    const newBytes = Buffer.byteLength(after, "utf8");
+    return {
+        oldBytes,
+        newBytes,
+        removedSections: markdownLevelTwoSections(before).filter((section) => {
+            const count = remaining.get(section) ?? 0;
+            if (count === 0)
+                return true;
+            remaining.set(section, count - 1);
+            return false;
+        }),
+        diffstat: lineDiffstat(before, after),
+    };
+}
 async function transition(repository, fullIdValue, apply, subject, now) {
     return repository.mutate((board) => {
         requireHealthy(board);
         const id = fullIdValue === undefined
-            ? selectSoleInProgress(board).id
+            ? selectSoleInProgress(board).coordinate
             : resolveTaskId(board, fullIdValue);
         const current = requireExisting(board, id);
         const document = documentFromView(current);
@@ -141,17 +268,18 @@ async function transition(repository, fullIdValue, apply, subject, now) {
 }
 function rejectBound(document, action = "state") {
     if (document.contractId !== undefined) {
+        const coordinate = documentCoordinate(document);
         if (action === "drop") {
-            throw new FlowError("UNSUPPORTED_POLICY", `task ${document.id} is bound to contract ${document.contractId}; forfeit the contract before dropping this task`);
+            throw new FlowError("UNSUPPORTED_POLICY", `task ${coordinate} is bound to contract ${document.contractId}; forfeit the contract before dropping this task`);
         }
-        throw new FlowError("UNSUPPORTED_POLICY", `task ${document.id} is bound to contract ${document.contractId}; its state follows the contract`);
+        throw new FlowError("UNSUPPORTED_POLICY", `task ${coordinate} is bound to contract ${document.contractId}; its state follows the contract`);
     }
 }
 export async function startTask(repository, fullId, now) {
     return transition(repository, fullId, (document) => {
         rejectBound(document);
         if (document.state !== "open")
-            invalid(`task ${document.id} is ${document.state}, not open`);
+            invalid(`task ${documentCoordinate(document)} is ${document.state}, not open`);
         document.state = "in_progress";
         document.startedAt = dateTimestamp("startedAt", now);
     }, (id) => `Start task ${id}`, now);
@@ -160,16 +288,34 @@ export async function stopTask(repository, fullId, now = new Date()) {
     return transition(repository, fullId, (document) => {
         rejectBound(document);
         if (document.state !== "in_progress")
-            invalid(`task ${document.id} is ${document.state}, not in_progress`);
+            invalid(`task ${documentCoordinate(document)} is ${document.state}, not in_progress`);
         document.state = "open";
         delete document.startedAt;
     }, (id) => `Stop task ${id}`, now);
 }
-export async function doneTask(repository, fullId, now = new Date()) {
+export async function holdTask(repository, fullId, now = new Date()) {
     return transition(repository, fullId, (document) => {
         rejectBound(document);
         if (document.state !== "open" && document.state !== "in_progress") {
-            invalid(`task ${document.id} is ${document.state}, not open or in_progress`);
+            invalid(`task ${documentCoordinate(document)} is ${document.state}, not open or in_progress`);
+        }
+        document.state = "on_hold";
+        delete document.startedAt;
+    }, (id) => `Hold task ${id}`, now);
+}
+export async function resumeTask(repository, fullId, now = new Date()) {
+    return transition(repository, fullId, (document) => {
+        rejectBound(document);
+        if (document.state !== "on_hold")
+            invalid(`task ${documentCoordinate(document)} is ${document.state}, not on_hold`);
+        document.state = "open";
+    }, (id) => `Resume task ${id}`, now);
+}
+export async function doneTask(repository, fullId, now = new Date()) {
+    return transition(repository, fullId, (document) => {
+        rejectBound(document);
+        if (document.state !== "open" && document.state !== "in_progress" && document.state !== "on_hold") {
+            invalid(`task ${documentCoordinate(document)} is ${document.state}, not open, in_progress, or on_hold`);
         }
         document.state = "done";
         delete document.startedAt;
@@ -178,8 +324,8 @@ export async function doneTask(repository, fullId, now = new Date()) {
 export async function dropTask(repository, fullId, now = new Date()) {
     return transition(repository, fullId, (document) => {
         rejectBound(document, "drop");
-        if (document.state !== "open" && document.state !== "in_progress") {
-            invalid(`task ${document.id} is ${document.state}, not open or in_progress`);
+        if (document.state !== "open" && document.state !== "in_progress" && document.state !== "on_hold") {
+            invalid(`task ${documentCoordinate(document)} is ${document.state}, not open, in_progress, or on_hold`);
         }
         document.state = "drop";
         delete document.startedAt;
@@ -189,11 +335,13 @@ export function selectSoleInProgress(board) {
     const candidates = board.tasks.filter((task) => task.state === "in_progress");
     if (candidates.length === 1)
         return candidates[0];
-    const ids = candidates.map((task) => task.id).sort();
-    const code = candidates.length === 0 ? "INVALID_TARGET" : "CONTRACT_AMBIGUOUS";
+    const ids = candidates.map((task) => task.coordinate).sort();
+    const code = candidates.length === 0 ? "INVALID_TARGET" : "TASK_AMBIGUOUS";
     throw Object.assign(new FlowError(code, candidates.length === 0
         ? "no task in progress"
-        : "more than one task in progress; pass an ID"), { candidates: ids, candidateTasks: candidates });
+        : "more than one task in progress; pass a coordinate", candidates.length === 0 ? undefined : {
+        facts: { kind: "task_ambiguous", candidates: ids },
+    }), { candidates: ids, candidateTasks: candidates });
 }
 /** Reopen task pointers whose contract authority has disappeared. The caller
  * supplies the ledger fact; this operation itself remains storage-neutral. */
@@ -201,7 +349,7 @@ export async function rollbackOrphanTaskPointers(repository, contractIds, now =
     const before = await repository.read();
     const orphans = before.tasks
         .filter((task) => task.contractId !== undefined && !contractIds.has(task.contractId))
-        .map((task) => ({ taskId: task.id, contractId: task.contractId }))
+        .map((task) => ({ taskId: task.coordinate, contractId: task.contractId }))
         .sort((a, b) => a.taskId.localeCompare(b.taskId));
     if (orphans.length === 0)
         return [];
@@ -220,7 +368,7 @@ export async function rollbackOrphanTaskPointers(repository, contractIds, now =
         if (replacements.length === 0)
             throw new FlowError("CONCURRENT_MODIFICATION", "task pointers changed while doctor was reconciling them");
         const subject = replacements.length === 1
-            ? `Clear orphan contract pointer from task ${replacements[0].id}`
+            ? `Clear orphan contract pointer from task ${documentCoordinate(replacements[0])}`
             : `Clear orphan contract pointers from ${replacements.length} tasks`;
         return { replacements, subject, select: () => undefined };
     });

package/build/core/task/coordinate.js

@@ -0,0 +1,56 @@
+import { FlowError } from "../../flow-error.js";
+import { isNormalizedIdentifierSlug } from "../identifier-slug.js";
+import { taskIdentifierSlug } from "../identifier-slug.js";
+export function formatTaskCoordinate(namespace, localId) {
+    return namespace === null ? localId : `${namespace}/${localId}`;
+}
+export function parseTaskCoordinate(value, field = "task coordinate") {
+    const parts = value.split("/");
+    if (parts.length < 1 || parts.length > 2) {
+        throw new FlowError("INVALID_TARGET", `${field} must be <local-id> or <namespace>/<local-id>`);
+    }
+    const namespace = parts.length === 1 ? null : parts[0];
+    const localId = parts.at(-1);
+    if (!isNormalizedIdentifierSlug(localId) || (namespace !== null && !isNormalizedIdentifierSlug(namespace))) {
+        throw new FlowError("INVALID_TARGET", `${field} must be <local-id> or <namespace>/<local-id>`);
+    }
+    return { namespace, localId, coordinate: formatTaskCoordinate(namespace, localId) };
+}
+export function isTaskCoordinate(value) {
+    try {
+        parseTaskCoordinate(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function taskCoordinateFromSourcePath(sourcePath) {
+    const normalized = sourcePath.replaceAll("\\", "/");
+    const marker = "/.keiyaku/tasks/";
+    const markerIndex = normalized.lastIndexOf(marker);
+    const relative = markerIndex < 0 ? normalized : normalized.slice(markerIndex + marker.length);
+    if (!relative.endsWith(".md")) {
+        throw new FlowError("INVALID_TARGET", `task source must be a Markdown file below .keiyaku/tasks: ${sourcePath}`);
+    }
+    return parseTaskCoordinate(relative.slice(0, -3), "task source coordinate");
+}
+export const TASK_NAMESPACE_SCOPE_PREFIX = ".keiyaku/tasks/";
+export function taskNamespaceScope(namespace) {
+    parseTaskCoordinate(`${namespace}/task`, "task namespace");
+    return `${TASK_NAMESPACE_SCOPE_PREFIX}${namespace}/**`;
+}
+export function taskNamespaceFromScope(term) {
+    const match = /^\.keiyaku\/tasks\/([^/]+)\/\*\*$/.exec(term);
+    if (!match || !isNormalizedIdentifierSlug(match[1]))
+        return undefined;
+    return match[1];
+}
+export function allocateTaskNamespace(title, occupied) {
+    for (let ordinal = 1; Number.isSafeInteger(ordinal); ordinal += 1) {
+        const candidate = taskIdentifierSlug(title, ordinal === 1 ? "" : `-${ordinal}`);
+        if (!occupied.has(candidate))
+            return candidate;
+    }
+    throw new FlowError("INTERNAL_STATE", "task namespace collision ordinal exceeded the safe integer range");
+}