@astrosheep/keiyaku 2.8.5 → 2.9.1

package/build/core/status/lifecycle.js

@@ -0,0 +1,84 @@
+function transitionFromEntry(current, entry) {
+    if (current === "claimed" || current === "forfeited" || current === "corrupt") {
+        return "corrupt";
+    }
+    switch (entry.kind) {
+        case "bind":
+            return "corrupt";
+        case "bootstrap":
+            // Placement legality is owned exclusively by deriveContractState.
+            return "corrupt";
+        case "arc":
+            return current === "bound" || current === "active" ? "active" : "corrupt";
+        case "seal":
+            if (current === "active")
+                return "active";
+            // Derived default arc a0 may seal from bound (bind/bootstrap → seal0 → petition).
+            if (current === "bound" && entry.data.arc === 0)
+                return "active";
+            return "corrupt";
+        case "amend":
+            return current === "petitioned" ? "active" : current;
+        case "renew":
+            return current;
+        case "verdict":
+            if (current !== "petitioned")
+                return "corrupt";
+            return entry.data.result === "rejected" ? "active" : "petitioned";
+        case "petition":
+            return current === "bound" || current === "active" ? "petitioned" : "corrupt";
+        case "claim":
+            return current === "petitioned" ? "claimed" : "corrupt";
+        case "forfeit":
+            return "forfeited";
+    }
+    return "corrupt";
+}
+export function deriveContractState(entries) {
+    if (entries.length === 0 || entries[0]?.kind !== "bind") {
+        return { state: "corrupt", at: 0, reason: "ledger must start with bind" };
+    }
+    const bind = entries[0];
+    let state = "bound";
+    for (let index = 1; index < entries.length; index += 1) {
+        const entry = entries[index];
+        if (entry.kind === "bootstrap") {
+            if (index !== 1 || state !== "bound") {
+                return { state: "corrupt", at: index + 1, reason: "bootstrap must immediately follow bind" };
+            }
+            if (!bind.data.bootstrap) {
+                return { state: "corrupt", at: index + 1, reason: "bootstrap without bind plan" };
+            }
+            // Legal bootstrap is a durable fact and leaves the derived state bound.
+            continue;
+        }
+        const next = transitionFromEntry(state, entry);
+        if (next === "corrupt") {
+            return { state: "corrupt", at: index + 1, reason: `invalid ${entry.kind} after ${state}` };
+        }
+        state = next;
+    }
+    return { state };
+}
+export function deriveBootstrapDiagnostics(entries) {
+    const bind = entries.find((entry) => entry.kind === "bind");
+    if (!bind?.data.bootstrap)
+        return [];
+    if (entries.some((entry) => entry.kind === "bootstrap"))
+        return [];
+    return [{ kind: "plan-without-result" }];
+}
+export function isTerminalState(state) {
+    return state.state === "claimed" || state.state === "forfeited";
+}
+/** Current-petition verdict predicate used by board queue-head stall logic. */
+export function hasCurrentPetitionVerdict(entries) {
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (entry.kind === "verdict")
+            return true;
+        if (entry.kind === "petition")
+            return false;
+    }
+    return false;
+}

package/build/core/status/reconciliation.js

@@ -0,0 +1,131 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createGit } from "../../git/core.js";
+import { stableRepoRoot } from "../worktree-path.js";
+function isClaimReceipt(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const receipt = value;
+    return receipt.kind === "receipt" && [receipt.oldHead, receipt.newHead, receipt.contract].every((field) => typeof field === "string" && field.length > 0);
+}
+function isClaimReceiptBaseline(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const baseline = value;
+    if (baseline.kind !== "baseline" || typeof baseline.head !== "string" || typeof baseline.by !== "string" || baseline.by.length === 0) {
+        return false;
+    }
+    if (typeof baseline.establishedAt !== "string" || !baseline.establishedAt.endsWith("Z"))
+        return false;
+    const at = Date.parse(baseline.establishedAt);
+    return Number.isFinite(at) && new Date(at).toISOString() === baseline.establishedAt;
+}
+async function readClaimReceipts(cwd) {
+    const receiptsPath = path.join(await stableRepoRoot(cwd), ".keiyaku", "claim-receipts.jsonl");
+    try {
+        const content = fs.readFileSync(receiptsPath, "utf8");
+        return content
+            .split("\n")
+            .map((line, index) => ({ line, index: index + 1 }))
+            .filter(({ line }) => line.trim().length > 0)
+            .map(({ line, index }) => {
+            try {
+                const parsed = JSON.parse(line);
+                return isClaimReceipt(parsed) || isClaimReceiptBaseline(parsed)
+                    ? { line: index, record: parsed }
+                    : { line: index, issue: { line: index, reason: "malformed" } };
+            }
+            catch {
+                return { line: index, issue: { line: index, reason: "malformed" } };
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+export async function computeClaimReconciliation(cwd, defaultBranch) {
+    if (!defaultBranch)
+        return null;
+    const receiptLines = await readClaimReceipts(cwd);
+    if (receiptLines.length === 0)
+        return null;
+    const git = createGit(cwd);
+    const firstParentHistory = (await git.raw(["rev-list", "--first-parent", defaultBranch.head])).trim().split("\n").filter(Boolean);
+    const firstParentSet = new Set(firstParentHistory);
+    let baselineIndex = -1;
+    for (let index = receiptLines.length - 1; index >= 0; index -= 1) {
+        const record = receiptLines[index].record;
+        if (record?.kind === "baseline" && firstParentSet.has(record.head)) {
+            baselineIndex = index;
+            break;
+        }
+    }
+    if (baselineIndex < 0)
+        return null;
+    const baseline = receiptLines[baselineIndex].record;
+    const issues = receiptLines.slice(baselineIndex + 1).flatMap((line) => {
+        if (line.issue)
+            return [line.issue];
+        return line.record?.kind === "baseline" ? [{ line: line.line, reason: "non-chain" }] : [];
+    });
+    // Only records after the latest valid baseline belong to this fence window.
+    let revList;
+    try {
+        const output = await git.raw(["rev-list", "--first-parent", "--reverse", `${baseline.head}..${defaultBranch.head}`]);
+        revList = output.trim().split("\n").filter((h) => h.length > 0);
+    }
+    catch {
+        return {
+            defaultBranch: defaultBranch.branch,
+            head: defaultBranch.head,
+            unclaimedSegments: [],
+            receiptIssues: [...issues, ...receiptLines.slice(baselineIndex + 1).filter((line) => line.record?.kind === "receipt").map((line) => ({ line: line.line, reason: "non-chain" }))],
+        };
+    }
+    const firstParent = new Map();
+    let parent = baseline.head;
+    for (const commit of revList) {
+        firstParent.set(commit, parent);
+        parent = commit;
+    }
+    const indexByCommit = new Map(revList.map((commit, index) => [commit, index]));
+    const claimedHeads = new Set();
+    let previousReceiptIndex = -1;
+    for (const line of receiptLines.slice(baselineIndex + 1)) {
+        if (line.record?.kind !== "receipt")
+            continue;
+        const index = indexByCommit.get(line.record.newHead);
+        if (index === undefined || index <= previousReceiptIndex || firstParent.get(line.record.newHead) !== line.record.oldHead) {
+            issues.push({ line: line.line, reason: "non-chain" });
+            continue;
+        }
+        previousReceiptIndex = index;
+        claimedHeads.add(line.record.newHead);
+    }
+    // Walk default-branch first-parent edges and group only movement not covered
+    // by a valid receipt. These are facts, not a judgment about their source.
+    const segments = [];
+    let segmentStart = null;
+    let segmentCount = 0;
+    for (const commit of revList) {
+        if (claimedHeads.has(commit)) {
+            if (segmentStart !== null) {
+                segments.push({ oldHead: segmentStart, newHead: firstParent.get(commit), commitCount: segmentCount });
+                segmentStart = null;
+                segmentCount = 0;
+            }
+        }
+        else {
+            if (segmentStart === null) {
+                segmentStart = firstParent.get(commit);
+            }
+            segmentCount++;
+        }
+    }
+    // Trailing unclaimed segment up to HEAD
+    if (segmentStart !== null) {
+        segments.push({ oldHead: segmentStart, newHead: defaultBranch.head, commitCount: segmentCount });
+    }
+    return { defaultBranch: defaultBranch.branch, head: defaultBranch.head, unclaimedSegments: segments, receiptIssues: issues };
+}

package/build/core/stored-agent-event.js

@@ -1,11 +1,28 @@
-import { activityEventBodySchema, AGENT_EVENT_TEXT_MAX_CHARS, AGENT_UNKNOWN_PAYLOAD_MAX_CHARS, } from "../agents/harness/index.js";
-import { EXEC_EVENT_BUFFER_HARD_CAP } from "../agents/harness/event-channel.js";
+import { activityEventBodySchema, AGENT_EVENT_TEXT_MAX_CHARS, AGENT_UNKNOWN_PAYLOAD_MAX_CHARS, EXEC_EVENT_BUFFER_HARD_CAP, } from "../agents/harness/index.js";
 import { isSubagentProvider } from "../keiyaku.js";
 const FAIL_CODES = new Set(["SUBAGENT_TIMEOUT", "SUBAGENT_NON_ZERO_EXIT", "SUBAGENT_SPAWN_ERROR", "SUBAGENT_EXEC_ERROR", "SUBAGENT_PROVIDER_UNAVAILABLE", "PROJECTION_STATE_ERROR"]);
 const KNOWN = new Set(["message", "unknown", "activity", "thought", "plan", "turn", "usage", "warning", "diagnostic", "truncation", "done", "fail"]);
 const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 const finite = (value) => typeof value === "number" && Number.isFinite(value);
 const optionalString = (value, key) => value[key] === undefined || typeof value[key] === "string";
+const nonNegativeSafeInteger = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+const safeIntegerOrNull = (value) => value === null || (typeof value === "number" && Number.isSafeInteger(value));
+function isValidStoredWarning(warning) {
+    if (warning.reason === "retry") {
+        return nonNegativeSafeInteger(warning.attempt)
+            && nonNegativeSafeInteger(warning.maxRetries)
+            && nonNegativeSafeInteger(warning.retryDelayMs)
+            && safeIntegerOrNull(warning.errorStatus);
+    }
+    if (warning.reason === "refusal" || warning.reason === "overload") {
+        return optionalString(warning, "originalModel")
+            && optionalString(warning, "fallbackModel")
+            && optionalString(warning, "direction")
+            && (warning.requestId === undefined || warning.requestId === null || typeof warning.requestId === "string")
+            && optionalString(warning, "signerModel");
+    }
+    return false;
+}
 export function classifyStoredAgentEvent(value) {
     if (!record(value) || typeof value.type !== "string")
         return "malformed";
@@ -20,7 +37,14 @@ export function classifyStoredAgentEvent(value) {
         || value.turn < 0)
         return "malformed";
     switch (value.type) {
-        case "message": return typeof value.text === "string" ? "valid" : "malformed";
+        case "message":
+            return typeof value.id === "string"
+                && value.id.length > 0
+                && value.id.length <= AGENT_EVENT_TEXT_MAX_CHARS
+                && typeof value.text === "string"
+                && value.text.length <= AGENT_EVENT_TEXT_MAX_CHARS
+                ? "valid"
+                : "malformed";
         case "unknown": {
             if (typeof value.provider !== "string" || value.provider.length > AGENT_EVENT_TEXT_MAX_CHARS ||
                 typeof value.nativeType !== "string" || value.nativeType.length > AGENT_EVENT_TEXT_MAX_CHARS ||
@@ -51,7 +75,7 @@ export function classifyStoredAgentEvent(value) {
         case "plan": return typeof value.id === "string" && Array.isArray(value.items) && value.items.every((item) => record(item) && typeof item.text === "string" && typeof item.done === "boolean" && (item.active === undefined || item.active === true)) ? "valid" : "malformed";
         case "turn": return value.phase === "started" || value.phase === "completed" ? "valid" : "malformed";
         case "usage": return finite(value.inputTokens) && finite(value.outputTokens) && (value.cachedInputTokens === undefined || finite(value.cachedInputTokens)) && (value.costUsd === undefined || finite(value.costUsd)) && optionalString(value, "model") ? "valid" : "malformed";
-        case "warning": return record(value.warning) && (value.warning.reason === "refusal" || value.warning.reason === "overload") && optionalString(value.warning, "originalModel") && optionalString(value.warning, "fallbackModel") && optionalString(value.warning, "direction") && (value.warning.requestId === undefined || value.warning.requestId === null || typeof value.warning.requestId === "string") && optionalString(value.warning, "signerModel") ? "valid" : "malformed";
+        case "warning": return record(value.warning) && isValidStoredWarning(value.warning) ? "valid" : "malformed";
         case "diagnostic": return typeof value.text === "string" ? "valid" : "malformed";
         case "truncation": {
             return Number.isInteger(value.limit)

package/build/core/target-ref.js

@@ -0,0 +1,10 @@
+import { FlowError } from "../flow-error.js";
+import { fullBranchRefSchema } from "./entry.js";
+/** Prefix bare branch names and validate the full ref. Sole status/bind normalizer. */
+export function normalizeTargetRef(raw) {
+    const ref = raw.startsWith("refs/heads/") ? raw : `refs/heads/${raw}`;
+    if (!fullBranchRefSchema.safeParse(ref).success) {
+        throw new FlowError("INVALID_TARGET", `invalid target ref '${raw}' — pass a branch name or refs/heads/<name>`);
+    }
+    return ref;
+}

package/build/core/task/board.js

@@ -0,0 +1,175 @@
+import { FlowError } from "../../flow-error.js";
+import { TASK_ID } from "./validation.js";
+const TASK_READ_ID = /^k-[0-9a-f]{7,12}$/;
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function diseaseSort(left, right) {
+    return compareText(left.code, right.code)
+        || compareText(left.id ?? "", right.id ?? "")
+        || compareText(left.message, right.message);
+}
+function taskSort(left, right) {
+    const leftTerminal = left.state === "done" || left.state === "drop" ? 1 : 0;
+    const rightTerminal = right.state === "done" || right.state === "drop" ? 1 : 0;
+    return leftTerminal - rightTerminal
+        || left.pri - right.pri
+        || compareText(left.createdAt, right.createdAt)
+        || compareText(left.id, right.id);
+}
+function cycleComponents(tasks) {
+    let nextIndex = 0;
+    const indexes = new Map();
+    const low = new Map();
+    const stack = [];
+    const onStack = new Set();
+    const cycles = [];
+    const visit = (id) => {
+        indexes.set(id, nextIndex);
+        low.set(id, nextIndex);
+        nextIndex += 1;
+        stack.push(id);
+        onStack.add(id);
+        for (const need of tasks.get(id).needs) {
+            if (!tasks.has(need))
+                continue;
+            if (!indexes.has(need)) {
+                visit(need);
+                low.set(id, Math.min(low.get(id), low.get(need)));
+            }
+            else if (onStack.has(need)) {
+                low.set(id, Math.min(low.get(id), indexes.get(need)));
+            }
+        }
+        if (low.get(id) !== indexes.get(id))
+            return;
+        const component = [];
+        while (stack.length > 0) {
+            const member = stack.pop();
+            onStack.delete(member);
+            component.push(member);
+            if (member === id)
+                break;
+        }
+        if (component.length > 1 || tasks.get(id).needs.includes(id)) {
+            cycles.push(new Set(component));
+        }
+    };
+    for (const id of [...tasks.keys()].sort())
+        if (!indexes.has(id))
+            visit(id);
+    return cycles;
+}
+/** Derive the complete storage-neutral board from domain records. */
+export function buildTaskBoardFromDocuments(documents) {
+    const diseases = [];
+    const counts = new Map();
+    for (const task of documents)
+        counts.set(task.id, (counts.get(task.id) ?? 0) + 1);
+    const candidates = new Map();
+    for (const task of documents) {
+        if (counts.get(task.id) > 1) {
+            diseases.push({
+                code: "duplicate_id",
+                message: `duplicate authoritative task id ${task.id}`,
+                id: task.id,
+            });
+        }
+        else {
+            candidates.set(task.id, task);
+        }
+    }
+    for (const component of cycleComponents(candidates)) {
+        const relatedIds = [...component].sort();
+        for (const id of relatedIds) {
+            diseases.push({
+                code: "needs_cycle",
+                message: `task ${id} participates in a needs cycle`,
+                id,
+                relatedIds,
+            });
+            candidates.delete(id);
+        }
+    }
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const [id, task] of [...candidates].sort(([a], [b]) => compareText(a, b))) {
+            const missing = [...task.needs, ...(task.parent ? [task.parent] : []), ...task.from]
+                .filter((related) => !candidates.has(related));
+            if (missing.length === 0)
+                continue;
+            const relatedIds = [...new Set(missing)].sort();
+            diseases.push({
+                code: "missing_reference",
+                message: `task ${id} references missing task(s): ${relatedIds.join(", ")}`,
+                id,
+                relatedIds,
+            });
+            candidates.delete(id);
+            changed = true;
+        }
+    }
+    const blocks = new Map();
+    for (const task of candidates.values()) {
+        for (const need of task.needs)
+            blocks.set(need, [...(blocks.get(need) ?? []), task.id]);
+    }
+    const tasks = [...candidates.values()].sort(taskSort).map((task) => {
+        const blockingNeeds = task.needs.filter((id) => {
+            const state = candidates.get(id).state;
+            return state === "open" || state === "in_progress";
+        });
+        return {
+            id: task.id,
+            title: task.title,
+            state: task.state,
+            pri: task.pri,
+            needs: [...task.needs],
+            parent: task.parent,
+            from: [...task.from],
+            createdAt: task.createdAt,
+            creator: task.creator,
+            ...(task.startedAt === undefined ? {} : { startedAt: task.startedAt }),
+            ...(task.contractId === undefined ? {} : { contractId: task.contractId }),
+            body: task.body,
+            blocks: [...(blocks.get(task.id) ?? [])].sort(),
+            blocked: task.state === "open" && blockingNeeds.length > 0,
+            releasedNeeds: task.needs.filter((id) => candidates.get(id).state === "drop").sort(),
+        };
+    });
+    return {
+        tasks,
+        diseases: diseases.sort(diseaseSort),
+        byId: new Map(tasks.map((task) => [task.id, task])),
+    };
+}
+export function resolveTaskReadId(board, input) {
+    return resolveTaskId(board, input);
+}
+export function resolveTaskId(board, input) {
+    if (!TASK_READ_ID.test(input)) {
+        throw new FlowError("INVALID_TARGET", `invalid task id '${input}'`);
+    }
+    const matches = board.tasks
+        .map((task) => task.id)
+        .filter((id) => id.startsWith(input))
+        .sort();
+    if (matches.length === 0)
+        throw new FlowError("INVALID_TARGET", `task '${input}' not found`);
+    if (matches.length > 1) {
+        throw Object.assign(new FlowError("CONTRACT_AMBIGUOUS", `task prefix '${input}' is ambiguous: ${matches.join(", ")}`), { candidates: matches });
+    }
+    return matches[0];
+}
+export function requireCanonicalTaskId(input) {
+    if (!TASK_ID.test(input)) {
+        throw new FlowError("INVALID_TARGET", "task mutations require a canonical full task id");
+    }
+    return input;
+}
+export function requireHealthy(board) {
+    if (board.diseases.length > 0) {
+        throw new FlowError("INTERNAL_STATE", `authoritative task board is diseased: ${board.diseases.map((item) => item.message).join("; ")}`);
+    }
+}

package/build/core/task/commands.js

@@ -0,0 +1,211 @@
+import { FlowError } from "../../flow-error.js";
+import { requireCanonicalTaskId, requireHealthy, resolveTaskId, } from "./board.js";
+import { dateTimestamp, invalid, nonblank, } from "./validation.js";
+export async function readTaskBoard(repository) {
+    return repository.read();
+}
+function documentFromView(view) {
+    return {
+        id: view.id,
+        title: view.title,
+        state: view.state,
+        pri: view.pri,
+        needs: [...view.needs],
+        parent: view.parent,
+        from: [...view.from],
+        createdAt: view.createdAt,
+        creator: view.creator,
+        ...(view.startedAt === undefined ? {} : { startedAt: view.startedAt }),
+        ...(view.contractId === undefined ? {} : { contractId: view.contractId }),
+        body: view.body,
+    };
+}
+function replaceDocument(document) {
+    return {
+        replacements: [document],
+        select(resulting) {
+            const value = resulting.byId.get(document.id);
+            if (!value)
+                throw new FlowError("INTERNAL_STATE", `mutated task ${document.id} disappeared from the board`);
+            return value;
+        },
+    };
+}
+function requireExisting(board, id) {
+    const task = board.byId.get(requireCanonicalTaskId(id));
+    if (!task)
+        throw new FlowError("INVALID_TARGET", `task '${id}' not found`);
+    return task;
+}
+function resolveMutationIds(board, ids) {
+    return ids.map((id) => resolveTaskId(board, id));
+}
+export async function createTask(repository, input, deps) {
+    nonblank("title", input.title);
+    nonblank("creator", input.creator);
+    const pri = input.pri ?? 2;
+    if (!Number.isInteger(pri) || pri < 0 || pri > 3)
+        invalid("task priority must be an integer from 0 through 3");
+    return repository.mutate((board) => {
+        requireHealthy(board);
+        const needs = resolveMutationIds(board, input.needs ?? []);
+        if (new Set(needs).size !== needs.length)
+            invalid("task needs must be unique");
+        const parent = input.parent == null ? null : resolveTaskId(board, input.parent);
+        const from = resolveMutationIds(board, input.from ?? []);
+        if (new Set(from).size !== from.length)
+            invalid("task from edges must be unique");
+        let id;
+        for (let attempt = 0; attempt < 32; attempt += 1) {
+            const bytes = deps.randomBytes(6);
+            if (bytes.byteLength !== 6)
+                throw new FlowError("INTERNAL_STATE", "randomBytes(6) must return exactly 6 bytes");
+            const candidate = `k-${Buffer.from(bytes).toString("hex")}`;
+            if (!board.byId.has(candidate)) {
+                id = candidate;
+                break;
+            }
+        }
+        if (!id)
+            throw new FlowError("CONCURRENT_MODIFICATION", "could not allocate a unique task id after 32 attempts");
+        const document = {
+            id,
+            title: input.title,
+            state: "open",
+            pri,
+            needs,
+            parent,
+            from,
+            createdAt: dateTimestamp("createdAt", deps.now()),
+            creator: input.creator,
+            body: input.body ?? "",
+        };
+        return replaceDocument(document);
+    });
+}
+export async function updateTask(repository, fullIdValue, patch) {
+    const hasChange = Object.values(patch).some((value) => value !== undefined);
+    if (!hasChange)
+        throw new FlowError("EMPTY_PARAM", "task update requires at least one change");
+    return repository.mutate((board) => {
+        requireHealthy(board);
+        const id = resolveTaskId(board, fullIdValue);
+        const current = requireExisting(board, id);
+        const document = documentFromView(current);
+        if (patch.title !== undefined)
+            document.title = nonblank("title", patch.title);
+        if (patch.body !== undefined)
+            document.body = patch.body;
+        if (patch.pri !== undefined) {
+            if (!Number.isInteger(patch.pri) || patch.pri < 0 || patch.pri > 3)
+                invalid("task priority must be an integer from 0 through 3");
+            document.pri = patch.pri;
+        }
+        const additions = resolveMutationIds(board, patch.addNeeds ?? []);
+        const removals = new Set(resolveMutationIds(board, patch.dropNeeds ?? []));
+        document.needs = [...new Set([...document.needs.filter((need) => !removals.has(need)), ...additions])];
+        if (patch.parent !== undefined)
+            document.parent = patch.parent === null ? null : resolveTaskId(board, patch.parent);
+        if (patch.from !== undefined) {
+            document.from = [...new Set([...document.from, ...resolveMutationIds(board, patch.from)])];
+        }
+        if (JSON.stringify(document) === JSON.stringify(documentFromView(current))) {
+            throw new FlowError("EMPTY_PARAM", "task update requires at least one change");
+        }
+        return replaceDocument(document);
+    });
+}
+async function transition(repository, fullIdValue, apply) {
+    return repository.mutate((board) => {
+        requireHealthy(board);
+        const id = fullIdValue === undefined
+            ? selectSoleInProgress(board).id
+            : resolveTaskId(board, fullIdValue);
+        const document = documentFromView(requireExisting(board, id));
+        apply(document);
+        return replaceDocument(document);
+    });
+}
+function rejectBound(document, action = "state") {
+    if (document.contractId !== undefined) {
+        if (action === "drop") {
+            throw new FlowError("UNSUPPORTED_POLICY", `task ${document.id} is bound to contract ${document.contractId}; forfeit the contract before dropping this task`);
+        }
+        throw new FlowError("UNSUPPORTED_POLICY", `task ${document.id} is bound to contract ${document.contractId}; its state follows the contract`);
+    }
+}
+export async function startTask(repository, fullId, now) {
+    return transition(repository, fullId, (document) => {
+        rejectBound(document);
+        if (document.state !== "open")
+            invalid(`task ${document.id} is ${document.state}, not open`);
+        document.state = "in_progress";
+        document.startedAt = dateTimestamp("startedAt", now);
+    });
+}
+export async function stopTask(repository, fullId) {
+    return transition(repository, fullId, (document) => {
+        rejectBound(document);
+        if (document.state !== "in_progress")
+            invalid(`task ${document.id} is ${document.state}, not in_progress`);
+        document.state = "open";
+        delete document.startedAt;
+    });
+}
+export async function doneTask(repository, fullId) {
+    return transition(repository, fullId, (document) => {
+        rejectBound(document);
+        if (document.state !== "open" && document.state !== "in_progress") {
+            invalid(`task ${document.id} is ${document.state}, not open or in_progress`);
+        }
+        document.state = "done";
+        delete document.startedAt;
+    });
+}
+export async function dropTask(repository, fullId) {
+    return transition(repository, fullId, (document) => {
+        rejectBound(document, "drop");
+        if (document.state !== "open" && document.state !== "in_progress") {
+            invalid(`task ${document.id} is ${document.state}, not open or in_progress`);
+        }
+        document.state = "drop";
+        delete document.startedAt;
+    });
+}
+export function selectSoleInProgress(board) {
+    const candidates = board.tasks.filter((task) => task.state === "in_progress");
+    if (candidates.length === 1)
+        return candidates[0];
+    const ids = candidates.map((task) => task.id).sort();
+    const code = candidates.length === 0 ? "INVALID_TARGET" : "CONTRACT_AMBIGUOUS";
+    throw Object.assign(new FlowError(code, candidates.length === 0
+        ? "no task in progress"
+        : "more than one task in progress; pass an ID"), { candidates: ids, candidateTasks: candidates });
+}
+/** Reopen task pointers whose contract authority has disappeared. The caller
+ * supplies the ledger fact; this operation itself remains storage-neutral. */
+export async function rollbackOrphanTaskPointers(repository, contractIds) {
+    const before = await repository.read();
+    const orphans = before.tasks
+        .filter((task) => task.contractId !== undefined && !contractIds.has(task.contractId))
+        .map((task) => ({ taskId: task.id, contractId: task.contractId }))
+        .sort((a, b) => a.taskId.localeCompare(b.taskId));
+    if (orphans.length === 0)
+        return [];
+    await repository.mutate((board) => {
+        const replacements = orphans.flatMap(({ taskId: id }) => {
+            const current = board.byId.get(id);
+            if (!current || current.contractId === undefined || contractIds.has(current.contractId))
+                return [];
+            const document = documentFromView(current);
+            document.state = "open";
+            delete document.startedAt;
+            delete document.contractId;
+            return [document];
+        });
+        if (replacements.length === 0)
+            throw new FlowError("CONCURRENT_MODIFICATION", "task pointers changed while doctor was reconciling them");
+        return { replacements, select: () => undefined };
+    });
+    return orphans;
+}