@astrosheep/keiyaku 4.5.6 → 4.5.8

package/build/src/protocol/run.js

@@ -1,4 +1,5 @@
 import { extendAdmissionPathsAt, observeContractsForAdmissionAt } from "../git/observe.js";
+import { withPrivateStatePublicationSeat } from "../git/private-state-seat.js";
 import { admitDecidedOffer } from "./attempt.js";
 /** Form one decided offer without admitting or reinterpreting it. */
 export async function prepareProtocolAttempt(input, baseAttempt) {
@@ -41,20 +42,23 @@ export async function prepareProtocolAttempt(input, baseAttempt) {
 export async function runProtocol(input) {
     const attempts = input.attempts;
     for (let index = 0; index < attempts.length; index += 1) {
-        const prepared = await prepareProtocolAttempt(input, attempts[index]);
-        if (prepared.kind === "refused")
-            return prepared;
-        const result = await admitDecidedOffer({
-            channel: input.channel,
-            repository: input.repository,
-            decisionObservation: prepared.observation,
-            attempt: prepared.attempt,
-            offer: prepared.offer,
-            primaryContract: input.input.contractId,
-            assertions: prepared.assertions,
-            ...(input.validateAdmission === undefined ? {} : { validateAdmission: input.validateAdmission }),
+        const result = await withPrivateStatePublicationSeat(input.repository, async (seat) => {
+            const prepared = await prepareProtocolAttempt(input, attempts[index]);
+            if (prepared.kind === "refused")
+                return prepared;
+            return await admitDecidedOffer({
+                channel: input.channel,
+                repository: input.repository,
+                seat,
+                decisionObservation: prepared.observation,
+                attempt: prepared.attempt,
+                offer: prepared.offer,
+                primaryContract: input.input.contractId,
+                assertions: prepared.assertions,
+                ...(input.validateAdmission === undefined ? {} : { validateAdmission: input.validateAdmission }),
+            });
         });
-        if (result.kind === "accepted" || result.kind === "publication-failed" || result.kind === "refused")
+        if (result.kind === "refused" || result.kind === "accepted" || result.kind === "publication-failed")
             return result;
         if (result.kind === "collision" && index + 1 === attempts.length)
             return result;

package/build/src/runtime/proc/run.d.ts

@@ -1,3 +1,4 @@
+import { type ChildProcess } from "node:child_process";
 import { type DetachedProcessInput } from "./launch.js";
 import type { OwnedProcess } from "./types.js";
 export type { DetachedProcessInput } from "./launch.js";
@@ -8,6 +9,13 @@ type ProcessLaunch = Readonly<{
     readonly env?: NodeJS.ProcessEnv;
     readonly signal?: AbortSignal;
 }>;
+export type CancellableProcess = Readonly<{
+    child: ChildProcess;
+    cancelled(): boolean;
+    terminate(force?: boolean): Promise<void>;
+    waitTermination(): Promise<void>;
+}>;
+export declare function spawnCancellableProcess(input: ProcessLaunch): CancellableProcess;
 export type ProcessInput = ProcessLaunch & Readonly<{
     readonly timeoutMs?: number;
 }>;

package/build/src/runtime/proc/run.js

@@ -7,6 +7,33 @@ import { createProcessLifecycle } from "./lifecycle.js";
 import { terminateOwnedProcess } from "./termination.js";
 import { spawnWindowsRetainedProcess } from "./windows-run.js";
 const STREAM_TAIL_BYTES = 16 * 1024;
+export function spawnCancellableProcess(input) {
+    const child = spawn(input.argv[0], input.argv.slice(1), spawnOptionsFor(input, ["pipe", "pipe", "pipe"]));
+    let cancelled = false;
+    let termination;
+    const terminate = (force = false) => {
+        termination ??= terminateOwnedProcess(child, force);
+        return termination;
+    };
+    const cancel = () => {
+        if (cancelled)
+            return;
+        cancelled = true;
+        void terminate();
+    };
+    input.signal?.addEventListener("abort", cancel, { once: true });
+    if (input.signal?.aborted === true)
+        cancel();
+    return {
+        child,
+        cancelled: () => cancelled,
+        terminate,
+        async waitTermination() {
+            input.signal?.removeEventListener("abort", cancel);
+            await termination;
+        },
+    };
+}
 function tailCapture(limit) {
     const bytes = Buffer.allocUnsafe(limit);
     let total = 0;

package/build/src/runtime/proc/termination.js

@@ -5,9 +5,25 @@ const TERMINATION_GRACE_MS = 250;
 const WINDOWS_TERMINATION_SETTLE_MS = 250;
 const WINDOWS_TERMINATION_TIMEOUT_MS = 1_000;
 const execFileAsync = promisify(execFile);
-function ignoreMissingProcess(error) {
-    if (error.code !== "ESRCH")
-        throw error;
+function isMissingProcess(error) {
+    return error.code === "ESRCH";
+}
+async function signalOwnedProcessGroup(pid, signal, exit) {
+    try {
+        process.kill(-pid, signal);
+    }
+    catch (error) {
+        if (isMissingProcess(error))
+            return;
+        if (error.code !== "EPERM")
+            throw error;
+        const exited = await Promise.race([
+            exit.then(() => true),
+            delay(TERMINATION_GRACE_MS, false, { ref: false }).then(() => false),
+        ]);
+        if (!exited)
+            throw error;
+    }
 }
 export async function terminateWindowsTree(pid) {
     try {
@@ -53,6 +69,9 @@ export async function terminateOwnedProcess(child, force = false) {
             resolve();
         });
     });
+    await new Promise((resolve) => setImmediate(resolve));
+    if (exited || child.exitCode !== null || child.signalCode !== null)
+        return;
     if (process.platform === "win32") {
         try {
             await terminateWindowsTree(pid);
@@ -64,31 +83,16 @@ export async function terminateOwnedProcess(child, force = false) {
         return;
     }
     if (force) {
-        try {
-            process.kill(-pid, "SIGKILL");
-        }
-        catch (error) {
-            ignoreMissingProcess(error);
-        }
+        await signalOwnedProcessGroup(pid, "SIGKILL", exit);
         await exit;
         return;
     }
-    try {
-        process.kill(-pid, "SIGTERM");
-    }
-    catch (error) {
-        ignoreMissingProcess(error);
-        await exit;
+    await signalOwnedProcessGroup(pid, "SIGTERM", exit);
+    if (exited || child.exitCode !== null || child.signalCode !== null)
         return;
-    }
     await Promise.race([exit, delay(TERMINATION_GRACE_MS)]);
     if (exited || child.exitCode !== null || child.signalCode !== null)
         return;
-    try {
-        process.kill(-pid, "SIGKILL");
-    }
-    catch (error) {
-        ignoreMissingProcess(error);
-    }
+    await signalOwnedProcessGroup(pid, "SIGKILL", exit);
     await exit;
 }

package/build/src/settlement/holder.d.ts

@@ -1,6 +1,7 @@
 import type { TreeUpdate } from "../core/facts/offer.js";
 import { type ContractId } from "../core/facts/types.js";
 import type { GitDecisionObservation } from "../git/observe.js";
+import { type PrivateStatePublicationSeat } from "../git/private-state-seat.js";
 import type { GitRepository } from "../git/process.js";
 import { type GitDecodeChannel, type GitReadObservation, type GitTreeSelection } from "../git/read-observation.js";
 import { type TaskId } from "../task/identity.js";
@@ -37,7 +38,7 @@ export type TaskHolderReleasePublication = Readonly<{
     diagnostic: string;
 }>;
 /** Publish the released holder against the same frozen observation that decided the release. */
-export declare function publishTaskHolderRelease(repository: GitRepository, channel: GitDecodeChannel, observation: GitDecisionObservation, owner: ContractId): Promise<TaskHolderReleasePublication>;
+export declare function publishTaskHolderRelease(repository: GitRepository, channel: GitDecodeChannel, observation: GitDecisionObservation, owner: ContractId, seat: PrivateStatePublicationSeat): Promise<TaskHolderReleasePublication>;
 export declare function readTaskHolderProjectionFromDecision(channel: GitDecodeChannel, observation: GitDecisionObservation): Promise<TaskHolderProjection>;
 export declare function observeTaskHolderProjection(repository: GitRepository, channel: GitDecodeChannel): Promise<TaskHolderProjection>;
 export declare function releaseTaskHolderWithFence<T extends AdmissionOutcome>(repository: GitRepository, channel: GitDecodeChannel, owner: ContractId, action: () => T | Promise<T>): Promise<TaskHolderAdmission<T>>;

package/build/src/settlement/holder.js

@@ -1,7 +1,8 @@
 import { createHash } from "node:crypto";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
 import { contractId } from "../core/facts/types.js";
-import { GIT_REF, updateGitTree, updateRefsAtomically, writeBlob, writeCommit } from "../git/repository.js";
+import { GIT_REF, updateGitTree, updateRefsAtomically, writeBlob, writeStateCommit } from "../git/repository.js";
+import { confirmPrivateStatePublication } from "../git/private-state-seat.js";
 import { withGitTargetedReadObservation, } from "../git/read-observation.js";
 import { parseTaskId } from "../task/identity.js";
 import { acquireTaskSettlementFence } from "./fence.js";
@@ -121,13 +122,17 @@ export async function releaseTaskHolder(channel, observation, owner) {
     const current = (await readTaskHolderProjectionFromDecision(channel, observation)).get(owner) ?? null;
     return current === null || current.disposition !== "held" ? null : update({ ...current, disposition: "released" });
 }
+async function releasedHolderIsCurrent(repository, channel, owner, expected) {
+    const current = (await observeTaskHolderProjection(repository, channel)).get(owner) ?? null;
+    return current?.disposition === "released" && Buffer.from(canonicalBytes(current)).equals(expected);
+}
 /** Publish the released holder against the same frozen observation that decided the release. */
-export async function publishTaskHolderRelease(repository, channel, observation, owner) {
+export async function publishTaskHolderRelease(repository, channel, observation, owner, seat) {
     const release = await releaseTaskHolder(channel, observation, owner);
     if (release === null)
         return { kind: "not-held" };
     const tree = await updateGitTree(repository, observation.admission.snapshot.tree, new Map([[release.path, { oid: await writeBlob(repository, release.bytes) }]]));
-    const commit = await writeCommit({
+    const commit = await writeStateCommit({
         repository,
         tree,
         parent: observation.admission.snapshot.commit,
@@ -140,8 +145,14 @@ export async function publishTaskHolderRelease(repository, channel, observation,
             expectedOid: observation.admission.snapshot.commit,
         },
     ]);
-    if (publication.kind === "published")
+    if (publication.kind === "published") {
+        confirmPrivateStatePublication(seat);
+        return { kind: "released" };
+    }
+    if (publication.kind === "unknown" && (await releasedHolderIsCurrent(repository, channel, owner, release.bytes))) {
+        confirmPrivateStatePublication(seat);
         return { kind: "released" };
+    }
     return {
         kind: "non-published",
         diagnostic: publication.kind === "non-published"

package/build/src/settlement/settle.js

@@ -1,8 +1,10 @@
 import { contractSegment } from "../core/facts/types.js";
 import { observeContractsForAdmissionAt } from "../git/observe.js";
+import { withPrivateStatePublicationSeat } from "../git/private-state-seat.js";
 import { repairNamespaceContext } from "../task/context.js";
 import { settleTask } from "../task/operations.js";
 import { publishTaskHolderRelease, readTaskHolderProjectionFromDecision, taskHolderObservationSelection, } from "./holder.js";
+import { acquireTaskSettlementFence } from "./fence.js";
 import { World } from "../world.js";
 export function deferredTaskHolderSettlement(input) {
     return { actions: [], lags: [{ kind: "settlement-failed", surface: "task-holder", ...input }] };
@@ -18,11 +20,16 @@ function taskFailure(result) {
         ? `Task settlement requires retry: ${result.reason}`
         : `Task settlement refused: ${JSON.stringify(result.refusal)}`;
 }
-async function settleTasks(input) {
-    const { repository, channel, world, candidate, actions, lags } = input;
+async function observeApplicableHolder(input) {
+    const { repository, channel, candidate, lags } = input;
     let observation;
     try {
         observation = await observeContractsForAdmissionAt(repository, channel, [candidate.id], taskHolderObservationSelection());
+        const state = observation.journals.get(candidate.id)?.state ?? null;
+        if (state === null || state.terminal?.kind !== "claimed")
+            return null;
+        const holder = (await readTaskHolderProjectionFromDecision(channel, observation)).get(candidate.id) ?? null;
+        return holder?.disposition === "held" ? holder : null;
     }
     catch (error) {
         lags.push({
@@ -31,27 +38,25 @@ async function settleTasks(input) {
             contractId: candidate.id,
             diagnostic: diagnostic(error),
         });
-        return;
+        return null;
     }
-    const state = observation.journals.get(candidate.id)?.state ?? null;
-    if (state === null || state.terminal?.kind !== "claimed")
-        return;
-    let holder;
+}
+async function completeHeldTask(input) {
+    const { repository, candidate, actions, lags, taskId } = input;
+    let world;
     try {
-        holder = (await readTaskHolderProjectionFromDecision(channel, observation)).get(candidate.id) ?? null;
+        world = await World.at(repository.primaryWorktree);
     }
     catch (error) {
         lags.push({
             kind: "settlement-failed",
-            surface: "task-holder",
+            surface: "task",
             contractId: candidate.id,
+            taskId,
             diagnostic: diagnostic(error),
         });
-        return;
+        return false;
     }
-    if (holder === null || holder.disposition !== "held")
-        return;
-    const taskId = holder.taskId;
     let result;
     try {
         result = await settleTask(world, taskId);
@@ -64,44 +69,104 @@ async function settleTasks(input) {
             taskId,
             diagnostic: diagnostic(error),
         });
-        return;
+        return false;
     }
     if (result.kind === "changed")
         actions.push({ kind: "task", taskId, action: "done" });
-    else if (result.kind !== "unchanged") {
+    if (result.kind === "changed" || result.kind === "unchanged")
+        return true;
+    lags.push({
+        kind: "settlement-failed",
+        surface: "task",
+        contractId: candidate.id,
+        taskId,
+        diagnostic: taskFailure(result),
+    });
+    return false;
+}
+async function releaseHeldTaskHolder(input) {
+    const { repository, channel, candidate, lags, taskId } = input;
+    try {
+        await withPrivateStatePublicationSeat(repository, async (seat) => {
+            const observation = await observeContractsForAdmissionAt(repository, channel, [candidate.id], taskHolderObservationSelection());
+            const state = observation.journals.get(candidate.id)?.state ?? null;
+            if (state === null || state.terminal?.kind !== "claimed")
+                return;
+            const holder = (await readTaskHolderProjectionFromDecision(channel, observation)).get(candidate.id) ?? null;
+            if (holder === null || holder.disposition !== "held" || holder.taskId !== taskId)
+                return;
+            const publication = await publishTaskHolderRelease(repository, channel, observation, candidate.id, seat);
+            if (publication.kind === "non-published") {
+                lags.push({
+                    kind: "settlement-failed",
+                    surface: "task-holder",
+                    contractId: candidate.id,
+                    taskId,
+                    diagnostic: `Task holder release requires retry: ${publication.diagnostic}`,
+                });
+            }
+        });
+    }
+    catch (error) {
         lags.push({
             kind: "settlement-failed",
-            surface: "task",
+            surface: "task-holder",
             contractId: candidate.id,
             taskId,
-            diagnostic: taskFailure(result),
+            diagnostic: diagnostic(error),
         });
-        return;
     }
+}
+async function settleTasks(input) {
+    const { repository, channel, candidate, actions, lags } = input;
+    const hint = await observeApplicableHolder({ repository, channel, candidate, lags });
+    if (hint === null)
+        return false;
+    const taskId = hint.taskId;
+    let fence;
     try {
-        const publication = await publishTaskHolderRelease(repository, channel, observation, candidate.id);
-        if (publication.kind === "non-published") {
-            lags.push({
-                kind: "settlement-failed",
-                surface: "task-holder",
-                contractId: candidate.id,
-                taskId,
-                diagnostic: `Task holder release requires retry: ${publication.diagnostic}`,
-            });
-        }
+        fence = await acquireTaskSettlementFence(repository, taskId);
     }
     catch (error) {
         lags.push({
             kind: "settlement-failed",
-            surface: "task-holder",
+            surface: "task",
             contractId: candidate.id,
             taskId,
             diagnostic: diagnostic(error),
         });
+        return true;
+    }
+    let taskSettled = false;
+    try {
+        const holder = await observeApplicableHolder({ repository, channel, candidate, lags });
+        if (holder === null || holder.taskId !== taskId)
+            return false;
+        if (!(await completeHeldTask({ repository, candidate, actions, lags, taskId })))
+            return true;
+        taskSettled = true;
+        await releaseHeldTaskHolder({ repository, channel, candidate, taskId, lags });
+        return true;
+    }
+    finally {
+        try {
+            await fence.close();
+        }
+        catch (error) {
+            if (!taskSettled)
+                throw error;
+            lags.push({
+                kind: "settlement-failed",
+                surface: "task-holder",
+                contractId: candidate.id,
+                taskId,
+                diagnostic: diagnostic(error),
+            });
+        }
     }
 }
 async function settleNamespace(state, effects, actions, lags) {
-    if (state.terminal !== null || state.coordinates.workspace !== "worktree")
+    if (state.coordinates.workspace !== "worktree")
         return;
     const worktrees = effects.filter((effect) => effect.kind === "worktree" && effect.action !== "removed");
     for (const effect of worktrees) {
@@ -127,12 +192,12 @@ async function settleObserved(input) {
     if (input.state === null)
         return { actions: [], lags: [] };
     const actions = [], lags = [];
+    let holderApplies = false;
     if (input.state.terminal?.kind === "claimed") {
         try {
-            await settleTasks({
+            holderApplies = await settleTasks({
                 repository: input.repository,
                 channel: input.channel,
-                world: await World.at(input.repository.primaryWorktree),
                 candidate: input.state,
                 actions,
                 lags,
@@ -147,7 +212,8 @@ async function settleObserved(input) {
             });
         }
     }
-    await settleNamespace(input.state, input.effects, actions, lags);
+    if (holderApplies)
+        await settleNamespace(input.state, input.effects, actions, lags);
     return { actions, lags };
 }
 function onPrimaryWorktree(repository) {

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

@@ -1,24 +1,65 @@
 import type { TaskDocument, TaskPriority, TaskState } from "./document.js";
 import { type TaskId } from "./identity.js";
+import { z } from "zod";
 export type TaskRef = Readonly<{
     id: TaskId;
     title: string | null;
     state: TaskState | "missing";
 }>;
-export type TaskDisposition = "ready" | "blocked" | "in_progress" | "on_hold" | "done" | "drop";
-export type TaskRow = Readonly<{
-    id: TaskId;
-    title: string;
-    state: TaskState;
-    priority: TaskPriority;
-    disposition: TaskDisposition;
-    updatedAt: string;
-    bodyPresent: boolean;
-    children?: Readonly<{
-        live: number;
-        total: number;
+export declare const taskRowSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodString, z.ZodTransform<`task/${string}`, string>>;
+    title: z.ZodString;
+    state: z.ZodEnum<{
+        open: "open";
+        in_progress: "in_progress";
+        on_hold: "on_hold";
+        done: "done";
+        drop: "drop";
     }>;
-}>;
+    priority: z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
+    disposition: z.ZodEnum<{
+        in_progress: "in_progress";
+        on_hold: "on_hold";
+        done: "done";
+        drop: "drop";
+        ready: "ready";
+        blocked: "blocked";
+    }>;
+    updatedAt: z.ZodString;
+    bodyPresent: z.ZodBoolean;
+    children: z.ZodOptional<z.ZodObject<{
+        live: z.ZodNumber;
+        total: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const taskRowsSchema: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+    id: z.ZodPipe<z.ZodString, z.ZodTransform<`task/${string}`, string>>;
+    title: z.ZodString;
+    state: z.ZodEnum<{
+        open: "open";
+        in_progress: "in_progress";
+        on_hold: "on_hold";
+        done: "done";
+        drop: "drop";
+    }>;
+    priority: z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
+    disposition: z.ZodEnum<{
+        in_progress: "in_progress";
+        on_hold: "on_hold";
+        done: "done";
+        drop: "drop";
+        ready: "ready";
+        blocked: "blocked";
+    }>;
+    updatedAt: z.ZodString;
+    bodyPresent: z.ZodBoolean;
+    children: z.ZodOptional<z.ZodObject<{
+        live: z.ZodNumber;
+        total: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>>>;
+export type TaskDisposition = z.infer<typeof taskRowSchema>["disposition"];
+export type TaskRow = z.infer<typeof taskRowSchema>;
 export type BlockedTaskRow = TaskRow & Readonly<{
     blockers: readonly TaskRef[];
 }>;
@@ -74,35 +115,35 @@ export declare function projectDetailFacts(board: TaskBoard, id: TaskId, relatio
 export declare function projectTaskRow(board: TaskBoard, relations: TaskRelationProjection, task: TaskDocument): TaskRow;
 export declare function projectRows(board: TaskBoard, relations: TaskRelationProjection, scope: readonly string[] | null, selection: "active" | "closed" | "all"): readonly TaskRow[];
 export declare function projectBlocked(board: TaskBoard, scope: readonly string[] | null, relations: TaskRelationProjection): readonly BlockedTaskRow[];
-export declare function projectStatusRows(board: TaskBoard, relations: TaskRelationProjection, scope: readonly string[] | null): (Readonly<{
-    id: TaskId;
+export declare function projectStatusRows(board: TaskBoard, relations: TaskRelationProjection, scope: readonly string[] | null): ({
+    id: `task/${string}`;
     title: string;
-    state: TaskState;
-    priority: TaskPriority;
-    disposition: TaskDisposition;
+    state: "open" | "in_progress" | "on_hold" | "done" | "drop";
+    priority: 0 | 1 | 2 | 3;
+    disposition: "in_progress" | "on_hold" | "done" | "drop" | "ready" | "blocked";
     updatedAt: string;
     bodyPresent: boolean;
-    children?: Readonly<{
+    children?: {
         live: number;
         total: number;
-    }>;
-}> | {
+    } | undefined;
+} | {
     blockers: readonly Readonly<{
         id: TaskId;
         title: string | null;
         state: TaskState | "missing";
     }>[];
-    id: TaskId;
+    id: `task/${string}`;
     title: string;
-    state: TaskState;
-    priority: TaskPriority;
-    disposition: TaskDisposition;
+    state: "open" | "in_progress" | "on_hold" | "done" | "drop";
+    priority: 0 | 1 | 2 | 3;
+    disposition: "in_progress" | "on_hold" | "done" | "drop" | "ready" | "blocked";
     updatedAt: string;
     bodyPresent: boolean;
-    children?: Readonly<{
+    children?: {
         live: number;
         total: number;
-    }>;
+    } | undefined;
 })[];
 export type TaskBoardObservation = Readonly<{
     statusRows: ReturnType<typeof projectStatusRows>;

package/build/src/task/board.js

@@ -1,4 +1,34 @@
-import { parseTaskId, sameNamespace } from "./identity.js";
+import { formatTaskId, parseTaskId, sameNamespace } from "./identity.js";
+import { z } from "zod";
+const taskRowIdSchema = z.string().transform((value, context) => {
+    try {
+        const id = formatTaskId(parseTaskId(value));
+        if (id !== value)
+            throw new Error("not canonical");
+        return id;
+    }
+    catch {
+        context.addIssue({ code: "custom", message: "expected canonical TaskId" });
+        return z.NEVER;
+    }
+});
+const taskRowTimestampSchema = z.string().refine((value) => Number.isFinite(Date.parse(value)), "expected timestamp");
+export const taskRowSchema = z
+    .object({
+    id: taskRowIdSchema,
+    title: z.string().refine((value) => value.trim() !== ""),
+    state: z.enum(["open", "in_progress", "on_hold", "done", "drop"]),
+    priority: z.union([z.literal(0), z.literal(1), z.literal(2), z.literal(3)]),
+    disposition: z.enum(["ready", "blocked", "in_progress", "on_hold", "done", "drop"]),
+    updatedAt: taskRowTimestampSchema,
+    bodyPresent: z.boolean(),
+    children: z
+        .object({ live: z.number().int().nonnegative(), total: z.number().int().nonnegative() })
+        .strict()
+        .optional(),
+})
+    .strict();
+export const taskRowsSchema = z.array(taskRowSchema).readonly();
 const terminal = (state) => state === "done" || state === "drop";
 const none = Object.freeze([]);
 const sorted = (values) => [...values].sort((a, b) => Buffer.compare(Buffer.from(a.id), Buffer.from(b.id)));

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

@@ -0,0 +1,4 @@
+import { type TaskRow } from "./board.js";
+import type { WorldRoot } from "../world.js";
+export declare function parseTaskNamespaceSelector(value: string): readonly string[];
+export declare function observeTaskCatalogRows(world: WorldRoot, namespace?: readonly string[]): Promise<readonly TaskRow[]>;

package/build/src/task/catalog.js

@@ -0,0 +1,23 @@
+import { createTaskRelations, projectRows } from "./board.js";
+import { isTaskSegment, parseTaskId } from "./identity.js";
+import { readBoard } from "./store.js";
+export function parseTaskNamespaceSelector(value) {
+    if (value === "task/")
+        return [];
+    if (!value.startsWith("task/") || !value.endsWith("/")) {
+        throw new TypeError(`invalid Task namespace selector: ${value}`);
+    }
+    const body = value.slice("task/".length, -1);
+    const segments = body.split("/");
+    if (body.length === 0 || !segments.every(isTaskSegment)) {
+        throw new TypeError(`invalid Task namespace selector: ${value}`);
+    }
+    return parseTaskId(`task/${body}/placeholder`).namespace;
+}
+export async function observeTaskCatalogRows(world, namespace) {
+    if (namespace !== undefined && !namespace.every(isTaskSegment)) {
+        throw new TypeError("namespace must contain canonical segments");
+    }
+    const board = (await readBoard(world)).board;
+    return projectRows(board, createTaskRelations(board), namespace ?? null, "all");
+}

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

@@ -2,6 +2,10 @@ import type { TaskBoard } from "./board.js";
 import { type TaskDocument } from "./document.js";
 import { type TaskId } from "./identity.js";
 import { type TaskCompositionDiagnostic } from "./operations.js";
+export declare function taskCompositionNamespaceHeader(markdown: string): Readonly<{
+    specified: boolean;
+    namespace?: readonly string[];
+}>;
 export type TaskCompositionAlias = Readonly<{
     alias: string;
     taskId: TaskId;