@astrosheep/keiyaku 4.0.0 → 4.0.2

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 } 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.root);
-    return current === "malformed" ? { kind: "invalid-namespace-context", path: `${world.root}/.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,54 +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 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.root, 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>;

package/build/src/task/query.js

@@ -0,0 +1,279 @@
+import { formatTaskId, parseTaskId, sameNamespace } from "./identity.js";
+import { taskDisposition } from "./board.js";
+export const DEFAULT_TASK_LIMIT = 100;
+export const MAX_TASK_LIMIT = 1_000;
+const states = ["open", "in_progress", "on_hold", "done", "drop"];
+const comparisons = ["=", "!=", "<", "<=", ">", ">=", "~"];
+function fail(message) { throw new TypeError(message); }
+function object(value, label) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        fail(`${label} must be an object`);
+    return value;
+}
+function closed(value, fields, label) {
+    for (const key of Object.keys(value))
+        if (!fields.includes(key))
+            fail(`${label} has unknown field: ${key}`);
+}
+function taskId(value, label) {
+    if (typeof value !== "string")
+        fail(`${label} must be a TaskId`);
+    try {
+        const coordinate = parseTaskId(value);
+        if (formatTaskId(coordinate) !== value)
+            fail(`${label} must be a canonical TaskId`);
+    }
+    catch {
+        fail(`${label} must be a canonical TaskId`);
+    }
+    return value;
+}
+function comparison(value) {
+    if (typeof value !== "string" || !comparisons.includes(value))
+        fail("query operator is invalid");
+    return value;
+}
+function timestamp(value, field) {
+    if (typeof value !== "string" || !Number.isFinite(Date.parse(value)) || new Date(Date.parse(value)).toISOString() !== value) {
+        fail(`${field} must be a canonical UTC ISO timestamp`);
+    }
+    return value;
+}
+function equalityOperator(operator, field) {
+    if (operator !== "=" && operator !== "!=")
+        fail(`${field} supports only = and !=`);
+    return operator;
+}
+function orderedOperator(operator, field) {
+    if (operator === "~")
+        fail(`${field} does not support ~`);
+    return operator;
+}
+function normalizeStatePredicate(input, operator) {
+    if (typeof input.value !== "string" || !states.includes(input.value))
+        fail("state value is invalid");
+    return { field: "state", operator: equalityOperator(operator, "state"), value: input.value };
+}
+function normalizePriorityPredicate(input, operator) {
+    if (typeof input.value !== "number" || !Number.isInteger(input.value) || input.value < 0 || input.value > 3) {
+        fail("priority value must be 0..3");
+    }
+    return { field: "priority", operator: orderedOperator(operator, "priority"), value: input.value };
+}
+function normalizeTextPredicate(input, field, operator) {
+    if (typeof input.value !== "string" || input.value.length === 0)
+        fail(`${field} value must be nonblank`);
+    if (operator !== "=" && operator !== "!=" && operator !== "~")
+        fail(`${field} supports only =, !=, and ~`);
+    if (field === "id" && operator !== "~")
+        taskId(input.value, "id value");
+    return { field, operator, value: input.value };
+}
+function normalizeParentPredicate(input, operator) {
+    const value = input.value === null ? null : taskId(input.value, "parent value");
+    return { field: "parent", operator: equalityOperator(operator, "parent"), value };
+}
+function normalizeRelationPredicate(input, field, operator) {
+    return { field, operator: equalityOperator(operator, field), value: taskId(input.value, `${field} value`) };
+}
+function normalizeBooleanPredicate(input, field, operator) {
+    if (typeof input.value !== "boolean")
+        fail(`${field} value must be boolean`);
+    return { field, operator: equalityOperator(operator, field), value: input.value };
+}
+function normalizeTimestampPredicate(input, field, operator) {
+    return { field, operator: orderedOperator(operator, field), value: timestamp(input.value, `${field} value`) };
+}
+function predicate(value) {
+    const input = object(value, "query predicate");
+    closed(input, ["field", "operator", "value"], "query predicate");
+    const field = input.field;
+    if (typeof field !== "string")
+        fail("query predicate field is required");
+    const operator = comparison(input.operator);
+    switch (field) {
+        case "state": return normalizeStatePredicate(input, operator);
+        case "priority": return normalizePriorityPredicate(input, operator);
+        case "title": return normalizeTextPredicate(input, "title", operator);
+        case "id": return normalizeTextPredicate(input, "id", operator);
+        case "parent": return normalizeParentPredicate(input, operator);
+        case "under": return normalizeRelationPredicate(input, "under", operator);
+        case "needs": return normalizeRelationPredicate(input, "needs", operator);
+        case "blocks": return normalizeRelationPredicate(input, "blocks", operator);
+        case "ready": return normalizeBooleanPredicate(input, "ready", operator);
+        case "blocked": return normalizeBooleanPredicate(input, "blocked", operator);
+        case "created": return normalizeTimestampPredicate(input, "created", operator);
+        case "updated": return normalizeTimestampPredicate(input, "updated", operator);
+        default: return fail(`unknown query field: ${field}`);
+    }
+}
+export function normalizeTaskQuery(value) {
+    const input = object(value, "query expression");
+    if (input.kind === "predicate") {
+        closed(input, ["kind", "predicate"], "query expression");
+        return { kind: "predicate", predicate: predicate(input.predicate) };
+    }
+    if (input.kind === "not") {
+        closed(input, ["kind", "term"], "query expression");
+        return { kind: "not", term: normalizeTaskQuery(input.term) };
+    }
+    if (input.kind === "and" || input.kind === "or") {
+        closed(input, ["kind", "terms"], "query expression");
+        if (!Array.isArray(input.terms) || input.terms.length === 0)
+            fail(`${input.kind} query requires terms`);
+        return { kind: input.kind, terms: input.terms.map((term) => normalizeTaskQuery(term)) };
+    }
+    fail("query expression kind is invalid");
+}
+function compare(left, operator, right) {
+    if (operator === "=")
+        return left === right;
+    if (operator === "!=")
+        return left !== right;
+    if (operator === "<")
+        return left < right;
+    if (operator === "<=")
+        return left <= right;
+    if (operator === ">")
+        return left > right;
+    return left >= right;
+}
+function membership(left, operator, right) { return operator === "=" ? left === right : left !== right; }
+function indexChildren(board) {
+    const children = new Map();
+    for (const task of board.tasks.values()) {
+        if (task.parent === null)
+            continue;
+        const siblings = children.get(task.parent) ?? [];
+        siblings.push(task.id);
+        children.set(task.parent, siblings);
+    }
+    return children;
+}
+function indexReverseNeeds(board) {
+    const reverse = new Map();
+    for (const task of board.tasks.values()) {
+        for (const need of task.needs) {
+            const blockers = reverse.get(need) ?? new Set();
+            blockers.add(task.id);
+            reverse.set(need, blockers);
+        }
+    }
+    return reverse;
+}
+function descendants(children, parent) {
+    const result = new Set(), pending = [parent];
+    while (pending.length > 0) {
+        const current = pending.shift();
+        for (const child of children.get(current) ?? []) {
+            if (result.has(child))
+                continue;
+            result.add(child);
+            pending.push(child);
+        }
+    }
+    return result;
+}
+function relation(board, reverseNeeds, id, field, target) {
+    const task = board.tasks.get(id);
+    if (task === undefined)
+        return false;
+    return field === "needs" ? task.needs.includes(target) : reverseNeeds.get(target)?.has(id) === true;
+}
+function matchText(left, operator, right) {
+    return operator === "~" ? left.includes(right) : compare(left, operator, right);
+}
+function matchRelation(selected, operator) {
+    return operator === "=" ? selected : !selected;
+}
+function isBlocked(board, task) {
+    const active = task.state === "open" || task.state === "in_progress";
+    return active && task.needs.some((need) => {
+        const target = board.tasks.get(need);
+        return target === undefined || (target.state !== "done" && target.state !== "drop");
+    });
+}
+function taskRef(board, id) {
+    const task = board.tasks.get(id);
+    return task === undefined ? { id, title: null, state: "missing" } : { id, title: task.title, state: task.state };
+}
+function matchesPredicate(board, reverseNeeds, task, value, under) {
+    switch (value.field) {
+        case "state": return compare(task.state, value.operator, value.value);
+        case "priority": return compare(task.priority, value.operator, value.value);
+        case "title": return matchText(task.title, value.operator, value.value);
+        case "id": return matchText(task.id, value.operator, value.value);
+        case "parent": return compare(task.parent ?? "", value.operator, value.value ?? "");
+        case "under": return matchRelation(under.get(value.value)?.has(task.id) === true, value.operator);
+        case "needs": return matchRelation(relation(board, reverseNeeds, task.id, "needs", value.value), value.operator);
+        case "blocks": return matchRelation(relation(board, reverseNeeds, task.id, "blocks", value.value), value.operator);
+        case "ready": return membership(taskDisposition(board, task) === "ready", value.operator, value.value);
+        case "blocked": return membership(isBlocked(board, task), value.operator, value.value);
+        case "created": return compare(task.createdAt, value.operator, value.value);
+        case "updated": return compare(task.updatedAt, value.operator, value.value);
+    }
+}
+function matches(board, reverseNeeds, task, expression, under) {
+    if (expression.kind === "not")
+        return !matches(board, reverseNeeds, task, expression.term, under);
+    if (expression.kind !== "predicate") {
+        return expression.kind === "and"
+            ? expression.terms.every((term) => matches(board, reverseNeeds, task, term, under))
+            : expression.terms.some((term) => matches(board, reverseNeeds, task, term, under));
+    }
+    return matchesPredicate(board, reverseNeeds, task, expression.predicate, under);
+}
+function row(board, reverseNeeds, task) {
+    return {
+        id: task.id, title: task.title, state: task.state, priority: task.priority, disposition: taskDisposition(board, task),
+        parent: task.parent,
+        needs: task.needs.map((need) => taskRef(board, need)),
+        blocks: [...(reverseNeeds.get(task.id) ?? [])]
+            .sort((left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right)))
+            .map((id) => taskRef(board, id)),
+        createdAt: task.createdAt, updatedAt: task.updatedAt,
+    };
+}
+function sortTasks(tasks, sort) {
+    return [...tasks].sort((left, right) => {
+        const tie = Buffer.compare(Buffer.from(left.id), Buffer.from(right.id));
+        if (sort === "id")
+            return tie;
+        if (sort === "priority")
+            return left.priority - right.priority || tie;
+        const compared = left[sort === "created" ? "createdAt" : "updatedAt"].localeCompare(right[sort === "created" ? "createdAt" : "updatedAt"]);
+        return (sort === "updated" ? -compared : compared) || tie;
+    });
+}
+export function projectQuery(board, scope, expression, sort = "priority", limit = DEFAULT_TASK_LIMIT) {
+    const children = indexChildren(board);
+    const reverseNeeds = indexReverseNeeds(board);
+    const under = new Map(queryUnderTargets(expression).map((target) => [target, descendants(children, target)]));
+    const selected = sortTasks([...board.tasks.values()].filter((task) => scope === null || sameNamespace(parseTaskId(task.id).namespace, scope))
+        .filter((task) => matches(board, reverseNeeds, task, expression, under)), sort);
+    const rows = selected.slice(0, limit).map((task) => row(board, reverseNeeds, task));
+    return { rows, total: selected.length, returned: rows.length, truncated: rows.length < selected.length };
+}
+export function projectPage(rows, limit = DEFAULT_TASK_LIMIT) {
+    const visible = rows.slice(0, limit);
+    return { rows: visible, total: rows.length, returned: visible.length, truncated: visible.length < rows.length };
+}
+export function underExpression(parent) {
+    return { kind: "predicate", predicate: { field: "under", operator: "=", value: parent } };
+}
+export function queryUnderTargets(expression) {
+    const targets = new Set();
+    function collect(value) {
+        if (value.kind === "predicate" && value.predicate.field === "under")
+            targets.add(value.predicate.value);
+        else if (value.kind === "not")
+            collect(value.term);
+        else if (value.kind !== "predicate")
+            value.terms.forEach(collect);
+    }
+    collect(expression);
+    return [...targets];
+}
+export function isValidTaskLimit(value) {
+    return Number.isInteger(value) && value > 0 && value <= MAX_TASK_LIMIT;
+}

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

@@ -1,22 +1,20 @@
+import type { WorldRoot } from "../world.js";
 import { type TaskId } from "./identity.js";
 import type { TaskBoard } from "./board.js";
-export type TaskWorld = Readonly<{
-    root: string;
-}>;
 export type BoardSnapshot = Readonly<{
     board: TaskBoard;
     bytes: ReadonlyMap<TaskId, Uint8Array>;
 }>;
-export declare function readBoard(world: TaskWorld): BoardSnapshot;
+export declare function readBoard(world: WorldRoot): Promise<BoardSnapshot>;
 export declare function replaceAuthority(input: Readonly<{
     path: string;
     expected: Uint8Array | null;
     next: Uint8Array;
-}>): "replaced" | "concurrent-modification";
+}>): Promise<"replaced" | "concurrent-modification">;
 export declare function withTaskLocks<T>(input: Readonly<{
-    world: TaskWorld;
+    world: WorldRoot;
     allocation: boolean;
     ids: readonly TaskId[];
     signal?: AbortSignal;
 }>, action: () => Promise<T>): Promise<T | "busy">;
-export declare function authorityPath(world: TaskWorld, id: TaskId): string;
+export declare function authorityPath(world: WorldRoot, id: TaskId): string;