@zq-silk/yui 0.2.0 → 0.4.2

package/dist/coordination/workMailboxQueue.js

@@ -0,0 +1,86 @@
+import { completeProcessing, createWorkMailbox, enqueueSignal, mailboxEntityRefKey } from "./workMailbox.js";
+/** Atomically useful when called inside the caller's TaskStore transaction. */
+export function enqueueWork(store, target, reason, occurredAt, refs = []) {
+    const mailbox = store.getWorkMailbox(target) ?? createWorkMailbox(target);
+    const queued = enqueueSignal(mailbox, {
+        reason,
+        refs,
+        occurredAt: timestamp(occurredAt)
+    });
+    store.saveWorkMailbox(queued);
+    return queued;
+}
+/** Completes only the batch owned by the matching durable execution. */
+export function completeWorkExecution(store, target, executionRef) {
+    const mailbox = store.getWorkMailbox(target);
+    const processing = mailbox?.processing;
+    if (mailbox === null
+        || processing === undefined
+        || processing === null
+        || processing.executionRef === undefined
+        || mailboxEntityRefKey(processing.executionRef) !== mailboxEntityRefKey(executionRef)) {
+        return false;
+    }
+    store.saveWorkMailbox(completeProcessing(mailbox, processing.batchId));
+    return true;
+}
+/**
+ * Completes a mailbox execution or fails the surrounding transaction.
+ *
+ * A terminal Run and its processing mailbox batch are one consistency
+ * boundary. Silently accepting a missing or mismatched batch would leave
+ * durable work stuck in `processing` after the Run has already ended.
+ */
+export function requireCompleteWorkExecution(store, target, executionRef) {
+    const mailbox = store.getWorkMailbox(target);
+    const processing = mailbox?.processing;
+    if (mailbox === null || processing === null || processing === undefined) {
+        throw new Error(`Work mailbox has no processing execution for ${targetLabel(target)}: `
+            + `${executionRef.type}/${executionRef.id}.`);
+    }
+    if (processing.executionRef === undefined) {
+        throw new Error(`Work mailbox processing batch is not bound for ${targetLabel(target)}: `
+            + `${executionRef.type}/${executionRef.id}.`);
+    }
+    if (completeWorkExecution(store, target, executionRef))
+        return;
+    throw new Error(`Work mailbox execution mismatch for ${targetLabel(target)}: `
+        + `${executionRef.type}/${executionRef.id}.`);
+}
+/**
+ * Settles the exact Run delivery boundary, including the short window before
+ * the scheduler has claimed its single pending dispatch. A merged pending
+ * batch is never discarded because its signal-to-ref mapping is no longer
+ * recoverable.
+ */
+export function settleExactWorkExecution(store, target, executionRef) {
+    if (completeWorkExecution(store, target, executionRef))
+        return "processing";
+    const mailbox = store.getWorkMailbox(target);
+    if (mailbox === null)
+        return "absent";
+    const pending = mailbox.pending;
+    if (pending === null)
+        return "absent";
+    const matches = pending.refs.some((ref) => mailboxEntityRefKey(ref) === mailboxEntityRefKey(executionRef));
+    if (!matches)
+        return "absent";
+    if (pending.requestCount !== 1) {
+        throw new Error(`Cannot settle a merged pending mailbox batch for ${targetLabel(target)}: `
+            + `${executionRef.type}/${executionRef.id}.`);
+    }
+    store.saveWorkMailbox({ ...mailbox, pending: null });
+    return "pending";
+}
+function timestamp(value) {
+    return value instanceof Date ? value.toISOString() : value;
+}
+function targetLabel(target) {
+    switch (target.kind) {
+        case "operator": return "operator";
+        case "task": return `task/${target.taskId}`;
+        case "role": return `role/${target.taskId}/${target.roleName}`;
+        case "role-runtime": return `role-runtime/${target.taskId}/${target.roleName}`;
+        case "global-role-runtime": return `global-role-runtime/${target.roleName}`;
+    }
+}

package/dist/core/controllerClient.js

@@ -2,7 +2,8 @@ import { randomUUID } from "node:crypto";
 import { lstat, readFile } from "node:fs/promises";
 import { createConnection } from "node:net";
 import { join } from "node:path";
-import { CONTROLLER_DISCOVERY_PATH, CONTROLLER_SOCKET_PATH, MAX_CONTROLLER_MESSAGE_BYTES, ControllerProtocolError, encodeControllerRequest, parseControllerDiscovery, parseControllerResponse } from "./protocol.js";
+import { CONTROLLER_DISCOVERY_PATH, MAX_CONTROLLER_MESSAGE_BYTES, ControllerProtocolError, encodeControllerRequest, parseControllerDiscovery, parseControllerResponse } from "./protocol.js";
+import { isControllerSocketPathForHome } from "./controllerEndpoint.js";
 export class ControllerClientError extends Error {
     code;
     constructor(code, message) {
@@ -13,26 +14,39 @@ export class ControllerClientError extends Error {
 }
 export async function readControllerDiscovery(home) {
     const discoveryPath = join(home, CONTROLLER_DISCOVERY_PATH);
-    const expectedSocketPath = join(home, CONTROLLER_SOCKET_PATH);
     try {
         const metadata = await lstat(discoveryPath);
+        const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
         if (!metadata.isFile()
             || (metadata.mode & 0o077) !== 0
-            || metadata.size > 4_096) {
+            || metadata.size > 4_096
+            || (uid !== undefined && metadata.uid !== uid)) {
             throw invalidDiscovery();
         }
         const value = JSON.parse(await readFile(discoveryPath, "utf8"));
-        return parseControllerDiscovery(value, expectedSocketPath);
+        const socketPath = discoverySocketPath(home, value);
+        return parseControllerDiscovery(value, socketPath);
     }
     catch (error) {
         if (error instanceof ControllerClientError)
             throw error;
         if (isNodeError(error) && error.code === "ENOENT") {
-            throw new ControllerClientError("CONTROLLER_UNAVAILABLE", "Controller is not running.");
+            throw new ControllerClientError("CONTROLLER_NOT_RUNNING", "Controller is not running.");
         }
         throw invalidDiscovery();
     }
 }
+function discoverySocketPath(home, value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw invalidDiscovery();
+    }
+    const socketPath = Reflect.get(value, "socketPath");
+    if (typeof socketPath !== "string"
+        || !isControllerSocketPathForHome(home, socketPath)) {
+        throw invalidDiscovery();
+    }
+    return socketPath;
+}
 export async function callController(home, method, params = {}, options = {}) {
     const discovery = await readControllerDiscovery(home);
     const timeoutMs = options.timeoutMs ?? 5_000;

package/dist/core/controllerEndpoint.js

@@ -0,0 +1,37 @@
+import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+const LINUX_UNIX_SOCKET_PATH_BUDGET = 100;
+export function controllerSocketPath(home) {
+    const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+    const socketName = `${controllerSocketIdentity(home)}.sock`;
+    const isolatedPath = join(tmpdir(), `yui-${uid}`, socketName);
+    if (process.platform !== "linux"
+        || Buffer.byteLength(isolatedPath) < LINUX_UNIX_SOCKET_PATH_BUDGET) {
+        return isolatedPath;
+    }
+    // Linux limits Unix-socket paths to a small fixed budget. Managed Task
+    // runtimes intentionally use isolated TMPDIR roots, which may themselves
+    // be nested deeply enough to exhaust that budget. Keep the Home/uid/name
+    // fence while using the compact system temporary root only for this
+    // exceptional path; clients follow the Home-owned discovery record.
+    return join("/tmp", `yui-${uid}`, socketName);
+}
+/**
+ * A protected Home discovery record owns the Controller endpoint. Clients may
+ * run with an isolated TMPDIR, so validate the published Home/uid identity
+ * without recomputing the Controller process's temporary root.
+ */
+export function isControllerSocketPathForHome(home, candidate) {
+    if (!isAbsolute(candidate) || resolve(candidate) !== candidate)
+        return false;
+    const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+    return basename(dirname(candidate)) === `yui-${uid}`
+        && basename(candidate) === `${controllerSocketIdentity(home)}.sock`;
+}
+function controllerSocketIdentity(home) {
+    return createHash("sha256")
+        .update(resolve(home))
+        .digest("hex")
+        .slice(0, 24);
+}

package/dist/core/controllerServer.js

@@ -1,14 +1,29 @@
 import { randomBytes, timingSafeEqual } from "node:crypto";
-import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { createConnection, createServer } from "node:net";
-import { dirname, join } from "node:path";
-import { CONTROLLER_DISCOVERY_PATH, CONTROLLER_SOCKET_PATH, MAX_CONTROLLER_MESSAGE_BYTES, ControllerProtocolError, controllerFailure, encodeControllerResponse, isEmptyParams, parseControllerRequest } from "./protocol.js";
-export async function startControllerServer(home, dispatcher) {
+import { basename, dirname, join, resolve } from "node:path";
+import { CONTROLLER_DISCOVERY_PATH, FILE_TASK_CONTROLLER_PROTOCOL_VERSION, MAX_CONTROLLER_MESSAGE_BYTES, ControllerProtocolError, controllerFailure, encodeControllerResponse, isEmptyParams, parseControllerRequest } from "./protocol.js";
+import { controllerSocketPath } from "./controllerEndpoint.js";
+import { YUI_VERSION, yuiVersionIdentity } from "../version.js";
+import { removeEphemeralDomainIdentity, readEphemeralDomainIdentity, writeEphemeralDomainIdentity } from "../controller/domainIdentity.js";
+export async function startControllerServer(home, dispatcher, beforeDiscoveryRemoval, options = {}) {
+    const releaseLifecycleLock = await acquireHomeLifecycleLock(home);
+    try {
+        return await startControllerServerLocked(home, dispatcher, beforeDiscoveryRemoval, options);
+    }
+    finally {
+        await releaseLifecycleLock();
+    }
+}
+async function startControllerServerLocked(home, dispatcher, beforeDiscoveryRemoval, options = {}) {
     const discoveryPath = join(home, CONTROLLER_DISCOVERY_PATH);
-    const socketPath = join(home, CONTROLLER_SOCKET_PATH);
+    const socketPath = controllerSocketPath(home);
     const runtimeDirectory = dirname(discoveryPath);
+    const socketDirectory = dirname(socketPath);
     await mkdir(runtimeDirectory, { recursive: true, mode: 0o700 });
     await chmod(runtimeDirectory, 0o700);
+    await mkdir(socketDirectory, { recursive: true, mode: 0o700 });
+    await chmod(socketDirectory, 0o700);
     const token = randomBytes(32).toString("hex");
     let closeRunning = async () => undefined;
     const netServer = createServer((socket) => {
@@ -34,13 +49,17 @@ export async function startControllerServer(home, dispatcher) {
     }
     try {
         await chmod(socketPath, 0o600);
+        const processStartIdentity = await readLinuxProcessStartIdentity(process.pid);
         const discovery = Object.freeze({
             pid: process.pid,
+            processStartIdentity,
             socketPath,
             token
         });
-        await writeFile(discoveryPath, `${JSON.stringify(discovery)}\n`, { mode: 0o600 });
-        await chmod(discoveryPath, 0o600);
+        if (options.domainIdentity !== undefined) {
+            writeEphemeralDomainIdentity(home, options.domainIdentity);
+        }
+        await writeDiscoveryAtomically(discoveryPath, discovery);
         let resolveClosed = () => undefined;
         const closed = new Promise((resolve) => {
             resolveClosed = resolve;
@@ -50,8 +69,21 @@ export async function startControllerServer(home, dispatcher) {
             if (closePromise !== undefined)
                 return closePromise;
             closePromise = (async () => {
+                await beforeDiscoveryRemoval?.();
                 await closeNetServer(netServer);
                 await removeOwnedDiscovery(discoveryPath, token);
+                if (options.domainIdentity !== undefined) {
+                    // Keep the exact target fence while detached Role panes survive a
+                    // Controller stop/restart. The owning test teardown or an expired
+                    // domain reaper removes the identity only after those resources
+                    // converge, never by dropping the fence during a normal stop.
+                    const current = readEphemeralDomainIdentity(home);
+                    if (current.status === "valid"
+                        && current.identity?.token === options.domainIdentity.token
+                        && current.identity.tmuxTargets.length === 0) {
+                        removeEphemeralDomainIdentity(home, options.domainIdentity.token);
+                    }
+                }
                 resolveClosed();
             })();
             return closePromise;
@@ -63,6 +95,21 @@ export async function startControllerServer(home, dispatcher) {
         throw error;
     }
 }
+async function writeDiscoveryAtomically(discoveryPath, discovery) {
+    const temporaryPath = `${discoveryPath}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+    try {
+        await writeFile(temporaryPath, `${JSON.stringify(discovery)}\n`, {
+            mode: 0o600,
+            flag: "wx"
+        });
+        await chmod(temporaryPath, 0o600);
+        await rename(temporaryPath, discoveryPath);
+    }
+    catch (error) {
+        await rm(temporaryPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
 function receiveRequest(socket, token, dispatcher, stop) {
     let buffer = Buffer.alloc(0);
     let complete = false;
@@ -116,6 +163,25 @@ async function routeRequest(socket, line, token, dispatcher, stop) {
         sendResponse(socket, controllerFailure(request.id, "UNAUTHORIZED", "Controller authentication failed."));
         return;
     }
+    if (request.method === "controller.identity") {
+        if (!isEmptyParams(request.params)) {
+            sendResponse(socket, controllerFailure(request.id, "INVALID_PARAMS", "Controller params are invalid."));
+            return;
+        }
+        // This is an authenticated, private lifecycle response. Unlike the public
+        // resource inventory, it retains the exact executable/argv that the socket
+        // owner was launched with so an update can restore that same Controller.
+        sendResponse(socket, {
+            id: request.id,
+            ok: true,
+            result: {
+                executablePath: process.execPath,
+                args: process.argv.slice(1),
+                version: YUI_VERSION
+            }
+        });
+        return;
+    }
     if (request.method === "controller.status") {
         if (!isEmptyParams(request.params)) {
             sendResponse(socket, controllerFailure(request.id, "INVALID_PARAMS", "Controller params are invalid."));
@@ -124,16 +190,35 @@ async function routeRequest(socket, line, token, dispatcher, stop) {
         sendResponse(socket, {
             id: request.id,
             ok: true,
-            result: { pid: process.pid, running: true }
+            result: {
+                pid: process.pid,
+                running: true,
+                protocolVersion: FILE_TASK_CONTROLLER_PROTOCOL_VERSION,
+                version: YUI_VERSION,
+                storageLayoutVersion: yuiVersionIdentity().storageLayoutVersion,
+                aggregateSchemaVersion: yuiVersionIdentity().aggregateSchemaVersion
+            }
         });
         return;
     }
     if (request.method === "controller.stop") {
-        if (!isEmptyParams(request.params)) {
+        const expectedPid = expectedControllerStopPid(request.params);
+        if (expectedPid === null) {
             sendResponse(socket, controllerFailure(request.id, "INVALID_PARAMS", "Controller params are invalid."));
             return;
         }
-        sendResponse(socket, { id: request.id, ok: true, result: { stopped: true } }, () => void stop());
+        if (expectedPid !== undefined && expectedPid !== process.pid) {
+            sendResponse(socket, controllerFailure(request.id, "CONTROLLER_OWNERSHIP_MISMATCH", `Controller PID ${process.pid} does not match the expected PID ${expectedPid}.`));
+            return;
+        }
+        sendResponse(socket, {
+            id: request.id,
+            ok: true,
+            result: {
+                stopped: true,
+                ...(expectedPid === undefined ? {} : { pid: process.pid })
+            }
+        }, () => void stop());
         return;
     }
     if (dispatcher === undefined) {
@@ -151,6 +236,25 @@ async function routeRequest(socket, line, token, dispatcher, stop) {
             : controllerFailure(request.id, safeError.code, safeError.message));
     }
 }
+/**
+ * `controller.stop` is public with `{}` params, but update's replacement
+ * mismatch path may provide one exact PID fence.  `null` means malformed;
+ * `undefined` is the ordinary unfenced public request.
+ */
+function expectedControllerStopPid(value) {
+    if (isEmptyParams(value))
+        return undefined;
+    if (typeof value !== "object"
+        || value === null
+        || Array.isArray(value)
+        || Reflect.ownKeys(value).length !== 1
+        || !("expectedPid" in value)
+        || !Number.isSafeInteger(value.expectedPid)
+        || value.expectedPid <= 0) {
+        return null;
+    }
+    return value.expectedPid;
+}
 function sendResponse(socket, response, onFlushed) {
     let line;
     try {
@@ -258,6 +362,110 @@ function safeErrorMessage(message) {
         .slice(0, 512);
     return safe.length === 0 ? undefined : safe;
 }
+async function acquireHomeLifecycleLock(home) {
+    const lockPath = homeLifecycleLockPath(home);
+    await mkdir(dirname(lockPath), { recursive: true, mode: 0o700 });
+    const owner = Object.freeze({
+        pid: process.pid,
+        token: randomBytes(16).toString("hex"),
+        createdAt: new Date().toISOString()
+    });
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        try {
+            await writeFile(lockPath, `${JSON.stringify(owner)}\n`, {
+                flag: "wx",
+                mode: 0o600
+            });
+            return () => releaseHomeLifecycleLock(lockPath, owner);
+        }
+        catch (error) {
+            if (!isNodeError(error) || error.code !== "EEXIST")
+                throw error;
+        }
+        let existing;
+        try {
+            existing = await readHomeLifecycleLockOwner(lockPath);
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+        const ownerDescription = `owner PID ${existing.pid}, createdAt ${existing.createdAt}`;
+        if (isProcessAlive(existing.pid)) {
+            throw new Error(`Another Yui home lifecycle operation is already running (${ownerDescription}): ${lockPath}`);
+        }
+        throw new Error(`A previous Yui home lifecycle operation left a stale lock `
+            + `(${ownerDescription}): ${lockPath}. `
+            + "If no Controller startup or development reset is running, "
+            + "remove this exact lock file and retry.");
+    }
+    throw new Error(`Cannot safely acquire the Yui home lifecycle lock because its owner changed repeatedly: `
+        + lockPath);
+}
+function homeLifecycleLockPath(home) {
+    const resolvedHome = resolve(home);
+    return join(dirname(resolvedHome), `.${basename(resolvedHome)}.controller-lifecycle.lock`);
+}
+async function readHomeLifecycleLockOwner(lockPath) {
+    try {
+        const value = JSON.parse(await readFile(lockPath, "utf8"));
+        if (typeof value !== "object" || value === null
+            || !("pid" in value) || !Number.isSafeInteger(value.pid) || value.pid <= 0
+            || !("token" in value) || typeof value.token !== "string"
+            || value.token.length === 0 || value.token.length > 128
+            || !("createdAt" in value) || typeof value.createdAt !== "string"
+            || Number.isNaN(Date.parse(value.createdAt))) {
+            throw new Error("invalid owner");
+        }
+        return Object.freeze({
+            pid: value.pid,
+            token: value.token,
+            createdAt: value.createdAt
+        });
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            throw error;
+        throw new Error(`Cannot verify the existing Yui home lifecycle lock: ${lockPath}. `
+            + "If no Controller startup or development reset is running, remove this exact lock file and retry.");
+    }
+}
+async function releaseHomeLifecycleLock(lockPath, owner) {
+    let current;
+    try {
+        current = await readHomeLifecycleLockOwner(lockPath);
+    }
+    catch {
+        return;
+    }
+    if (current.pid === owner.pid && current.token === owner.token) {
+        await rm(lockPath, { force: true });
+    }
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !isNodeError(error) || error.code !== "ESRCH";
+    }
+}
+async function readLinuxProcessStartIdentity(pid) {
+    const stat = await readFile(`/proc/${pid}/stat`, "utf8");
+    const closingParenthesis = stat.lastIndexOf(")");
+    if (closingParenthesis < 0) {
+        throw new Error(`Cannot read Controller process identity for PID ${pid}.`);
+    }
+    const fieldsAfterCommand = stat.slice(closingParenthesis + 1).trim().split(/\s+/u);
+    const processStartIdentity = fieldsAfterCommand[19];
+    if (processStartIdentity === undefined
+        || !/^[0-9]{1,32}$/u.test(processStartIdentity)) {
+        throw new Error(`Cannot read Controller process identity for PID ${pid}.`);
+    }
+    return processStartIdentity;
+}
 function controllerAlreadyRunning() {
     return new Error("Controller is already running.");
 }

package/dist/core/protocol.js

@@ -1,6 +1,7 @@
 export const MAX_CONTROLLER_MESSAGE_BYTES = 1_048_576;
 export const CONTROLLER_DISCOVERY_PATH = "runtime/controller.json";
-export const CONTROLLER_SOCKET_PATH = "runtime/controller.sock";
+/** Bump when a running Controller cannot safely share one YUI_HOME with this CLI. */
+export const FILE_TASK_CONTROLLER_PROTOCOL_VERSION = 3;
 export class ControllerProtocolError extends Error {
     code;
     id;
@@ -97,9 +98,11 @@ export function controllerFailure(id, code, message) {
 }
 export function parseControllerDiscovery(value, expectedSocketPath) {
     if (!isRecord(value)
-        || !hasExactKeys(value, ["pid", "socketPath", "token"])
+        || !hasExactKeys(value, ["pid", "processStartIdentity", "socketPath", "token"])
         || !Number.isSafeInteger(value.pid)
         || value.pid < 1
+        || typeof value.processStartIdentity !== "string"
+        || !/^[0-9]{1,32}$/u.test(value.processStartIdentity)
         || value.socketPath !== expectedSocketPath
         || typeof value.token !== "string"
         || !/^[a-f0-9]{64}$/u.test(value.token)) {
@@ -107,6 +110,7 @@ export function parseControllerDiscovery(value, expectedSocketPath) {
     }
     return Object.freeze({
         pid: value.pid,
+        processStartIdentity: value.processStartIdentity,
         socketPath: value.socketPath,
         token: value.token
     });

package/dist/decision/decision.js

@@ -1,8 +1,9 @@
+import { validateTaskRecordReference } from "../task/taskRecordReference.js";
 export function createDecision(id, taskId, title, rationale, now) {
     const timestamp = now.toISOString();
     return {
         schemaVersion: 1,
-        id: requireSafeIdentity(id, "Decision id"),
+        id: validateTaskRecordReference({ taskId, localId: id }, "decision").localId,
         taskId: requireSafeIdentity(taskId, "Task id"),
         title: requireText(title, "Decision title"),
         rationale: requireText(rationale, "Decision rationale"),