@zq-silk/yui 0.6.0 → 0.6.2

package/dist/controller/handoverCandidate.js

@@ -0,0 +1,168 @@
+/**
+ * Controller handover candidate prelude (Issue 02).
+ *
+ * A handover candidate is the new release's Controller process started while
+ * the old Controller still owns the Home. It does NOT bind the main socket or
+ * run the scheduler: it proves the new release starts, publishes its identity
+ * receipt, and waits until the old owner exits AND the active release pointer
+ * names its release. Only then does it promote itself by starting the full
+ * Controller runtime in-process.
+ *
+ * If the old owner stays live after the commit (a stuck Controller), the
+ * candidate stays read-only and reports `dualOwner: true` in its identity
+ * receipt; it never writes while another owner is live.
+ */
+import { fileURLToPath } from "node:url";
+import { buildRuntimeIdentityReceipt } from "../core/controllerServer.js";
+import { resolveStoreWorkerEnabledForHome } from "../storage/storeRpc.js";
+import { resolveTaskStoreBackendForHome } from "../storage/sqliteStore.js";
+import { detectRunningRelease, isOwnerLive, readActiveReleasePointer, readHandoverFence, removeCandidateDiscovery, removeHandoverFence, writeCandidateDiscovery, writeHandoverFence, writeHandoverReceipt, writeRuntimeIdentity } from "../release/runtimeRelease.js";
+import { startFileTaskControllerRuntime } from "./runtime.js";
+import { readLinuxProcessStartIdentity } from "./domainIdentity.js";
+export const CONTROLLER_CANDIDATE_ENV = "YUI_CONTROLLER_CANDIDATE";
+export const CONTROLLER_HANDOVER_ID_ENV = "YUI_CONTROLLER_HANDOVER_ID";
+const DEFAULT_POLL_INTERVAL_MS = 100;
+/**
+ * The grace a committed candidate waits for the old owner to exit before it
+ * latches `dualOwner: true`. This is the single authoritative old-owner exit
+ * grace: the activator trusts the candidate's latched signal and does not add
+ * a second independent grace (see `DEFAULT_DUAL_OWNER_GRACE_MS` in
+ * `releaseHandover.ts`, which is only an optional confirmation debounce).
+ */
+export const DEFAULT_DUAL_OWNER_GRACE_MS = 30_000;
+/** Reads the candidate configuration from the process environment. */
+export function handoverCandidateFromEnvironment(environment) {
+    if (environment[CONTROLLER_CANDIDATE_ENV] !== "1")
+        return null;
+    const handoverId = environment[CONTROLLER_HANDOVER_ID_ENV];
+    if (typeof handoverId !== "string"
+        || handoverId.length === 0
+        || handoverId.length > 128) {
+        throw new Error(`Handover candidate requires ${CONTROLLER_HANDOVER_ID_ENV} with a valid handover id.`);
+    }
+    return { handoverId };
+}
+/**
+ * Runs the candidate prelude and, on promotion, the full Controller runtime.
+ * Resolves when the promoted Controller closes or the candidate aborts.
+ */
+export async function runHandoverCandidate(home, handoverId, options = {}) {
+    const environment = options.environment ?? process.env;
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const dualOwnerGraceMs = options.dualOwnerGraceMs ?? DEFAULT_DUAL_OWNER_GRACE_MS;
+    const now = options.now ?? (() => new Date());
+    const release = detectRunningRelease(fileURLToPath(import.meta.url));
+    const startIdentity = readLinuxProcessStartIdentity(process.pid);
+    if (startIdentity === undefined) {
+        throw new Error(`Cannot read process start identity for handover candidate PID ${process.pid}.`);
+    }
+    const fence = readHandoverFence(home);
+    if (fence === null || fence.handoverId !== handoverId) {
+        throw new Error(`Handover fence for ${handoverId} is missing or does not match; aborting candidate.`);
+    }
+    // A candidate only starts from the `fenced` phase. If the activator already
+    // rolled the handover back (fence written as `rolled-back`, old Controller
+    // restored), a slow-starting candidate must not resurrect the fence to
+    // `candidate-ready`: that would leak the candidate process and could lead a
+    // later `release activate` recovery into a split-brain commit.
+    if (fence.phase !== "fenced") {
+        removeCandidateDiscovery(home);
+        return {
+            outcome: "aborted",
+            reason: `Handover fence is in phase '${fence.phase}', not 'fenced'; the handover was rolled back.`
+        };
+    }
+    // Publish the candidate identity so the activator can read back build ID,
+    // backend, and worker state before committing the handover.
+    writeCandidateDiscovery(home, { pid: process.pid, processStartIdentity: startIdentity });
+    writeRuntimeIdentity(home, buildRuntimeIdentityReceipt({
+        home,
+        release,
+        storageBackend: resolveTaskStoreBackendForHome(home, environment),
+        workerEnabled: resolveStoreWorkerEnabledForHome(home, environment),
+        processStartIdentity: startIdentity,
+        mode: "candidate",
+        dualOwner: false
+    }));
+    advanceFence(home, fence, "candidate-ready", now().toISOString());
+    const committedAt = Date.now();
+    let dualOwnerReported = false;
+    for (;;) {
+        const current = readHandoverFence(home);
+        if (current === null || current.handoverId !== handoverId) {
+            removeCandidateDiscovery(home);
+            return {
+                outcome: "aborted",
+                reason: "Handover fence disappeared; the handover was rolled back."
+            };
+        }
+        if (current.phase === "rolled-back") {
+            removeCandidateDiscovery(home);
+            return {
+                outcome: "aborted",
+                reason: "Handover was rolled back while the candidate was polling."
+            };
+        }
+        const oldDead = !isOwnerLive(current.old);
+        const pointer = readActiveReleasePointer(home);
+        const pointerSwitched = pointer !== null && pointer.releaseId === current.toReleaseId;
+        if (oldDead && pointerSwitched) {
+            return await promote(home, current, environment, now);
+        }
+        if (current.phase === "committed"
+            && !oldDead
+            && Date.now() - committedAt > dualOwnerGraceMs
+            && !dualOwnerReported) {
+            // The old Controller was told to exit but is still live. Stay read-only
+            // and make the dual-owner condition visible; never write concurrently.
+            dualOwnerReported = true;
+            writeRuntimeIdentity(home, buildRuntimeIdentityReceipt({
+                home,
+                release,
+                storageBackend: resolveTaskStoreBackendForHome(home, environment),
+                workerEnabled: resolveStoreWorkerEnabledForHome(home, environment),
+                processStartIdentity: startIdentity,
+                mode: "candidate",
+                dualOwner: true
+            }));
+        }
+        await delay(pollIntervalMs);
+    }
+}
+async function promote(home, fence, environment, now) {
+    removeCandidateDiscovery(home);
+    const controller = await startFileTaskControllerRuntime(home, { environment });
+    // The promoted Controller server has already published its primary identity
+    // receipt. Complete the handover record and release the fence.
+    writeHandoverReceipt(home, Object.freeze({
+        schemaVersion: 1,
+        handoverId: fence.handoverId,
+        outcome: "completed",
+        old: fence.old,
+        candidate: fence.candidate,
+        previousReleaseId: fence.fromReleaseId,
+        activatedReleaseId: fence.toReleaseId,
+        startedAt: fence.createdAt,
+        completedAt: now().toISOString()
+    }));
+    removeHandoverFence(home);
+    const stop = () => {
+        void controller.close().catch(() => undefined);
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    try {
+        await controller.closed;
+    }
+    finally {
+        process.removeListener("SIGINT", stop);
+        process.removeListener("SIGTERM", stop);
+    }
+    return { outcome: "promoted", reason: "Candidate promoted and Controller closed." };
+}
+function advanceFence(home, fence, phase, updatedAt) {
+    writeHandoverFence(home, Object.freeze({ ...fence, phase, updatedAt }));
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/controller/jobClient.js

@@ -0,0 +1,102 @@
+import { resolveJobCaller } from "../commands/taskActor.js";
+import { callFileTaskController } from "./clientRuntime.js";
+export async function startDurableJob(home, params, clientOptions = {}) {
+    // rr6/f2: Route through callFileTaskController so an Integration-issued
+    // job.start starts a stopped per-Home Controller on demand, mirroring the
+    // `job start` CLI. A bare callController only reads discovery and fails.
+    const result = await callFileTaskController(home, "job.start", params, clientOptions);
+    return parseStartResult(result);
+}
+export async function getDurableJob(home, taskId, jobId, clientOptions = {}) {
+    const result = await callFileTaskController(home, "job.get", { taskId, jobId }, clientOptions);
+    return parseJobResult(result);
+}
+export async function acknowledgeDurableJob(home, taskId, jobId, caller, clientOptions = {}) {
+    const result = await callFileTaskController(home, "job.acknowledge", {
+        taskId,
+        jobId,
+        caller
+    }, clientOptions);
+    if (typeof result !== "object" || result === null || Array.isArray(result)
+        || typeof result.acknowledged !== "boolean") {
+        throw new Error("Controller job.acknowledge returned an invalid result.");
+    }
+    return {
+        job: parseJobResult(result),
+        acknowledged: result.acknowledged
+    };
+}
+export async function cancelDurableJob(home, taskId, jobId, caller, clientOptions = {}) {
+    const result = await callFileTaskController(home, "job.cancel", { taskId, jobId, caller }, clientOptions);
+    if (typeof result !== "object" || result === null || Array.isArray(result)
+        || typeof result.cancelRequested !== "boolean") {
+        throw new Error("Controller job.cancel returned an invalid result.");
+    }
+    return {
+        job: parseJobResult(result),
+        cancelRequested: result.cancelRequested
+    };
+}
+function parseStartResult(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)
+        || typeof value.created !== "boolean") {
+        throw new Error("Controller job.start returned an invalid result.");
+    }
+    return {
+        job: parseJobResult(value),
+        created: value.created
+    };
+}
+function parseJobResult(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("Controller returned an invalid DurableJob result.");
+    }
+    const job = value.job;
+    if (typeof job !== "object" || job === null || Array.isArray(job)) {
+        throw new Error("Controller returned an invalid DurableJob record.");
+    }
+    return job;
+}
+/**
+ * Production IntegrationJobPort: Integration checks ask the Controller socket
+ * for their DurableJob. The Controller owns the detached runner, so a Leader
+ * exit or Session replacement never kills a running check.
+ *
+ * rr6/f2: The port routes through callFileTaskController, so an Integration
+ * operation that issues a job.* RPC (start/continue/abort, and job-backed Task
+ * completion) starts a stopped per-Home Controller on demand. Read-only
+ * list/show paths do not use this port and stay lean.
+ */
+export function createControllerIntegrationJobPort(home, clientOptions = {}) {
+    const { store, ...controllerOptions } = clientOptions;
+    return {
+        async startCheckJob(input) {
+            const owner = {
+                kind: "integration-attempt",
+                integrationAttemptId: input.integrationId
+            };
+            // rr8/rr12: Bind the Integration-issued job to the caller's managed
+            // identity. A user-scope caller carries a verified Leader assertion.
+            const caller = resolveJobCaller(controllerOptions.environment, input.taskId, store);
+            const { job } = await startDurableJob(home, {
+                taskId: input.taskId,
+                owner,
+                projectId: input.projectId,
+                head: input.head,
+                workspace: input.workspace,
+                env: input.env,
+                steps: input.steps,
+                caller
+            }, controllerOptions);
+            return job;
+        },
+        async getJob(taskId, jobId) {
+            return getDurableJob(home, taskId, jobId, controllerOptions);
+        },
+        async cancelJob(taskId, jobId) {
+            // rr8/rr12: Bind the cancel request to the caller's managed identity.
+            const caller = resolveJobCaller(controllerOptions.environment, taskId, store);
+            await cancelDurableJob(home, taskId, jobId, caller, controllerOptions);
+        }
+    };
+}