@zq-silk/yui 0.2.0 → 0.4.2

package/dist/storage/upgradeFence.js

@@ -0,0 +1,366 @@
+/**
+ * The upgrade admission fence.
+ *
+ * A fence is a small marker file inside a Yui Home. While it exists and is owned
+ * by a live process other than the caller, every authoritative writer — a
+ * baseline `yui` CLI invocation *and* the per-home Controller alike — refuses to
+ * begin a new write. This is the mechanism by which `yui upgrade`/`yui update`
+ * stop new writes before quiescing and switching the store, without a broad
+ * process kill or a TTL/idle heuristic.
+ *
+ * The fence is honored at the single storage write choke point
+ * (`FileTaskStore` commit), so both the CLI and the Controller — which mutate
+ * through the same store — observe it. Because the check lives in that shared
+ * path, every writer built from this release forward enforces it; it cannot
+ * retroactively bind an already-installed older binary, so the upgrade
+ * orchestrator additionally drains the Controller and fails closed on any live
+ * writer rather than relying on the fence alone. It never blocks reads, and it
+ * never blocks the process that placed it (so the upgrade orchestrator can
+ * re-pin the revision under the write lock). A fence whose owner process is gone
+ * is stale and is reclaimed, mirroring the storage lock's dead-owner reclaim.
+ */
+import { closeSync, constants, fsyncSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Fence marker location, beside the Controller discovery file under `runtime/`. */
+export const UPGRADE_FENCE_FILE = "runtime/upgrade.fence";
+/** Thrown when a writer is refused because an upgrade fence is in place. */
+export class UpgradeFenceError extends Error {
+    reason;
+    constructor(reason) {
+        super("Yui storage is fenced for an in-progress upgrade; new writes are refused "
+            + `(${reason}). Wait for the upgrade to finish, or if no upgrade is `
+            + "running remove the stale fence and retry.");
+        this.name = "UpgradeFenceError";
+        this.reason = reason;
+    }
+}
+function fencePath(home) {
+    return join(home, UPGRADE_FENCE_FILE);
+}
+/** Read the fence file's raw bytes at an exact path, or `null` when absent. */
+function readFenceRaw(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return null;
+        throw error;
+    }
+}
+/**
+ * Parse raw fence bytes into a record. A well-formed fence yields its fields; a
+ * malformed/unparseable fence yields a sentinel `ownerPid: -1` "malformed fence"
+ * so callers treat it as an undeterminable (fail-closed) live fence, never as
+ * absent or reclaimable.
+ */
+function parseFence(raw) {
+    try {
+        const value = JSON.parse(raw);
+        if (value.schemaVersion === 1
+            && Number.isInteger(value.ownerPid)
+            && typeof value.reason === "string"
+            && typeof value.createdAt === "string") {
+            return {
+                schemaVersion: 1,
+                ownerPid: value.ownerPid,
+                reason: value.reason,
+                createdAt: value.createdAt
+            };
+        }
+    }
+    catch {
+        // fall through to the malformed sentinel.
+    }
+    return { schemaVersion: 1, ownerPid: -1, reason: "malformed fence", createdAt: "" };
+}
+/** Read the current fence record, or `null` when none is present or it is unreadable. */
+export function readUpgradeFence(home) {
+    const raw = readFenceRaw(fencePath(home));
+    if (raw === null)
+        return null;
+    return parseFence(raw);
+}
+/**
+ * Refuse a write when a live upgrade fence owned by another process is present.
+ * A fence owned by the current process, or by a process that is gone, never
+ * blocks: the placer may re-pin under the lock, and a stale (dead-owner) fence is
+ * reclaimed. A stale fence is only cleared for the caller once the reclaim is
+ * PROVEN complete — if it cannot be cleared, this fails closed rather than
+ * falsely reporting the Home writable (R2-F4).
+ */
+export function assertHomeWritable(home, callerPid = process.pid) {
+    const path = fencePath(home);
+    const raw = readFenceRaw(path);
+    if (raw === null)
+        return;
+    const fence = parseFence(raw);
+    if (fence.ownerPid === callerPid)
+        return;
+    if (fence.ownerPid > 0 && !processIsAlive(fence.ownerPid)) {
+        // Stale fence from a crashed upgrade: reclaim it with the crash-safe atomic
+        // rename-aside (F4/R2-F4), then RE-VERIFY. We only permit the write if the
+        // admission path is now clear of a blocking fence:
+        //  - absent / owned by us / owned by a still-dead pid -> writable, and
+        //  - a LIVE foreign owner that took the freed slot -> refuse.
+        // If the stale fence is somehow still present (reclaim could not move it), we
+        // do NOT return writable — fail closed.
+        reclaimStaleFence(path, raw);
+        const afterRaw = readFenceRaw(path);
+        if (afterRaw === null)
+            return; // reclaimed: path is free.
+        const after = parseFence(afterRaw);
+        if (after.ownerPid === callerPid)
+            return;
+        if (after.ownerPid > 0 && !processIsAlive(after.ownerPid) && afterRaw !== raw) {
+            // A different dead-owner fence appeared (a racer's crashed attempt); it is
+            // itself reclaimable, so the Home is not live-fenced. Permit.
+            return;
+        }
+        // Either the SAME stale fence is still there (reclaim did not complete) or a
+        // live/undeterminable owner now holds it: fail closed, never falsely writable.
+        throw new UpgradeFenceError(after.reason);
+    }
+    throw new UpgradeFenceError(fence.reason);
+}
+/**
+ * Place an upgrade fence owned by the current process and return a release
+ * handle. The handle is idempotent and only removes a fence this process owns.
+ *
+ * Acquisition is a SINGLE atomic `O_CREAT | O_EXCL` create (P2-5): the kernel
+ * guarantees exactly one of any number of concurrent entrants wins that create,
+ * so there is no check-then-write window in which two upgraders both believe
+ * they acquired. A loser reads the existing fence and either:
+ *  - re-enters (it already owns the fence — idempotent), or
+ *  - reclaims a PROVABLY-DEAD owner's stale fence and retries the atomic create
+ *    once (a dead owner cannot be a live competitor), or
+ *  - fails closed with {@link UpgradeFenceError} for a live foreign owner or an
+ *    undeterminable/malformed fence.
+ * There is no lease, heartbeat, or multi-round negotiation — just the one atomic
+ * create plus a bounded dead-owner reclaim.
+ */
+export function placeUpgradeFence(home, options) {
+    const ownerPid = options.ownerPid ?? process.pid;
+    const fence = {
+        schemaVersion: 1,
+        ownerPid,
+        reason: options.reason,
+        createdAt: options.createdAt
+    };
+    const content = `${JSON.stringify(fence, null, 2)}\n`;
+    const path = fencePath(home);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    // At most a bounded number of attempts: each reclaim of a dead owner's stale
+    // fence is followed by one more atomic-create try. A fresh race is settled by
+    // the first atomic create; a live foreign owner fails immediately.
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        if (tryCreateFenceExclusive(path, content)) {
+            fsyncDirectory(dirname(path));
+            return makeFenceRelease(home, ownerPid);
+        }
+        // The atomic create lost: a fence already exists. Decide purely from its
+        // owner — never by overwriting, which would reintroduce the race.
+        const rawExisting = readFenceRaw(path);
+        if (rawExisting === null)
+            continue; // vanished between create and read; retry.
+        const existing = parseFence(rawExisting);
+        if (existing.ownerPid === ownerPid) {
+            // This process already owns the fence: idempotent re-entry.
+            return makeFenceRelease(home, ownerPid);
+        }
+        if (existing.ownerPid > 0 && !processIsAlive(existing.ownerPid)) {
+            // Provably-dead owner: reclaim the stale fence with a crash-safe atomic
+            // rename-aside (F4). It moves ONLY the exact stale inode out of the
+            // admission path — a racer that replaced it with a live fence is preserved,
+            // and no persistent coordination lock is left to orphan and block future
+            // reclaims. Then retry the atomic create against the freed path.
+            reclaimStaleFence(path, rawExisting);
+            continue;
+        }
+        // A live foreign owner, or an undeterminable/malformed fence (ownerPid <= 0):
+        // another upgrade holds this Home. Fail closed with no coordination protocol.
+        throw new UpgradeFenceError(existing.reason);
+    }
+    // Still contended after the bounded reclaim retries: fail closed rather than spin.
+    throw new UpgradeFenceError(readUpgradeFence(home)?.reason ?? "upgrade fence contended");
+}
+/**
+ * Reclaim a stale (dead-owner) fence: delete the fence file at `path` only if its
+ * bytes still exactly equal `expectedRaw`, under a short critical section that is
+ * itself CRASH-SAFE (R2-F4).
+ *
+ * The exclusion is a `mkdir` lock — but, mirroring the storage lock's
+ * `reclaimDeadLock`, the lock records its owner pid and is itself reclaimable, so
+ * a holder that crashes mid-critical-section cannot permanently orphan it and
+ * strand admission. On contention we first try to reclaim an orphaned lock (dead
+ * owner, or older than a small age bound), then retry; if the lock is genuinely
+ * held by a live process we simply return (that live reclaimer will finish, and
+ * the caller's next O_EXCL create settles the race).
+ *
+ * Correctness of the delete: inside the lock we RE-READ the fence and delete only
+ * if the bytes are still the exact stale ones, so a racer that O_EXCL-created a
+ * fresh live fence at `path` between our observe and the delete is never
+ * clobbered. The single O_EXCL create in `placeUpgradeFence` remains the sole
+ * winner-decider, so a reclaim never grants ownership by itself.
+ */
+function reclaimStaleFence(path, expectedRaw) {
+    const reclaimLock = `${path}.reclaim.lock`;
+    const ownerFile = join(reclaimLock, "owner");
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            mkdirSync(reclaimLock); // atomic; EEXIST if another reclaimer holds it.
+        }
+        catch (error) {
+            if (!isEexist(error))
+                throw error;
+            // Contended: reclaim the lock only if it is orphaned (dead owner or too
+            // old), then retry once. A live-held lock means another reclaimer is
+            // actively working — leave it and let the O_EXCL create settle the race.
+            if (reclaimOrphanedLock(reclaimLock, ownerFile))
+                continue;
+            return;
+        }
+        try {
+            writeFenceLockOwner(ownerFile);
+            // Re-read UNDER the lock; delete only if still the exact stale bytes.
+            const current = readFenceRaw(path);
+            if (current !== null && current === expectedRaw) {
+                rmSync(path, { force: true });
+                fsyncDirectory(dirname(path));
+            }
+        }
+        finally {
+            rmSync(reclaimLock, { recursive: true, force: true });
+        }
+        return;
+    }
+}
+/** Small age bound below which an orphaned-looking lock is given the benefit of the doubt. */
+const RECLAIM_LOCK_MIN_AGE_MS = 1_000;
+/**
+ * Reclaim a reclaim-lock directory ONLY when it is provably orphaned: its owner
+ * pid is dead (or unreadable) AND it is older than a small age bound (so a lock
+ * whose owner just `mkdir`ed but has not yet written its pid is not stolen).
+ * Returns true when it removed the lock (caller should retry), false otherwise.
+ */
+function reclaimOrphanedLock(reclaimLock, ownerFile) {
+    try {
+        const age = Date.now() - statSync(reclaimLock).mtimeMs;
+        if (age < RECLAIM_LOCK_MIN_AGE_MS)
+            return false; // too fresh; owner may be mid-acquire.
+        let pid;
+        try {
+            pid = Number.parseInt(readFileSync(ownerFile, "utf8"), 10);
+        }
+        catch {
+            pid = null; // no/unreadable owner on an old lock: treat as orphaned.
+        }
+        if (pid !== null && Number.isInteger(pid) && processIsAlive(pid))
+            return false; // live holder.
+        rmSync(reclaimLock, { recursive: true, force: true });
+        return true;
+    }
+    catch (error) {
+        // ENOENT: the lock vanished (holder released it) — retry the mkdir.
+        return isEnoent(error);
+    }
+}
+function writeFenceLockOwner(ownerFile) {
+    let descriptor;
+    try {
+        descriptor = openSync(ownerFile, constants.O_CREAT | constants.O_WRONLY | constants.O_TRUNC, 0o600);
+    }
+    catch {
+        // Best effort: without the owner pid the lock is still age-reclaimable, so a
+        // failure to record it degrades to the age bound rather than orphaning.
+        return;
+    }
+    // Keep the descriptor so it can be closed in `finally` — never leak an fd per
+    // reclaim (R3-F5).
+    try {
+        writeSync(descriptor, `${process.pid}\n`);
+    }
+    catch {
+        // Recording the pid is best-effort; the age bound still bounds reclaim.
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+/**
+ * Atomically create the fence file and write its content, failing (returning
+ * `false`) iff the file already exists. The `O_EXCL` create is the single point
+ * that decides a concurrent race; the owner bytes are written into the same
+ * descriptor and fsynced before it is closed.
+ */
+function tryCreateFenceExclusive(path, content) {
+    let descriptor;
+    try {
+        descriptor = openSync(path, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+    }
+    catch (error) {
+        if (isEexist(error))
+            return false;
+        throw error;
+    }
+    try {
+        writeSync(descriptor, content);
+        fsyncSync(descriptor);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+    return true;
+}
+/** Build the idempotent release handle that only clears a fence this owner holds. */
+function makeFenceRelease(home, ownerPid) {
+    return () => {
+        const current = readUpgradeFence(home);
+        if (current !== null && current.ownerPid === ownerPid)
+            clearUpgradeFence(home);
+    };
+}
+/** Unconditionally remove any fence marker (used by release and stale reclaim). */
+export function clearUpgradeFence(home) {
+    rmSync(fencePath(home), { force: true });
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error instanceof Error && "code" in error && error.code === "EPERM";
+    }
+}
+function isEnoent(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function isEexist(error) {
+    return error instanceof Error && "code" in error && error.code === "EEXIST";
+}
+/**
+ * fsync the directory holding the fence so a crash right after acquisition still
+ * observes the fence on the next boot (the marker's whole purpose is durability
+ * across an interrupted upgrade). Best-effort: a platform that cannot open a
+ * directory for fsync must not fail the acquisition.
+ */
+function fsyncDirectory(directory) {
+    let descriptor;
+    try {
+        descriptor = openSync(directory, constants.O_RDONLY | (constants.O_DIRECTORY ?? 0));
+    }
+    catch {
+        return;
+    }
+    try {
+        fsyncSync(descriptor);
+    }
+    catch {
+        // Some filesystems reject fsync on a directory fd; the O_EXCL create already
+        // committed the inode, so this is not fatal to correctness.
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}

package/dist/task/task.js

@@ -1,7 +1,7 @@
 export function createTask(id, title, now, metadata = {}) {
     const timestamp = now.toISOString();
     return {
-        schemaVersion: 1,
+        schemaVersion: 3,
         id: requireSafeIdentity(id, "Task id"),
         title: requireText(title, "Task title"),
         ...cloneMetadata(metadata),
@@ -15,10 +15,50 @@ export function activateTask(task, now) {
         throw new Error(`Cannot activate archived Task: ${task.id}.`);
     if (task.status === "completed")
         throw new Error(`Cannot activate completed Task ${task.id}; reopen it instead.`);
+    if (task.status === "retired")
+        throw new Error(`Cannot activate retired Task: ${task.id}.`);
     if (task.status === "active")
         return task;
     return { ...task, status: "active", updatedAt: now.toISOString() };
 }
+/** Explicitly retires a stale aggregate while retaining all historical facts. */
+export function retireTask(task, input, now) {
+    validateTask(task);
+    const summary = requireText(input.summary, "Task retirement summary");
+    const by = input.by;
+    if (!["user", "operator", "leader"].includes(by)) {
+        throw new Error(`Task retirement actor is invalid: ${String(by)}.`);
+    }
+    if (input.replacementTaskId !== undefined) {
+        const replacementTaskId = requireSafeIdentity(input.replacementTaskId, "Replacement Task id");
+        if (replacementTaskId === task.id) {
+            throw new Error("A Task cannot replace itself.");
+        }
+    }
+    if (task.status === "retired") {
+        if (task.retiredBy === by
+            && task.retirementSummary === summary
+            && task.replacementTaskId === input.replacementTaskId) {
+            return task;
+        }
+        throw new Error(`Task already has an explicit retirement: ${task.id}.`);
+    }
+    if (task.status === "archived" || task.status === "completed") {
+        throw new Error(`Task cannot be retired from ${task.status}: ${task.id}.`);
+    }
+    const timestamp = now.toISOString();
+    return validateTask({
+        ...task,
+        status: "retired",
+        retiredAt: timestamp,
+        retiredBy: by,
+        retirementSummary: summary,
+        ...(input.replacementTaskId === undefined
+            ? {}
+            : { replacementTaskId: input.replacementTaskId }),
+        updatedAt: timestamp
+    });
+}
 export function completeTask(task, now, completion) {
     if (task.status === "completed")
         return task;
@@ -47,8 +87,12 @@ export function reopenTask(task, now) {
 export function archiveTask(task, now, archive) {
     if (task.status === "archived")
         return task;
+    if (task.status !== "completed"
+        && task.status !== "retired") {
+        throw new Error(`Only a completed or retired Task can be archived: ${task.id}.`);
+    }
     const timestamp = now.toISOString();
-    return {
+    return validateTask({
         ...task,
         status: "archived",
         archivedAt: timestamp,
@@ -56,7 +100,7 @@ export function archiveTask(task, now, archive) {
         ...(archive?.reason === undefined ? {} : { archiveReason: archive.reason.trim() }),
         ...(archive?.summary === undefined ? {} : { archiveSummary: archive.summary.trim() }),
         updatedAt: timestamp
-    };
+    });
 }
 export function updateTaskArchived(task, archived, now, archive) {
     if (archived)
@@ -76,14 +120,13 @@ export function updateTaskMetadata(task, metadata, now) {
         ? metadata.tags
         : [...metadata.tags]);
     applyOptional(updated, "dueAt", metadata.dueAt);
-    if (metadata.repositoryId !== undefined) {
-        updated.repositoryId = requireSafeIdentity(metadata.repositoryId, "Repository id");
+    if (metadata.projectBindings !== undefined) {
+        updated.projectBindings = normalizeProjectBindings(metadata.projectBindings);
     }
-    if (metadata.baseRef !== undefined)
-        updated.baseRef = requireText(metadata.baseRef, "Task base ref");
     if (metadata.cwd !== undefined)
         updated.cwd = requireText(metadata.cwd, "Task workspace");
-    validateRepositorySelection(updated);
+    if (metadata.requireIntegration === true)
+        updated.requireIntegration = true;
     return updated;
 }
 function applyOptional(task, key, value) {
@@ -101,11 +144,11 @@ export function isTaskArchived(task) {
     return task.status === "archived";
 }
 export function validateTask(task) {
-    if (task.schemaVersion !== 1)
-        throw new Error("Task must use schemaVersion 1.");
+    if (task.schemaVersion !== 3)
+        throw new Error("Task must use schemaVersion 3.");
     requireSafeIdentity(task.id, "Task id");
     requireText(task.title, "Task title");
-    if (!["draft", "active", "completed", "archived"].includes(task.status)) {
+    if (!["draft", "active", "completed", "retired", "archived"].includes(task.status)) {
         throw new Error(`Task status is invalid: ${String(task.status)}.`);
     }
     requireTimestamp(task.createdAt, "Task createdAt");
@@ -127,13 +170,12 @@ export function validateTask(task) {
     }
     if (task.dueAt !== undefined)
         requireTimestamp(task.dueAt, "Task dueAt");
-    if (task.repositoryId !== undefined)
-        requireSafeIdentity(task.repositoryId, "Repository id");
-    if (task.baseRef !== undefined)
-        requireText(task.baseRef, "Task base ref");
+    normalizeProjectBindings(task.projectBindings);
     if (task.cwd !== undefined)
         requireText(task.cwd, "Task workspace");
-    validateRepositorySelection(task);
+    if (task.requireIntegration !== undefined && task.requireIntegration !== true) {
+        throw new Error("Task requireIntegration must be true when present.");
+    }
     const completionFields = [task.completedAt, task.completedBy, task.completionSummary];
     const hasAnyCompletion = completionFields.some((value) => value !== undefined);
     const hasAllCompletion = completionFields.every((value) => value !== undefined);
@@ -150,9 +192,39 @@ export function validateTask(task) {
     if (task.status === "completed" && !hasAllCompletion) {
         throw new Error("A completed Task requires completedAt, completedBy, and completionSummary.");
     }
-    if ((task.status === "draft" || task.status === "active") && hasAnyCompletion) {
+    if (["draft", "active", "retired"].includes(task.status)
+        && hasAnyCompletion) {
         throw new Error(`Task completion metadata is invalid for ${task.status} status.`);
     }
+    const retirementFields = [
+        task.retiredAt,
+        task.retiredBy,
+        task.retirementSummary,
+        task.replacementTaskId
+    ];
+    const hasAnyRetirement = retirementFields.some((value) => value !== undefined);
+    const retired = task.status === "retired";
+    const archivedRetirement = task.status === "archived" && hasAnyRetirement;
+    if (retired || archivedRetirement) {
+        if (task.retiredAt === undefined
+            || task.retiredBy === undefined
+            || task.retirementSummary === undefined) {
+            throw new Error("A retired Task requires retiredAt, retiredBy, and retirementSummary.");
+        }
+        requireTimestamp(task.retiredAt, "Task retiredAt");
+        if (!["user", "operator", "leader"].includes(task.retiredBy)) {
+            throw new Error(`Task retiredBy is invalid: ${String(task.retiredBy)}.`);
+        }
+        requireText(task.retirementSummary, "Task retirement summary");
+        if (task.replacementTaskId !== undefined) {
+            const replacementTaskId = requireSafeIdentity(task.replacementTaskId, "Replacement Task id");
+            if (replacementTaskId === task.id)
+                throw new Error("A Task cannot replace itself.");
+        }
+    }
+    else if (hasAnyRetirement) {
+        throw new Error(`Task retirement metadata is invalid for ${task.status} status.`);
+    }
     const hasAnyArchive = [task.archivedAt, task.archivedBy, task.archiveReason, task.archiveSummary]
         .some((value) => value !== undefined);
     if (task.status === "archived") {
@@ -167,6 +239,9 @@ export function validateTask(task) {
             requireText(task.archiveReason, "Task archive reason");
         if (task.archiveSummary !== undefined)
             requireText(task.archiveSummary, "Task archive summary");
+        if (hasAllCompletion === hasAnyRetirement) {
+            throw new Error("An archived Task must preserve exactly one completion or retirement outcome.");
+        }
     }
     else if (hasAnyArchive) {
         throw new Error(`Task archive metadata is invalid for ${task.status} status.`);
@@ -179,19 +254,50 @@ function cloneMetadata(metadata) {
         ...(metadata.priority === undefined ? {} : { priority: metadata.priority }),
         ...(metadata.tags === undefined ? {} : { tags: [...metadata.tags] }),
         ...(metadata.dueAt === undefined ? {} : { dueAt: metadata.dueAt }),
-        ...(metadata.repositoryId === undefined
-            ? {}
-            : { repositoryId: requireSafeIdentity(metadata.repositoryId, "Repository id") }),
-        ...(metadata.baseRef === undefined ? {} : { baseRef: requireText(metadata.baseRef, "Task base ref") }),
-        ...(metadata.cwd === undefined ? {} : { cwd: requireText(metadata.cwd, "Task workspace") })
+        projectBindings: normalizeProjectBindings(metadata.projectBindings ?? []),
+        ...(metadata.cwd === undefined ? {} : { cwd: requireText(metadata.cwd, "Task workspace") }),
+        ...(metadata.requireIntegration === true ? { requireIntegration: true } : {})
     };
-    validateRepositorySelection(cloned);
     return cloned;
 }
-function validateRepositorySelection(value) {
-    if (value.baseRef !== undefined && value.repositoryId === undefined) {
-        throw new Error("Task base ref requires a repository.");
+function normalizeProjectBindings(bindings) {
+    if (!Array.isArray(bindings))
+        throw new Error("Task Project bindings are invalid.");
+    const projectIds = new Set();
+    const directories = new Set();
+    return bindings.map((binding) => {
+        const projectId = requireSafeIdentity(binding.projectId, "Project id");
+        const directory = requireSafeIdentity(binding.directory, "Project directory");
+        const baseRef = requireText(binding.baseRef, "Task base ref");
+        if (projectIds.has(projectId)) {
+            throw new Error(`Task Project is duplicated: ${projectId}.`);
+        }
+        if (directories.has(directory)) {
+            throw new Error(`Task Project directory is duplicated: ${directory}.`);
+        }
+        projectIds.add(projectId);
+        directories.add(directory);
+        return { projectId, directory, baseRef };
+    });
+}
+export function taskProjectBinding(task, projectId) {
+    return task.projectBindings.find((binding) => binding.projectId === projectId);
+}
+export function taskHasProjects(task) {
+    return task.projectBindings.length > 0;
+}
+export function taskProjectIds(task) {
+    return task.projectBindings.map(({ projectId }) => projectId);
+}
+export function addTaskProjectBinding(task, binding, now) {
+    if (taskProjectBinding(task, binding.projectId) !== undefined) {
+        throw new Error(`Task already contains Project: ${binding.projectId}.`);
     }
+    return validateTask({
+        ...task,
+        projectBindings: normalizeProjectBindings([...task.projectBindings, binding]),
+        updatedAt: now.toISOString()
+    });
 }
 function requireSafeIdentity(value, label) {
     const normalized = requireText(value, label);

package/dist/task/taskRecordReference.js

@@ -0,0 +1,66 @@
+import { requireIdentity } from "../domain/validation.js";
+export const TASK_RECORD_ID_PREFIXES = {
+    workItem: "work-item",
+    agentRun: "agent-run",
+    reviewRound: "review-round",
+    changeSet: "change-set",
+    integrationAttempt: "integration",
+    message: "message",
+    inputRequest: "input",
+    decision: "decision",
+    milestone: "milestone",
+    event: "event"
+};
+export function formatTaskRecordReference(taskId, localId, kind) {
+    const reference = validateTaskRecordReference({ taskId, localId }, kind);
+    return `${reference.taskId}/${reference.localId}`;
+}
+export function formatAgentRunReceiptId(taskId, runId) {
+    return `agent-run:${formatTaskRecordReference(taskId, runId, "agentRun")}`;
+}
+export function formatInputRequestReceiptId(taskId, requestId) {
+    return `input-request:${formatTaskRecordReference(taskId, requestId, "inputRequest")}`;
+}
+export function resolveTaskRecordReference(value, options) {
+    const reference = normalizedReference(value, options.label);
+    const firstSeparator = reference.indexOf("/");
+    if (firstSeparator < 0) {
+        if (options.contextTaskId === undefined) {
+            throw new Error(`${options.label} has no Task context: ${reference}; `
+                + `use task-<n>/${reference}.`);
+        }
+        return validateTaskRecordReference({
+            taskId: options.contextTaskId,
+            localId: reference
+        }, options.kind);
+    }
+    if (firstSeparator === 0
+        || firstSeparator === reference.length - 1
+        || reference.indexOf("/", firstSeparator + 1) >= 0) {
+        throw new Error(`${options.label} must use taskId/localId.`);
+    }
+    return validateTaskRecordReference({
+        taskId: reference.slice(0, firstSeparator),
+        localId: reference.slice(firstSeparator + 1)
+    }, options.kind);
+}
+export function validateTaskRecordReference(value, kind) {
+    const taskId = requireIdentity(value.taskId, "Task id");
+    const localId = requireIdentity(value.localId, `${TASK_RECORD_ID_PREFIXES[kind]} local id`);
+    const match = new RegExp(`^${TASK_RECORD_ID_PREFIXES[kind]}-([1-9]\\d*)$`).exec(localId);
+    if (match === null || !Number.isSafeInteger(Number(match[1]))) {
+        throw new Error(`${TASK_RECORD_ID_PREFIXES[kind]} local id is invalid: ${localId}.`);
+    }
+    return { taskId, localId };
+}
+function normalizedReference(value, label) {
+    if (typeof value !== "string" || value.includes("\0")) {
+        throw new Error(`${label} is invalid.`);
+    }
+    const normalized = value.trim();
+    if (normalized.length === 0)
+        throw new Error(`${label} is required.`);
+    if (normalized !== value)
+        throw new Error(`${label} must be normalized.`);
+    return normalized;
+}