@@ -0,0 +1,163 @@
+import { describe, test, expect } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  EVENT_LOG_ENV,
+  EVENT_LOG_FILE,
+  createEventLogWriter,
+  isEventLogEnabled,
+  openEventLogWriter,
+} from "./event-log.js";
+
+function tempDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "event-log-"));
+}
+
+function rawLines(dir: string, file: string = EVENT_LOG_FILE): string[] {
+  const raw = fs.readFileSync(path.join(dir, file), "utf8");
+  return raw.split("\n").filter((line) => line.length > 0);
+}
+
+describe("createEventLogWriter", () => {
+  test("appends one JSON line per event with id, type, seq, ts, and payload", async () => {
+    const dir = tempDir();
+    const writer = createEventLogWriter(dir, { now: () => 1_700_000_000_000 });
+    const first = await writer.append({
+      id: "evt-1",
+      type: "session.started",
+      payload: { task: "hello" },
+    });
+    const second = await writer.append({ id: "evt-2", type: "turn.done" });
+
+    expect(first).toEqual({
+      id: "evt-1",
+      type: "session.started",
+      seq: 0,
+      ts: 1_700_000_000_000,
+      payload: { task: "hello" },
+    });
+    expect(second.seq).toBe(1);
+
+    const lines = rawLines(dir);
+    expect(lines).toHaveLength(2);
+    for (const line of lines) {
+      expect(() => JSON.parse(line)).not.toThrow();
+      expect(line.endsWith("\n")).toBe(false);
+    }
+    expect(lines[0]).toBe(JSON.stringify(first));
+  });
+
+  test("preserves append order and assigns seq in order", async () => {
+    const dir = tempDir();
+    const writer = createEventLogWriter(dir);
+    const ids = ["a", "b", "c", "d", "e"];
+    for (const id of ids) {
+      await writer.append({ id, type: "event" });
+    }
+
+    const records = await writer.readAll();
+    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 },
+    );
+    expect(lines.map((l) => l.id)).toEqual(ids);
+  });
+
+  test("keeps parentId linkage resolvable across the stream", async () => {
+    const dir = tempDir();
+    const writer = createEventLogWriter(dir);
+    await writer.append({ id: "root", type: "session.started" });
+    await writer.append({ id: "turn-1", parentId: "root", type: "turn.done" });
+    await writer.append({
+      id: "turn-2",
+      parentId: "turn-1",
+      type: "turn.done",
+    });
+
+    const records = await writer.readAll();
+    expect(records.map((r) => r.parentId)).toEqual([
+      undefined,
+      "root",
+      "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";
+    while (cursor !== undefined) {
+      const record = byId.get(cursor);
+      if (record === undefined) throw new Error(`missing event ${cursor}`);
+      chain.push(record.id);
+      cursor = record.parentId;
+    }
+    expect(chain).toEqual(["turn-2", "turn-1", "root"]);
+  });
+
+  test("a reopened writer continues seq and preserves prior events", async () => {
+    const dir = tempDir();
+    const first = createEventLogWriter(dir);
+    await first.append({ id: "evt-1", type: "session.started" });
+    await first.append({ id: "evt-2", type: "turn.done" });
+    await first.close();
+
+    // New writer on the same file: seq continues from the on-disk line count.
+    const reopened = createEventLogWriter(dir);
+    const third = await reopened.append({ id: "evt-3", type: "turn.done" });
+    expect(third.seq).toBe(2);
+
+    const records = await reopened.readAll();
+    expect(records.map((r) => r.id)).toEqual(["evt-1", "evt-2", "evt-3"]);
+    expect(records.map((r) => r.seq)).toEqual([0, 1, 2]);
+    await reopened.close();
+  });
+
+  test("appends reject after close", async () => {
+    const dir = tempDir();
+    const writer = createEventLogWriter(dir);
+    await writer.close();
+    await expect(writer.append({ id: "late", type: "event" })).rejects.toThrow(
+      "closed",
+    );
+  });
+});
+
+describe("event log flag gating", () => {
+  test("isEventLogEnabled treats unset and falsy values as off", () => {
+    expect(isEventLogEnabled({})).toBe(false);
+    expect(isEventLogEnabled({ [EVENT_LOG_ENV]: "" })).toBe(false);
+    expect(isEventLogEnabled({ [EVENT_LOG_ENV]: "0" })).toBe(false);
+    expect(isEventLogEnabled({ [EVENT_LOG_ENV]: "false" })).toBe(false);
+    expect(isEventLogEnabled({ [EVENT_LOG_ENV]: "no" })).toBe(false);
+    expect(isEventLogEnabled({ [EVENT_LOG_ENV]: "1" })).toBe(true);
+    expect(isEventLogEnabled({ [EVENT_LOG_ENV]: "true" })).toBe(true);
+  });
+
+  test("openEventLogWriter returns null (inert) when the flag is off", () => {
+    const dir = tempDir();
+    expect(openEventLogWriter(dir, { flagEnv: {} })).toBeNull();
+    expect(
+      openEventLogWriter(dir, { flagEnv: { [EVENT_LOG_ENV]: "0" } }),
+    ).toBeNull();
+    // Nothing is created on disk while the log is disabled.
+    expect(fs.existsSync(path.join(dir, EVENT_LOG_FILE))).toBe(false);
+  });
+
+  test("openEventLogWriter returns a live writer when the flag is on", async () => {
+    const dir = tempDir();
+    const writer = openEventLogWriter(dir, {
+      flagEnv: { [EVENT_LOG_ENV]: "1" },
+    });
+    expect(writer).not.toBeNull();
+    if (writer === null)
+      throw new Error("flag-enabled writer should not be null");
+    await writer.append({ id: "evt-1", type: "session.started" });
+    expect(await writer.readAll()).toHaveLength(1);
+    expect(fs.existsSync(path.join(dir, EVENT_LOG_FILE))).toBe(true);
+    await writer.close();
+  });
+});