@astrosheep/keiyaku 2.9.10 → 2.9.12

package/build/core/repository-ledger/read-model.js

@@ -1,7 +1,7 @@
 import { openTaskAdmissionEvidenceReader, readTaskAdmissionEvidenceAtCommit, } from "../task/settlement-git.js";
 import { repositoryDeliveryRef, } from "./codec.js";
 import { observeRepositoryLedgerHead, readAcceptedRepositoryFold } from "./accepted-fold-read.js";
-import { advanceRepositoryCurrentState, discardRepositoryCurrentState, publishRepositoryCurrentState, readPinnedCurrentContract, readPinnedRepositoryLifecycle, readRepositoryCurrentStateNodeIds, readRepositoryCurrentStatePin } from "./current-state-store.js";
+import { advanceRepositoryCurrentState, publishRepositoryCurrentState, readPinnedCurrentContract, readPinnedRepositoryLifecycle, readRepositoryCurrentStateNodeIds, readRepositoryCurrentStatePin, readRepositoryCurrentStatePredecessor } from "./current-state-store.js";
 import { IncrementalLedgerValidationError, readIncrementalRepositorySegment } from "./incremental-read.js";
 import { RepositoryObjectError } from "./git-object-store.js";
 /** Public lifecycle state derived only from the accepted repository-ledger fold. */
@@ -366,7 +366,8 @@ export async function readRepositoryLifecycle(cwd, options = {}) {
         const pinned = await readPinnedRepositoryLifecycle(cwd, observedHead, options.signal, { includeTopology: options.includeTopology });
         if (pinned)
             return deepFreeze(pinned);
-        const priorHead = await readRepositoryCurrentStatePin(cwd, options.signal);
+        const candidatePriorHead = observedHead === null ? null : await readRepositoryCurrentStatePredecessor(cwd, observedHead, options.signal);
+        const priorHead = candidatePriorHead === null ? null : await readRepositoryCurrentStatePin(cwd, candidatePriorHead, options.signal);
         if (priorHead && observedHead && priorHead !== observedHead) {
             try {
                 const acceptedObjectIds = await readRepositoryCurrentStateNodeIds(cwd, priorHead, options.signal);
@@ -391,7 +392,6 @@ export async function readRepositoryLifecycle(cwd, options = {}) {
                     || (error instanceof RepositoryObjectError && error.reason !== "git-failure");
                 if (!untrustedDelta)
                     throw error;
-                await discardRepositoryCurrentState(cwd, options.signal);
             }
         }
     }

package/build/core/repository-ledger/write-transaction.js

@@ -80,22 +80,22 @@ async function assertAuthoritativeCommitTipClosure(cwd, coordinates, operations)
         checked.add(operation.newOid);
     }
 }
-export async function buildLifecycleEntry(cwd, entry, expectedLedgerHead) {
-    const coordinates = await deriveHostGitCoordinates(cwd);
+export async function buildLifecycleEntry(cwd, entry, expectedLedgerHead, coordinates) {
+    const resolvedCoordinates = coordinates ?? await deriveHostGitCoordinates(cwd);
     if (expectedLedgerHead !== null)
-        assertHostObjectId(coordinates, expectedLedgerHead);
+        assertHostObjectId(resolvedCoordinates, expectedLedgerHead);
     const evidence = evidenceObjectId(entry);
     if (evidence !== null) {
-        assertHostObjectId(coordinates, evidence);
-        await assertReadableCommit(cwd, coordinates, evidence);
+        assertHostObjectId(resolvedCoordinates, evidence);
+        await assertReadableCommit(cwd, resolvedCoordinates, evidence);
     }
     const parents = [
         ...(expectedLedgerHead === null ? [] : [expectedLedgerHead]),
         ...(evidence === null ? [] : [evidence]),
     ];
-    const args = ["commit-tree", coordinates.emptyTree, ...parents.flatMap((parent) => ["-p", parent])];
+    const args = ["commit-tree", resolvedCoordinates.emptyTree, ...parents.flatMap((parent) => ["-p", parent])];
     const result = await runGitProcess(cwd, args, {
-        input: formatLifecycleEntry(entry, coordinates.objectFormat),
+        input: formatLifecycleEntry(entry, resolvedCoordinates.objectFormat),
         env: {
             GIT_AUTHOR_NAME: "Keiyaku",
             GIT_AUTHOR_EMAIL: "keiyaku@localhost",
@@ -110,16 +110,17 @@ export async function buildLifecycleEntry(cwd, entry, expectedLedgerHead) {
         throw new Error(`cannot build ${entry.kind} ledger object: ${detail}`, { cause: result.error });
     }
     const objectId = result.stdout.trim();
-    assertHostObjectId(coordinates, objectId);
-    return { entry, objectId, expectedLedgerHead, parents, coordinates };
+    assertHostObjectId(resolvedCoordinates, objectId);
+    return { entry, objectId, expectedLedgerHead, parents, coordinates: resolvedCoordinates };
 }
-export async function buildLifecycleTail(cwd, entries, expectedLedgerHead) {
+export async function buildLifecycleTail(cwd, entries, expectedLedgerHead, coordinates) {
     if (entries.length === 0)
         throw new Error("a lifecycle tail requires at least one entry");
+    const resolvedCoordinates = coordinates ?? await deriveHostGitCoordinates(cwd);
     const built = [];
     let parent = expectedLedgerHead;
     for (const entry of entries) {
-        const next = await buildLifecycleEntry(cwd, entry, parent);
+        const next = await buildLifecycleEntry(cwd, entry, parent, resolvedCoordinates);
         built.push(next);
         parent = next.objectId;
     }
@@ -199,7 +200,8 @@ async function buildTransactionTail(input) {
         throw new Error(`bind transaction repeats contract ${contract}`);
     if (input.verb !== "bind" && causalParent === null)
         throw new Error(`${input.verb} transaction has no accepted lifecycle predecessor for ${contract}`);
-    const tail = await buildLifecycleTail(input.cwd, input.entries, causalParent);
+    const coordinates = await deriveHostGitCoordinates(input.cwd);
+    const tail = await buildLifecycleTail(input.cwd, input.entries, causalParent, coordinates);
     const transaction = await buildLifecycleTransactionNode({
         cwd: input.cwd,
         verb: input.verb,
@@ -331,7 +333,7 @@ export async function publishAuthoritativeTransaction(cwd, transaction, options
         assertAuthority(transaction.target.expectedOid === entry.data.targetHead, "claim target CAS must equal targetHead");
         assertAuthority(transaction.delivery.ref === repositoryDeliveryRef(entry.contract), "claim delivery ref does not name its contract");
         assertAuthority(transaction.delivery.expectedOid === entry.data.deliveryHead, "claim delivery CAS must equal deliveryHead");
-        await assertHonestClaimEvidence(cwd, entry.data);
+        await assertHonestClaimEvidence(cwd, entry.data, { coordinates: built.transaction.coordinates });
         operations.push({ kind: "update", ref: transaction.target.ref, expectedOldOid: transaction.target.expectedOid, newOid: entry.data.mergeCommit }, { kind: "delete", ref: transaction.delivery.ref, expectedOldOid: transaction.delivery.expectedOid });
     }
     const write = await publishLifecycleWrite(cwd, built.transaction, final, operations, options.replayPlan, options.transactionRunner);

package/build/core/sqlite-process-lifetime-lock.js

@@ -0,0 +1,194 @@
+import * as fs from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+const SQLITE_BUSY = 5;
+const SUPPORTED_PLATFORMS = new Set(["darwin", "linux", "win32"]);
+export class SqliteProcessLifetimeLockError extends Error {
+    reason;
+    code = "SQLITE_PROCESS_LIFETIME_LOCK_UNAVAILABLE";
+    constructor(message, reason, options) {
+        super(message, options);
+        this.reason = reason;
+        this.name = "SqliteProcessLifetimeLockError";
+    }
+}
+export class SqliteProcessLifetimeLockUnsupportedError extends Error {
+    code = "SQLITE_PROCESS_LIFETIME_LOCK_UNSUPPORTED";
+    constructor(platform) {
+        super(`SQLite process-lifetime locks are unsupported on platform '${platform}'`);
+        this.name = "SqliteProcessLifetimeLockUnsupportedError";
+    }
+}
+export function isSqliteProcessLifetimeLockPlatformSupported(platform = process.platform) {
+    return SUPPORTED_PLATFORMS.has(platform);
+}
+export function sqliteProcessLifetimeLockErrorDetail(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function isSqliteProcessLifetimeLockContention(error) {
+    const code = typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : "";
+    const errcode = typeof error === "object" && error !== null && "errcode" in error
+        ? error.errcode
+        : undefined;
+    const message = sqliteProcessLifetimeLockErrorDetail(error).toLowerCase();
+    return errcode === SQLITE_BUSY || code === "ERR_SQLITE_BUSY" || code === "ERR_SQLITE_LOCKED"
+        || message.includes("database is locked") || message.includes("database is busy");
+}
+function assertPlatform(platform) {
+    if (!isSqliteProcessLifetimeLockPlatformSupported(platform)) {
+        throw new SqliteProcessLifetimeLockUnsupportedError(platform);
+    }
+}
+function assertBusyTimeout(busyTimeoutMs) {
+    if (!Number.isSafeInteger(busyTimeoutMs) || busyTimeoutMs < 0) {
+        throw new SqliteProcessLifetimeLockError("SQLite process-lifetime lock busy timeout must be a non-negative safe integer", "invalid");
+    }
+}
+function journalMode(database) {
+    const row = database.prepare("PRAGMA journal_mode").get();
+    return typeof row?.journal_mode === "string" ? row.journal_mode.toLowerCase() : undefined;
+}
+function assertSchema(database) {
+    database.prepare("SELECT singleton FROM lock_anchor LIMIT 1").get();
+}
+function closeTransaction(database) {
+    let failure;
+    try {
+        database.exec("ROLLBACK");
+    }
+    catch (error) {
+        failure = error;
+    }
+    try {
+        database.close();
+    }
+    catch (error) {
+        failure ??= error;
+    }
+    return failure;
+}
+function throwLockError(prefix, error) {
+    if (error instanceof SqliteProcessLifetimeLockError || error instanceof SqliteProcessLifetimeLockUnsupportedError)
+        throw error;
+    if (isSqliteProcessLifetimeLockContention(error)) {
+        throw new SqliteProcessLifetimeLockError(`${prefix} is already held`, "busy", { cause: error });
+    }
+    throw new SqliteProcessLifetimeLockError(`${prefix} failed: ${sqliteProcessLifetimeLockErrorDetail(error)}`, "open-failed", { cause: error });
+}
+/**
+ * Creates only a rollback-journal schema anchor. The empty database persists no
+ * ownership facts; an open transaction is the complete ownership signal.
+ */
+export function initializeSqliteProcessLifetimeLockDatabase(lockPath, platform = process.platform) {
+    assertPlatform(platform);
+    let database;
+    try {
+        database = new DatabaseSync(lockPath);
+        database.exec("PRAGMA busy_timeout=0");
+        database.exec("PRAGMA journal_mode=DELETE");
+        database.exec("CREATE TABLE IF NOT EXISTS lock_anchor (singleton INTEGER PRIMARY KEY CHECK (singleton = 1))");
+        assertSchema(database);
+        if (journalMode(database) !== "delete") {
+            throw new SqliteProcessLifetimeLockError("SQLite process-lifetime lock database does not use rollback-journal mode", "invalid");
+        }
+    }
+    catch (error) {
+        throwLockError("SQLite process-lifetime lock database initialization", error);
+    }
+    finally {
+        try {
+            database?.close();
+        }
+        catch { /* the causal initialization error is retained */ }
+    }
+    return lockPath;
+}
+export function openSqliteProcessLifetimeLockTransaction(input) {
+    const platform = input.platform ?? process.platform;
+    const busyTimeoutMs = input.busyTimeoutMs ?? 0;
+    assertPlatform(platform);
+    assertBusyTimeout(busyTimeoutMs);
+    if (!input.create) {
+        try {
+            if (!fs.lstatSync(input.path).isFile()) {
+                throw new SqliteProcessLifetimeLockError("SQLite process-lifetime lock database is not a regular file", "invalid");
+            }
+        }
+        catch (error) {
+            if (error instanceof SqliteProcessLifetimeLockError)
+                throw error;
+            throw new SqliteProcessLifetimeLockError(`SQLite process-lifetime lock database is not initialized: ${sqliteProcessLifetimeLockErrorDetail(error)}`, "open-failed", { cause: error });
+        }
+    }
+    let database;
+    try {
+        database = new DatabaseSync(input.path);
+        database.exec(`PRAGMA busy_timeout=${busyTimeoutMs}`);
+        if (input.create) {
+            database.exec("PRAGMA journal_mode=DELETE");
+            database.exec("CREATE TABLE IF NOT EXISTS lock_anchor (singleton INTEGER PRIMARY KEY CHECK (singleton = 1))");
+        }
+        database.exec(`BEGIN ${input.mode.toUpperCase()}`);
+        // A DEFERRED transaction becomes the projection guard only after this read
+        // acquires its SHARED lock. Keep this inside every transaction mode.
+        assertSchema(database);
+        if (journalMode(database) !== "delete") {
+            throw new SqliteProcessLifetimeLockError("SQLite process-lifetime lock database does not use rollback-journal mode", "invalid");
+        }
+    }
+    catch (error) {
+        if (database !== undefined)
+            closeTransaction(database);
+        throwLockError("SQLite process-lifetime lock acquisition", error);
+    }
+    let closed = false;
+    return {
+        path: input.path,
+        database,
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            const failure = closeTransaction(database);
+            if (failure !== undefined) {
+                throw new SqliteProcessLifetimeLockError(`SQLite process-lifetime lock release failed: ${sqliteProcessLifetimeLockErrorDetail(failure)}`, "release-failed", { cause: failure });
+            }
+        },
+    };
+}
+function waitForRetry(milliseconds, signal) {
+    return new Promise((resolve, reject) => {
+        const abort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason ?? new DOMException("operation aborted", "AbortError"));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", abort);
+            resolve();
+        }, milliseconds);
+        signal?.addEventListener("abort", abort, { once: true });
+    });
+}
+/** Waits for the sole BEGIN IMMEDIATE owner. Cancellation is the only time bound. */
+export async function acquireSqliteProcessLifetimeLock(input) {
+    const retryMs = input.retryMs ?? 25;
+    assertBusyTimeout(retryMs);
+    for (;;) {
+        input.signal?.throwIfAborted();
+        try {
+            return openSqliteProcessLifetimeLockTransaction({
+                path: input.path,
+                mode: "immediate",
+                busyTimeoutMs: 0,
+                create: true,
+                platform: input.platform,
+            });
+        }
+        catch (error) {
+            if (!(error instanceof SqliteProcessLifetimeLockError) || error.reason !== "busy")
+                throw error;
+            await waitForRetry(retryMs, input.signal);
+        }
+    }
+}

package/build/core/task/compose.js

@@ -0,0 +1,327 @@
+import { FlowError } from "../../flow-error.js";
+import { taskIdentifierSlug, IdentifierSlugError } from "../identifier-slug.js";
+import { buildTaskBoardFromDocuments, requireHealthy, resolveTaskId } from "./board.js";
+import { formatTaskCoordinate, parseTaskCoordinate } from "./coordinate.js";
+import { advancedTaskUpdatedAt } from "./model.js";
+function atLine(line, message) {
+    throw new FlowError("INVALID_TARGET", `task compose line ${line}: ${message}`);
+}
+function parseRelationValues(line, field, value) {
+    if (value === "")
+        return [];
+    const values = value.split(",");
+    const references = values.map((entry) => {
+        if (!entry.startsWith("@"))
+            atLine(line, `${field}= accepts comma-separated @COORDINATE references or an explicit empty assignment`);
+        try {
+            return parseTaskCoordinate(entry.slice(1), `${field} coordinate`).coordinate;
+        }
+        catch (error) {
+            if (error instanceof FlowError)
+                atLine(line, `${field}= accepts comma-separated @COORDINATE references or an explicit empty assignment`);
+            throw error;
+        }
+    });
+    if (new Set(references).size !== references.length)
+        atLine(line, `${field}= cannot repeat a coordinate`);
+    return references;
+}
+function parseAssignments(line, tokens) {
+    let clearParent = false;
+    const relations = {};
+    const declared = new Set();
+    for (const token of tokens) {
+        const match = /^(parent|needs|supersedes|relates)=(.*)$/.exec(token);
+        if (!match)
+            atLine(line, "inline declarations must use parent=, needs=, supersedes=, or relates=");
+        const field = match[1];
+        const value = match[2];
+        if (declared.has(field))
+            atLine(line, `${field}= may appear only once`);
+        declared.add(field);
+        if (field === "parent") {
+            if (value !== "")
+                atLine(line, "parent= only clears the parent; use nesting to assign one");
+            clearParent = true;
+        }
+        else {
+            relations[field] = parseRelationValues(line, field, value);
+        }
+    }
+    return { clearParent, relations };
+}
+function declarationTokens(line, content, kind) {
+    if (/\[(?:parent|needs|supersedes|relates)=/.test(content)) {
+        atLine(line, "inline declarations use whitespace-separated field=value tokens, not brackets");
+    }
+    if (kind === "@") {
+        const [reference, ...assignments] = content.slice(1).split(/\s+/);
+        if (!reference)
+            atLine(line, "task references must be exactly @COORDINATE followed only by inline declarations");
+        return { reference, ...parseAssignments(line, assignments) };
+    }
+    const source = content.slice(1).trim();
+    if (!source)
+        atLine(line, "+ must be followed by a task title");
+    const tokens = source.split(/\s+/);
+    const assignmentStart = tokens.findIndex((token) => token.includes("="));
+    const titleTokens = assignmentStart === -1 ? tokens : tokens.slice(0, assignmentStart);
+    if (titleTokens.length === 0)
+        atLine(line, "+ must be followed by a task title");
+    const assignments = assignmentStart === -1 ? [] : tokens.slice(assignmentStart);
+    return { title: titleTokens.join(" "), ...parseAssignments(line, assignments) };
+}
+export function parseTaskCompositionSketch(input) {
+    if (!input.trim())
+        throw new FlowError("EMPTY_PARAM", "task compose sketch cannot be blank");
+    const nodes = [];
+    const taskAtDepth = new Map();
+    let pendingBodyBlanks;
+    let activeBody;
+    for (const [offset, raw] of input.split(/\r?\n/).entries()) {
+        const line = offset + 1;
+        if (/\t/.test(raw))
+            atLine(line, "uses spaces only; indentation is two spaces per tree level");
+        const indent = /^( *)/.exec(raw)[1].length;
+        if (indent % 2 !== 0)
+            atLine(line, "indentation must use whole two-space levels");
+        const content = raw.slice(indent).trimEnd();
+        const depth = indent / 2;
+        if (!content) {
+            if (activeBody) {
+                if (pendingBodyBlanks?.parent === activeBody)
+                    pendingBodyBlanks.count += 1;
+                else
+                    pendingBodyBlanks = { parent: activeBody, count: 1 };
+            }
+            else {
+                pendingBodyBlanks = undefined;
+            }
+            continue;
+        }
+        if (!content.startsWith("+") && !content.startsWith("@")) {
+            const parentDepth = [...taskAtDepth.keys()].filter((candidate) => candidate < depth).sort((a, b) => b - a)[0];
+            const parent = parentDepth === undefined ? undefined : taskAtDepth.get(parentDepth);
+            if (!parent?.title)
+                atLine(line, "bare prose is allowed only inside a new + task body");
+            if (pendingBodyBlanks?.parent === parent)
+                parent.body.push(...Array(pendingBodyBlanks.count).fill(""));
+            pendingBodyBlanks = undefined;
+            parent.body.push(raw.slice((parent.depth + 1) * 2));
+            activeBody = parent;
+            continue;
+        }
+        pendingBodyBlanks = undefined;
+        activeBody = undefined;
+        const kind = content.startsWith("+") ? "+" : "@";
+        const parsed = declarationTokens(line, content, kind);
+        for (const existingDepth of [...taskAtDepth.keys()])
+            if (existingDepth >= depth)
+                taskAtDepth.delete(existingDepth);
+        if (depth > 0 && !taskAtDepth.has(depth - 1))
+            atLine(line, "cannot indent below a missing parent task line");
+        const node = { line, depth, body: [], ...parsed };
+        nodes.push(node);
+        taskAtDepth.set(depth, node);
+    }
+    if (nodes.length === 0)
+        throw new FlowError("EMPTY_PARAM", "task compose sketch cannot be blank");
+    return nodes;
+}
+function requireHealthyFinalCompositionBoard(board, lines) {
+    const disease = board.diseases[0];
+    if (!disease)
+        return;
+    const coordinate = [disease.id, ...(disease.relatedIds ?? [])].find((candidate) => candidate !== undefined && lines.has(candidate));
+    if (coordinate !== undefined)
+        atLine(lines.get(coordinate), disease.message);
+    requireHealthy(board);
+}
+function documentFromView(task) {
+    return {
+        id: task.id, namespace: task.namespace, coordinate: task.coordinate, title: task.title,
+        state: task.state, pri: task.pri, needs: [...task.needs], parent: task.parent,
+        from: [...task.from], supersedes: [...task.supersedes], relatesTo: [...task.relatesTo],
+        createdAt: task.createdAt, ...(task.updatedAt === undefined ? {} : { updatedAt: task.updatedAt }),
+        creator: task.creator, ...(task.startedAt === undefined ? {} : { startedAt: task.startedAt }),
+        ...(task.contractId === undefined ? {} : { contractId: task.contractId }), body: task.body,
+    };
+}
+function allocateCoordinate(title, namespace, occupied, line) {
+    for (let ordinal = 1; Number.isSafeInteger(ordinal); ordinal += 1) {
+        try {
+            const localId = taskIdentifierSlug(title, ordinal === 1 ? "" : `-${ordinal}`);
+            const coordinate = formatTaskCoordinate(namespace, localId);
+            if (!occupied.has(coordinate))
+                return coordinate;
+        }
+        catch (error) {
+            if (error instanceof IdentifierSlugError)
+                atLine(line, `task title ${error.message}`);
+            throw error;
+        }
+    }
+    throw new FlowError("INTERNAL_STATE", "task compose allocation exceeded the safe integer range");
+}
+function same(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function resolvedRelations(board, node) {
+    const result = {};
+    for (const [name, values] of Object.entries(node.relations)) {
+        try {
+            const resolved = values.map((value) => resolveTaskId(board, value));
+            if (new Set(resolved).size !== resolved.length)
+                atLine(node.line, `${name}= resolves the same coordinate more than once`);
+            result[name] = resolved;
+        }
+        catch (error) {
+            if (error instanceof FlowError)
+                atLine(node.line, error.message);
+            throw error;
+        }
+    }
+    return result;
+}
+/** Build the composition entirely from one board observation. Persistence is caller-owned. */
+export function planTaskComposition(board, input) {
+    requireHealthy(board);
+    const now = input.now();
+    const parsed = parseTaskCompositionSketch(input.sketch);
+    const occupied = new Set(board.byId.keys());
+    const resolved = [];
+    const declared = new Set();
+    const allocations = [];
+    const parents = new Map();
+    for (const node of parsed) {
+        if (node.depth > 0 && !parents.has(node.depth - 1))
+            atLine(node.line, "cannot indent below a missing parent line");
+        for (const depth of [...parents.keys()])
+            if (depth >= node.depth)
+                parents.delete(depth);
+        let coordinate;
+        let existing;
+        if (node.reference) {
+            try {
+                coordinate = resolveTaskId(board, node.reference);
+            }
+            catch (error) {
+                if (error instanceof FlowError)
+                    atLine(node.line, error.message);
+                throw error;
+            }
+            existing = board.byId.get(coordinate);
+        }
+        else {
+            coordinate = allocateCoordinate(node.title, input.namespace, occupied, node.line);
+            occupied.add(coordinate);
+            allocations.push({ title: node.title, coordinate });
+        }
+        if (declared.has(coordinate))
+            atLine(node.line, `task ${coordinate} is declared more than once`);
+        declared.add(coordinate);
+        const parent = node.depth > 0 ? parents.get(node.depth - 1) : node.clearParent ? null : undefined;
+        if (node.depth > 0 && node.clearParent)
+            atLine(node.line, "cannot combine nesting with parent=");
+        if (parent === coordinate)
+            atLine(node.line, `task ${coordinate} cannot be its own parent`);
+        if (parent && (board.byId.get(parent)?.state === "done" || board.byId.get(parent)?.state === "drop")) {
+            atLine(node.line, `terminal task ${parent} cannot be a parent target`);
+        }
+        resolved.push({ ...node, coordinate, existing, parent });
+        parents.set(node.depth, coordinate);
+    }
+    const relationBoard = { ...board, byId: new Map(board.byId) };
+    for (const allocation of allocations) {
+        const [namespace, id] = allocation.coordinate.includes("/") ? allocation.coordinate.split("/") : [null, allocation.coordinate];
+        const node = resolved.find((entry) => entry.coordinate === allocation.coordinate);
+        const document = { id, namespace, coordinate: allocation.coordinate, title: allocation.title, state: "open", pri: 2, needs: [], parent: null, from: [], supersedes: [], relatesTo: [], createdAt: now.toISOString(), updatedAt: now.toISOString(), creator: input.creator, body: node.body.join("\n") };
+        relationBoard.byId.set(allocation.coordinate, { ...document, namespace, coordinate: allocation.coordinate, blocks: [], blocked: false, releasedNeeds: [], supersededBy: [], relatedTasks: [] });
+    }
+    const replacements = [];
+    const deltas = [];
+    for (const node of resolved) {
+        const current = node.existing;
+        const document = current ? documentFromView(current) : (() => {
+            const allocation = allocations.find((entry) => entry.coordinate === node.coordinate);
+            const [namespace, id] = node.coordinate.includes("/") ? node.coordinate.split("/") : [null, node.coordinate];
+            const timestamp = now.toISOString();
+            return { id, namespace, coordinate: node.coordinate, title: allocation.title, state: "open", pri: 2, needs: [], parent: null, from: [], supersedes: [], relatesTo: [], createdAt: timestamp, updatedAt: timestamp, creator: input.creator, body: node.body.join("\n") };
+        })();
+        if (node.parent !== undefined)
+            document.parent = node.parent;
+        const relations = resolvedRelations(relationBoard, node);
+        if (relations.needs !== undefined) {
+            for (const target of relations.needs) {
+                const targetTask = relationBoard.byId.get(target);
+                if (targetTask?.state === "done" || targetTask?.state === "drop")
+                    atLine(node.line, `terminal task ${target} cannot be a needs target`);
+            }
+            if (relations.needs.includes(document.coordinate))
+                atLine(node.line, `task ${document.coordinate} needs must not reference itself`);
+            document.needs = relations.needs;
+        }
+        if (relations.supersedes !== undefined) {
+            if (relations.supersedes.includes(document.coordinate))
+                atLine(node.line, `task ${document.coordinate} supersedes must not reference itself`);
+            document.supersedes = relations.supersedes;
+        }
+        if (relations.relates !== undefined) {
+            if (relations.relates.includes(document.coordinate))
+                atLine(node.line, `task ${document.coordinate} relations must not reference itself`);
+            document.relatesTo = relations.relates;
+        }
+        if (document.relatesTo.includes(document.coordinate))
+            atLine(node.line, `task ${document.coordinate} relations must not reference itself`);
+        const before = current;
+        const delta = { coordinate: node.coordinate, allocated: !current };
+        if (!before || before.parent !== document.parent)
+            delta.parent = { before: before?.parent ?? null, after: document.parent };
+        if (!before || !same(before.needs, document.needs))
+            delta.needs = { before: before?.needs ?? [], after: document.needs };
+        if (!before || !same(before.supersedes, document.supersedes))
+            delta.supersedes = { before: before?.supersedes ?? [], after: document.supersedes };
+        if (!before || !same(before.relatesTo, document.relatesTo))
+            delta.relatesTo = { before: before?.relatesTo ?? [], after: document.relatesTo };
+        if (Object.keys(delta).length > 2) {
+            if (input.namespace !== null && current && current.namespace !== input.namespace) {
+                atLine(node.line, `task ${node.coordinate} is outside compose namespace ${input.namespace}`);
+            }
+            if (current)
+                document.updatedAt = advancedTaskUpdatedAt(current, input.now());
+            replacements.push(document);
+            deltas.push(delta);
+        }
+    }
+    if (replacements.length === 0)
+        throw new FlowError("EMPTY_PARAM", "task compose sketch makes no changes");
+    const replacementByCoordinate = new Map(replacements.map((document) => [document.coordinate, document]));
+    const finalBoard = buildTaskBoardFromDocuments(board.tasks.map((task) => replacementByCoordinate.get(task.coordinate) ?? documentFromView(task)).concat(replacements.filter((document) => !board.byId.has(document.coordinate))));
+    const mentioned = new Set(resolved.map((node) => node.coordinate));
+    requireHealthyFinalCompositionBoard(finalBoard, new Map(resolved.map((node) => [node.coordinate, node.line])));
+    const warnings = [];
+    for (const task of board.tasks) {
+        if (mentioned.has(task.coordinate))
+            continue;
+        for (const target of [...task.needs, ...(task.parent ? [task.parent] : []), ...task.supersedes, ...task.relatesTo]) {
+            if (mentioned.has(target))
+                warnings.push({ kind: "external_inbound", coordinate: target, related: task.coordinate });
+        }
+    }
+    for (const node of resolved) {
+        const task = finalBoard.byId.get(node.coordinate);
+        for (const target of task.supersedes) {
+            if (finalBoard.byId.get(target)?.state === "open")
+                warnings.push({ kind: "open_superseded", coordinate: task.coordinate, related: target });
+        }
+        if (task.contractId)
+            warnings.push({ kind: "bound_task", coordinate: task.coordinate, related: task.contractId });
+    }
+    return { allocations, replacements, deltas, warnings };
+}
+export async function composeTasks(repository, input) {
+    return repository.mutate((board) => {
+        const plan = planTaskComposition(board, input);
+        return { replacements: plan.replacements, subject: "Compose tasks", requireCommit: true, select: () => plan };
+    });
+}

package/build/core/task/index.js

@@ -10,6 +10,7 @@ export { resolveTaskCreator } from "./task-git-actor.js";
 export { openTaskCommandRepository, openTaskMutationContext, readTaskDoctor, taskCommandContractId, taskCommandNamespace, } from "./task-git-runtime.js";
 export { openTaskStore, readTaskHistory, readTaskNamespaces } from "./task-git-store.js";
 export { taskRepositoryFromStore } from "./task-store-repository.js";
+export { composeTasks, planTaskComposition, parseTaskCompositionSketch, } from "./compose.js";
 export { isTaskId } from "./validation.js";
 export { isTaskCoordinate, parseTaskCoordinate, taskCoordinateFromSourcePath } from "./coordinate.js";
 export { buildTaskTree, createTask, doneTask, dropTask, parseTaskDocument, readTaskBoard, resolveTaskReadId, serializeTaskDocument, startTask, stopTask, holdTask, resumeTask, updateTask, updateTaskWithReceipt, deriveTaskDisplay, selectTaskList, taskUpdatedAt, advancedTaskUpdatedAt, } from "./task.js";