@astrosheep/keiyaku 4.5.11 → 4.5.13

package/build/src/task/identity.js

@@ -1,7 +1,17 @@
 import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { contractSegment } from "../core/facts/types.js";
 import { identityCoordinate, identitySegments } from "../identity/coordinates.js";
 import { normalizeIdentityStem } from "../identity/normalize.js";
 const STEM_CODE_POINTS = 32;
+const TASK_FILENAME_BYTES = 255;
+const TASK_EXTENSION_BYTES = Buffer.byteLength(".md");
+const TASK_LOCK_EXTENSION_BYTES = Buffer.byteLength(".sqlite");
+const GENERATED_SUFFIX = "-0000";
+export const TASK_LOCK_ID_BYTES = TASK_FILENAME_BYTES - TASK_LOCK_EXTENSION_BYTES;
+export const TASK_LOCAL_ID_BYTES = TASK_FILENAME_BYTES - TASK_EXTENSION_BYTES - TASK_LOCK_EXTENSION_BYTES - Buffer.byteLength(GENERATED_SUFFIX);
+const GENERATED_STEM_BYTES = TASK_LOCAL_ID_BYTES - Buffer.byteLength(GENERATED_SUFFIX);
+const WINDOWS_RESERVED = /^(?:con|prn|aux|nul|clock\$|com[1-9]|lpt[1-9])(?:\..*)?$/iu;
 export function isTaskSegment(value) {
     return (value.length > 0 &&
         value !== "." &&
@@ -26,8 +36,19 @@ export function formatTaskId(coordinate) {
         throw new TypeError("task coordinate contains a noncanonical segment");
     return identityCoordinate({ family: "task", segments: [...coordinate.namespace, coordinate.localId] });
 }
+export function canonicalTaskId(value) {
+    const id = formatTaskId(parseTaskId(value));
+    if (id !== value)
+        throw new TypeError("task ID is not canonical");
+    return id;
+}
+export function contractNamespace(id) {
+    return ["kei", contractSegment(id)];
+}
 export function taskAuthorityPath(tasksDirectory, coordinate) {
-    return join(tasksDirectory, ...coordinate.namespace, `${coordinate.localId}.md`);
+    if (![...coordinate.namespace, coordinate.localId].every(isTaskSegment))
+        throw new TypeError("task coordinate contains a noncanonical segment");
+    return join(tasksDirectory, ...coordinate.namespace.map((segment) => physicalTaskSegment(segment)), `${physicalTaskSegment(coordinate.localId)}.md`);
 }
 export function deriveLocalStem(title) {
     const stem = normalizeIdentityStem({ source: title });
@@ -43,17 +64,37 @@ export function deriveLocalStem(title) {
         fitted += `-${word}`;
         count = candidate;
     }
-    return fitted;
+    return fitPhysicalStem(fitted);
 }
 export function allocateLocalId(stem, occupied) {
-    if (!occupied.has(stem))
-        return stem;
-    for (let suffix = 2; Number.isSafeInteger(suffix); suffix += 1) {
-        const candidate = `${stem}-${suffix}`;
+    const seed = randomBytes(2).readUInt16BE(0);
+    for (let offset = 0; offset <= 0xffff; offset += 1) {
+        const suffix = ((seed + offset) & 0xffff).toString(16).padStart(4, "0");
+        const candidate = `${fitPhysicalStem(stem, suffix)}-${suffix}`;
         if (!occupied.has(candidate))
             return candidate;
     }
-    throw new Error("task identity collision ordinal exceeded the safe integer range");
+    throw new Error("task identity hexadecimal suffix space exhausted");
+}
+function fitPhysicalStem(stem, suffix) {
+    const maxBytes = suffix === undefined ? GENERATED_STEM_BYTES : TASK_LOCAL_ID_BYTES - Buffer.byteLength(`-${suffix}`);
+    let result = "";
+    for (const segment of new Intl.Segmenter("und", { granularity: "grapheme" }).segment(stem)) {
+        if (Buffer.byteLength(result + segment.segment) > maxBytes)
+            break;
+        result += segment.segment;
+    }
+    result = result.replace(/-+$/u, "");
+    if (result.length === 0)
+        throw new TypeError("task title cannot fit the physical filename budget");
+    return result;
+}
+export function physicalTaskSegment(segment, maxBytes = TASK_LOCAL_ID_BYTES) {
+    if (Buffer.byteLength(segment) <= maxBytes && !WINDOWS_RESERVED.test(segment))
+        return segment;
+    if (Buffer.byteLength(segment) > maxBytes)
+        throw new TypeError("task identity cannot fit the physical filename budget");
+    throw new TypeError("task identity contains a Windows-reserved physical segment");
 }
 export function sameNamespace(left, right) {
     return left.length === right.length && left.every((segment, index) => segment === right[index]);

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

@@ -5,7 +5,7 @@ import { type BlockedTaskRow, type TaskDetailFacts, type TaskDoctorIssue, type T
 import { type TaskCompositionAlias, type TaskCompositionBodyPreview, type TaskCompositionResult } from "./compose.js";
 import { TaskAuthorityCorruptionError, type TaskPriority, type TaskState } from "./document.js";
 import type { TaskId } from "./identity.js";
-import { type AddTaskDocumentInput, type AddTaskInput, type TaskBatchResult, type TaskCompositionDiagnostic, type TaskMutationResult, type TaskOutcome, type TaskRefusal, type TaskRetry, type TaskUpdateResult, type TaskView, type UpdateTaskInput } from "./operations.js";
+import { type AddTaskDocumentInput, type AddTaskInput, type TaskBatchResult, type TaskCleanupFailure, type TaskCompositionDiagnostic, type TaskMutationResult, type TaskOutcome, type TaskRefusal, type TaskRetry, type TaskUpdateResult, type TaskView, type UpdateTaskInput } from "./operations.js";
 import { TASK_RELATION_PREDICATE_FIELDS, type TaskPage, type TaskQueryExpression, type TaskQueryPredicate, type TaskQueryRow, type TaskQuerySort, type TaskRelationPredicateField } from "./query.js";
 export type TaskDetail = Omit<TaskDetailFacts, "task"> & Readonly<{
     task: TaskView;
@@ -23,9 +23,11 @@ export type TaskDoctorReport = Readonly<{
     issues: readonly TaskDoctorIssue[];
 }>;
 export type TaskDecompositionTree = TaskOutcome<TaskTreeNode>;
-export type { AddTaskDocumentInput, AddTaskInput, BlockedTaskRow, TaskBatchResult, TaskCompositionDiagnostic, TaskCompositionAlias, TaskCompositionBodyPreview, TaskCompositionResult, TaskDoctorIssue, TaskId, TaskMutationResult, TaskOutcome, TaskPriority, TaskRef, TaskRefusal, TaskRetry, TaskRow, TaskState, TaskTreeNode, TaskUpdateResult, TaskView, UpdateTaskInput, TaskPage, TaskQueryExpression, TaskQueryPredicate, TaskQueryRow, TaskQuerySort, TaskRelationPredicateField, };
+export type { AddTaskDocumentInput, AddTaskInput, BlockedTaskRow, TaskBatchResult, TaskCleanupFailure, TaskCompositionDiagnostic, TaskCompositionAlias, TaskCompositionBodyPreview, TaskCompositionResult, TaskDoctorIssue, TaskId, TaskMutationResult, TaskOutcome, TaskPriority, TaskRef, TaskRefusal, TaskRetry, TaskRow, TaskState, TaskTreeNode, TaskUpdateResult, TaskView, UpdateTaskInput, TaskPage, TaskQueryExpression, TaskQueryPredicate, TaskQueryRow, TaskQuerySort, TaskRelationPredicateField, };
 export type { LibraryExecution } from "../akuma/requests.js";
 export { TaskAuthorityCorruptionError, TASK_RELATION_PREDICATE_FIELDS };
+export { observeRecentTaskStatus, type RecentTaskStatusRow } from "./catalog.js";
+export { taskRowViewLimit } from "./input.js";
 declare class TaskHandle {
     readonly id: TaskId;
     private readonly world;
@@ -108,7 +110,6 @@ declare class TasksHandle {
     }>): Promise<TaskCompositionResult>;
 }
 export type Tasks = TasksHandle;
-export declare function tasksForExecution(world: WorldRoot, execution: ExecutionContext): Tasks;
 type TasksOfInput = Readonly<{
     execution?: LibraryExecution;
 }>;

package/build/src/task/index.js

@@ -1,13 +1,15 @@
 import { executionChannel, libraryExecution, localExecutionContext, } from "../akuma/requests.js";
 import { requestForwardedTask } from "./mutation.js";
-import { buildTree, createTaskRelations, diagnoseBoard, projectDetailFacts, } from "./board.js";
+import { buildTree, createTaskRelations, diagnoseBoard, } from "./board.js";
 import { composeTasks, } from "./compose.js";
 import { TaskAuthorityCorruptionError } from "./document.js";
-import { addTask, addTaskDocument, batchTasks, blockedTasks, lifecycleTask, listTasks, queryTasks, readyTasks, taskView, updateTask, } from "./operations.js";
+import { addTask, addTaskDocument, batchTasks, blockedTasks, lifecycleTask, listTasks, queryTasks, readTaskDetail, readyTasks, taskView, updateTask, } from "./operations.js";
 import { readBoard } from "./store.js";
-import { actor, addInput, closed, limit, namespace, record, signal, sort, taskId as id, taskIds, text, updateInput, } from "./input.js";
-import { normalizeTaskQuery, TASK_RELATION_PREDICATE_FIELDS, DEFAULT_TASK_LIMIT, } from "./query.js";
+import { actor, addInput, closed, namespace, record, signal, sort, taskRowViewLimit, taskId as id, taskIds, text, updateInput, } from "./input.js";
+import { normalizeTaskQuery, TASK_RELATION_PREDICATE_FIELDS, } from "./query.js";
 export { TaskAuthorityCorruptionError, TASK_RELATION_PREDICATE_FIELDS };
+export { observeRecentTaskStatus } from "./catalog.js";
+export { taskRowViewLimit } from "./input.js";
 function forwardTask(directory, world, request, signal) {
     return requestForwardedTask({
         directory,
@@ -26,8 +28,7 @@ class TaskHandle {
         this.execution = execution;
     }
     async read() {
-        const board = (await readBoard(this.world)).board;
-        const facts = projectDetailFacts(board, this.id, createTaskRelations(board));
+        const facts = await readTaskDetail(this.world, this.id);
         return facts === null ? null : { ...facts, task: taskView(facts.task) };
     }
     async tree() {
@@ -140,7 +141,8 @@ class TasksHandle {
             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");
-        return listTasks(this.world, namespace(v.namespace), v.selection ?? "active", v.scope, limit(v.limit) ?? DEFAULT_TASK_LIMIT);
+        const selectedLimit = taskRowViewLimit(v.limit);
+        return listTasks(this.world, namespace(v.namespace), v.selection ?? "active", v.scope, selectedLimit);
     }
     async ready(input = {}) {
         const v = record(input, "ready input");
@@ -148,7 +150,8 @@ class TasksHandle {
         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);
-        return readyTasks(this.world, namespace(v.namespace), v.scope, parent, limit(v.limit) ?? DEFAULT_TASK_LIMIT);
+        const selectedLimit = taskRowViewLimit(v.limit);
+        return readyTasks(this.world, namespace(v.namespace), v.scope, parent, selectedLimit);
     }
     async blocked(input = {}) {
         const v = record(input, "blocked input");
@@ -156,7 +159,8 @@ class TasksHandle {
         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);
-        return blockedTasks(this.world, namespace(v.namespace), v.scope, parent, limit(v.limit) ?? DEFAULT_TASK_LIMIT);
+        const selectedLimit = taskRowViewLimit(v.limit);
+        return blockedTasks(this.world, namespace(v.namespace), v.scope, parent, selectedLimit);
     }
     async query(input = {}) {
         const v = record(input, "query input");
@@ -173,13 +177,14 @@ class TasksHandle {
             }
             : normalizeTaskQuery(v.where);
         const selected = namespace(v.namespace);
+        const selectedLimit = taskRowViewLimit(v.limit);
         return queryTasks({
             world: this.world,
             ...(selected === undefined ? {} : { namespace: selected }),
             expression,
             ...(v.scope === undefined ? {} : { scope: v.scope }),
             sort: sort(v.sort) ?? "priority",
-            limit: limit(v.limit) ?? DEFAULT_TASK_LIMIT,
+            limit: selectedLimit,
         });
     }
     async doctor() {
@@ -239,11 +244,6 @@ class TasksHandle {
         return composeTasks(local);
     }
 }
-export function tasksForExecution(world, execution) {
-    if (typeof world !== "string")
-        throw new TypeError("Tasks.of world must be a WorldRoot");
-    return new TasksHandle(world, execution);
-}
 function tasksOfExecution(input) {
     if (input === undefined)
         return localExecutionContext();
@@ -253,6 +253,9 @@ function tasksOfExecution(input) {
 }
 export const Tasks = Object.freeze({
     of(world, input) {
-        return tasksForExecution(world, tasksOfExecution(input));
+        const execution = tasksOfExecution(input);
+        if (typeof world !== "string")
+            throw new TypeError("Tasks.of world must be a WorldRoot");
+        return new TasksHandle(world, execution);
     },
 });

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

@@ -1,7 +1,7 @@
 import { type TaskPriority, type TaskState } from "./document.js";
 import { type TaskId } from "./identity.js";
 import type { AddTaskInput, UpdateTaskInput } from "./operations.js";
-import { type TaskQuerySort } from "./query.js";
+import type { TaskQuerySort } 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;
@@ -12,6 +12,8 @@ export declare function text(value: unknown, label: string): string | undefined;
 export declare function actor(value: unknown): string | undefined;
 export declare function priority(value: unknown): TaskPriority | undefined;
 export declare function limit(value: unknown): number | undefined;
+/** Validates and supplies the shared bounded-list limit for Task row views. */
+export declare function taskRowViewLimit(value: unknown): number;
 export declare function sort(value: unknown): TaskQuerySort | undefined;
 export declare function state(value: unknown): TaskState | undefined;
 export declare function addInput(input: unknown): AddTaskInput;

package/build/src/task/input.js

@@ -1,5 +1,5 @@
 import { isTaskSegment, parseTaskId } from "./identity.js";
-import { isValidTaskLimit, MAX_TASK_LIMIT } from "./query.js";
+import { boundedListLimit } from "../bounded-list.js";
 export function record(value, label) {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
         throw new TypeError(`${label} must be an object`);
@@ -74,11 +74,14 @@ export function priority(value) {
 export function limit(value) {
     if (value === undefined)
         return undefined;
-    if (typeof value !== "number" || !isValidTaskLimit(value)) {
-        throw new TypeError(`limit must be an integer from 1 to ${MAX_TASK_LIMIT}`);
-    }
+    if (typeof value !== "number")
+        throw new TypeError("limit must be a number");
     return value;
 }
+/** Validates and supplies the shared bounded-list limit for Task row views. */
+export function taskRowViewLimit(value) {
+    return boundedListLimit(value);
+}
 export function sort(value) {
     if (value === undefined)
         return undefined;

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

@@ -0,0 +1,6 @@
+import { type SettledTaskResult, type TaskBatchResult, type TaskLifecycleVerb, type TaskMutationResult } from "./operation-types.js";
+import type { TaskId } from "./identity.js";
+import type { WorldRoot } from "../world.js";
+export declare function lifecycleTask(world: WorldRoot, id: TaskId, verb: TaskLifecycleVerb, signal?: AbortSignal, note?: string): Promise<TaskMutationResult>;
+export declare function batchTasks(world: WorldRoot, verb: "start" | "done" | "drop" | "hold", ids: readonly TaskId[], signal?: AbortSignal, note?: string): Promise<TaskBatchResult>;
+export declare function settleTask(world: WorldRoot, id: TaskId): Promise<SettledTaskResult>;

package/build/src/task/lifecycle-operations.js

@@ -0,0 +1,116 @@
+import { serializeTaskDocument } from "./document.js";
+import { authorityBytesMatch, readBoard, replaceAuthority, withTaskLocks } from "./store.js";
+import { advanceTaskTimestamp, taskView } 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" },
+};
+function currentTaskBoard(board, bytes) {
+    return { board, bytes: new Map(bytes) };
+}
+function retry(reason) {
+    return { kind: "retry", reason };
+}
+async function transitionLifecycle(world, id, verb, currentBoard, options = {}) {
+    const { note, freshness = "none" } = options;
+    const current = currentBoard.board.tasks.get(id);
+    if (current === undefined) {
+        return freshness === "batch" && !(await authorityBytesMatch(world, id, null))
+            ? retry("concurrent-modification")
+            : { kind: "refused", refusal: { kind: "task-missing", taskId: 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 } };
+    }
+    const at = new Date().toISOString();
+    const next = {
+        ...current,
+        state,
+        ...(note === undefined ? {} : { note }),
+        updatedAt: advanceTaskTimestamp(current.updatedAt, at),
+    };
+    const bytes = serializeTaskDocument(next);
+    if ((await replaceAuthority({
+        world,
+        id,
+        expected: currentBoard.bytes.get(id),
+        next: bytes,
+    })) !== "replaced") {
+        return retry("concurrent-modification");
+    }
+    currentBoard.board = {
+        tasks: new Map(currentBoard.board.tasks).set(id, next),
+    };
+    currentBoard.bytes.set(id, bytes);
+    return { kind: "accepted", value: taskView(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, {
+        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 () => {
+        const snapshot = await readBoard(world);
+        const options = note === undefined ? {} : { note };
+        return transitionLifecycle(world, id, verb, currentTaskBoard(snapshot.board, snapshot.bytes), options);
+    });
+    return result === "busy" ? retry("busy") : result;
+}
+export async function batchTasks(world, verb, ids, signal, note) {
+    signal?.throwIfAborted();
+    const snapshot = await readBoard(world);
+    const currentBoard = currentTaskBoard(snapshot.board, snapshot.bytes);
+    const items = [];
+    for (const id of ids) {
+        signal?.throwIfAborted();
+        items.push({
+            id,
+            outcome: await lifecycleFromCurrentBoard(world, id, verb, currentBoard, {
+                ...(signal === undefined ? {} : { signal }),
+                ...(note === undefined ? {} : { 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);
+        if (current === undefined)
+            return { kind: "refused", refusal: { kind: "task-missing", taskId: 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" },
+            };
+        }
+        const next = {
+            ...current,
+            state: "done",
+            updatedAt: advanceTaskTimestamp(current.updatedAt, new Date().toISOString()),
+        };
+        const replaced = await replaceAuthority({
+            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" };
+    });
+    return result === "busy" ? { kind: "retry", reason: "busy" } : result;
+}