feat: close architecture gaps G1, G2, G3 — error types, state versioning, structured logging (#27)

* feat(g1): add structured error types with toBeamCodeError and errorMessage utilities

* refactor(g1): replace local toError with toBeamCodeError in process-supervisor

* feat(g3): add structured JSON logger with level filtering and safe serialization

* feat(g3): wire structured logger as default in beamcode entry point

* feat(g2): add state schema versioning with step-registry migrator

- Add state-migrator with step-registry pattern (Map<version, MigrationFn>)
- Wire migrateSession into FileStorage load/loadAll/saveSync
- Stamp schemaVersion on save, migrate on load
- Add schemaVersion field to PersistedSession type
- v0→v1 migration: ensure messageHistory, pendingMessages, pendingPermissions
- Skip unmigrateable sessions in loadAll instead of crashing

* docs: add G1/G2/G3 architecture gaps implementation plan

* fix: address CI type check failure and review feedback

- Fix TS2352: cast Record<string, unknown> via unknown for PersistedSession
- Prevent log field spoofing: skip reserved keys (time, level, msg, component) in ctx
- Extract makeV0Session helper to deduplicate test code
- Clean up stale section comments in index.ts exports

Author: teng-lin

docs/plans/2026-02-17-arch-gaps-g1-g2-g3.md

@@ -447,6 +447,91 @@ describe("FileStorage", () => {
     });
   });
 
+  // -----------------------------------------------------------------------
+  // Schema migration on load
+  // -----------------------------------------------------------------------
+
+  describe("schema migration on load", () => {
+    /** Create a v0 session JSON string (no schemaVersion field). */
+    function makeV0Session(id: string): string {
+      return JSON.stringify({
+        id,
+        state: {
+          session_id: id,
+          model: "test",
+          cwd: "/test",
+          tools: [],
+          permissionMode: "default",
+          claude_code_version: "1.0",
+          mcp_servers: [],
+          agents: [],
+          slash_commands: [],
+          skills: [],
+          total_cost_usd: 0,
+          num_turns: 0,
+          context_used_percent: 0,
+          is_compacting: false,
+          git_branch: "",
+          is_worktree: false,
+          repo_root: "",
+          git_ahead: 0,
+          git_behind: 0,
+          total_lines_added: 0,
+          total_lines_removed: 0,
+        },
+        messageHistory: [],
+      });
+    }
+
+    it("migrates unversioned sessions on load", () => {
+      writeFileSync(join(dir, `${VALID_UUID}.json`), makeV0Session(VALID_UUID));
+
+      const loaded = storage.load(VALID_UUID);
+      expect(loaded).not.toBeNull();
+      expect(loaded!.schemaVersion).toBe(1);
+      expect(loaded!.pendingMessages).toEqual([]);
+      expect(loaded!.pendingPermissions).toEqual([]);
+    });
+
+    it("stamps schemaVersion on save", () => {
+      const session = makeSession(VALID_UUID);
+      storage.saveSync(session);
+
+      // Read raw file to check schemaVersion was stamped
+      const raw = JSON.parse(readFileSync(join(dir, `${VALID_UUID}.json`), "utf-8"));
+      expect(raw.schemaVersion).toBe(1);
+    });
+
+    it("migrates unversioned sessions in loadAll", () => {
+      writeFileSync(join(dir, `${VALID_UUID}.json`), makeV0Session(VALID_UUID));
+      writeFileSync(join(dir, `${VALID_UUID_2}.json`), makeV0Session(VALID_UUID_2));
+
+      const all = storage.loadAll();
+      expect(all).toHaveLength(2);
+      for (const session of all) {
+        expect(session.schemaVersion).toBe(1);
+      }
+    });
+
+    it("skips sessions that fail migration in loadAll", () => {
+      // Write a valid session
+      storage.saveSync(makeSession(VALID_UUID));
+      // Write a session with a future schema version (unmigrateable)
+      writeFileSync(
+        join(dir, `${VALID_UUID_2}.json`),
+        JSON.stringify({
+          id: VALID_UUID_2,
+          state: { session_id: VALID_UUID_2 },
+          schemaVersion: 999,
+        }),
+      );
+
+      const all = storage.loadAll();
+      expect(all).toHaveLength(1);
+      expect(all[0].id).toBe(VALID_UUID);
+    });
+  });
+
   // -----------------------------------------------------------------------
   // Error handling (atomic write failures)
   // -----------------------------------------------------------------------

src/adapters/file-storage.test.ts

@@ -12,6 +12,7 @@ import {
 import { join, normalize, resolve } from "node:path";
 import type { LauncherStateStorage, SessionStorage } from "../interfaces/storage.js";
 import type { PersistedSession } from "../types/session-state.js";
+import { CURRENT_SCHEMA_VERSION, migrateSession } from "./state-migrator.js";
 
 const SESSION_ID_PATTERN = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
 
@@ -129,6 +130,7 @@ export class FileStorage implements SessionStorage, LauncherStateStorage {
 
   saveSync(session: PersistedSession): void {
     try {
+      session.schemaVersion = CURRENT_SCHEMA_VERSION;
       this.atomicWrite(this.filePath(session.id), JSON.stringify(session));
     } catch (err) {
       // Log but don't crash — storage failures shouldn't kill sessions
@@ -139,7 +141,7 @@ export class FileStorage implements SessionStorage, LauncherStateStorage {
   load(sessionId: string): PersistedSession | null {
     try {
       const raw = readFileSync(this.filePath(sessionId), "utf-8");
-      return JSON.parse(raw) as PersistedSession;
+      return migrateSession(JSON.parse(raw));
     } catch {
       return null;
     }
@@ -157,7 +159,8 @@ export class FileStorage implements SessionStorage, LauncherStateStorage {
         if (!SESSION_ID_PATTERN.test(sessionId)) continue;
         try {
           const raw = readFileSync(safeJoin(this.dir, file), "utf-8");
-          sessions.push(JSON.parse(raw));
+          const migrated = migrateSession(JSON.parse(raw));
+          if (migrated) sessions.push(migrated);
         } catch {
           // Skip corrupt files
         }

src/adapters/file-storage.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import { CURRENT_SCHEMA_VERSION, migrateSession } from "./state-migrator.js";
+
+describe("state-migrator", () => {
+  it("returns null for null input", () => {
+    expect(migrateSession(null)).toBeNull();
+  });
+
+  it("returns null for non-object input", () => {
+    expect(migrateSession("string")).toBeNull();
+    expect(migrateSession(42)).toBeNull();
+  });
+
+  it("returns null when id is not a string", () => {
+    expect(migrateSession({ state: {} })).toBeNull();
+    expect(migrateSession({ id: 123, state: {} })).toBeNull();
+  });
+
+  it("returns null when state is not an object", () => {
+    expect(migrateSession({ id: "test", state: "corrupt" })).toBeNull();
+    expect(migrateSession({ id: "test" })).toBeNull();
+  });
+
+  it("adds schemaVersion to v0 (unversioned) sessions", () => {
+    const v0 = { id: "test-id", state: { session_id: "test-id" }, messageHistory: [] };
+    const result = migrateSession(v0);
+    expect(result).not.toBeNull();
+    expect(result!.schemaVersion).toBe(CURRENT_SCHEMA_VERSION);
+  });
+
+  it("passes through current-version sessions unchanged", () => {
+    const current = {
+      id: "test-id",
+      state: { session_id: "test-id" },
+      messageHistory: [],
+      pendingMessages: [],
+      pendingPermissions: [],
+      schemaVersion: CURRENT_SCHEMA_VERSION,
+    };
+    const result = migrateSession(current);
+    expect(result).toEqual(current);
+  });
+
+  it("returns null for future versions it cannot handle", () => {
+    const future = {
+      id: "test-id",
+      state: { session_id: "test-id" },
+      messageHistory: [],
+      schemaVersion: 999,
+    };
+    expect(migrateSession(future)).toBeNull();
+  });
+
+  it("adds default fields missing in v0 sessions", () => {
+    const v0 = { id: "test-id", state: { session_id: "test-id" } };
+    const result = migrateSession(v0);
+    expect(result!.messageHistory).toEqual([]);
+    expect(result!.pendingMessages).toEqual([]);
+    expect(result!.pendingPermissions).toEqual([]);
+  });
+});

src/adapters/state-migrator.test.ts

@@ -0,0 +1,51 @@
+import type { PersistedSession } from "../types/session-state.js";
+
+export const CURRENT_SCHEMA_VERSION = 1;
+
+type MigrationFn = (session: Record<string, unknown>) => Record<string, unknown>;
+
+/** Map from source version to the function that migrates to source+1. */
+const migrations: Map<number, MigrationFn> = new Map([[0, migrateV0ToV1]]);
+
+function migrateV0ToV1(session: Record<string, unknown>): Record<string, unknown> {
+  return {
+    ...session,
+    messageHistory: Array.isArray(session.messageHistory) ? session.messageHistory : [],
+    pendingMessages: Array.isArray(session.pendingMessages) ? session.pendingMessages : [],
+    pendingPermissions: Array.isArray(session.pendingPermissions) ? session.pendingPermissions : [],
+    schemaVersion: 1,
+  };
+}
+
+/**
+ * Migrate a persisted session to the current schema version.
+ * Returns null if the session cannot be migrated (corrupt, missing fields, or future version).
+ */
+export function migrateSession(raw: unknown): PersistedSession | null {
+  if (raw == null || typeof raw !== "object") return null;
+
+  const session = raw as Record<string, unknown>;
+
+  // Required fields
+  if (typeof session.id !== "string") return null;
+  if (session.state == null || typeof session.state !== "object") return null;
+
+  let version = typeof session.schemaVersion === "number" ? session.schemaVersion : 0;
+
+  // Cannot downgrade from future versions
+  if (version > CURRENT_SCHEMA_VERSION) return null;
+
+  // Already current
+  if (version === CURRENT_SCHEMA_VERSION) return raw as unknown as PersistedSession;
+
+  // Run migration chain
+  let current = session;
+  while (version < CURRENT_SCHEMA_VERSION) {
+    const migrate = migrations.get(version);
+    if (!migrate) return null; // Gap in migration chain
+    current = migrate(current);
+    version++;
+  }
+
+  return current as unknown as PersistedSession;
+}

src/adapters/state-migrator.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import { LogLevel, StructuredLogger } from "./structured-logger.js";
+
+describe("StructuredLogger", () => {
+  it("outputs JSON lines to the writer", () => {
+    const lines: string[] = [];
+    const logger = new StructuredLogger({ writer: (line) => lines.push(line) });
+
+    logger.info("server started", { port: 3456 });
+
+    const parsed = JSON.parse(lines[0]);
+    expect(parsed.level).toBe("info");
+    expect(parsed.msg).toBe("server started");
+    expect(parsed.port).toBe(3456);
+    expect(parsed.time).toBeTypeOf("string"); // ISO 8601
+  });
+
+  it("respects log level filtering", () => {
+    const lines: string[] = [];
+    const logger = new StructuredLogger({
+      writer: (line) => lines.push(line),
+      level: LogLevel.WARN,
+    });
+
+    logger.debug("hidden");
+    logger.info("hidden");
+    logger.warn("visible");
+    logger.error("visible");
+
+    expect(lines).toHaveLength(2);
+  });
+
+  it("includes component name when set", () => {
+    const lines: string[] = [];
+    const logger = new StructuredLogger({
+      writer: (line) => lines.push(line),
+      component: "session-bridge",
+    });
+
+    logger.info("test");
+
+    const parsed = JSON.parse(lines[0]);
+    expect(parsed.component).toBe("session-bridge");
+  });
+
+  it("passes correlation ID through ctx parameter", () => {
+    const lines: string[] = [];
+    const logger = new StructuredLogger({ writer: (line) => lines.push(line) });
+
+    logger.info("message received", { correlationId: "sess-abc-123" });
+
+    const parsed = JSON.parse(lines[0]);
+    expect(parsed.correlationId).toBe("sess-abc-123");
+  });
+
+  it("serializes error objects with stack", () => {
+    const lines: string[] = [];
+    const logger = new StructuredLogger({ writer: (line) => lines.push(line) });
+
+    logger.error("failed", { error: new Error("boom") });
+
+    const parsed = JSON.parse(lines[0]);
+    expect(parsed.error).toBe("boom");
+    expect(parsed.errorStack).toContain("Error: boom");
+  });
+
+  it("does not allow ctx to overwrite reserved fields", () => {
+    const lines: string[] = [];
+    const logger = new StructuredLogger({
+      writer: (line) => lines.push(line),
+      component: "test",
+    });
+
+    logger.info("spoofed", { level: "debug", time: "fake", msg: "injected", component: "evil" });
+
+    const parsed = JSON.parse(lines[0]);
+    expect(parsed.level).toBe("info");
+    expect(parsed.msg).toBe("spoofed");
+    expect(parsed.component).toBe("test");
+    expect(parsed.time).not.toBe("fake");
+  });
+
+  it("survives circular references in ctx", () => {
+    const lines: string[] = [];
+    const logger = new StructuredLogger({ writer: (line) => lines.push(line) });
+
+    const circular: Record<string, unknown> = { key: "value" };
+    circular.self = circular;
+
+    // Should not throw
+    logger.error("circular data", circular);
+
+    expect(lines).toHaveLength(1);
+    const parsed = JSON.parse(lines[0]);
+    expect(parsed.msg).toBe("circular data");
+  });
+});