refactor(runtime): hold the test doubles to the seal, and name corruption

Two terminal events was classified as `ambiguous`. Nothing is ambiguous
about it: a store seals a run on its first terminal, so a second one means
the ledger was written around the seal. It is `corrupt`, and the strict
recovery error now says what it found rather than that it was unsure.

The seal itself was an obligation only one double honoured, which is what
let that state look reachable in the first place. It is stated once now and
used by every RuntimeEventStore double, so a double cannot drift from the
SQLite store or from the interface.

Six fixtures were appending to a finished run through the API that forbids
it, using append as a way to write into the ledger rather than to test the
seal. They now seed the double directly, which is where a ledger shape no
supported store can produce belongs.

Generated-by: Claude Code

Author: Astro-Han

packages/runtime/src/__tests__/agent-run-inspect.test.ts

@@ -29,6 +29,7 @@ import {
 } from '@maka/core/runtime-invocation';
 import { inspectAgentRunReadModel } from '../agent-run-inspect.js';
 import { testInvocationOpening } from './invocation-fixture.js';
+import { assertDoubleRunNotSealed } from './runtime-event-store-seal.js';
 
 const sessionId = 'session-1';
 const invocationId = 'inv-1';
@@ -186,6 +187,7 @@ class MemoryAgentRunStore implements AgentRunStore, RuntimeEventStore {
 
   async appendRuntimeEvent(sessionId: string, runId: string, event: RuntimeEvent): Promise<void> {
     const eventKey = key(sessionId, runId);
+    assertDoubleRunNotSealed(this.runtimeEvents.get(eventKey) ?? [], event);
     this.runtimeEvents.set(eventKey, [
       ...(this.runtimeEvents.get(eventKey) ?? []),
       copyRuntimeEvent(event),

packages/runtime/src/__tests__/runtime-event-store-seal.ts

@@ -0,0 +1,43 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { isTerminalRuntimeEvent } from '@maka/core/runtime-event';
+import type { RuntimeEvent } from '@maka/core/runtime-event';
+import { RunSealedError } from '@maka/core/runtime-event-store';
+
+/**
+ * The seal every `RuntimeEventStore` owes its callers, for the doubles.
+ *
+ * `RuntimeEventStore` requires an implementation to refuse any new event on a
+ * run that already holds a terminal one. A double that skips it manufactures a
+ * ledger no supported store can produce, and a test built on that ledger proves
+ * nothing about production. Stated here once so the doubles cannot drift apart
+ * from each other or from the SQLite store.
+ *
+ * A test that genuinely needs a corrupt ledger should assemble it underneath the
+ * store rather than appending through it.
+ */
+export function assertDoubleRunNotSealed(
+  storedEvents: readonly RuntimeEvent[],
+  incoming: RuntimeEvent,
+): void {
+  // An exact-id replay is idempotent: the event is already inside the seal.
+  if (storedEvents.some((event) => event.id === incoming.id)) return;
+  if (storedEvents.some(isTerminalRuntimeEvent)) throw new RunSealedError(incoming.runId);
+}

packages/runtime/src/__tests__/session-manager-terminal-ledger.test.ts

@@ -63,6 +63,7 @@ import { RuntimeReadModel } from '../runtime-read-model.js';
 import { RuntimeKernel } from '../runtime-kernel.js';
 import type { RuntimeInteractionAuthority } from '../interaction-authority.js';
 import { testInvocationOpening } from './invocation-fixture.js';
+import { assertDoubleRunNotSealed } from './runtime-event-store-seal.js';
 
 describe('SessionManager terminal ledger invariants', () => {
   test('coalesces one partial stream and flushes it before the final model event', async () => {
@@ -1042,7 +1043,7 @@ describe('SessionManager terminal ledger invariants', () => {
       }),
     ]);
 
-    assert.strictEqual(result.kind, 'ambiguous');
+    assert.strictEqual(result.kind, 'corrupt');
     assert.deepStrictEqual(
       result.terminalEvents.map((event) => event.id),
       ['rt-completed', 'rt-failed'],
@@ -2394,6 +2395,7 @@ class BatchingRuntimeEventStore implements RuntimeEventStore {
   constructor(private readonly failPartialBatch = false) {}
 
   async appendRuntimeEvent(_sessionId: string, _runId: string, event: RuntimeEvent): Promise<void> {
+    assertDoubleRunNotSealed(this.events, event);
     this.order.push(`append:${event.id}`);
     this.events.push(clone(event));
   }

packages/runtime/src/__tests__/session-manager.test.ts

@@ -91,6 +91,7 @@ import type {
 import { PlanConflictError, emptyPlanSessionState, type PlanStore } from '@maka/core/plan';
 import { MockLanguageModelV4, simulateReadableStream } from 'ai/test';
 import { createTestAiSdkBackend } from './execution-boundary-test-helpers.js';
+import { assertDoubleRunNotSealed } from './runtime-event-store-seal.js';
 import type { LanguageModelV4StreamPart } from '@ai-sdk/provider';
 import { z } from 'zod';
 import { AiSdkBackend } from '../ai-sdk-backend.js';
@@ -6011,7 +6012,7 @@ describe('SessionManager permission mode updates', () => {
 
     const targetRunId = firstPlan.continuation.runId;
     const targetRun = await readInvocation(runStore, session.id, targetRunId);
-    await runStore.appendRuntimeEvent(
+    runStore.seedRuntimeEvent(
       session.id,
       targetRunId,
       runtimeEvent({
@@ -6708,7 +6709,7 @@ describe('SessionManager permission mode updates', () => {
     });
     if (!plan.continuation) throw new Error('expected continuation');
 
-    await runStore.appendRuntimeEvent(
+    runStore.seedRuntimeEvent(
       session.id,
       sourceRunId,
       runtimeEvent({
@@ -10053,7 +10054,7 @@ describe('SessionManager permission mode updates', () => {
           ts: 120 + index,
         }),
       );
-      await runStore.appendRuntimeEvent(
+      runStore.seedRuntimeEvent(
         session.id,
         'child-run',
         runtimeEvent({
@@ -10122,7 +10123,7 @@ describe('SessionManager permission mode updates', () => {
         permissionMode: 'explore',
       }),
     );
-    await runStore.appendRuntimeEvent(
+    runStore.seedRuntimeEvent(
       session.id,
       'child-run',
       runtimeEvent({
@@ -10136,7 +10137,7 @@ describe('SessionManager permission mode updates', () => {
         content: { kind: 'text', text: 'x'.repeat(64 * 1024) },
       }),
     );
-    await runStore.appendRuntimeEvent(
+    runStore.seedRuntimeEvent(
       session.id,
       'child-run',
       runtimeEvent({
@@ -10467,7 +10468,7 @@ describe('SessionManager permission mode updates', () => {
     }
 
     const [run] = await runStore.listSessionInvocations(session.id);
-    await runStore.appendRuntimeEvent(
+    runStore.seedRuntimeEvent(
       session.id,
       run!.runId,
       runtimeEvent({
@@ -13185,6 +13186,17 @@ class MemoryAgentRunStore
       this.options.failRuntimeEventAppendAfter = undefined;
       throw new Error('runtime event append failed');
     }
+    assertDoubleRunNotSealed(this.runtimeEvents.get(key(sessionId, runId)) ?? [], event);
+    this.seedRuntimeEvent(sessionId, runId, event);
+  }
+
+  /**
+   * Put an event into the ledger underneath the seal.
+   *
+   * A test that needs a ledger shape the store would refuse to write has to
+   * assemble it below the store, not through the API whose contract forbids it.
+   */
+  seedRuntimeEvent(sessionId: string, runId: string, event: RuntimeEvent): void {
     const eventKey = key(sessionId, runId);
     this.runtimeEvents.set(eventKey, [
       ...(this.runtimeEvents.get(eventKey) ?? []),
@@ -13566,6 +13578,17 @@ class MemoryRuntimeEventStore implements RuntimeEventStore {
 
   async appendRuntimeEvent(sessionId: string, runId: string, event: RuntimeEvent): Promise<void> {
     if (this.options.failRuntimeEventAppends) throw new Error('runtime event append failed');
+    assertDoubleRunNotSealed(this.runtimeEvents.get(key(sessionId, runId)) ?? [], event);
+    this.seedRuntimeEvent(sessionId, runId, event);
+  }
+
+  /**
+   * Put an event into the ledger underneath the seal.
+   *
+   * A test that needs a ledger shape the store would refuse to write has to
+   * assemble it below the store, not through the API whose contract forbids it.
+   */
+  seedRuntimeEvent(sessionId: string, runId: string, event: RuntimeEvent): void {
     const eventKey = key(sessionId, runId);
     this.runtimeEvents.set(eventKey, [
       ...(this.runtimeEvents.get(eventKey) ?? []),

packages/runtime/src/session-manager.ts

@@ -4592,9 +4592,11 @@ export class SessionManager {
         }
       }
       const terminalLedger = classifyTerminalRuntimeLedger(run, inspected.runtimeEvents);
-      if (terminalLedger.kind === 'ambiguous') {
+      if (terminalLedger.kind === 'corrupt') {
         if (policy.kind === 'strict') {
-          throw new Error(`RuntimeEvent ledger has ambiguous terminal facts for run ${run.runId}`);
+          throw new Error(
+            `RuntimeEvent ledger has more than one terminal event for run ${run.runId}`,
+          );
         }
         continue;
       }

packages/runtime/src/terminal-run-commit.ts

@@ -47,7 +47,12 @@ export type TerminalRuntimeLedgerClassification =
       terminalEvents: readonly RuntimeEvent[];
     }
   | {
-      kind: 'ambiguous';
+      /**
+       * More than one terminal event. Nothing ambiguous about it: a store seals
+       * a run on its first terminal, so a second one means the ledger was
+       * written around that seal and is corrupt.
+       */
+      kind: 'corrupt';
       terminalEvents: readonly RuntimeEvent[];
     };
 
@@ -60,7 +65,7 @@ export function classifyTerminalRuntimeLedger(
     return { kind: 'none', terminalEvents };
   }
   if (terminalEvents.length > 1) {
-    return { kind: 'ambiguous', terminalEvents };
+    return { kind: 'corrupt', terminalEvents };
   }
 
   const fact = classifyRuntimeEventTerminalFact(run, events).fact;