perf(storage): read one invocation by run id

`readRunIfPresent`, `readInvocationIfPresent` and
`SessionManager.readInvocation` had become `listSessionInvocations()`
followed by `find`, and a Turn calls them four to six times. The header
era answered these with a keyed row read.

`RuntimeEventStore` gains an optional `readRunInvocation(sessionId,
runId)`; the SQLite store answers it off the opening index, and a helper
in core answers it from the inventory for stores that do not implement
it, so callers state one intent either way.

Generated-by: Claude Code

Author: Astro-Han

packages/core/src/runtime-event-store.ts

@@ -82,6 +82,15 @@ export interface RuntimeEventStore {
    * fact and therefore never appear here.
    */
   listSessionInvocations(sessionId: string): Promise<RuntimeInvocationRecord[]>;
+  /**
+   * One invocation by run id, absent when no opening fact names it. A store
+   * that indexes openings answers this in one read; stores without the fast
+   * path are answered from the inventory by `readRunInvocation`.
+   */
+  readRunInvocation?(
+    sessionId: string,
+    runId: string,
+  ): Promise<RuntimeInvocationRecord | undefined>;
   appendRuntimeEvent(
     sessionId: string,
     runId: string,
@@ -121,6 +130,18 @@ export interface RuntimeEventStore {
   readSessionRuntimeEvents(sessionId: string): Promise<RuntimeEvent[]>;
 }
 
+/** One invocation by run id, through the store's fast path when it has one. */
+export async function readRunInvocation(
+  store: Pick<RuntimeEventStore, 'listSessionInvocations' | 'readRunInvocation'>,
+  sessionId: string,
+  runId: string,
+): Promise<RuntimeInvocationRecord | undefined> {
+  if (store.readRunInvocation) return store.readRunInvocation(sessionId, runId);
+  return (await store.listSessionInvocations(sessionId)).find(
+    (invocation) => invocation.runId === runId,
+  );
+}
+
 export interface RuntimeRecoveryBundleStore extends RuntimeEventStore {
   readonly recoveryBundleCapability: typeof TOOL_RECOVERY_BUNDLE_CAPABILITY_V1;
   commitToolRecoveryBundle(input: RuntimeRecoveryBundleCommit): Promise<void>;

packages/runtime-host/src/server/canonical-turn-snapshot.ts

@@ -20,6 +20,7 @@
 import { type ContextCompactionOutcome } from '@maka/core/events';
 import { truncateUtf8 } from '@maka/core/diagnostic-log';
 import { redactSecrets } from '@maka/core/redaction';
+import { readRunInvocation } from '@maka/core/runtime-event-store';
 import type { RuntimeInvocationRecord } from '@maka/core/runtime-invocation';
 import { classifyTerminalRuntimeLedger } from '@maka/runtime/terminal-run-commit';
 import type { ExecutionStoresWriter } from '@maka/storage/execution-stores';
@@ -152,9 +153,7 @@ async function readInvocationIfPresent(
   runId: string,
 ): Promise<RuntimeInvocationRecord | undefined> {
   try {
-    return (await stores.runtimeEventStore.listSessionInvocations(sessionId)).find(
-      (invocation) => invocation.runId === runId,
-    );
+    return await readRunInvocation(stores.runtimeEventStore, sessionId, runId);
   } catch (error) {
     if (isMissingFile(error)) return undefined;
     throw error;

packages/runtime-host/src/server/hosted-execution-projection.ts

@@ -23,6 +23,7 @@ import {
   type RuntimeInvocationRecord,
 } from '@maka/core/runtime-invocation';
 import { RuntimeMessageAuthorityInvariantError } from '@maka/runtime/message-authority';
+import { readRunInvocation } from '@maka/core/runtime-event-store';
 import type { ExecutionStoresWriter } from '@maka/storage/execution-stores';
 import { readCanonicalTurnSnapshot } from './canonical-turn-snapshot.js';
 import type { HostedExecutionRef, HostedExecutionSnapshot } from './hosted-execution-authority.js';
@@ -48,9 +49,7 @@ export class HostedExecutionProjectionReader {
     runId: string,
   ): Promise<RuntimeInvocationRecord | undefined> {
     try {
-      return (await this.stores.runtimeEventStore.listSessionInvocations(sessionId)).find(
-        (invocation) => invocation.runId === runId,
-      );
+      return await readRunInvocation(this.stores.runtimeEventStore, sessionId, runId);
     } catch (error) {
       if (isMissingFile(error)) return undefined;
       throw error;

packages/runtime/src/session-manager.ts

@@ -122,9 +122,10 @@ import type { AgentRunEvent, AgentRunStore } from '@maka/core/agent-run';
 import type { ArtifactRecord } from '@maka/core/artifacts';
 import { invocationMatchesClaimTarget } from '@maka/core/runtime-boundary';
 import type { ContinuationClaimV1 } from '@maka/core/runtime-boundary';
-import type {
-  RuntimeEventStore,
-  RuntimeContinuationAuthorityStore,
+import {
+  readRunInvocation,
+  type RuntimeEventStore,
+  type RuntimeContinuationAuthorityStore,
 } from '@maka/core/runtime-event-store';
 import type {
   RuntimeEvent,
@@ -1057,9 +1058,8 @@ export class SessionManager {
 
   /** One invocation by run id. Absent means no opening fact ever named it. */
   private async readInvocation(sessionId: string, runId: string): Promise<RuntimeInvocationRecord> {
-    const invocation = (await this.listInvocations(sessionId)).find(
-      (candidate) => candidate.runId === runId,
-    );
+    const store = this.deps.runtimeEventStore;
+    const invocation = store ? await readRunInvocation(store, sessionId, runId) : undefined;
     if (!invocation) {
       const error = new Error(`AgentRun ${runId} not found`) as Error & { code?: string };
       error.code = 'ENOENT';

packages/storage/src/agent-run-store.ts

@@ -271,6 +271,7 @@ export type RuntimeEventScanResult = { readonly status: 'complete' | 'limit_exce
 
 export interface DurableRuntimeEventStore extends RuntimeEventStore {
   listSessionInvocations(sessionId: string): Promise<RuntimeInvocationRecord[]>;
+  readRunInvocation(sessionId: string, runId: string): Promise<RuntimeInvocationRecord | undefined>;
   listSessionInvocationsBounded(
     sessionId: string,
     limit: number,

packages/storage/src/execution-stores.ts

@@ -206,6 +206,7 @@ export interface ExecutionRuntimeEventReader {
    * repairs it.
    */
   listSessionInvocations(sessionId: string): Promise<RuntimeInvocationRecord[]>;
+  readRunInvocation(sessionId: string, runId: string): Promise<RuntimeInvocationRecord | undefined>;
   listSessionInvocationsBounded(
     sessionId: string,
     limit: number,
@@ -552,6 +553,8 @@ async function createExecutionStoresForWrite<K extends StorageRootKind, E extend
         run(() => runtimeEventStore.readImmutableRuntimePrefix(input)),
       listSessionInvocations: (sessionId) =>
         run(() => runtimeEventStore.listSessionInvocations(sessionId)),
+      readRunInvocation: (sessionId, runId) =>
+        run(() => runtimeEventStore.readRunInvocation(sessionId, runId)),
       listSessionInvocationsBounded: (sessionId, limit) =>
         run(() => runtimeEventStore.listSessionInvocationsBounded(sessionId, limit)),
       listSessionInvocationsPage: (sessionId, input) =>
@@ -665,6 +668,8 @@ async function openExecutionStoresForRead<K extends StorageRootKind, E extends o
         run(() => runtimeEventStore.readImmutableRuntimeEvents(sessionId, runId)),
       listSessionInvocations: (sessionId) =>
         run(() => runtimeEventStore.listSessionInvocations(sessionId)),
+      readRunInvocation: (sessionId, runId) =>
+        run(() => runtimeEventStore.readRunInvocation(sessionId, runId)),
       listSessionInvocationsBounded: (sessionId, limit) =>
         run(() => runtimeEventStore.listSessionInvocationsBounded(sessionId, limit)),
       listSessionInvocationsPage: (sessionId, input) =>

packages/storage/src/runtime-event-persistence.ts

@@ -47,6 +47,7 @@ export type RuntimeEventReadPersistence = {
 
 export interface RuntimeEventReadStore {
   listSessionInvocations(sessionId: string): Promise<RuntimeInvocationRecord[]>;
+  readRunInvocation(sessionId: string, runId: string): Promise<RuntimeInvocationRecord | undefined>;
   listSessionInvocationsBounded(
     sessionId: string,
     limit: number,
@@ -96,6 +97,8 @@ export async function openRuntimeEventReadPersistence(input: {
     kind: 'sqlite',
     runtimeEventStore: Object.freeze({
       listSessionInvocations: (sessionId: string) => store.listSessionInvocations(sessionId),
+      readRunInvocation: (sessionId: string, runId: string) =>
+        store.readRunInvocation(sessionId, runId),
       listSessionInvocationsBounded: (sessionId: string, limit: number) =>
         store.listSessionInvocationsBounded(sessionId, limit),
       listSessionInvocationsPage: (sessionId: string, input: RuntimeInvocationPageInput) =>

packages/storage/src/sqlite-runtime-store.ts

@@ -555,6 +555,18 @@ export class SqliteRuntimeStore
     );
   }
 
+  async readRunInvocation(
+    sessionId: string,
+    runId: string,
+  ): Promise<RuntimeInvocationRecord | undefined> {
+    assertRuntimeStorageSafeId(sessionId, 'Invalid session id');
+    assertRuntimeStorageSafeId(runId, 'Invalid run id');
+    return this.readTransaction(() => {
+      const row = this.readInvocationOpeningsSync(sessionId, { direction: 'asc', runId }).at(0);
+      return row ? this.completeInvocationRecordSync(row) : undefined;
+    });
+  }
+
   /**
    * The first page of a Session's invocations, plus whether more exist.
    *
@@ -646,6 +658,7 @@ export class SqliteRuntimeStore
       limit?: number;
       before?: RuntimeInvocationPageCursor;
       invocationId?: string;
+      runId?: string;
     },
   ): Omit<RuntimeInvocationRecord, 'terminalEvent'>[] {
     const order = options.direction === 'desc' ? 'DESC' : 'ASC';
@@ -680,6 +693,7 @@ export class SqliteRuntimeStore
             )
         )
         WHERE (:invocationId IS NULL OR invocation_id = :invocationId)
+          AND (:runId IS NULL OR run_id = :runId)
           AND (
             :beforeOpenedAt IS NULL
             OR opened_at < :beforeOpenedAt
@@ -691,6 +705,7 @@ export class SqliteRuntimeStore
       .all({
         sessionId,
         invocationId: options.invocationId ?? null,
+        runId: options.runId ?? null,
         beforeOpenedAt: options.before?.openedAt ?? null,
         beforeInvocationId: options.before?.invocationId ?? null,
         limit: options.limit ?? -1,