@astrosheep/keiyaku 2.9.12 → 4.0.0

package/build/src/task/index.js

@@ -0,0 +1,179 @@
+import { resolveContextRoot } from "../context-root.js";
+import { buildTree, diagnoseBoard, projectDetailFacts } from "./board.js";
+import { composeTasks } from "./compose.js";
+import { TaskAuthorityCorruptionError } from "./document.js";
+import { isTaskSegment, parseTaskId } from "./identity.js";
+import { addTask, addTaskDocument, batchTasks, blockedTasks, currentNamespace, lifecycleTask, listTasks, readyTasks, setCurrentNamespace, taskView, updateTask, } from "./operations.js";
+import { readBoard } from "./store.js";
+export { TaskAuthorityCorruptionError };
+function record(value, label) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new TypeError(`${label} must be an object`);
+    return value;
+}
+function closed(value, allowed, label) {
+    for (const key of Object.keys(value))
+        if (!allowed.includes(key))
+            throw new TypeError(`${label} has unknown field: ${key}`);
+}
+function id(value) { if (typeof value !== "string")
+    throw new TypeError("task ID must be a string"); parseTaskId(value); return value; }
+function signal(value) {
+    if (value === undefined)
+        return undefined;
+    if (!(value instanceof AbortSignal))
+        throw new TypeError("signal must be an AbortSignal");
+    return value;
+}
+function strings(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || !value.every((item) => typeof item === "string"))
+        throw new TypeError(`${label} must be an array of strings`);
+    return value;
+}
+function taskIds(value, label) {
+    const values = strings(value, label)?.map(id);
+    if (values !== undefined && new Set(values).size !== values.length)
+        throw new TypeError(`${label} must not contain duplicates`);
+    return values;
+}
+function namespace(value) {
+    const values = strings(value, "namespace");
+    if (values === undefined)
+        return undefined;
+    if (!values.every(isTaskSegment))
+        throw new TypeError("namespace must contain canonical segments");
+    return values;
+}
+function text(value, label) { if (value === undefined)
+    return undefined; if (typeof value !== "string")
+    throw new TypeError(`${label} must be a 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 state(value) {
+    if (value === undefined)
+        return undefined;
+    if (value !== "open" && value !== "in_progress" && value !== "on_hold" && value !== "done" && value !== "drop")
+        throw new TypeError("state is invalid");
+    return 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");
+    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);
+    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 }),
+        ...(abort === undefined ? {} : { signal: abort }) };
+}
+function updateInput(input) {
+    const v = record(input, "update input");
+    closed(v, ["title", "body", "appendBody", "note", "priority", "needs", "addNeeds", "dropNeeds", "parent", "supersedes", "addSupersedes", "dropSupersedes", "relates", "addRelates", "dropRelates", "signal"], "update input");
+    if (v.body !== undefined && v.appendBody !== undefined)
+        throw new TypeError("body and appendBody are mutually exclusive");
+    const result = {};
+    const title = text(v.title, "title");
+    if (title !== undefined) {
+        if (title.trim().length === 0)
+            throw new TypeError("title must be nonblank");
+        result.title = title;
+    }
+    const body = text(v.body, "body");
+    if (body !== undefined)
+        result.body = body;
+    const appendBody = text(v.appendBody, "appendBody");
+    if (appendBody !== undefined)
+        result.appendBody = appendBody;
+    const note = text(v.note, "note");
+    if (note !== undefined)
+        result.note = note;
+    const pri = priority(v.priority);
+    if (pri !== undefined)
+        result.priority = pri;
+    for (const [key, value] of [["needs", taskIds(v.needs, "needs")], ["addNeeds", taskIds(v.addNeeds, "addNeeds")], ["dropNeeds", taskIds(v.dropNeeds, "dropNeeds")], ["supersedes", taskIds(v.supersedes, "supersedes")], ["addSupersedes", taskIds(v.addSupersedes, "addSupersedes")], ["dropSupersedes", taskIds(v.dropSupersedes, "dropSupersedes")], ["relates", taskIds(v.relates, "relates")], ["addRelates", taskIds(v.addRelates, "addRelates")], ["dropRelates", taskIds(v.dropRelates, "dropRelates")]])
+        if (value !== undefined)
+            result[key] = value;
+    const parent = nullableId(v.parent);
+    if (parent !== undefined)
+        result.parent = parent;
+    const abort = signal(v.signal);
+    if (abort !== undefined)
+        result.signal = abort;
+    const update = result;
+    if (Object.keys(result).filter((key) => key !== "signal").length === 0)
+        throw new TypeError("update requires at least one field change");
+    return update;
+}
+class TaskHandle {
+    id;
+    world;
+    constructor(id, world) {
+        this.id = id;
+        this.world = world;
+    }
+    async read() {
+        const facts = projectDetailFacts(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);
+        return node === null ? { kind: "refused", refusal: { kind: "task-missing", taskId: this.id } } : { kind: "accepted", value: node };
+    }
+    update(input) { return updateTask(this.world, this.id, updateInput(input)); }
+    lifecycle(verb, input) {
+        const value = record(input ?? {}, `${verb} input`);
+        closed(value, verb === "drop" ? ["note", "signal"] : ["signal"], `${verb} input`);
+        const note = verb === "drop" ? text(value.note, "note") : undefined;
+        return lifecycleTask(this.world, this.id, verb, signal(value.signal), note);
+    }
+    start(input) { return this.lifecycle("start", input); }
+    stop(input) { return this.lifecycle("stop", input); }
+    hold(input) { return this.lifecycle("hold", input); }
+    resume(input) { return this.lifecycle("resume", input); }
+    done(input) { return this.lifecycle("done", input); }
+    drop(input) { return this.lifecycle("drop", input); }
+}
+class TasksHandle {
+    root;
+    world;
+    constructor(path) {
+        const root = resolveContextRoot({ from: path ?? process.cwd(), marker: ".keiyaku" });
+        this.world = { root };
+        this.root = root;
+    }
+    async namespace() { const value = 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); }
+    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")
+        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) }; }
+    batch(input) { const v = record(input, "batch input"); closed(v, ["verb", "ids", "note", "signal"], "batch input"); const verb = v.verb; if (verb !== "done" && verb !== "drop" && verb !== "hold")
+        throw new TypeError("batch verb is invalid"); const note = text(v.note, "note"); if (note !== undefined && verb !== "drop")
+        throw new TypeError("batch note is valid only for drop"); return batchTasks(this.world, verb, taskIds(v.ids, "ids") ?? [], signal(v.signal), note); }
+    compose(input) { const v = record(input, "compose input"); closed(v, ["markdown", "signal"], "compose input"); const markdown = text(v.markdown, "markdown"); if (markdown === undefined)
+        throw new TypeError("markdown is required"); return composeTasks(this.world, markdown, signal(v.signal)); }
+}
+export const Tasks = Object.freeze({ at(input) { if (input === undefined)
+        return new TasksHandle(); const value = record(input, "Tasks.at input"); closed(value, ["path"], "Tasks.at input"); return new TasksHandle(text(value.path, "path")); } });

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

@@ -0,0 +1,115 @@
+import { type BlockedTaskRow, type TaskRow } from "./board.js";
+import { type TaskDocument, type TaskPriority, type TaskState } from "./document.js";
+import { type TaskId } from "./identity.js";
+import { type TaskWorld } from "./store.js";
+export type TaskView = Readonly<TaskDocument & {
+    namespace: readonly string[];
+}>;
+export type TaskRefusal = Readonly<{
+    kind: "task-missing";
+    taskId: TaskId;
+}> | Readonly<{
+    kind: "invalid-lifecycle-transition";
+    taskId: TaskId;
+    state: TaskState;
+    verb: TaskLifecycleVerb;
+}> | Readonly<{
+    kind: "invalid-graph";
+    diagnostic: string;
+}> | Readonly<{
+    kind: "invalid-namespace-context";
+    path: string;
+}> | Readonly<{
+    kind: "relation-owned-by-other";
+    taskId: TaskId;
+    related: TaskId;
+    declaringTask: TaskId;
+}> | Readonly<{
+    kind: "invalid-composition";
+    diagnostic: string;
+}>;
+export type TaskRetry = "busy" | "concurrent-modification";
+export type TaskOutcome<A> = Readonly<{
+    kind: "accepted";
+    value: A;
+}> | Readonly<{
+    kind: "refused";
+    refusal: TaskRefusal;
+}> | Readonly<{
+    kind: "retry";
+    reason: TaskRetry;
+}>;
+export type TaskMutationResult = TaskOutcome<TaskView>;
+export type TaskUpdateResult = TaskOutcome<Readonly<{
+    task: TaskView;
+    documentDiff: string;
+}>>;
+export type TaskLifecycleVerb = "start" | "stop" | "hold" | "resume" | "done" | "drop";
+export type TaskBatchResult = Readonly<{
+    items: readonly Readonly<{
+        id: TaskId;
+        outcome: TaskMutationResult;
+    }>[];
+}>;
+export type SettledTaskAction = "done" | "reopened";
+export type SettledTaskResult = Readonly<{
+    kind: "changed";
+    task: TaskView;
+    action: SettledTaskAction;
+}> | Readonly<{
+    kind: "unchanged";
+}> | Readonly<{
+    kind: "refused";
+    refusal: TaskRefusal;
+}> | Readonly<{
+    kind: "retry";
+    reason: TaskRetry;
+}>;
+export type AddTaskInput = Readonly<{
+    title: string;
+    namespace?: readonly string[];
+    body?: string;
+    note?: string;
+    state?: TaskState;
+    priority?: TaskPriority;
+    needs?: readonly TaskId[];
+    parent?: TaskId | null;
+    supersedes?: readonly TaskId[];
+    relates?: readonly TaskId[];
+    signal?: AbortSignal;
+}>;
+export type AddTaskDocumentInput = Readonly<{
+    markdown: string;
+    namespace?: readonly string[];
+    signal?: AbortSignal;
+}>;
+export type UpdateTaskInput = Readonly<{
+    title?: string;
+    body?: string;
+    appendBody?: string;
+    note?: string;
+    priority?: TaskPriority;
+    needs?: readonly TaskId[];
+    addNeeds?: readonly TaskId[];
+    dropNeeds?: readonly TaskId[];
+    parent?: TaskId | null;
+    supersedes?: readonly TaskId[];
+    addSupersedes?: readonly TaskId[];
+    dropSupersedes?: readonly TaskId[];
+    relates?: readonly TaskId[];
+    addRelates?: readonly TaskId[];
+    dropRelates?: readonly TaskId[];
+    signal?: AbortSignal;
+}>;
+export declare function taskView(document: TaskDocument): TaskView;
+export declare function addTask(world: TaskWorld, input: AddTaskInput): Promise<TaskMutationResult>;
+export declare function addTaskDocument(world: TaskWorld, input: AddTaskDocumentInput): Promise<TaskMutationResult>;
+export declare function updateTask(world: TaskWorld, id: TaskId, input: UpdateTaskInput): Promise<TaskUpdateResult>;
+export declare function lifecycleTask(world: TaskWorld, id: TaskId, verb: TaskLifecycleVerb, signal?: AbortSignal, note?: string): Promise<TaskMutationResult>;
+export declare function batchTasks(world: TaskWorld, verb: "done" | "drop" | "hold", ids: readonly TaskId[], signal?: AbortSignal, note?: string): Promise<TaskBatchResult>;
+export declare function settleTask(world: TaskWorld, id: TaskId, desired: "done" | "open-from-done"): Promise<SettledTaskResult>;
+export declare function listTasks(world: TaskWorld, selection: "active" | "closed" | "all", scope?: "namespace" | "world"): TaskOutcome<readonly TaskRow[]>;
+export declare function readyTasks(world: TaskWorld, scope?: "namespace" | "world"): TaskOutcome<readonly TaskRow[]>;
+export declare function blockedTasks(world: TaskWorld, scope?: "namespace" | "world"): TaskOutcome<readonly BlockedTaskRow[]>;
+export declare function setCurrentNamespace(world: TaskWorld, namespace: readonly string[]): void;
+export declare function currentNamespace(world: TaskWorld): readonly string[] | TaskRefusal;

package/build/src/task/operations.js

@@ -0,0 +1,194 @@
+import { documentDiff } from "../markdown/diff.js";
+import { installNamespaceContext, readNamespaceContext } from "./context.js";
+import { relationProblem, projectBlocked, projectReady, projectRows } 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";
+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) {
+    if (explicit !== undefined)
+        return explicit;
+    const current = readNamespaceContext(world.root);
+    return current === "malformed" ? { kind: "invalid-namespace-context", path: `${world.root}/.keiyaku/namespace/current` }
+        : current === "absent" ? [] : current;
+}
+function occupied(board, namespace) {
+    return new Set([...board.tasks.values()].flatMap((task) => {
+        const coordinate = parseTaskId(task.id);
+        return sameNamespace(coordinate.namespace, namespace) ? [coordinate.localId] : [];
+    }));
+}
+function currentTimestamp() { return new Date().toISOString(); }
+function advancedTimestamp(previous) {
+    const current = currentTimestamp();
+    return current > previous ? current : new Date(Date.parse(previous) + 1).toISOString();
+}
+function addDocument(base, namespace, board, at) {
+    const localId = allocateLocalId(deriveLocalStem(base.title), occupied(board, namespace));
+    return { ...base, id: formatTaskId({ namespace, localId }), 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) {
+    const result = await withTaskLocks({ world, allocation: true, ids: [], ...(signal === undefined ? {} : { signal }) }, async () => {
+        const snapshot = readBoard(world), next = addDocument(base, namespace, snapshot.board, currentTimestamp());
+        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) });
+        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);
+    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);
+}
+export async function addTaskDocument(world, input) {
+    const namespace = context(world, input.namespace);
+    if (!Array.isArray(namespace))
+        return refused(namespace);
+    return create(world, parseTaskCreationDocument(input.markdown), namespace, input.signal);
+}
+function listChange(current, replacement, additions, removals) {
+    const next = [...(replacement ?? current)];
+    for (const id of additions ?? [])
+        if (!next.includes(id))
+            next.push(id);
+    return next.filter((id) => !(removals ?? []).includes(id));
+}
+function relatedOwner(board, id, target) {
+    return board.tasks.get(target)?.relates.includes(id) ? target : null;
+}
+function updateDocument(board, current, input) {
+    for (const related of input.dropRelates ?? [])
+        if (!current.relates.includes(related)) {
+            const owner = relatedOwner(board, current.id, related);
+            if (owner !== null)
+                return { kind: "relation-owned-by-other", taskId: current.id, related, declaringTask: owner };
+        }
+    return {
+        ...current,
+        ...(input.title === undefined ? {} : { title: input.title }),
+        body: input.body ?? (input.appendBody === undefined ? current.body : current.body + input.appendBody),
+        ...(input.note === undefined ? {} : { note: input.note }),
+        ...(input.priority === undefined ? {} : { priority: input.priority }),
+        needs: listChange(current.needs, input.needs, input.addNeeds, input.dropNeeds),
+        ...(input.parent === undefined ? {} : { parent: input.parent }),
+        supersedes: listChange(current.supersedes, input.supersedes, input.addSupersedes, input.dropSupersedes),
+        relates: listChange(current.relates, input.relates, input.addRelates, input.dropRelates),
+    };
+}
+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);
+        if (current === undefined)
+            return { kind: "refused", refusal: { kind: "task-missing", taskId: id } };
+        const candidate = updateDocument(snapshot.board, current, input);
+        if ("kind" in candidate)
+            return { kind: "refused", refusal: candidate };
+        const problem = relationProblem(boardWith(snapshot.board, candidate), current, candidate);
+        if (problem !== null)
+            return { kind: "refused", refusal: { kind: "invalid-graph", diagnostic: problem } };
+        const predecessor = snapshot.bytes.get(id), before = Buffer.from(predecessor).toString("utf8");
+        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")
+            return { kind: "retry", reason: "concurrent-modification" };
+        const label = `${id}.md`;
+        return { kind: "accepted", value: { task: taskView(next), documentDiff: documentDiff(label, label, before, after) } };
+    });
+    return result === "busy" ? { kind: "retry", reason: "busy" } : result;
+}
+const TRANSITIONS = {
+    start: { open: "in_progress" }, stop: { in_progress: "open" }, hold: { open: "on_hold", in_progress: "on_hold" },
+    resume: { on_hold: "open" }, done: { open: "done", in_progress: "done", on_hold: "done" },
+    drop: { open: "drop", in_progress: "drop", on_hold: "drop" },
+};
+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);
+        if (current === undefined)
+            return refused({ kind: "task-missing", taskId: id });
+        const state = TRANSITIONS[verb][current.state];
+        if (state === undefined)
+            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"
+            ? { kind: "accepted", value: taskView(next) } : retry("concurrent-modification");
+    });
+    return result === "busy" ? retry("busy") : result;
+}
+export async function batchTasks(world, verb, ids, signal, note) {
+    const items = [];
+    for (const id of ids) {
+        signal?.throwIfAborted();
+        items.push({ id, outcome: await lifecycleTask(world, id, verb, signal, note) });
+    }
+    return { items };
+}
+export async function settleTask(world, id, desired) {
+    const result = await withTaskLocks({ world, allocation: false, ids: [id] }, async () => {
+        const snapshot = 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")
+            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) });
+        return replaced === "replaced"
+            ? { kind: "changed", task: taskView(next), action: desired === "done" ? "done" : "reopened" }
+            : { kind: "retry", reason: "concurrent-modification" };
+    });
+    return result === "busy" ? { kind: "retry", reason: "busy" } : result;
+}
+function readScope(world, scope) {
+    if (scope === "world")
+        return null;
+    return context(world);
+}
+export function listTasks(world, selection, scope) {
+    const selected = readScope(world, scope);
+    if (selected !== null && !Array.isArray(selected))
+        return { kind: "refused", refusal: selected };
+    return { kind: "accepted", value: projectRows(readBoard(world).board, selected, selection) };
+}
+export function readyTasks(world, scope) {
+    const selected = 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);
+    if (selected !== null && !Array.isArray(selected))
+        return { kind: "refused", refusal: selected };
+    return { kind: "accepted", value: projectBlocked(readBoard(world).board, selected) };
+}
+export function setCurrentNamespace(world, namespace) { installNamespaceContext(world.root, namespace); }
+export function currentNamespace(world) {
+    const selected = context(world);
+    return selected;
+}

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

@@ -0,0 +1,22 @@
+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 replaceAuthority(input: Readonly<{
+    path: string;
+    expected: Uint8Array | null;
+    next: Uint8Array;
+}>): "replaced" | "concurrent-modification";
+export declare function withTaskLocks<T>(input: Readonly<{
+    world: TaskWorld;
+    allocation: boolean;
+    ids: readonly TaskId[];
+    signal?: AbortSignal;
+}>, action: () => Promise<T>): Promise<T | "busy">;
+export declare function authorityPath(world: TaskWorld, id: TaskId): string;

package/build/src/task/store.js

@@ -0,0 +1,114 @@
+import { randomBytes } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, relative, resolve, sep } from "node:path";
+import { acquireSqliteTransactionLock, SqliteTransactionLockError } from "../coordination/sqlite-transaction-lock.js";
+import { parseTaskDocument } from "./document.js";
+import { formatTaskId, parseTaskId, taskAuthorityPath } from "./identity.js";
+function tasksDirectory(world) { return resolve(world.root, ".keiyaku", "tasks"); }
+function authorityFiles(directory) {
+    if (!existsSync(directory))
+        return [];
+    const files = [];
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        const path = resolve(directory, entry.name);
+        if (entry.isDirectory())
+            files.push(...authorityFiles(path));
+        else if (entry.isFile() && entry.name.endsWith(".md"))
+            files.push(path);
+        else
+            throw new Error(`unexpected Task authority entry: ${path}`);
+    }
+    return files.sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)));
+}
+function coordinateFromPath(tasksDirectory, path) {
+    const local = relative(tasksDirectory, path);
+    if (local.startsWith("..") || resolve(tasksDirectory, local) !== path || !local.endsWith(".md"))
+        throw new Error(`invalid Task authority path: ${path}`);
+    return parseTaskId(`task/${local.slice(0, -3).split(sep).join("/")}`);
+}
+export function readBoard(world) {
+    const directory = tasksDirectory(world);
+    const tasks = new Map(), bytes = new Map();
+    for (const path of authorityFiles(directory)) {
+        const stat = lstatSync(path);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error(`Task authority is not a regular file: ${path}`);
+        const coordinate = coordinateFromPath(directory, path);
+        const id = formatTaskId(coordinate);
+        const source = readFileSync(path);
+        tasks.set(id, parseTaskDocument(source, coordinate));
+        bytes.set(id, source);
+    }
+    return { board: { tasks }, bytes };
+}
+function equal(left, right) {
+    return left === null || right === null ? left === right : Buffer.from(left).equals(Buffer.from(right));
+}
+function currentBytes(path) {
+    try {
+        return readFileSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+export function replaceAuthority(input) {
+    const parent = dirname(input.path);
+    mkdirSync(parent, { recursive: true });
+    const temporary = resolve(parent, `.tmp-${randomBytes(8).toString("hex")}`);
+    let descriptor;
+    try {
+        descriptor = openSync(temporary, "wx", 0o600);
+        writeFileSync(descriptor, input.next);
+        fsyncSync(descriptor);
+        closeSync(descriptor);
+        descriptor = undefined;
+        if (!equal(currentBytes(input.path), input.expected))
+            return "concurrent-modification";
+        renameSync(temporary, input.path);
+        const directoryDescriptor = openSync(parent, "r");
+        try {
+            fsyncSync(directoryDescriptor);
+        }
+        finally {
+            closeSync(directoryDescriptor);
+        }
+        return "replaced";
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+        try {
+            unlinkSync(temporary);
+        }
+        catch { /* renamed or best effort */ }
+    }
+}
+function lockPath(world, id) {
+    const coordinate = parseTaskId(id);
+    return resolve(world.root, ".keiyaku", "locks", "task", ...coordinate.namespace, `${coordinate.localId}.sqlite`);
+}
+export async function withTaskLocks(input, action) {
+    const paths = [
+        ...(input.allocation ? [resolve(input.world.root, ".keiyaku", "locks", "task-allocation.sqlite")] : []),
+        ...[...new Set(input.ids)].sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b))).map((id) => lockPath(input.world, id)),
+    ];
+    const held = [];
+    try {
+        for (const path of paths)
+            held.push(await acquireSqliteTransactionLock({ path, mode: "immediate", timeoutMs: 3_000, ...(input.signal === undefined ? {} : { signal: input.signal }) }));
+        return await action();
+    }
+    catch (error) {
+        if (error instanceof SqliteTransactionLockError && error.reason === "timeout")
+            return "busy";
+        throw error;
+    }
+    finally {
+        for (const lock of held.reverse())
+            lock.close();
+    }
+}
+export function authorityPath(world, id) { return taskAuthorityPath(tasksDirectory(world), parseTaskId(id)); }

package/build/src/verification/declaration.d.ts

@@ -0,0 +1,22 @@
+import type { Preparation } from "../core/decide.js";
+import { type ContractId, type DocumentSegmentKey, type Gate } from "../core/facts/types.js";
+export type VerificationExecutor = "bash" | "zsh" | "pwsh";
+export type VerificationDeclaration = Readonly<{
+    readonly executor: VerificationExecutor;
+    readonly script: string;
+}>;
+export type VerificationDefinition = Readonly<{
+    readonly segment: DocumentSegmentKey;
+    readonly declarations: readonly VerificationDeclaration[];
+}>;
+export type VerificationDeclarationRefusal = Readonly<{
+    kind: "verification-declaration-invalid";
+    contractId?: ContractId;
+}>;
+export type VerificationDeclarationPreparation = Preparation<VerificationDefinition | null, VerificationDeclarationRefusal>;
+export declare const VERIFIED: Gate;
+export declare function prepareVerificationDeclaration(input: Readonly<{
+    gates: readonly Gate[];
+    definition: VerificationDefinition | null;
+    contractId?: ContractId;
+}>): VerificationDeclarationPreparation;

package/build/src/verification/declaration.js

@@ -0,0 +1,14 @@
+import { gate } from "../core/facts/types.js";
+export const VERIFIED = gate("verified");
+export function prepareVerificationDeclaration(input) {
+    if (input.definition !== null || !input.gates.includes(VERIFIED)) {
+        return { kind: "prepared", data: input.definition };
+    }
+    return {
+        kind: "refused",
+        refusal: {
+            kind: "verification-declaration-invalid",
+            ...(input.contractId === undefined ? {} : { contractId: input.contractId }),
+        },
+    };
+}