feat(runtime): admit cross-epoch graph results (#2992)

- persist typed selected_result_inputs with the source graph identity for scheduled work
- admit only committed results selected by a finished earlier epoch of the same root Session
- revalidate historical inputs during recovery and hydrate them with explicit graph provenance
- page historical result discovery without reusing old operators, claims, routes, or control state

Historical results cross the epoch boundary as immutable data only. Runtime Host authorization verifies the root, epoch ordering, finished schedule selection, and exact RuntimeEvent-backed record before the schedule is committed; recovery performs the same resolution again. Input counts and discovery pages are bounded, and ambiguous current/historical record identities fail closed.

Generated-by: Maka

Author: me2seeks

apps/desktop/src/main/__tests__/agent-graph-panel.test.ts

@@ -4,10 +4,33 @@ import { parseHTML } from 'linkedom';
 import { act, createElement } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import type { AgentGraphClientSnapshot } from '@maka/runtime/stream-graph-read-model';
+import type { AgentGraphEpochSummary } from '@maka/runtime-host/protocol';
 import { AgentGraphPanel } from '../../renderer/agent-graph-panel.js';
 
 type GraphListener = () => void;
 
+interface DeferredRead {
+  started: Promise<void>;
+  release(): void;
+}
+
+interface DeferredReadGate extends DeferredRead {
+  markStarted(): void;
+  waitForRelease: Promise<void>;
+}
+
+function deferredReadGate(): DeferredReadGate {
+  let markStarted = () => {};
+  let release = () => {};
+  const started = new Promise<void>((resolve) => {
+    markStarted = resolve;
+  });
+  const waitForRelease = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  return { started, markStarted, release, waitForRelease };
+}
+
 const originalGlobals = {
   document: globalThis.document,
   window: globalThis.window,
@@ -59,11 +82,18 @@ function snapshot(
   };
 }
 
-function installGraphRenderer(initial: AgentGraphClientSnapshot): {
+function installGraphRenderer(
+  initial: AgentGraphClientSnapshot,
+  historical: readonly AgentGraphClientSnapshot[] = [],
+): {
   container: Element;
   root: Root;
   setSnapshot(next: AgentGraphClientSnapshot): Promise<void>;
+  evict(graphId: string): void;
   renderSession(sessionId: string): Promise<void>;
+  holdNextEpochList(sessionId: string): DeferredRead;
+  holdNextSnapshot(graphId: string): DeferredRead;
+  stopCalls: string[];
 } {
   const { document, window } = parseHTML('<div id="root"></div>');
   const matchMedia = (media: string) => ({
@@ -88,15 +118,54 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
     IS_REACT_ACT_ENVIRONMENT: true,
   });
 
-  const snapshots = new Map<string, AgentGraphClientSnapshot>([
-    [initial.rootSessionId, initial],
-  ]);
+  const snapshots = new Map(
+    [initial, ...historical].map((entry) => [entry.graphId, entry] as const),
+  );
+  const currentGraphIds = new Map<string, string>();
+  for (const entry of [initial, ...historical]) {
+    if (!currentGraphIds.has(entry.rootSessionId)) {
+      currentGraphIds.set(entry.rootSessionId, entry.graphId);
+    }
+  }
   const listeners = new Set<GraphListener>();
+  const epochListGates = new Map<string, DeferredReadGate>();
+  const snapshotGates = new Map<string, DeferredReadGate>();
+  const stopCalls: string[] = [];
   (window as unknown as { maka: unknown }).maka = {
     graphs: {
-      getSnapshot: async (sessionId: string) => {
-        const next = snapshots.get(sessionId);
-        if (!next) throw new Error(`missing graph snapshot for ${sessionId}`);
+      listEpochs: async (sessionId: string) => {
+        const gate = epochListGates.get(sessionId);
+        if (gate) {
+          epochListGates.delete(sessionId);
+          gate.markStarted();
+          await gate.waitForRelease;
+        }
+        const currentGraphId = currentGraphIds.get(sessionId);
+        const entries = [...snapshots.values()]
+          .filter((entry) => entry.rootSessionId === sessionId)
+          .sort((left, right) => Number(right.graphId === currentGraphId) - Number(left.graphId === currentGraphId));
+        return {
+          epochs: entries.map((entry, index) => ({
+            epoch: entries.length - index,
+            graphId: entry.graphId,
+            createdAt: index + 1,
+            current: currentGraphIds.get(sessionId) === entry.graphId,
+          })),
+          truncated: false,
+        };
+      },
+      getSnapshot: async (sessionId: string, options?: { graphId?: string }) => {
+        const graphId = options?.graphId ?? currentGraphIds.get(sessionId);
+        const gate = graphId ? snapshotGates.get(graphId) : undefined;
+        if (gate && graphId) {
+          snapshotGates.delete(graphId);
+          gate.markStarted();
+          await gate.waitForRelease;
+        }
+        const next = graphId ? snapshots.get(graphId) : undefined;
+        if (!next || next.rootSessionId !== sessionId) {
+          throw new Error(`missing graph snapshot for ${sessionId}`);
+        }
         return next;
       },
       inspectOperator: async () => {
@@ -108,7 +177,9 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
           listeners.delete(listener);
         };
       },
-      stop: async () => undefined,
+      stop: async (sessionId: string) => {
+        stopCalls.push(sessionId);
+      },
     },
   };
 
@@ -119,12 +190,16 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
     container,
     root,
     async setSnapshot(next) {
-      snapshots.set(next.rootSessionId, next);
+      snapshots.set(next.graphId, next);
+      currentGraphIds.set(next.rootSessionId, next.graphId);
       await act(async () => {
         for (const listener of [...listeners]) listener();
         await Promise.resolve();
       });
     },
+    evict(graphId) {
+      snapshots.delete(graphId);
+    },
     async renderSession(sessionId) {
       await act(async () => {
         root.render(
@@ -138,6 +213,17 @@ function installGraphRenderer(initial: AgentGraphClientSnapshot): {
         await Promise.resolve();
       });
     },
+    holdNextEpochList(sessionId) {
+      const gate = deferredReadGate();
+      epochListGates.set(sessionId, gate);
+      return gate;
+    },
+    holdNextSnapshot(graphId) {
+      const gate = deferredReadGate();
+      snapshotGates.set(graphId, gate);
+      return gate;
+    },
+    stopCalls,
   };
 }
 
@@ -160,6 +246,126 @@ async function renderPanel(
 }
 
 describe('AgentGraphPanel dismiss', () => {
+  it('keeps the new session loading when a disposed read settles later', async () => {
+    const sessionA = snapshot({ graphId: 'graph-a', status: 'active' });
+    const sessionB = snapshot({
+      graphId: 'graph-b',
+      status: 'active',
+      rootSessionId: 'session-2',
+    });
+    const harness = installGraphRenderer(sessionA, [sessionB]);
+    const readA = harness.holdNextEpochList('session-1');
+    await harness.renderSession('session-1');
+    await readA.started;
+
+    const readB = harness.holdNextEpochList('session-2');
+    await harness.renderSession('session-2');
+    await readB.started;
+    assert.match(harness.container.textContent ?? '', /Loading graph state/);
+
+    await act(async () => {
+      readA.release();
+      await Promise.resolve();
+    });
+    assert.match(harness.container.textContent ?? '', /Loading graph state/);
+
+    await act(async () => {
+      readB.release();
+      await Promise.resolve();
+    });
+    assert.match(harness.container.textContent ?? '', /Agent Graph/);
+    await act(async () => harness.root.unmount());
+  });
+
+  it('switches to a historical epoch without exposing current-graph controls', async () => {
+    const current = snapshot({ graphId: 'graph-2', status: 'active' });
+    const previous = snapshot({ graphId: 'graph-1', status: 'completed' });
+    const harness = installGraphRenderer(current, [previous]);
+    await act(async () => {
+      harness.root.render(
+        createElement(AgentGraphPanel, {
+          rootSessionId: 'session-1',
+          enabled: true,
+          locale: 'en',
+          onOpenSession: () => undefined,
+        }),
+      );
+      await Promise.resolve();
+    });
+
+    const selector = harness.container.querySelector('[role="combobox"]');
+    assert.ok(selector);
+    assert.match(harness.container.textContent ?? '', /Stop graph/);
+    await act(async () => {
+      (selector as HTMLElement).click();
+      await Promise.resolve();
+    });
+    const historyOption = [...document.querySelectorAll('[role="option"]')].find((option) =>
+      option.textContent?.includes('History'),
+    );
+    assert.ok(historyOption);
+    const historyRead = harness.holdNextSnapshot('graph-1');
+    await act(async () => {
+      (historyOption as HTMLElement).click();
+      await historyRead.started;
+    });
+
+    assert.match(harness.container.textContent ?? '', /#1 · History \(read-only\)/);
+    assert.doesNotMatch(harness.container.textContent ?? '', /Stop graph/);
+    assert.equal(harness.container.querySelector('.maka-agent-graph-dismiss'), null);
+    assert.deepEqual(harness.stopCalls, []);
+    await act(async () => {
+      historyRead.release();
+      await Promise.resolve();
+    });
+    await act(async () => harness.root.unmount());
+  });
+
+  it('resumes following the current epoch after the selected history expires', async () => {
+    const current = snapshot({ graphId: 'graph-2', status: 'active' });
+    const previous = snapshot({ graphId: 'graph-1', status: 'completed' });
+    const harness = installGraphRenderer(current, [previous]);
+    await act(async () => {
+      harness.root.render(
+        createElement(AgentGraphPanel, {
+          rootSessionId: 'session-1',
+          enabled: true,
+          locale: 'en',
+          onOpenSession: () => undefined,
+        }),
+      );
+      await Promise.resolve();
+    });
+
+    const selector = harness.container.querySelector('[role="combobox"]');
+    assert.ok(selector);
+    await act(async () => {
+      (selector as HTMLElement).click();
+      await Promise.resolve();
+    });
+    const historyOption = [...document.querySelectorAll('[role="option"]')].find((option) =>
+      option.textContent?.includes('History'),
+    );
+    assert.ok(historyOption);
+    await act(async () => {
+      (historyOption as HTMLElement).click();
+      await Promise.resolve();
+    });
+    const combobox = () => harness.container.querySelector('[role="combobox"]')?.textContent ?? '';
+    assert.match(combobox(), /#1 · History \(read-only\)/);
+
+    // The selected epoch leaves the bounded directory while the graph rolls over.
+    harness.evict('graph-1');
+    await harness.setSnapshot(snapshot({ graphId: 'graph-3', status: 'active' }));
+    assert.match(combobox(), /#2 · Current/);
+
+    // Follow restored: the next rollover refreshes the panel instead of
+    // staying pinned on the fallback graph.
+    await harness.setSnapshot(snapshot({ graphId: 'graph-4', status: 'waiting' }));
+    assert.match(combobox(), /#3 · Current/);
+    await act(async () => harness.root.unmount());
+  });
+
   it('shows dismiss only after the graph has settled', async () => {
     const active = await renderPanel(snapshot({ graphId: 'graph-1', status: 'active' }));
     assert.ok(active.container.querySelector('.maka-agent-graph-panel'));