@astrosheep/keiyaku 4.6.8 → 4.6.9

package/build/src/debt/index.js

@@ -0,0 +1,203 @@
+import { executionChannel, localExecutionContext } from "../akuma/requests.js";
+import { requestForwardedDebt, } from "./mutation.js";
+import { buildTree, createDebtRelations, diagnoseBoard, } from "./board.js";
+import { DebtAuthorityCorruptionError } from "./document.js";
+import { addDebt, addDebtDocument, batchDebts, blockedDebts, lifecycleDebt, listDebts, queryDebts, readDebtDetail, readyDebts, debtView, updateDebt, } from "./operations.js";
+import { boundedListLimit } from "../bounded-list.js";
+import { readBoard } from "./store.js";
+import { actor, addInput, closed, namespace, record, signal, sort, debtId as id, debtIds, text, updateInput, } from "./input.js";
+import { normalizeDebtQuery, debtQuerySelection, DEBT_RELATION_PREDICATE_FIELDS, } from "./query.js";
+export { DebtAuthorityCorruptionError, DEBT_RELATION_PREDICATE_FIELDS };
+export { observeRecentDebtStatus } from "./catalog.js";
+export { boundedListLimit as debtRowViewLimit } from "../bounded-list.js";
+function debtRoute(execution) {
+    const channel = executionChannel(execution);
+    return channel.kind === "body-request" ? { kind: "forwarded", directory: channel.directory } : { kind: "local" };
+}
+function forwardDebt(directory, world, request, signal) {
+    return requestForwardedDebt({
+        directory,
+        world,
+        request,
+        ...(signal === undefined ? {} : { signal }),
+    });
+}
+/** The single lifecycle request shapes, keyed once by verb instead of switched per handle. */
+const SINGLE_LIFECYCLE = {
+    done: (id, note) => ({ action: "debt.done", id, ...(note === undefined ? {} : { note }) }),
+    drop: (id, note) => ({ action: "debt.drop", id, ...(note === undefined ? {} : { note }) }),
+};
+/** The batch lifecycle request shapes for the same verbs. */
+const BATCH_LIFECYCLE = {
+    done: (ids, note) => ({ action: "debt.done", ids, ...(note === undefined ? {} : { note }) }),
+    drop: (ids, note) => ({ action: "debt.drop", ids, ...(note === undefined ? {} : { note }) }),
+};
+function debtOperations(world, route) {
+    if (route.kind === "forwarded") {
+        const { directory } = route;
+        return {
+            add: (values) => {
+                const { actor: _actor, signal, namespace: selected, ...request } = values;
+                return forwardDebt(directory, world, { action: "debt.add", input: { ...request, namespace: selected ?? [] } }, signal);
+            },
+            addDocument: (values) => forwardDebt(directory, world, { action: "debt.addDocument", input: { markdown: values.markdown, namespace: values.namespace ?? [] } }, values.signal),
+            update: (id, values) => {
+                const { signal, ...request } = values;
+                return forwardDebt(directory, world, { action: "debt.update", id, input: request }, signal);
+            },
+            lifecycle: (id, verb, note, signal) => forwardDebt(directory, world, SINGLE_LIFECYCLE[verb](id, note), signal),
+            batch: (verb, ids, note, signal) => forwardDebt(directory, world, BATCH_LIFECYCLE[verb](ids, note), signal),
+        };
+    }
+    return {
+        add: (values) => addDebt(world, values),
+        addDocument: (values) => addDebtDocument(world, values),
+        update: (id, values) => updateDebt(world, id, values),
+        lifecycle: (id, verb, note, signal) => lifecycleDebt(world, id, verb, signal, note),
+        batch: (verb, ids, note, signal) => batchDebts(world, verb, ids, signal, note),
+    };
+}
+class DebtHandle {
+    id;
+    world;
+    operations;
+    constructor(id, world, operations) {
+        this.id = id;
+        this.world = world;
+        this.operations = operations;
+    }
+    async read() {
+        const facts = await readDebtDetail(this.world, this.id);
+        return facts === null ? null : { ...facts, debt: debtView(facts.debt) };
+    }
+    async tree() {
+        if (arguments.length > 0)
+            throw new TypeError("tree accepts no input");
+        const board = (await readBoard(this.world)).board;
+        const node = buildTree(board, this.id, createDebtRelations(board));
+        return node === null
+            ? { kind: "refused", refusal: { kind: "debt-missing", debtId: this.id } }
+            : { kind: "accepted", value: node };
+    }
+    update(input) {
+        return this.operations.update(this.id, updateInput(input));
+    }
+    lifecycle(verb, input) {
+        const value = record(input ?? {}, `${verb} input`);
+        closed(value, ["note", "signal"], `${verb} input`);
+        const note = text(value.note, "note");
+        return this.operations.lifecycle(this.id, verb, note, signal(value.signal));
+    }
+    done(input) {
+        return this.lifecycle("done", input);
+    }
+    drop(input) {
+        return this.lifecycle("drop", input);
+    }
+}
+class DebtsHandle {
+    world;
+    root;
+    operations;
+    constructor(world, execution) {
+        this.world = world;
+        this.root = world;
+        this.operations = debtOperations(world, debtRoute(execution));
+    }
+    debt(input) {
+        const v = record(input, "debt input");
+        closed(v, ["id"], "debt input");
+        return new DebtHandle(id(v.id), this.world, this.operations);
+    }
+    add(input) {
+        return this.operations.add(addInput(input));
+    }
+    addDocument(input) {
+        const v = record(input, "addDocument input");
+        closed(v, ["markdown", "namespace", "actor", "signal"], "addDocument input");
+        const markdown = text(v.markdown, "markdown");
+        if (markdown === undefined)
+            throw new TypeError("markdown is required");
+        const ns = namespace(v.namespace), createdBy = actor(v.actor), abort = signal(v.signal);
+        return this.operations.addDocument({
+            markdown,
+            ...(ns === undefined ? {} : { namespace: ns }),
+            ...(createdBy === undefined ? {} : { actor: createdBy }),
+            ...(abort === undefined ? {} : { signal: abort }),
+        });
+    }
+    async list(input = {}) {
+        const v = record(input, "list input");
+        closed(v, ["selection", "scope", "namespace", "limit"], "list input");
+        if (v.selection !== undefined && v.selection !== "active" && v.selection !== "closed" && v.selection !== "all")
+            throw new TypeError("selection must be active, closed, or all");
+        if (v.scope !== undefined && v.scope !== "namespace" && v.scope !== "world")
+            throw new TypeError("scope must be namespace or world");
+        const selectedLimit = boundedListLimit(v.limit);
+        return listDebts(this.world, namespace(v.namespace), v.selection ?? "active", v.scope, selectedLimit);
+    }
+    async ready(input = {}) {
+        const v = record(input, "ready input");
+        closed(v, ["scope", "namespace", "parent", "limit"], "ready input");
+        if (v.scope !== undefined && v.scope !== "namespace" && v.scope !== "world")
+            throw new TypeError("scope must be namespace or world");
+        const parent = v.parent === undefined ? undefined : id(v.parent);
+        const selectedLimit = boundedListLimit(v.limit);
+        return readyDebts(this.world, namespace(v.namespace), v.scope, parent, selectedLimit);
+    }
+    async blocked(input = {}) {
+        const v = record(input, "blocked input");
+        closed(v, ["scope", "namespace", "parent", "limit"], "blocked input");
+        if (v.scope !== undefined && v.scope !== "namespace" && v.scope !== "world")
+            throw new TypeError("scope must be namespace or world");
+        const parent = v.parent === undefined ? undefined : id(v.parent);
+        const selectedLimit = boundedListLimit(v.limit);
+        return blockedDebts(this.world, namespace(v.namespace), v.scope, parent, selectedLimit);
+    }
+    async query(input = {}) {
+        const v = record(input, "query input");
+        closed(v, ["where", "scope", "namespace", "sort", "limit"], "query input");
+        if (v.scope !== undefined && v.scope !== "namespace" && v.scope !== "world")
+            throw new TypeError("scope must be namespace or world");
+        const expression = v.where === undefined ? debtQuerySelection() : normalizeDebtQuery(v.where);
+        const selected = namespace(v.namespace);
+        const selectedLimit = boundedListLimit(v.limit);
+        return queryDebts({
+            world: this.world,
+            ...(selected === undefined ? {} : { namespace: selected }),
+            expression,
+            ...(v.scope === undefined ? {} : { scope: v.scope }),
+            sort: sort(v.sort) ?? "priority",
+            limit: selectedLimit,
+        });
+    }
+    async doctor() {
+        return { issues: diagnoseBoard((await readBoard(this.world)).board) };
+    }
+    batch(input) {
+        const v = record(input, "batch input");
+        closed(v, ["verb", "ids", "note", "signal"], "batch input");
+        const verb = v.verb;
+        if (verb !== "done" && verb !== "drop")
+            throw new TypeError("batch verb is invalid");
+        const ids = debtIds(v.ids, "ids");
+        if (ids === undefined || ids.length === 0)
+            throw new TypeError("ids requires at least one DebtId");
+        const note = text(v.note, "note");
+        return this.operations.batch(verb, ids, note, signal(v.signal));
+    }
+}
+/**
+ * The one Debts composition. Public `of` fixes local execution; CLI and Body pass their captured
+ * internal channel through `debtsWithExecution` instead of a second constructor.
+ */
+export function debtsWithExecution(world, execution) {
+    if (typeof world !== "string")
+        throw new TypeError("Debts.of world must be a WorldRoot");
+    return new DebtsHandle(world, execution);
+}
+export const Debts = Object.freeze({
+    of(world) {
+        return debtsWithExecution(world, localExecutionContext());
+    },
+});

package/build/src/{task → debt}/input.d.ts

@@ -1,14 +1,14 @@
-import { type TaskId } from "./identity.js";
-import type { AddTaskInput, UpdateTaskInput } from "./operations.js";
-import type { TaskQuerySort } from "./query.js";
+import { type DebtId } from "./identity.js";
+import type { AddDebtInput, UpdateDebtInput } from "./operations.js";
+import type { DebtQuerySort } from "./query.js";
 export declare function record(value: unknown, label: string): Record<string, unknown>;
 export declare function closed(value: Record<string, unknown>, allowed: readonly string[], label: string): void;
-export declare function taskId(value: unknown): TaskId;
+export declare function debtId(value: unknown): DebtId;
 export declare function signal(value: unknown): AbortSignal | undefined;
-export declare function taskIds(value: unknown, label: string): readonly TaskId[] | undefined;
+export declare function debtIds(value: unknown, label: string): readonly DebtId[] | undefined;
 export declare function namespace(value: unknown): readonly string[] | undefined;
 export declare function text(value: unknown, label: string): string | undefined;
 export declare function actor(value: unknown): string | undefined;
-export declare function sort(value: unknown): TaskQuerySort | undefined;
-export declare function addInput(input: unknown): AddTaskInput;
-export declare function updateInput(input: unknown): UpdateTaskInput;
+export declare function sort(value: unknown): DebtQuerySort | undefined;
+export declare function addInput(input: unknown): AddDebtInput;
+export declare function updateInput(input: unknown): UpdateDebtInput;

package/build/src/{task → debt}/input.js

@@ -1,4 +1,4 @@
-import { isTaskSegment, parseTaskId } from "./identity.js";
+import { isDebtSegment, parseDebtId } from "./identity.js";
 export function record(value, label) {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
         throw new TypeError(`${label} must be an object`);
@@ -11,10 +11,10 @@ export function closed(value, allowed, label) {
             throw new TypeError(`${label} has unknown field: ${key}`);
     }
 }
-export function taskId(value) {
+export function debtId(value) {
     if (typeof value !== "string")
-        throw new TypeError("task ID must be a string");
-    parseTaskId(value);
+        throw new TypeError("debt ID must be a string");
+    parseDebtId(value);
     return value;
 }
 export function signal(value) {
@@ -32,8 +32,8 @@ function strings(value, label) {
     }
     return value;
 }
-export function taskIds(value, label) {
-    const values = strings(value, label)?.map(taskId);
+export function debtIds(value, label) {
+    const values = strings(value, label)?.map(debtId);
     if (values !== undefined && new Set(values).size !== values.length) {
         throw new TypeError(`${label} must not contain duplicates`);
     }
@@ -43,7 +43,7 @@ export function namespace(value) {
     const values = strings(value, "namespace");
     if (values === undefined)
         return undefined;
-    if (!values.every(isTaskSegment))
+    if (!values.every(isDebtSegment))
         throw new TypeError("namespace must contain canonical segments");
     return values;
 }
@@ -81,13 +81,13 @@ export function sort(value) {
 function state(value) {
     if (value === undefined)
         return undefined;
-    if (value !== "open" && value !== "in_progress" && value !== "on_hold" && value !== "done" && value !== "drop") {
+    if (value !== "open" && value !== "done" && value !== "drop") {
         throw new TypeError("state is invalid");
     }
     return value;
 }
 function nullableId(value) {
-    return value === undefined || value === null ? value : taskId(value);
+    return value === undefined || value === null ? value : debtId(value);
 }
 export function addInput(input) {
     const value = record(input, "add input");
@@ -113,10 +113,10 @@ export function addInput(input) {
     const note = text(value.note, "note");
     const initialState = state(value.state);
     const selectedPriority = priority(value.priority);
-    const needs = taskIds(value.needs, "needs");
+    const needs = debtIds(value.needs, "needs");
     const parent = nullableId(value.parent);
-    const supersedes = taskIds(value.supersedes, "supersedes");
-    const relates = taskIds(value.relates, "relates");
+    const supersedes = debtIds(value.supersedes, "supersedes");
+    const relates = debtIds(value.relates, "relates");
     const createdBy = actor(value.actor);
     const abort = signal(value.signal);
     return {
@@ -177,15 +177,15 @@ export function updateInput(input) {
     if (selectedPriority !== undefined)
         result.priority = selectedPriority;
     for (const [key, ids] of [
-        ["needs", taskIds(value.needs, "needs")],
-        ["addNeeds", taskIds(value.addNeeds, "addNeeds")],
-        ["dropNeeds", taskIds(value.dropNeeds, "dropNeeds")],
-        ["supersedes", taskIds(value.supersedes, "supersedes")],
-        ["addSupersedes", taskIds(value.addSupersedes, "addSupersedes")],
-        ["dropSupersedes", taskIds(value.dropSupersedes, "dropSupersedes")],
-        ["relates", taskIds(value.relates, "relates")],
-        ["addRelates", taskIds(value.addRelates, "addRelates")],
-        ["dropRelates", taskIds(value.dropRelates, "dropRelates")],
+        ["needs", debtIds(value.needs, "needs")],
+        ["addNeeds", debtIds(value.addNeeds, "addNeeds")],
+        ["dropNeeds", debtIds(value.dropNeeds, "dropNeeds")],
+        ["supersedes", debtIds(value.supersedes, "supersedes")],
+        ["addSupersedes", debtIds(value.addSupersedes, "addSupersedes")],
+        ["dropSupersedes", debtIds(value.dropSupersedes, "dropSupersedes")],
+        ["relates", debtIds(value.relates, "relates")],
+        ["addRelates", debtIds(value.addRelates, "addRelates")],
+        ["dropRelates", debtIds(value.dropRelates, "dropRelates")],
     ])
         if (ids !== undefined)
             result[key] = ids;

package/build/src/debt/lifecycle-operations.d.ts

@@ -0,0 +1,6 @@
+import { type SettledDebtResult, type DebtBatchResult, type DebtLifecycleVerb, type DebtMutationResult } from "./operation-types.js";
+import type { DebtId } from "./identity.js";
+import type { WorldRoot } from "../world.js";
+export declare function lifecycleDebt(world: WorldRoot, id: DebtId, verb: DebtLifecycleVerb, signal?: AbortSignal, note?: string): Promise<DebtMutationResult>;
+export declare function batchDebts(world: WorldRoot, verb: DebtLifecycleVerb, ids: readonly DebtId[], signal?: AbortSignal, note?: string): Promise<DebtBatchResult>;
+export declare function settleDebt(world: WorldRoot, id: DebtId): Promise<SettledDebtResult>;

package/build/src/{task → debt}/lifecycle-operations.js

@@ -1,15 +1,11 @@
-import { serializeTaskDocument } from "./document.js";
-import { authorityBytesMatch, readBoard, replaceAuthority, withTaskLocks } from "./store.js";
-import { advanceTaskTimestamp, taskView } from "./view.js";
+import { serializeDebtDocument } from "./document.js";
+import { authorityBytesMatch, readBoard, replaceAuthority, withDebtLocks } from "./store.js";
+import { advanceDebtTimestamp, debtView } from "./view.js";
 const TRANSITIONS = {
-    start: { open: "in_progress" },
-    stop: { in_progress: "open" },
-    hold: { open: "on_hold", in_progress: "on_hold" },
-    resume: { on_hold: "open" },
-    done: { open: "done", in_progress: "done", on_hold: "done" },
-    drop: { open: "drop", in_progress: "drop", on_hold: "drop" },
+    done: { open: "done" },
+    drop: { open: "drop" },
 };
-function currentTaskBoard(board, bytes) {
+function currentDebtBoard(board, bytes) {
     return { board, bytes: new Map(bytes) };
 }
 function retry(reason) {
@@ -17,26 +13,26 @@ function retry(reason) {
 }
 async function transitionLifecycle(world, id, verb, currentBoard, options = {}) {
     const { note, freshness = "none" } = options;
-    const current = currentBoard.board.tasks.get(id);
+    const current = currentBoard.board.debts.get(id);
     if (current === undefined) {
         return freshness === "batch" && !(await authorityBytesMatch(world, id, null))
             ? retry("concurrent-modification")
-            : { kind: "refused", refusal: { kind: "task-missing", taskId: id } };
+            : { kind: "refused", refusal: { kind: "debt-missing", debtId: id } };
     }
     const state = TRANSITIONS[verb][current.state];
     if (state === undefined) {
         return freshness === "batch" && !(await authorityBytesMatch(world, id, currentBoard.bytes.get(id)))
             ? retry("concurrent-modification")
-            : { kind: "refused", refusal: { kind: "invalid-lifecycle-transition", taskId: id, state: current.state, verb } };
+            : { kind: "refused", refusal: { kind: "invalid-lifecycle-transition", debtId: id, state: current.state, verb } };
     }
     const at = new Date().toISOString();
     const next = {
         ...current,
         state,
         ...(note === undefined ? {} : { note }),
-        updatedAt: advanceTaskTimestamp(current.updatedAt, at),
+        updatedAt: advanceDebtTimestamp(current.updatedAt, at),
     };
-    const bytes = serializeTaskDocument(next);
+    const bytes = serializeDebtDocument(next);
     if ((await replaceAuthority({
         world,
         id,
@@ -46,31 +42,31 @@ async function transitionLifecycle(world, id, verb, currentBoard, options = {})
         return retry("concurrent-modification");
     }
     currentBoard.board = {
-        tasks: new Map(currentBoard.board.tasks).set(id, next),
+        debts: new Map(currentBoard.board.debts).set(id, next),
     };
     currentBoard.bytes.set(id, bytes);
-    return { kind: "accepted", value: taskView(next) };
+    return { kind: "accepted", value: debtView(next) };
 }
 async function lifecycleFromCurrentBoard(world, id, verb, currentBoard, options = {}) {
     const { signal, note } = options;
-    const result = await withTaskLocks({ world, allocation: false, ids: [id], ...(signal === undefined ? {} : { signal }) }, async () => transitionLifecycle(world, id, verb, currentBoard, {
+    const result = await withDebtLocks({ world, allocation: false, ids: [id], ...(signal === undefined ? {} : { signal }) }, async () => transitionLifecycle(world, id, verb, currentBoard, {
         freshness: "batch",
         ...(note === undefined ? {} : { note }),
     }));
     return result === "busy" ? retry("busy") : result;
 }
-export async function lifecycleTask(world, id, verb, signal, note) {
-    const result = await withTaskLocks({ world, allocation: false, ids: [id], ...(signal === undefined ? {} : { signal }) }, async () => {
+export async function lifecycleDebt(world, id, verb, signal, note) {
+    const result = await withDebtLocks({ world, allocation: false, ids: [id], ...(signal === undefined ? {} : { signal }) }, async () => {
         const snapshot = await readBoard(world);
         const options = note === undefined ? {} : { note };
-        return transitionLifecycle(world, id, verb, currentTaskBoard(snapshot.board, snapshot.bytes), options);
+        return transitionLifecycle(world, id, verb, currentDebtBoard(snapshot.board, snapshot.bytes), options);
     });
     return result === "busy" ? retry("busy") : result;
 }
-export async function batchTasks(world, verb, ids, signal, note) {
+export async function batchDebts(world, verb, ids, signal, note) {
     signal?.throwIfAborted();
     const snapshot = await readBoard(world);
-    const currentBoard = currentTaskBoard(snapshot.board, snapshot.bytes);
+    const currentBoard = currentDebtBoard(snapshot.board, snapshot.bytes);
     const items = [];
     for (const id of ids) {
         signal?.throwIfAborted();
@@ -84,32 +80,32 @@ export async function batchTasks(world, verb, ids, signal, note) {
     }
     return { items };
 }
-export async function settleTask(world, id) {
-    const result = await withTaskLocks({ world, allocation: false, ids: [id] }, async () => {
-        const snapshot = await readBoard(world), current = snapshot.board.tasks.get(id);
+export async function settleDebt(world, id) {
+    const result = await withDebtLocks({ world, allocation: false, ids: [id] }, async () => {
+        const snapshot = await readBoard(world), current = snapshot.board.debts.get(id);
         if (current === undefined)
-            return { kind: "refused", refusal: { kind: "task-missing", taskId: id } };
+            return { kind: "refused", refusal: { kind: "debt-missing", debtId: 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" },
+                refusal: { kind: "invalid-lifecycle-transition", debtId: id, state: current.state, verb: "done" },
             };
         }
         const next = {
             ...current,
             state: "done",
-            updatedAt: advanceTaskTimestamp(current.updatedAt, new Date().toISOString()),
+            updatedAt: advanceDebtTimestamp(current.updatedAt, new Date().toISOString()),
         };
         const replaced = await replaceAuthority({
             world,
             id,
             expected: snapshot.bytes.get(id),
-            next: serializeTaskDocument(next),
+            next: serializeDebtDocument(next),
         });
         return replaced === "replaced"
-            ? { kind: "changed", task: taskView(next), action: "done" }
+            ? { kind: "changed", debt: debtView(next), action: "done" }
             : { kind: "retry", reason: "concurrent-modification" };
     });
     return result === "busy" ? { kind: "retry", reason: "busy" } : result;