@astrosheep/keiyaku 4.0.0 → 4.0.2

package/build/src/task/context.js

@@ -1,6 +1,6 @@
-import { lstatSync, mkdirSync, readFileSync, } from "node:fs";
+import { lstat, mkdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { replaceFileDurably } from "../coordination/durable-file.js";
+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"); }
@@ -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,28 +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) {
-    const ignore = ignorePath(root);
-    const stat = lstatSync(ignore, { throwIfNoEntry: false });
-    if (stat !== undefined && (!stat.isFile() || stat.isSymbolicLink()))
-        throw new Error(`namespace ignore is not a regular file: ${ignore}`);
-    if (stat === undefined || readFileSync(ignore, "utf8") !== "*\n")
-        replaceFileDurably(ignore, "*\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

@@ -1,29 +1,30 @@
-import { type BlockedTaskRow, type TaskDetailFacts, type TaskDoctorIssue, type TaskRow, type TaskTreeNode } from "./board.js";
+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";
-import { type TaskWorld } from "./store.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, 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: TaskWorld);
+    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?: {
@@ -39,6 +40,7 @@ declare class TaskHandle {
         signal?: AbortSignal;
     }): Promise<TaskMutationResult>;
     done(input?: {
+        note?: string;
         signal?: AbortSignal;
     }): Promise<TaskMutationResult>;
     drop(input?: {
@@ -48,9 +50,9 @@ declare class TaskHandle {
 }
 export type Task = TaskHandle;
 declare class TasksHandle {
-    readonly root: string;
     private readonly world;
-    constructor(path?: string);
+    readonly root: WorldRoot;
+    constructor(world: WorldRoot);
     namespace(): Promise<TaskNamespaceResult>;
     setNamespace(input: Readonly<{
         namespace: readonly string[];
@@ -63,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";
@@ -79,12 +92,11 @@ declare class TasksHandle {
     }>): Promise<TaskBatchResult>;
     compose(input: Readonly<{
         markdown: string;
+        actor?: string;
         signal?: AbortSignal;
     }>): Promise<TaskCompositionResult>;
 }
 export type Tasks = TasksHandle;
 export declare const Tasks: Readonly<{
-    at(input?: Readonly<{
-        path?: string;
-    }>): Tasks;
+    of(root: WorldRoot): Tasks;
 }>;

package/build/src/task/index.js

@@ -1,10 +1,10 @@
-import { resolveContextRoot } from "../context-root.js";
 import { buildTree, diagnoseBoard, projectDetailFacts } from "./board.js";
 import { composeTasks } from "./compose.js";
 import { TaskAuthorityCorruptionError } from "./document.js";
 import { isTaskSegment, parseTaskId } from "./identity.js";
-import { addTask, addTaskDocument, batchTasks, blockedTasks, currentNamespace, lifecycleTask, listTasks, readyTasks, setCurrentNamespace, taskView, updateTask, } from "./operations.js";
+import { addTask, addTaskDocument, batchTasks, blockedTasks, currentNamespace, lifecycleTask, listTasks, queryTasks, readyTasks, setCurrentNamespace, taskView, updateTask, } from "./operations.js";
 import { readBoard } from "./store.js";
+import { isValidTaskLimit, normalizeTaskQuery, MAX_TASK_LIMIT, DEFAULT_TASK_LIMIT } from "./query.js";
 export { TaskAuthorityCorruptionError };
 function record(value, label) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
@@ -49,9 +49,26 @@ function namespace(value) {
 function text(value, label) { if (value === undefined)
     return undefined; if (typeof value !== "string")
     throw new TypeError(`${label} must be a string`); return value; }
+function actor(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || value.trim().length === 0)
+        throw new TypeError("actor must be a nonblank string");
+    return value;
+}
 function priority(value) { if (value === undefined)
     return undefined; if (!Number.isInteger(value) || typeof value !== "number" || value < 0 || value > 3)
     throw new TypeError("priority must be 0..3"); return value; }
+function limit(value) { if (value === undefined)
+    return undefined; if (typeof value !== "number" || !isValidTaskLimit(value))
+    throw new TypeError(`limit must be an integer from 1 to ${MAX_TASK_LIMIT}`); return value; }
+function sort(value) {
+    if (value === undefined)
+        return undefined;
+    if (value !== "priority" && value !== "created" && value !== "updated" && value !== "id")
+        throw new TypeError("sort is invalid");
+    return value;
+}
 function state(value) {
     if (value === undefined)
         return undefined;
@@ -62,17 +79,18 @@ function state(value) {
 function nullableId(value) { return value === undefined || value === null ? value : id(value); }
 function addInput(input) {
     const v = record(input, "add input");
-    closed(v, ["title", "namespace", "body", "note", "state", "priority", "needs", "parent", "supersedes", "relates", "signal"], "add input");
+    closed(v, ["title", "namespace", "body", "note", "state", "priority", "needs", "parent", "supersedes", "relates", "actor", "signal"], "add input");
     const title = text(v.title, "title");
     if (title === undefined || title.trim() === "")
         throw new TypeError("title is required");
     const ns = namespace(v.namespace), body = text(v.body, "body"), note = text(v.note, "note"), initialState = state(v.state), pri = priority(v.priority);
     const needs = taskIds(v.needs, "needs"), parent = nullableId(v.parent), supersedes = taskIds(v.supersedes, "supersedes"), relates = taskIds(v.relates, "relates");
-    const abort = signal(v.signal);
+    const createdBy = actor(v.actor), abort = signal(v.signal);
     return { title, ...(ns === undefined ? {} : { namespace: ns }), ...(body === undefined ? {} : { body }), ...(note === undefined ? {} : { note }),
         ...(initialState === undefined ? {} : { state: initialState }), ...(pri === undefined ? {} : { priority: pri }),
         ...(needs === undefined ? {} : { needs }), ...(parent === undefined ? {} : { parent }),
         ...(supersedes === undefined ? {} : { supersedes }), ...(relates === undefined ? {} : { relates }),
+        ...(createdBy === undefined ? {} : { actor: createdBy }),
         ...(abort === undefined ? {} : { signal: abort }) };
 }
 function updateInput(input) {
@@ -121,22 +139,20 @@ class TaskHandle {
         this.world = world;
     }
     async read() {
-        const facts = projectDetailFacts(readBoard(this.world).board, this.id);
+        const facts = projectDetailFacts((await readBoard(this.world)).board, this.id);
         return facts === null ? null : { ...facts, task: taskView(facts.task) };
     }
-    async tree(input) {
-        const value = record(input ?? {}, "tree input");
-        closed(value, ["full"], "tree input");
-        if (value.full !== undefined && typeof value.full !== "boolean")
-            throw new TypeError("full must be a boolean");
-        const node = buildTree(readBoard(this.world).board, this.id, value.full ?? false);
+    async tree() {
+        if (arguments.length > 0)
+            throw new TypeError("tree accepts no input");
+        const node = buildTree((await readBoard(this.world)).board, this.id);
         return node === null ? { kind: "refused", refusal: { kind: "task-missing", taskId: this.id } } : { kind: "accepted", value: node };
     }
     update(input) { return updateTask(this.world, this.id, updateInput(input)); }
     lifecycle(verb, input) {
         const value = record(input ?? {}, `${verb} input`);
-        closed(value, verb === "drop" ? ["note", "signal"] : ["signal"], `${verb} input`);
-        const note = verb === "drop" ? text(value.note, "note") : undefined;
+        closed(value, verb === "drop" || verb === "done" ? ["note", "signal"] : ["signal"], `${verb} input`);
+        const note = verb === "drop" || verb === "done" ? text(value.note, "note") : undefined;
         return lifecycleTask(this.world, this.id, verb, signal(value.signal), note);
     }
     start(input) { return this.lifecycle("start", input); }
@@ -147,33 +163,39 @@ class TaskHandle {
     drop(input) { return this.lifecycle("drop", input); }
 }
 class TasksHandle {
-    root;
     world;
-    constructor(path) {
-        const root = resolveContextRoot({ from: path ?? process.cwd(), marker: ".keiyaku" });
-        this.world = { root };
-        this.root = root;
+    root;
+    constructor(world) {
+        this.world = world;
+        this.root = world;
     }
-    async namespace() { const value = currentNamespace(this.world); return "kind" in value ? { kind: "refused", refusal: value } : { kind: "accepted", value }; }
+    async namespace() { const value = await currentNamespace(this.world); return "kind" in value ? { kind: "refused", refusal: value } : { kind: "accepted", value }; }
     async setNamespace(input) { const v = record(input, "setNamespace input"); closed(v, ["namespace"], "setNamespace input"); const ns = namespace(v.namespace); if (ns === undefined)
-        throw new TypeError("namespace is required"); setCurrentNamespace(this.world, ns); }
+        throw new TypeError("namespace is required"); await setCurrentNamespace(this.world, ns); }
     task(input) { const v = record(input, "task input"); closed(v, ["id"], "task input"); return new TaskHandle(id(v.id), this.world); }
     add(input) { return addTask(this.world, addInput(input)); }
-    addDocument(input) { const v = record(input, "addDocument input"); closed(v, ["markdown", "namespace", "signal"], "addDocument input"); const markdown = text(v.markdown, "markdown"); if (markdown === undefined)
-        throw new TypeError("markdown is required"); const ns = namespace(v.namespace), abort = signal(v.signal); return addTaskDocument(this.world, { markdown, ...(ns === undefined ? {} : { namespace: ns }), ...(abort === undefined ? {} : { signal: abort }) }); }
-    async list(input = {}) { const v = record(input, "list input"); closed(v, ["selection", "scope"], "list input"); if (v.selection !== undefined && v.selection !== "active" && v.selection !== "closed" && v.selection !== "all")
+    addDocument(input) { const v = record(input, "addDocument input"); closed(v, ["markdown", "namespace", "actor", "signal"], "addDocument input"); const markdown = text(v.markdown, "markdown"); if (markdown === undefined)
+        throw new TypeError("markdown is required"); const ns = namespace(v.namespace), createdBy = actor(v.actor), abort = signal(v.signal); return addTaskDocument(this.world, { markdown, ...(ns === undefined ? {} : { namespace: ns }), ...(createdBy === undefined ? {} : { actor: createdBy }), ...(abort === undefined ? {} : { signal: abort }) }); }
+    async list(input = {}) { const v = record(input, "list input"); closed(v, ["selection", "scope", "limit"], "list input"); if (v.selection !== undefined && v.selection !== "active" && v.selection !== "closed" && v.selection !== "all")
         throw new TypeError("selection must be active, closed, or all"); if (v.scope !== undefined && v.scope !== "namespace" && v.scope !== "world")
-        throw new TypeError("scope must be namespace or world"); return listTasks(this.world, v.selection ?? "active", v.scope); }
-    async ready(input = {}) { const v = record(input, "ready input"); closed(v, ["scope"], "ready input"); if (v.scope !== undefined && v.scope !== "namespace" && v.scope !== "world")
-        throw new TypeError("scope must be namespace or world"); return readyTasks(this.world, v.scope); }
-    async blocked(input = {}) { const v = record(input, "blocked input"); closed(v, ["scope"], "blocked input"); if (v.scope !== undefined && v.scope !== "namespace" && v.scope !== "world")
-        throw new TypeError("scope must be namespace or world"); return blockedTasks(this.world, v.scope); }
-    async doctor() { return { issues: diagnoseBoard(readBoard(this.world).board) }; }
+        throw new TypeError("scope must be namespace or world"); return listTasks(this.world, v.selection ?? "active", v.scope, limit(v.limit) ?? DEFAULT_TASK_LIMIT); }
+    async ready(input = {}) { const v = record(input, "ready input"); closed(v, ["scope", "parent", "limit"], "ready input"); if (v.scope !== undefined && v.scope !== "namespace" && v.scope !== "world")
+        throw new TypeError("scope must be namespace or world"); const parent = v.parent === undefined ? undefined : id(v.parent); return readyTasks(this.world, v.scope, parent, limit(v.limit) ?? DEFAULT_TASK_LIMIT); }
+    async blocked(input = {}) { const v = record(input, "blocked input"); closed(v, ["scope", "parent", "limit"], "blocked input"); if (v.scope !== undefined && v.scope !== "namespace" && v.scope !== "world")
+        throw new TypeError("scope must be namespace or world"); const parent = v.parent === undefined ? undefined : id(v.parent); return blockedTasks(this.world, v.scope, parent, limit(v.limit) ?? DEFAULT_TASK_LIMIT); }
+    async query(input = {}) { const v = record(input, "query input"); closed(v, ["where", "scope", "sort", "limit"], "query input"); if (v.scope !== undefined && v.scope !== "namespace" && v.scope !== "world")
+        throw new TypeError("scope must be namespace or world"); const expression = v.where === undefined ? { kind: "and", terms: [{ kind: "predicate", predicate: { field: "state", operator: "!=", value: "done" } }, { kind: "predicate", predicate: { field: "state", operator: "!=", value: "drop" } }] } : normalizeTaskQuery(v.where); return queryTasks(this.world, expression, v.scope, sort(v.sort) ?? "priority", limit(v.limit) ?? DEFAULT_TASK_LIMIT); }
+    async doctor() { return { issues: diagnoseBoard((await readBoard(this.world)).board) }; }
     batch(input) { const v = record(input, "batch input"); closed(v, ["verb", "ids", "note", "signal"], "batch input"); const verb = v.verb; if (verb !== "done" && verb !== "drop" && verb !== "hold")
-        throw new TypeError("batch verb is invalid"); const note = text(v.note, "note"); if (note !== undefined && verb !== "drop")
-        throw new TypeError("batch note is valid only for drop"); return batchTasks(this.world, verb, taskIds(v.ids, "ids") ?? [], signal(v.signal), note); }
-    compose(input) { const v = record(input, "compose input"); closed(v, ["markdown", "signal"], "compose input"); const markdown = text(v.markdown, "markdown"); if (markdown === undefined)
-        throw new TypeError("markdown is required"); return composeTasks(this.world, markdown, signal(v.signal)); }
+        throw new TypeError("batch verb is invalid"); const note = text(v.note, "note"); if (note !== undefined && verb !== "done" && verb !== "drop")
+        throw new TypeError("batch note is valid only for done or drop"); return batchTasks(this.world, verb, taskIds(v.ids, "ids") ?? [], signal(v.signal), note); }
+    compose(input) { const v = record(input, "compose input"); closed(v, ["markdown", "actor", "signal"], "compose input"); const markdown = text(v.markdown, "markdown"); if (markdown === undefined)
+        throw new TypeError("markdown is required"); return composeTasks(this.world, markdown, signal(v.signal), actor(v.actor)); }
 }
-export const Tasks = Object.freeze({ at(input) { if (input === undefined)
-        return new TasksHandle(); const value = record(input, "Tasks.at input"); closed(value, ["path"], "Tasks.at input"); return new TasksHandle(text(value.path, "path")); } });
+export const Tasks = Object.freeze({
+    of(root) {
+        if (typeof root !== "string")
+            throw new TypeError("Tasks.of root must be a WorldRoot");
+        return new TasksHandle(root);
+    },
+});

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

@@ -1,7 +1,8 @@
 import { type BlockedTaskRow, type TaskRow } from "./board.js";
 import { type TaskDocument, type TaskPriority, type TaskState } from "./document.js";
 import { type TaskId } from "./identity.js";
-import { type TaskWorld } from "./store.js";
+import type { WorldRoot } from "../world.js";
+import { type TaskPage, type TaskQueryExpression, type TaskQueryRow, type TaskQuerySort } from "./query.js";
 export type TaskView = Readonly<TaskDocument & {
     namespace: readonly string[];
 }>;
@@ -51,7 +52,7 @@ export type TaskBatchResult = Readonly<{
         outcome: TaskMutationResult;
     }>[];
 }>;
-export type SettledTaskAction = "done" | "reopened";
+export type SettledTaskAction = "done";
 export type SettledTaskResult = Readonly<{
     kind: "changed";
     task: TaskView;
@@ -76,11 +77,13 @@ export type AddTaskInput = Readonly<{
     parent?: TaskId | null;
     supersedes?: readonly TaskId[];
     relates?: readonly TaskId[];
+    actor?: string;
     signal?: AbortSignal;
 }>;
 export type AddTaskDocumentInput = Readonly<{
     markdown: string;
     namespace?: readonly string[];
+    actor?: string;
     signal?: AbortSignal;
 }>;
 export type UpdateTaskInput = Readonly<{
@@ -102,14 +105,36 @@ export type UpdateTaskInput = Readonly<{
     signal?: AbortSignal;
 }>;
 export declare function taskView(document: TaskDocument): TaskView;
-export declare function addTask(world: TaskWorld, input: AddTaskInput): Promise<TaskMutationResult>;
-export declare function addTaskDocument(world: TaskWorld, input: AddTaskDocumentInput): Promise<TaskMutationResult>;
-export declare function updateTask(world: TaskWorld, id: TaskId, input: UpdateTaskInput): Promise<TaskUpdateResult>;
-export declare function lifecycleTask(world: TaskWorld, id: TaskId, verb: TaskLifecycleVerb, signal?: AbortSignal, note?: string): Promise<TaskMutationResult>;
-export declare function batchTasks(world: TaskWorld, verb: "done" | "drop" | "hold", ids: readonly TaskId[], signal?: AbortSignal, note?: string): Promise<TaskBatchResult>;
-export declare function settleTask(world: TaskWorld, id: TaskId, desired: "done" | "open-from-done"): Promise<SettledTaskResult>;
-export declare function listTasks(world: TaskWorld, selection: "active" | "closed" | "all", scope?: "namespace" | "world"): TaskOutcome<readonly TaskRow[]>;
-export declare function readyTasks(world: TaskWorld, scope?: "namespace" | "world"): TaskOutcome<readonly TaskRow[]>;
-export declare function blockedTasks(world: TaskWorld, scope?: "namespace" | "world"): TaskOutcome<readonly BlockedTaskRow[]>;
-export declare function setCurrentNamespace(world: TaskWorld, namespace: readonly string[]): void;
-export declare function currentNamespace(world: TaskWorld): readonly string[] | TaskRefusal;
+export declare function addTask(world: WorldRoot, input: AddTaskInput): Promise<TaskMutationResult>;
+export declare function addTaskDocument(world: WorldRoot, input: AddTaskDocumentInput): Promise<TaskMutationResult>;
+export declare function updateTask(world: WorldRoot, id: TaskId, input: UpdateTaskInput): Promise<TaskUpdateResult>;
+export declare function lifecycleTask(world: WorldRoot, id: TaskId, verb: TaskLifecycleVerb, signal?: AbortSignal, note?: string): Promise<TaskMutationResult>;
+export declare function batchTasks(world: WorldRoot, verb: "done" | "drop" | "hold", ids: readonly TaskId[], signal?: AbortSignal, note?: string): Promise<TaskBatchResult>;
+export declare function settleTask(world: WorldRoot, id: TaskId): Promise<SettledTaskResult>;
+export declare function listTasks(world: WorldRoot, selection: "active" | "closed" | "all", scope?: "namespace" | "world", limit?: number): Promise<TaskOutcome<TaskPage<TaskRow>>>;
+export declare function readyTasks(world: WorldRoot, scope?: "namespace" | "world", parent?: TaskId, limit?: number): Promise<TaskOutcome<TaskPage<TaskRow>>>;
+export declare function blockedTasks(world: WorldRoot, scope?: "namespace" | "world", parent?: TaskId, limit?: number): Promise<TaskOutcome<TaskPage<BlockedTaskRow>>>;
+export declare function queryTasks(world: WorldRoot, expression: TaskQueryExpression, scope?: "namespace" | "world", sort?: TaskQuerySort, limit?: number): Promise<TaskOutcome<TaskPage<TaskQueryRow>>>;
+/** Internal composite observation from one complete Task board read. */
+export declare function observeTaskStatusRows(world: WorldRoot): Promise<(Readonly<{
+    id: TaskId;
+    title: string;
+    state: TaskState;
+    priority: TaskPriority;
+    disposition: import("./board.js").TaskDisposition;
+}> | {
+    blockers: readonly Readonly<{
+        id: TaskId;
+        title: string | null;
+        state: TaskState | "missing";
+    }>[];
+    id: TaskId;
+    title: string;
+    state: TaskState;
+    priority: TaskPriority;
+    disposition: import("./board.js").TaskDisposition;
+})[]>;
+/** Internal identity catalog from one complete Task board read. */
+export declare function observeTaskCatalogRows(world: WorldRoot): Promise<readonly TaskRow[]>;
+export declare function setCurrentNamespace(world: WorldRoot, namespace: readonly string[]): Promise<void>;
+export declare function currentNamespace(world: WorldRoot): Promise<readonly string[] | TaskRefusal>;