@astrosheep/keiyaku 4.0.1 → 4.0.3

package/build/src/task/index.js

@@ -2,8 +2,9 @@ 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))
@@ -48,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;
@@ -61,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) {
@@ -120,15 +139,13 @@ 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)); }
@@ -152,26 +169,28 @@ class TasksHandle {
         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 !== "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", "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)); }
+    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({
     of(root) {

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

@@ -2,6 +2,7 @@ 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 { 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<{
@@ -107,12 +110,13 @@ export declare function addTaskDocument(world: WorldRoot, input: AddTaskDocument
 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, desired: "done" | "open-from-done"): Promise<SettledTaskResult>;
-export declare function listTasks(world: WorldRoot, selection: "active" | "closed" | "all", scope?: "namespace" | "world"): TaskOutcome<readonly TaskRow[]>;
-export declare function readyTasks(world: WorldRoot, scope?: "namespace" | "world"): TaskOutcome<readonly TaskRow[]>;
-export declare function blockedTasks(world: WorldRoot, scope?: "namespace" | "world"): TaskOutcome<readonly BlockedTaskRow[]>;
+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): (Readonly<{
+export declare function observeTaskStatusRows(world: WorldRoot): Promise<(Readonly<{
     id: TaskId;
     title: string;
     state: TaskState;
@@ -129,6 +133,8 @@ export declare function observeTaskStatusRows(world: WorldRoot): (Readonly<{
     state: TaskState;
     priority: TaskPriority;
     disposition: import("./board.js").TaskDisposition;
-})[];
-export declare function setCurrentNamespace(world: WorldRoot, namespace: readonly string[]): void;
-export declare function currentNamespace(world: WorldRoot): readonly string[] | TaskRefusal;
+})[]>;
+/** 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>;

package/build/src/task/operations.js

@@ -1,19 +1,21 @@
+import { resolve } from "node:path";
 import { documentDiff } from "../markdown/diff.js";
 import { installNamespaceContext, readNamespaceContext } from "./context.js";
-import { relationProblem, projectBlocked, projectReady, projectRows, projectStatusRows } from "./board.js";
+import { relationProblem, projectBlocked, projectRows, projectStatusRows } from "./board.js";
 import { parseTaskCreationDocument, serializeTaskDocument } from "./document.js";
 import { allocateLocalId, deriveLocalStem, formatTaskId, parseTaskId, sameNamespace } from "./identity.js";
 import { authorityPath, readBoard, replaceAuthority, withTaskLocks, } from "./store.js";
+import { DEFAULT_TASK_LIMIT, projectPage, projectQuery, queryUnderTargets, underExpression } from "./query.js";
 export function taskView(document) {
     return { ...document, namespace: parseTaskId(document.id).namespace };
 }
 function refused(refusal) { return { kind: "refused", refusal }; }
 function retry(reason) { return { kind: "retry", reason }; }
-function context(world, explicit) {
+async function context(world, explicit) {
     if (explicit !== undefined)
         return explicit;
-    const current = readNamespaceContext(world);
-    return current === "malformed" ? { kind: "invalid-namespace-context", path: `${world}/.keiyaku/namespace/current` }
+    const current = await readNamespaceContext(world);
+    return current === "malformed" ? { kind: "invalid-namespace-context", path: resolve(world, ".keiyaku", "namespace", "current") }
         : current === "absent" ? [] : current;
 }
 function occupied(board, namespace) {
@@ -27,40 +29,44 @@ function advancedTimestamp(previous) {
     const current = currentTimestamp();
     return current > previous ? current : new Date(Date.parse(previous) + 1).toISOString();
 }
-function addDocument(base, namespace, board, at) {
+function addDocument(base, namespace, board, at, actor) {
     const localId = allocateLocalId(deriveLocalStem(base.title), occupied(board, namespace));
-    return { ...base, id: formatTaskId({ namespace, localId }), createdAt: at, updatedAt: at };
+    return {
+        ...base, id: formatTaskId({ namespace, localId }),
+        ...(actor === undefined ? {} : { createdBy: actor }),
+        createdAt: at, updatedAt: at,
+    };
 }
 function boardWith(board, document) {
     const tasks = new Map(board.tasks);
     tasks.set(document.id, document);
     return { tasks };
 }
-async function create(world, base, namespace, signal) {
+async function create(world, base, namespace, signal, actor) {
     const result = await withTaskLocks({ world, allocation: true, ids: [], ...(signal === undefined ? {} : { signal }) }, async () => {
-        const snapshot = readBoard(world), next = addDocument(base, namespace, snapshot.board, currentTimestamp());
+        const snapshot = await readBoard(world), next = addDocument(base, namespace, snapshot.board, currentTimestamp(), actor);
         const problem = relationProblem(boardWith(snapshot.board, next), null, next);
         if (problem !== null)
             return refused({ kind: "invalid-graph", diagnostic: problem });
-        const replaced = replaceAuthority({ path: authorityPath(world, next.id), expected: null, next: serializeTaskDocument(next) });
+        const replaced = await replaceAuthority({ path: authorityPath(world, next.id), expected: null, next: serializeTaskDocument(next) });
         return replaced === "replaced" ? { kind: "accepted", value: taskView(next) } : retry("concurrent-modification");
     });
     return result === "busy" ? retry("busy") : result;
 }
 export async function addTask(world, input) {
-    const namespace = context(world, input.namespace);
+    const namespace = await context(world, input.namespace);
     if (!Array.isArray(namespace))
         return refused(namespace);
     return create(world, {
         title: input.title, body: input.body ?? "", note: input.note ?? "", state: input.state ?? "open", priority: input.priority ?? 2, needs: input.needs ?? [], parent: input.parent ?? null,
         supersedes: input.supersedes ?? [], relates: input.relates ?? [],
-    }, namespace, input.signal);
+    }, namespace, input.signal, input.actor);
 }
 export async function addTaskDocument(world, input) {
-    const namespace = context(world, input.namespace);
+    const namespace = await context(world, input.namespace);
     if (!Array.isArray(namespace))
         return refused(namespace);
-    return create(world, parseTaskCreationDocument(input.markdown), namespace, input.signal);
+    return create(world, parseTaskCreationDocument(input.markdown), namespace, input.signal, input.actor);
 }
 function listChange(current, replacement, additions, removals) {
     const next = [...(replacement ?? current)];
@@ -93,7 +99,7 @@ function updateDocument(board, current, input) {
 }
 export async function updateTask(world, id, input) {
     const result = await withTaskLocks({ world, allocation: false, ids: [id], ...(input.signal === undefined ? {} : { signal: input.signal }) }, async () => {
-        const snapshot = readBoard(world), current = snapshot.board.tasks.get(id);
+        const snapshot = await readBoard(world), current = snapshot.board.tasks.get(id);
         if (current === undefined)
             return { kind: "refused", refusal: { kind: "task-missing", taskId: id } };
         const candidate = updateDocument(snapshot.board, current, input);
@@ -106,7 +112,7 @@ export async function updateTask(world, id, input) {
         const changed = !Buffer.from(serializeTaskDocument(candidate)).equals(Buffer.from(predecessor));
         const next = changed ? { ...candidate, updatedAt: advancedTimestamp(current.updatedAt) } : candidate;
         const afterBytes = serializeTaskDocument(next), after = Buffer.from(afterBytes).toString("utf8");
-        if (before !== after && replaceAuthority({ path: authorityPath(world, id), expected: predecessor, next: afterBytes }) !== "replaced")
+        if (before !== after && await replaceAuthority({ path: authorityPath(world, id), expected: predecessor, next: afterBytes }) !== "replaced")
             return { kind: "retry", reason: "concurrent-modification" };
         const label = `${id}.md`;
         return { kind: "accepted", value: { task: taskView(next), documentDiff: documentDiff(label, label, before, after) } };
@@ -120,7 +126,7 @@ const TRANSITIONS = {
 };
 export async function lifecycleTask(world, id, verb, signal, note) {
     const result = await withTaskLocks({ world, allocation: false, ids: [id], ...(signal === undefined ? {} : { signal }) }, async () => {
-        const snapshot = readBoard(world), current = snapshot.board.tasks.get(id);
+        const snapshot = await readBoard(world), current = snapshot.board.tasks.get(id);
         if (current === undefined)
             return refused({ kind: "task-missing", taskId: id });
         const state = TRANSITIONS[verb][current.state];
@@ -128,7 +134,7 @@ export async function lifecycleTask(world, id, verb, signal, note) {
             return refused({ kind: "invalid-lifecycle-transition", taskId: id, state: current.state, verb });
         const next = { ...current, state, ...(note === undefined ? {} : { note }), updatedAt: advancedTimestamp(current.updatedAt) };
         const bytes = serializeTaskDocument(next);
-        return replaceAuthority({ path: authorityPath(world, id), expected: snapshot.bytes.get(id), next: bytes }) === "replaced"
+        return await replaceAuthority({ path: authorityPath(world, id), expected: snapshot.bytes.get(id), next: bytes }) === "replaced"
             ? { kind: "accepted", value: taskView(next) } : retry("concurrent-modification");
     });
     return result === "busy" ? retry("busy") : result;
@@ -141,58 +147,82 @@ export async function batchTasks(world, verb, ids, signal, note) {
     }
     return { items };
 }
-export async function settleTask(world, id, desired) {
+export async function settleTask(world, id) {
     const result = await withTaskLocks({ world, allocation: false, ids: [id] }, async () => {
-        const snapshot = readBoard(world), current = snapshot.board.tasks.get(id);
+        const snapshot = await readBoard(world), current = snapshot.board.tasks.get(id);
         if (current === undefined)
             return { kind: "refused", refusal: { kind: "task-missing", taskId: id } };
-        if (desired === "done") {
-            if (current.state === "done")
-                return { kind: "unchanged" };
-            if (current.state === "drop") {
-                return { kind: "refused", refusal: { kind: "invalid-lifecycle-transition", taskId: id, state: current.state, verb: "done" } };
-            }
-        }
-        else if (current.state !== "done")
+        if (current.state === "done")
             return { kind: "unchanged" };
-        const state = desired === "done" ? "done" : "open";
-        const next = { ...current, state, updatedAt: advancedTimestamp(current.updatedAt) };
-        const replaced = replaceAuthority({ path: authorityPath(world, id), expected: snapshot.bytes.get(id), next: serializeTaskDocument(next) });
+        if (current.state === "drop") {
+            return { kind: "refused", refusal: { kind: "invalid-lifecycle-transition", taskId: id, state: current.state, verb: "done" } };
+        }
+        const next = { ...current, state: "done", updatedAt: advancedTimestamp(current.updatedAt) };
+        const replaced = await replaceAuthority({ path: authorityPath(world, id), expected: snapshot.bytes.get(id), next: serializeTaskDocument(next) });
         return replaced === "replaced"
-            ? { kind: "changed", task: taskView(next), action: desired === "done" ? "done" : "reopened" }
+            ? { kind: "changed", task: taskView(next), action: "done" }
             : { kind: "retry", reason: "concurrent-modification" };
     });
     return result === "busy" ? { kind: "retry", reason: "busy" } : result;
 }
-function readScope(world, scope) {
+async function readScope(world, scope) {
     if (scope === "world")
         return null;
-    return context(world);
+    return await context(world);
 }
-export function listTasks(world, selection, scope) {
-    const selected = readScope(world, scope);
+export async function listTasks(world, selection, scope, limit = DEFAULT_TASK_LIMIT) {
+    const selected = await readScope(world, scope);
     if (selected !== null && !Array.isArray(selected))
         return { kind: "refused", refusal: selected };
-    return { kind: "accepted", value: projectRows(readBoard(world).board, selected, selection) };
+    return { kind: "accepted", value: projectPage(projectRows((await readBoard(world)).board, selected, selection), limit) };
 }
-export function readyTasks(world, scope) {
-    const selected = readScope(world, scope);
+export async function readyTasks(world, scope, parent, limit = DEFAULT_TASK_LIMIT) {
+    const selected = await readScope(world, scope);
     if (selected !== null && !Array.isArray(selected))
         return { kind: "refused", refusal: selected };
-    return { kind: "accepted", value: projectReady(readBoard(world).board, selected) };
-}
-export function blockedTasks(world, scope) {
-    const selected = readScope(world, scope);
+    const board = (await readBoard(world)).board;
+    if (parent !== undefined && !board.tasks.has(parent))
+        return { kind: "refused", refusal: { kind: "task-missing", taskId: parent } };
+    const ready = { kind: "predicate", predicate: { field: "ready", operator: "=", value: true } };
+    const expression = parent === undefined ? ready : { kind: "and", terms: [ready, underExpression(parent)] };
+    const selectedRows = projectQuery(board, selected, expression, "priority", Math.max(1, board.tasks.size)).rows;
+    const rows = selectedRows.map(({ parent: _parent, needs: _needs, blocks: _blocks, createdAt: _createdAt, updatedAt: _updatedAt, ...row }) => row);
+    return { kind: "accepted", value: projectPage(rows, limit) };
+}
+export async function blockedTasks(world, scope, parent, limit = DEFAULT_TASK_LIMIT) {
+    const selected = await readScope(world, scope);
     if (selected !== null && !Array.isArray(selected))
         return { kind: "refused", refusal: selected };
-    return { kind: "accepted", value: projectBlocked(readBoard(world).board, selected) };
+    const board = (await readBoard(world)).board;
+    if (parent !== undefined && !board.tasks.has(parent))
+        return { kind: "refused", refusal: { kind: "task-missing", taskId: parent } };
+    const blocked = { kind: "predicate", predicate: { field: "blocked", operator: "=", value: true } };
+    const expression = parent === undefined ? blocked : { kind: "and", terms: [blocked, underExpression(parent)] };
+    const selectedRows = projectQuery(board, selected, expression, "priority", Math.max(1, board.tasks.size)).rows;
+    const ids = new Set(selectedRows.map((row) => row.id));
+    return { kind: "accepted", value: projectPage(projectBlocked(board, selected).filter((row) => ids.has(row.id)), limit) };
+}
+export async function queryTasks(world, expression, scope, sort = "priority", limit = DEFAULT_TASK_LIMIT) {
+    const selected = await readScope(world, scope);
+    if (selected !== null && !Array.isArray(selected))
+        return { kind: "refused", refusal: selected };
+    const board = (await readBoard(world)).board;
+    for (const target of queryUnderTargets(expression))
+        if (!board.tasks.has(target)) {
+            return { kind: "refused", refusal: { kind: "task-missing", taskId: target } };
+        }
+    return { kind: "accepted", value: projectQuery(board, selected, expression, sort, limit) };
 }
 /** Internal composite observation from one complete Task board read. */
-export function observeTaskStatusRows(world) {
-    return projectStatusRows(readBoard(world).board, null);
+export async function observeTaskStatusRows(world) {
+    return projectStatusRows((await readBoard(world)).board, null);
+}
+/** Internal identity catalog from one complete Task board read. */
+export async function observeTaskCatalogRows(world) {
+    return projectRows((await readBoard(world)).board, null, "all");
 }
-export function setCurrentNamespace(world, namespace) { installNamespaceContext(world, namespace); }
-export function currentNamespace(world) {
-    const selected = context(world);
+export async function setCurrentNamespace(world, namespace) { await installNamespaceContext(world, namespace); }
+export async function currentNamespace(world) {
+    const selected = await context(world);
     return selected;
 }

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

@@ -0,0 +1,67 @@
+import type { TaskPriority, TaskState } from "./document.js";
+import { type TaskId } from "./identity.js";
+import type { BlockedTaskRow, TaskBoard, TaskRef, TaskRow } from "./board.js";
+export declare const DEFAULT_TASK_LIMIT = 100;
+export declare const MAX_TASK_LIMIT = 1000;
+export type TaskQueryComparison = "=" | "!=" | "<" | "<=" | ">" | ">=" | "~";
+export type TaskQueryPredicate = Readonly<{
+    field: "state";
+    operator: "=" | "!=";
+    value: TaskState;
+}> | Readonly<{
+    field: "priority";
+    operator: "=" | "!=" | "<" | "<=" | ">" | ">=";
+    value: TaskPriority;
+}> | Readonly<{
+    field: "title" | "id";
+    operator: "=" | "!=" | "~";
+    value: string;
+}> | Readonly<{
+    field: "parent";
+    operator: "=" | "!=";
+    value: TaskId | null;
+}> | Readonly<{
+    field: "under" | "needs" | "blocks";
+    operator: "=" | "!=";
+    value: TaskId;
+}> | Readonly<{
+    field: "ready" | "blocked";
+    operator: "=" | "!=";
+    value: boolean;
+}> | Readonly<{
+    field: "created" | "updated";
+    operator: "=" | "!=" | "<" | "<=" | ">" | ">=";
+    value: string;
+}>;
+export type TaskQueryExpression = Readonly<{
+    kind: "and" | "or";
+    terms: readonly TaskQueryExpression[];
+}> | Readonly<{
+    kind: "not";
+    term: TaskQueryExpression;
+}> | Readonly<{
+    kind: "predicate";
+    predicate: TaskQueryPredicate;
+}>;
+export type TaskQuerySort = "priority" | "created" | "updated" | "id";
+export type TaskQueryRow = TaskRow & Readonly<{
+    parent: TaskId | null;
+    needs: readonly TaskRef[];
+    blocks: readonly TaskRef[];
+    createdAt: string;
+    updatedAt: string;
+}>;
+export type TaskPage<Row> = Readonly<{
+    rows: readonly Row[];
+    total: number;
+    returned: number;
+    truncated: boolean;
+}>;
+export declare function normalizeTaskQuery(value: unknown): TaskQueryExpression;
+export declare function projectQuery(board: TaskBoard, scope: readonly string[] | null, expression: TaskQueryExpression, sort?: TaskQuerySort, limit?: number): TaskPage<TaskQueryRow>;
+export declare function projectPage<Row>(rows: readonly Row[], limit?: number): TaskPage<Row>;
+export declare function underExpression(parent: TaskId): TaskQueryExpression;
+export declare function queryUnderTargets(expression: TaskQueryExpression): readonly TaskId[];
+export declare function isValidTaskLimit(value: number): boolean;
+export type TaskQueryPage = TaskPage<TaskQueryRow>;
+export type TaskBlockedPage = TaskPage<BlockedTaskRow>;