@astrosheep/keiyaku 2.9.6 → 2.9.7

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

@@ -4,7 +4,7 @@ import { DatabaseSync } from "node:sqlite";
 import { configureHeartBusyTimeout } from "../heart.js";
 import { ProjectionGenerationStoreError, parseStoredRow, validateHistory, } from "./model.js";
 export const PROJECTION_GENERATION_STORE_FILE = "heart";
-export const PROJECTION_GENERATION_SCHEMA_VERSION = 2;
+export const PROJECTION_GENERATION_SCHEMA_VERSION = 3;
 const SCHEMA_TABLE_SQL = `
   CREATE TABLE generation_schema (
     singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
@@ -14,7 +14,7 @@ const SCHEMA_TABLE_SQL = `
 const RECORD_TABLE_SQL = `
   CREATE TABLE generation_records (
     seq INTEGER PRIMARY KEY CHECK (seq > 0),
-    kind TEXT NOT NULL CHECK (kind IN ('launch', 'adoption', 'kill-intent', 'verdict')),
+    kind TEXT NOT NULL CHECK (kind IN ('launch', 'adoption', 'kill-intent', 'interrupt-intent', 'verdict')),
     execution_id TEXT NOT NULL CHECK (length(trim(execution_id)) > 0),
     facts_json TEXT NOT NULL CHECK (json_valid(facts_json))
   ) STRICT
@@ -250,6 +250,25 @@ export function openReadOnlyDatabase(projectionDirectory) {
         throw projectionGenerationStoreReadError(databasePath, error);
     }
 }
+/** Read the validated heart through one consistent SQLite snapshot. */
+export function withGenerationReadSnapshot(projectionDirectory, read) {
+    const { database } = openReadOnlyDatabase(projectionDirectory);
+    try {
+        database.exec("BEGIN");
+        try {
+            const result = read(database);
+            database.exec("COMMIT");
+            return result;
+        }
+        catch (error) {
+            rollbackQuietly(database);
+            throw error;
+        }
+    }
+    finally {
+        closeDatabase(database);
+    }
+}
 export function assertDatabaseOpen(database) {
     if (closedDatabases.has(database))
         throw new ProjectionGenerationStoreError("projection generation store is closed");

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

@@ -133,6 +133,16 @@ export function validateKillIntentFacts(value, location) {
         throw new ProjectionGenerationStoreError(`${location}.state is reserved for verdict records`);
     return facts;
 }
+export function validateInterruptIntentFacts(value, location) {
+    const facts = cloneFacts(value, location);
+    facts.interruptedAt = assertIsoTimestamp(facts.interruptedAt, `${location}.interruptedAt`);
+    if ("operatorAction" in facts) {
+        throw new ProjectionGenerationStoreError(`${location}.operatorAction is not part of interrupt-intent`);
+    }
+    if ("state" in facts)
+        throw new ProjectionGenerationStoreError(`${location}.state is reserved for verdict records`);
+    return facts;
+}
 export function validateVerdictFacts(value, location) {
     const facts = cloneFacts(value, location);
     if (typeof facts.state !== "string" || !VERDICTS.has(facts.state)) {
@@ -182,6 +192,7 @@ export function parseStoredRow(row) {
     if (row.kind !== "launch"
         && row.kind !== "adoption"
         && row.kind !== "kill-intent"
+        && row.kind !== "interrupt-intent"
         && row.kind !== "verdict") {
         throw new ProjectionGenerationStoreError(`generation row ${seq} has unknown kind '${row.kind}'`);
     }
@@ -200,7 +211,9 @@ export function parseStoredRow(row) {
             ? validateAdoptionFacts(decoded, location)
             : row.kind === "kill-intent"
                 ? validateKillIntentFacts(decoded, location)
-                : validateVerdictFacts(decoded, location);
+                : row.kind === "interrupt-intent"
+                    ? validateInterruptIntentFacts(decoded, location)
+                    : validateVerdictFacts(decoded, location);
     return { seq, kind: row.kind, executionId, facts };
 }
 export function validateHistory(records) {
@@ -237,13 +250,21 @@ export function validateHistory(records) {
             continue;
         }
         if (record.kind === "kill-intent") {
-            if (current.killIntent)
-                throw new ProjectionGenerationStoreError(`generation row ${record.seq} duplicates kill-intent`);
+            if (current.killIntent || current.interruptIntent)
+                throw new ProjectionGenerationStoreError(`generation row ${record.seq} duplicates generation stop intent`);
             if (current.verdict)
                 throw new ProjectionGenerationStoreError(`generation row ${record.seq} records kill-intent after verdict`);
             current.killIntent = record;
             continue;
         }
+        if (record.kind === "interrupt-intent") {
+            if (current.killIntent || current.interruptIntent)
+                throw new ProjectionGenerationStoreError(`generation row ${record.seq} duplicates generation stop intent`);
+            if (current.verdict)
+                throw new ProjectionGenerationStoreError(`generation row ${record.seq} records interrupt-intent after verdict`);
+            current.interruptIntent = record;
+            continue;
+        }
         if (current.verdict)
             throw new ProjectionGenerationStoreError(`generation row ${record.seq} duplicates verdict`);
         current.verdict = record;

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

@@ -1,22 +1,87 @@
 import { ProjectionStateError } from "../../atomic-publish.js";
 import { applySnapshotEffort, parseResolvedAkumaLaunchSnapshot, } from "../../../agents/launch-snapshot/model.js";
-import { listTellIds, readTellOriginal, readTellSubmitted, } from "../projection-core.js";
-export function snapshotPendingTells(projectionDirectory) {
-    const pending = ["inbox", "inflight", "submitted"]
-        .flatMap((layer) => listTellIds(projectionDirectory, layer)
-        .map((tellId) => ({ layer, tellId })))
-        .sort((left, right) => left.tellId.localeCompare(right.tellId));
+import { listTellMetadataFromDatabase, readPendingTellWindowFromDatabase, } from "../tell/store.js";
+import { PENDING_PROJECTION_TELL_STATES } from "../tell/model.js";
+import { readValidatedHistory, withGenerationReadSnapshot } from "./database.js";
+function retainedFenceFor(current) {
+    return current?.verdict?.facts.state === "launch-failed"
+        ? current.launch.facts.tellFence ?? []
+        : [];
+}
+function interruptedForReplay(current) {
+    return current?.verdict?.facts.state === "interrupted";
+}
+function snapshotTells(database, layers, admit) {
+    const pending = listTellMetadataFromDatabase(database, layers)
+        .filter((item) => admit?.({
+        layer: item.state,
+        tellId: item.tellId,
+        ...(item.executionId ? { executionId: item.executionId } : {}),
+    }) ?? true);
     const effort = pending.reduce((selected, item) => {
-        const tell = item.layer === "submitted"
-            ? readTellSubmitted(projectionDirectory, item.tellId)
-            : readTellOriginal(projectionDirectory, item.layer, item.tellId);
-        return tell.effort ?? selected;
+        return item.effort ?? selected;
     }, undefined);
     return {
         tellIds: pending.map((item) => item.tellId),
         ...(effort ? { effort } : {}),
     };
 }
+/** Ordinary completed-generation handoff retains only tells not yet delivered. */
+export function snapshotPendingTells(projectionDirectory) {
+    return withGenerationReadSnapshot(projectionDirectory, (database) => snapshotTells(database, PENDING_PROJECTION_TELL_STATES));
+}
+/** Interrupted generations replay pending mail and their own delivered tells. */
+export function snapshotInterruptTells(projectionDirectory, executionId) {
+    return withGenerationReadSnapshot(projectionDirectory, (database) => snapshotTells(database, [...PENDING_PROJECTION_TELL_STATES, "delivered"], (item) => item.layer !== "delivered" || item.executionId === executionId));
+}
+/** Retry ordinary pending mail plus exactly the durable fence of a failed launch. */
+export function snapshotRetainedSuccessorTells(projectionDirectory, retainedFence) {
+    const retained = new Set(retainedFence);
+    return withGenerationReadSnapshot(projectionDirectory, (database) => snapshotTells(database, [...PENDING_PROJECTION_TELL_STATES, "delivered"], ({ layer, tellId }) => layer !== "delivered" || retained.has(tellId)));
+}
+/** Build the durable successor fence only after continuation is admitted. */
+export function snapshotProjectionContinuationTells(projectionDirectory, current) {
+    const snapshot = readProjectionGenerationContinuationSnapshot(projectionDirectory, 0);
+    if (snapshot.current?.launch.executionId !== current?.launch.executionId) {
+        throw new ProjectionStateError("projection generation changed while selecting continuation tells");
+    }
+    return snapshot.successor;
+}
+function readContinuationFromDatabase(database, current, limit = 10) {
+    const tells = readPendingTellWindowFromDatabase(database, limit);
+    const retainedFence = retainedFenceFor(current);
+    const successor = interruptedForReplay(current)
+        ? snapshotTells(database, [...PENDING_PROJECTION_TELL_STATES, "delivered"], (item) => item.layer !== "delivered" || item.executionId === current.launch.executionId)
+        : retainedFence.length > 0
+            ? snapshotTells(database, [...PENDING_PROJECTION_TELL_STATES, "delivered"], ({ layer, tellId }) => layer !== "delivered" || retainedFence.includes(tellId))
+            : snapshotTells(database, PENDING_PROJECTION_TELL_STATES);
+    return {
+        tells,
+        successor,
+        requiresWake: successor.tellIds.length > 0,
+    };
+}
+/** 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 continuation = readContinuationFromDatabase(database, current, limit);
+        return {
+            records,
+            current,
+            generationSequence: records.at(-1)?.seq ?? 0,
+            ...continuation,
+        };
+    });
+}
+/** One continuation eligibility fact shared by tell, wait, and wake. */
+export function readProjectionContinuation(projectionDirectory, current, limit = 10) {
+    const snapshot = readProjectionGenerationContinuationSnapshot(projectionDirectory, limit);
+    if (snapshot.current?.launch.executionId !== current?.launch.executionId) {
+        throw new ProjectionStateError("projection generation changed while reading continuation");
+    }
+    return snapshot;
+}
 export function applyContinuationEffort(inputs, effort) {
     if (!effort)
         return inputs;

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

@@ -2,7 +2,7 @@ import { initializeConfig } from "../../../config/env.js";
 import { buildCallTerms } from "../../../agents/call-terms.js";
 import { parseResolvedAkumaLaunchSnapshot } from "../../../agents/launch-snapshot/model.js";
 import { revive, call, } from "../../../agents/harness/index.js";
-import { claimFencedTells, demoteSubmittedTellsForReplay, readTellOriginal, readProjectionEvents, } from "../projection-core.js";
+import { claimFencedTells, readTellOriginal, readProjectionEvents, } from "../projection-core.js";
 import { createProjectionExecutionObserver, renderProjectionTellFrame, } from "../projection-execution-observer.js";
 import { readProjectionIdentity } from "../projection-identity.js";
 import { selectValidStoredAgentEvents } from "../../stored-agent-event.js";
@@ -140,7 +140,6 @@ export function executeProjectionGeneration(projectionDirectory, launch, provide
     const inputs = parseLaunchInputs(launch);
     initializeConfig(process.env, inputs.cwd);
     const executionId = launch.executionId;
-    demoteSubmittedTellsForReplay(projectionDirectory, executionId);
     const initialTellIds = claimFencedTells(projectionDirectory, launch.facts.tellFence ?? [], executionId);
     const tellPrompt = initialTellIds.map((tellId) => {
         const tell = readTellOriginal(projectionDirectory, "inflight", tellId);
@@ -182,7 +181,9 @@ export function executeProjectionGeneration(projectionDirectory, launch, provide
                     ? "completed"
                     : result.status === "dismissed"
                         ? "dismissed"
-                        : "failed",
+                        : result.status === "interrupted"
+                            ? "interrupted"
+                            : "failed",
                 facts: await completionFacts(projectionDirectory, executionId, inputs, result),
             };
         }

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

@@ -76,6 +76,7 @@ export async function runProjectionGeneration(input) {
     let settled = false;
     let tellObserver;
     let graceTimer;
+    let intentTimer;
     const clearGraceTimer = () => {
         if (graceTimer === undefined)
             return;
@@ -103,7 +104,8 @@ export async function runProjectionGeneration(input) {
         if (current?.launch.executionId !== input.executionId) {
             throw new Error("adopted generation stopped being current");
         }
-        // Pre-admission kill: skip provider work and commit killed directly.
+        // Pre-admission kill retains its established settlement law. Interrupt
+        // intent must enter provider execution so only an actual stop can settle it.
         if (current.killIntent) {
             const killed = store.runnerKilledIfRequested({ executionId: input.executionId });
             if (killed.status !== "committed")
@@ -113,10 +115,46 @@ export async function runProjectionGeneration(input) {
         }
         const handle = input.execute(current.launch);
         tellObserver = openProjectionTellObserver(input.projectionDirectory);
+        const settleInterrupted = (facts = {}) => {
+            const transition = store.runnerInterruptedIfRequested({
+                executionId: input.executionId,
+                facts,
+                terminalAt: new Date(now()).toISOString(),
+            });
+            if (transition.status !== "committed")
+                return { status: "rejected" };
+            settled = true;
+            runnerLock.close();
+            runnerLock = undefined;
+            void input.wakeAfterInterrupt?.().catch(() => {
+                // The ordinary wake path persists its typed failure. A later tell can retry.
+            });
+            return { status: "completed" };
+        };
+        const settleRunnerOutcome = (execution) => {
+            const transition = store.runnerVerdictIfOpen({
+                executionId: input.executionId,
+                verdict: execution.verdict,
+                facts: execution.facts,
+                terminalAt: new Date(now()).toISOString(),
+            });
+            if (transition.status !== "committed")
+                return { status: "rejected" };
+            settled = true;
+            if (transition.records[0]?.facts.state === "interrupted") {
+                runnerLock.close();
+                runnerLock = undefined;
+                void input.wakeAfterInterrupt?.().catch(() => {
+                    // The ordinary wake path persists its typed failure. A later observer retries.
+                });
+            }
+            return { status: "completed" };
+        };
         let gracefulAbortInvoked = false;
         let forceAbortInvoked = false;
         let sawKillIntent = false;
-        const observeKillBoundary = () => {
+        let sawInterruptIntent = false;
+        const observeStopBoundary = () => {
             try {
                 if (!tellObserver.hasDataVersionChanged())
                     return;
@@ -125,9 +163,10 @@ export async function runProjectionGeneration(input) {
                     return;
                 if (live.verdict)
                     return;
-                if (!live.killIntent)
+                sawKillIntent = live.killIntent !== undefined;
+                sawInterruptIntent = live.interruptIntent !== undefined;
+                if (!sawKillIntent && !sawInterruptIntent)
                     return;
-                sawKillIntent = true;
                 if (gracefulAbortInvoked)
                     return;
                 gracefulAbortInvoked = true;
@@ -153,12 +192,12 @@ export async function runProjectionGeneration(input) {
         const outcomeWatch = handle.outcome.then((execution) => {
             outcomeBox.status = "fulfilled";
             outcomeBox.execution = execution;
-            observeKillBoundary();
+            observeStopBoundary();
             bumpActivity();
         }, (error) => {
             outcomeBox.status = "rejected";
             outcomeBox.error = error;
-            observeKillBoundary();
+            observeStopBoundary();
             bumpActivity();
         });
         // Always rejection-observe so abandon paths never surface unhandled rejections.
@@ -168,7 +207,7 @@ export async function runProjectionGeneration(input) {
                 for await (const _event of handle.events) {
                     if (forceAbortInvoked)
                         return;
-                    observeKillBoundary();
+                    observeStopBoundary();
                     bumpActivity();
                 }
             }
@@ -178,10 +217,17 @@ export async function runProjectionGeneration(input) {
             bumpActivity();
         })();
         observeAbandoned(eventDrain);
-        while (outcomeBox.status === "pending" && !sawKillIntent) {
+        // A provider may be silently executing when an operator interrupts it.
+        // The durable observer is the sole stop-intent authority in that interval.
+        intentTimer = setInterval(() => {
+            observeStopBoundary();
+            bumpActivity();
+        }, 100);
+        intentTimer.unref?.();
+        while (outcomeBox.status === "pending" && !sawKillIntent && !sawInterruptIntent) {
             await activityChanged();
         }
-        if (sawKillIntent) {
+        if (sawKillIntent || sawInterruptIntent) {
             // Grace race: outcome settlement inside the window is stop proof.
             if (outcomeBox.status === "pending") {
                 const graceExpired = new Promise((resolve) => {
@@ -201,6 +247,16 @@ export async function runProjectionGeneration(input) {
                 const facts = killOutcome.status === "fulfilled"
                     ? nonReservedRunnerKillFacts(killOutcome.execution.facts)
                     : undefined;
+                if (sawInterruptIntent && killOutcome.status === "fulfilled" && killOutcome.execution.verdict === "interrupted") {
+                    return settleInterrupted(facts);
+                }
+                if (sawInterruptIntent) {
+                    if (killOutcome.status === "fulfilled")
+                        return settleRunnerOutcome(killOutcome.execution);
+                    if (killOutcome.status === "rejected")
+                        throw killOutcome.error;
+                    throw new Error("interrupt outcome did not establish provider stop");
+                }
                 const killed = store.runnerKilledIfRequested({
                     executionId: input.executionId,
                     ...(facts && Object.keys(facts).length > 0 ? { facts } : {}),
@@ -214,6 +270,8 @@ export async function runProjectionGeneration(input) {
             forceAbortInvoked = true;
             try {
                 await handle.abort("force");
+                if (sawInterruptIntent)
+                    return settleInterrupted();
                 const killed = store.runnerKilledIfRequested({ executionId: input.executionId });
                 if (killed.status !== "committed")
                     return { status: "rejected" };
@@ -225,7 +283,7 @@ export async function runProjectionGeneration(input) {
                     executionId: input.executionId,
                     verdict: "failed",
                     facts: {
-                        operatorAction: "kill",
+                        ...(sawKillIntent ? { operatorAction: "kill" } : {}),
                         diagnostic: "escalation-failed",
                         detail: errorDetail(error),
                         failedAt: new Date(now()).toISOString(),
@@ -268,53 +326,36 @@ export async function runProjectionGeneration(input) {
                 successorFacts: successorLaunchFacts(current.launch, execution.facts, pending.effort, now),
                 tellFence,
             });
-            if (transition.status !== "committed")
-                return { status: "rejected" };
-            settled = true;
-            // Handoff makes the predecessor terminal before life authority moves.
-            // A held projection lock must always mean that a current runner exists,
-            // so release it before the successor makes its one-shot acquisition.
-            runnerLock.close();
-            runnerLock = undefined;
-            try {
-                input.spawnSuccessor?.(successorExecutionId);
-            }
-            catch (error) {
-                store.verdictIfOpen({
-                    executionId: successorExecutionId,
-                    verdict: "launch-failed",
-                    facts: {
-                        stage: "spawn",
-                        detail: `successor runner spawn failed: ${errorDetail(error)}`,
-                        terminalAt: new Date(now()).toISOString(),
-                    },
-                });
-            }
-            return { status: "handed-off", successorExecutionId };
-        }
-        const verdict = store.verdictIfOpen({
-            executionId: input.executionId,
-            verdict: execution.verdict,
-            facts: execution.facts,
-        });
-        if (verdict.status !== "committed") {
-            // Kill intent may commit after the last outcome-boundary observation and
-            // before this transaction. The settled outcome is already stop proof.
-            if (verdict.reason === "kill-requested") {
-                const facts = nonReservedRunnerKillFacts(execution.facts);
-                const killed = store.runnerKilledIfRequested({
-                    executionId: input.executionId,
-                    ...(Object.keys(facts).length > 0 ? { facts } : {}),
-                });
-                if (killed.status !== "committed")
+            if (transition.status !== "committed") {
+                if (transition.reason !== "kill-requested" && transition.reason !== "interrupt-requested") {
                     return { status: "rejected" };
+                }
+            }
+            else {
                 settled = true;
-                return { status: "completed" };
+                // Handoff makes the predecessor terminal before life authority moves.
+                // A held projection lock must always mean that a current runner exists,
+                // so release it before the successor makes its one-shot acquisition.
+                runnerLock.close();
+                runnerLock = undefined;
+                try {
+                    input.spawnSuccessor?.(successorExecutionId);
+                }
+                catch (error) {
+                    store.verdictIfOpen({
+                        executionId: successorExecutionId,
+                        verdict: "launch-failed",
+                        facts: {
+                            stage: "spawn",
+                            detail: `successor runner spawn failed: ${errorDetail(error)}`,
+                            terminalAt: new Date(now()).toISOString(),
+                        },
+                    });
+                }
+                return { status: "handed-off", successorExecutionId };
             }
-            return { status: "rejected" };
         }
-        settled = true;
-        return { status: "completed" };
+        return settleRunnerOutcome(execution);
     }
     catch (error) {
         if (adopted && !settled) {
@@ -338,6 +379,8 @@ export async function runProjectionGeneration(input) {
     }
     finally {
         clearGraceTimer();
+        if (intentTimer !== undefined)
+            clearInterval(intentTimer);
         try {
             tellObserver?.close();
         }

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

@@ -2,6 +2,24 @@ import { executeProjectionGeneration } from "./projection-generation-execution.j
 import { spawnProjectionGenerationRunner } from "./projection-generation-process.js";
 import { runProjectionGeneration } from "./projection-generation-runner.js";
 import { snapshotPendingTells } from "./projection-generation-continuation.js";
+import { recordInterruptWakeFailure, tellProjection } from "../projection-wake.js";
+import { readProjectionIdentity } from "../projection-identity.js";
+import { FlowError } from "../../../flow-error.js";
+import * as path from "node:path";
+export async function wakeProjectionAfterInterrupt(projectionDirectory, wake = tellProjection) {
+    const pact = readProjectionIdentity(projectionDirectory);
+    try {
+        await wake(projectionDirectory, `${pact.akuma}/${path.basename(projectionDirectory)}`, undefined);
+    }
+    catch (error) {
+        const cause = error instanceof FlowError
+            && error.facts?.kind === "projection_wake_failure"
+            ? error.facts.cause
+            : "spawn";
+        recordInterruptWakeFailure(projectionDirectory, cause);
+        throw error;
+    }
+}
 export async function runProjectionGenerationRuntime(projectionDirectory, executionId) {
     await runProjectionGeneration({
         projectionDirectory,
@@ -11,5 +29,6 @@ export async function runProjectionGenerationRuntime(projectionDirectory, execut
         spawnSuccessor: (successorExecutionId) => {
             spawnProjectionGenerationRunner(projectionDirectory, successorExecutionId);
         },
+        wakeAfterInterrupt: () => wakeProjectionAfterInterrupt(projectionDirectory),
     });
 }

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

@@ -46,9 +46,18 @@ export class ProjectionGenerationStore {
     requestKillIfOpen(input) {
         return transitions.requestKillIfOpen(this.#database, this.readOnly, input);
     }
+    requestInterruptIfOpen(input) {
+        return transitions.requestInterruptIfOpen(this.#database, this.readOnly, input);
+    }
     runnerKilledIfRequested(input) {
         return transitions.runnerKilledIfRequested(this.#database, this.readOnly, input);
     }
+    runnerInterruptedIfRequested(input) {
+        return transitions.runnerInterruptedIfRequested(this.#database, this.readOnly, input);
+    }
+    runnerVerdictIfOpen(input) {
+        return transitions.runnerVerdictIfOpen(this.#database, this.readOnly, input);
+    }
     settleKillIfRunnerDead(input) {
         return transitions.settleKillIfRunnerDead(this.#database, this.readOnly, input);
     }