@astrosheep/keiyaku 4.1.0 → 4.1.2

package/build/src/task/operations.js

@@ -1,18 +1,22 @@
 import { documentDiff } from "../markdown/diff.js";
 import { createTaskRelations, projectDetailFacts, projectTaskBoardObservation, relationProblem, projectBlocked, projectRows, } from "./board.js";
-import { parseTaskCreationDocument, serializeTaskDocument } from "./document.js";
+import { parseTaskCreationDocument, serializeTaskDocument, } from "./document.js";
 import { allocateLocalId, deriveLocalStem, formatTaskId, parseTaskId, sameNamespace } from "./identity.js";
-import { authorityPath, nukeTaskAuthority, readBoard, replaceAuthority, withTaskLocks, } from "./store.js";
-import { DEFAULT_TASK_LIMIT, projectPage, projectQuery, queryUnderTargets, underExpression } from "./query.js";
-export async function nukeTask(world) {
-    if (await nukeTaskAuthority(world) === "busy")
+import { authorityPath, nukeTaskAuthority, readBoard, replaceAuthority, withTaskLocks } from "./store.js";
+import { DEFAULT_TASK_LIMIT, projectPage, projectQuery, queryUnderTargets, underExpression, } from "./query.js";
+export async function nukeTask(world, options) {
+    if ((await nukeTaskAuthority(world, options)) === "busy")
         throw new Error("Task reset lock contention");
 }
 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 refused(refusal) {
+    return { kind: "refused", refusal };
+}
+function retry(reason) {
+    return { kind: "retry", reason };
+}
 function occupied(board, namespace) {
     return new Set([...board.tasks.values()].flatMap((task) => {
         const coordinate = parseTaskId(task.id);
@@ -24,16 +28,16 @@ function currentTimestamp() {
 }
 /** Internal Task timestamp rule shared by ordinary mutations and compose. */
 export function advanceTaskTimestamp(previous, candidate) {
-    return candidate > previous
-        ? candidate
-        : new Date(Date.parse(previous) + 1).toISOString();
+    return candidate > previous ? candidate : new Date(Date.parse(previous) + 1).toISOString();
 }
 function addDocument(base, namespace, board, at, actor) {
     const localId = allocateLocalId(deriveLocalStem(base.title), occupied(board, namespace));
     return {
-        ...base, id: formatTaskId({ namespace, localId }),
+        ...base,
+        id: formatTaskId({ namespace, localId }),
         ...(actor === undefined ? {} : { createdBy: actor }),
-        createdAt: at, updatedAt: at,
+        createdAt: at,
+        updatedAt: at,
     };
 }
 function boardWith(board, document) {
@@ -47,16 +51,29 @@ async function create(world, base, namespace, signal, actor) {
         const problem = relationProblem(boardWith(snapshot.board, next), null, next);
         if (problem !== null)
             return refused({ kind: "invalid-graph", diagnostic: problem });
-        const replaced = await replaceAuthority({ path: authorityPath(world, next.id), expected: null, next: serializeTaskDocument(next) });
-        return replaced === "replaced" ? { kind: "accepted", value: taskView(next) } : retry("concurrent-modification");
+        const replaced = await replaceAuthority({
+            path: authorityPath(world, next.id),
+            expected: null,
+            next: serializeTaskDocument(next),
+        });
+        return replaced === "replaced"
+            ? { kind: "accepted", value: taskView(next) }
+            : retry("concurrent-modification");
     });
     return result === "busy" ? retry("busy") : result;
 }
 export async function addTask(world, input) {
     const namespace = input.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 ?? [],
+        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, input.actor);
 }
 export async function addTaskDocument(world, input) {
@@ -73,6 +90,12 @@ function listChange(current, replacement, additions, removals) {
 function relatedOwner(board, id, target) {
     return board.tasks.get(target)?.relates.includes(id) ? target : null;
 }
+function appendTaskBody(current, addition) {
+    if (current.length === 0 || addition.length === 0 || current.endsWith("\n") || addition.startsWith("\n")) {
+        return current + addition;
+    }
+    return `${current}\n${addition}`;
+}
 function updateDocument(board, current, input) {
     for (const related of input.dropRelates ?? [])
         if (!current.relates.includes(related)) {
@@ -83,7 +106,7 @@ function updateDocument(board, current, input) {
     return {
         ...current,
         ...(input.title === undefined ? {} : { title: input.title }),
-        body: input.body ?? (input.appendBody === undefined ? current.body : current.body + input.appendBody),
+        body: input.body ?? (input.appendBody === undefined ? current.body : appendTaskBody(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),
@@ -113,18 +136,25 @@ export async function updateTask(world, id, input) {
         }
         const afterBytes = serializeTaskDocument(next);
         const after = Buffer.from(afterBytes).toString("utf8");
-        if (before !== after
-            && await replaceAuthority({ path: authorityPath(world, id), expected: predecessor, next: afterBytes }) !== "replaced") {
+        if (before !== after &&
+            (await replaceAuthority({ path: authorityPath(world, id), expected: predecessor, next: afterBytes })) !==
+                "replaced") {
             return { kind: "retry", reason: "concurrent-modification" };
         }
         const label = `${id}.md`;
-        return { kind: "accepted", value: { task: taskView(next), documentDiff: documentDiff(label, label, before, after) } };
+        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" },
+    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) {
@@ -144,8 +174,13 @@ export async function lifecycleTask(world, id, verb, signal, note) {
             updatedAt: advanceTaskTimestamp(current.updatedAt, at),
         };
         const bytes = serializeTaskDocument(next);
-        return await replaceAuthority({ path: authorityPath(world, id), expected: snapshot.bytes.get(id), next: bytes }) === "replaced"
-            ? { kind: "accepted", value: taskView(next) } : retry("concurrent-modification");
+        return (await replaceAuthority({
+            path: authorityPath(world, id),
+            expected: snapshot.bytes.get(id),
+            next: bytes,
+        })) === "replaced"
+            ? { kind: "accepted", value: taskView(next) }
+            : retry("concurrent-modification");
     });
     return result === "busy" ? retry("busy") : result;
 }
@@ -165,7 +200,10 @@ export async function settleTask(world, id) {
         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" } };
+            return {
+                kind: "refused",
+                refusal: { kind: "invalid-lifecycle-transition", taskId: id, state: current.state, verb: "done" },
+            };
         }
         const at = currentTimestamp();
         const next = {
@@ -173,7 +211,11 @@ export async function settleTask(world, id) {
             state: "done",
             updatedAt: advanceTaskTimestamp(current.updatedAt, at),
         };
-        const replaced = await replaceAuthority({ path: authorityPath(world, id), expected: snapshot.bytes.get(id), next: serializeTaskDocument(next) });
+        const replaced = await replaceAuthority({
+            path: authorityPath(world, id),
+            expected: snapshot.bytes.get(id),
+            next: serializeTaskDocument(next),
+        });
         return replaced === "replaced"
             ? { kind: "changed", task: taskView(next), action: "done" }
             : { kind: "retry", reason: "concurrent-modification" };
@@ -181,12 +223,15 @@ export async function settleTask(world, id) {
     return result === "busy" ? { kind: "retry", reason: "busy" } : result;
 }
 function readScope(namespace, scope) {
-    return scope === "world" ? null : namespace ?? [];
+    return scope === "world" ? null : (namespace ?? []);
 }
 export async function listTasks(world, namespace, selection, scope, limit = DEFAULT_TASK_LIMIT) {
     const selected = readScope(namespace, scope);
     const board = (await readBoard(world)).board;
-    return { kind: "accepted", value: projectPage(projectRows(board, createTaskRelations(board), selected, selection), limit) };
+    return {
+        kind: "accepted",
+        value: projectPage(projectRows(board, createTaskRelations(board), selected, selection), limit),
+    };
 }
 export async function readTaskDetails(world, ids) {
     const board = (await readBoard(world)).board;
@@ -197,6 +242,12 @@ export async function readTaskDetails(world, ids) {
         ? { kind: "accepted", value: details }
         : { kind: "refused", refusal: { kind: "task-missing", taskId: ids[missing] } };
 }
+export async function observeTaskDetails(world, ids) {
+    const observed = await readTaskDetails(world, ids);
+    if (observed.kind !== "accepted")
+        return observed;
+    return { kind: "accepted", value: observed.value.map((facts) => ({ ...facts, task: taskView(facts.task) })) };
+}
 export async function readyTasks(world, namespace, scope, parent, limit = DEFAULT_TASK_LIMIT) {
     const selected = readScope(namespace, scope);
     const board = (await readBoard(world)).board;
@@ -219,7 +270,10 @@ export async function blockedTasks(world, namespace, scope, parent, limit = DEFA
     if (parent !== undefined && !board.tasks.has(parent))
         return { kind: "refused", refusal: { kind: "task-missing", taskId: parent } };
     const relations = createTaskRelations(board);
-    const blocked = { kind: "predicate", predicate: { field: "blocked", operator: "=", value: true } };
+    const blocked = {
+        kind: "predicate",
+        predicate: { field: "blocked", operator: "=", value: true },
+    };
     const expression = parent === undefined ? blocked : { kind: "and", terms: [blocked, underExpression(parent)] };
     const selectedRows = projectQuery(board, relations, {
         scope: selected,

package/build/src/task/query.js

@@ -8,7 +8,9 @@ function isTaskRelationPredicateField(value) {
 }
 const states = ["open", "in_progress", "on_hold", "done", "drop"];
 const comparisons = ["=", "!=", "<", "<=", ">", ">=", "~"];
-function fail(message) { throw new TypeError(message); }
+function fail(message) {
+    throw new TypeError(message);
+}
 function object(value, label) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         fail(`${label} must be an object`);
@@ -38,7 +40,9 @@ function comparison(value) {
     return value;
 }
 function timestamp(value, field) {
-    if (typeof value !== "string" || !Number.isFinite(Date.parse(value)) || new Date(Date.parse(value)).toISOString() !== value) {
+    if (typeof value !== "string" ||
+        !Number.isFinite(Date.parse(value)) ||
+        new Date(Date.parse(value)).toISOString() !== value) {
         fail(`${field} must be a canonical UTC ISO timestamp`);
     }
     return value;
@@ -96,15 +100,24 @@ function predicate(value) {
         fail("query predicate field is required");
     const operator = comparison(input.operator);
     switch (field) {
-        case "state": return normalizeStatePredicate(input, operator);
-        case "priority": return normalizePriorityPredicate(input, operator);
-        case "title": return normalizeTextPredicate(input, "title", operator);
-        case "id": return normalizeTextPredicate(input, "id", operator);
-        case "parent": return normalizeParentPredicate(input, operator);
-        case "ready": return normalizeBooleanPredicate(input, "ready", operator);
-        case "blocked": return normalizeBooleanPredicate(input, "blocked", operator);
-        case "created": return normalizeTimestampPredicate(input, "created", operator);
-        case "updated": return normalizeTimestampPredicate(input, "updated", operator);
+        case "state":
+            return normalizeStatePredicate(input, operator);
+        case "priority":
+            return normalizePriorityPredicate(input, operator);
+        case "title":
+            return normalizeTextPredicate(input, "title", operator);
+        case "id":
+            return normalizeTextPredicate(input, "id", operator);
+        case "parent":
+            return normalizeParentPredicate(input, operator);
+        case "ready":
+            return normalizeBooleanPredicate(input, "ready", operator);
+        case "blocked":
+            return normalizeBooleanPredicate(input, "blocked", operator);
+        case "created":
+            return normalizeTimestampPredicate(input, "created", operator);
+        case "updated":
+            return normalizeTimestampPredicate(input, "updated", operator);
         default:
             if (isTaskRelationPredicateField(field))
                 return normalizeRelationPredicate(input, field, operator);
@@ -142,7 +155,9 @@ function compare(left, operator, right) {
         return left > right;
     return left >= right;
 }
-function membership(left, operator, right) { return operator === "=" ? left === right : left !== right; }
+function membership(left, operator, right) {
+    return operator === "=" ? left === right : left !== right;
+}
 function descendants(relations, parent) {
     const result = new Set(), pending = [parent];
     while (pending.length > 0) {
@@ -170,18 +185,30 @@ function matchRelation(selected, operator) {
 }
 function matchesPredicate(board, relations, task, value, under) {
     switch (value.field) {
-        case "state": return compare(task.state, value.operator, value.value);
-        case "priority": return compare(task.priority, value.operator, value.value);
-        case "title": return matchText(task.title, value.operator, value.value);
-        case "id": return matchText(task.id, value.operator, value.value);
-        case "parent": return compare(task.parent ?? "", value.operator, value.value ?? "");
-        case "under": return matchRelation(under.get(value.value)?.has(task.id) === true, value.operator);
-        case "needs": return matchRelation(relation(board, relations, task.id, "needs", value.value), value.operator);
-        case "blocks": return matchRelation(relation(board, relations, task.id, "blocks", value.value), value.operator);
-        case "ready": return membership(taskDisposition(board, task) === "ready", value.operator, value.value);
-        case "blocked": return membership(taskBlocked(board, task), value.operator, value.value);
-        case "created": return compare(task.createdAt, value.operator, value.value);
-        case "updated": return compare(task.updatedAt, value.operator, value.value);
+        case "state":
+            return compare(task.state, value.operator, value.value);
+        case "priority":
+            return compare(task.priority, value.operator, value.value);
+        case "title":
+            return matchText(task.title, value.operator, value.value);
+        case "id":
+            return matchText(task.id, value.operator, value.value);
+        case "parent":
+            return compare(task.parent ?? "", value.operator, value.value ?? "");
+        case "under":
+            return matchRelation(under.get(value.value)?.has(task.id) === true, value.operator);
+        case "needs":
+            return matchRelation(relation(board, relations, task.id, "needs", value.value), value.operator);
+        case "blocks":
+            return matchRelation(relation(board, relations, task.id, "blocks", value.value), value.operator);
+        case "ready":
+            return membership(taskDisposition(board, task) === "ready", value.operator, value.value);
+        case "blocked":
+            return membership(taskBlocked(board, task), value.operator, value.value);
+        case "created":
+            return compare(task.createdAt, value.operator, value.value);
+        case "updated":
+            return compare(task.updatedAt, value.operator, value.value);
     }
 }
 function matches(board, relations, task, expression, under) {
@@ -200,7 +227,8 @@ function row(board, relations, task) {
         parent: task.parent,
         needs: task.needs.map((need) => taskRef(board, need)),
         blocks: relations.blocks(task.id),
-        createdAt: task.createdAt, updatedAt: task.updatedAt,
+        createdAt: task.createdAt,
+        updatedAt: task.updatedAt,
     };
 }
 function sortTasks(tasks, sort) {
@@ -217,7 +245,8 @@ function sortTasks(tasks, sort) {
 export function projectQuery(board, relations, input) {
     const { scope, expression, sort = "priority", limit = DEFAULT_TASK_LIMIT } = input;
     const under = new Map(queryUnderTargets(expression).map((target) => [target, descendants(relations, target)]));
-    const selected = sortTasks([...board.tasks.values()].filter((task) => scope === null || sameNamespace(parseTaskId(task.id).namespace, scope))
+    const selected = sortTasks([...board.tasks.values()]
+        .filter((task) => scope === null || sameNamespace(parseTaskId(task.id).namespace, scope))
         .filter((task) => matches(board, relations, task, expression, under)), sort);
     const rows = selected.slice(0, limit).map((task) => row(board, relations, task));
     return { rows, total: selected.length, returned: rows.length, truncated: rows.length < selected.length };

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

@@ -12,7 +12,9 @@ export declare function replaceAuthority(input: Readonly<{
     expected: Uint8Array | null;
     next: Uint8Array;
 }>): Promise<"replaced" | "concurrent-modification">;
-export declare function nukeTaskAuthority(world: WorldRoot): Promise<void | "busy">;
+export declare function nukeTaskAuthority(world: WorldRoot, options?: Readonly<{
+    timeoutMs?: number;
+}>): Promise<void | "busy">;
 export declare function withTaskLocks<T>(input: Readonly<{
     world: WorldRoot;
     allocation: boolean;

package/build/src/task/store.js

@@ -1,8 +1,8 @@
 import { randomBytes } from "node:crypto";
-import { closeSync, fsyncSync, openSync, renameSync, writeFileSync, } from "node:fs";
-import { lstat, mkdir, readFile, readdir, unlink } from "node:fs/promises";
+import { closeSync, fsyncSync, openSync, renameSync, writeFileSync } from "node:fs";
+import { lstat, mkdir, readFile, readdir, rmdir, unlink } from "node:fs/promises";
 import { dirname, relative, resolve, sep } from "node:path";
-import { acquireSqliteTransactionLock, SqliteTransactionLockError } from "../coordination/sqlite-transaction-lock.js";
+import { acquireSqliteTransactionLock, SqliteTransactionLockError, } from "../coordination/sqlite-transaction-lock.js";
 import { parseTaskDocument } from "./document.js";
 import { formatTaskId, parseTaskId, taskAuthorityPath } from "./identity.js";
 export const DEFAULT_TASK_LOCK_TIMEOUT_MS = 3_000;
@@ -17,8 +17,12 @@ function syncTaskDirectory(path) {
         closeSync(directory);
     }
 }
-function tasksDirectory(world) { return resolve(world, ".keiyaku", "tasks"); }
-function allocationLockPath(world) { return resolve(world, ".keiyaku", "locks", "task-allocation.sqlite"); }
+function tasksDirectory(world) {
+    return resolve(world, ".keiyaku", "tasks");
+}
+function allocationLockPath(world) {
+    return resolve(world, ".keiyaku", "locks", "task-allocation.sqlite");
+}
 async function authorityFiles(directory) {
     const files = [];
     let entries;
@@ -33,7 +37,7 @@ async function authorityFiles(directory) {
     for (const entry of entries) {
         const path = resolve(directory, entry.name);
         if (entry.isDirectory())
-            files.push(...await authorityFiles(path));
+            files.push(...(await authorityFiles(path)));
         else if (entry.isFile() && entry.name.endsWith(".md"))
             files.push(path);
     }
@@ -45,6 +49,48 @@ function coordinateFromPath(tasksDirectory, path) {
         throw new Error(`invalid Task authority path: ${path}`);
     return parseTaskId(`task/${local.slice(0, -3).split(sep).join("/")}`);
 }
+function ownedTaskId(tasksDirectory, path) {
+    try {
+        return formatTaskId(coordinateFromPath(tasksDirectory, path));
+    }
+    catch {
+        return null;
+    }
+}
+async function ownedAuthorityCandidates(directory) {
+    const candidates = [];
+    for (const path of await authorityFiles(directory)) {
+        const id = ownedTaskId(directory, path);
+        if (id !== null)
+            candidates.push({ id, path });
+    }
+    return candidates;
+}
+async function removeEmptyTaskDirectories(directory, removeSelf) {
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory())
+            await removeEmptyTaskDirectories(resolve(directory, entry.name), true);
+    }
+    if (!removeSelf)
+        return;
+    try {
+        await rmdir(directory);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "ENOENT" && code !== "ENOTEMPTY")
+            throw error;
+    }
+}
 export async function readBoard(world) {
     const directory = tasksDirectory(world);
     const tasks = new Map();
@@ -98,21 +144,35 @@ export async function replaceAuthority(input) {
         try {
             await unlink(temporary);
         }
-        catch { /* renamed or best effort */ }
+        catch {
+            /* renamed or best effort */
+        }
     }
 }
 function lockPath(world, id) {
     const coordinate = parseTaskId(id);
     return resolve(world, ".keiyaku", "locks", "task", ...coordinate.namespace, `${coordinate.localId}.sqlite`);
 }
-export async function nukeTaskAuthority(world) {
-    const ids = [...(await readBoard(world)).board.tasks.keys()]
-        .sort((left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right)));
-    if (ids.length === 0)
-        return;
-    const result = await withTaskLocks({ world, allocation: true, ids }, async () => {
-        for (const id of ids)
-            await unlink(authorityPath(world, id));
+export async function nukeTaskAuthority(world, options) {
+    const directory = tasksDirectory(world);
+    const lockOptions = options?.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs };
+    const result = await withTaskLocks({ world, allocation: true, ids: [], ...lockOptions }, async () => {
+        const candidates = await ownedAuthorityCandidates(directory);
+        const ids = [...new Set(candidates.map((candidate) => candidate.id))].sort((left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right)));
+        return await withTaskLocks({ world, allocation: false, ids, ...lockOptions }, async () => {
+            for (const candidate of candidates) {
+                try {
+                    const stat = await lstat(candidate.path);
+                    if (stat.isFile() && !stat.isSymbolicLink())
+                        await unlink(candidate.path);
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT")
+                        throw error;
+                }
+            }
+            await removeEmptyTaskDirectories(directory, false);
+        });
     });
     if (result === "busy")
         return "busy";
@@ -120,7 +180,9 @@ export async function nukeTaskAuthority(world) {
 export async function withTaskLocks(input, action) {
     const paths = [
         ...(input.allocation ? [allocationLockPath(input.world)] : []),
-        ...[...new Set(input.ids)].sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b))).map((id) => lockPath(input.world, id)),
+        ...[...new Set(input.ids)]
+            .sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)))
+            .map((id) => lockPath(input.world, id)),
     ];
     const held = [];
     try {
@@ -143,4 +205,6 @@ export async function withTaskLocks(input, action) {
             lock.close();
     }
 }
-export function authorityPath(world, id) { return taskAuthorityPath(tasksDirectory(world), parseTaskId(id)); }
+export function authorityPath(world, id) {
+    return taskAuthorityPath(tasksDirectory(world), parseTaskId(id));
+}

package/build/src/verification/execution.js

@@ -63,7 +63,9 @@ export async function executeVerification(input) {
         scratch = await input.materializeScratchCandidate(input.repository, input.candidate);
     }
     catch (error) {
-        return { outcome: { kind: "candidate-unavailable", diagnostic: error instanceof Error ? error.message : String(error) } };
+        return {
+            outcome: { kind: "candidate-unavailable", diagnostic: error instanceof Error ? error.message : String(error) },
+        };
     }
     let outcome;
     let cleanup;
@@ -74,16 +76,17 @@ export async function executeVerification(input) {
             const hooks = worktreeHooksFrom({ settings: await input.projectSettings(scratch.cwd) });
             destroy = hooks.destroy;
             const readiness = await runHookCommands(scratch.cwd, hooks.create, input.signal);
-            outcome = readiness.kind === "cancelled"
-                ? { kind: "cancelled" }
-                : readiness.kind === "failed"
-                    ? { kind: "environment-failure", command: readiness.command, detail: readiness.failure }
-                    : await executeDeclarations({
-                        declarations: input.declarations,
-                        cwd: scratch.cwd,
-                        environment: input.environment,
-                        ...(input.signal === undefined ? {} : { signal: input.signal }),
-                    });
+            outcome =
+                readiness.kind === "cancelled"
+                    ? { kind: "cancelled" }
+                    : readiness.kind === "failed"
+                        ? { kind: "environment-failure", command: readiness.command, detail: readiness.failure }
+                        : await executeDeclarations({
+                            declarations: input.declarations,
+                            cwd: scratch.cwd,
+                            environment: input.environment,
+                            ...(input.signal === undefined ? {} : { signal: input.signal }),
+                        });
         }
         catch (error) {
             outcome = { kind: "environment-failure", diagnostic: error instanceof Error ? error.message : String(error) };

package/build/src/workspace-place.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { lstat, mkdir, readFile, unlink } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { replaceFileDurably } from "./coordination/durable-file.js";
@@ -312,7 +313,7 @@ async function mutatePlaceRegister(repository, mutate) {
         const next = mutate(current);
         const bytes = canonicalPlaceRegister(next);
         try {
-            if (await readFile(location.authority, "utf8") === bytes)
+            if ((await readFile(location.authority, "utf8")) === bytes)
                 return next;
         }
         catch (error) {
@@ -331,20 +332,31 @@ function withAppointments(register, contracts) {
     const additions = [];
     const occupied = new Set(register.byPlace.keys());
     const known = new Set(register.byContract.keys());
-    let cursor;
     for (const contract of contracts) {
         if (known.has(contract))
             continue;
-        let candidate = cursor === undefined ? nextPlace() : nextPlace(cursor);
-        while (occupied.has(candidate))
-            candidate = nextPlace(candidate);
+        const candidate = firstUnoccupiedPlace(contract, occupied);
         additions.push({ place: candidate, contract });
         occupied.add(candidate);
         known.add(contract);
-        cursor = candidate;
     }
     return additions.length === 0 ? register : indexedRegister([...register.appointments, ...additions]);
 }
+function stableStartIndex(contract) {
+    const digest = createHash("sha256").update(contract, "utf8").digest("hex");
+    return Number(BigInt(`0x${digest}`) % BigInt(CONTRACT_PLACES.length));
+}
+function firstUnoccupiedPlace(contract, occupied) {
+    const start = stableStartIndex(contract);
+    for (let generation = 1n;; generation += 1n) {
+        for (let offset = 0; offset < CONTRACT_PLACES.length; offset += 1) {
+            const base = CONTRACT_PLACES[(start + offset) % CONTRACT_PLACES.length];
+            const candidate = composePlace(base, generation);
+            if (!occupied.has(candidate))
+                return candidate;
+        }
+    }
+}
 export async function appointManagedWorktrees(repository, contracts) {
     return await mutatePlaceRegister(repository, (current) => withAppointments(current, contracts));
 }
@@ -385,7 +397,7 @@ export async function nukeEmptyPlaceAuthority(repository) {
 }
 export async function readManagedWorktreeAppointment(repository, contract, register) {
     try {
-        const snapshot = register ?? await readPlaceRegister(repository);
+        const snapshot = register ?? (await readPlaceRegister(repository));
         const appointed = appointmentFor(snapshot, contract);
         return appointed === undefined
             ? { kind: "unappointed" }

package/build/src/world.js

@@ -39,10 +39,14 @@ async function directory(input, label) {
     }
     return real;
 }
-function brand(path) { return path; }
-function marker(root) { return join(root, ".keiyaku"); }
+function brand(path) {
+    return path;
+}
+function marker(root) {
+    return join(root, ".keiyaku");
+}
 async function rejectReservedRoot(root) {
-    if (root === await homeRoot()) {
+    if (root === (await homeRoot())) {
         throw new WorldError("home-world", "the user home directory cannot be a Keiyaku world");
     }
     if (root === parse(root).root) {
@@ -130,7 +134,13 @@ async function resolved(input) {
     });
 }
 export const World = Object.freeze({
-    resolve(input) { return resolved(input); },
-    async locate(input) { return (await resolved(input)).root; },
-    at(input) { return exact(input); },
+    resolve(input) {
+        return resolved(input);
+    },
+    async locate(input) {
+        return (await resolved(input)).root;
+    },
+    at(input) {
+        return exact(input);
+    },
 });