@astrosheep/keiyaku 2.9.11 → 2.9.13

package/build/core/projection/generation/model.js

@@ -1,6 +1,13 @@
-import { GENERATION_VERDICT_STATES, } from "../projection-life-protocol.js";
 import { OutcomeErrorValidationError, parseCurrentOutcomeError, } from "../../../agents/harness/index.js";
-export { GENERATION_VERDICT_STATES };
+export const GENERATION_VERDICT_STATES = [
+    "completed",
+    "failed",
+    "launch-failed",
+    "lost-runner",
+    "dismissed",
+    "interrupted",
+    "killed",
+];
 export const VERDICTS = new Set(GENERATION_VERDICT_STATES);
 export class ProjectionGenerationStoreError extends Error {
     code = "PROJECTION_GENERATION_STORE_ERROR";
@@ -12,17 +19,17 @@ export class ProjectionGenerationStoreError extends Error {
         this.observation = options?.observation ?? "unknown";
     }
 }
-export function isIncompatibleProjectionGenerationStoreError(error) {
-    return error instanceof ProjectionGenerationStoreError
-        && error.observation === "incompatible";
-}
-export function isPlainObject(value) {
+function isPlainObject(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value))
         return false;
     const prototype = Object.getPrototypeOf(value);
     return prototype === Object.prototype || prototype === null;
 }
-export function assertJsonValue(value, location, ancestors) {
+export function isIncompatibleProjectionGenerationStoreError(error) {
+    return error instanceof ProjectionGenerationStoreError
+        && error.observation === "incompatible";
+}
+export function assertJsonValue(value, location, ancestors = new Set()) {
     if (value === null || typeof value === "string" || typeof value === "boolean")
         return;
     if (typeof value === "number") {
@@ -30,9 +37,8 @@ export function assertJsonValue(value, location, ancestors) {
             throw new ProjectionGenerationStoreError(`${location} contains a non-finite number`);
         return;
     }
-    if (typeof value !== "object") {
+    if (typeof value !== "object")
         throw new ProjectionGenerationStoreError(`${location} contains a non-JSON value`);
-    }
     if (ancestors.has(value))
         throw new ProjectionGenerationStoreError(`${location} contains a cycle`);
     ancestors.add(value);
@@ -43,9 +49,8 @@ export function assertJsonValue(value, location, ancestors) {
         }
         if (!isPlainObject(value))
             throw new ProjectionGenerationStoreError(`${location} must contain only plain JSON objects`);
-        for (const [key, item] of Object.entries(value)) {
+        for (const [key, item] of Object.entries(value))
             assertJsonValue(item, `${location}.${key}`, ancestors);
-        }
     }
     finally {
         ancestors.delete(value);
@@ -54,7 +59,7 @@ export function assertJsonValue(value, location, ancestors) {
 export function cloneFacts(value, location) {
     if (!isPlainObject(value))
         throw new ProjectionGenerationStoreError(`${location} must be a JSON object`);
-    assertJsonValue(value, location, new Set());
+    assertJsonValue(value, location);
     return JSON.parse(JSON.stringify(value));
 }
 export function assertExecutionId(executionId) {
@@ -247,7 +252,7 @@ export function validateHistory(records) {
 export function extractTerminalTimestamp(facts) {
     if (!facts)
         return undefined;
-    for (const key of ["completedAt", "failedAt", "dismissedAt", "killedAt", "terminalAt"]) {
+    for (const key of ["terminalAt", "completedAt", "failedAt", "dismissedAt", "killedAt"]) {
         const value = facts[key];
         if (typeof value === "string" && Number.isFinite(Date.parse(value)))
             return value;

package/build/core/projection/generation/projection-generation-continuation.js

@@ -52,7 +52,7 @@ function readContinuationFromDatabase(database, limit = 10) {
 /** One heart snapshot owns generation selection and all continuation facts. */
 export function readProjectionGenerationContinuationSnapshot(projectionDirectory, limit = 10) {
     return withGenerationReadSnapshot(projectionDirectory, (database) => {
-        const { records, current } = readValidatedHistory(database);
+        const { records, current } = readValidatedHistory(database, true);
         const continuation = readContinuationFromDatabase(database, limit);
         return {
             records,

package/build/core/projection/generation/projection-generation-doorbell.js

@@ -0,0 +1,88 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as net from "node:net";
+const CONNECT_TIMEOUT_MS = 50;
+const POSIX_PREFIX = "/tmp/keiyaku-doorbell-";
+const WINDOWS_PREFIX = "\\\\.\\pipe\\keiyaku-doorbell-";
+function endpointDigest(identity, executionId) {
+    return createHash("sha256")
+        .update(JSON.stringify(identity))
+        .update("\0")
+        .update(executionId)
+        .digest("hex");
+}
+/** A bounded, deterministic endpoint with no projection-directory pathname. */
+export function projectionGenerationDoorbellAddress(identity, executionId) {
+    const digest = endpointDigest(identity, executionId);
+    return process.platform === "win32"
+        ? `${WINDOWS_PREFIX}${digest}`
+        : `${POSIX_PREFIX}${digest}.sock`;
+}
+function removeStalePosixSocket(address) {
+    try {
+        const stat = fs.lstatSync(address);
+        if (!stat.isSocket())
+            throw new Error(`doorbell endpoint is not a socket: ${address}`);
+        fs.unlinkSync(address);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+}
+function listen(server, address) {
+    return new Promise((resolve, reject) => {
+        const onError = (error) => {
+            server.off("listening", onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            server.off("error", onError);
+            resolve();
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        server.listen(address);
+    });
+}
+export async function openProjectionGenerationDoorbell(input) {
+    const address = projectionGenerationDoorbellAddress(input.identity, input.executionId);
+    if (process.platform !== "win32")
+        removeStalePosixSocket(address);
+    const server = net.createServer((socket) => {
+        socket.destroy();
+        input.onRing();
+    });
+    await listen(server, address);
+    return {
+        address,
+        close: async () => {
+            await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+            if (process.platform !== "win32") {
+                try {
+                    fs.unlinkSync(address);
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT")
+                        throw error;
+                }
+            }
+        },
+    };
+}
+/**
+ * Best-effort wake only. Connection result is deliberately discarded: heart
+ * durability and leash evidence remain the only product/liveness authority.
+ */
+export function ringProjectionGenerationDoorbell(identity, executionId) {
+    const socket = net.createConnection(projectionGenerationDoorbellAddress(identity, executionId));
+    const timeout = setTimeout(() => socket.destroy(), CONNECT_TIMEOUT_MS);
+    timeout.unref?.();
+    const finish = () => {
+        clearTimeout(timeout);
+        socket.destroy();
+    };
+    socket.once("connect", finish);
+    socket.once("error", finish);
+}

package/build/core/projection/generation/projection-generation-execution.js

@@ -20,6 +20,27 @@ function requireString(value, field) {
 function optionalString(value, field) {
     return value === undefined ? undefined : requireString(value, field);
 }
+function optionalCarrier(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isObject(value) || value.path !== ".keiyaku/KEIYAKU.md" || !isObject(value.identity)) {
+        throw new Error("generation launch carrier must be a verified carrier coordinate");
+    }
+    const { identity } = value;
+    if (typeof identity.contractId !== "string" || identity.contractId.trim() === ""
+        || typeof identity.contractHead !== "string" || identity.contractHead.trim() === ""
+        || typeof identity.bodyDigest !== "string" || identity.bodyDigest.trim() === "") {
+        throw new Error("generation launch carrier identity must contain non-blank contractId, contractHead, and bodyDigest");
+    }
+    return {
+        path: ".keiyaku/KEIYAKU.md",
+        identity: {
+            contractId: identity.contractId,
+            contractHead: identity.contractHead,
+            bodyDigest: identity.bodyDigest,
+        },
+    };
+}
 function requirePositiveSafeInteger(value, field) {
     if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
         throw new Error(`generation launch ${field} must be a positive safe integer`);
@@ -54,6 +75,7 @@ function parseLaunchInputs(launch) {
     const context = optionalString(raw.context, "context");
     const resumePath = optionalString(raw.resumePath, "resumePath");
     const sourceArtifactId = optionalString(raw.sourceArtifactId, "sourceArtifactId");
+    const carrier = optionalCarrier(raw.carrier);
     return {
         prompt: requireString(raw.prompt, "prompt"),
         cwd: requireString(raw.cwd, "cwd"),
@@ -69,6 +91,7 @@ function parseLaunchInputs(launch) {
         ...(raw.session ? { session: raw.session } : {}),
         ...(resumePath ? { resumePath } : {}),
         ...(sourceArtifactId ? { sourceArtifactId } : {}),
+        ...(carrier ? { carrier } : {}),
     };
 }
 function persistenceError(error) {
@@ -161,6 +184,7 @@ export function prepareProjectionGenerationExecution(projectionDirectory, launch
         idleTimeoutMs: inputs.idleTimeoutMs,
         executionTimeoutMs: inputs.executionTimeoutMs,
         initialTurn: maximumValidEnvelopeTurn(projectionDirectory),
+        carrier: inputs.carrier,
     }), providerLoaderPorts);
     const observerController = createProjectionExecutionObserver({
         projectionDirectory,

package/build/core/projection/generation/projection-generation-identity.js

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import { ProjectionStateError } from "../../atomic-publish.js";
 import { createUlid } from "../../ids.js";
 const EXECUTION_ID_PATTERN = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+export const PROJECTION_RUNNER_LEASE_FILE = "leash";
 export function createProjectionExecutionId(nowMs = Date.now()) {
     return createUlid(nowMs, [...randomBytes(10)]);
 }
@@ -15,3 +16,6 @@ export function executionStdioLogPath(projectionDirectory, executionId) {
     assertProjectionExecutionId(executionId);
     return path.join(projectionDirectory, `${executionId}.stdio.log`);
 }
+export function projectionRunnerLeasePath(projectionDirectory) {
+    return path.join(projectionDirectory, PROJECTION_RUNNER_LEASE_FILE);
+}

package/build/core/projection/generation/projection-generation-launcher.js

@@ -1,9 +1,11 @@
 import { setTimeout as delay } from "node:timers/promises";
+import { PROJECTION_ADOPTION_TIMEOUT_DEFAULT_MS } from "../../../config/settings/knobs.js";
 import { openProjectionGenerationStore } from "./store.js";
-import { spawnProjectionGenerationRunner, } from "./projection-generation-process.js";
-import { acquireProjectionRunnerLock, observeProjectionRunnerLock, } from "../projection-runner-lock.js";
-export const PROJECTION_ADOPTION_TIMEOUT_MS = 4_000;
-export const PROJECTION_ADOPTION_POLL_MS = 20;
+import { prepareProjectionGenerationRunner, } from "./projection-generation-process.js";
+import { acquireRunnerLease, observeRunnerLease, } from "../../run-control/runner-lease.js";
+import { openDetachedLeaseBootstrap } from "../../run-control/detached-lease-bootstrap.js";
+import { projectionRunnerLeasePath } from "./projection-generation-identity.js";
+const PROJECTION_ADOPTION_POLL_MS = 20;
 function errorDetail(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -21,86 +23,39 @@ function recordDeadStartup(projectionDirectory, executionId, detail, stage, term
         store.close();
     }
 }
-function observeBootstrapMessages(child, executionId) {
-    const seen = new Set();
-    const waiters = new Map();
-    let failure;
-    const onMessage = (value) => {
-        const message = value;
-        if (message.executionId !== executionId)
-            return;
-        if (message.kind !== "leash-inherited" && message.kind !== "leash-acquired")
-            return;
-        seen.add(message.kind);
-        const waiter = waiters.get(message.kind);
-        if (waiter) {
-            waiter.resolve();
-            waiters.delete(message.kind);
-        }
-    };
-    const onError = (error) => {
-        failure = error;
-        for (const waiter of waiters.values())
-            waiter.reject(error);
-        waiters.clear();
-    };
-    const onExit = () => onError(new Error("runner exited during bootstrap"));
-    child.on("message", onMessage);
-    child.on("error", onError);
-    child.on("exit", onExit);
-    return {
-        waitFor(kind) {
-            if (seen.has(kind))
-                return Promise.resolve();
-            if (failure)
-                return Promise.reject(failure);
-            return new Promise((resolve, reject) => {
-                const timer = setTimeout(() => {
-                    waiters.delete(kind);
-                    reject(failure ?? new Error(`runner did not report ${kind} before startup timeout`));
-                }, PROJECTION_ADOPTION_TIMEOUT_MS);
-                waiters.set(kind, {
-                    resolve: () => {
-                        clearTimeout(timer);
-                        waiters.delete(kind);
-                        resolve();
-                    },
-                    reject: (error) => {
-                        clearTimeout(timer);
-                        waiters.delete(kind);
-                        reject(error);
-                    },
-                });
-            });
-        },
-        close() {
-            child.off("message", onMessage);
-            child.off("error", onError);
-            child.off("exit", onExit);
-        },
-    };
-}
-function sendBootstrapCommand(child, command) {
-    return new Promise((resolve, reject) => {
-        if (!child.send || !child.connected) {
-            reject(new Error("runner bootstrap channel is unavailable"));
-            return;
-        }
-        child.send(command, (error) => error ? reject(error) : resolve());
-    });
+const ADOPTION_TIMEOUT_DETAIL = "runner did not adopt before projection adoption timeout";
+async function failAdoptionDeadline(projectionDirectory, executionId, child, now, terminateChild, detail = ADOPTION_TIMEOUT_DETAIL) {
+    try {
+        await terminateChild(child);
+    }
+    catch (error) {
+        return { status: "failed", cause: "adoption", detail: `${detail}; runner termination could not be verified: ${errorDetail(error)}` };
+    }
+    const lease = observeRunnerLease(projectionRunnerLeasePath(projectionDirectory));
+    if (lease.state !== "released")
+        return {
+            status: "failed",
+            cause: "adoption",
+            detail: `${detail}; runner lock ${lease.state === "held" ? "remained held" : `could not be verified: ${lease.detail}`}`,
+        };
+    recordDeadStartup(projectionDirectory, executionId, detail, "adoption", new Date(now()).toISOString());
+    return { status: "failed", cause: "adoption", detail };
 }
 /** Spawn one committed launch and return only after its exact adoption row. */
 export async function startProjectionGeneration(projectionDirectory, executionId, dependencies = {}) {
     const now = dependencies.now ?? Date.now;
     const sleep = dependencies.sleep ?? ((milliseconds) => delay(milliseconds));
-    const launcherAcquiredOwnership = dependencies.launchOwnership === undefined;
+    const adoptionTimeoutMs = dependencies.adoptionTimeoutMs ?? PROJECTION_ADOPTION_TIMEOUT_DEFAULT_MS;
+    // Bootstrap IPC and durable adoption are one launch operation, not retries
+    // with independent startup allowances.
+    const deadline = now() + adoptionTimeoutMs;
     let launchOwnership;
     try {
         launchOwnership = dependencies.launchOwnership
-            ?? acquireProjectionRunnerLock(projectionDirectory);
+            ?? acquireRunnerLease(projectionRunnerLeasePath(projectionDirectory));
     }
     catch (error) {
-        if (observeProjectionRunnerLock(projectionDirectory).state === "held") {
+        if (observeRunnerLease(projectionRunnerLeasePath(projectionDirectory)).state === "held") {
             return { status: "pending" };
         }
         return {
@@ -109,11 +64,9 @@ export async function startProjectionGeneration(projectionDirectory, executionId
             detail: `runner construction failed: ${errorDetail(error)}`,
         };
     }
-    let launchCommitted = false;
-    let childPromoted = false;
-    let child;
+    let prepared;
     try {
-        child = spawnProjectionGenerationRunner(projectionDirectory, executionId, dependencies);
+        prepared = prepareProjectionGenerationRunner(projectionDirectory, executionId, dependencies);
     }
     catch (error) {
         const detail = `runner spawn failed: ${errorDetail(error)}`;
@@ -121,60 +74,48 @@ export async function startProjectionGeneration(projectionDirectory, executionId
         launchOwnership.close();
         return { status: "failed", cause: "spawn", detail };
     }
-    const bootstrap = observeBootstrapMessages(child, executionId);
+    const opened = await openDetachedLeaseBootstrap({
+        coordinate: executionId,
+        leasePath: projectionRunnerLeasePath(projectionDirectory),
+        parentLease: launchOwnership,
+        launch: prepared.launch,
+        deadline,
+        now,
+        spawn: dependencies.spawn,
+        terminate: dependencies.terminateChild,
+    });
+    prepared.close();
+    if (opened.status === "failed") {
+        const detail = opened.stage === "spawn" ? `runner spawn failed: ${opened.detail}` : `runner construction failed: ${opened.detail}`;
+        recordDeadStartup(projectionDirectory, executionId, detail, opened.stage === "spawn" ? "spawn" : "adoption", new Date(now()).toISOString());
+        return { status: "failed", cause: opened.stage === "spawn" ? "spawn" : "adoption", detail };
+    }
+    let committed = true;
+    let commitFailure;
     try {
-        await bootstrap.waitFor("leash-inherited");
-        if (dependencies.commitLaunch && !dependencies.commitLaunch()) {
-            await sendBootstrapCommand(child, { kind: "launch-rejected", executionId });
-            if (launcherAcquiredOwnership)
-                launchOwnership.close();
-            return { status: "failed", cause: "adoption", detail: "generation launch transaction was rejected" };
-        }
-        launchCommitted = true;
-        launchOwnership.releaseReservationForTransfer();
-        await sendBootstrapCommand(child, { kind: "promote-leash", executionId });
-        await bootstrap.waitFor("leash-acquired");
-        childPromoted = true;
-        await sendBootstrapCommand(child, { kind: "launch-committed", executionId });
-        try {
-            launchOwnership.close();
-        }
-        catch {
-            // The promoted child owns lifecycle truth; parent guard cleanup is diagnostic only.
-        }
+        committed = dependencies.commitLaunch?.() ?? true;
     }
     catch (error) {
-        void sendBootstrapCommand(child, { kind: "launch-rejected", executionId }).catch(() => { });
-        if (childPromoted) {
-            try {
-                launchOwnership.close();
-            }
-            catch { }
-            return { status: "pending", child };
-        }
-        if (!launchCommitted) {
-            launchOwnership.close();
-            return { status: "failed", cause: "adoption", detail: `runner construction failed: ${errorDetail(error)}` };
-        }
-        try {
-            launchOwnership.reclaimReservation();
-        }
-        catch {
-            launchOwnership.close();
-            return { status: "pending", child };
-        }
-        try {
-            recordDeadStartup(projectionDirectory, executionId, `runner construction failed: ${errorDetail(error)}`, "adoption", new Date(now()).toISOString());
-        }
-        finally {
-            launchOwnership.close();
-        }
-        return { status: "failed", cause: "adoption", detail: `runner construction failed: ${errorDetail(error)}` };
+        committed = false;
+        commitFailure = error;
     }
-    finally {
-        bootstrap.close();
+    if (!committed) {
+        const rejected = await opened.bootstrap.reject();
+        return {
+            status: "failed",
+            cause: "adoption",
+            detail: rejected.status === "failed"
+                ? rejected.detail
+                : commitFailure ? `generation launch transaction failed: ${errorDetail(commitFailure)}` : "generation launch transaction was rejected",
+        };
     }
-    const deadline = now() + PROJECTION_ADOPTION_TIMEOUT_MS;
+    const authorized = await opened.bootstrap.authorize();
+    if (authorized.status === "failed") {
+        const detail = now() >= deadline ? ADOPTION_TIMEOUT_DETAIL : `runner construction failed: ${authorized.detail}`;
+        recordDeadStartup(projectionDirectory, executionId, detail, "adoption", new Date(now()).toISOString());
+        return { status: "failed", cause: "adoption", detail };
+    }
+    const child = authorized.child;
     for (;;) {
         const observedAt = now();
         const store = openProjectionGenerationStore(projectionDirectory);
@@ -202,19 +143,12 @@ export async function startProjectionGeneration(projectionDirectory, executionId
         finally {
             store.close();
         }
+        if (observeRunnerLease(projectionRunnerLeasePath(projectionDirectory)).state === "held") {
+            return { status: "adopted", child };
+        }
         if (observedAt >= deadline)
             break;
         await sleep(Math.max(0, Math.min(PROJECTION_ADOPTION_POLL_MS, deadline - observedAt)));
     }
-    const store = openProjectionGenerationStore(projectionDirectory);
-    try {
-        const current = store.readCurrentGeneration();
-        if (current?.launch.executionId === executionId && current.adoption) {
-            return { status: "adopted", child };
-        }
-    }
-    finally {
-        store.close();
-    }
-    return { status: "pending", child };
+    return failAdoptionDeadline(projectionDirectory, executionId, child, now, dependencies.terminateChild ?? (await import("../../run-control/process-tree.js")).terminateProcessGroup);
 }

package/build/core/projection/generation/projection-generation-process.js

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { spawn as nodeSpawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { RUN_CONTROL_BOOTSTRAP_ENV } from "../../run-control/index.js";
 import { executionStdioLogPath } from "./projection-generation-identity.js";
 const MODULE_FILE = fileURLToPath(import.meta.url);
 // Lives at src/core/projection/generation/ — four levels up is the package root.
@@ -17,9 +17,7 @@ export function projectionGenerationRunnerArgv(projectionDirectory, executionId)
         executionId,
     ];
 }
-export const PROJECTION_RUNNER_BOOTSTRAP_ENV = "KEIYAKU_PROJECTION_RUNNER_BOOTSTRAP";
-export function spawnProjectionGenerationRunner(projectionDirectory, executionId, dependencies = {}) {
-    const spawn = dependencies.spawn ?? nodeSpawn;
+export function prepareProjectionGenerationRunner(projectionDirectory, executionId, dependencies = {}) {
     const openSync = dependencies.openSync ?? fs.openSync;
     const closeSync = dependencies.closeSync ?? fs.closeSync;
     const absoluteDirectory = path.resolve(projectionDirectory);
@@ -29,18 +27,21 @@ export function spawnProjectionGenerationRunner(projectionDirectory, executionId
     const logPath = executionStdioLogPath(absoluteDirectory, executionId);
     const logFd = openSync(logPath, "a");
     try {
-        const child = spawn(command, args, {
-            detached: true,
-            stdio: ["ignore", logFd, logFd, "ipc"],
-            env: { ...process.env, [PROJECTION_RUNNER_BOOTSTRAP_ENV]: "1" },
-        });
-        if (child.pid === undefined) {
-            throw new Error("projection runner did not expose a process id");
-        }
-        child.unref();
-        return child;
+        return {
+            launch: {
+                command,
+                args,
+                unref: true,
+                options: {
+                    stdio: ["ignore", logFd, logFd, "ipc"],
+                    env: { ...process.env, [RUN_CONTROL_BOOTSTRAP_ENV]: "1" },
+                },
+            },
+            close: () => closeSync(logFd),
+        };
     }
-    finally {
+    catch (error) {
         closeSync(logFd);
+        throw error;
     }
 }