@frockbot/kernel-do 0.3.21 → 0.3.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/kernel-do",
-  "version": "0.3.21",
+  "version": "0.3.23",
   "private": false,
   "type": "module",
   "exports": {
@@ -12,8 +12,8 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/kernel-composition": "0.3.21",
-    "@frockbot/kernel-contracts": "0.3.21",
+    "@frockbot/kernel-composition": "0.3.23",
+    "@frockbot/kernel-contracts": "0.3.23",
     "cordis": "4.0.0-rc.8"
   },
   "devDependencies": {

package/src/authority.ts

@@ -1177,19 +1177,58 @@ export class BotDurableAuthority<Snapshot> {
     return this.readRunFrom(this.ctx.storage, runId);
   }
 
+  /**
+   * The run record alone, with no journal behind it.
+   *
+   * Deciding whether a Turn belongs to the conversation being read, and
+   * whether a person is meant to see it, needs the record and nothing else. A
+   * transcript page scans many more candidates than it keeps, and hydrating
+   * every candidate's events to discard it was the whole cost of that scan.
+   * The returned record carries an empty `events` array and its `eventRange`;
+   * anything that reads the journal calls {@link readStoredRun} or
+   * {@link readStoredRunForDisplay}.
+   */
+  async readRunHeader(
+    runId: string,
+  ): Promise<StoredRunV1<Snapshot> | undefined> {
+    return this.codec.optional(
+      await this.ctx.storage.get<unknown>(`${RUN_PREFIX}${runId}`),
+    );
+  }
+
+  /**
+   * A run hydrated for the conversation surface: exact for everything the
+   * transcript renders, and each normalized model request left as its durable
+   * projection. See `SessionEventLog.readDisplayRange`.
+   */
+  async readStoredRunForDisplay(
+    runId: string,
+  ): Promise<StoredRunV1<Snapshot> | undefined> {
+    return this.readRunFrom(this.ctx.storage, runId, "display");
+  }
+
   private async readRunFrom(
     storage: SessionEventLogStorage,
     runId: string,
+    fidelity: "exact" | "display" = "exact",
   ): Promise<StoredRunV1<Snapshot> | undefined> {
     const run = this.codec.optional(
       await storage.get<unknown>(`${RUN_PREFIX}${runId}`),
     );
     if (!run?.eventRange) return run;
-    const events = await new SessionEventLog(storage).readRange(
-      run.sessionId,
-      run.eventRange.startSeq,
-      run.eventRange.endSeq,
-    );
+    const log = new SessionEventLog(storage);
+    const events =
+      fidelity === "display"
+        ? await log.readDisplayRange(
+            run.sessionId,
+            run.eventRange.startSeq,
+            run.eventRange.endSeq,
+          )
+        : await log.readRange(
+            run.sessionId,
+            run.eventRange.startSeq,
+            run.eventRange.endSeq,
+          );
     if (events.length !== run.eventRange.endSeq - run.eventRange.startSeq) {
       throw new Error(`run "${run.runId}" has an incomplete event range`);
     }
@@ -1203,9 +1242,10 @@ export class BotDurableAuthority<Snapshot> {
 
   /**
    * The bounded durable event projections for a run. This is the inspection
-   * path: recovery and client transcript projection use `readStoredRun` and
-   * therefore receive exact events, while a debug snapshot never hydrates a
-   * multi-megabyte prompt merely to cut it again.
+   * path: recovery, compaction and audit use `readStoredRun` and therefore
+   * receive exact events, the transcript uses `readStoredRunForDisplay`, and a
+   * debug snapshot never hydrates a multi-megabyte prompt merely to cut it
+   * again (ADR 0038).
    */
   async readRunEventProjections(runId: string): Promise<
     | {

package/src/session-event-log.test.ts

@@ -250,6 +250,138 @@ describe("the paged Session event log", () => {
     expect(await log.readRange(SESSION_ID, 2, 3)).toEqual([repaired[2]]);
   });
 
+  test("reads a range without hydrating unrelated model requests", async () => {
+    const storage = new MemoryStorage();
+    const session = new Session(SESSION_ID, () => {});
+    for (let turn = 1; turn <= 12; turn += 1) {
+      session.appendBatch([
+        { type: "turn/start", turn },
+        {
+          type: "model/request",
+          turn,
+          step: 1,
+          request: {
+            requestId: `request-${turn}`,
+            provider: "fake",
+            model: "large-context",
+            system: "s".repeat(80_000),
+            messages: [],
+            tools: [],
+          },
+        },
+        { type: "turn/end", turn, outcome: "completed" },
+      ]);
+    }
+    const log = new SessionEventLog(storage);
+    await log.rewrite(SESSION_ID, [...session.events]);
+
+    const reads: string[] = [];
+    const get = storage.get.bind(storage);
+    storage.get = <T>(key: string): Promise<T | undefined> => {
+      reads.push(key);
+      return get<T>(key);
+    };
+
+    const range = await log.readRange(SESSION_ID, 0, 1);
+
+    expect(range).toEqual([session.events[0]!]);
+    expect(
+      reads.filter((key) =>
+        key.startsWith(sessionEventPayloadPrefixV1(SESSION_ID)),
+      ),
+    ).toEqual([]);
+    // The index, the bisected pages, and nothing else: the cost of a range is
+    // the range, not every request the conversation has ever retained.
+    expect(reads.length).toBeLessThanOrEqual(4);
+  });
+
+  test("hydrates only the payloads its own range references", async () => {
+    const storage = new MemoryStorage();
+    const session = new Session(SESSION_ID, () => {});
+    for (let turn = 1; turn <= 12; turn += 1) {
+      session.appendBatch([
+        { type: "turn/start", turn },
+        {
+          type: "model/request",
+          turn,
+          step: 1,
+          request: {
+            requestId: `request-${turn}`,
+            provider: "fake",
+            model: "large-context",
+            system: "s".repeat(80_000),
+            messages: [],
+            tools: [],
+          },
+        },
+        { type: "turn/end", turn, outcome: "completed" },
+      ]);
+    }
+    const log = new SessionEventLog(storage);
+    await log.rewrite(SESSION_ID, [...session.events]);
+
+    const reads: string[] = [];
+    const get = storage.get.bind(storage);
+    storage.get = <T>(key: string): Promise<T | undefined> => {
+      reads.push(key);
+      return get<T>(key);
+    };
+
+    const range = await log.readRange(SESSION_ID, 30, 33);
+
+    expect(range).toEqual(session.events.slice(30, 33));
+    const payloads = new Set(
+      reads
+        .filter((key) =>
+          key.startsWith(sessionEventPayloadPrefixV1(SESSION_ID)),
+        )
+        .map((key) => key.slice(0, key.lastIndexOf(":"))),
+    );
+    const requestSeq = session.events
+      .slice(30, 33)
+      .find((event) => event.type === "model/request")!.seq;
+    expect([...payloads]).toEqual([
+      `${sessionEventPayloadPrefixV1(SESSION_ID)}${String(requestSeq).padStart(12, "0")}`,
+    ]);
+  });
+
+  test("leaves exact model requests off the display range", async () => {
+    const storage = new MemoryStorage();
+    const log = new SessionEventLog(storage);
+    const events = journal();
+    await log.rewrite(SESSION_ID, events);
+
+    const reads: string[] = [];
+    const get = storage.get.bind(storage);
+    storage.get = <T>(key: string): Promise<T | undefined> => {
+      reads.push(key);
+      return get<T>(key);
+    };
+
+    const display = await log.readDisplayRange(SESSION_ID, 0, events.length);
+
+    expect(display.map((event) => event.type)).toEqual(
+      events.map((event) => event.type),
+    );
+    expect(display.map((event) => event.seq)).toEqual(
+      events.map((event) => event.seq),
+    );
+    expect(
+      reads.filter((key) =>
+        key.startsWith(sessionEventPayloadPrefixV1(SESSION_ID)),
+      ),
+    ).toEqual([]);
+    const request = display.find((event) => event.type === "model/request");
+    expect(request?.type === "model/request" && request.request.requestId).toBe(
+      "request-1",
+    );
+    // The excerpt says what it is; the exact request stays on the audit path.
+    expect(
+      request?.type === "model/request" && request.request.system.length,
+    ).toBeLessThan(80_000);
+    expect(await log.readRange(SESSION_ID, 0, events.length)).toEqual(events);
+  });
+
   test("migrates the legacy single value on demand", async () => {
     const storage = new MemoryStorage();
     const events = journal(1_900_000);

package/src/session-event-log.ts

@@ -338,10 +338,47 @@ export class SessionEventLog {
     return events;
   }
 
+  /**
+   * The exact events of one half-open range.
+   *
+   * A range read seeks to the pages that cover it and hydrates only the
+   * payloads those pages reference. Reading the whole conversation to slice
+   * three events out of it made a transcript read cost one storage operation
+   * per retained model request — a Bot with a hundred 80 KiB requests paid for
+   * all of them to draw one Turn.
+   */
   async readRange(
     sessionId: string,
     startSeq: number,
     endSeq: number,
+  ): Promise<SessionEvent[]> {
+    return this.rangeEvents(sessionId, startSeq, endSeq, "exact");
+  }
+
+  /**
+   * The same range at display fidelity: every event the conversation shows,
+   * with each exact model request left on the audit path.
+   *
+   * The transcript projection reads tool calls, tool results, sends and
+   * assistant chunks; it has never rendered a normalized model request. ADR
+   * 0033 keeps a bounded projection of that request beside its chunked exact
+   * payload precisely so a reader that does not need the exact bytes need not
+   * pay for them, and this is that reader. Recovery, compaction, audit, and
+   * model-history derivation stay on {@link readRange}.
+   */
+  async readDisplayRange(
+    sessionId: string,
+    startSeq: number,
+    endSeq: number,
+  ): Promise<SessionEvent[]> {
+    return this.rangeEvents(sessionId, startSeq, endSeq, "display");
+  }
+
+  private async rangeEvents(
+    sessionId: string,
+    startSeq: number,
+    endSeq: number,
+    fidelity: "exact" | "display",
   ): Promise<SessionEvent[]> {
     if (
       !Number.isSafeInteger(startSeq) ||
@@ -351,7 +388,88 @@ export class SessionEventLog {
     ) {
       throw new Error("Session event range is invalid");
     }
-    return (await this.read(sessionId)).slice(startSeq, endSeq);
+    const index = requireIndex(
+      await this.storage.get<SessionEventLogIndexV1>(
+        sessionEventLogIndexKeyV1(sessionId),
+      ),
+      sessionId,
+    );
+    if (!index) return (await this.read(sessionId)).slice(startSeq, endSeq);
+    const last = Math.min(endSeq, index.eventCount);
+    if (startSeq >= last) return [];
+    const located = await this.pageContaining(sessionId, index, startSeq);
+    if (!located) {
+      throw new Error(
+        `Session event pages for "${sessionId}" are not contiguous`,
+      );
+    }
+    const events: SessionEvent[] = [];
+    for (let page = located.page; page < index.pageCount; page += 1) {
+      const stored =
+        page === located.page
+          ? located.stored
+          : requirePage(
+              await this.storage.get<StoredSessionEventPageV1>(
+                sessionEventLogPageKey(sessionId, page),
+              ),
+              sessionId,
+              page,
+            );
+      for (const entry of stored.entries) {
+        const seq = storedEventSeq(entry);
+        if (seq < startSeq) continue;
+        if (seq >= last) return events;
+        if (seq !== startSeq + events.length) {
+          throw new Error(
+            `Session event log for "${sessionId}" is not contiguous`,
+          );
+        }
+        events.push(
+          fidelity === "display"
+            ? await this.displayEvent(sessionId, entry)
+            : await this.exactEvent(sessionId, entry),
+        );
+      }
+      if (events.length === last - startSeq) break;
+    }
+    if (events.length !== last - startSeq) {
+      throw new Error(`Session event log for "${sessionId}" is not contiguous`);
+    }
+    return events;
+  }
+
+  /**
+   * The page holding `seq`, found by bisecting the page keys.
+   *
+   * Pages carry their own `startSeq` and are written in sequence order, so the
+   * accessor can seek without an extra durable page directory to keep
+   * consistent with the pages themselves.
+   */
+  private async pageContaining(
+    sessionId: string,
+    index: SessionEventLogIndexV1,
+    seq: number,
+  ): Promise<{ page: number; stored: StoredSessionEventPageV1 } | undefined> {
+    let low = 0;
+    let high = index.pageCount - 1;
+    let found: { page: number; stored: StoredSessionEventPageV1 } | undefined;
+    while (low <= high) {
+      const middle = Math.floor((low + high) / 2);
+      const stored = requirePage(
+        await this.storage.get<StoredSessionEventPageV1>(
+          sessionEventLogPageKey(sessionId, middle),
+        ),
+        sessionId,
+        middle,
+      );
+      if (stored.startSeq <= seq) {
+        found = { page: middle, stored };
+        low = middle + 1;
+      } else {
+        high = middle - 1;
+      }
+    }
+    return found;
   }
 
   async readProjections(
@@ -522,6 +640,23 @@ export class SessionEventLog {
     };
   }
 
+  /**
+   * One stored entry at display fidelity.
+   *
+   * Only a cut `model/request` is answered from its durable projection: every
+   * other cut event carries content the conversation renders, so it is
+   * hydrated exactly and costs storage in proportion to what is shown.
+   */
+  private async displayEvent(
+    sessionId: string,
+    entry: StoredSessionEventV1,
+  ): Promise<SessionEvent> {
+    if (entry.storage === "cut" && entry.projection.type === "model/request") {
+      return decodeSessionEvent(displayModelRequest(entry.projection));
+    }
+    return this.exactEvent(sessionId, entry);
+  }
+
   private async exactEvent(
     sessionId: string,
     entry: StoredSessionEventV1,
@@ -717,6 +852,42 @@ export class SessionEventLog {
   }
 }
 
+function storedEventSeq(entry: StoredSessionEventV1): number {
+  return entry.storage === "inline" ? entry.event.seq : entry.projection.seq;
+}
+
+/**
+ * A `model/request` event rebuilt from its durable projection.
+ *
+ * The system prompt is the projection's excerpt and carries its own cut
+ * marker; messages and tools are empty because their counts, not their
+ * contents, are what the projection retained. This is deliberately not the
+ * request the model ran on, and it never reaches recovery, compaction, or
+ * audit — only the transcript, which does not render model requests at all.
+ */
+function displayModelRequest(
+  projection: StoredSessionEventCutV1["projection"],
+): Record<string, unknown> {
+  const request = (projection.request ?? {}) as Record<string, unknown>;
+  const excerpt = (request.excerpt ?? {}) as Record<string, unknown>;
+  return {
+    type: "model/request",
+    seq: projection.seq,
+    timestamp: projection.timestamp,
+    turn: typeof projection.turn === "number" ? projection.turn : 0,
+    step: typeof projection.step === "number" ? projection.step : 0,
+    request: {
+      requestId: typeof request.requestId === "string" ? request.requestId : "",
+      provider: typeof request.provider === "string" ? request.provider : "",
+      model: typeof request.model === "string" ? request.model : "",
+      system: typeof excerpt.system === "string" ? excerpt.system : "",
+      messages: [],
+      tools: [],
+      ...(request.modelBinding ? { modelBinding: request.modelBinding } : {}),
+    },
+  };
+}
+
 function isEventRange(
   value: unknown,
 ): value is { startSeq: number; endSeq: number } {