@code-yeongyu/senpi-agent-core 2026.10.31-1 → 2026.11.2-1

package/dist/agent-loop.js

@@ -99,7 +99,10 @@ export class StreamStartTimeoutError extends Error {
  */
 async function runLoop(initialContext, newMessages, initialConfig, signal, emit, streamFunction) {
     let currentContext = initialContext;
-    let config = initialConfig;
+    let config = {
+        ...initialConfig,
+        executionScope: initialConfig.executionScope ?? { id: crypto.randomUUID(), root: "" },
+    };
     let firstTurn = true;
     let firstProviderRequest = true;
     let drainedTerminatingQueue;
@@ -922,10 +925,28 @@ async function executeToolCalls(currentContext, assistantMessage, config, signal
     // channel and its result buffered; running it again would duplicate a
     // side-effecting tool.
     const toolCalls = assistantMessage.content.filter((c) => c.type === "toolCall" && !isCursorExecResolved(c));
-    if (config.toolExecution === "sequential") {
-        return executeToolCallsSequential(currentContext, assistantMessage, toolCalls, config, signal, emit);
-    }
-    return executeToolCallsParallel(currentContext, assistantMessage, toolCalls, config, signal, emit);
+    const host = config.toolHost ?? {
+        execute: async (call, options) => {
+            // Only yield when a witness sink is configured and returns a promise: an unconditional `await` adds a
+            // microtask per call and reorders lifecycle vs message events against today's fused path (EQ E03).
+            const recordWitness = options.recordWitness;
+            if (recordWitness) {
+                for (const raw of call.calls) {
+                    const pending = recordWitness({ pipeline: "legacy", toolCallId: raw.id });
+                    if (pending)
+                        await pending;
+                }
+            }
+            return call.mode === "sequential"
+                ? executeToolCallsSequential(currentContext, assistantMessage, toolCalls, config, options.signal, options.emit)
+                : executeToolCallsParallel(currentContext, assistantMessage, toolCalls, config, options.signal, options.emit);
+        },
+    };
+    return host.execute({
+        scope: config.executionScope ?? { id: crypto.randomUUID(), root: "" },
+        calls: toolCalls,
+        mode: config.toolExecution ?? "parallel",
+    }, { signal, emit, recordWitness: config.onExecutionPipeline });
 }
 async function executeToolCallsSequential(currentContext, assistantMessage, toolCalls, config, signal, emit) {
     const finalizedCalls = [];

package/dist/agent.d.ts

@@ -37,6 +37,9 @@ export interface AgentOptions {
     streamKeepAliveTimeoutMs?: number;
     maxRetryDelayMs?: number;
     toolExecution?: ToolExecutionMode;
+    toolHost?: AgentLoopConfig["toolHost"];
+    executionScope?: AgentLoopConfig["executionScope"];
+    onExecutionPipeline?: AgentLoopConfig["onExecutionPipeline"];
     removedToolHints?: Record<string, string>;
     resolveUnknownToolCall?: AgentLoopConfig["resolveUnknownToolCall"];
     abortServerSideFallback?: boolean;
@@ -113,6 +116,10 @@ export declare class Agent {
     maxRetryDelayMs?: number;
     /** Tool execution strategy for assistant messages that contain multiple tool calls. */
     toolExecution: ToolExecutionMode;
+    toolHost?: AgentLoopConfig["toolHost"];
+    executionScope: NonNullable<AgentLoopConfig["executionScope"]>;
+    getExecutionScope?: () => NonNullable<AgentLoopConfig["executionScope"]>;
+    onExecutionPipeline?: AgentLoopConfig["onExecutionPipeline"];
     /** Migration guidance returned when a removed tool name is called. */
     removedToolHints: Record<string, string>;
     /** Optional call-time resolver for tools absent from the request context. */

package/dist/agent.js

@@ -167,6 +167,9 @@ export class Agent {
         this.streamKeepAliveTimeoutMs = runtimeOptions.streamKeepAliveTimeoutMs;
         this.maxRetryDelayMs = runtimeOptions.maxRetryDelayMs;
         this.toolExecution = runtimeOptions.toolExecution ?? "parallel";
+        this.toolHost = runtimeOptions.toolHost;
+        this.executionScope = runtimeOptions.executionScope ?? { id: crypto.randomUUID(), root: "" };
+        this.onExecutionPipeline = runtimeOptions.onExecutionPipeline;
         this.removedToolHints = runtimeOptions.removedToolHints ?? {};
         this.resolveUnknownToolCall = runtimeOptions.resolveUnknownToolCall;
         this.abortServerSideFallback = runtimeOptions.abortServerSideFallback;
@@ -485,6 +488,9 @@ export class Agent {
             abortServerSideFallback: this.abortServerSideFallback,
             cursorExecHandlers: this.cursorExecHandlers,
             toolExecution: this.toolExecution,
+            toolHost: this.toolHost,
+            executionScope: this.getExecutionScope?.() ?? this.executionScope,
+            onExecutionPipeline: this.onExecutionPipeline,
             removedToolHints: this.removedToolHints,
             resolveUnknownToolCall: this.resolveUnknownToolCall,
             beforeToolCall: this.beforeToolCall,

package/dist/conformance/index.d.ts

@@ -39,4 +39,10 @@ export { TRANSPORT_CASES } from "../transport/testing/transport-cases.ts";
 export type { CarrierFault, TransportCaseAdapters, TransportConformanceAdapter, WireView, } from "../transport/testing/transport-harness.ts";
 export type { CarrierConnection, CarrierSide, FrameHandler, Transport, TransportClock, TransportFrame, TransportSide, } from "../transport/transport.ts";
 export { TransportClosedError } from "../transport/transport.ts";
+export { createExecutionLedger } from "../execution/ledger.ts";
+export type { ExecutionLedger } from "../execution/ledger.ts";
+export type { ExecutionAdmission, ExecutionCommand, ExecutionEntry, ExecutionEvent, ExecutionKey, ExecutionOutcome, ExecutionProgress, FrozenCall, LedgerReply, } from "../execution/ledger-types.ts";
+export { LEDGER_CASES } from "../execution/testing/ledger-cases.ts";
+export { KILL_LEDGER_CASES, KILL_LEDGER_DECLARATIONS } from "../execution/testing/kill-ledger.ts";
+export type { KillLedgerDeclaration } from "../execution/testing/kill-ledger.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/conformance/index.js

@@ -20,4 +20,7 @@ export { FAULT_PROFILE_NAMES } from "../transport/testing/fault-transport.js";
 export { MULTI_CASES } from "../transport/testing/multi-cases.js";
 export { TRANSPORT_CASES } from "../transport/testing/transport-cases.js";
 export { TransportClosedError } from "../transport/transport.js";
+export { createExecutionLedger } from "../execution/ledger.js";
+export { LEDGER_CASES } from "../execution/testing/ledger-cases.js";
+export { KILL_LEDGER_CASES, KILL_LEDGER_DECLARATIONS } from "../execution/testing/kill-ledger.js";
 //# sourceMappingURL=index.js.map

package/dist/conformance/loop-core-manifest.d.ts

@@ -0,0 +1,14 @@
+/**
+ * S06: the host-independent loop boundary, relative to packages/agent/src.
+ * Every local dependency (including type imports) must also be listed and checked.
+ * Host adapters, carriers, persistence implementations and the Node harness stay outside.
+ * Extend this closure when adding loop modules; never add a host implementation to it.
+ */
+export declare const LOOP_CORE_MODULES: readonly ["agent.ts", "agent-loop.ts", "assistant-terminal-state.ts", "empty-assistant-recovery.ts", "internal-events.ts", "local-failure.ts", "response-timing.ts", "stream-fn.ts", "stream-keepalive.ts", "tool-arguments.ts", "tool-name-alias.ts", "types.ts", "durable/store.ts", "execution/tool-host.ts", "durable/store-admission.ts", "durable/wake-host.ts", "transport/transport.ts"];
+/**
+ * Existing portable model/message utilities and schema types, not provider runtimes.
+ * Exact specifiers deliberately exclude compat, OAuth, SDKs and host-specific subpaths.
+ * The model implementation enters the loop through StreamFn, not a provider import.
+ */
+export declare const LOOP_CORE_EXTERNAL_MODULES: readonly ["@earendil-works/pi-ai", "@earendil-works/pi-ai/utils/oauth-refresh-error", "@earendil-works/pi-ai/utils/retry", "@earendil-works/pi-ai/utils/tool-name-match", "typebox"];
+//# sourceMappingURL=loop-core-manifest.d.ts.map

package/dist/conformance/loop-core-manifest.js

@@ -0,0 +1,38 @@
+/**
+ * S06: the host-independent loop boundary, relative to packages/agent/src.
+ * Every local dependency (including type imports) must also be listed and checked.
+ * Host adapters, carriers, persistence implementations and the Node harness stay outside.
+ * Extend this closure when adding loop modules; never add a host implementation to it.
+ */
+export const LOOP_CORE_MODULES = [
+    "agent.ts",
+    "agent-loop.ts",
+    "assistant-terminal-state.ts",
+    "empty-assistant-recovery.ts",
+    "internal-events.ts",
+    "local-failure.ts",
+    "response-timing.ts",
+    "stream-fn.ts",
+    "stream-keepalive.ts",
+    "tool-arguments.ts",
+    "tool-name-alias.ts",
+    "types.ts",
+    "durable/store.ts",
+    "execution/tool-host.ts",
+    "durable/store-admission.ts",
+    "durable/wake-host.ts",
+    "transport/transport.ts",
+];
+/**
+ * Existing portable model/message utilities and schema types, not provider runtimes.
+ * Exact specifiers deliberately exclude compat, OAuth, SDKs and host-specific subpaths.
+ * The model implementation enters the loop through StreamFn, not a provider import.
+ */
+export const LOOP_CORE_EXTERNAL_MODULES = [
+    "@earendil-works/pi-ai",
+    "@earendil-works/pi-ai/utils/oauth-refresh-error",
+    "@earendil-works/pi-ai/utils/retry",
+    "@earendil-works/pi-ai/utils/tool-name-match",
+    "typebox",
+];
+//# sourceMappingURL=loop-core-manifest.js.map

package/dist/conformance/registry.js

@@ -1,3 +1,4 @@
+import { LEDGER_REGISTRY } from "../execution/testing/ledger-registry.js";
 export const ADAPTER_KINDS = ["store", "wake", "transport", "executor", "host"];
 /**
  * Every case of the durable-core conformance suite (packages/agent/docs/durable-core-adr.md). A change that adds cases
@@ -34,6 +35,7 @@ const storeCase = (id, impl, expected) => ({
     expected,
 });
 export const CONFORMANCE_REGISTRY = [
+    ...LEDGER_REGISTRY,
     storeCase("STORE-01", STORE_CASES_IMPL, "a commit adopts once, after its batch is durable; every instance sees each batch whole"),
     storeCase("STORE-02", STORE_CASES_IMPL, "a cut at every write point of a commit leaves nothing of it durable, with no adopt and no seq burned"),
     storeCase("STORE-03", STORE_CASES_IMPL, "concurrent admissions run one at a time in admission order; a refused mutation releases the line"),

package/dist/execution/ledger-codec.d.ts

@@ -0,0 +1,5 @@
+import type { StoreValue } from "../durable/store.ts";
+import type { ExecutionEntry } from "./ledger-types.ts";
+/** Stored JSON crosses its schema boundary once, on read. A corrupt row must never look like a missing execution. */
+export declare function decodeExecution(value: StoreValue): ExecutionEntry;
+//# sourceMappingURL=ledger-codec.d.ts.map

package/dist/execution/ledger-codec.js

@@ -0,0 +1,64 @@
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function frozen(value) {
+    return (object(value) && typeof value.name === "string" && typeof value.digest === "string" && value.args !== undefined);
+}
+function outcome(value) {
+    if (!object(value) || typeof value.hooksRan !== "boolean" || typeof value.uncertain !== "boolean")
+        return false;
+    switch (value.reason) {
+        case "result":
+            return value.value !== undefined && value.uncertain === false;
+        case "cancelled":
+        case "lease_expired":
+        case "hand_restarted":
+        case "uncertain":
+            return true;
+        default:
+            return false;
+    }
+}
+function progress(value) {
+    if (!object(value))
+        return false;
+    switch (value.state) {
+        case "admitted":
+        case "preparing":
+        case "acked":
+            return true;
+        case "prepared":
+        case "prepared_awaiting_consent":
+        case "released":
+        case "dispatched":
+            return frozen(value.call);
+        case "reconciling":
+            return frozen(value.call) && typeof value.until === "number" && Number.isFinite(value.until);
+        case "settled":
+            return outcome(value.outcome);
+        default:
+            return false;
+    }
+}
+function entry(value) {
+    return (object(value) &&
+        ["issuer", "commandId", "executor", "workspace", "scope", "requestDigest"].every((key) => typeof value[key] === "string") &&
+        ["generation", "admittedAt", "leaseUntil", "initialLeaseUntil", "renewSeq"].every((key) => typeof value[key] === "number" && Number.isFinite(value[key])) &&
+        typeof value.reconcilable === "boolean" &&
+        typeof value.effectPossible === "boolean" &&
+        typeof value.bodyDispatched === "boolean" &&
+        progress(value.progress));
+}
+class ExecutionLedgerCorruptError extends Error {
+    constructor() {
+        super("invalid durable execution ledger row");
+        this.name = "ExecutionLedgerCorruptError";
+    }
+}
+/** Stored JSON crosses its schema boundary once, on read. A corrupt row must never look like a missing execution. */
+export function decodeExecution(value) {
+    if (!entry(value))
+        throw new ExecutionLedgerCorruptError();
+    return value;
+}
+//# sourceMappingURL=ledger-codec.js.map

package/dist/execution/ledger-transition.d.ts

@@ -0,0 +1,4 @@
+import { type ExecutionCommand, type ExecutionEntry, type LedgerReply } from "./ledger-types.ts";
+/** A body may run only for an applied reply in state `dispatched`, never for an expiry settlement or replay. */
+export declare function transitionExecution(entry: ExecutionEntry, command: ExecutionCommand): LedgerReply;
+//# sourceMappingURL=ledger-transition.d.ts.map

package/dist/execution/ledger-transition.js

@@ -0,0 +1,139 @@
+import { applied, MAX_EXECUTION_LIFETIME_MS, RECONCILIATION_GRACE_MS, refused, replayed, } from "./ledger-types.js";
+const advance = (entry, progress) => applied({ ...entry, progress });
+const settle = (entry, reason) => advance(entry, {
+    state: "settled",
+    outcome: { reason, hooksRan: entry.effectPossible, uncertain: entry.effectPossible || entry.bodyDispatched },
+});
+function authorized(entry, { actor, event }) {
+    switch (event.kind) {
+        case "cancel":
+            return actor.id === entry.issuer || actor.approvedWorkspace === entry.workspace;
+        case "consent":
+        case "release":
+        case "abort":
+        case "ack":
+        case "renew":
+            return actor.id === entry.issuer;
+        case "prepare":
+        case "effect":
+        case "freeze":
+        case "dispatch":
+        case "result":
+        case "expire":
+        case "restart":
+            return actor.id === entry.executor;
+    }
+}
+function recover(entry, now) {
+    switch (entry.progress.state) {
+        case "admitted":
+        case "preparing":
+            return settle(entry, "hand_restarted");
+        case "dispatched":
+            return entry.reconcilable
+                ? advance(entry, {
+                    state: "reconciling",
+                    call: entry.progress.call,
+                    until: Math.min(entry.leaseUntil, now + RECONCILIATION_GRACE_MS),
+                })
+                : settle(entry, "hand_restarted");
+        case "reconciling":
+            return now >= entry.progress.until ? settle(entry, "hand_restarted") : replayed(entry);
+        case "prepared":
+        case "prepared_awaiting_consent":
+        case "released":
+        case "settled":
+        case "acked":
+            return replayed(entry);
+    }
+}
+/** A body may run only for an applied reply in state `dispatched`, never for an expiry settlement or replay. */
+export function transitionExecution(entry, command) {
+    const { event, now } = command;
+    if (command.generation !== entry.generation)
+        return refused("stale_generation");
+    if (!authorized(entry, command))
+        return refused("unauthorized");
+    if (!Number.isFinite(now) || now < entry.admittedAt)
+        return refused("invalid_time");
+    const progress = entry.progress;
+    if (progress.state === "acked")
+        return event.kind === "ack" ? { status: "replayed", entry } : { status: "result_expired" };
+    if (progress.state === "settled") {
+        switch (event.kind) {
+            case "ack":
+                return advance(entry, { state: "acked" });
+            case "release":
+            case "abort":
+            case "consent":
+                return refused("terminal");
+            default:
+                return replayed(entry);
+        }
+    }
+    if (now >= entry.leaseUntil)
+        return settle(entry, "lease_expired");
+    if (progress.state === "reconciling" && now >= progress.until)
+        return settle(entry, "hand_restarted");
+    switch (event.kind) {
+        case "prepare":
+            return progress.state === "admitted" ? advance(entry, { state: "preparing" }) : replayed(entry);
+        case "effect":
+            if (entry.effectPossible)
+                return replayed(entry);
+            return progress.state === "preparing"
+                ? applied({ ...entry, effectPossible: true })
+                : refused("invalid_transition");
+        case "freeze":
+            if (progress.state === "preparing" && entry.effectPossible) {
+                return advance(entry, {
+                    state: event.awaitingConsent ? "prepared_awaiting_consent" : "prepared",
+                    call: event.call,
+                });
+            }
+            return "call" in progress && progress.call.digest === event.call.digest
+                ? replayed(entry)
+                : refused("invalid_transition");
+        case "consent":
+            return progress.state === "prepared_awaiting_consent"
+                ? advance(entry, { state: "prepared", call: progress.call })
+                : refused("invalid_transition");
+        case "release":
+            if (progress.state === "prepared")
+                return advance(entry, { state: "released", call: progress.call });
+            return progress.state === "released" || entry.bodyDispatched ? replayed(entry) : refused("invalid_transition");
+        case "dispatch":
+            if (entry.bodyDispatched)
+                return replayed(entry);
+            return progress.state === "released"
+                ? applied({ ...entry, bodyDispatched: true, progress: { state: "dispatched", call: progress.call } })
+                : refused("invalid_transition");
+        case "result":
+            if (progress.state !== "dispatched" && progress.state !== "reconciling")
+                return refused("invalid_transition");
+            return advance(entry, {
+                state: "settled",
+                outcome: { reason: "result", value: event.value, hooksRan: entry.effectPossible, uncertain: false },
+            });
+        case "cancel":
+            return settle(entry, "cancelled");
+        case "abort":
+            return entry.bodyDispatched ? refused("invalid_transition") : settle(entry, "cancelled");
+        case "ack":
+            return refused("invalid_transition");
+        case "renew":
+            if (event.seq <= entry.renewSeq)
+                return replayed(entry);
+            if (!Number.isSafeInteger(event.seq) ||
+                !Number.isFinite(event.leaseUntil) ||
+                event.leaseUntil <= entry.leaseUntil ||
+                event.leaseUntil > entry.admittedAt + MAX_EXECUTION_LIFETIME_MS)
+                return refused("invalid_renewal");
+            return applied({ ...entry, renewSeq: event.seq, leaseUntil: event.leaseUntil });
+        case "expire":
+            return replayed(entry);
+        case "restart":
+            return recover(entry, now);
+    }
+}
+//# sourceMappingURL=ledger-transition.js.map

package/dist/execution/ledger-types.d.ts

@@ -0,0 +1,93 @@
+import type { StoreValue } from "../durable/store.ts";
+export type ExecutionKey = {
+    readonly issuer: string;
+    readonly commandId: string;
+};
+export type ExecutionAdmission = ExecutionKey & {
+    readonly executor: string;
+    readonly workspace: string;
+    readonly scope: string;
+    readonly generation: number;
+    readonly requestDigest: string;
+    readonly admittedAt: number;
+    readonly leaseUntil: number;
+    readonly reconcilable: boolean;
+};
+export type FrozenCall = {
+    readonly name: string;
+    readonly args: StoreValue;
+    readonly digest: string;
+};
+export type ExecutionOutcome = {
+    readonly reason: "result";
+    readonly value: StoreValue;
+    readonly hooksRan: boolean;
+    readonly uncertain: false;
+} | {
+    readonly reason: "cancelled" | "lease_expired" | "hand_restarted" | "uncertain";
+    readonly hooksRan: boolean;
+    readonly uncertain: boolean;
+};
+export type ExecutionProgress = {
+    readonly state: "admitted" | "preparing";
+} | {
+    readonly state: "prepared" | "prepared_awaiting_consent" | "released" | "dispatched";
+    readonly call: FrozenCall;
+} | {
+    readonly state: "reconciling";
+    readonly call: FrozenCall;
+    readonly until: number;
+} | {
+    readonly state: "settled";
+    readonly outcome: ExecutionOutcome;
+} | {
+    readonly state: "acked";
+};
+export type ExecutionEntry = ExecutionAdmission & {
+    readonly initialLeaseUntil: number;
+    readonly renewSeq: number;
+    readonly effectPossible: boolean;
+    readonly bodyDispatched: boolean;
+    readonly progress: ExecutionProgress;
+};
+export type ExecutionEvent = {
+    readonly kind: "prepare" | "effect" | "consent" | "release" | "dispatch" | "cancel" | "abort" | "ack" | "expire" | "restart";
+} | {
+    readonly kind: "freeze";
+    readonly call: FrozenCall;
+    readonly awaitingConsent: boolean;
+} | {
+    readonly kind: "result";
+    readonly value: StoreValue;
+} | {
+    readonly kind: "renew";
+    readonly seq: number;
+    readonly leaseUntil: number;
+};
+export type ExecutionCommand = {
+    readonly key: ExecutionKey;
+    readonly generation: number;
+    /** Verified identity and workspace approval, supplied by the authenticated endpoint, never by a wire body. */
+    readonly actor: {
+        readonly id: string;
+        readonly approvedWorkspace?: string;
+    };
+    readonly now: number;
+    readonly event: ExecutionEvent;
+};
+export type LedgerRefusal = "not_found" | "identity_conflict" | "invalid_admission" | "stale_generation" | "unauthorized" | "invalid_transition" | "invalid_renewal" | "invalid_time" | "terminal";
+export type LedgerReply = {
+    readonly status: "applied" | "replayed";
+    readonly entry: ExecutionEntry;
+} | {
+    readonly status: "refused";
+    readonly reason: LedgerRefusal;
+} | {
+    readonly status: "result_expired";
+};
+export declare const MAX_EXECUTION_LIFETIME_MS = 86400000;
+export declare const RECONCILIATION_GRACE_MS = 30000;
+export declare const refused: (reason: LedgerRefusal) => LedgerReply;
+export declare const replayed: (entry: ExecutionEntry) => LedgerReply;
+export declare const applied: (entry: ExecutionEntry) => LedgerReply;
+//# sourceMappingURL=ledger-types.d.ts.map

package/dist/execution/ledger-types.js

@@ -0,0 +1,6 @@
+export const MAX_EXECUTION_LIFETIME_MS = 86_400_000;
+export const RECONCILIATION_GRACE_MS = 30_000;
+export const refused = (reason) => ({ status: "refused", reason });
+export const replayed = (entry) => entry.progress.state === "acked" ? { status: "result_expired" } : { status: "replayed", entry };
+export const applied = (entry) => ({ status: "applied", entry });
+//# sourceMappingURL=ledger-types.js.map

package/dist/execution/ledger.d.ts

@@ -0,0 +1,17 @@
+import type { AdmissionLine } from "../durable/store-admission.ts";
+import type { DurableStore } from "../durable/store.ts";
+import { type ExecutionAdmission, type ExecutionCommand, type ExecutionEntry, type ExecutionKey, type LedgerReply } from "./ledger-types.ts";
+export interface ExecutionLedger {
+    admit(input: ExecutionAdmission): Promise<LedgerReply>;
+    apply(command: ExecutionCommand): Promise<LedgerReply>;
+    read(key: ExecutionKey): Promise<ExecutionEntry | undefined>;
+    /** Called once on endpoint restart; also expires overdue leases and reconciliation deadlines. */
+    recover(now: number): Promise<void>;
+}
+/** All ledgers sharing a writable store epoch must share its single admission line. */
+export declare function createExecutionLedger(options: {
+    readonly store: DurableStore;
+    readonly epoch: number;
+    readonly admission: AdmissionLine;
+}): ExecutionLedger;
+//# sourceMappingURL=ledger.d.ts.map

package/dist/execution/ledger.js

@@ -0,0 +1,101 @@
+import { decodeExecution } from "./ledger-codec.js";
+import { transitionExecution } from "./ledger-transition.js";
+import { applied, MAX_EXECUTION_LIFETIME_MS, refused, replayed, } from "./ledger-types.js";
+const PREFIX = "execution.ledger:";
+const keyOf = ({ issuer, commandId }) => `${PREFIX}${JSON.stringify([issuer, commandId])}`;
+/** All ledgers sharing a writable store epoch must share its single admission line. */
+export function createExecutionLedger(options) {
+    const { store, epoch, admission } = options;
+    const read = async (key) => {
+        const value = await store.getDocument(keyOf(key));
+        return value === undefined ? undefined : decodeExecution(value);
+    };
+    const persist = async (entry, event, audit = false) => {
+        const writes = [
+            {
+                op: "append",
+                id: store.mintId(),
+                kind: audit ? "execution.audit" : "execution.transition",
+                data: {
+                    issuer: entry.issuer,
+                    commandId: entry.commandId,
+                    generation: entry.generation,
+                    event,
+                    state: entry.progress.state,
+                },
+            },
+        ];
+        if (!audit)
+            writes.push({ op: "put", key: keyOf(entry), data: entry });
+        await store.commit(epoch, writes, () => { });
+    };
+    const apply = (command) => admission.admit(async () => {
+        const entry = await read(command.key);
+        if (entry === undefined)
+            return refused("not_found");
+        const reply = transitionExecution(entry, command);
+        if (reply.status === "applied")
+            await persist(reply.entry, command.event.kind);
+        else if (reply.status === "replayed" &&
+            entry.progress.state === "settled" &&
+            (command.event.kind === "result" || command.event.kind === "cancel"))
+            await persist(entry, command.event.kind, true);
+        return reply;
+    });
+    return {
+        read,
+        apply,
+        admit: (input) => admission.admit(async () => {
+            const prior = await read(input);
+            if (prior !== undefined) {
+                const same = prior.executor === input.executor &&
+                    prior.workspace === input.workspace &&
+                    prior.scope === input.scope &&
+                    prior.generation === input.generation &&
+                    prior.requestDigest === input.requestDigest &&
+                    prior.admittedAt === input.admittedAt &&
+                    prior.initialLeaseUntil === input.leaseUntil &&
+                    prior.reconcilable === input.reconcilable;
+                return same ? replayed(prior) : refused("identity_conflict");
+            }
+            if (![
+                input.issuer,
+                input.commandId,
+                input.executor,
+                input.workspace,
+                input.scope,
+                input.requestDigest,
+            ].every(Boolean) ||
+                !Number.isSafeInteger(input.generation) ||
+                input.generation < 1 ||
+                !Number.isFinite(input.admittedAt) ||
+                !Number.isFinite(input.leaseUntil) ||
+                input.leaseUntil <= input.admittedAt ||
+                input.leaseUntil > input.admittedAt + MAX_EXECUTION_LIFETIME_MS)
+                return refused("invalid_admission");
+            const entry = {
+                ...input,
+                initialLeaseUntil: input.leaseUntil,
+                renewSeq: 0,
+                effectPossible: false,
+                bodyDispatched: false,
+                progress: { state: "admitted" },
+            };
+            await persist(entry, "admit");
+            return applied(entry);
+        }),
+        recover: async (now) => {
+            for (const document of await store.scanDocuments(PREFIX)) {
+                const entry = decodeExecution(document.data);
+                await apply({
+                    key: entry,
+                    generation: entry.generation,
+                    actor: { id: entry.executor },
+                    now,
+                    event: { kind: "restart" },
+                });
+            }
+        },
+    };
+}
+//# sourceMappingURL=ledger.js.map

package/dist/execution/testing/kill-ledger.d.ts

@@ -0,0 +1,12 @@
+import type { CaseImplementation } from "../../conformance/runner.ts";
+import type { StoreWritePoint } from "../../durable/store.ts";
+import { type StoreCaseAdapters } from "../../durable/testing/store-harness.ts";
+export interface KillLedgerDeclaration {
+    readonly id: string;
+    readonly operation: string;
+    readonly point: StoreWritePoint;
+    readonly placement: "everywhere";
+}
+export declare const KILL_LEDGER_DECLARATIONS: readonly KillLedgerDeclaration[];
+export declare const KILL_LEDGER_CASES: ReadonlyMap<string, CaseImplementation<StoreCaseAdapters>>;
+//# sourceMappingURL=kill-ledger.d.ts.map

package/dist/execution/testing/kill-ledger.js

@@ -0,0 +1,88 @@
+import { claimedStore } from "../../durable/testing/store-cases.js";
+import { cutOnceAt, expectCut, expectEqual } from "../../durable/testing/store-harness.js";
+import { ADMISSION, command, DISPATCH, FROZEN, ledgerOn, PREPARE, runEvents } from "./ledger-harness.js";
+const TRANSITIONS = [
+    { name: "admit", before: [], expected: "admitted" },
+    { name: "prepare", before: [], event: { kind: "prepare" }, expected: "preparing" },
+    { name: "effect", before: PREPARE.slice(0, 1), event: { kind: "effect" }, expected: "preparing" },
+    {
+        name: "freeze",
+        before: PREPARE.slice(0, 2),
+        event: { kind: "freeze", call: FROZEN, awaitingConsent: false },
+        expected: "prepared",
+    },
+    {
+        name: "await-consent",
+        before: PREPARE.slice(0, 2),
+        event: { kind: "freeze", call: FROZEN, awaitingConsent: true },
+        expected: "prepared_awaiting_consent",
+    },
+    {
+        name: "consent",
+        before: [...PREPARE.slice(0, 2), { kind: "freeze", call: FROZEN, awaitingConsent: true }],
+        event: { kind: "consent" },
+        expected: "prepared",
+    },
+    { name: "release", before: PREPARE, event: { kind: "release" }, expected: "released" },
+    { name: "dispatch", before: DISPATCH.slice(0, 4), event: { kind: "dispatch" }, expected: "dispatched" },
+    { name: "result", before: DISPATCH, event: { kind: "result", value: "done" }, expected: "settled" },
+    { name: "cancel", before: DISPATCH, event: { kind: "cancel" }, expected: "settled" },
+    { name: "abort", before: PREPARE, event: { kind: "abort" }, expected: "settled" },
+    { name: "renew", before: [], event: { kind: "renew", seq: 1, leaseUntil: 70_100 }, expected: "admitted" },
+    { name: "expire", before: PREPARE, event: { kind: "expire" }, now: 60_100, expected: "settled" },
+    { name: "restart", before: PREPARE.slice(0, 2), event: { kind: "restart" }, expected: "settled" },
+    { name: "reconcile", before: DISPATCH, event: { kind: "restart" }, reconcilable: true, expected: "reconciling" },
+    { name: "ack", before: [...DISPATCH, { kind: "result", value: "done" }], event: { kind: "ack" }, expected: "acked" },
+];
+const POINTS = [
+    { op: "commit", at: "before" },
+    { op: "commit", at: "write", index: 0 },
+    { op: "commit", at: "write", index: 1 },
+    { op: "commit", at: "durable" },
+];
+const cases = TRANSITIONS.flatMap((transition, index) => POINTS.map((point, cutIndex) => {
+    const id = `KILL-LEDGER-${String(index + 1).padStart(2, "0")}-${cutIndex + 1}`;
+    const run = async ({ store: adapter }) => {
+        const { medium, store } = await claimedStore(adapter);
+        const ledger = ledgerOn(store);
+        const input = { ...ADMISSION, reconcilable: transition.reconcilable ?? false };
+        if (transition.event !== undefined)
+            await ledger.admit(input);
+        await runEvents(ledger, transition.before);
+        const baseline = await store.exportSnapshot();
+        const cut = ledgerOn(await adapter.open(medium, cutOnceAt(point)));
+        await expectCut(transition.event === undefined ? cut.admit(input) : cut.apply(command(transition.event, transition.now)), `${transition.name}/${point.at}`);
+        const reopenedStore = await adapter.open(medium);
+        const reopened = ledgerOn(reopenedStore);
+        const snapshot = await reopenedStore.exportSnapshot();
+        if (point.at !== "durable") {
+            expectEqual(snapshot, baseline, "a cut before durable changes neither journal nor row");
+        }
+        else {
+            expectEqual(snapshot.head, baseline.head + 1, "exactly one durable transition");
+            const entry = await reopened.read(ADMISSION);
+            expectEqual(entry?.progress.state, transition.expected, "the complete endpoint transition survived");
+            if (transition.name === "effect")
+                expectEqual(entry?.effectPossible, true, "effect permission durable before callback");
+            if (transition.name === "dispatch") {
+                expectEqual(entry?.bodyDispatched, true, "dispatch permission is durable before body");
+                expectEqual((await reopened.apply(command({ kind: "dispatch" }))).status, "replayed", "no second dispatch after crash");
+            }
+            if (transition.name === "renew")
+                expectEqual(entry?.renewSeq, 1, "renewal sequence survives");
+        }
+        await reopened.recover(transition.now ?? 102);
+        const recovered = await reopened.read(ADMISSION);
+        if (recovered?.progress.state === "preparing" || recovered?.progress.state === "dispatched") {
+            throw new Error("restart left a non-resumable execution live");
+        }
+        if (recovered !== undefined) {
+            const replay = await reopened.admit(input);
+            expectEqual(replay.status, recovered.progress.state === "acked" ? "result_expired" : "replayed", "identity survives restart");
+        }
+    };
+    return { id, operation: transition.name, point, placement: "everywhere", run };
+}));
+export const KILL_LEDGER_DECLARATIONS = cases.map(({ run: _run, ...entry }) => entry);
+export const KILL_LEDGER_CASES = new Map(cases.map(({ id, run }) => [id, run]));
+//# sourceMappingURL=kill-ledger.js.map

package/dist/execution/testing/ledger-cases.d.ts

@@ -0,0 +1,6 @@
+import type { CaseImplementation } from "../../conformance/runner.ts";
+import { type StoreCaseAdapters } from "../../durable/testing/store-harness.ts";
+type LedgerCase = CaseImplementation<StoreCaseAdapters>;
+export declare const LEDGER_CASES: ReadonlyMap<string, LedgerCase>;
+export {};
+//# sourceMappingURL=ledger-cases.d.ts.map

package/dist/execution/testing/ledger-cases.js

@@ -0,0 +1,74 @@
+import { expectEqual } from "../../durable/testing/store-harness.js";
+import { ADMISSION, command, DISPATCH, fixture, FROZEN, PREPARE, row, runEvents } from "./ledger-harness.js";
+import { LEDGER_RECOVERY_CASES } from "./ledger-recovery-cases.js";
+const identity = async ({ store }) => {
+    const { ledger } = await fixture(store);
+    expectEqual((await ledger.admit(ADMISSION)).status, "replayed", "same identity");
+    for (const change of [{ scope: "other" }, { generation: 2 }, { requestDigest: "changed" }, { executor: "other" }]) {
+        expectEqual(await ledger.admit({ ...ADMISSION, ...change }), { status: "refused", reason: "identity_conflict" }, "binding");
+    }
+    expectEqual((await ledger.admit({ ...ADMISSION, issuer: "another" })).status, "applied", "issuer namespaces identity");
+    expectEqual(await ledger.apply({ ...command({ kind: "prepare" }), generation: 2 }), { status: "refused", reason: "stale_generation" }, "generation fence");
+};
+const preparation = async ({ store }) => {
+    const { ledger, reopen } = await fixture(store);
+    expectEqual(await ledger.apply(command({ kind: "effect" })), { status: "refused", reason: "invalid_transition" }, "no effects before prepare");
+    await ledger.apply(command({ kind: "prepare" }));
+    expectEqual(await ledger.apply(command({ kind: "freeze", call: FROZEN, awaitingConsent: false })), { status: "refused", reason: "invalid_transition" }, "freeze requires effect marker");
+    await ledger.apply(command({ kind: "effect" }));
+    expectEqual((await row(await reopen())).effectPossible, true, "effect marker survives reopen before a callback may run");
+    expectEqual((await ledger.apply(command({ kind: "effect" }))).status, "replayed", "effects never granted twice");
+    await ledger.apply(command({ kind: "freeze", call: FROZEN, awaitingConsent: false }));
+    expectEqual((await row(await reopen())).progress, { state: "prepared", call: FROZEN }, "frozen bytes survive reopen");
+};
+const consent = async ({ store }) => {
+    const { ledger } = await fixture(store);
+    await runEvents(ledger, [...PREPARE.slice(0, 2), { kind: "freeze", call: FROZEN, awaitingConsent: true }]);
+    expectEqual(await ledger.apply(command({ kind: "release" })), { status: "refused", reason: "invalid_transition" }, "consent wait cannot release");
+    expectEqual(await ledger.apply({ ...command({ kind: "consent" }), actor: { id: "other" } }), { status: "refused", reason: "unauthorized" }, "consent issuer");
+    await runEvents(ledger, [{ kind: "consent" }, { kind: "release" }, { kind: "dispatch" }]);
+    expectEqual((await row(ledger)).progress, { state: "dispatched", call: FROZEN }, "consent releases the frozen call without preparation");
+};
+const dispatch = async ({ store }) => {
+    const { ledger, reopen } = await fixture(store);
+    expectEqual(await ledger.apply(command({ kind: "dispatch" })), { status: "refused", reason: "invalid_transition" }, "no dispatch without release");
+    await runEvents(ledger, DISPATCH);
+    expectEqual((await (await reopen()).apply(command({ kind: "dispatch" }))).status, "replayed", "durable dispatch is never granted twice");
+    expectEqual((await ledger.admit(ADMISSION)).status, "replayed", "invoke replay");
+};
+const cancelFirst = async ({ store }) => {
+    for (const before of [[], PREPARE.slice(0, 2), DISPATCH]) {
+        const { ledger, store: durable, reopen } = await fixture(store);
+        await runEvents(ledger, before);
+        await ledger.apply(command({ kind: "cancel" }));
+        const terminal = await row(ledger);
+        expectEqual(terminal.progress, {
+            state: "settled",
+            outcome: { reason: "cancelled", hooksRan: before.length > 0, uncertain: before.length > 0 },
+        }, "cancel projection follows the effect boundary");
+        await ledger.apply(command({ kind: "result", value: "late" }));
+        expectEqual(await row(await reopen()), terminal, "late result cannot replace cancellation");
+        expectEqual((await durable.scanRecords({ kind: "execution.audit" })).length, 1, "late result is audited");
+    }
+};
+const resultFirst = async ({ store }) => {
+    const { ledger, reopen } = await fixture(store);
+    await runEvents(ledger, DISPATCH);
+    await ledger.apply(command({ kind: "result", value: { content: "done" } }));
+    const terminal = await row(ledger);
+    await ledger.apply(command({ kind: "cancel" }));
+    expectEqual(await row(await reopen()), terminal, "result-first is immutable");
+    for (const kind of ["release", "abort", "consent"]) {
+        expectEqual(await ledger.apply(command({ kind })), { status: "refused", reason: "terminal" }, `${kind} on terminal`);
+    }
+};
+export const LEDGER_CASES = new Map([
+    ["LEDGER-01", identity],
+    ["LEDGER-02", preparation],
+    ["LEDGER-03", consent],
+    ["LEDGER-04", dispatch],
+    ["LEDGER-05", cancelFirst],
+    ["LEDGER-06", resultFirst],
+    ...LEDGER_RECOVERY_CASES,
+]);
+//# sourceMappingURL=ledger-cases.js.map

package/dist/execution/testing/ledger-harness.d.ts

@@ -0,0 +1,26 @@
+import type { DurableStore, DurableStoreOptions } from "../../durable/store.ts";
+import { type StoreConformanceAdapter } from "../../durable/testing/store-harness.ts";
+import { type ExecutionLedger } from "../ledger.ts";
+import type { ExecutionAdmission, ExecutionCommand, ExecutionEntry, ExecutionEvent, LedgerReply } from "../ledger-types.ts";
+export declare const ADMISSION: ExecutionAdmission;
+export declare const FROZEN: {
+    readonly name: "read";
+    readonly args: {
+        readonly path: "a";
+    };
+    readonly digest: "frozen";
+};
+export declare const PREPARE: readonly ExecutionEvent[];
+export declare const DISPATCH: readonly ExecutionEvent[];
+export declare function command(event: ExecutionEvent, now?: number): ExecutionCommand;
+export declare function accepted(reply: LedgerReply): ExecutionEntry;
+export declare function ledgerOn(store: DurableStore, epoch?: number): ExecutionLedger;
+export declare function fixture(adapter: StoreConformanceAdapter, input?: ExecutionAdmission): Promise<{
+    medium: string;
+    store: DurableStore;
+    ledger: ExecutionLedger;
+    reopen: (options?: DurableStoreOptions) => Promise<ExecutionLedger>;
+}>;
+export declare function runEvents(ledger: ExecutionLedger, events: readonly ExecutionEvent[]): Promise<void>;
+export declare function row(ledger: ExecutionLedger): Promise<ExecutionEntry>;
+//# sourceMappingURL=ledger-harness.d.ts.map

package/dist/execution/testing/ledger-harness.js

@@ -0,0 +1,58 @@
+import { createAdmissionLine } from "../../durable/store-admission.js";
+import { claimedStore } from "../../durable/testing/store-cases.js";
+import { expectEqual } from "../../durable/testing/store-harness.js";
+import { createExecutionLedger } from "../ledger.js";
+export const ADMISSION = {
+    issuer: "brain",
+    commandId: "call",
+    executor: "hand",
+    workspace: "workspace",
+    scope: "scope",
+    generation: 1,
+    requestDigest: "raw",
+    admittedAt: 100,
+    leaseUntil: 60_100,
+    reconcilable: false,
+};
+export const FROZEN = { name: "read", args: { path: "a" }, digest: "frozen" };
+export const PREPARE = [
+    { kind: "prepare" },
+    { kind: "effect" },
+    { kind: "freeze", call: FROZEN, awaitingConsent: false },
+];
+export const DISPATCH = [...PREPARE, { kind: "release" }, { kind: "dispatch" }];
+export function command(event, now = 101) {
+    const issuer = ["consent", "release", "abort", "ack", "renew", "cancel"].includes(event.kind);
+    return { key: ADMISSION, generation: 1, actor: { id: issuer ? "brain" : "hand" }, now, event };
+}
+export function accepted(reply) {
+    if (reply.status !== "applied" && reply.status !== "replayed") {
+        throw new Error(`expected an execution row, got ${JSON.stringify(reply)}`);
+    }
+    return reply.entry;
+}
+export function ledgerOn(store, epoch = 1) {
+    return createExecutionLedger({ store, epoch, admission: createAdmissionLine() });
+}
+export async function fixture(adapter, input = ADMISSION) {
+    const { medium, store } = await claimedStore(adapter);
+    const ledger = ledgerOn(store);
+    expectEqual((await ledger.admit(input)).status, "applied", "admitted");
+    return {
+        medium,
+        store,
+        ledger,
+        reopen: async (options) => ledgerOn(await adapter.open(medium, options)),
+    };
+}
+export async function runEvents(ledger, events) {
+    for (const event of events)
+        expectEqual((await ledger.apply(command(event))).status, "applied", event.kind);
+}
+export async function row(ledger) {
+    const entry = await ledger.read(ADMISSION);
+    if (entry === undefined)
+        throw new Error("the admitted execution disappeared");
+    return entry;
+}
+//# sourceMappingURL=ledger-harness.js.map

package/dist/execution/testing/ledger-recovery-cases.d.ts

@@ -0,0 +1,6 @@
+import type { CaseImplementation } from "../../conformance/runner.ts";
+import { type StoreCaseAdapters } from "../../durable/testing/store-harness.ts";
+type LedgerCase = CaseImplementation<StoreCaseAdapters>;
+export declare const LEDGER_RECOVERY_CASES: ReadonlyMap<string, LedgerCase>;
+export {};
+//# sourceMappingURL=ledger-recovery-cases.d.ts.map

package/dist/execution/testing/ledger-recovery-cases.js

@@ -0,0 +1,108 @@
+import { expectEqual, expectStoreError } from "../../durable/testing/store-harness.js";
+import { MAX_EXECUTION_LIFETIME_MS } from "../ledger-types.js";
+import { accepted, ADMISSION, command, DISPATCH, fixture, FROZEN, ledgerOn, PREPARE, row, runEvents, } from "./ledger-harness.js";
+const renewal = async ({ store }) => {
+    const { ledger } = await fixture(store);
+    const renew = { kind: "renew", seq: 1, leaseUntil: 100_000 };
+    expectEqual(await ledger.apply({ ...command(renew), actor: { id: "hand" } }), { status: "refused", reason: "unauthorized" }, "issuer-only renewal");
+    expectEqual((await ledger.apply(command(renew))).status, "applied", "renewal starts at admission");
+    expectEqual((await ledger.apply(command(renew))).status, "replayed", "duplicate renewal");
+    expectEqual(await ledger.apply(command({ ...renew, seq: 2, leaseUntil: ADMISSION.admittedAt + MAX_EXECUTION_LIFETIME_MS + 1 })), { status: "refused", reason: "invalid_renewal" }, "24-hour cap");
+    expectEqual(await ledger.apply(command({ ...renew, seq: 2, leaseUntil: 90_000 })), { status: "refused", reason: "invalid_renewal" }, "lease cannot shrink");
+    await ledger.apply(command({ kind: "cancel" }));
+    const terminal = await row(ledger);
+    expectEqual(accepted(await ledger.apply(command({ ...renew, seq: 3 }))), terminal, "terminal renewal returns stored outcome");
+};
+const acknowledgement = async ({ store }) => {
+    const { ledger, reopen } = await fixture(store);
+    expectEqual(await ledger.apply(command({ kind: "ack" })), { status: "refused", reason: "invalid_transition" }, "early ACK");
+    await ledger.apply(command({ kind: "cancel" }));
+    expectEqual(await ledger.apply({ ...command({ kind: "ack" }), actor: { id: "other" } }), { status: "refused", reason: "unauthorized" }, "issuer-only ACK");
+    await ledger.apply(command({ kind: "ack" }));
+    const reopened = await reopen();
+    expectEqual((await reopened.apply(command({ kind: "ack" }))).status, "replayed", "duplicate ACK");
+    expectEqual(await reopened.admit(ADMISSION), { status: "result_expired" }, "dedup after ACK");
+    expectEqual((await row(reopened)).progress, { state: "acked" }, "payload removed, identity retained");
+};
+const preparingRestart = async ({ store }) => {
+    for (const effects of [false, true]) {
+        const { ledger, reopen } = await fixture(store);
+        await runEvents(ledger, PREPARE.slice(0, effects ? 2 : 1));
+        const reopened = await reopen();
+        await reopened.recover(102);
+        expectEqual((await row(reopened)).progress, {
+            state: "settled",
+            outcome: { reason: "hand_restarted", hooksRan: effects, uncertain: effects },
+        }, "preparing never reruns after restart");
+        expectEqual((await reopened.apply(command({ kind: "prepare" }, 103))).status, "replayed", "no new preparation permission");
+    }
+};
+const preparedRestart = async ({ store }) => {
+    for (const state of ["prepared", "prepared_awaiting_consent", "released"]) {
+        const { ledger, reopen } = await fixture(store);
+        await runEvents(ledger, [
+            ...PREPARE.slice(0, 2),
+            { kind: "freeze", call: FROZEN, awaitingConsent: state === "prepared_awaiting_consent" },
+        ]);
+        if (state === "released")
+            await ledger.apply(command({ kind: "release" }));
+        const reopened = await reopen();
+        await reopened.recover(102);
+        expectEqual((await row(reopened)).progress, { state, call: FROZEN }, "frozen state survives restart");
+    }
+};
+const reconciliation = async ({ store }) => {
+    for (const reconcilable of [false, true]) {
+        const { ledger, reopen } = await fixture(store, { ...ADMISSION, reconcilable });
+        await runEvents(ledger, DISPATCH);
+        const reopened = await reopen();
+        await reopened.recover(102);
+        if (!reconcilable) {
+            expectEqual((await row(reopened)).progress, { state: "settled", outcome: { reason: "hand_restarted", hooksRan: true, uncertain: true } }, "unreconcilable dispatch");
+            continue;
+        }
+        expectEqual((await row(reopened)).progress, { state: "reconciling", call: FROZEN, until: 30_102 }, "30-second grace");
+        await reopened.recover(103);
+        expectEqual((await row(reopened)).progress, { state: "reconciling", call: FROZEN, until: 30_102 }, "another restart cannot extend grace");
+        await reopened.apply(command({ kind: "expire" }, 30_102));
+        expectEqual((await row(reopened)).progress.state, "settled", "grace deadline settles without dispatching again");
+    }
+    const { ledger, reopen } = await fixture(store, { ...ADMISSION, reconcilable: true });
+    await runEvents(ledger, DISPATCH);
+    const restarted = await reopen();
+    await restarted.recover(102);
+    await restarted.apply(command({ kind: "result", value: "reconciled" }, 103));
+    expectEqual((await row(restarted)).progress, { state: "settled", outcome: { reason: "result", value: "reconciled", hooksRan: true, uncertain: false } }, "authoritative reconciliation resolves uncertainty");
+};
+const expiryAndFencing = async ({ store }) => {
+    const { ledger, store: durable, medium } = await fixture(store);
+    await runEvents(ledger, PREPARE);
+    const expired = accepted(await ledger.apply(command({ kind: "release" }, ADMISSION.leaseUntil)));
+    expectEqual(expired.progress, { state: "settled", outcome: { reason: "lease_expired", hooksRan: true, uncertain: true } }, "lease reason retained at boundary");
+    const next = await store.open(medium);
+    await next.claim(1, 2);
+    await expectStoreError(ledger.admit({ ...ADMISSION, commandId: "old" }), "stale-epoch", "old owner cannot admit");
+    const current = ledgerOn(next, 2);
+    expectEqual((await current.admit({ ...ADMISSION, commandId: "new" })).status, "applied", "new owner");
+    expectEqual(await durable.readEpoch(), 2, "fence shared by reopened instances");
+    const { ledger: concurrent } = await fixture(store);
+    const results = await Promise.all([
+        concurrent.apply(command({ kind: "prepare" })),
+        concurrent.apply(command({ kind: "prepare" })),
+    ]);
+    expectEqual(results.map((reply) => reply.status), ["applied", "replayed"], "one preparation grant under concurrency");
+    expectEqual(await concurrent.apply({ ...command({ kind: "cancel" }), actor: { id: "approver", approvedWorkspace: "wrong" } }), { status: "refused", reason: "unauthorized" }, "approval cannot cross workspaces");
+    expectEqual((await concurrent.apply({
+        ...command({ kind: "cancel" }),
+        actor: { id: "approver", approvedWorkspace: ADMISSION.workspace },
+    })).status, "applied", "workspace approver may cancel");
+};
+export const LEDGER_RECOVERY_CASES = new Map([
+    ["LEDGER-07", renewal],
+    ["LEDGER-08", acknowledgement],
+    ["LEDGER-09", preparingRestart],
+    ["LEDGER-10", preparedRestart],
+    ["LEDGER-11", reconciliation],
+    ["LEDGER-12", expiryAndFencing],
+]);
+//# sourceMappingURL=ledger-recovery-cases.js.map

package/dist/execution/testing/ledger-registry.d.ts

@@ -0,0 +1,3 @@
+import type { RegisteredCase } from "../../conformance/registry.ts";
+export declare const LEDGER_REGISTRY: readonly RegisteredCase[];
+//# sourceMappingURL=ledger-registry.d.ts.map

package/dist/execution/testing/ledger-registry.js

@@ -0,0 +1,34 @@
+import { KILL_LEDGER_DECLARATIONS } from "./kill-ledger.js";
+const expectations = [
+    "identity and generation are bound; replay never re-admits",
+    "effect_possible is durable before preparation effects and freeze",
+    "consent waits on the frozen call; unauthorized approval is refused",
+    "dispatch requires release and is granted at most once",
+    "cancel-first stays terminal; late result is audit-only",
+    "result-first stays terminal; terminal release, abort and consent are refused",
+    "renewal is issuer-only, monotonic, capped and returns terminal outcomes",
+    "ACK is issuer-only, terminal-only and idempotent; replay after ACK is result_expired",
+    "preparing never reruns after restart; uncertainty follows effect_possible",
+    "prepared, consent-waiting and released calls survive restart",
+    "reconcilable dispatch has one bounded grace; an authoritative result resolves uncertainty",
+    "lease expiry retains its reason; concurrent admissions and owner epochs are fenced",
+];
+export const LEDGER_REGISTRY = [
+    ...expectations.map((expected, index) => ({
+        id: `LEDGER-${String(index + 1).padStart(2, "0")}`,
+        impl: index < 6
+            ? "packages/agent/src/execution/testing/ledger-cases.ts"
+            : "packages/agent/src/execution/testing/ledger-recovery-cases.ts",
+        intro: "#5004",
+        adapters: ["store"],
+        expected,
+    })),
+    ...KILL_LEDGER_DECLARATIONS.map(({ id, operation, point }) => ({
+        id,
+        impl: "packages/agent/src/execution/testing/kill-ledger.ts",
+        intro: "#5004",
+        adapters: ["store"],
+        expected: `everywhere: kill ${point.at}${point.at === "write" ? ` ${point.index}` : ""} ${operation}; journal and row recover atomically, with no repeated dispatch`,
+    })),
+];
+//# sourceMappingURL=ledger-registry.js.map

package/dist/execution/tool-host.d.ts

@@ -0,0 +1,32 @@
+import type { ToolResultMessage } from "@earendil-works/pi-ai";
+import type { AgentEvent, AgentToolCall, ToolExecutionMode } from "../types.ts";
+/** Brain-minted identity and execution root; the executor treats the identity as opaque. */
+export interface ExecutionScope {
+    readonly id: string;
+    readonly root: string;
+}
+/** The raw model calls, before name resolution, argument preparation, validation or hooks. */
+export interface ToolHostCall {
+    readonly scope: ExecutionScope;
+    readonly calls: readonly AgentToolCall[];
+    readonly mode: ToolExecutionMode;
+}
+export interface ExecutionPipelineWitness {
+    readonly pipeline: "legacy" | "prepared";
+    readonly toolCallId: string;
+}
+export interface ToolHostResult {
+    readonly messages: ToolResultMessage[];
+    readonly terminate: boolean;
+}
+export interface ToolHostOptions {
+    readonly signal?: AbortSignal;
+    /** Preserve tool events and ordered result-message events. The loop appends the returned messages to context. */
+    readonly emit: (event: AgentEvent) => Promise<void> | void;
+    /** Receipt metadata only: never an AgentEvent, tool result, provider payload or EQ observable. */
+    readonly recordWitness?: (witness: ExecutionPipelineWitness) => Promise<void> | void;
+}
+export interface ToolHost {
+    execute(call: ToolHostCall, options: ToolHostOptions): Promise<ToolHostResult>;
+}
+//# sourceMappingURL=tool-host.d.ts.map

package/dist/execution/tool-host.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tool-host.js.map

package/dist/types.d.ts

@@ -1,5 +1,7 @@
 import type { Api, AssistantMessage, AssistantMessageEvent, AssistantMessageEventStream, CursorExecHandlers, ImageContent, JsonValue, Message, Model, ProviderDiagnostic, SimpleStreamOptions, TextContent, ThinkingSelection, Tool, ToolResultMessage, TranscriptContext, Usage } from "@earendil-works/pi-ai";
 import type { Static, TSchema } from "typebox";
+import type { ExecutionPipelineWitness, ExecutionScope, ToolHost } from "./execution/tool-host.ts";
+export type { ExecutionPipelineWitness, ExecutionScope, ToolHost, ToolHostCall, ToolHostOptions, ToolHostResult, } from "./execution/tool-host.ts";
 /**
  * Stream function used by the agent loop. `Models.streamSimple` satisfies
  * this shape.
@@ -322,6 +324,10 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * Default: "parallel"
      */
     toolExecution?: ToolExecutionMode;
+    /** Unprepared batch boundary. Omitted selects the existing in-process legacy scheduler. */
+    toolHost?: ToolHost;
+    executionScope?: ExecutionScope;
+    onExecutionPipeline?: (witness: ExecutionPipelineWitness) => Promise<void> | void;
     /**
      * Optional migration guidance for tool names intentionally removed by an extension.
      * The matching hint is appended to the normal unknown-tool error before hooks run.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/senpi-agent-core",
-	"version": "2026.10.31-1",
+	"version": "2026.11.02-1",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -70,8 +70,8 @@
 	},
 	"dependencies": {
 		"@earendil-works/chord": "0.99.1",
-		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.31-1",
-		"@earendil-works/pi-telemetry": "npm:@code-yeongyu/senpi-telemetry@2026.10.31-1",
+		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.11.02-1",
+		"@earendil-works/pi-telemetry": "npm:@code-yeongyu/senpi-telemetry@2026.11.02-1",
 		"diff": "9.0.0",
 		"ignore": "7.0.9",
 		"typebox": "1.3.34",