refactor(session): drop event-log narration

Author: TheGreatAxios

src/session/event-log.test.ts

@@ -33,7 +33,6 @@ describe("createEventStreamWriter", () => {
     });
     const second = await writer.append({ id: "fixed-id", type: "turn.done" });
 
-    // Event ids are UUIDv7 when the caller does not supply one.
     expect(isSessionId(first.id)).toBe(true);
     expect(first).toEqual({
       id: first.id,
@@ -66,7 +65,6 @@ describe("createEventStreamWriter", () => {
     expect(records.map((r) => r.id)).toEqual(ids);
     expect(records.map((r) => r.seq)).toEqual([0, 1, 2, 3, 4]);
 
-    // File order matches append order.
     const lines = rawLines(dir).map(
       (line) => JSON.parse(line) as { id: string },
     );
@@ -91,7 +89,6 @@ describe("createEventStreamWriter", () => {
       "turn-1",
     ]);
 
-    // Walk the chain from the tail back to the root through parentId.
     const byId = new Map(records.map((r) => [r.id, r]));
     const chain: string[] = [];
     let cursor: string | undefined = "turn-2";
@@ -111,7 +108,6 @@ describe("createEventStreamWriter", () => {
     await first.append({ id: "evt-2", type: "turn.done" });
     await first.flush();
 
-    // New writer on the same file: seq continues from the on-disk line count.
     const reopened = createEventStreamWriter(dir);
     const third = await reopened.append({ id: "evt-3", type: "turn.done" });
     expect(third.seq).toBe(2);
@@ -160,18 +156,15 @@ describe("createEventStreamWriter", () => {
     await writer.append({ id: "evt-1", type: "session.started" });
     await writer.flush();
 
-    // Simulate a crash mid-append: a partial line with no trailing newline.
     fs.appendFileSync(
       path.join(dir, EVENT_LOG_FILE),
       '{"id":"torn","type":"eve',
     );
 
-    // Reads drop the torn tail instead of throwing on it.
     const reader = createEventStreamWriter(dir);
     expect((await reader.readFrom(-1)).map((r) => r.id)).toEqual(["evt-1"]);
     expect(await reader.latestCursor()).toBe(0);
 
-    // The next append truncates the torn bytes and continues the seq.
     const reopened = createEventStreamWriter(dir);
     const next = await reopened.append({ id: "evt-2", type: "turn.done" });
     expect(next.seq).toBe(1);
@@ -280,7 +273,6 @@ describe("createEventStreamWriter", () => {
     );
     const writer = createEventStreamWriter(dir);
     expect(await writer.backfillFromLegacy()).toBe(2);
-    // A second run (e.g. after an interrupted first attempt) adds nothing.
     expect(await writer.backfillFromLegacy()).toBe(0);
 
     const records = await writer.readFrom(-1);
@@ -297,7 +289,6 @@ describe("createEventStreamWriter", () => {
     const writer = createEventStreamWriter(dir);
     expect(await writer.backfillFromLegacy()).toBe(2);
 
-    // Grow the legacy file; only the new line is backfilled.
     fs.appendFileSync(
       path.join(dir, "turns.jsonl"),
       '{"role":"user","text":"three"}\n',
@@ -326,7 +317,6 @@ describe("event stream flag gating", () => {
         flagEnv: { [SESSION_EVENT_LOG_ENV]: "true" },
       }),
     ).toBe(true);
-    // An explicit "off" env value wins over settings.
     for (const off of ["", "0", "false", "no", "off"]) {
       expect(
         isSessionEventLogEnabled({
@@ -347,7 +337,6 @@ describe("event stream flag gating", () => {
         flagEnv: { [SESSION_EVENT_LOG_ENV]: "off" },
       }),
     ).toBeNull();
-    // Nothing is created on disk while the flag is off.
     expect(fs.existsSync(path.join(dir, EVENT_LOG_FILE))).toBe(false);
   });
 

src/session/event-log.ts

@@ -4,69 +4,26 @@ import { join } from "node:path";
 import { generateSessionId } from "./index.js";
 import { withResolvedDirLock } from "./session-dir-lock.js";
 
-/**
- * Prototype for CL-9459: a single append-only session event stream (revives
- * CL-4351 for the Hub). One JSON object per line in `event-log.jsonl` inside
- * the session dir, coexisting with the segmented `turns.jsonl` writer without
- * touching the existing read path.
- *
- * Contract:
- * - Append-only: one event per line; the file is only grown by `appendFile`.
- *   A torn tail (an unterminated partial line from an interrupted append) is
- *   dropped on read and truncated before the next append so `seq` stays
- *   contiguous.
- * - Ordering: `seq` is a monotonic per-file index assigned in append order;
- *   file order equals append order.
- * - Serialization: every append runs inside `withResolvedDirLock`
- *   (`session-dir-lock.ts`), with `seq` derived from the on-disk complete
- *   line count, so concurrent writers on one dir can neither interleave lines
- *   nor duplicate seqs.
- * - Linkage: events may carry `parentId` pointing at the `id` of the event
- *   they continue.
- * - Ids: UUIDv7 via the existing `generateSessionId` pattern; a reopened
- *   writer continues an existing log from the on-disk line count.
- *
- * Flag-gated and inert by design: `settings.sessionEventLog` with env
- * override `CORBITS_SESSION_EVENT_LOG`; an explicit "off" env value (`0`,
- * `false`, `no`, `off`, empty) forces the feature off even when settings
- * enable it. Nothing in the current write/read path imports this module;
- * production would enter through `openEventStreamWriter`, which returns null
- * when the flag is off.
- */
-
-/** On-disk name of the append-only event stream within a session dir. */
 export const EVENT_LOG_FILE = "event-log.jsonl";
 
-/** Env override for the flag (e.g. `CORBITS_SESSION_EVENT_LOG=1`). */
 export const SESSION_EVENT_LOG_ENV = "CORBITS_SESSION_EVENT_LOG";
 
-/** One event as persisted: a single JSON line in `EVENT_LOG_FILE`. */
 export interface EventStreamRecord {
-  /** UUIDv7 event id; linkage target for child events (`parentId`). */
   id: string;
-  /** id of the parent event this one continues, when any. */
   parentId?: string;
-  /** Event kind, e.g. `session.started`, `turn.done`, `turn.error`. */
   type: string;
-  /** Monotonic per-file index assigned by the writer in append order. */
   seq: number;
-  /** Unix ms timestamp assigned by the writer at append time. */
   ts: number;
-  /** Free-form event payload. */
   payload?: unknown;
 }
 
-/** Caller-supplied fields for one appended event; seq/ts are assigned. */
 export interface AppendEventInput {
-  /** UUIDv7 id; generated (via `generateSessionId`) when omitted. */
   id?: string;
   parentId?: string;
   type: string;
   payload?: unknown;
 }
 
-/** The 7-method writer contract: append/flush/readFrom/latestCursor plus the
- * Phase A projections and the legacy backfill. */
 export interface EventStreamWriter {
   append(event: AppendEventInput): Promise<EventStreamRecord>;
   flush(): Promise<void>;
@@ -78,19 +35,14 @@ export interface EventStreamWriter {
 }
 
 export interface EventStreamWriterOptions {
-  /** Clock override for `ts` (tests). */
   now?: () => number;
 }
 
 export interface OpenEventStreamWriterOptions extends EventStreamWriterOptions {
-  /** `settings.sessionEventLog` value; defaults to undefined (off). */
   settings?: { sessionEventLog?: boolean };
-  /** Env override for the flag check; defaults to `process.env`. */
   flagEnv?: Record<string, string | undefined>;
 }
 
-/** Resolve the event-log flag from `settings.sessionEventLog` with an env
- * override; an explicit "off" env value wins over settings. */
 export function isSessionEventLogEnabled(
   sources: OpenEventStreamWriterOptions = {},
 ): boolean {
@@ -117,7 +69,6 @@ function isENOENT(err: unknown): boolean {
   );
 }
 
-/** FNV-1a 32-bit hash of a legacy line; the idempotency key for backfill. */
 function hashLine(line: string): string {
   let hash = 0x811c9dc5;
   for (let i = 0; i < line.length; i++) {
@@ -127,8 +78,7 @@ function hashLine(line: string): string {
   return (hash >>> 0).toString(16).padStart(8, "0");
 }
 
-/** Complete, non-empty lines of `raw`; an unterminated final line (a torn
- * tail) is dropped so reads never throw on it and `seq` stays contiguous. */
+// Drop an unterminated tail so a torn append does not shift seq.
 function completeLines(raw: string): string[] {
   if (raw.length === 0) return [];
   const split = raw.split("\n");
@@ -149,20 +99,14 @@ async function readRawOrEmpty(filePath: string): Promise<string> {
   }
 }
 
-/** Drop a torn tail from disk so the next append starts on a fresh line;
- * no-op when the file ends with a newline (or is empty). */
+// Truncate the torn tail on disk so the next append cannot glue onto it.
 async function dropTornTail(filePath: string, raw: string): Promise<string> {
   if (raw.length === 0 || raw.endsWith("\n")) return raw;
   const lastNl = raw.lastIndexOf("\n");
   await truncate(filePath, lastNl + 1);
   return raw.slice(0, lastNl + 1);
 }
 
-/** Raw append-only event stream writer (not itself flag-gated; tests and
- * `openEventStreamWriter` use this). Appends run inside
- * `withResolvedDirLock` and derive `seq` from the on-disk complete line
- * count, so every writer on a dir — including concurrent ones — serializes
- * and assigns unique contiguous seqs. */
 export function createEventStreamWriter(
   dir: string,
   opts: EventStreamWriterOptions = {},
@@ -171,8 +115,7 @@ export function createEventStreamWriter(
   const filePath = join(dir, EVENT_LOG_FILE);
 
   let dirReady: Promise<void> | null = null;
-  // Appends issued by this writer; awaited by flush(). Cross-writer ordering
-  // is the dir lock's job; this only tracks this writer's own in-flight work.
+  // flush() waits on this writer only; the dir lock orders concurrent writers.
   let pending: Promise<unknown> = Promise.resolve();
 
   const ensureDir = async (): Promise<void> => {
@@ -182,7 +125,7 @@ export function createEventStreamWriter(
     await dirReady;
   };
 
-  // Caller must already hold the dir lock (append/backfillFromLegacy wrap it).
+  // Seq is the on-disk line count, so callers must already hold the dir lock.
   const appendLocked = async (
     event: AppendEventInput,
   ): Promise<EventStreamRecord> => {
@@ -259,9 +202,7 @@ export function createEventStreamWriter(
         if (isENOENT(err)) return 0;
         throw err;
       }
-      // Idempotency: lines already backfilled (content hash present in the
-      // stream) are skipped, so re-running after a partial backfill cannot
-      // duplicate legacy events.
+      // Content hash, not position, so a partial re-run cannot duplicate lines.
       const records = await readAll();
       const existingKeys = new Set<string>();
       for (const record of records) {
@@ -280,8 +221,6 @@ export function createEventStreamWriter(
         try {
           record = JSON.parse(line);
         } catch {
-          // A torn legacy line is not backfilled; the append-only log keeps
-          // whatever it has already persisted.
           continue;
         }
         const event: AppendEventInput = {
@@ -308,11 +247,6 @@ export function createEventStreamWriter(
   };
 }
 
-/** Flag-gated entry point: returns a live writer only when the
- * `settings.sessionEventLog` / `CORBITS_SESSION_EVENT_LOG` flag is enabled,
- * otherwise null (inert — nothing is written). This is the seam the
- * segmented-writer path would call when the feature lands; today nothing
- * calls it, so the prototype cannot affect the existing read path. */
 export function openEventStreamWriter(
   dir: string,
   opts: OpenEventStreamWriterOptions = {},