@astrosheep/keiyaku 2.9.9 → 2.9.10

package/build/core/status/board.js

@@ -1,14 +1,19 @@
 import { availableParallelism } from "node:os";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
 import { loadKeiyakuSettings } from "../../config/settings/loader.js";
 import { observeGitRepository } from "../../git/branches.js";
+import { currentLifecycleState } from "../repository-ledger/read-model.js";
+import { parseCarrierIdentity } from "../contract-carrier.js";
+import { KEIYAKU_FILE } from "../../keiyaku.js";
+import { lookupCurrentContract, } from "../repository-ledger/read-model.js";
 import { readExactProjectionStatus, readOperationalProjectionStatusBoard, } from "../projection/index.js";
 import { deriveQueueReadModel, queueMembership, } from "../settlement/index.js";
-import { findOpenArc, getMaxArc, receiptsAfterFence } from "../seal.js";
 import { openTaskStore, readTaskBoard, taskRepositoryFromStore, taskUpdatedAt, } from "../task/index.js";
-import { deriveBootstrapDiagnostics, deriveContractState, hasCurrentPetitionVerdict, isTerminalState, } from "./lifecycle.js";
-import { commissionTarget, evaluateBaseDrift, latestBase, resolveDefaultBranchFromSettings, } from "./drift.js";
-import { computeClaimReconciliation, } from "./reconciliation.js";
-import { readStatusLedgers } from "./ledger-batch.js";
+import { replayBlockingFact, } from "./lifecycle.js";
+import { findRegisteredContractWorktreePathFromModel, stableRepoRoot } from "../worktree-path.js";
+import { evaluateBaseDrift, resolveDefaultBranchFromSettings, } from "./drift.js";
+import { readRepositoryLifecycleSummaries as readStatusLifecycle } from "../repository-ledger/read-model.js";
 // Git object reads benefit from overlap, but a hard cap avoids process and disk contention.
 const STATUS_DRIFT_MAX_CONCURRENCY = 8;
 const STATUS_DRIFT_CONCURRENCY = Math.min(STATUS_DRIFT_MAX_CONCURRENCY, availableParallelism());
@@ -24,10 +29,11 @@ function timestampAge(timestamp, now) {
     return Number.isFinite(value) ? Math.max(0, now - value) : 0;
 }
 export function deriveTaskStatusSummary(board, now) {
-    const eligible = board.tasks.filter((task) => !task.contractId && (task.state === "open" || task.state === "in_progress"));
+    const eligible = board.tasks.filter((task) => !task.contractId && (task.state === "open" || task.state === "in_progress" || task.state === "on_hold"));
     const inProgress = eligible.filter((task) => task.state === "in_progress").length;
+    const onHold = eligible.filter((task) => task.state === "on_hold").length;
     const topTasks = eligible
-        .filter((task) => task.state === "in_progress")
+        .filter((task) => task.state === "in_progress" || task.state === "on_hold")
         .sort(compareTaskStatusRows)
         .map((task) => {
         const updatedAt = taskUpdatedAt(task);
@@ -48,6 +54,7 @@ export function deriveTaskStatusSummary(board, now) {
     return {
         total: eligible.length,
         inProgress,
+        onHold,
         ready,
         blocked,
         omitted: ready + blocked,
@@ -64,6 +71,7 @@ async function readTaskStatusSummary(cwd, now) {
         return {
             total: 0,
             inProgress: 0,
+            onHold: 0,
             ready: 0,
             blocked: 0,
             omitted: 0,
@@ -77,10 +85,7 @@ function isQueueHeadStall(input) {
     return (input.queuePosition === 1 &&
         input.queueLength > 1 &&
         input.state.state === "petitioned" &&
-        !hasCurrentPetitionVerdict(input.entries));
-}
-function findBindEntry(entries) {
-    return entries.find((entry) => entry.kind === "bind");
+        !input.hasVerdict);
 }
 function contractSlugFromId(id) {
     const dot = id.indexOf(".");
@@ -88,44 +93,25 @@ function contractSlugFromId(id) {
         return id.slice(0, dot);
     return id;
 }
-function deriveCurrentArc(entries, bindObjective, lifecycle) {
-    // No explicit arc has ever existed: derive a0 from bind objective.
-    if (getMaxArc(entries) === 0) {
-        const a0Open = lifecycle.state === "bound" || lifecycle.state === "active";
-        return {
-            number: 0,
-            objective: bindObjective ?? "",
-            state: a0Open ? "open" : "closed",
-        };
-    }
-    const arcObjectives = new Map();
-    let currentArc = null;
-    for (const entry of entries) {
-        if (entry.kind === "arc") {
-            arcObjectives.set(entry.data.arc, entry.data.objective);
-            currentArc = {
-                number: entry.data.arc,
-                objective: entry.data.objective,
-                state: "open",
-            };
-            continue;
-        }
-        if (entry.kind === "seal" && entry.data.arc > 0) {
-            currentArc = {
-                number: entry.data.arc,
-                objective: arcObjectives.get(entry.data.arc) ?? bindObjective ?? "",
-                state: "closed",
-            };
-        }
-    }
-    if (currentArc)
-        return currentArc;
+function deriveCurrentArc(model) {
     return {
-        number: 0,
-        objective: bindObjective ?? "",
-        state: "closed",
+        number: model.intent.arc,
+        objective: model.intent.objective,
+        state: model.phase === "active" ? "open" : "closed",
     };
 }
+function bindTitle(model) {
+    const bind = model.history.find(({ entry }) => entry.kind === "bind")?.entry;
+    return bind?.kind === "bind" ? bind.data.title : model.intent.title;
+}
+function lifecycleDiseaseReason(read, contract) {
+    return read.diagnostics.filter((diagnostic) => diagnostic.contract === contract).map((diagnostic) => diagnostic.detail).join("; ");
+}
+function bootstrapReplayBlockers(model) {
+    return model.bootstrapReplay.state === "pending"
+        ? [replayBlockingFact(model.contract, "bootstrap")]
+        : [];
+}
 function deriveNextStep(input) {
     if (input.state.state === "corrupt") {
         return { kind: "inspect-log", detail: "inspect log" };
@@ -152,8 +138,8 @@ function deriveNextStep(input) {
     }
     return { kind: "arc", detail: "arc" };
 }
-function deriveLastActiveAge(entries, now) {
-    const last = entries.at(-1);
+function deriveLastActiveAge(model, now) {
+    const last = model.history.at(-1)?.entry;
     if (!last)
         return {};
     const atMs = Date.parse(last.at);
@@ -202,7 +188,6 @@ export async function readKanshiBoard(cwd, now, opts) {
                 : exactProjection ? { rows: [exactProjection] } : null,
             queueLength: 0,
             diseases: loadedSettings.diseases,
-            claimReconciliation: null,
             targetFilter,
             // Task and contract boards are repository organs; a non-repository cwd
             // cannot truthfully turn their absence into a zero count.
@@ -217,109 +202,121 @@ export async function readKanshiBoard(cwd, now, opts) {
     catch {
         defaultBranch = null;
     }
-    const terminalById = new Map();
-    const ledgers = await readStatusLedgers(cwd);
-    const readableLedgers = [];
-    for (const ledger of ledgers) {
-        if ("error" in ledger)
-            continue;
-        readableLedgers.push(ledger);
-        terminalById.set(ledger.contractId, isTerminalState(deriveContractState(ledger.entries)));
-    }
-    const queueModel = deriveQueueReadModel(readableLedgers);
+    const lifecycle = await readStatusLifecycle(cwd);
+    const stableRoot = await stableRepoRoot(cwd);
+    const terminalById = new Map(lifecycle.contracts.map((model) => [
+        model.contract,
+        model.phase === "claimed" || model.phase === "forfeited",
+    ]));
+    const queueModel = deriveQueueReadModel(lifecycle);
     const boardQueueLength = queueModel.targetQueues.reduce((sum, queue) => sum + queue.ordered.length, 0);
-    const baseDrifts = await evaluateDistinctBaseDrifts(cwd, readableLedgers.flatMap((item) => {
-        const state = deriveContractState(item.entries);
-        return isTerminalState(state) ? [] : (() => {
-            const base = latestBase(item.entries);
-            return base ? [base] : [];
-        })();
+    const baseDrifts = await evaluateDistinctBaseDrifts(cwd, lifecycle.contracts.flatMap((model) => {
+        const outcome = lookupCurrentContract(lifecycle, model.contract);
+        return outcome.status === "healthy" && !terminalById.get(model.contract) ? [model.pins.base] : [];
     }), defaultBranch);
     const contracts = [];
     const commissionPlaces = new Map();
-    // Readable-ledger commission targets retained for post-assembly filter only.
+    // Folded target pins are retained only for post-assembly filtering.
     const derivedTargetById = new Map();
-    for (const item of ledgers) {
-        if ("error" in item) {
-            // Unreadable ledgers have no derivable target and stay under every filter.
-            derivedTargetById.set(item.id, undefined);
-            contracts.push({
-                id: item.id,
-                slug: contractSlugFromId(item.id),
-                title: contractSlugFromId(item.id),
-                state: { state: "corrupt", at: 0, reason: item.error.message },
-                queueHeadStalled: false,
-                arcs: 0,
-                currentArc: { number: 0, objective: "", state: "closed" },
-                nextStep: { kind: "inspect-log", detail: "inspect log" },
-                baseDrift: { state: "unknown", label: "n/a (corrupt ledger)" },
-                after: [],
-                corruptReason: item.error.message,
-                bootstrapDiagnostics: [],
-                queueDiagnostics: [],
-            });
+    for (const model of lifecycle.contracts) {
+        const outcome = lookupCurrentContract(lifecycle, model.contract);
+        const diseaseReason = lifecycleDiseaseReason(lifecycle, model.contract);
+        const state = outcome.status === "healthy"
+            ? currentLifecycleState(model)
+            : { state: "corrupt", at: 0, reason: diseaseReason || "isolated lifecycle disease" };
+        commissionPlaces.set(model.contract, model.resources.worktree?.place ?? null);
+        derivedTargetById.set(model.contract, model.pins.target.ref);
+        const base = model.pins.base;
+        // Terminal lifecycle facts retire their carrier and worktree projections.
+        // Do not interpret a different active workspace-here carrier as terminal
+        // replay debt.
+        if (model.phase === "claimed" || model.phase === "forfeited")
             continue;
-        }
-        const bind = findBindEntry(item.entries);
-        commissionPlaces.set(item.contractId, bind?.data.place ?? null);
-        derivedTargetById.set(item.contractId, commissionTarget(item.entries)?.ref);
-        const base = latestBase(item.entries);
-        const state = deriveContractState(item.entries);
-        if (isTerminalState(state))
-            continue;
-        const after = (bind?.data.after ?? []).map((id) => ({ id, terminal: terminalById.get(id) ?? false }));
-        const currentArc = deriveCurrentArc(item.entries, bind?.data.objective, state);
+        const after = model.causal.after.map((id) => ({ id, terminal: terminalById.get(id) ?? false }));
+        const currentArc = deriveCurrentArc(model);
         const baseDrift = base
             ? baseDrifts.get(base) ?? { state: "unknown", label: "n/a (base drift unavailable)" }
             : { state: "unknown", label: "n/a (no default branch)" };
         const nextStep = deriveNextStep({
-            id: item.contractId,
+            id: model.contract,
             state,
             currentArc,
             baseDrift,
             after,
         });
         if (nextStep.kind === "renew" && baseDrift.state === "drift") {
-            const openArc = findOpenArc(item.entries);
-            let receiptCount = 0;
-            if (openArc) {
-                try {
-                    receiptCount = (await receiptsAfterFence(cwd, item.entries, `keiyaku/${item.contractId}`)).length;
-                }
-                catch {
-                    // A ledger-only here contract may not have a delivery ref yet.
-                }
-            }
-            const sealForecast = openArc ? `seals a${openArc.data.arc} (${receiptCount} receipts), ` : "";
-            nextStep.hint = `run: keiyaku @${item.contractId} renew — ${sealForecast}follows ${baseDrift.defaultBranch} ▲${baseDrift.behindBy}`;
+            nextStep.hint = `run: keiyaku @${model.contract} renew — follows ${baseDrift.defaultBranch} ▲${baseDrift.behindBy}`;
         }
-        const membership = queueMembership(queueModel, item.contractId);
+        const membership = queueMembership(queueModel, model.contract);
         const queuePosition = membership?.position ?? null;
         const targetQueueLength = membership?.queueLength ?? 0;
+        const replayBlockers = bootstrapReplayBlockers(model);
+        const carrierRoot = model.resources.worktree === null
+            ? stableRoot
+            : await findRegisteredContractWorktreePathFromModel(stableRoot, model);
+        if (model.resources.worktree !== null && carrierRoot === undefined) {
+            replayBlockers.unshift(replayBlockingFact(model.contract, "worktree"));
+        }
+        else if (carrierRoot !== undefined) {
+            let carrierIdentity = null;
+            try {
+                carrierIdentity = parseCarrierIdentity(await fs.readFile(path.join(carrierRoot, KEIYAKU_FILE), "utf8"));
+            }
+            catch {
+                carrierIdentity = null;
+            }
+            if (carrierIdentity?.contractId !== model.contract || carrierIdentity.ledgerHead !== model.observedLedgerHead) {
+                const reason = carrierIdentity === null
+                    ? "missing-or-invalid"
+                    : carrierIdentity.contractId !== model.contract
+                        ? "contract-id-mismatch"
+                        : "ledger-head-mismatch";
+                replayBlockers.push(replayBlockingFact(model.contract, "carrier", {
+                    reason,
+                    expected: { contractId: model.contract, ledgerHead: model.observedLedgerHead },
+                    observed: carrierIdentity,
+                }));
+            }
+        }
         contracts.push({
-            id: item.contractId,
-            slug: contractSlugFromId(item.contractId),
-            title: bind?.data.name ?? contractSlugFromId(item.contractId),
+            id: model.contract,
+            slug: contractSlugFromId(model.contract),
+            title: bindTitle(model),
             state,
             queuePosition,
             queueHeadStalled: isQueueHeadStall({
-                entries: item.entries,
                 queuePosition,
                 queueLength: targetQueueLength,
                 state,
+                hasVerdict: model.petition.state === "approved",
             }),
-            arcs: getMaxArc(item.entries),
+            arcs: model.intent.arc,
             currentArc,
             nextStep,
-            ...deriveLastActiveAge(item.entries, now),
-            place: bind?.data.place ?? null,
+            ...deriveLastActiveAge(model, now),
+            place: model.resources.worktree?.place ?? null,
             base,
             baseDrift,
             after,
-            bootstrapDiagnostics: deriveBootstrapDiagnostics(item.entries),
+            lifecycleDiagnostics: outcome.diagnostics,
+            replayBlockers,
             queueDiagnostics: membership ? [...membership.diagnostics] : [],
         });
     }
+    for (const contract of lifecycle.isolatedContracts) {
+        if (lifecycle.contracts.some((model) => model.contract === contract))
+            continue;
+        const reason = lifecycleDiseaseReason(lifecycle, contract) || "isolated lifecycle disease";
+        derivedTargetById.set(contract, undefined);
+        contracts.push({
+            id: contract, slug: contractSlugFromId(contract), title: contractSlugFromId(contract),
+            state: { state: "corrupt", at: 0, reason }, queueHeadStalled: false, arcs: 0,
+            currentArc: { number: 0, objective: "", state: "closed" }, nextStep: { kind: "inspect-log", detail: "inspect log" },
+            baseDrift: { state: "unknown", label: "n/a (corrupt ledger)" }, after: [], corruptReason: reason,
+            lifecycleDiagnostics: lifecycle.diagnostics.filter((diagnostic) => diagnostic.contract === contract),
+            replayBlockers: [], queueDiagnostics: [],
+        });
+    }
     const filteredContracts = targetFilter === null
         ? contracts
         : contracts.filter((contract) => {
@@ -329,7 +326,6 @@ export async function readKanshiBoard(cwd, now, opts) {
     const queueLength = targetFilter === null
         ? boardQueueLength
         : (queueModel.targetQueues.find((queue) => queue.target === targetFilter)?.ordered.length ?? 0);
-    const claimReconciliation = await computeClaimReconciliation(cwd, defaultBranch);
     const exactProjection = opts?.projectionId === undefined
         ? undefined
         : await readExactProjectionStatus(cwd, now, opts.projectionId);
@@ -344,7 +340,6 @@ export async function readKanshiBoard(cwd, now, opts) {
         defaultBranch: defaultBranch?.branch,
         defaultHead: defaultBranch?.head,
         diseases: loadedSettings.diseases,
-        claimReconciliation,
         targetFilter,
         ...(tasks ? { tasks } : {}),
     };

package/build/core/status/lifecycle.js

@@ -1,84 +1,11 @@
-function transitionFromEntry(current, entry) {
-    if (current === "claimed" || current === "forfeited" || current === "corrupt") {
-        return "corrupt";
-    }
-    switch (entry.kind) {
-        case "bind":
-            return "corrupt";
-        case "bootstrap":
-            // Placement legality is owned exclusively by deriveContractState.
-            return "corrupt";
-        case "arc":
-            return current === "bound" || current === "active" ? "active" : "corrupt";
-        case "seal":
-            if (current === "active")
-                return "active";
-            // Derived default arc a0 may seal from bound (bind/bootstrap → seal0 → petition).
-            if (current === "bound" && entry.data.arc === 0)
-                return "active";
-            return "corrupt";
-        case "amend":
-            return current === "petitioned" ? "active" : current;
-        case "renew":
-            return current;
-        case "verdict":
-            if (current !== "petitioned")
-                return "corrupt";
-            return entry.data.result === "rejected" ? "active" : "petitioned";
-        case "petition":
-            return current === "bound" || current === "active" ? "petitioned" : "corrupt";
-        case "claim":
-            return current === "petitioned" ? "claimed" : "corrupt";
-        case "forfeit":
-            return "forfeited";
-    }
-    return "corrupt";
-}
-export function deriveContractState(entries) {
-    if (entries.length === 0 || entries[0]?.kind !== "bind") {
-        return { state: "corrupt", at: 0, reason: "ledger must start with bind" };
-    }
-    const bind = entries[0];
-    let state = "bound";
-    for (let index = 1; index < entries.length; index += 1) {
-        const entry = entries[index];
-        if (entry.kind === "bootstrap") {
-            if (index !== 1 || state !== "bound") {
-                return { state: "corrupt", at: index + 1, reason: "bootstrap must immediately follow bind" };
-            }
-            if (!bind.data.bootstrap) {
-                return { state: "corrupt", at: index + 1, reason: "bootstrap without bind plan" };
-            }
-            // Legal bootstrap is a durable fact and leaves the derived state bound.
-            continue;
-        }
-        const next = transitionFromEntry(state, entry);
-        if (next === "corrupt") {
-            return { state: "corrupt", at: index + 1, reason: `invalid ${entry.kind} after ${state}` };
-        }
-        state = next;
-    }
-    return { state };
-}
-export function deriveBootstrapDiagnostics(entries) {
-    const bind = entries.find((entry) => entry.kind === "bind");
-    if (!bind?.data.bootstrap)
-        return [];
-    if (entries.some((entry) => entry.kind === "bootstrap"))
-        return [];
-    return [{ kind: "plan-without-result" }];
-}
 export function isTerminalState(state) {
     return state.state === "claimed" || state.state === "forfeited";
 }
-/** Current-petition verdict predicate used by board queue-head stall logic. */
-export function hasCurrentPetitionVerdict(entries) {
-    for (let index = entries.length - 1; index >= 0; index -= 1) {
-        const entry = entries[index];
-        if (entry.kind === "verdict")
-            return true;
-        if (entry.kind === "petition")
-            return false;
-    }
-    return false;
+export function replayBlockingFact(contract, surface, carrierMismatch) {
+    return {
+        kind: "incomplete-replay",
+        surface,
+        recoveryCommand: `keiyaku bind --contract ${contract}`,
+        ...(carrierMismatch ? { carrierMismatch } : {}),
+    };
 }

package/build/core/structured-query.js

@@ -0,0 +1,23 @@
+export const STRUCTURED_QUERY_GRAMMAR = "FIELD OP VALUE[,VALUE...] [| FIELD OP VALUE[,VALUE...]]...";
+export const STRUCTURED_QUERY_COMPLETION = "FIELD OP VALUE[,VALUE...]|FIELD OP VALUE[,VALUE...]";
+export const STRUCTURED_QUERY_OPERATORS = ["=", "!=", "~", "<", "<=", ">", ">="];
+export function parseStructuredQuery(input) {
+    const parsed = [];
+    for (const rawTerm of input.expression.split("|")) {
+        if (!rawTerm)
+            input.invalid(`'${input.expression}' must use ${STRUCTURED_QUERY_GRAMMAR}`, parsed);
+        const match = /^([a-z][a-z0-9_-]*)(!=|<=|>=|~|=|<|>)(.*)$/.exec(rawTerm);
+        if (!match)
+            input.invalid(`'${input.expression}' must use ${STRUCTURED_QUERY_GRAMMAR}`, parsed);
+        const field = match[1];
+        const operator = match[2];
+        if (!input.fields.has(field))
+            input.invalid(`unknown field '${field}'`, parsed);
+        const values = match[3].split(",");
+        if (values.some((value) => !value))
+            input.invalid(`field '${field}' has an empty value`, parsed);
+        input.validate(field, operator, values, parsed);
+        parsed.push({ field, operator, values });
+    }
+    return parsed;
+}

package/build/core/target-ref.js

@@ -1,5 +1,5 @@
 import { FlowError } from "../flow-error.js";
-import { fullBranchRefSchema } from "./entry.js";
+import { fullBranchRefSchema } from "./repository-ledger/codec.js";
 /** Prefix bare branch names and validate the full ref. Sole status/bind normalizer. */
 export function normalizeTargetRef(raw) {
     const ref = raw.startsWith("refs/heads/") ? raw : `refs/heads/${raw}`;

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) {