@astrosheep/keiyaku 2.9.13 → 4.0.1

package/build/src/task/compose.js

@@ -0,0 +1,232 @@
+import { documentDiff } from "../markdown/diff.js";
+import { readNamespaceContext } from "./context.js";
+import { relationProblem } from "./board.js";
+import { serializeTaskDocument } from "./document.js";
+import { allocateLocalId, deriveLocalStem, formatTaskId, parseTaskId, sameNamespace } from "./identity.js";
+import { authorityPath, readBoard, replaceAuthority, withTaskLocks } from "./store.js";
+function failure(diagnostic) { return { kind: "invalid-composition", diagnostic }; }
+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 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 };
+    }
+    catch (error) {
+        return failure(error instanceof Error ? error.message : String(error));
+    }
+}
+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 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 };
+        }
+        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) };
+    }
+    return body === undefined ? next : { ...next, body };
+}
+function currentTimestamp() { return new Date().toISOString(); }
+function advancedTimestamp(previous, current) { return current > previous ? current : new Date(Date.parse(previous) + 1).toISOString(); }
+function plan(sketch, board, defaultNamespace, at) {
+    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, { id: formatTaskId(coordinate), title: node.title, state: "open", priority: 2, needs: [], parent: null, supersedes: [], relates: [], note: "", createdAt: at, updatedAt: at, body: "" });
+            }
+        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: advancedTimestamp(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) {
+    const sketch = parseSketch(markdown);
+    if ("kind" in sketch)
+        return { kind: "refused", refusal: sketch };
+    const at = currentTimestamp();
+    const context = sketch.namespace ?? readNamespaceContext(world);
+    if (context === "malformed")
+        return { kind: "refused", refusal: { kind: "invalid-namespace-context", path: `${world}/.keiyaku/namespace/current` } };
+    const namespace = context === "absent" ? [] : context;
+    const initial = readBoard(world);
+    const planned = plan(sketch, initial.board, namespace, at);
+    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 = readBoard(world);
+        const replanned = plan(sketch, fresh.board, namespace, at);
+        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 (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;
+}

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

@@ -0,0 +1,4 @@
+export type NamespaceContextRead = readonly string[] | "absent" | "malformed";
+export declare function readNamespaceContext(root: string): NamespaceContextRead;
+export declare function installNamespaceContext(root: string, segments: readonly string[]): void;
+export declare function repairNamespaceContext(root: string, segments: readonly string[]): "kept" | "installed";

package/build/src/task/context.js

@@ -0,0 +1,51 @@
+import { lstatSync, mkdirSync, readFileSync, } from "node:fs";
+import { join } from "node:path";
+import { repairDerivedFile, replaceFileDurably } from "../coordination/durable-file.js";
+import { normalizeIdentityStem } from "../identity/normalize.js";
+function directory(root) { return join(root, ".keiyaku", "namespace"); }
+function currentPath(root) { return join(directory(root), "current"); }
+function ignorePath(root) { return join(directory(root), ".gitignore"); }
+function validNamespaceSegments(value) {
+    return Array.isArray(value) && value.every((segment) => typeof segment === "string"
+        && segment.length > 0 && normalizeIdentityStem({ source: segment }) === segment
+        && !segment.includes("/") && segment !== "." && segment !== "..");
+}
+export function readNamespaceContext(root) {
+    let bytes;
+    try {
+        const path = currentPath(root), stat = lstatSync(path);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            return "malformed";
+        bytes = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "absent";
+        throw error;
+    }
+    if (!bytes.endsWith("\n") || bytes.slice(0, -1).includes("\n"))
+        return "malformed";
+    const content = bytes.slice(0, -1);
+    const segments = content === "" ? [] : content.split("/");
+    return validNamespaceSegments(segments) ? segments : "malformed";
+}
+export function installNamespaceContext(root, segments) {
+    if (!validNamespaceSegments(segments))
+        throw new TypeError("namespace must contain normalized segments");
+    const parent = directory(root);
+    mkdirSync(parent, { recursive: true });
+    installIgnore(root);
+    replaceFileDurably(currentPath(root), `${segments.join("/")}\n`);
+}
+function installIgnore(root) {
+    repairDerivedFile(ignorePath(root), "*\n");
+}
+export function repairNamespaceContext(root, segments) {
+    const current = readNamespaceContext(root);
+    if (Array.isArray(current)) {
+        installIgnore(root);
+        return "kept";
+    }
+    installNamespaceContext(root, segments);
+    return "installed";
+}

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

@@ -0,0 +1,24 @@
+import { type TaskCoordinate, type TaskId } from "./identity.js";
+export type TaskState = "open" | "in_progress" | "on_hold" | "done" | "drop";
+export type TaskPriority = 0 | 1 | 2 | 3;
+export type TaskDocument = Readonly<{
+    id: TaskId;
+    title: string;
+    state: TaskState;
+    priority: TaskPriority;
+    needs: readonly TaskId[];
+    parent: TaskId | null;
+    supersedes: readonly TaskId[];
+    relates: readonly TaskId[];
+    note: string;
+    createdAt: string;
+    updatedAt: string;
+    body: string;
+}>;
+export type TaskCreationDocument = Omit<TaskDocument, "id" | "createdAt" | "updatedAt">;
+export declare class TaskAuthorityCorruptionError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare function parseTaskDocument(bytes: Uint8Array, expected: TaskCoordinate): TaskDocument;
+export declare function parseTaskCreationDocument(markdown: string): TaskCreationDocument;
+export declare function serializeTaskDocument(document: TaskDocument): Uint8Array;

package/build/src/task/document.js

@@ -0,0 +1,118 @@
+import { isMap, parseDocument, stringify } from "yaml";
+import { formatTaskId, parseTaskId } from "./identity.js";
+export class TaskAuthorityCorruptionError extends Error {
+    constructor(message, options) { super(message, options); this.name = "TaskAuthorityCorruptionError"; }
+}
+const STATES = new Set(["open", "in_progress", "on_hold", "done", "drop"]);
+const STORED_KEYS = ["id", "title", "state", "priority", "needs", "parent", "supersedes", "relates", "note", "createdAt", "updatedAt"];
+const CREATION_KEYS = ["title", "state", "priority", "needs", "parent", "supersedes", "relates", "note"];
+function frontMatter(markdown, fail) {
+    if (!markdown.startsWith("---\n"))
+        fail("task document must begin with YAML front matter");
+    const end = markdown.indexOf("\n---\n", 4);
+    if (end < 0)
+        fail("task document front matter is not closed");
+    const source = markdown.slice(4, end);
+    const parsed = parseDocument(source, { merge: false, prettyErrors: false, strict: true, uniqueKeys: true });
+    if (parsed.errors.length > 0 || parsed.warnings.length > 0 || !isMap(parsed.contents)) {
+        fail("task front matter must be one strict YAML mapping", parsed.errors[0]);
+    }
+    const value = parsed.toJS({ maxAliasCount: 0 });
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        fail("task front matter must be a mapping");
+    return { value: value, body: markdown.slice(end + 5) };
+}
+function closed(value, allowed, required, fail) {
+    for (const key of Object.keys(value))
+        if (!allowed.includes(key))
+            fail(`unknown task front matter key: ${key}`);
+    for (const key of required)
+        if (!Object.hasOwn(value, key))
+            fail(`task front matter is missing ${key}`);
+}
+function title(value, fail) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        fail("task title must be a nonblank string");
+    return value;
+}
+function priority(value, fail) {
+    if (!Number.isInteger(value) || typeof value !== "number" || value < 0 || value > 3)
+        fail("task priority must be 0, 1, 2, or 3");
+    return value;
+}
+function state(value, fail) {
+    if (typeof value !== "string" || !STATES.has(value))
+        fail("task state is invalid");
+    return value;
+}
+function timestamp(value, field, fail) {
+    const milliseconds = typeof value === "string" ? Date.parse(value) : Number.NaN;
+    if (typeof value !== "string" || !Number.isFinite(milliseconds) || new Date(milliseconds).toISOString() !== value)
+        fail(`${field} must be a canonical UTC ISO timestamp`);
+    return value;
+}
+function taskId(value, field, fail) {
+    if (typeof value !== "string")
+        fail(`${field} must be a TaskId`);
+    try {
+        parseTaskId(value);
+        return value;
+    }
+    catch {
+        return fail(`${field} must be a canonical TaskId`);
+    }
+}
+function taskIds(value, field, fail) {
+    if (!Array.isArray(value))
+        fail(`${field} must be an array`);
+    const ids = value.map((item) => taskId(item, field, fail));
+    if (new Set(ids).size !== ids.length)
+        fail(`${field} must not contain duplicates`);
+    return ids;
+}
+function nullableTaskId(value, field, fail) {
+    return value === null ? null : taskId(value, field, fail);
+}
+function fields(value, body, fail) {
+    return {
+        title: title(value.title, fail),
+        priority: priority(value.priority, fail),
+        needs: taskIds(value.needs, "needs", fail),
+        parent: nullableTaskId(value.parent, "parent", fail),
+        supersedes: taskIds(value.supersedes, "supersedes", fail),
+        relates: taskIds(value.relates, "relates", fail),
+        note: typeof value.note === "string" ? value.note : fail("note must be a string"),
+        body,
+    };
+}
+export function parseTaskDocument(bytes, expected) {
+    const fail = (message, cause) => { throw new TaskAuthorityCorruptionError(message, cause === undefined ? {} : { cause }); };
+    const { value, body } = frontMatter(Buffer.from(bytes).toString("utf8"), fail);
+    closed(value, STORED_KEYS, STORED_KEYS, fail);
+    const id = taskId(value.id, "id", fail);
+    if (id !== formatTaskId(expected))
+        fail(`task document ID ${id} does not match its authority path`);
+    const createdAt = timestamp(value.createdAt, "createdAt", fail), updatedAt = timestamp(value.updatedAt, "updatedAt", fail);
+    if (Date.parse(updatedAt) < Date.parse(createdAt))
+        fail("updatedAt must not precede createdAt");
+    return { id, state: state(value.state, fail), createdAt, updatedAt, ...fields(value, body, fail) };
+}
+export function parseTaskCreationDocument(markdown) {
+    const fail = (message) => { throw new TypeError(message); };
+    const { value, body } = frontMatter(markdown, fail);
+    closed(value, CREATION_KEYS, ["title"], fail);
+    const complete = {
+        state: "open", priority: 2, needs: [], parent: null, supersedes: [], relates: [], note: "",
+        ...value,
+    };
+    return { state: state(complete.state, fail), ...fields(complete, body, fail) };
+}
+export function serializeTaskDocument(document) {
+    const value = {
+        id: document.id, title: document.title, state: document.state, priority: document.priority,
+        needs: [...document.needs], parent: document.parent, supersedes: [...document.supersedes],
+        relates: [...document.relates], note: document.note, createdAt: document.createdAt,
+        updatedAt: document.updatedAt,
+    };
+    return Buffer.from(`---\n${stringify(value, { lineWidth: 0 })}---\n${document.body}`);
+}

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

@@ -0,0 +1,12 @@
+export type TaskId = `task/${string}`;
+export type TaskCoordinate = Readonly<{
+    namespace: readonly string[];
+    localId: string;
+}>;
+export declare function isTaskSegment(value: string): boolean;
+export declare function parseTaskId(value: string): TaskCoordinate;
+export declare function formatTaskId(coordinate: TaskCoordinate): TaskId;
+export declare function taskAuthorityPath(tasksDirectory: string, coordinate: TaskCoordinate): string;
+export declare function deriveLocalStem(title: string): string;
+export declare function allocateLocalId(stem: string, occupied: ReadonlySet<string>): string;
+export declare function sameNamespace(left: readonly string[], right: readonly string[]): boolean;

package/build/src/task/identity.js

@@ -0,0 +1,47 @@
+import { join } from "node:path";
+import { identityCoordinate, identitySegments } from "../identity/coordinates.js";
+import { fitIdentityStem, normalizeIdentityStem } from "../identity/normalize.js";
+const STEM_BYTES = 48;
+export function isTaskSegment(value) {
+    return value.length > 0 && value !== "." && value !== ".." && !value.includes("/")
+        && normalizeIdentityStem({ source: value }) === value;
+}
+export function parseTaskId(value) {
+    let segments;
+    try {
+        segments = identitySegments({ family: "task", value });
+    }
+    catch {
+        throw new TypeError("task ID must be task/<local-id> or task/<namespace...>/<local-id>");
+    }
+    if (!segments.every(isTaskSegment))
+        throw new TypeError("task ID contains a noncanonical segment");
+    return { namespace: segments.slice(0, -1), localId: segments.at(-1) };
+}
+export function formatTaskId(coordinate) {
+    if (![...coordinate.namespace, coordinate.localId].every(isTaskSegment))
+        throw new TypeError("task coordinate contains a noncanonical segment");
+    return identityCoordinate({ family: "task", segments: [...coordinate.namespace, coordinate.localId] });
+}
+export function taskAuthorityPath(tasksDirectory, coordinate) {
+    return join(tasksDirectory, ...coordinate.namespace, `${coordinate.localId}.md`);
+}
+export function deriveLocalStem(title) {
+    const stem = normalizeIdentityStem({ source: title });
+    if (stem.length === 0)
+        throw new TypeError("task title must contain a normalized identity segment");
+    return fitIdentityStem({ stem, maxBytes: STEM_BYTES });
+}
+export function allocateLocalId(stem, occupied) {
+    if (!occupied.has(stem))
+        return stem;
+    for (let suffix = 2; Number.isSafeInteger(suffix); suffix += 1) {
+        const candidate = fitIdentityStem({ stem, maxBytes: STEM_BYTES, suffix: String(suffix) });
+        if (!occupied.has(candidate))
+            return candidate;
+    }
+    throw new Error("task identity collision ordinal exceeded the safe integer range");
+}
+export function sameNamespace(left, right) {
+    return left.length === right.length && left.every((segment, index) => segment === right[index]);
+}

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

@@ -0,0 +1,90 @@
+import type { WorldRoot } from "../world.js";
+export type { WorldRoot } from "../world.js";
+import { type BlockedTaskRow, type TaskDetailFacts, type TaskDoctorIssue, type TaskRef, type TaskRow, type TaskTreeNode } from "./board.js";
+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";
+export type TaskDetail = Omit<TaskDetailFacts, "task"> & Readonly<{
+    task: TaskView;
+}>;
+export type TaskList = TaskOutcome<readonly TaskRow[]>;
+export type BlockedTaskList = TaskOutcome<readonly BlockedTaskRow[]>;
+export type TaskNamespaceResult = TaskOutcome<readonly string[]>;
+export type TaskDoctorReport = Readonly<{
+    issues: readonly TaskDoctorIssue[];
+}>;
+export type TaskDependencyTree = TaskOutcome<TaskTreeNode>;
+export type { AddTaskDocumentInput, AddTaskInput, BlockedTaskRow, TaskBatchResult, TaskCompositionResult, TaskDoctorIssue, TaskId, TaskMutationResult, TaskOutcome, TaskPriority, TaskRef, TaskRefusal, TaskRetry, TaskRow, TaskState, TaskUpdateResult, TaskView, UpdateTaskInput };
+export { TaskAuthorityCorruptionError };
+declare class TaskHandle {
+    readonly id: TaskId;
+    private readonly world;
+    constructor(id: TaskId, world: WorldRoot);
+    read(): Promise<TaskDetail | null>;
+    tree(input?: Readonly<{
+        full?: boolean;
+    }>): Promise<TaskDependencyTree>;
+    update(input: UpdateTaskInput): Promise<TaskUpdateResult>;
+    private lifecycle;
+    start(input?: {
+        signal?: AbortSignal;
+    }): Promise<TaskMutationResult>;
+    stop(input?: {
+        signal?: AbortSignal;
+    }): Promise<TaskMutationResult>;
+    hold(input?: {
+        signal?: AbortSignal;
+    }): Promise<TaskMutationResult>;
+    resume(input?: {
+        signal?: AbortSignal;
+    }): Promise<TaskMutationResult>;
+    done(input?: {
+        note?: string;
+        signal?: AbortSignal;
+    }): Promise<TaskMutationResult>;
+    drop(input?: {
+        note?: string;
+        signal?: AbortSignal;
+    }): Promise<TaskMutationResult>;
+}
+export type Task = TaskHandle;
+declare class TasksHandle {
+    private readonly world;
+    readonly root: WorldRoot;
+    constructor(world: WorldRoot);
+    namespace(): Promise<TaskNamespaceResult>;
+    setNamespace(input: Readonly<{
+        namespace: readonly string[];
+    }>): Promise<void>;
+    task(input: Readonly<{
+        id: string;
+    }>): Task;
+    add(input: AddTaskInput): Promise<TaskMutationResult>;
+    addDocument(input: AddTaskDocumentInput): Promise<TaskMutationResult>;
+    list(input?: Readonly<{
+        selection?: "active" | "closed" | "all";
+        scope?: "namespace" | "world";
+    }>): Promise<TaskList>;
+    ready(input?: Readonly<{
+        scope?: "namespace" | "world";
+    }>): Promise<TaskList>;
+    blocked(input?: Readonly<{
+        scope?: "namespace" | "world";
+    }>): Promise<BlockedTaskList>;
+    doctor(): Promise<TaskDoctorReport>;
+    batch(input: Readonly<{
+        verb: "done" | "drop" | "hold";
+        ids: readonly string[];
+        note?: string;
+        signal?: AbortSignal;
+    }>): Promise<TaskBatchResult>;
+    compose(input: Readonly<{
+        markdown: string;
+        signal?: AbortSignal;
+    }>): Promise<TaskCompositionResult>;
+}
+export type Tasks = TasksHandle;
+export declare const Tasks: Readonly<{
+    of(root: WorldRoot): Tasks;
+}>;