@astrosheep/keiyaku 2.9.13 → 4.0.1

package/build/src/settlement/holder.js

@@ -0,0 +1,187 @@
+import { createHash } from "node:crypto";
+import { AuthorityCorruptionError } from "../core/facts/errors.js";
+import { contractId } from "../core/facts/types.js";
+import { withGitTargetedReadObservation, } from "../git/read-observation.js";
+import { parseTaskId } from "../task/identity.js";
+import { acquireTaskSettlementFence } from "./fence.js";
+const HOLDER_ROOT = "settlement/task-holders";
+const HOLDER_PREFIX = `${HOLDER_ROOT}/`;
+const HOLDER_SUFFIX = ".json";
+export function taskHolderObservationSelection() {
+    return { subtrees: [HOLDER_ROOT] };
+}
+function holderPath(taskId) {
+    const digest = createHash("sha256").update(taskId).digest("hex");
+    return `${HOLDER_PREFIX}${digest}${HOLDER_SUFFIX}`;
+}
+function canonicalBytes(holder) {
+    return Buffer.from(`${JSON.stringify(holder)}\n`);
+}
+function corruption(message, cause) {
+    throw new AuthorityCorruptionError(message, cause === undefined ? {} : { cause });
+}
+function decodeHolder(path, bytes) {
+    let value;
+    try {
+        const text = Buffer.from(bytes).toString("utf8");
+        if (!text.endsWith("\n") || text.slice(0, -1).includes("\n"))
+            corruption(`TaskHolder is not one canonical JSON line: ${path}`);
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        if (error instanceof AuthorityCorruptionError)
+            throw error;
+        return corruption(`invalid TaskHolder JSON: ${path}`, error);
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        corruption(`TaskHolder must be an object: ${path}`);
+    const record = value;
+    const keys = Object.keys(record);
+    if (keys.length !== 4 || keys.some((key) => !["version", "taskId", "contractId", "disposition"].includes(key))) {
+        corruption(`TaskHolder has invalid fields: ${path}`);
+    }
+    if (record.version !== 1)
+        corruption(`TaskHolder version must be 1: ${path}`);
+    if (typeof record.taskId !== "string")
+        corruption(`TaskHolder taskId is invalid: ${path}`);
+    if (typeof record.contractId !== "string")
+        corruption(`TaskHolder contractId is invalid: ${path}`);
+    let taskId;
+    let owner;
+    try {
+        parseTaskId(record.taskId);
+        taskId = record.taskId;
+        owner = contractId(record.contractId);
+    }
+    catch (error) {
+        return corruption(`TaskHolder identity is invalid: ${path}`, error);
+    }
+    if (record.disposition !== "held" && record.disposition !== "released") {
+        corruption(`TaskHolder disposition is invalid: ${path}`);
+    }
+    const holder = { version: 1, taskId, contractId: owner, disposition: record.disposition };
+    if (holderPath(taskId) !== path)
+        corruption(`TaskHolder path does not match taskId: ${path}`);
+    if (!Buffer.from(canonicalBytes(holder)).equals(Buffer.from(bytes)))
+        corruption(`TaskHolder bytes are not canonical: ${path}`);
+    return holder;
+}
+function projectTaskHolders(holders) {
+    const projection = new Map();
+    for (const holder of holders) {
+        if (projection.has(holder.contractId)) {
+            corruption(`Contract has multiple current TaskHolders: ${holder.contractId}`);
+        }
+        projection.set(holder.contractId, holder);
+    }
+    return projection;
+}
+function update(holder) {
+    return { path: holderPath(holder.taskId), bytes: canonicalBytes(holder) };
+}
+export function claimTaskHolder(taskId, owner) {
+    return update({ version: 1, taskId, contractId: owner, disposition: "held" });
+}
+function detail(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function finishTaskHolderAdmission(taskId, result, close) {
+    try {
+        close();
+        return { kind: "completed", result };
+    }
+    catch (error) {
+        if (result.kind !== "accepted")
+            throw error;
+        return { kind: "accepted-release-failed", result, taskId, diagnostic: detail(error) };
+    }
+}
+async function admitWithTaskHolderFence(repository, taskId, action) {
+    const held = await acquireTaskSettlementFence(repository, taskId);
+    let result;
+    try {
+        result = await action();
+    }
+    catch (error) {
+        try {
+            held.close();
+        }
+        catch { /* The operation failure remains decisive before admission. */ }
+        throw error;
+    }
+    return finishTaskHolderAdmission(taskId, result, () => held.close());
+}
+export function claimTaskHolderWithFence(repository, taskId, action) {
+    return admitWithTaskHolderFence(repository, taskId, action);
+}
+export async function releaseTaskHolder(channel, observation, owner) {
+    const current = (await readTaskHolderProjectionFromDecision(channel, observation)).get(owner) ?? null;
+    return current === null || current.disposition !== "held"
+        ? null
+        : update({ ...current, disposition: "released" });
+}
+export async function readTaskHolderProjectionFromDecision(channel, observation) {
+    const read = {
+        snapshot: observation.admission.snapshot,
+        readBlobs: async (oids) => {
+            const objects = await channel.readObjects(oids);
+            const blobs = new Map();
+            for (const [oid, object] of objects) {
+                if (object.kind === "missing")
+                    blobs.set(oid, object);
+                else {
+                    if (object.type !== "blob")
+                        corruption(`TaskHolder Git object is not a blob: ${oid}`);
+                    blobs.set(oid, { kind: "present", bytes: object.bytes });
+                }
+            }
+            return blobs;
+        },
+    };
+    return projectTaskHolders(await readTaskHoldersAt(read));
+}
+export function observeTaskHolderProjection(repository, channel) {
+    return withGitTargetedReadObservation(repository, channel, taskHolderObservationSelection(), readTaskHolderProjectionAt);
+}
+async function heldTaskForContract(repository, channel, owner) {
+    const holder = (await observeTaskHolderProjection(repository, channel)).get(owner) ?? null;
+    return holder?.disposition === "held" ? holder.taskId : null;
+}
+export async function releaseTaskHolderWithFence(repository, channel, owner, action) {
+    const taskId = await heldTaskForContract(repository, channel, owner);
+    return taskId === null
+        ? { kind: "completed", result: await action() }
+        : admitWithTaskHolderFence(repository, taskId, action);
+}
+export async function readTaskHoldersAt(observation) {
+    const entries = [...observation.snapshot.paths]
+        .filter(([path, entry]) => path.startsWith(HOLDER_PREFIX) && entry.type === "blob");
+    const blobs = await observation.readBlobs(entries.map(([, entry]) => entry.oid));
+    const holders = [];
+    const seen = new Set();
+    for (const [path, entry] of observation.snapshot.paths) {
+        if (path === HOLDER_ROOT) {
+            if (entry.type !== "tree")
+                corruption(`TaskHolder authority root is not a tree: ${path}`);
+            continue;
+        }
+        if (!path.startsWith(HOLDER_PREFIX))
+            continue;
+        if (!path.endsWith(HOLDER_SUFFIX))
+            corruption(`unexpected TaskHolder authority path: ${path}`);
+        if (entry.type !== "blob")
+            corruption(`TaskHolder path is not a blob: ${path}`);
+        const result = blobs.get(entry.oid);
+        if (result?.kind !== "present")
+            corruption(`missing TaskHolder Git object: ${path}`);
+        const holder = decodeHolder(path, result.bytes);
+        if (seen.has(holder.taskId))
+            corruption(`duplicate TaskHolder identity: ${holder.taskId}`);
+        seen.add(holder.taskId);
+        holders.push(holder);
+    }
+    return holders.sort((left, right) => Buffer.compare(Buffer.from(left.taskId), Buffer.from(right.taskId)));
+}
+export async function readTaskHolderProjectionAt(observation) {
+    return projectTaskHolders(await readTaskHoldersAt(observation));
+}

package/build/src/settlement/settle.d.ts

@@ -0,0 +1,44 @@
+import { type ContractId, type ContractState } from "../core/facts/types.js";
+import type { GitDecodeChannel } from "../git/read-observation.js";
+import type { Effect } from "../git/reconcile.js";
+import type { GitRepository } from "../git/repository.js";
+import type { TaskId } from "../task/identity.js";
+export type SettlementAction = Readonly<{
+    kind: "task";
+    taskId: TaskId;
+    action: "done" | "reopened";
+}> | Readonly<{
+    kind: "namespace-context";
+    path: string;
+    action: "installed" | "kept";
+}>;
+export type SettlementLag = Readonly<{
+    kind: "settlement-failed";
+    surface: "task-holder" | "task" | "namespace-context";
+    contractId: ContractId;
+    taskId?: TaskId;
+    path?: string;
+    diagnostic: string;
+}>;
+export type SettlementReport = Readonly<{
+    actions: readonly SettlementAction[];
+    lags: readonly SettlementLag[];
+}>;
+export declare function deferredTaskHolderSettlement(input: Readonly<{
+    contractId: ContractId;
+    taskId: TaskId;
+    diagnostic: string;
+}>): SettlementReport;
+export type SettlementInput = Readonly<{
+    repository: GitRepository;
+    channel: GitDecodeChannel;
+    state: ContractState | null;
+    effects: readonly Effect[];
+}>;
+export type SettlementBatchInput = Readonly<{
+    repository: GitRepository;
+    channel: GitDecodeChannel;
+    contracts: readonly Readonly<Pick<SettlementInput, "state" | "effects">>[];
+}>;
+export declare function settle(input: SettlementInput): Promise<SettlementReport>;
+export declare function settleAll(input: SettlementBatchInput): Promise<readonly SettlementReport[]>;

package/build/src/settlement/settle.js

@@ -0,0 +1,165 @@
+import { contractSegment } from "../core/facts/types.js";
+import { observeContractsForAdmissionAt } from "../git/observe.js";
+import { repairNamespaceContext } from "../task/context.js";
+import { settleTask } from "../task/operations.js";
+import { observeTaskHolderProjection, readTaskHolderProjectionFromDecision, taskHolderObservationSelection, } from "./holder.js";
+import { withTaskSettlementFence } from "./fence.js";
+import { World } from "../world.js";
+export function deferredTaskHolderSettlement(input) {
+    return { actions: [], lags: [{ kind: "settlement-failed", surface: "task-holder", ...input }] };
+}
+function taskRuleCanApply(state) {
+    const terminal = state?.terminal?.kind;
+    return terminal === "claimed" || terminal === "abandoned";
+}
+function diagnostic(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function taskFailure(result) {
+    return result.kind === "retry"
+        ? `Task settlement requires retry: ${result.reason}`
+        : `Task settlement refused: ${JSON.stringify(result.refusal)}`;
+}
+async function settleTasks(input) {
+    const { observation, repository, world, candidate, actions, lags } = input;
+    const terminal = candidate.terminal?.kind;
+    if (terminal !== "claimed" && terminal !== "abandoned")
+        return;
+    if (observation.kind === "failed") {
+        lags.push({ kind: "settlement-failed", surface: "task-holder", contractId: candidate.id, diagnostic: observation.diagnostic });
+        return;
+    }
+    const holder = observation.holders.get(candidate.id) ?? null;
+    const expectedDisposition = terminal === "claimed" ? "held" : "released";
+    if (holder === null || holder.disposition !== expectedDisposition)
+        return;
+    const taskId = holder.taskId;
+    try {
+        await withTaskSettlementFence({ repository, taskId }, async () => {
+            let current;
+            try {
+                const observation = await observeContractsForAdmissionAt(repository, input.channel, [candidate.id], taskHolderObservationSelection());
+                current = {
+                    state: observation.journals.get(candidate.id)?.state ?? null,
+                    holders: await readTaskHolderProjectionFromDecision(input.channel, observation),
+                };
+            }
+            catch (error) {
+                lags.push({
+                    kind: "settlement-failed",
+                    surface: "task-holder",
+                    contractId: candidate.id,
+                    taskId,
+                    diagnostic: diagnostic(error),
+                });
+                return;
+            }
+            const state = current.state;
+            const currentTerminal = state?.terminal?.kind;
+            if (state === null || (currentTerminal !== "claimed" && currentTerminal !== "abandoned"))
+                return;
+            const currentHolder = current.holders.get(state.id) ?? null;
+            const disposition = currentTerminal === "claimed" ? "held" : "released";
+            if (currentHolder === null || currentHolder.taskId !== taskId || currentHolder.disposition !== disposition)
+                return;
+            try {
+                const result = await settleTask(world, taskId, currentTerminal === "claimed" ? "done" : "open-from-done");
+                if (result.kind === "changed")
+                    actions.push({ kind: "task", taskId, action: result.action });
+                else if (result.kind !== "unchanged")
+                    lags.push({
+                        kind: "settlement-failed",
+                        surface: "task",
+                        contractId: state.id,
+                        taskId,
+                        diagnostic: taskFailure(result),
+                    });
+            }
+            catch (error) {
+                lags.push({ kind: "settlement-failed", surface: "task", contractId: state.id, taskId, diagnostic: diagnostic(error) });
+            }
+        });
+    }
+    catch (error) {
+        lags.push({ kind: "settlement-failed", surface: "task-holder", contractId: candidate.id, taskId, diagnostic: diagnostic(error) });
+    }
+}
+function settleNamespace(state, effects, actions, lags) {
+    if (state.terminal !== null || state.coordinates.workspace !== "worktree")
+        return;
+    const worktrees = effects.filter((effect) => effect.kind === "worktree" && effect.action !== "removed");
+    for (const effect of worktrees) {
+        try {
+            const world = World.at(effect.path);
+            actions.push({
+                kind: "namespace-context",
+                path: effect.path,
+                action: repairNamespaceContext(world, [contractSegment(state.id)]),
+            });
+        }
+        catch (error) {
+            lags.push({
+                kind: "settlement-failed",
+                surface: "namespace-context",
+                contractId: state.id,
+                path: effect.path,
+                diagnostic: diagnostic(error),
+            });
+        }
+    }
+}
+async function observeSettlement(repository, channel) {
+    try {
+        return {
+            kind: "present",
+            holders: await observeTaskHolderProjection(repository, channel),
+        };
+    }
+    catch (error) {
+        return { kind: "failed", diagnostic: diagnostic(error) };
+    }
+}
+async function settleObserved(input, observation) {
+    if (input.state === null)
+        return { actions: [], lags: [] };
+    const actions = [], lags = [];
+    if (observation !== null) {
+        try {
+            await settleTasks({
+                observation,
+                repository: input.repository,
+                channel: input.channel,
+                world: World.at(input.repository.primaryWorktree),
+                candidate: input.state,
+                actions,
+                lags,
+            });
+        }
+        catch (error) {
+            lags.push({ kind: "settlement-failed", surface: "task", contractId: input.state.id, diagnostic: diagnostic(error) });
+        }
+    }
+    settleNamespace(input.state, input.effects, actions, lags);
+    return { actions, lags };
+}
+function onPrimaryWorktree(repository) {
+    return { ...repository, effectiveCwd: repository.primaryWorktree };
+}
+export async function settle(input) {
+    const repository = onPrimaryWorktree(input.repository);
+    const observation = taskRuleCanApply(input.state)
+        ? await observeSettlement(repository, input.channel)
+        : null;
+    return settleObserved({ ...input, repository }, observation);
+}
+export async function settleAll(input) {
+    const repository = onPrimaryWorktree(input.repository);
+    const observation = input.contracts.some((contract) => taskRuleCanApply(contract.state))
+        ? await observeSettlement(repository, input.channel)
+        : null;
+    const reports = [];
+    for (const contract of input.contracts) {
+        reports.push(await settleObserved({ repository, channel: input.channel, ...contract }, observation));
+    }
+    return reports;
+}

package/build/src/task/board.d.ts

@@ -0,0 +1,83 @@
+import type { TaskDocument, TaskPriority, TaskState } from "./document.js";
+import { type TaskId } from "./identity.js";
+export type TaskRef = Readonly<{
+    id: TaskId;
+    title: string | null;
+    state: TaskState | "missing";
+}>;
+export type TaskDisposition = "ready" | "blocked" | "in_progress" | "on_hold" | "done" | "drop";
+export type TaskRow = Readonly<{
+    id: TaskId;
+    title: string;
+    state: TaskState;
+    priority: TaskPriority;
+    disposition: TaskDisposition;
+}>;
+export type BlockedTaskRow = TaskRow & Readonly<{
+    blockers: readonly TaskRef[];
+}>;
+export type TaskDetailFacts = Readonly<{
+    task: TaskDocument;
+    needs: readonly (TaskRef & Readonly<{
+        released: boolean;
+    }>)[];
+    blockers: readonly TaskRef[];
+    blocks: readonly TaskRef[];
+    parent: TaskRef | null;
+    children: readonly TaskRef[];
+    supersedes: readonly TaskRef[];
+    supersededBy: readonly TaskRef[];
+    related: readonly TaskRef[];
+}>;
+export type TaskTreeNode = Readonly<{
+    task: TaskRef & Readonly<{
+        priority: TaskPriority | null;
+    }>;
+    cycle?: true;
+    reference?: true;
+    needs: readonly TaskTreeNode[];
+}>;
+export type TaskBoard = Readonly<{
+    tasks: ReadonlyMap<TaskId, TaskDocument>;
+}>;
+type TaskRelation = "needs" | "parent" | "supersedes" | "relates";
+export type TaskDoctorIssue = Readonly<{
+    kind: "missing-target";
+    taskId: TaskId;
+    relation: TaskRelation;
+    target: TaskId;
+}> | Readonly<{
+    kind: "self-relation";
+    taskId: TaskId;
+    relation: TaskRelation;
+}> | Readonly<{
+    kind: "cycle";
+    relation: "needs" | "parent" | "supersedes";
+    tasks: readonly TaskId[];
+}>;
+export declare function projectDetailFacts(board: TaskBoard, id: TaskId): TaskDetailFacts | null;
+export declare function projectRows(board: TaskBoard, scope: readonly string[] | null, selection: "active" | "closed" | "all"): readonly TaskRow[];
+export declare function projectReady(board: TaskBoard, scope: readonly string[] | null): readonly TaskRow[];
+export declare function projectBlocked(board: TaskBoard, scope: readonly string[] | null): readonly BlockedTaskRow[];
+export declare function projectStatusRows(board: TaskBoard, scope: readonly string[] | null): (Readonly<{
+    id: TaskId;
+    title: string;
+    state: TaskState;
+    priority: TaskPriority;
+    disposition: TaskDisposition;
+}> | {
+    blockers: readonly Readonly<{
+        id: TaskId;
+        title: string | null;
+        state: TaskState | "missing";
+    }>[];
+    id: TaskId;
+    title: string;
+    state: TaskState;
+    priority: TaskPriority;
+    disposition: TaskDisposition;
+})[];
+export declare function relationProblem(board: TaskBoard, before: TaskDocument | null, after: TaskDocument): string | null;
+export declare function diagnoseBoard(board: TaskBoard): readonly TaskDoctorIssue[];
+export declare function buildTree(board: TaskBoard, root: TaskId, full: boolean): TaskTreeNode | null;
+export {};

package/build/src/task/board.js

@@ -0,0 +1,165 @@
+import { parseTaskId, sameNamespace } from "./identity.js";
+const terminal = (state) => state === "done" || state === "drop";
+const sorted = (values) => [...values].sort((a, b) => Buffer.compare(Buffer.from(a.id), Buffer.from(b.id)));
+function taskRef(board, id) {
+    const task = board.tasks.get(id);
+    return task === undefined ? { id, title: null, state: "missing" } : { id, title: task.title, state: task.state };
+}
+function outgoing(document, relation) { return document[relation]; }
+function reverse(board, id, relation) {
+    return sorted([...board.tasks.values()].filter((task) => outgoing(task, relation).includes(id)).map((task) => taskRef(board, task.id)));
+}
+function children(board, id) {
+    return sorted([...board.tasks.values()].filter((task) => task.parent === id).map((task) => taskRef(board, task.id)));
+}
+function related(board, task) {
+    const ids = new Set(task.relates);
+    for (const candidate of board.tasks.values())
+        if (candidate.relates.includes(task.id))
+            ids.add(candidate.id);
+    return sorted([...ids].map((id) => taskRef(board, id)));
+}
+function disposition(board, task) {
+    if (task.state !== "open")
+        return task.state;
+    return task.needs.every((id) => { const target = board.tasks.get(id); return target !== undefined && terminal(target.state); }) ? "ready" : "blocked";
+}
+export function projectDetailFacts(board, id) {
+    const task = board.tasks.get(id);
+    if (task === undefined)
+        return null;
+    const needs = task.needs.map((need) => ({ ...taskRef(board, need), released: board.tasks.has(need) && terminal(board.tasks.get(need).state) }));
+    return {
+        task,
+        needs,
+        blockers: needs.filter((need) => !need.released).map(({ released: _released, ...ref }) => ref),
+        blocks: reverse(board, id, "needs"),
+        parent: task.parent === null ? null : taskRef(board, task.parent), children: children(board, id),
+        supersedes: task.supersedes.map((target) => taskRef(board, target)), supersededBy: reverse(board, id, "supersedes"),
+        related: related(board, task),
+    };
+}
+function inScope(task, scope) { return scope === null || sameNamespace(parseTaskId(task.id).namespace, scope); }
+export function projectRows(board, scope, selection) {
+    return [...board.tasks.values()].filter((task) => inScope(task, scope)).filter((task) => selection === "all"
+        || (selection === "closed") === terminal(task.state)).map((task) => ({
+        id: task.id, title: task.title, state: task.state, priority: task.priority,
+        disposition: disposition(board, task),
+    })).sort((a, b) => a.priority - b.priority || Buffer.compare(Buffer.from(a.id), Buffer.from(b.id)));
+}
+export function projectReady(board, scope) {
+    return projectRows(board, scope, "active").filter((row) => row.disposition === "ready");
+}
+export function projectBlocked(board, scope) {
+    return projectRows(board, scope, "active").flatMap((row) => {
+        if (row.state !== "open" && row.state !== "in_progress")
+            return [];
+        const blockers = projectDetailFacts(board, row.id).blockers;
+        return blockers.length === 0 ? [] : [{ ...row, blockers }];
+    });
+}
+export function projectStatusRows(board, scope) {
+    const blockers = new Map(projectBlocked(board, scope).map((row) => [row.id, row.blockers]));
+    return projectRows(board, scope, "all").map((row) => {
+        const unresolved = blockers.get(row.id);
+        return unresolved === undefined ? row : { ...row, blockers: unresolved };
+    });
+}
+function relationIds(task, relation) {
+    return relation === "parent" ? task.parent === null ? [] : [task.parent] : task[relation];
+}
+export function relationProblem(board, before, after) {
+    for (const relation of ["needs", "parent", "supersedes", "relates"]) {
+        const previous = new Set(before === null ? [] : relationIds(before, relation));
+        for (const target of relationIds(after, relation)) {
+            if (previous.has(target))
+                continue;
+            if (target === after.id)
+                return `${after.id} has a self ${relation} relation`;
+            if (!board.tasks.has(target))
+                return `${after.id} ${relation} target does not exist: ${target}`;
+        }
+    }
+    return null;
+}
+function cycleComponents(board, relation) {
+    const ids = sorted([...board.tasks.keys()].map((id) => ({ id }))).map(({ id }) => id);
+    const edges = new Map(ids.map((id) => [id, relationIds(board.tasks.get(id), relation).filter((target) => board.tasks.has(target))]));
+    const reverse = new Map(ids.map((id) => [id, []]));
+    for (const [id, targets] of edges)
+        for (const target of targets)
+            reverse.get(target).push(id);
+    const visited = new Set(), finished = [];
+    for (const root of ids) {
+        if (visited.has(root))
+            continue;
+        visited.add(root);
+        const stack = [{ id: root, index: 0 }];
+        while (stack.length > 0) {
+            const frame = stack.at(-1), targets = edges.get(frame.id);
+            if (frame.index < targets.length) {
+                const target = targets[frame.index++];
+                if (!visited.has(target)) {
+                    visited.add(target);
+                    stack.push({ id: target, index: 0 });
+                }
+            }
+            else {
+                finished.push(frame.id);
+                stack.pop();
+            }
+        }
+    }
+    const assigned = new Set(), components = [];
+    for (const root of finished.reverse()) {
+        if (assigned.has(root))
+            continue;
+        const component = [], stack = [root];
+        assigned.add(root);
+        while (stack.length > 0) {
+            const id = stack.pop();
+            component.push(id);
+            for (const target of reverse.get(id))
+                if (!assigned.has(target)) {
+                    assigned.add(target);
+                    stack.push(target);
+                }
+        }
+        if (component.length > 1)
+            components.push(sorted(component.map((id) => ({ id }))).map(({ id }) => id));
+    }
+    return components.sort((left, right) => Buffer.compare(Buffer.from(left.join("\0")), Buffer.from(right.join("\0"))));
+}
+export function diagnoseBoard(board) {
+    const issues = [];
+    for (const task of sorted(board.tasks.values()))
+        for (const relation of ["needs", "parent", "supersedes", "relates"]) {
+            for (const target of relationIds(task, relation)) {
+                if (target === task.id)
+                    issues.push({ kind: "self-relation", taskId: task.id, relation });
+                else if (!board.tasks.has(target))
+                    issues.push({ kind: "missing-target", taskId: task.id, relation, target });
+            }
+        }
+    for (const relation of ["needs", "parent", "supersedes"]) {
+        for (const tasks of cycleComponents(board, relation))
+            issues.push({ kind: "cycle", relation, tasks });
+    }
+    return issues;
+}
+export function buildTree(board, root, full) {
+    if (!board.tasks.has(root))
+        return null;
+    const expanded = new Set();
+    const walk = (id, path) => {
+        const ref = taskRef(board, id);
+        const task = board.tasks.get(id);
+        if (path.includes(id))
+            return { task: { ...ref, priority: task?.priority ?? null }, cycle: true, needs: [] };
+        if (!full && expanded.has(id))
+            return { task: { ...ref, priority: task?.priority ?? null }, reference: true, needs: [] };
+        expanded.add(id);
+        return { task: { ...ref, priority: task?.priority ?? null }, needs: task === undefined ? [] : task.needs.map((need) => walk(need, [...path, id])) };
+    };
+    return walk(root, []);
+}

package/build/src/task/compose.d.ts

@@ -0,0 +1,25 @@
+import { type TaskId } from "./identity.js";
+import type { WorldRoot } from "../world.js";
+import type { TaskRefusal, TaskRetry } from "./operations.js";
+type TaskDocumentChange = Readonly<{
+    taskId: TaskId;
+    kind: "created" | "updated";
+    documentDiff: string;
+}>;
+export type TaskCompositionResult = Readonly<{
+    kind: "accepted";
+    documentChanges: readonly TaskDocumentChange[];
+}> | Readonly<{
+    kind: "refused";
+    refusal: TaskRefusal;
+}> | Readonly<{
+    kind: "incomplete";
+    documentChanges: readonly TaskDocumentChange[];
+    stopped: TaskRefusal | Readonly<{
+        kind: "retry";
+        reason: TaskRetry;
+    }>;
+    draft: string;
+}>;
+export declare function composeTasks(world: WorldRoot, markdown: string, signal?: AbortSignal): Promise<TaskCompositionResult>;
+export {};