@astrosheep/keiyaku 2.9.13 → 4.0.0

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

@@ -0,0 +1,15 @@
+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 TaskId } from "../task/identity.js";
+export type TaskHolder = Readonly<{
+    version: 1;
+    taskId: TaskId;
+    contractId: ContractId;
+    disposition: "held" | "released";
+}>;
+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;

package/build/src/settlement/holder.js

@@ -0,0 +1,113 @@
+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 { parseTaskId } from "../task/identity.js";
+const HOLDER_ROOT = "settlement/task-holders";
+const HOLDER_PREFIX = `${HOLDER_ROOT}/`;
+const HOLDER_SUFFIX = ".json";
+function holderPath(taskId) {
+    const digest = createHash("sha256").update(taskId).digest("hex");
+    return `${HOLDER_PREFIX}${digest}${HOLDER_SUFFIX}`;
+}
+function canonicalBytes(holder) {
+    return Buffer.from(`${JSON.stringify(holder)}\n`);
+}
+function corruption(message, cause) {
+    throw new AuthorityCorruptionError(message, cause === undefined ? {} : { cause });
+}
+function decodeHolder(path, bytes) {
+    let value;
+    try {
+        const text = Buffer.from(bytes).toString("utf8");
+        if (!text.endsWith("\n") || text.slice(0, -1).includes("\n"))
+            corruption(`TaskHolder is not one canonical JSON line: ${path}`);
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        if (error instanceof AuthorityCorruptionError)
+            throw error;
+        return corruption(`invalid TaskHolder JSON: ${path}`, error);
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        corruption(`TaskHolder must be an object: ${path}`);
+    const record = value;
+    const keys = Object.keys(record);
+    if (keys.length !== 4 || keys.some((key) => !["version", "taskId", "contractId", "disposition"].includes(key))) {
+        corruption(`TaskHolder has invalid fields: ${path}`);
+    }
+    if (record.version !== 1)
+        corruption(`TaskHolder version must be 1: ${path}`);
+    if (typeof record.taskId !== "string")
+        corruption(`TaskHolder taskId is invalid: ${path}`);
+    if (typeof record.contractId !== "string")
+        corruption(`TaskHolder contractId is invalid: ${path}`);
+    let taskId;
+    let owner;
+    try {
+        parseTaskId(record.taskId);
+        taskId = record.taskId;
+        owner = contractId(record.contractId);
+    }
+    catch (error) {
+        return corruption(`TaskHolder identity is invalid: ${path}`, error);
+    }
+    if (record.disposition !== "held" && record.disposition !== "released") {
+        corruption(`TaskHolder disposition is invalid: ${path}`);
+    }
+    const holder = { version: 1, taskId, contractId: owner, disposition: record.disposition };
+    if (holderPath(taskId) !== path)
+        corruption(`TaskHolder path does not match taskId: ${path}`);
+    if (!Buffer.from(canonicalBytes(holder)).equals(Buffer.from(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) {
+        if (projection.has(holder.contractId)) {
+            corruption(`Contract has multiple current TaskHolders: ${holder.contractId}`);
+        }
+        projection.set(holder.contractId, holder);
+    }
+    return projection;
+}
+function update(holder) {
+    return { path: holderPath(holder.taskId), bytes: canonicalBytes(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;
+    return current === null || current.disposition !== "held"
+        ? null
+        : update({ ...current, disposition: "released" });
+}
+export function readTaskHolders(repository) {
+    return holderEntries(repository, readGit(repository), "complete");
+}
+export function readTaskHolderProjection(repository) {
+    return projectTaskHolders(readTaskHolders(repository));
+}

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

@@ -0,0 +1,36 @@
+import { type ContractId, type ContractState } from "../core/facts/types.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";
+}> | Readonly<{
+    kind: "namespace-context";
+    path: string;
+    action: "installed" | "kept";
+}>;
+export type SettlementLag = Readonly<{
+    kind: "settlement-failed";
+    surface: "task-holder" | "task" | "namespace-context";
+    contractId: ContractId;
+    taskId?: TaskId;
+    path?: string;
+    diagnostic: string;
+}>;
+export type SettlementReport = Readonly<{
+    actions: readonly SettlementAction[];
+    lags: readonly SettlementLag[];
+}>;
+export type SettlementInput = Readonly<{
+    repository: GitRepository;
+    state: ContractState | null;
+    effects: readonly Effect[];
+}>;
+export type SettlementBatchInput = Readonly<{
+    repository: GitRepository;
+    contracts: readonly Readonly<Pick<SettlementInput, "state" | "effects">>[];
+}>;
+export declare function settle(input: SettlementInput): Promise<SettlementReport>;
+export declare function settleAll(input: SettlementBatchInput): Promise<readonly SettlementReport[]>;

package/build/src/settlement/settle.js

@@ -0,0 +1,91 @@
+import { contractSegment } from "../core/facts/types.js";
+import { repairNamespaceContext } from "../task/context.js";
+import { settleTask } from "../task/operations.js";
+import { readTaskHolderProjection } from "./holder.js";
+function diagnostic(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function taskFailure(result) {
+    return result.kind === "retry"
+        ? `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")
+        return;
+    if (observation.kind === "failed") {
+        lags.push({ kind: "settlement-failed", surface: "task-holder", contractId: state.id, diagnostic: observation.diagnostic });
+        return;
+    }
+    const holder = observation.holders.get(state.id) ?? null;
+    const expectedDisposition = terminal === "claimed" ? "held" : "released";
+    if (holder === null || holder.disposition !== expectedDisposition)
+        return;
+    const taskId = holder.taskId;
+    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")
+            lags.push({
+                kind: "settlement-failed",
+                surface: "task",
+                contractId: state.id,
+                taskId,
+                diagnostic: taskFailure(result),
+            });
+    }
+    catch (error) {
+        lags.push({ kind: "settlement-failed", surface: "task", contractId: state.id, taskId, diagnostic: diagnostic(error) });
+    }
+}
+function settleNamespace(state, effects, actions, lags) {
+    if (state.terminal !== null || state.coordinates.workspace !== "worktree" || state.bound === null)
+        return;
+    const worktrees = effects.filter((effect) => effect.kind === "worktree" && effect.action !== "removed");
+    for (const effect of worktrees) {
+        try {
+            actions.push({
+                kind: "namespace-context",
+                path: effect.path,
+                action: repairNamespaceContext(effect.path, [contractSegment(state.id)]),
+            });
+        }
+        catch (error) {
+            lags.push({
+                kind: "settlement-failed",
+                surface: "namespace-context",
+                contractId: state.id,
+                path: effect.path,
+                diagnostic: diagnostic(error),
+            });
+        }
+    }
+}
+function observeSettlement(repository) {
+    try {
+        return { kind: "present", holders: readTaskHolderProjection(repository) };
+    }
+    catch (error) {
+        return { kind: "failed", diagnostic: diagnostic(error) };
+    }
+}
+async function settleObserved(input, observation) {
+    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);
+    return { actions, lags };
+}
+export async function settle(input) {
+    return settleObserved(input, observeSettlement(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)));
+}

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

@@ -0,0 +1,65 @@
+import type { TaskDocument, TaskPriority, TaskState } from "./document.js";
+import { type TaskId } from "./identity.js";
+type TaskRef = Readonly<{
+    id: TaskId;
+    title: string | null;
+    state: TaskState | "missing";
+}>;
+type TaskDisposition = "ready" | "blocked" | "in_progress" | "on_hold" | "done" | "drop";
+export type TaskRow = Readonly<{
+    id: TaskId;
+    title: string;
+    state: TaskState;
+    priority: TaskPriority;
+    disposition: TaskDisposition;
+}>;
+export type BlockedTaskRow = TaskRow & Readonly<{
+    blockers: readonly TaskRef[];
+}>;
+export type TaskDetailFacts = Readonly<{
+    task: TaskDocument;
+    needs: readonly (TaskRef & Readonly<{
+        released: boolean;
+    }>)[];
+    blockers: readonly TaskRef[];
+    blocks: readonly TaskRef[];
+    parent: TaskRef | null;
+    children: readonly TaskRef[];
+    supersedes: readonly TaskRef[];
+    supersededBy: readonly TaskRef[];
+    related: readonly TaskRef[];
+}>;
+export type TaskTreeNode = Readonly<{
+    task: TaskRef & Readonly<{
+        priority: TaskPriority | null;
+    }>;
+    cycle?: true;
+    reference?: true;
+    needs: readonly TaskTreeNode[];
+}>;
+export type TaskBoard = Readonly<{
+    tasks: ReadonlyMap<TaskId, TaskDocument>;
+}>;
+type TaskRelation = "needs" | "parent" | "supersedes" | "relates";
+export type TaskDoctorIssue = Readonly<{
+    kind: "missing-target";
+    taskId: TaskId;
+    relation: TaskRelation;
+    target: TaskId;
+}> | Readonly<{
+    kind: "self-relation";
+    taskId: TaskId;
+    relation: TaskRelation;
+}> | Readonly<{
+    kind: "cycle";
+    relation: "needs" | "parent" | "supersedes";
+    tasks: readonly TaskId[];
+}>;
+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 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 {};

package/build/src/task/board.js

@@ -0,0 +1,155 @@
+import { parseTaskId, sameNamespace } from "./identity.js";
+const terminal = (state) => state === "done" || state === "drop";
+const sorted = (values) => [...values].sort((a, b) => Buffer.compare(Buffer.from(a.id), Buffer.from(b.id)));
+function taskRef(board, id) {
+    const task = board.tasks.get(id);
+    return task === undefined ? { id, title: null, state: "missing" } : { id, title: task.title, state: task.state };
+}
+function outgoing(document, relation) { return document[relation]; }
+function reverse(board, id, relation) {
+    return sorted([...board.tasks.values()].filter((task) => outgoing(task, relation).includes(id)).map((task) => taskRef(board, task.id)));
+}
+function children(board, id) {
+    return sorted([...board.tasks.values()].filter((task) => task.parent === id).map((task) => taskRef(board, task.id)));
+}
+function related(board, task) {
+    const ids = new Set(task.relates);
+    for (const candidate of board.tasks.values())
+        if (candidate.relates.includes(task.id))
+            ids.add(candidate.id);
+    return sorted([...ids].map((id) => taskRef(board, id)));
+}
+function disposition(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";
+}
+export function projectDetailFacts(board, id) {
+    const task = board.tasks.get(id);
+    if (task === undefined)
+        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"),
+        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),
+    };
+}
+function inScope(task, scope) { return scope === null || sameNamespace(parseTaskId(task.id).namespace, scope); }
+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),
+    })).sort((a, b) => a.priority - b.priority || Buffer.compare(Buffer.from(a.id), Buffer.from(b.id)));
+}
+export function projectReady(board, scope) {
+    return projectRows(board, scope, "active").filter((row) => row.disposition === "ready");
+}
+export function projectBlocked(board, scope) {
+    return projectRows(board, scope, "active").flatMap((row) => {
+        if (row.state !== "open" && row.state !== "in_progress")
+            return [];
+        const blockers = projectDetailFacts(board, row.id).blockers;
+        return blockers.length === 0 ? [] : [{ ...row, blockers }];
+    });
+}
+function relationIds(task, relation) {
+    return relation === "parent" ? task.parent === null ? [] : [task.parent] : task[relation];
+}
+export function relationProblem(board, before, after) {
+    for (const relation of ["needs", "parent", "supersedes", "relates"]) {
+        const previous = new Set(before === null ? [] : relationIds(before, relation));
+        for (const target of relationIds(after, relation)) {
+            if (previous.has(target))
+                continue;
+            if (target === after.id)
+                return `${after.id} has a self ${relation} relation`;
+            if (!board.tasks.has(target))
+                return `${after.id} ${relation} target does not exist: ${target}`;
+        }
+    }
+    return null;
+}
+function cycleComponents(board, relation) {
+    const ids = sorted([...board.tasks.keys()].map((id) => ({ id }))).map(({ id }) => id);
+    const edges = new Map(ids.map((id) => [id, relationIds(board.tasks.get(id), relation).filter((target) => board.tasks.has(target))]));
+    const reverse = new Map(ids.map((id) => [id, []]));
+    for (const [id, targets] of edges)
+        for (const target of targets)
+            reverse.get(target).push(id);
+    const visited = new Set(), finished = [];
+    for (const root of ids) {
+        if (visited.has(root))
+            continue;
+        visited.add(root);
+        const stack = [{ id: root, index: 0 }];
+        while (stack.length > 0) {
+            const frame = stack.at(-1), targets = edges.get(frame.id);
+            if (frame.index < targets.length) {
+                const target = targets[frame.index++];
+                if (!visited.has(target)) {
+                    visited.add(target);
+                    stack.push({ id: target, index: 0 });
+                }
+            }
+            else {
+                finished.push(frame.id);
+                stack.pop();
+            }
+        }
+    }
+    const assigned = new Set(), components = [];
+    for (const root of finished.reverse()) {
+        if (assigned.has(root))
+            continue;
+        const component = [], stack = [root];
+        assigned.add(root);
+        while (stack.length > 0) {
+            const id = stack.pop();
+            component.push(id);
+            for (const target of reverse.get(id))
+                if (!assigned.has(target)) {
+                    assigned.add(target);
+                    stack.push(target);
+                }
+        }
+        if (component.length > 1)
+            components.push(sorted(component.map((id) => ({ id }))).map(({ id }) => id));
+    }
+    return components.sort((left, right) => Buffer.compare(Buffer.from(left.join("\0")), Buffer.from(right.join("\0"))));
+}
+export function diagnoseBoard(board) {
+    const issues = [];
+    for (const task of sorted(board.tasks.values()))
+        for (const relation of ["needs", "parent", "supersedes", "relates"]) {
+            for (const target of relationIds(task, relation)) {
+                if (target === task.id)
+                    issues.push({ kind: "self-relation", taskId: task.id, relation });
+                else if (!board.tasks.has(target))
+                    issues.push({ kind: "missing-target", taskId: task.id, relation, target });
+            }
+        }
+    for (const relation of ["needs", "parent", "supersedes"]) {
+        for (const tasks of cycleComponents(board, relation))
+            issues.push({ kind: "cycle", relation, tasks });
+    }
+    return issues;
+}
+export function buildTree(board, root, full) {
+    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);
+        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 walk(root, []);
+}

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

@@ -0,0 +1,25 @@
+import { type TaskId } from "./identity.js";
+import { type TaskWorld } from "./store.js";
+import type { TaskRefusal, TaskRetry } from "./operations.js";
+type TaskDocumentChange = Readonly<{
+    taskId: TaskId;
+    kind: "created" | "updated";
+    documentDiff: string;
+}>;
+export type TaskCompositionResult = Readonly<{
+    kind: "accepted";
+    documentChanges: readonly TaskDocumentChange[];
+}> | Readonly<{
+    kind: "refused";
+    refusal: TaskRefusal;
+}> | Readonly<{
+    kind: "incomplete";
+    documentChanges: readonly TaskDocumentChange[];
+    stopped: TaskRefusal | Readonly<{
+        kind: "retry";
+        reason: TaskRetry;
+    }>;
+    draft: string;
+}>;
+export declare function composeTasks(world: TaskWorld, markdown: string, signal?: AbortSignal): Promise<TaskCompositionResult>;
+export {};