@astrosheep/keiyaku 4.0.0 → 4.0.2

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

@@ -1,7 +1,10 @@
 import type { TreeUpdate } from "../core/facts/offer.js";
 import { type ContractId } from "../core/facts/types.js";
-import { type GitRepository, type GitSnapshot } from "../git/repository.js";
+import type { GitDecisionObservation } from "../git/observe.js";
+import { type GitRepository } from "../git/repository.js";
+import { type GitDecodeChannel, type GitReadObservation, type GitTreeSelection } from "../git/read-observation.js";
 import { type TaskId } from "../task/identity.js";
+export declare function taskHolderObservationSelection(): GitTreeSelection;
 export type TaskHolder = Readonly<{
     version: 1;
     taskId: TaskId;
@@ -10,6 +13,34 @@ export type TaskHolder = Readonly<{
 }>;
 export type TaskHolderProjection = ReadonlyMap<ContractId, TaskHolder>;
 export declare function claimTaskHolder(taskId: TaskId, owner: ContractId): TreeUpdate;
-export declare function releaseTaskHolder(repository: GitRepository, snapshot: GitSnapshot, owner: ContractId): TreeUpdate | null;
-export declare function readTaskHolders(repository: GitRepository): readonly TaskHolder[];
-export declare function readTaskHolderProjection(repository: GitRepository): TaskHolderProjection;
+type AdmissionOutcome = Readonly<{
+    kind: string;
+}>;
+export type TaskHolderAdmission<T extends AdmissionOutcome> = Readonly<{
+    kind: "completed";
+    result: T;
+}> | Readonly<{
+    kind: "accepted-release-failed";
+    result: T;
+    taskId: TaskId;
+    diagnostic: string;
+}>;
+export declare function finishTaskHolderAdmission<T extends AdmissionOutcome>(taskId: TaskId, result: T, close: () => void): TaskHolderAdmission<T>;
+export declare function claimTaskHolderWithFence<T extends AdmissionOutcome>(repository: GitRepository, taskId: TaskId, action: () => T | Promise<T>): Promise<TaskHolderAdmission<T>>;
+export declare function releaseTaskHolder(channel: GitDecodeChannel, observation: GitDecisionObservation, owner: ContractId): Promise<TreeUpdate | null>;
+export type TaskHolderReleasePublication = Readonly<{
+    kind: "released";
+}> | Readonly<{
+    kind: "not-held";
+}> | Readonly<{
+    kind: "non-published";
+    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 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>>;
+export declare function readTaskHoldersAt(observation: Pick<GitReadObservation, "snapshot" | "readBlobs">): Promise<readonly TaskHolder[]>;
+export declare function readTaskHolderProjectionAt(observation: GitReadObservation): Promise<TaskHolderProjection>;
+export {};

package/build/src/settlement/holder.js

@@ -1,11 +1,16 @@
 import { createHash } from "node:crypto";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
 import { contractId } from "../core/facts/types.js";
-import { expandGitSnapshot, readBlob, readGit, } from "../git/repository.js";
+import { GIT_REF, updateGitTree, updateRefsAtomically, writeBlob, writeCommit, } from "../git/repository.js";
+import { withGitTargetedReadObservation, } from "../git/read-observation.js";
 import { parseTaskId } from "../task/identity.js";
+import { acquireTaskSettlementFence } from "./fence.js";
 const HOLDER_ROOT = "settlement/task-holders";
 const HOLDER_PREFIX = `${HOLDER_ROOT}/`;
 const HOLDER_SUFFIX = ".json";
+export function taskHolderObservationSelection() {
+    return { subtrees: [HOLDER_ROOT] };
+}
 function holderPath(taskId) {
     const digest = createHash("sha256").update(taskId).digest("hex");
     return `${HOLDER_PREFIX}${digest}${HOLDER_SUFFIX}`;
@@ -62,27 +67,6 @@ function decodeHolder(path, bytes) {
         corruption(`TaskHolder bytes are not canonical: ${path}`);
     return holder;
 }
-function holderEntries(repository, snapshot, scope) {
-    const expanded = scope === "complete" ? snapshot : expandGitSnapshot(repository, snapshot);
-    const holders = [];
-    const seen = new Set();
-    for (const [path, entry] of expanded.paths) {
-        if (path === HOLDER_ROOT)
-            corruption(`TaskHolder authority root is not a tree: ${path}`);
-        if (!path.startsWith(HOLDER_PREFIX))
-            continue;
-        if (!path.endsWith(HOLDER_SUFFIX))
-            corruption(`unexpected TaskHolder authority path: ${path}`);
-        if (entry.type !== "blob")
-            corruption(`TaskHolder path is not a blob: ${path}`);
-        const holder = decodeHolder(path, readBlob(repository, entry.oid));
-        if (seen.has(holder.taskId))
-            corruption(`duplicate TaskHolder identity: ${holder.taskId}`);
-        seen.add(holder.taskId);
-        holders.push(holder);
-    }
-    return holders.sort((left, right) => Buffer.compare(Buffer.from(left.taskId), Buffer.from(right.taskId)));
-}
 function projectTaskHolders(holders) {
     const projection = new Map();
     for (const holder of holders) {
@@ -99,15 +83,130 @@ function update(holder) {
 export function claimTaskHolder(taskId, owner) {
     return update({ version: 1, taskId, contractId: owner, disposition: "held" });
 }
-export function releaseTaskHolder(repository, snapshot, owner) {
-    const current = projectTaskHolders(holderEntries(repository, snapshot, "targeted")).get(owner) ?? null;
+function detail(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function finishTaskHolderAdmission(taskId, result, close) {
+    try {
+        close();
+        return { kind: "completed", result };
+    }
+    catch (error) {
+        if (result.kind !== "accepted")
+            throw error;
+        return { kind: "accepted-release-failed", result, taskId, diagnostic: detail(error) };
+    }
+}
+async function admitWithTaskHolderFence(repository, taskId, action) {
+    const held = await acquireTaskSettlementFence(repository, taskId);
+    let result;
+    try {
+        result = await action();
+    }
+    catch (error) {
+        try {
+            held.close();
+        }
+        catch { /* The operation failure remains decisive before admission. */ }
+        throw error;
+    }
+    return finishTaskHolderAdmission(taskId, result, () => held.close());
+}
+export function claimTaskHolderWithFence(repository, taskId, action) {
+    return admitWithTaskHolderFence(repository, taskId, action);
+}
+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" });
 }
-export function readTaskHolders(repository) {
-    return holderEntries(repository, readGit(repository), "complete");
+/** Publish the released holder against the same frozen observation that decided the release. */
+export async function publishTaskHolderRelease(repository, channel, observation, owner) {
+    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({
+        repository,
+        tree,
+        parent: observation.admission.snapshot.commit,
+        message: `release held Task completion: ${owner}`,
+    });
+    const publication = await updateRefsAtomically(repository, [{
+            ref: GIT_REF,
+            newOid: commit,
+            expectedOid: observation.admission.snapshot.commit,
+        }]);
+    if (publication.kind === "published")
+        return { kind: "released" };
+    return {
+        kind: "non-published",
+        diagnostic: publication.kind === "non-published" ? detail(publication.error) : "Task holder release publication state is unknown",
+    };
+}
+export async function readTaskHolderProjectionFromDecision(channel, observation) {
+    const read = {
+        snapshot: observation.admission.snapshot,
+        readBlobs: async (oids) => {
+            const objects = await channel.readObjects(oids);
+            const blobs = new Map();
+            for (const [oid, object] of objects) {
+                if (object.kind === "missing")
+                    blobs.set(oid, object);
+                else {
+                    if (object.type !== "blob")
+                        corruption(`TaskHolder Git object is not a blob: ${oid}`);
+                    blobs.set(oid, { kind: "present", bytes: object.bytes });
+                }
+            }
+            return blobs;
+        },
+    };
+    return projectTaskHolders(await readTaskHoldersAt(read));
+}
+export function observeTaskHolderProjection(repository, channel) {
+    return withGitTargetedReadObservation(repository, channel, taskHolderObservationSelection(), readTaskHolderProjectionAt);
+}
+async function heldTaskForContract(repository, channel, owner) {
+    const holder = (await observeTaskHolderProjection(repository, channel)).get(owner) ?? null;
+    return holder?.disposition === "held" ? holder.taskId : null;
+}
+export async function releaseTaskHolderWithFence(repository, channel, owner, action) {
+    const taskId = await heldTaskForContract(repository, channel, owner);
+    return taskId === null
+        ? { kind: "completed", result: await action() }
+        : admitWithTaskHolderFence(repository, taskId, action);
+}
+export async function readTaskHoldersAt(observation) {
+    const entries = [...observation.snapshot.paths]
+        .filter(([path, entry]) => path.startsWith(HOLDER_PREFIX) && entry.type === "blob");
+    const blobs = await observation.readBlobs(entries.map(([, entry]) => entry.oid));
+    const holders = [];
+    const seen = new Set();
+    for (const [path, entry] of observation.snapshot.paths) {
+        if (path === HOLDER_ROOT) {
+            if (entry.type !== "tree")
+                corruption(`TaskHolder authority root is not a tree: ${path}`);
+            continue;
+        }
+        if (!path.startsWith(HOLDER_PREFIX))
+            continue;
+        if (!path.endsWith(HOLDER_SUFFIX))
+            corruption(`unexpected TaskHolder authority path: ${path}`);
+        if (entry.type !== "blob")
+            corruption(`TaskHolder path is not a blob: ${path}`);
+        const result = blobs.get(entry.oid);
+        if (result?.kind !== "present")
+            corruption(`missing TaskHolder Git object: ${path}`);
+        const holder = decodeHolder(path, result.bytes);
+        if (seen.has(holder.taskId))
+            corruption(`duplicate TaskHolder identity: ${holder.taskId}`);
+        seen.add(holder.taskId);
+        holders.push(holder);
+    }
+    return holders.sort((left, right) => Buffer.compare(Buffer.from(left.taskId), Buffer.from(right.taskId)));
 }
-export function readTaskHolderProjection(repository) {
-    return projectTaskHolders(readTaskHolders(repository));
+export async function readTaskHolderProjectionAt(observation) {
+    return projectTaskHolders(await readTaskHoldersAt(observation));
 }

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

@@ -1,11 +1,12 @@
 import { type ContractId, type ContractState } from "../core/facts/types.js";
+import type { GitDecodeChannel } from "../git/read-observation.js";
 import type { Effect } from "../git/reconcile.js";
 import type { GitRepository } from "../git/repository.js";
 import type { TaskId } from "../task/identity.js";
 export type SettlementAction = Readonly<{
     kind: "task";
     taskId: TaskId;
-    action: "done" | "reopened";
+    action: "done";
 }> | Readonly<{
     kind: "namespace-context";
     path: string;
@@ -23,13 +24,20 @@ export type SettlementReport = Readonly<{
     actions: readonly SettlementAction[];
     lags: readonly SettlementLag[];
 }>;
+export declare function deferredTaskHolderSettlement(input: Readonly<{
+    contractId: ContractId;
+    taskId: TaskId;
+    diagnostic: string;
+}>): SettlementReport;
 export type SettlementInput = Readonly<{
     repository: GitRepository;
+    channel: GitDecodeChannel;
     state: ContractState | null;
     effects: readonly Effect[];
 }>;
 export type SettlementBatchInput = Readonly<{
     repository: GitRepository;
+    channel: GitDecodeChannel;
     contracts: readonly Readonly<Pick<SettlementInput, "state" | "effects">>[];
 }>;
 export declare function settle(input: SettlementInput): Promise<SettlementReport>;

package/build/src/settlement/settle.js

@@ -1,7 +1,12 @@
 import { contractSegment } from "../core/facts/types.js";
+import { observeContractsForAdmissionAt } from "../git/observe.js";
 import { repairNamespaceContext } from "../task/context.js";
 import { settleTask } from "../task/operations.js";
-import { readTaskHolderProjection } from "./holder.js";
+import { publishTaskHolderRelease, readTaskHolderProjectionFromDecision, taskHolderObservationSelection, } from "./holder.js";
+import { World } from "../world.js";
+export function deferredTaskHolderSettlement(input) {
+    return { actions: [], lags: [{ kind: "settlement-failed", surface: "task-holder", ...input }] };
+}
 function diagnostic(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -10,46 +15,71 @@ function taskFailure(result) {
         ? `Task settlement requires retry: ${result.reason}`
         : `Task settlement refused: ${JSON.stringify(result.refusal)}`;
 }
-async function settleTasks(observation, world, state, actions, lags) {
-    const terminal = state.terminal?.kind;
-    if (terminal !== "claimed" && terminal !== "abandoned")
+async function settleTasks(input) {
+    const { repository, channel, world, candidate, actions, lags } = input;
+    let observation;
+    try {
+        observation = await observeContractsForAdmissionAt(repository, channel, [candidate.id], taskHolderObservationSelection());
+    }
+    catch (error) {
+        lags.push({ kind: "settlement-failed", surface: "task-holder", contractId: candidate.id, diagnostic: diagnostic(error) });
         return;
-    if (observation.kind === "failed") {
-        lags.push({ kind: "settlement-failed", surface: "task-holder", contractId: state.id, diagnostic: observation.diagnostic });
+    }
+    const state = observation.journals.get(candidate.id)?.state ?? null;
+    if (state === null || state.terminal?.kind !== "claimed")
         return;
+    let holder;
+    try {
+        holder = (await readTaskHolderProjectionFromDecision(channel, observation)).get(candidate.id) ?? null;
     }
-    const holder = observation.holders.get(state.id) ?? null;
-    const expectedDisposition = terminal === "claimed" ? "held" : "released";
-    if (holder === null || holder.disposition !== expectedDisposition)
+    catch (error) {
+        lags.push({ kind: "settlement-failed", surface: "task-holder", contractId: candidate.id, diagnostic: diagnostic(error) });
+        return;
+    }
+    if (holder === null || holder.disposition !== "held")
         return;
     const taskId = holder.taskId;
+    let result;
+    try {
+        result = await settleTask(world, taskId);
+    }
+    catch (error) {
+        lags.push({ kind: "settlement-failed", surface: "task", contractId: candidate.id, taskId, diagnostic: diagnostic(error) });
+        return;
+    }
+    if (result.kind === "changed")
+        actions.push({ kind: "task", taskId, action: "done" });
+    else if (result.kind !== "unchanged") {
+        lags.push({ kind: "settlement-failed", surface: "task", contractId: candidate.id, taskId, diagnostic: taskFailure(result) });
+        return;
+    }
     try {
-        const result = await settleTask(world, taskId, terminal === "claimed" ? "done" : "open-from-done");
-        if (result.kind === "changed")
-            actions.push({ kind: "task", taskId, action: result.action });
-        else if (result.kind !== "unchanged")
+        const publication = await publishTaskHolderRelease(repository, channel, observation, candidate.id);
+        if (publication.kind === "non-published") {
             lags.push({
                 kind: "settlement-failed",
-                surface: "task",
-                contractId: state.id,
+                surface: "task-holder",
+                contractId: candidate.id,
                 taskId,
-                diagnostic: taskFailure(result),
+                diagnostic: `Task holder release requires retry: ${publication.diagnostic}`,
             });
+        }
     }
     catch (error) {
-        lags.push({ kind: "settlement-failed", surface: "task", contractId: state.id, taskId, diagnostic: diagnostic(error) });
+        lags.push({ kind: "settlement-failed", surface: "task-holder", contractId: candidate.id, taskId, diagnostic: diagnostic(error) });
     }
 }
-function settleNamespace(state, effects, actions, lags) {
-    if (state.terminal !== null || state.coordinates.workspace !== "worktree" || state.bound === null)
+async function settleNamespace(state, effects, actions, lags) {
+    if (state.terminal !== null || state.coordinates.workspace !== "worktree")
         return;
     const worktrees = effects.filter((effect) => effect.kind === "worktree" && effect.action !== "removed");
     for (const effect of worktrees) {
         try {
+            const world = await World.at(effect.path);
             actions.push({
                 kind: "namespace-context",
                 path: effect.path,
-                action: repairNamespaceContext(effect.path, [contractSegment(state.id)]),
+                action: await repairNamespaceContext(world, [contractSegment(state.id)]),
             });
         }
         catch (error) {
@@ -63,29 +93,36 @@ function settleNamespace(state, effects, actions, lags) {
         }
     }
 }
-function observeSettlement(repository) {
-    try {
-        return { kind: "present", holders: readTaskHolderProjection(repository) };
-    }
-    catch (error) {
-        return { kind: "failed", diagnostic: diagnostic(error) };
-    }
-}
-async function settleObserved(input, observation) {
+async function settleObserved(input) {
     if (input.state === null)
         return { actions: [], lags: [] };
     const actions = [], lags = [];
-    await settleTasks(observation, { root: input.repository.primaryWorktree }, input.state, actions, lags);
-    settleNamespace(input.state, input.effects, actions, lags);
+    if (input.state.terminal?.kind === "claimed") {
+        try {
+            await settleTasks({
+                repository: input.repository,
+                channel: input.channel,
+                world: await World.at(input.repository.primaryWorktree),
+                candidate: input.state,
+                actions,
+                lags,
+            });
+        }
+        catch (error) {
+            lags.push({ kind: "settlement-failed", surface: "task", contractId: input.state.id, diagnostic: diagnostic(error) });
+        }
+    }
+    await settleNamespace(input.state, input.effects, actions, lags);
     return { actions, lags };
 }
+function onPrimaryWorktree(repository) {
+    return { ...repository, effectiveCwd: repository.primaryWorktree };
+}
 export async function settle(input) {
-    return settleObserved(input, observeSettlement(input.repository));
+    const repository = onPrimaryWorktree(input.repository);
+    return await settleObserved({ ...input, repository });
 }
 export async function settleAll(input) {
-    const observation = observeSettlement(input.repository);
-    return Promise.all(input.contracts.map((contract) => settleObserved({
-        repository: input.repository,
-        ...contract,
-    }, observation)));
+    const repository = onPrimaryWorktree(input.repository);
+    return await Promise.all(input.contracts.map((contract) => settleObserved({ repository, channel: input.channel, ...contract })));
 }

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

@@ -1,11 +1,11 @@
 import type { TaskDocument, TaskPriority, TaskState } from "./document.js";
 import { type TaskId } from "./identity.js";
-type TaskRef = Readonly<{
+export type TaskRef = Readonly<{
     id: TaskId;
     title: string | null;
     state: TaskState | "missing";
 }>;
-type TaskDisposition = "ready" | "blocked" | "in_progress" | "on_hold" | "done" | "drop";
+export type TaskDisposition = "ready" | "blocked" | "in_progress" | "on_hold" | "done" | "drop";
 export type TaskRow = Readonly<{
     id: TaskId;
     title: string;
@@ -34,8 +34,7 @@ export type TaskTreeNode = Readonly<{
         priority: TaskPriority | null;
     }>;
     cycle?: true;
-    reference?: true;
-    needs: readonly TaskTreeNode[];
+    children: readonly TaskTreeNode[];
 }>;
 export type TaskBoard = Readonly<{
     tasks: ReadonlyMap<TaskId, TaskDocument>;
@@ -55,11 +54,30 @@ export type TaskDoctorIssue = Readonly<{
     relation: "needs" | "parent" | "supersedes";
     tasks: readonly TaskId[];
 }>;
+export declare function taskDisposition(board: TaskBoard, task: TaskDocument): TaskDisposition;
 export declare function projectDetailFacts(board: TaskBoard, id: TaskId): TaskDetailFacts | null;
 export declare function projectRows(board: TaskBoard, scope: readonly string[] | null, selection: "active" | "closed" | "all"): readonly TaskRow[];
 export declare function projectReady(board: TaskBoard, scope: readonly string[] | null): readonly TaskRow[];
 export declare function projectBlocked(board: TaskBoard, scope: readonly string[] | null): readonly BlockedTaskRow[];
+export declare function projectStatusRows(board: TaskBoard, scope: readonly string[] | null): (Readonly<{
+    id: TaskId;
+    title: string;
+    state: TaskState;
+    priority: TaskPriority;
+    disposition: TaskDisposition;
+}> | {
+    blockers: readonly Readonly<{
+        id: TaskId;
+        title: string | null;
+        state: TaskState | "missing";
+    }>[];
+    id: TaskId;
+    title: string;
+    state: TaskState;
+    priority: TaskPriority;
+    disposition: TaskDisposition;
+})[];
 export declare function relationProblem(board: TaskBoard, before: TaskDocument | null, after: TaskDocument): string | null;
 export declare function diagnoseBoard(board: TaskBoard): readonly TaskDoctorIssue[];
-export declare function buildTree(board: TaskBoard, root: TaskId, full: boolean): TaskTreeNode | null;
+export declare function buildTree(board: TaskBoard, root: TaskId): TaskTreeNode | null;
 export {};

package/build/src/task/board.js

@@ -19,7 +19,7 @@ function related(board, task) {
             ids.add(candidate.id);
     return sorted([...ids].map((id) => taskRef(board, id)));
 }
-function disposition(board, task) {
+export function taskDisposition(board, task) {
     if (task.state !== "open")
         return task.state;
     return task.needs.every((id) => { const target = board.tasks.get(id); return target !== undefined && terminal(target.state); }) ? "ready" : "blocked";
@@ -30,7 +30,10 @@ export function projectDetailFacts(board, id) {
         return null;
     const needs = task.needs.map((need) => ({ ...taskRef(board, need), released: board.tasks.has(need) && terminal(board.tasks.get(need).state) }));
     return {
-        task, needs, blockers: needs.filter((need) => !need.released), blocks: reverse(board, id, "needs"),
+        task,
+        needs,
+        blockers: needs.filter((need) => !need.released).map(({ released: _released, ...ref }) => ref),
+        blocks: reverse(board, id, "needs"),
         parent: task.parent === null ? null : taskRef(board, task.parent), children: children(board, id),
         supersedes: task.supersedes.map((target) => taskRef(board, target)), supersededBy: reverse(board, id, "supersedes"),
         related: related(board, task),
@@ -41,7 +44,7 @@ export function projectRows(board, scope, selection) {
     return [...board.tasks.values()].filter((task) => inScope(task, scope)).filter((task) => selection === "all"
         || (selection === "closed") === terminal(task.state)).map((task) => ({
         id: task.id, title: task.title, state: task.state, priority: task.priority,
-        disposition: disposition(board, task),
+        disposition: taskDisposition(board, task),
     })).sort((a, b) => a.priority - b.priority || Buffer.compare(Buffer.from(a.id), Buffer.from(b.id)));
 }
 export function projectReady(board, scope) {
@@ -55,6 +58,13 @@ export function projectBlocked(board, scope) {
         return blockers.length === 0 ? [] : [{ ...row, blockers }];
     });
 }
+export function projectStatusRows(board, scope) {
+    const blockers = new Map(projectBlocked(board, scope).map((row) => [row.id, row.blockers]));
+    return projectRows(board, scope, "all").map((row) => {
+        const unresolved = blockers.get(row.id);
+        return unresolved === undefined ? row : { ...row, blockers: unresolved };
+    });
+}
 function relationIds(task, relation) {
     return relation === "parent" ? task.parent === null ? [] : [task.parent] : task[relation];
 }
@@ -137,19 +147,16 @@ export function diagnoseBoard(board) {
     }
     return issues;
 }
-export function buildTree(board, root, full) {
+export function buildTree(board, root) {
     if (!board.tasks.has(root))
         return null;
-    const expanded = new Set();
     const walk = (id, path) => {
         const ref = taskRef(board, id);
         const task = board.tasks.get(id);
+        const node = { task: { ...ref, priority: task?.priority ?? null } };
         if (path.includes(id))
-            return { task: { ...ref, priority: task?.priority ?? null }, cycle: true, needs: [] };
-        if (!full && expanded.has(id))
-            return { task: { ...ref, priority: task?.priority ?? null }, reference: true, needs: [] };
-        expanded.add(id);
-        return { task: { ...ref, priority: task?.priority ?? null }, needs: task === undefined ? [] : task.needs.map((need) => walk(need, [...path, id])) };
+            return { ...node, cycle: true, children: [] };
+        return { ...node, children: children(board, id).map((child) => walk(child.id, [...path, id])) };
     };
     return walk(root, []);
 }

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

@@ -1,5 +1,5 @@
 import { type TaskId } from "./identity.js";
-import { type TaskWorld } from "./store.js";
+import type { WorldRoot } from "../world.js";
 import type { TaskRefusal, TaskRetry } from "./operations.js";
 type TaskDocumentChange = Readonly<{
     taskId: TaskId;
@@ -21,5 +21,5 @@ export type TaskCompositionResult = Readonly<{
     }>;
     draft: string;
 }>;
-export declare function composeTasks(world: TaskWorld, markdown: string, signal?: AbortSignal): Promise<TaskCompositionResult>;
+export declare function composeTasks(world: WorldRoot, markdown: string, signal?: AbortSignal, actor?: string): Promise<TaskCompositionResult>;
 export {};

package/build/src/task/compose.js

@@ -1,3 +1,4 @@
+import { resolve } from "node:path";
 import { documentDiff } from "../markdown/diff.js";
 import { readNamespaceContext } from "./context.js";
 import { relationProblem } from "./board.js";
@@ -119,7 +120,14 @@ function applyAssignments(document, assignments, body) {
 }
 function currentTimestamp() { return new Date().toISOString(); }
 function advancedTimestamp(previous, current) { return current > previous ? current : new Date(Date.parse(previous) + 1).toISOString(); }
-function plan(sketch, board, defaultNamespace, at) {
+function createdTask(id, title, at, actor) {
+    return {
+        id, title, state: "open", priority: 2, needs: [], parent: null, supersedes: [], relates: [], note: "",
+        ...(actor === undefined ? {} : { createdBy: actor }),
+        createdAt: at, updatedAt: at, body: "",
+    };
+}
+function plan(sketch, board, defaultNamespace, at, actor) {
     try {
         const namespace = sketch.namespace ?? defaultNamespace;
         const occupied = new Set([...board.tasks.values()].flatMap((task) => {
@@ -132,7 +140,7 @@ function plan(sketch, board, defaultNamespace, at) {
                 const localId = allocateLocalId(deriveLocalStem(node.title), occupied);
                 occupied.add(localId);
                 const coordinate = { namespace, localId };
-                allocations.set(node.index, { id: formatTaskId(coordinate), title: node.title, state: "open", priority: 2, needs: [], parent: null, supersedes: [], relates: [], note: "", createdAt: at, updatedAt: at, body: "" });
+                allocations.set(node.index, createdTask(formatTaskId(coordinate), node.title, at, actor));
             }
         const all = new Map(board.tasks);
         for (const allocated of allocations.values())
@@ -190,24 +198,24 @@ function draft(namespace, remaining) {
     }
     return `${lines.join("\n")}\n`;
 }
-export async function composeTasks(world, markdown, signal) {
+export async function composeTasks(world, markdown, signal, actor) {
     const sketch = parseSketch(markdown);
     if ("kind" in sketch)
         return { kind: "refused", refusal: sketch };
     const at = currentTimestamp();
-    const context = sketch.namespace ?? readNamespaceContext(world.root);
+    const context = sketch.namespace ?? await readNamespaceContext(world);
     if (context === "malformed")
-        return { kind: "refused", refusal: { kind: "invalid-namespace-context", path: `${world.root}/.keiyaku/namespace/current` } };
+        return { kind: "refused", refusal: { kind: "invalid-namespace-context", path: resolve(world, ".keiyaku", "namespace", "current") } };
     const namespace = context === "absent" ? [] : context;
-    const initial = readBoard(world);
-    const planned = plan(sketch, initial.board, namespace, at);
+    const initial = await readBoard(world);
+    const planned = plan(sketch, initial.board, namespace, at, actor);
     if ("kind" in planned)
         return { kind: "refused", refusal: planned };
     const ordered = [...planned].sort((a, b) => Buffer.compare(Buffer.from(a.after.id), Buffer.from(b.after.id)));
     const allocation = sketch.nodes.some((node) => node.kind === "new");
     const result = await withTaskLocks({ world, allocation, ids: ordered.map((item) => item.after.id), ...(signal === undefined ? {} : { signal }) }, async () => {
-        const fresh = readBoard(world);
-        const replanned = plan(sketch, fresh.board, namespace, at);
+        const fresh = await readBoard(world);
+        const replanned = plan(sketch, fresh.board, namespace, at, actor);
         if ("kind" in replanned)
             return { kind: "refused", refusal: replanned };
         const queue = [...replanned].sort((a, b) => Buffer.compare(Buffer.from(a.after.id), Buffer.from(b.after.id))), changes = [];
@@ -219,7 +227,7 @@ export async function composeTasks(world, markdown, signal) {
             const before = beforeBytes === null ? "" : Buffer.from(beforeBytes).toString("utf8"), after = Buffer.from(afterBytes).toString("utf8");
             if (before === after)
                 continue;
-            if (replaceAuthority({ path, expected: beforeBytes, next: afterBytes }) !== "replaced")
+            if (await replaceAuthority({ path, expected: beforeBytes, next: afterBytes }) !== "replaced")
                 return {
                     kind: "incomplete", documentChanges: changes, stopped: { kind: "retry", reason: "concurrent-modification" }, draft: draft(namespace, queue.slice(index)),
                 };

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

@@ -1,4 +1,4 @@
 export type NamespaceContextRead = readonly string[] | "absent" | "malformed";
-export declare function readNamespaceContext(root: string): NamespaceContextRead;
-export declare function installNamespaceContext(root: string, segments: readonly string[]): void;
-export declare function repairNamespaceContext(root: string, segments: readonly string[]): "kept" | "installed";
+export declare function readNamespaceContext(root: string): Promise<NamespaceContextRead>;
+export declare function installNamespaceContext(root: string, segments: readonly string[]): Promise<void>;
+export declare function repairNamespaceContext(root: string, segments: readonly string[]): Promise<"kept" | "installed">;