@astrosheep/keiyaku 4.0.1 → 4.0.2

package/build/src/settlement/settle.js

@@ -2,16 +2,11 @@ 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 { publishTaskHolderRelease, readTaskHolderProjectionFromDecision, taskHolderObservationSelection, } from "./holder.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);
 }
@@ -21,80 +16,70 @@ function taskFailure(result) {
         : `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")
+    const { repository, channel, world, candidate, actions, lags } = input;
+    let observation;
+    try {
+        observation = await observeContractsForAdmissionAt(repository, channel, [candidate.id], taskHolderObservationSelection());
+    }
+    catch (error) {
+        lags.push({ kind: "settlement-failed", surface: "task-holder", contractId: candidate.id, diagnostic: diagnostic(error) });
         return;
-    if (observation.kind === "failed") {
-        lags.push({ kind: "settlement-failed", surface: "task-holder", contractId: candidate.id, diagnostic: observation.diagnostic });
+    }
+    const state = observation.journals.get(candidate.id)?.state ?? null;
+    if (state === null || state.terminal?.kind !== "claimed")
         return;
+    let holder;
+    try {
+        holder = (await readTaskHolderProjectionFromDecision(channel, observation)).get(candidate.id) ?? null;
     }
-    const holder = observation.holders.get(candidate.id) ?? null;
-    const expectedDisposition = terminal === "claimed" ? "held" : "released";
-    if (holder === null || holder.disposition !== expectedDisposition)
+    catch (error) {
+        lags.push({ kind: "settlement-failed", surface: "task-holder", contractId: candidate.id, diagnostic: diagnostic(error) });
+        return;
+    }
+    if (holder === null || holder.disposition !== "held")
         return;
     const taskId = holder.taskId;
+    let result;
+    try {
+        result = await settleTask(world, taskId);
+    }
+    catch (error) {
+        lags.push({ kind: "settlement-failed", surface: "task", contractId: candidate.id, taskId, diagnostic: diagnostic(error) });
+        return;
+    }
+    if (result.kind === "changed")
+        actions.push({ kind: "task", taskId, action: "done" });
+    else if (result.kind !== "unchanged") {
+        lags.push({ kind: "settlement-failed", surface: "task", contractId: candidate.id, taskId, diagnostic: taskFailure(result) });
+        return;
+    }
     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) });
-            }
-        });
+        const publication = await publishTaskHolderRelease(repository, channel, observation, candidate.id);
+        if (publication.kind === "non-published") {
+            lags.push({
+                kind: "settlement-failed",
+                surface: "task-holder",
+                contractId: candidate.id,
+                taskId,
+                diagnostic: `Task holder release requires retry: ${publication.diagnostic}`,
+            });
+        }
     }
     catch (error) {
         lags.push({ kind: "settlement-failed", surface: "task-holder", contractId: candidate.id, taskId, diagnostic: diagnostic(error) });
     }
 }
-function settleNamespace(state, effects, actions, lags) {
+async 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);
+            const world = await World.at(effect.path);
             actions.push({
                 kind: "namespace-context",
                 path: effect.path,
-                action: repairNamespaceContext(world, [contractSegment(state.id)]),
+                action: await repairNamespaceContext(world, [contractSegment(state.id)]),
             });
         }
         catch (error) {
@@ -108,28 +93,16 @@ function settleNamespace(state, effects, actions, lags) {
         }
     }
 }
-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) {
+async function settleObserved(input) {
     if (input.state === null)
         return { actions: [], lags: [] };
     const actions = [], lags = [];
-    if (observation !== null) {
+    if (input.state.terminal?.kind === "claimed") {
         try {
             await settleTasks({
-                observation,
                 repository: input.repository,
                 channel: input.channel,
-                world: World.at(input.repository.primaryWorktree),
+                world: await World.at(input.repository.primaryWorktree),
                 candidate: input.state,
                 actions,
                 lags,
@@ -139,7 +112,7 @@ async function settleObserved(input, observation) {
             lags.push({ kind: "settlement-failed", surface: "task", contractId: input.state.id, diagnostic: diagnostic(error) });
         }
     }
-    settleNamespace(input.state, input.effects, actions, lags);
+    await settleNamespace(input.state, input.effects, actions, lags);
     return { actions, lags };
 }
 function onPrimaryWorktree(repository) {
@@ -147,19 +120,9 @@ function onPrimaryWorktree(repository) {
 }
 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);
+    return await settleObserved({ ...input, repository });
 }
 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;
+    return await Promise.all(input.contracts.map((contract) => settleObserved({ repository, channel: input.channel, ...contract })));
 }

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

@@ -34,8 +34,7 @@ export type TaskTreeNode = Readonly<{
         priority: TaskPriority | null;
     }>;
     cycle?: true;
-    reference?: true;
-    needs: readonly TaskTreeNode[];
+    children: readonly TaskTreeNode[];
 }>;
 export type TaskBoard = Readonly<{
     tasks: ReadonlyMap<TaskId, TaskDocument>;
@@ -55,6 +54,7 @@ export type TaskDoctorIssue = Readonly<{
     relation: "needs" | "parent" | "supersedes";
     tasks: readonly TaskId[];
 }>;
+export declare function taskDisposition(board: TaskBoard, task: TaskDocument): TaskDisposition;
 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[];
@@ -79,5 +79,5 @@ export declare function projectStatusRows(board: TaskBoard, scope: readonly stri
 })[];
 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 declare function buildTree(board: TaskBoard, root: TaskId): TaskTreeNode | null;
 export {};

package/build/src/task/board.js

@@ -19,7 +19,7 @@ function related(board, task) {
             ids.add(candidate.id);
     return sorted([...ids].map((id) => taskRef(board, id)));
 }
-function disposition(board, task) {
+export function taskDisposition(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";
@@ -44,7 +44,7 @@ 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),
+        disposition: taskDisposition(board, task),
     })).sort((a, b) => a.priority - b.priority || Buffer.compare(Buffer.from(a.id), Buffer.from(b.id)));
 }
 export function projectReady(board, scope) {
@@ -147,19 +147,16 @@ export function diagnoseBoard(board) {
     }
     return issues;
 }
-export function buildTree(board, root, full) {
+export function buildTree(board, root) {
     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);
+        const node = { task: { ...ref, priority: task?.priority ?? null } };
         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 { ...node, cycle: true, children: [] };
+        return { ...node, children: children(board, id).map((child) => walk(child.id, [...path, id])) };
     };
     return walk(root, []);
 }

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

@@ -21,5 +21,5 @@ export type TaskCompositionResult = Readonly<{
     }>;
     draft: string;
 }>;
-export declare function composeTasks(world: WorldRoot, markdown: string, signal?: AbortSignal): Promise<TaskCompositionResult>;
+export declare function composeTasks(world: WorldRoot, markdown: string, signal?: AbortSignal, actor?: string): Promise<TaskCompositionResult>;
 export {};

package/build/src/task/compose.js

@@ -1,3 +1,4 @@
+import { resolve } from "node:path";
 import { documentDiff } from "../markdown/diff.js";
 import { readNamespaceContext } from "./context.js";
 import { relationProblem } from "./board.js";
@@ -119,7 +120,14 @@ function applyAssignments(document, assignments, 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) {
+function createdTask(id, title, at, actor) {
+    return {
+        id, title, state: "open", priority: 2, needs: [], parent: null, supersedes: [], relates: [], note: "",
+        ...(actor === undefined ? {} : { createdBy: actor }),
+        createdAt: at, updatedAt: at, body: "",
+    };
+}
+function plan(sketch, board, defaultNamespace, at, actor) {
     try {
         const namespace = sketch.namespace ?? defaultNamespace;
         const occupied = new Set([...board.tasks.values()].flatMap((task) => {
@@ -132,7 +140,7 @@ function plan(sketch, board, defaultNamespace, at) {
                 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: "" });
+                allocations.set(node.index, createdTask(formatTaskId(coordinate), node.title, at, actor));
             }
         const all = new Map(board.tasks);
         for (const allocated of allocations.values())
@@ -190,24 +198,24 @@ function draft(namespace, remaining) {
     }
     return `${lines.join("\n")}\n`;
 }
-export async function composeTasks(world, markdown, signal) {
+export async function composeTasks(world, markdown, signal, actor) {
     const sketch = parseSketch(markdown);
     if ("kind" in sketch)
         return { kind: "refused", refusal: sketch };
     const at = currentTimestamp();
-    const context = sketch.namespace ?? readNamespaceContext(world);
+    const context = sketch.namespace ?? await readNamespaceContext(world);
     if (context === "malformed")
-        return { kind: "refused", refusal: { kind: "invalid-namespace-context", path: `${world}/.keiyaku/namespace/current` } };
+        return { kind: "refused", refusal: { kind: "invalid-namespace-context", path: resolve(world, ".keiyaku", "namespace", "current") } };
     const namespace = context === "absent" ? [] : context;
-    const initial = readBoard(world);
-    const planned = plan(sketch, initial.board, namespace, at);
+    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 = readBoard(world);
-        const replanned = plan(sketch, fresh.board, namespace, at);
+        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 = [];
@@ -219,7 +227,7 @@ export async function composeTasks(world, markdown, signal) {
             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")
+            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)),
                 };

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

@@ -1,4 +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";
+export declare function readNamespaceContext(root: string): Promise<NamespaceContextRead>;
+export declare function installNamespaceContext(root: string, segments: readonly string[]): Promise<void>;
+export declare function repairNamespaceContext(root: string, segments: readonly string[]): Promise<"kept" | "installed">;

package/build/src/task/context.js

@@ -1,4 +1,4 @@
-import { lstatSync, mkdirSync, readFileSync, } from "node:fs";
+import { lstat, mkdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { repairDerivedFile, replaceFileDurably } from "../coordination/durable-file.js";
 import { normalizeIdentityStem } from "../identity/normalize.js";
@@ -10,13 +10,13 @@ function validNamespaceSegments(value) {
         && segment.length > 0 && normalizeIdentityStem({ source: segment }) === segment
         && !segment.includes("/") && segment !== "." && segment !== "..");
 }
-export function readNamespaceContext(root) {
+export async function readNamespaceContext(root) {
     let bytes;
     try {
-        const path = currentPath(root), stat = lstatSync(path);
+        const path = currentPath(root), stat = await lstat(path);
         if (!stat.isFile() || stat.isSymbolicLink())
             return "malformed";
-        bytes = readFileSync(path, "utf8");
+        bytes = await readFile(path, "utf8");
     }
     catch (error) {
         if (error.code === "ENOENT")
@@ -29,23 +29,23 @@ export function readNamespaceContext(root) {
     const segments = content === "" ? [] : content.split("/");
     return validNamespaceSegments(segments) ? segments : "malformed";
 }
-export function installNamespaceContext(root, segments) {
+export async 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`);
+    await mkdir(parent, { recursive: true });
+    await installIgnore(root);
+    await replaceFileDurably(currentPath(root), `${segments.join("/")}\n`);
 }
-function installIgnore(root) {
-    repairDerivedFile(ignorePath(root), "*\n");
+async function installIgnore(root) {
+    await repairDerivedFile(ignorePath(root), "*\n");
 }
-export function repairNamespaceContext(root, segments) {
-    const current = readNamespaceContext(root);
+export async function repairNamespaceContext(root, segments) {
+    const current = await readNamespaceContext(root);
     if (Array.isArray(current)) {
-        installIgnore(root);
+        await installIgnore(root);
         return "kept";
     }
-    installNamespaceContext(root, segments);
+    await installNamespaceContext(root, segments);
     return "installed";
 }

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

@@ -11,11 +11,12 @@ export type TaskDocument = Readonly<{
     supersedes: readonly TaskId[];
     relates: readonly TaskId[];
     note: string;
+    createdBy?: string;
     createdAt: string;
     updatedAt: string;
     body: string;
 }>;
-export type TaskCreationDocument = Omit<TaskDocument, "id" | "createdAt" | "updatedAt">;
+export type TaskCreationDocument = Omit<TaskDocument, "id" | "createdBy" | "createdAt" | "updatedAt">;
 export declare class TaskAuthorityCorruptionError extends Error {
     constructor(message: string, options?: ErrorOptions);
 }

package/build/src/task/document.js

@@ -4,7 +4,8 @@ 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 REQUIRED_STORED_KEYS = ["id", "title", "state", "priority", "needs", "parent", "supersedes", "relates", "note", "createdAt", "updatedAt"];
+const STORED_KEYS = [...REQUIRED_STORED_KEYS, "createdBy"];
 const CREATION_KEYS = ["title", "state", "priority", "needs", "parent", "supersedes", "relates", "note"];
 function frontMatter(markdown, fail) {
     if (!markdown.startsWith("---\n"))
@@ -73,6 +74,11 @@ function taskIds(value, field, fail) {
 function nullableTaskId(value, field, fail) {
     return value === null ? null : taskId(value, field, fail);
 }
+function createdBy(value, fail) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        fail("createdBy must be a nonblank string");
+    return value;
+}
 function fields(value, body, fail) {
     return {
         title: title(value.title, fail),
@@ -88,14 +94,17 @@ function fields(value, body, fail) {
 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);
+    closed(value, STORED_KEYS, REQUIRED_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) };
+    return {
+        id, state: state(value.state, fail), createdAt, updatedAt, ...fields(value, body, fail),
+        ...(Object.hasOwn(value, "createdBy") ? { createdBy: createdBy(value.createdBy, fail) } : {}),
+    };
 }
 export function parseTaskCreationDocument(markdown) {
     const fail = (message) => { throw new TypeError(message); };
@@ -111,8 +120,9 @@ 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,
+        relates: [...document.relates], note: document.note,
+        ...(document.createdBy === undefined ? {} : { createdBy: document.createdBy }),
+        createdAt: document.createdAt, updatedAt: document.updatedAt,
     };
     return Buffer.from(`---\n${stringify(value, { lineWidth: 0 })}---\n${document.body}`);
 }

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

@@ -5,26 +5,26 @@ 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 TaskPage, type TaskQueryExpression, type TaskQueryPredicate, type TaskQueryRow, type TaskQuerySort } from "./query.js";
 export type TaskDetail = Omit<TaskDetailFacts, "task"> & Readonly<{
     task: TaskView;
 }>;
-export type TaskList = TaskOutcome<readonly TaskRow[]>;
-export type BlockedTaskList = TaskOutcome<readonly BlockedTaskRow[]>;
+export type TaskList = TaskOutcome<TaskPage<TaskRow>>;
+export type BlockedTaskList = TaskOutcome<TaskPage<BlockedTaskRow>>;
+export type TaskQueryResult = TaskOutcome<TaskPage<TaskQueryRow>>;
 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 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 };
 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>;
+    tree(): Promise<TaskDecompositionTree>;
     update(input: UpdateTaskInput): Promise<TaskUpdateResult>;
     private lifecycle;
     start(input?: {
@@ -65,13 +65,24 @@ declare class TasksHandle {
     list(input?: Readonly<{
         selection?: "active" | "closed" | "all";
         scope?: "namespace" | "world";
+        limit?: number;
     }>): Promise<TaskList>;
     ready(input?: Readonly<{
         scope?: "namespace" | "world";
+        parent?: string;
+        limit?: number;
     }>): Promise<TaskList>;
     blocked(input?: Readonly<{
         scope?: "namespace" | "world";
+        parent?: string;
+        limit?: number;
     }>): Promise<BlockedTaskList>;
+    query(input?: Readonly<{
+        where?: TaskQueryExpression;
+        scope?: "namespace" | "world";
+        sort?: TaskQuerySort;
+        limit?: number;
+    }>): Promise<TaskQueryResult>;
     doctor(): Promise<TaskDoctorReport>;
     batch(input: Readonly<{
         verb: "done" | "drop" | "hold";
@@ -81,6 +92,7 @@ declare class TasksHandle {
     }>): Promise<TaskBatchResult>;
     compose(input: Readonly<{
         markdown: string;
+        actor?: string;
         signal?: AbortSignal;
     }>): Promise<TaskCompositionResult>;
 }