@astrosheep/keiyaku 4.5.2 → 4.5.4

package/build/src/task/compose-parser.js

@@ -0,0 +1,162 @@
+import { parseTaskId } from "./identity.js";
+function diagnostic(line, reason, token) {
+    return { line, reason, token };
+}
+function sourceLines(source) {
+    const lines = [];
+    let start = 0;
+    let number = 1;
+    while (start < source.length) {
+        let cursor = start;
+        while (cursor < source.length && source[cursor] !== "\n" && source[cursor] !== "\r")
+            cursor += 1;
+        let end = cursor;
+        if (source[cursor] === "\r" && source[cursor + 1] === "\n")
+            end += 2;
+        else if (cursor < source.length)
+            end += 1;
+        lines.push({ number, start, end, text: source.slice(start, cursor) });
+        start = end;
+        number += 1;
+    }
+    if (source.length === 0 || source.endsWith("\n") || source.endsWith("\r")) {
+        lines.push({ number, start: source.length, end: source.length, text: "" });
+    }
+    return lines;
+}
+function withoutFenceSeparator(value) {
+    if (value.endsWith("\r\n"))
+        return value.slice(0, -2);
+    if (value.endsWith("\n") || value.endsWith("\r"))
+        return value.slice(0, -1);
+    return value;
+}
+function parseNamespace(value) {
+    if (value === "")
+        return [];
+    return parseTaskId(`task/${value}/placeholder`).namespace;
+}
+function parseAssignment(text, line) {
+    const matched = /^(as|parent|pri|needs|supersedes|relates)\s*(=|\+=|-=)\s*(.*)$/u.exec(text);
+    if (matched === null)
+        return null;
+    return {
+        field: matched[1],
+        operator: matched[2],
+        value: matched[3],
+        line,
+        token: text,
+    };
+}
+function parseNode(text, line, index) {
+    if (text.startsWith("+ ")) {
+        const title = text.slice(2);
+        return title.trim().length === 0
+            ? diagnostic(line, "new task title must be nonblank", text)
+            : { index, line, kind: "new", title, assignments: [] };
+    }
+    if (!text.startsWith("@task/"))
+        return diagnostic(line, "node must begin with + or @task/", text);
+    try {
+        const id = text.slice(1);
+        parseTaskId(id);
+        return { index, line, kind: "existing", id, assignments: [] };
+    }
+    catch (error) {
+        return diagnostic(line, error instanceof Error ? error.message : String(error), text);
+    }
+}
+function withAssignment(node, assignment) {
+    return { ...node, assignments: [...node.assignments, assignment] };
+}
+function withBody(node, body) {
+    return { ...node, body };
+}
+function replaceNode(nodes, node) {
+    nodes[node.index] = node;
+}
+export function parseTaskComposition(source) {
+    const lines = sourceLines(source);
+    const diagnostics = [];
+    const nodes = [];
+    let namespace;
+    let current;
+    let sawNode = false;
+    let sawNamespace = false;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        const text = line.text.trimStart();
+        if (text.trim().length === 0)
+            continue;
+        if (text.startsWith("ns=")) {
+            if (sawNode || sawNamespace)
+                diagnostics.push(diagnostic(line.number, "namespace must be the first nonblank line", text));
+            else {
+                try {
+                    namespace = parseNamespace(text.slice(3));
+                }
+                catch (error) {
+                    diagnostics.push(diagnostic(line.number, error instanceof Error ? error.message : String(error), text));
+                }
+            }
+            sawNamespace = true;
+            continue;
+        }
+        if (text.startsWith("+ ") || text.startsWith("@task/")) {
+            const parsed = parseNode(text, line.number, nodes.length);
+            if ("reason" in parsed) {
+                diagnostics.push(parsed);
+                current = undefined;
+            }
+            else {
+                nodes.push(parsed);
+                current = parsed;
+            }
+            sawNode = true;
+            continue;
+        }
+        if (current === undefined) {
+            diagnostics.push(diagnostic(line.number, "property must follow a task node", text));
+            continue;
+        }
+        const fence = /^body\s+<<(.+)$/u.exec(text);
+        if (fence !== null) {
+            const token = fence[1];
+            if (!/^[A-Z][A-Z0-9_]{2,31}$/u.test(token)) {
+                diagnostics.push(diagnostic(line.number, "body token must match [A-Z][A-Z0-9_]* with length 3..32", token));
+                continue;
+            }
+            const close = lines.findIndex((candidate, candidateIndex) => candidateIndex > index && candidate.text === token);
+            if (close < 0) {
+                diagnostics.push(diagnostic(line.number, "body fence is not closed", token));
+                break;
+            }
+            const body = withoutFenceSeparator(source.slice(line.end, lines[close].start));
+            if (current.body !== undefined)
+                diagnostics.push(diagnostic(line.number, "body is assigned more than once", text));
+            else {
+                current = withBody(current, { kind: "replace", value: body, line: line.number, token });
+                replaceNode(nodes, current);
+            }
+            index = close;
+            continue;
+        }
+        if (/^body\s*=\s*$/u.test(text)) {
+            if (current.body !== undefined)
+                diagnostics.push(diagnostic(line.number, "body is assigned more than once", text));
+            else {
+                current = withBody(current, { kind: "clear", value: "", line: line.number, token: text });
+                replaceNode(nodes, current);
+            }
+            continue;
+        }
+        const assignment = parseAssignment(text, line.number);
+        if (assignment === null)
+            diagnostics.push(diagnostic(line.number, "unknown compose property", text));
+        else {
+            current = withAssignment(current, assignment);
+            replaceNode(nodes, current);
+        }
+    }
+    return { ...(namespace === undefined ? {} : { namespace }), nodes, diagnostics };
+}

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

@@ -1,18 +1,30 @@
-import { type TaskId } from "./identity.js";
 import type { WorldRoot } from "../world.js";
-import { type TaskRefusal, type TaskRetry } from "./operations.js";
-type TaskDocumentChange = Readonly<{
+import { type TaskCompositionAlias, type TaskCompositionBodyPreview } from "./compose-language.js";
+import type { TaskId } from "./identity.js";
+import type { TaskRefusal, TaskRetry } from "./operations.js";
+export type TaskDocumentChange = Readonly<{
     taskId: TaskId;
     kind: "created" | "updated";
     documentDiff: string;
 }>;
+export type TaskCompositionFacts = Readonly<{
+    aliases: readonly TaskCompositionAlias[];
+    admissionOrder: readonly TaskId[];
+}>;
 export type TaskCompositionResult = Readonly<{
+    kind: "planned";
+    aliases: readonly TaskCompositionAlias[];
+    admissionOrder: readonly TaskId[];
+    bodies: readonly TaskCompositionBodyPreview[];
+}> | Readonly<{
     kind: "accepted";
     documentChanges: readonly TaskDocumentChange[];
-}> | Readonly<{
+} & TaskCompositionFacts> | Readonly<{
     kind: "refused";
-    refusal: TaskRefusal;
-}> | Readonly<{
+    refusal: Extract<TaskRefusal, {
+        kind: "invalid-composition";
+    }>;
+}> | (Readonly<{
     kind: "incomplete";
     documentChanges: readonly TaskDocumentChange[];
     stopped: TaskRefusal | Readonly<{
@@ -20,6 +32,5 @@ export type TaskCompositionResult = Readonly<{
         reason: TaskRetry;
     }>;
     draft: string;
-}>;
-export declare function composeTasks(world: WorldRoot, markdown: string, signal?: AbortSignal, actor?: string, defaultNamespace?: readonly string[]): Promise<TaskCompositionResult>;
-export {};
+}> & TaskCompositionFacts);
+export declare function composeTasks(world: WorldRoot, markdown: string, signal?: AbortSignal, actor?: string, defaultNamespace?: readonly string[], planOnly?: boolean): Promise<TaskCompositionResult>;

package/build/src/task/compose.js

@@ -1,305 +1,142 @@
 import { documentDiff } from "../markdown/diff.js";
-import { relationProblem } from "./board.js";
+import { planTaskComposition, } from "./compose-language.js";
 import { serializeTaskDocument } from "./document.js";
-import { allocateLocalId, deriveLocalStem, formatTaskId, parseTaskId, sameNamespace } from "./identity.js";
 import { authorityPath, readBoard, replaceAuthority, withTaskLocks } from "./store.js";
-import { advanceTaskTimestamp } from "./operations.js";
-function failure(diagnostic) {
-    return { kind: "invalid-composition", diagnostic };
+function refusal(diagnostics) {
+    return { kind: "refused", refusal: { kind: "invalid-composition", diagnostics } };
 }
-function parseNamespace(value) {
-    if (value === "")
-        return [];
-    const coordinate = parseTaskId(`task/${value}/placeholder`);
-    return coordinate.namespace;
-}
-function assignment(token) {
-    const matched = /^(parent|needs|supersedes|relates|pri|body)(\+=|=)(.*)$/u.exec(token);
-    if (matched === null)
-        return null;
-    const field = matched[1], append = matched[2] === "+=", value = matched[3];
-    if (append && (field === "parent" || field === "pri" || field === "body"))
-        throw new TypeError(`${field} does not accept +=`);
-    if (field === "body" && (append || value !== ""))
-        throw new TypeError("body accepts only bare body=");
-    return { field, append, value };
-}
-function parseNode(text, depth, index) {
-    const tokens = text.split(/ +/u);
-    if (text.startsWith("+ ")) {
-        const values = tokens.slice(1);
-        const at = values.findIndex((token) => assignment(token) !== null);
-        const title = values.slice(0, at < 0 ? values.length : at).join(" ");
-        if (title.trim().length === 0)
-            throw new TypeError("compose + node requires a title");
-        return {
-            index,
-            depth,
-            kind: "new",
-            title,
-            assignments: (at < 0 ? [] : values.slice(at)).map((token) => assignment(token) ??
-                (() => {
-                    throw new TypeError(`invalid assignment token: ${token}`);
-                })()),
-        };
-    }
-    const [rawId, ...rest] = tokens;
-    if (rawId === undefined || !rawId.startsWith("@task/"))
-        throw new TypeError("compose node must begin with + or @task/");
-    const id = `task/${rawId.slice(1).slice(5)}`;
-    parseTaskId(id);
-    return {
-        index,
-        depth,
-        kind: "existing",
-        id,
-        assignments: rest.map((token) => assignment(token) ??
-            (() => {
-                throw new TypeError(`invalid assignment token: ${token}`);
-            })()),
-    };
+function currentTimestamp() {
+    return new Date().toISOString();
 }
-function parseSketch(markdown) {
-    try {
-        const lines = markdown.replace(/\r\n?/gu, "\n").split("\n");
-        let namespace;
-        let start = 0;
-        if (lines[0]?.startsWith("ns=")) {
-            namespace = parseNamespace(lines[0].slice(3));
-            start = 1;
-        }
-        const mutable = [];
-        for (let line = start; line < lines.length; line += 1) {
-            const raw = lines[line];
-            if (line === lines.length - 1 && raw === "")
-                continue;
-            const leading = /^(?:\t| )*/u.exec(raw)[0].replace(/\t/gu, "  ");
-            const text = raw.slice(/^(?:\t| )*/u.exec(raw)[0].length);
-            const nodeLine = text.startsWith("+ ") || text.startsWith("@task/");
-            if (nodeLine) {
-                if (leading.length % 2 !== 0)
-                    throw new TypeError(`compose line ${line + 1} has invalid indentation`);
-                const depth = leading.length / 2;
-                if (depth > 0 && !mutable.some((entry) => entry.node.depth === depth - 1))
-                    throw new TypeError(`compose line ${line + 1} skips a parent depth`);
-                mutable.push({ node: parseNode(text, depth, mutable.length), body: [] });
-                continue;
-            }
-            const current = mutable.at(-1);
-            if (current === undefined) {
-                if (text.trim() === "")
-                    continue;
-                throw new TypeError(`compose line ${line + 1} has body before a node`);
-            }
-            current.body.push(text.startsWith("\\") ? text.slice(1) : text);
-        }
-        const nodes = mutable.map(({ node, body }) => ({
-            ...node,
-            ...(body.length === 0 ? {} : { body: body.join("\n") }),
-        }));
-        return { ...(namespace === undefined ? {} : { namespace }), nodes };
+function facts(plan) {
+    return { aliases: plan.aliases, admissionOrder: plan.admissionOrder };
+}
+function reference(id, remainingAliases) {
+    const alias = remainingAliases.get(id);
+    return alias === undefined ? `@${id}` : `^${alias}`;
+}
+function bodyToken(body) {
+    const lines = new Set(body.split(/\r\n|\n|\r/u));
+    for (let suffix = 0; Number.isSafeInteger(suffix); suffix += 1) {
+        const token = suffix === 0 ? "END_BODY" : `END_BODY_${suffix}`;
+        if (token.length > 32)
+            break;
+        if (!lines.has(token))
+            return token;
     }
-    catch (error) {
-        return failure(error instanceof Error ? error.message : String(error));
+    throw new Error("compose recovery body token space exhausted");
+}
+function taskDraft(task, remainingAliases) {
+    const document = task.after;
+    const lines = [task.kind === "new" ? `+ ${document.title}` : `@${document.id}`];
+    if (task.kind === "new" && task.alias !== undefined)
+        lines.push(`as = ${task.alias}`);
+    lines.push(`pri = ${document.priority}`, `needs = ${document.needs.map((id) => reference(id, remainingAliases)).join(", ")}`, `parent = ${document.parent === null ? "" : reference(document.parent, remainingAliases)}`, `supersedes = ${document.supersedes.map((id) => reference(id, remainingAliases)).join(", ")}`, `relates = ${document.relates.map((id) => reference(id, remainingAliases)).join(", ")}`);
+    if (document.body === "")
+        lines.push("body =");
+    else {
+        const token = bodyToken(document.body);
+        lines.push(`body <<${token}`, document.body, token);
     }
+    return lines;
 }
-function ids(value) {
-    if (value === "")
-        return [];
-    const parsed = value.split(",").map((raw) => {
-        if (!raw.startsWith("@task/"))
-            throw new TypeError("relation values must be @TaskId");
-        const id = raw.slice(1);
-        parseTaskId(id);
-        return id;
-    });
-    if (new Set(parsed).size !== parsed.length)
-        throw new TypeError("relation values must not contain duplicates");
-    return parsed;
-}
-function scalarId(value) {
-    const values = ids(value);
-    if (values.length > 1)
-        throw new TypeError("parent accepts at most one TaskId");
-    return values[0] ?? null;
-}
-function changed(current, value, append) {
-    return append ? [...current, ...value.filter((id) => !current.includes(id))] : value;
+function recoveryDraft(namespace, remaining) {
+    const aliases = new Map();
+    for (const task of remaining) {
+        if (task.kind === "new" && task.alias !== undefined)
+            aliases.set(task.after.id, task.alias);
+    }
+    const lines = [`ns=${namespace.join("/")}`];
+    for (const task of remaining)
+        lines.push("", ...taskDraft(task, aliases));
+    return `${lines.join("\n")}\n`;
 }
-function applyAssignments(document, assignments, body) {
-    let next = document;
-    const seen = new Set();
-    for (const item of assignments) {
-        const mode = `${item.field}:${item.append}`;
-        if (seen.has(mode) || [...seen].some((value) => value.startsWith(`${item.field}:`) && value !== mode))
-            throw new TypeError(`duplicate compose assignment: ${item.field}`);
-        seen.add(mode);
-        if (item.field === "pri") {
-            const priority = Number(item.value);
-            if (!Number.isInteger(priority) || priority < 0 || priority > 3)
-                throw new TypeError("pri must be 0..3");
-            next = { ...next, priority: priority };
+function plannedResult(plan) {
+    return { kind: "planned", ...facts(plan), bodies: plan.bodies };
+}
+function planAgainst(markdown, board, namespace, at, actor) {
+    return planTaskComposition({ markdown, board, namespace, at, ...(actor === undefined ? {} : { actor }) });
+}
+async function admitPlan(world, snapshot, plan, signal) {
+    const changes = [];
+    for (let index = 0; index < plan.tasks.length; index += 1) {
+        signal?.throwIfAborted();
+        const item = plan.tasks[index];
+        const beforeBytes = item.before === null ? null : (snapshot.bytes.get(item.after.id) ?? null);
+        const afterBytes = serializeTaskDocument(item.after);
+        const before = beforeBytes === null ? "" : Buffer.from(beforeBytes).toString("utf8");
+        const after = Buffer.from(afterBytes).toString("utf8");
+        const replaced = await replaceAuthority({
+            path: authorityPath(world, item.after.id),
+            expected: beforeBytes,
+            next: afterBytes,
+        });
+        if (replaced !== "replaced") {
+            return {
+                kind: "incomplete",
+                ...facts(plan),
+                documentChanges: changes,
+                stopped: { kind: "retry", reason: "concurrent-modification" },
+                draft: recoveryDraft(plan.namespace, plan.tasks.slice(index)),
+            };
         }
-        else if (item.field === "parent")
-            next = { ...next, parent: scalarId(item.value) };
-        else if (item.field === "body")
-            next = { ...next, body: "" };
-        else
-            next = { ...next, [item.field]: changed(next[item.field], ids(item.value), item.append) };
+        const label = `${item.after.id}.md`;
+        changes.push({
+            taskId: item.after.id,
+            kind: item.before === null ? "created" : "updated",
+            documentDiff: documentDiff(label, label, before, after),
+        });
     }
-    return body === undefined ? next : { ...next, body };
-}
-function currentTimestamp() {
-    return new Date().toISOString();
+    return { kind: "accepted", ...facts(plan), documentChanges: changes };
+}
+async function composeUnderLocks(input) {
+    const snapshot = await readBoard(input.world);
+    const planned = planAgainst(input.markdown, snapshot.board, input.namespace, input.at, input.actor);
+    if (planned.kind === "refused")
+        return refusal(planned.diagnostics);
+    return await withTaskLocks({
+        world: input.world,
+        allocation: false,
+        ids: planned.plan.admissionOrder,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    }, async () => {
+        const fresh = await readBoard(input.world);
+        const replanned = planAgainst(input.markdown, fresh.board, input.namespace, input.at, input.actor);
+        if (replanned.kind === "refused")
+            return refusal(replanned.diagnostics);
+        return await admitPlan(input.world, fresh, replanned.plan, input.signal);
+    });
 }
-function createdTask(id, title, at, actor) {
+function composeInput(world, markdown, namespace, at, actor, signal) {
     return {
-        id,
-        title,
-        state: "open",
-        priority: 2,
-        needs: [],
-        parent: null,
-        supersedes: [],
-        relates: [],
-        note: "",
-        ...(actor === undefined ? {} : { createdBy: actor }),
-        createdAt: at,
-        updatedAt: at,
-        body: "",
+        world,
+        markdown,
+        namespace,
+        at,
+        ...(actor === undefined ? {} : { actor }),
+        ...(signal === undefined ? {} : { signal }),
     };
 }
-function plan(sketch, board, defaultNamespace, at, actor) {
-    try {
-        const namespace = sketch.namespace ?? defaultNamespace;
-        const occupied = new Set([...board.tasks.values()].flatMap((task) => {
-            const coordinate = parseTaskId(task.id);
-            return sameNamespace(coordinate.namespace, namespace) ? [coordinate.localId] : [];
-        }));
-        const allocations = new Map();
-        for (const node of sketch.nodes)
-            if (node.kind === "new") {
-                const localId = allocateLocalId(deriveLocalStem(node.title), occupied);
-                occupied.add(localId);
-                const coordinate = { namespace, localId };
-                allocations.set(node.index, createdTask(formatTaskId(coordinate), node.title, at, actor));
-            }
-        const all = new Map(board.tasks);
-        for (const allocated of allocations.values())
-            all.set(allocated.id, allocated);
-        const byDepth = [], addressed = new Set();
-        const planned = [];
-        for (const node of sketch.nodes) {
-            const before = node.kind === "new" ? null : (board.tasks.get(node.id) ?? null);
-            let current = node.kind === "new" ? allocations.get(node.index) : all.get(node.id);
-            if (current === undefined)
-                throw new TypeError(`compose task does not exist: ${node.id}`);
-            if (addressed.has(current.id))
-                throw new TypeError(`compose addresses ${current.id} more than once`);
-            addressed.add(current.id);
-            if (node.depth > 0) {
-                const parent = byDepth[node.depth - 1];
-                if (parent === undefined)
-                    throw new TypeError("compose parent is unavailable");
-                if (node.assignments.some((item) => item.field === "parent"))
-                    throw new TypeError("indented node cannot also assign parent");
-                current = { ...current, parent };
-            }
-            current = applyAssignments(current, node.assignments, node.body);
-            if (before !== null &&
-                !Buffer.from(serializeTaskDocument(current)).equals(Buffer.from(serializeTaskDocument(before)))) {
-                current = {
-                    ...current,
-                    updatedAt: advanceTaskTimestamp(before.updatedAt, at),
-                };
-            }
-            byDepth[node.depth] = current.id;
-            byDepth.length = node.depth + 1;
-            all.set(current.id, current);
-            planned.push({ node, before, after: current });
-        }
-        for (const item of planned) {
-            const problem = relationProblem({ tasks: all }, item.before, item.after);
-            if (problem !== null)
-                return failure(problem);
-        }
-        return planned;
-    }
-    catch (error) {
-        return failure(error instanceof Error ? error.message : String(error));
-    }
-}
-function ref(id) {
-    return `@${id}`;
-}
-function bodyLines(body) {
-    return body.split("\n").map((line) => (/^[\\]|^\+ |^@task\//u.test(line) ? `\\${line}` : line));
-}
-function draft(namespace, remaining) {
-    const lines = [`ns=${namespace.join("/")}`];
-    for (const item of remaining) {
-        const task = item.after;
-        const assignments = [
-            `pri=${task.priority}`,
-            `needs=${task.needs.map(ref).join(",")}`,
-            `parent=${task.parent === null ? "" : ref(task.parent)}`,
-            `supersedes=${task.supersedes.map(ref).join(",")}`,
-            `relates=${task.relates.map(ref).join(",")}`,
-        ];
-        lines.push(`${item.node.kind === "new" ? `+ ${task.title}` : ref(task.id)} ${assignments.join(" ")}${task.body === "" ? " body=" : ""}`);
-        if (task.body !== "")
-            lines.push(...bodyLines(task.body));
-    }
-    return `${lines.join("\n")}\n`;
-}
-export async function composeTasks(world, markdown, signal, actor, defaultNamespace) {
-    const sketch = parseSketch(markdown);
-    if ("kind" in sketch)
-        return { kind: "refused", refusal: sketch };
+export async function composeTasks(world, markdown, signal, actor, defaultNamespace = [], planOnly = false) {
     const at = currentTimestamp();
-    const namespace = sketch.namespace ?? defaultNamespace ?? [];
     const initial = await readBoard(world);
-    const planned = plan(sketch, initial.board, namespace, at, actor);
-    if ("kind" in planned)
-        return { kind: "refused", refusal: planned };
-    const ordered = [...planned].sort((a, b) => Buffer.compare(Buffer.from(a.after.id), Buffer.from(b.after.id)));
-    const allocation = sketch.nodes.some((node) => node.kind === "new");
-    const result = await withTaskLocks({ world, allocation, ids: ordered.map((item) => item.after.id), ...(signal === undefined ? {} : { signal }) }, async () => {
-        const fresh = await readBoard(world);
-        const replanned = plan(sketch, fresh.board, namespace, at, actor);
-        if ("kind" in replanned)
-            return { kind: "refused", refusal: replanned };
-        const queue = [...replanned].sort((a, b) => Buffer.compare(Buffer.from(a.after.id), Buffer.from(b.after.id))), changes = [];
-        for (let index = 0; index < queue.length; index += 1) {
-            signal?.throwIfAborted();
-            const item = queue[index], path = authorityPath(world, item.after.id);
-            const beforeBytes = item.before === null ? null : (fresh.bytes.get(item.after.id) ?? null);
-            const afterBytes = serializeTaskDocument(item.after);
-            const before = beforeBytes === null ? "" : Buffer.from(beforeBytes).toString("utf8"), after = Buffer.from(afterBytes).toString("utf8");
-            if (before === after)
-                continue;
-            if ((await replaceAuthority({ path, expected: beforeBytes, next: afterBytes })) !== "replaced")
-                return {
-                    kind: "incomplete",
-                    documentChanges: changes,
-                    stopped: { kind: "retry", reason: "concurrent-modification" },
-                    draft: draft(namespace, queue.slice(index)),
-                };
-            const label = `${item.after.id}.md`;
-            changes.push({
-                taskId: item.after.id,
-                kind: item.before === null ? "created" : "updated",
-                documentDiff: documentDiff(label, label, before, after),
-            });
-        }
-        return { kind: "accepted", documentChanges: changes };
-    });
-    return result === "busy"
-        ? {
-            kind: "incomplete",
-            documentChanges: [],
-            stopped: { kind: "retry", reason: "busy" },
-            draft: draft(namespace, ordered),
-        }
-        : result;
+    const initialPlan = planAgainst(markdown, initial.board, defaultNamespace, at, actor);
+    if (initialPlan.kind === "refused")
+        return refusal(initialPlan.diagnostics);
+    if (planOnly)
+        return plannedResult(initialPlan.plan);
+    const input = composeInput(world, markdown, defaultNamespace, at, actor, signal);
+    const allocation = initialPlan.plan.tasks.some((task) => task.kind === "new");
+    const admitted = allocation
+        ? await withTaskLocks({ world, allocation: true, ids: [], ...(signal === undefined ? {} : { signal }) }, async () => await composeUnderLocks(input))
+        : await composeUnderLocks(input);
+    if (admitted !== "busy")
+        return admitted;
+    return {
+        kind: "incomplete",
+        ...facts(initialPlan.plan),
+        documentChanges: [],
+        stopped: { kind: "retry", reason: "busy" },
+        draft: recoveryDraft(initialPlan.plan.namespace, initialPlan.plan.tasks),
+    };
 }

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

@@ -4,7 +4,7 @@ import { type BlockedTaskRow, type TaskDetailFacts, type TaskDoctorIssue, type T
 import { type TaskCompositionResult } from "./compose.js";
 import { TaskAuthorityCorruptionError, type TaskPriority, type TaskState } from "./document.js";
 import type { TaskId } from "./identity.js";
-import { type AddTaskDocumentInput, type AddTaskInput, type TaskBatchResult, type TaskMutationResult, type TaskOutcome, type TaskRefusal, type TaskRetry, type TaskUpdateResult, type TaskView, type UpdateTaskInput } from "./operations.js";
+import { type AddTaskDocumentInput, type AddTaskInput, type TaskBatchResult, type TaskCompositionDiagnostic, type TaskMutationResult, type TaskOutcome, type TaskRefusal, type TaskRetry, type TaskUpdateResult, type TaskView, type UpdateTaskInput } from "./operations.js";
 import { TASK_RELATION_PREDICATE_FIELDS, type TaskPage, type TaskQueryExpression, type TaskQueryPredicate, type TaskQueryRow, type TaskQuerySort, type TaskRelationPredicateField } from "./query.js";
 export type TaskDetail = Omit<TaskDetailFacts, "task"> & Readonly<{
     task: TaskView;
@@ -17,7 +17,7 @@ export type TaskDoctorReport = Readonly<{
     issues: readonly TaskDoctorIssue[];
 }>;
 export type TaskDecompositionTree = TaskOutcome<TaskTreeNode>;
-export type { AddTaskDocumentInput, AddTaskInput, BlockedTaskRow, TaskBatchResult, TaskCompositionResult, TaskDoctorIssue, TaskId, TaskMutationResult, TaskOutcome, TaskPriority, TaskRef, TaskRefusal, TaskRetry, TaskRow, TaskState, TaskTreeNode, TaskUpdateResult, TaskView, UpdateTaskInput, TaskPage, TaskQueryExpression, TaskQueryPredicate, TaskQueryRow, TaskQuerySort, TaskRelationPredicateField, };
+export type { AddTaskDocumentInput, AddTaskInput, BlockedTaskRow, TaskBatchResult, TaskCompositionDiagnostic, TaskCompositionResult, TaskDoctorIssue, TaskId, TaskMutationResult, TaskOutcome, TaskPriority, TaskRef, TaskRefusal, TaskRetry, TaskRow, TaskState, TaskTreeNode, TaskUpdateResult, TaskView, UpdateTaskInput, TaskPage, TaskQueryExpression, TaskQueryPredicate, TaskQueryRow, TaskQuerySort, TaskRelationPredicateField, };
 export { TaskAuthorityCorruptionError, TASK_RELATION_PREDICATE_FIELDS };
 declare class TaskHandle {
     readonly id: TaskId;
@@ -95,6 +95,7 @@ declare class TasksHandle {
         namespace?: readonly string[];
         actor?: string;
         signal?: AbortSignal;
+        plan?: boolean;
     }>): Promise<TaskCompositionResult>;
 }
 export type Tasks = TasksHandle;