@frockbot/kernel-do 0.3.15 → 0.3.16

package/src/model-timeout-settlement.test.ts

@@ -31,7 +31,7 @@ import {
   BotTurnExecutionError,
   BotTurnReconciliationRequiredError,
 } from "./turn-errors.ts";
-import { createStoredRunCodecV1, type StoredRunV1 } from "./run-records.ts";
+import { createStoredRunCodecV1 } from "./run-records.ts";
 
 const codec = createStoredRunCodecV1<undefined>({
   decodeRunId: (value) => value as string,
@@ -188,11 +188,11 @@ function createAuthority(
   });
 }
 
-function storedRun(
-  storage: MemoryStorage,
+async function storedRun(
+  authority: BotDurableAuthority<undefined>,
   runId: string,
-): StoredRunV1<undefined> {
-  return codec.require(storage.values.get(`run:${runId}`));
+) {
+  return (await authority.readRun(runId))!;
 }
 
 describe("a model request that ran out of time", () => {
@@ -205,7 +205,7 @@ describe("a model request that ran out of time", () => {
     const completion = await authority.run(command("run-1", "build me one"));
 
     expect(completion.runId).toBe("run-1");
-    const run = storedRun(storage, "run-1");
+    const run = await storedRun(authority, "run-1");
     expect(run.status).toBe("failed");
     // The ordinary run-terminal path: the open Turn is closed rather than left
     // for the next message to trip over.
@@ -233,7 +233,7 @@ describe("a model request that ran out of time", () => {
       authority.run(command("run-1", "build me one")),
     ).rejects.toThrow();
 
-    const run = storedRun(storage, "run-1");
+    const run = await storedRun(authority, "run-1");
     expect(run.status).toBe("reconciliation-required");
     expect(run.events.some((event) => event.type === "turn/end")).toBe(false);
   });
@@ -252,7 +252,7 @@ describe("a model request that ran out of time", () => {
     const completion = await authority.run(command("run-1", "hello"));
 
     expect(completion.runId).toBe("run-1");
-    const run = storedRun(storage, "run-1");
+    const run = await storedRun(authority, "run-1");
     expect(run.status).toBe("failed");
     expect(
       run.events.findLast((event) => event.type === "turn/end"),

package/src/run-liveness.test.ts

@@ -28,6 +28,7 @@ import {
   STALE_RUNNING_RUN_FAILURE_V1,
   STALE_RUNNING_RUN_GRACE_MS_V1,
 } from "./run-liveness.ts";
+import { SessionEventLog } from "./session-event-log.ts";
 import {
   ACTIVE_RUN_KEY,
   IDENTITY_KEY,
@@ -255,7 +256,7 @@ describe("the read that repairs what it finds", () => {
     // The Bot is free: nothing holds the object, and the next Turn admits
     // against a log that reads as a complete history.
     expect(await storage.get<string>(ACTIVE_RUN_KEY)).toBeUndefined();
-    const log = (await storage.get<SessionEvent[]>(LATEST_EVENTS_KEY)) ?? [];
+    const log = await new SessionEventLog(storage).read("user-1:primary");
     expect(log.some((entry) => entry.type === "turn/end")).toBe(true);
   });
 

package/src/run-records.ts

@@ -133,6 +133,12 @@ export interface StoredRunV1<Snapshot = unknown> {
   acceptedAt: string;
   input: string;
   events: SessionEvent[];
+  /**
+   * Inclusive/exclusive coordinates of this Turn in the authoritative Session
+   * log. New durable records carry this instead of embedding `events`; the
+   * in-memory record is hydrated through the Session log accessor.
+   */
+  eventRange?: StoredRunEventRangeV1;
   effectAdmissions: StoredEffectAdmission[];
   status: StoredRunStatus;
   responseText?: string;
@@ -159,6 +165,44 @@ export interface StoredRunV1<Snapshot = unknown> {
   directTool?: DirectToolCommandV1;
 }
 
+export interface StoredRunEventRangeV1 {
+  startSeq: number;
+  endSeq: number;
+}
+
+/** Keeps a hydrated journal and its durable coordinates in lockstep. */
+export function storedRunEventFieldsV2(
+  previousEventCount: number,
+  events: SessionEvent[],
+): { events: SessionEvent[]; eventRange: StoredRunEventRangeV1 } {
+  return {
+    events,
+    eventRange: {
+      startSeq: previousEventCount,
+      endSeq: previousEventCount + events.length,
+    },
+  };
+}
+
+/**
+ * The compact durable run shape. Keeping this encoder beside the strict
+ * decoder makes it difficult for a metadata update to accidentally put a
+ * hydrated multi-megabyte journal back into one SQLite value.
+ */
+export function storedRunRecordV2<Snapshot>(
+  run: StoredRunV1<Snapshot>,
+): Omit<StoredRunV1<Snapshot>, "events"> {
+  const { events, ...record } = run;
+  const eventRange =
+    events.length === 0 && run.eventRange
+      ? run.eventRange
+      : {
+          startSeq: run.previousEventCount,
+          endSeq: run.previousEventCount + events.length,
+        };
+  return { ...record, eventRange };
+}
+
 export interface DirectToolCommandV1 {
   generationId: string;
   packageId: string;
@@ -246,7 +290,6 @@ const STORED_RUN_REQUIRED_KEYS = [
   "sessionId",
   "acceptedAt",
   "input",
-  "events",
   "effectAdmissions",
   "status",
   "phase",
@@ -255,6 +298,8 @@ const STORED_RUN_REQUIRED_KEYS = [
   "previousEventCount",
 ] as const;
 const STORED_RUN_OPTIONAL_KEYS = [
+  "events",
+  "eventRange",
   "responseText",
   "failure",
   "stopRequestedAt",
@@ -483,6 +528,32 @@ function decodeStoredRunEvents(value: unknown): SessionEvent[] {
   return value.map(decodeSessionEvent);
 }
 
+function decodeStoredRunEventRange(
+  value: unknown,
+  runId: string,
+): StoredRunEventRangeV1 {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`run "${runId}" has an invalid event range`);
+  }
+  const candidate = value as Record<PropertyKey, unknown>;
+  if (
+    Reflect.ownKeys(candidate).length !== 2 ||
+    Object.keys(candidate).length !== 2 ||
+    !Object.hasOwn(candidate, "startSeq") ||
+    !Object.hasOwn(candidate, "endSeq") ||
+    !Number.isSafeInteger(candidate.startSeq) ||
+    !Number.isSafeInteger(candidate.endSeq) ||
+    (candidate.startSeq as number) < 0 ||
+    (candidate.endSeq as number) < (candidate.startSeq as number)
+  ) {
+    throw new Error(`run "${runId}" has an invalid event range`);
+  }
+  return {
+    startSeq: candidate.startSeq as number,
+    endSeq: candidate.endSeq as number,
+  };
+}
+
 const STORED_EFFECT_ADMISSIONS_MAX = 256;
 const STORED_EFFECT_ID_MAX_BYTES = 512;
 
@@ -582,7 +653,17 @@ function requireStoredRunRecordV1<Snapshot>(
   if (!boundedString(candidate.input, 32_000)) {
     throw new Error(`run "${runId}" has no valid input`);
   }
-  const events = decodeStoredRunEvents(candidate.events);
+  if (candidate.events === undefined && candidate.eventRange === undefined) {
+    throw new Error(`run "${runId}" has no event journal reference`);
+  }
+  const events =
+    candidate.events === undefined
+      ? []
+      : decodeStoredRunEvents(candidate.events);
+  const eventRange =
+    candidate.eventRange === undefined
+      ? undefined
+      : decodeStoredRunEventRange(candidate.eventRange, runId);
   const effectAdmissions = decodeStoredEffectAdmissions(
     candidate.effectAdmissions,
   );
@@ -605,6 +686,15 @@ function requireStoredRunRecordV1<Snapshot>(
   ) {
     throw new Error(`run "${runId}" has no valid previous event count`);
   }
+  if (
+    eventRange &&
+    (eventRange.startSeq !== candidate.previousEventCount ||
+      (events.length > 0 &&
+        (events[0]?.seq !== eventRange.startSeq ||
+          events.at(-1)!.seq + 1 !== eventRange.endSeq)))
+  ) {
+    throw new Error(`run "${runId}" has an inconsistent event range`);
+  }
   const configurationSnapshot = options.decodeConfigurationSnapshot(
     candidate.configurationSnapshot,
   );
@@ -679,6 +769,7 @@ function requireStoredRunRecordV1<Snapshot>(
     acceptedAt: candidate.acceptedAt,
     input: candidate.input,
     events,
+    ...(eventRange ? { eventRange } : {}),
     effectAdmissions,
     status,
     phase,

package/src/run-terminal-open-turn.test.ts

@@ -14,6 +14,7 @@ import {
   validateToolOccurrenceJournal,
 } from "@frockbot/kernel-contracts";
 import { MemoryStorage } from "./memory-storage.fixture.ts";
+import { SessionEventLog } from "./session-event-log.ts";
 import { createStoredRunCodecV1, type StoredRunV1 } from "./run-records.ts";
 import {
   cancelStoredRun,
@@ -117,7 +118,7 @@ async function settled(
 
   return {
     storage,
-    latest: storage.values.get(KEYS.latestEvents) as SessionEvent[],
+    latest: await new SessionEventLog(storage).read(SESSION_ID),
   };
 }
 
@@ -141,9 +142,13 @@ describe("settling a Turn interrupted mid-answer", () => {
     expect(() => admitNextTurn(latest)).not.toThrow();
     expect(latest.at(-1)).toMatchObject({ type: "turn/end", turn: 1 });
     // The settled record carries the same closed account, not a different one.
-    const record = storage.values.get(KEYS.run) as StoredRunV1<null>;
+    const record = storage.values.get(KEYS.run) as Omit<
+      StoredRunV1<null>,
+      "events"
+    >;
     expect(record.status).toBe("superseded");
-    expect(record.events.at(-1)).toMatchObject({ type: "turn/end", turn: 1 });
+    expect(Object.hasOwn(record, "events")).toBe(false);
+    expect(record.eventRange).toEqual({ startSeq: 0, endSeq: latest.length });
   });
 
   test("a stopped run leaves a log the next Turn can start on", async () => {
@@ -196,7 +201,7 @@ describe("settling a Turn interrupted mid-answer", () => {
 
     await cancelStoredRun(codec, storage, KEYS, "run-1", [], events);
 
-    const latest = storage.values.get(KEYS.latestEvents) as SessionEvent[];
+    const latest = await new SessionEventLog(storage).read(SESSION_ID);
     expect(latest.filter((event) => event.type === "turn/end")).toHaveLength(1);
     expect(() => admitNextTurn(latest)).not.toThrow();
   });

package/src/run-terminal.ts

@@ -8,7 +8,13 @@ import type {
   StoredRunCodecV1,
   StoredRunV1,
 } from "./run-records.js";
+import { storedRunRecordV2 } from "./run-records.js";
+import { storedRunEventFieldsV2 } from "./run-records.js";
 import { repairedSessionLogV1 } from "./run-recovery.js";
+import {
+  SessionEventLog,
+  type SessionEventLogStorage,
+} from "./session-event-log.js";
 
 /**
  * The events a terminal settlement commits, with any Turn they were left
@@ -57,11 +63,7 @@ function settledEventsV1(
   };
 }
 
-export interface RunTerminalStorage {
-  get<T>(key: string): Promise<T | undefined>;
-  put(entries: Record<string, unknown>): Promise<void>;
-  delete(key: string): Promise<boolean>;
-}
+export interface RunTerminalStorage extends SessionEventLogStorage {}
 
 export interface RunTerminalKeys {
   run: string;
@@ -70,6 +72,24 @@ export interface RunTerminalKeys {
   notificationPrefix: string;
 }
 
+async function hydratedRun<Snapshot>(
+  codec: StoredRunCodecV1<Snapshot>,
+  storage: RunTerminalStorage,
+  key: string,
+): Promise<StoredRunV1<Snapshot> | undefined> {
+  const stored = codec.optional(await storage.get<unknown>(key));
+  if (!stored?.eventRange) return stored;
+  const events = await new SessionEventLog(storage).readRange(
+    stored.sessionId,
+    stored.eventRange.startSeq,
+    stored.eventRange.endSeq,
+  );
+  if (events.length !== stored.eventRange.endSeq - stored.eventRange.startSeq) {
+    throw new Error(`run "${stored.runId}" has an incomplete event range`);
+  }
+  return codec.require({ ...stored, events });
+}
+
 /**
  * Records a Package writes in the same transaction that settles a Turn. The
  * kernel never reads them: it is handed opaque key/value pairs and a reader
@@ -126,9 +146,8 @@ export async function supersedeStoredRun<Snapshot>(
   events: readonly SessionEvent[],
   packageRecords?: SupersededPackageRecords<Snapshot>,
 ): Promise<"superseded"> {
-  const stored = await storage.get<StoredRunV1<Snapshot>>(keys.run);
-  if (!stored) throw new Error(`run "${runId}" was not accepted`);
-  const run = codec.require(stored);
+  const run = await hydratedRun(codec, storage, keys.run);
+  if (!run) throw new Error(`run "${runId}" was not accepted`);
   if (!run.supersededAt) {
     throw new Error(`run "${runId}" has no durable supersede intent`);
   }
@@ -141,7 +160,10 @@ export async function supersedeStoredRun<Snapshot>(
   const queued = settled.phase === "queued";
   const superseded = codec.require({
     ...settled,
-    events: queued ? [] : decodedEvents,
+    ...storedRunEventFieldsV2(
+      run.previousEventCount,
+      queued ? [] : decodedEvents,
+    ),
     status: "superseded",
     phase:
       settled.phase === "reconciliation-required"
@@ -151,12 +173,7 @@ export async function supersedeStoredRun<Snapshot>(
           : settled.phase,
   } satisfies StoredRunV1<Snapshot>);
   const records: Record<string, unknown> = {
-    [keys.run]: structuredClone(superseded),
-    ...(queued
-      ? {}
-      : {
-          [keys.latestEvents]: structuredClone(settledEvents.latestEvents),
-        }),
+    [keys.run]: structuredClone(storedRunRecordV2(superseded)),
   };
   if (packageRecords && !queued) {
     const contributed = await packageRecords({
@@ -168,6 +185,12 @@ export async function supersedeStoredRun<Snapshot>(
       records[key] = structuredClone(value);
     }
   }
+  if (!queued) {
+    await new SessionEventLog(storage).rewrite(
+      run.sessionId,
+      settledEvents.latestEvents,
+    );
+  }
   await storage.put(records);
   if ((await storage.get<string>(keys.activeRun)) === runId) {
     await storage.delete(keys.activeRun);
@@ -187,9 +210,8 @@ export async function completeStoredRun<Snapshot>(
 ): Promise<"completed" | "cancelled" | "superseded"> {
   const activeRunId = await storage.get<string>(keys.activeRun);
   if (activeRunId !== runId) throw new Error(`run "${runId}" is not active`);
-  const stored = await storage.get<StoredRunV1<Snapshot>>(keys.run);
-  if (!stored) throw new Error(`run "${runId}" was not accepted`);
-  const run = codec.require(stored);
+  const run = await hydratedRun(codec, storage, keys.run);
+  if (!run) throw new Error(`run "${runId}" was not accepted`);
   const events = result.events.map(decodeSessionEvent);
   const latestEvents = [...previous, ...events].map(decodeSessionEvent);
   // Stop outranks supersede: the User asked for this Turn to stop, and a
@@ -212,29 +234,28 @@ export async function completeStoredRun<Snapshot>(
     const { responseText: _text, failure: _failure, ...settled } = run;
     const cancelled = codec.require({
       ...settled,
-      events,
+      ...storedRunEventFieldsV2(run.previousEventCount, events),
       status: "cancelled",
       phase:
         settled.phase === "reconciliation-required"
           ? "executing"
           : settled.phase,
     } satisfies StoredRunV1<Snapshot>);
+    await new SessionEventLog(storage).rewrite(run.sessionId, latestEvents);
     await storage.put({
-      [keys.run]: structuredClone(cancelled),
-      [keys.latestEvents]: structuredClone(latestEvents),
+      [keys.run]: structuredClone(storedRunRecordV2(cancelled)),
     });
     await storage.delete(keys.activeRun);
     return "cancelled";
   }
   const completed = codec.require({
     ...run,
-    events,
+    ...storedRunEventFieldsV2(run.previousEventCount, events),
     status: "completed",
     responseText: result.text,
   } satisfies StoredRunV1<Snapshot>);
   const records: Record<string, unknown> = {
-    [keys.run]: structuredClone(completed),
-    [keys.latestEvents]: structuredClone(latestEvents),
+    [keys.run]: structuredClone(storedRunRecordV2(completed)),
   };
   if (result.notification) {
     records[`${keys.notificationPrefix}${result.notification.notificationId}`] =
@@ -250,6 +271,7 @@ export async function completeStoredRun<Snapshot>(
       records[key] = structuredClone(value);
     }
   }
+  await new SessionEventLog(storage).rewrite(run.sessionId, latestEvents);
   await storage.put(records);
   await storage.delete(keys.activeRun);
   return "completed";
@@ -267,9 +289,8 @@ export async function cancelStoredRun<Snapshot>(
   previous: readonly SessionEvent[],
   events: readonly SessionEvent[],
 ): Promise<"cancelled" | "preserved-completion" | "missing"> {
-  const stored = await storage.get<StoredRunV1<Snapshot>>(keys.run);
-  if (!stored) return "missing";
-  const run = codec.require(stored);
+  const run = await hydratedRun(codec, storage, keys.run);
+  if (!run) return "missing";
   if (run.status === "completed") return "preserved-completion";
   if (!run.stopRequestedAt) {
     throw new Error(`run "${runId}" has no durable stop intent`);
@@ -280,14 +301,14 @@ export async function cancelStoredRun<Snapshot>(
   const { responseText: _text, failure: _failure, ...settled } = run;
   const cancelled = codec.require({
     ...settled,
-    events: decodedEvents,
+    ...storedRunEventFieldsV2(run.previousEventCount, decodedEvents),
     status: "cancelled",
     phase:
       settled.phase === "reconciliation-required" ? "executing" : settled.phase,
   } satisfies StoredRunV1<Snapshot>);
+  await new SessionEventLog(storage).rewrite(run.sessionId, latestEvents);
   await storage.put({
-    [keys.run]: structuredClone(cancelled),
-    [keys.latestEvents]: structuredClone(latestEvents),
+    [keys.run]: structuredClone(storedRunRecordV2(cancelled)),
   });
   if ((await storage.get<string>(keys.activeRun)) === runId) {
     await storage.delete(keys.activeRun);
@@ -307,9 +328,8 @@ export async function failStoredRun<Snapshot>(
 ): Promise<
   "failed" | "cancelled" | "superseded" | "preserved-completion" | "missing"
 > {
-  const stored = await storage.get<StoredRunV1<Snapshot>>(keys.run);
-  if (!stored) return "missing";
-  const run = codec.require(stored);
+  const run = await hydratedRun(codec, storage, keys.run);
+  if (!run) return "missing";
   if (run.status === "completed") return "preserved-completion";
   // A stopped run never becomes `failed`: Stop is the durable outcome.
   if (run.stopRequestedAt) {
@@ -332,15 +352,13 @@ export async function failStoredRun<Snapshot>(
   const latestEvents = settledEvents.latestEvents;
   const failed = codec.require({
     ...run,
-    events: decodedEvents,
+    ...storedRunEventFieldsV2(run.previousEventCount, decodedEvents),
     status: "failed",
     phase: run.phase === "reconciliation-required" ? "executing" : run.phase,
     failure,
   } satisfies StoredRunV1<Snapshot>);
-  await storage.put({
-    [keys.run]: structuredClone(failed),
-    [keys.latestEvents]: structuredClone(latestEvents),
-  });
+  await new SessionEventLog(storage).rewrite(run.sessionId, latestEvents);
+  await storage.put({ [keys.run]: structuredClone(storedRunRecordV2(failed)) });
   if ((await storage.get<string>(keys.activeRun)) === runId) {
     await storage.delete(keys.activeRun);
   }
@@ -358,20 +376,19 @@ export async function requireStoredRunReconciliation<Snapshot>(
 ): Promise<void> {
   const activeRunId = await storage.get<string>(keys.activeRun);
   if (activeRunId !== runId) throw new Error(`run "${runId}" is not active`);
-  const stored = await storage.get<StoredRunV1<Snapshot>>(keys.run);
-  if (!stored) throw new Error(`run "${runId}" was not accepted`);
-  const run = codec.require(stored);
+  const run = await hydratedRun(codec, storage, keys.run);
+  if (!run) throw new Error(`run "${runId}" was not accepted`);
   const decodedEvents = events.map(decodeSessionEvent);
   const latestEvents = [...previous, ...decodedEvents].map(decodeSessionEvent);
   const reconciliation = codec.require({
     ...run,
-    events: decodedEvents,
+    ...storedRunEventFieldsV2(run.previousEventCount, decodedEvents),
     status: "reconciliation-required",
     phase: "reconciliation-required",
     failure,
   } satisfies StoredRunV1<Snapshot>);
+  await new SessionEventLog(storage).rewrite(run.sessionId, latestEvents);
   await storage.put({
-    [keys.run]: structuredClone(reconciliation),
-    [keys.latestEvents]: structuredClone(latestEvents),
+    [keys.run]: structuredClone(storedRunRecordV2(reconciliation)),
   });
 }