@celestea/session 2.7.1

package/dist/checkpoint.js

@@ -0,0 +1,292 @@
+/**
+ * `checkpoint.json` — the per-session crash / shutdown sidecar (iteration E §1.2).
+ *
+ * WHY this file exists at all: `cli-main.jsonl` is the ONLY source of truth for
+ * the conversation (K4), and everything derivable from it (turn counter,
+ * history, last outcome) is deliberately NOT persisted twice. What the log can
+ * NOT express is the difference between
+ *
+ *   - "a turn is open because this process is running it right now" and
+ *   - "a turn is open because the process died mid-turn"
+ *
+ * so exactly those two facts are written here: the process identity
+ * (`pid`/`boot_id`/`clean_shutdown`) and the open turn (`open_turn`).
+ *
+ * Failure discipline (fail-safe, §1.2.2 / R1-3):
+ *   - missing file        -> "no checkpoint" (never repair, never invent);
+ *   - unparsable / unknown `version` / `session` mismatch -> the WHOLE file is
+ *     ignored and warned about, and the caller degrades to "no checkpoint" — a
+ *     corrupt sidecar must never read as "the last exit was clean";
+ *   - a failing write is reported and swallowed: checkpointing is observation,
+ *     so it can never fail a turn (the session log's own degradation model).
+ *
+ * Write discipline: `<path>.tmp-<pid>` -> `rename` (atomic), mode `0600`,
+ * pretty-printed JSON — the same rules as every other data file
+ * (`contracts/data-files/index.json` durability map).
+ */
+import { chmodSync, existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { outcomePhase } from "@celestea/core";
+/** File name inside a session directory (contract). */
+export const CHECKPOINT_FILE_NAME = "checkpoint.json";
+/** The only accepted `version`; anything else is "unknown schema" -> ignored. */
+export const CHECKPOINT_VERSION = 1;
+/** `b-<8 hex>` — short, greppable, unique per process start. */
+export function newBootId() {
+    return `b-${randomBytes(4).toString("hex")}`;
+}
+const PROCESS_BOOT_ID = newBootId();
+/** The identity of THIS process (stable for its whole life). */
+export function currentProcessIdentity() {
+    return { boot_id: PROCESS_BOOT_ID, pid: process.pid };
+}
+export function checkpointPathFor(dir) {
+    return join(dir, CHECKPOINT_FILE_NAME);
+}
+/** A fresh, empty checkpoint of the current process. */
+export function freshCheckpoint(session, identity, now) {
+    return {
+        version: CHECKPOINT_VERSION,
+        session,
+        pid: identity.pid,
+        boot_id: identity.boot_id,
+        updated_at: now,
+        clean_shutdown: false,
+        open_turn: null,
+        last_outcome: null,
+        degraded: { log_write_errors: 0 },
+        lanes: { next_turn: [], next_step: [] },
+        delivered_ids: [],
+        repaired: [],
+    };
+}
+/** Atomic write: tmp file in the same directory -> rename, mode 0600. */
+export function writeCheckpointFile(path, value) {
+    const tmp = `${path}.tmp-${process.pid}`;
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, path);
+}
+/** Read + validate; missing / corrupt / foreign files are never an exception. */
+export function readCheckpointFile(path, session) {
+    if (!existsSync(path))
+        return { kind: "missing" };
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (e) {
+        return { kind: "invalid", error: messageOf(e) };
+    }
+    if (text.trim() === "")
+        return { kind: "invalid", error: "empty file" };
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        return { kind: "invalid", error: messageOf(e) };
+    }
+    return validateCheckpoint(raw, session);
+}
+/** Shape gate: version, self-description, open_turn and the repair list. */
+export function validateCheckpoint(raw, session) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return { kind: "invalid", error: "not a JSON object" };
+    const value = raw;
+    if (value.version !== CHECKPOINT_VERSION)
+        return { kind: "invalid", error: `unknown version: ${String(value.version)}` };
+    if (typeof value.session !== "string" || value.session !== session) {
+        return { kind: "invalid", error: `session mismatch: ${String(value.session)} != ${session}` };
+    }
+    if (!(value.open_turn === null || value.open_turn === undefined || isOpenTurn(value.open_turn))) {
+        return { kind: "invalid", error: "malformed open_turn" };
+    }
+    if (value.repaired !== undefined && !Array.isArray(value.repaired))
+        return { kind: "invalid", error: "malformed repaired[]" };
+    return { kind: "ok", value: normalize(value, session) };
+}
+function isOpenTurn(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const turn = value;
+    return typeof turn.id === "string" && typeof turn.started_at === "number";
+}
+/** Fill every optional key so consumers never read `undefined`. */
+function normalize(value, session) {
+    const lanes = value.lanes ?? { next_turn: [], next_step: [] };
+    return {
+        version: CHECKPOINT_VERSION,
+        session,
+        pid: typeof value.pid === "number" ? value.pid : 0,
+        boot_id: typeof value.boot_id === "string" ? value.boot_id : "",
+        updated_at: typeof value.updated_at === "number" ? value.updated_at : 0,
+        clean_shutdown: value.clean_shutdown === true,
+        open_turn: value.open_turn ?? null,
+        last_outcome: typeof value.last_outcome === "string" ? value.last_outcome : null,
+        degraded: { log_write_errors: Math.max(0, Math.trunc(value.degraded?.log_write_errors ?? 0)) },
+        lanes: { next_turn: laneOf(lanes.next_turn), next_step: laneOf(lanes.next_step) },
+        delivered_ids: Array.isArray(value.delivered_ids) ? value.delivered_ids.filter((id) => typeof id === "string") : [],
+        repaired: (value.repaired ?? []).filter(isRepair),
+    };
+}
+/** A persisted lane is a list of messages; anything else is dropped, never fatal. */
+function laneOf(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((m) => m !== null && typeof m === "object" && typeof m.id === "string");
+}
+function isRepair(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const repair = value;
+    return typeof repair.turn_id === "string" && typeof repair.at === "number";
+}
+function messageOf(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/**
+ * ONE session's checkpoint: in memory + on disk. Mutations are the write
+ * timings of §1.2.2 (turn start, turn end, clean shutdown). Any activity marks
+ * the process alive again (`clean_shutdown: false`); `markCleanShutdown` is the
+ * only transition to `true`.
+ */
+export class CheckpointStore {
+    path;
+    session;
+    identity;
+    now;
+    warn;
+    sample;
+    loaded = null;
+    state = null;
+    observations = [];
+    degradedReported = false;
+    onDegraded;
+    constructor(opts) {
+        this.session = opts.session;
+        this.identity = opts.identity ?? currentProcessIdentity();
+        this.now = opts.now ?? Date.now;
+        this.warn = opts.warn ?? ((message) => process.stderr.write(`[celestea-session] ${message}\n`));
+        this.sample = opts.logWriteErrors ?? (() => 0);
+        this.onDegraded = opts.onDegraded ?? null;
+        this.path = checkpointPathFor(opts.dir);
+    }
+    /** The sidecar as found on disk (cached; never throws). */
+    load() {
+        if (this.loaded === null) {
+            const read = readCheckpointFile(this.path, this.session);
+            if (read.kind === "invalid")
+                this.observe(`checkpoint ignored (${this.path}): ${read.error}`);
+            this.loaded = read;
+        }
+        return this.loaded;
+    }
+    /** The current state (a fresh, empty checkpoint when missing / ignored). */
+    get current() {
+        if (this.state !== null)
+            return this.state;
+        const read = this.load();
+        if (read.kind !== "ok") {
+            this.state = freshCheckpoint(this.session, this.identity, this.now());
+            return this.state;
+        }
+        const value = { ...read.value, degraded: { log_write_errors: Math.max(read.value.degraded.log_write_errors, this.sample()) } };
+        this.state = value;
+        return value;
+    }
+    /** Observations gathered so far (ignored files, failed writes). */
+    warnings() {
+        return [...this.observations];
+    }
+    /** A turn is open from now on (written RIGHT AFTER `turn_start`). */
+    turnStarted(id) {
+        this.persist({ open_turn: { id, started_at: this.now() }, last_outcome: null });
+    }
+    /** The turn closed normally: no open turn, outcome recorded (§1.2.2). */
+    turnEnded(outcome) {
+        this.persist({ open_turn: null, last_outcome: outcomePhase(outcome) });
+    }
+    /** Clear a stale open turn WITHOUT touching the log (already-closed case). */
+    clearOpenTurn() {
+        this.persist({ open_turn: null });
+    }
+    /**
+     * The ONE crash repair: the log just got `turn_end: interrupted`, so the
+     * record goes into `repaired[]` — the log row itself stays indistinguishable
+     * from engine output (§1.2.3 幂等边界 4).
+     */
+    recordSynthesizedTurnEnd(turnId) {
+        const repaired = [...this.current.repaired, { at: this.now(), action: "synthesize_turn_end", turn_id: turnId }];
+        this.persist({ open_turn: null, last_outcome: "interrupted", repaired });
+    }
+    /** Graceful exit: `true` forbids any repair on the next boot. */
+    markCleanShutdown() {
+        this.persist({ open_turn: null, clean_shutdown: true });
+    }
+    /** Sample the log's degradation counter (sticky: a fork must stay visible). */
+    noteLogWriteErrors() {
+        if (this.sample() > 0)
+            this.persist({});
+    }
+    /**
+     * E §1.3 P1 ①: the two lanes + the delivered-id ledger, written by the SAME
+     * atomic path as every other field. This is the third (and last) write timing
+     * the sidecar has, so a crash can lose at most the newest queue change.
+     */
+    lanesChanged(nextTurn, nextStep, deliveredIds) {
+        this.persist({
+            lanes: { next_turn: [...nextTurn], next_step: [...nextStep] },
+            delivered_ids: [...deliveredIds],
+        });
+    }
+    /** The persisted lanes + delivered ledger of the file on disk (null = unusable). */
+    persistedQueues() {
+        const read = this.load();
+        return read.kind === "ok" ? { lanes: read.value.lanes, delivered_ids: read.value.delivered_ids } : null;
+    }
+    persist(patch) {
+        const base = this.current;
+        const next = {
+            ...base,
+            ...patch,
+            version: CHECKPOINT_VERSION,
+            session: this.session,
+            pid: this.identity.pid,
+            boot_id: this.identity.boot_id,
+            updated_at: this.now(),
+            // Any write means "this process is running this session": only an explicit
+            // markCleanShutdown may claim a graceful exit.
+            clean_shutdown: patch.clean_shutdown ?? false,
+            degraded: { log_write_errors: Math.max(base.degraded.log_write_errors, this.sample()) },
+        };
+        this.state = next;
+        this.loaded = { kind: "ok", value: next };
+        this.reportDegraded(next.degraded.log_write_errors);
+        try {
+            writeCheckpointFile(this.path, next);
+        }
+        catch (e) {
+            // Observation only: a sidecar that cannot be written must never fail a
+            // turn — the next boot simply sees "no checkpoint" and stays fail-safe.
+            this.observe(`checkpoint write failed (${this.path}): ${messageOf(e)}`);
+        }
+    }
+    /** §5.2③: a silent disk/memory fork is exactly what must never stay silent. */
+    reportDegraded(count) {
+        if (count <= 0 || this.degradedReported || this.onDegraded === null)
+            return;
+        this.degradedReported = true;
+        try {
+            this.onDegraded({ session: this.session, count });
+        }
+        catch (e) {
+            this.observe(`degraded audit hook failed: ${messageOf(e)}`);
+        }
+    }
+    observe(message) {
+        this.observations.push(message);
+        this.warn(message);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `@celestea/session` — the SessionLog implementations (plugin form).
+ *
+ * Responsibility: record SessionEvents in insertion order (in memory and as an
+ * append-only JSONL file), replay/repair a persisted log, and project the two
+ * message views. A2 (W746): the projection algorithm and the turn-id math are
+ * CORE's (`deriveMessagesFrom` / `formatTurnId`), re-exported here — this package
+ * owns storage, not seam semantics:
+ *   - the Studio projection (`projectMessages`, per-event, golden vs frozen HTTP);
+ *   - the engine model-visible history (`deriveMessages`, derive_messages).
+ *
+ * This package depends only on `@celestea/core` and is consumed by mounting
+ * `inMemorySessionLogPlugin` / `persistentSessionLogPlugin` into a Context.
+ *
+ * Module map:
+ *   log/derive.ts      derive_messages + balance_tool_calls   (re-export of core, A2)
+ *   log/memory.ts      InMemorySessionLog                     (session/log.rs)
+ *   log/file.ts        JSONL file replay / naming             (session/persistent.rs)
+ *   log/persistent.ts  PersistentSessionLog                   (session/persistent.rs)
+ *   plugin.ts          Context registration (SESSION_LOG_SERVICE)
+ *   jsonl.ts           file-level parse/serialize + codec re-exports
+ *   messages.ts        Studio projection + deriveMessages facade
+ *   turn-id.ts         turn id math + audit (re-export of core, A2)
+ *   replay.ts          replay analysis + SSE transcript derivation
+ *   checkpoint.ts      checkpoint.json sidecar: shape + atomic read/write
+ *   checkpoint-log.ts  SessionLog decorator: turn boundary -> checkpoint
+ *   checkpoint-recovery.ts  boot decision table (§1.2.3), append-only repair
+ */
+export * from "./log/derive.js";
+export * from "./log/memory.js";
+export * from "./log/file.js";
+export * from "./log/persistent.js";
+export * from "./plugin.js";
+export * from "./jsonl.js";
+export * from "./messages.js";
+export * from "./turn-id.js";
+export * from "./replay.js";
+export * from "./checkpoint.js";
+export * from "./checkpoint-log.js";
+export * from "./checkpoint-recovery.js";

package/dist/index.js

@@ -0,0 +1,40 @@
+/**
+ * `@celestea/session` — the SessionLog implementations (plugin form).
+ *
+ * Responsibility: record SessionEvents in insertion order (in memory and as an
+ * append-only JSONL file), replay/repair a persisted log, and project the two
+ * message views. A2 (W746): the projection algorithm and the turn-id math are
+ * CORE's (`deriveMessagesFrom` / `formatTurnId`), re-exported here — this package
+ * owns storage, not seam semantics:
+ *   - the Studio projection (`projectMessages`, per-event, golden vs frozen HTTP);
+ *   - the engine model-visible history (`deriveMessages`, derive_messages).
+ *
+ * This package depends only on `@celestea/core` and is consumed by mounting
+ * `inMemorySessionLogPlugin` / `persistentSessionLogPlugin` into a Context.
+ *
+ * Module map:
+ *   log/derive.ts      derive_messages + balance_tool_calls   (re-export of core, A2)
+ *   log/memory.ts      InMemorySessionLog                     (session/log.rs)
+ *   log/file.ts        JSONL file replay / naming             (session/persistent.rs)
+ *   log/persistent.ts  PersistentSessionLog                   (session/persistent.rs)
+ *   plugin.ts          Context registration (SESSION_LOG_SERVICE)
+ *   jsonl.ts           file-level parse/serialize + codec re-exports
+ *   messages.ts        Studio projection + deriveMessages facade
+ *   turn-id.ts         turn id math + audit (re-export of core, A2)
+ *   replay.ts          replay analysis + SSE transcript derivation
+ *   checkpoint.ts      checkpoint.json sidecar: shape + atomic read/write
+ *   checkpoint-log.ts  SessionLog decorator: turn boundary -> checkpoint
+ *   checkpoint-recovery.ts  boot decision table (§1.2.3), append-only repair
+ */
+export * from "./log/derive.js";
+export * from "./log/memory.js";
+export * from "./log/file.js";
+export * from "./log/persistent.js";
+export * from "./plugin.js";
+export * from "./jsonl.js";
+export * from "./messages.js";
+export * from "./turn-id.js";
+export * from "./replay.js";
+export * from "./checkpoint.js";
+export * from "./checkpoint-log.js";
+export * from "./checkpoint-recovery.js";

package/dist/jsonl.d.ts

@@ -0,0 +1,33 @@
+/**
+ * cli-main.jsonl parsing/serialization (file level).
+ *
+ * Contract: one SessionEvent per line; blank lines are padding; parsing STOPS at
+ * the first unparsable line (a torn tail is never treated as content) —
+ * src/api.rs:141-153. The per-row codec (validate / serde-exact serialize) and
+ * the TurnOutcome helpers live in `@celestea/core` (`session-event.ts`) and are
+ * re-exported here so existing imports keep working.
+ *
+ * "Blank" is a truly empty line (or a lone `\r`), matching the legacy replay
+ * (`record.is_empty()`); a whitespace-only line is an unparsable record.
+ */
+import { type SessionEvent } from "@celestea/core";
+export { DEFAULT_TURN_OUTCOME, effectiveOutcome, isSessionEventType, isTurnOutcome, outcomeError, outcomeErrorParts, outcomePhase, parseSessionEvent, serializeSessionEvent, validateSessionEvent, type ValidateResult, } from "@celestea/core";
+export interface TornTail {
+    /** 1-based line number of the first unparsable line. */
+    line: number;
+    raw: string;
+    error: string;
+}
+export interface ParseJsonlResult {
+    events: SessionEvent[];
+    /** Total physical lines in the input. */
+    lines: string[];
+    physicalLines: number;
+    blankLines: number;
+    /** Lines successfully parsed into events. */
+    parsedLines: number;
+    /** Everything from the first unparsable line onwards is ignored. */
+    tornTail: TornTail | null;
+}
+export declare function parseSessionJsonl(text: string): ParseJsonlResult;
+export declare function serializeSessionJsonl(events: readonly SessionEvent[]): string;

package/dist/jsonl.js

@@ -0,0 +1,44 @@
+/**
+ * cli-main.jsonl parsing/serialization (file level).
+ *
+ * Contract: one SessionEvent per line; blank lines are padding; parsing STOPS at
+ * the first unparsable line (a torn tail is never treated as content) —
+ * src/api.rs:141-153. The per-row codec (validate / serde-exact serialize) and
+ * the TurnOutcome helpers live in `@celestea/core` (`session-event.ts`) and are
+ * re-exported here so existing imports keep working.
+ *
+ * "Blank" is a truly empty line (or a lone `\r`), matching the legacy replay
+ * (`record.is_empty()`); a whitespace-only line is an unparsable record.
+ */
+import { parseSessionEvent, serializeSessionEvent } from "@celestea/core";
+export { DEFAULT_TURN_OUTCOME, effectiveOutcome, isSessionEventType, isTurnOutcome, outcomeError, outcomeErrorParts, outcomePhase, parseSessionEvent, serializeSessionEvent, validateSessionEvent, } from "@celestea/core";
+/** Strip one trailing `\r` (`trim_line_end`); the `\n` is already consumed. */
+function stripCr(line) {
+    return line.endsWith("\r") ? line.slice(0, -1) : line;
+}
+export function parseSessionJsonl(text) {
+    const lines = text.split("\n");
+    // A trailing newline produces a final empty element; it is not a line.
+    if (lines.length > 0 && lines[lines.length - 1] === "")
+        lines.pop();
+    const events = [];
+    let blankLines = 0;
+    let tornTail = null;
+    for (let i = 0; i < lines.length; i++) {
+        const raw = stripCr(lines[i] ?? "");
+        if (raw === "") {
+            blankLines += 1;
+            continue;
+        }
+        const parsed = parseSessionEvent(raw);
+        if (!parsed.ok) {
+            tornTail = { line: i + 1, raw, error: parsed.errors.join("; ") };
+            break;
+        }
+        events.push(parsed.event);
+    }
+    return { events, lines, physicalLines: lines.length, blankLines, parsedLines: events.length, tornTail };
+}
+export function serializeSessionJsonl(events) {
+    return events.map((ev) => serializeSessionEvent(ev)).join("\n") + (events.length > 0 ? "\n" : "");
+}

package/dist/log/derive.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The engine's `derive_messages` projection — A2 (W746): the algorithm moved
+ * to `@celestea/core` (`core/src/projection.ts`, the same 1:1 port of
+ * `crates/session/src/log.rs:73-204`), because it is seam behaviour, not
+ * implementation behaviour: every `SessionLog` must project the same history,
+ * and `SessionLog.deriveMessages()` is a seam method.
+ *
+ * This module stays as the stable import path inside the package (and for
+ * callers of `@celestea/session`) so nothing else has to move; the rules,
+ * parity notes and the W267 cursor quirk are documented where the code is.
+ */
+export { CANCELLED_TOOL_CALL_TEXT, balanceToolCalls, deriveMessagesFrom, flushToolCalls, projectEvent, toolResultText, } from "@celestea/core";

package/dist/log/derive.js

@@ -0,0 +1,12 @@
+/**
+ * The engine's `derive_messages` projection — A2 (W746): the algorithm moved
+ * to `@celestea/core` (`core/src/projection.ts`, the same 1:1 port of
+ * `crates/session/src/log.rs:73-204`), because it is seam behaviour, not
+ * implementation behaviour: every `SessionLog` must project the same history,
+ * and `SessionLog.deriveMessages()` is a seam method.
+ *
+ * This module stays as the stable import path inside the package (and for
+ * callers of `@celestea/session`) so nothing else has to move; the rules,
+ * parity notes and the W267 cursor quirk are documented where the code is.
+ */
+export { CANCELLED_TOOL_CALL_TEXT, balanceToolCalls, deriveMessagesFrom, flushToolCalls, projectEvent, toolResultText, } from "@celestea/core";

package/dist/log/file.d.ts

@@ -0,0 +1,43 @@
+/**
+ * cli-main.jsonl file-level replay — port of
+ * `crates/session/src/persistent.rs:282-402`.
+ *
+ * Contract:
+ *   - `file_name_for` sanitizes a session id (only `[A-Za-z0-9._-]` survive) so
+ *     a caller-supplied id can never escape the session directory;
+ *   - replay keeps the LONGEST VALID PREFIX: blank lines are harmless padding,
+ *     and everything from the first unparsable record (a torn tail left by a
+ *     crash mid-write) is truncated away — a half record is never replayed;
+ *   - a file whose last record has no terminating newline is repaired before
+ *     the next append, otherwise the next record would merge into it.
+ */
+import { type SessionEvent } from "@celestea/core";
+export interface TornRecord {
+    /** 1-based line number of the first unparsable record. */
+    line: number;
+    /** Byte offset the record starts at. */
+    offset: number;
+    raw: string;
+    error: string;
+}
+export interface ReplayFileResult {
+    events: SessionEvent[];
+    /** Byte length of the valid prefix (what the caller truncates to). */
+    validBytes: number;
+    /** True when an unparsable record followed the valid prefix. */
+    truncated: boolean;
+    torn: TornRecord | null;
+}
+/** Map a session id to a safe file name (`file_name_for`). */
+export declare function fileNameFor(sessionId: string): string;
+/** The JSONL path used for a session id under a directory (`file_path`). */
+export declare function filePathFor(dir: string, sessionId: string): string;
+/** Strip one trailing `\n` and an optional `\r` (`trim_line_end`). */
+export declare function trimLineEnd(line: Buffer): Buffer;
+/**
+ * True when the file is non-empty and its last byte is not a newline — only a
+ * hand-crafted/corrupt file can be in this state (`file_lacks_final_newline`).
+ */
+export declare function fileLacksFinalNewline(path: string): boolean;
+/** Replay a JSONL file line by line, keeping the longest valid prefix. */
+export declare function replayFile(path: string): ReplayFileResult;

package/dist/log/file.js

@@ -0,0 +1,85 @@
+/**
+ * cli-main.jsonl file-level replay — port of
+ * `crates/session/src/persistent.rs:282-402`.
+ *
+ * Contract:
+ *   - `file_name_for` sanitizes a session id (only `[A-Za-z0-9._-]` survive) so
+ *     a caller-supplied id can never escape the session directory;
+ *   - replay keeps the LONGEST VALID PREFIX: blank lines are harmless padding,
+ *     and everything from the first unparsable record (a torn tail left by a
+ *     crash mid-write) is truncated away — a half record is never replayed;
+ *   - a file whose last record has no terminating newline is repaired before
+ *     the next append, otherwise the next record would merge into it.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseSessionEvent } from "@celestea/core";
+/** Map a session id to a safe file name (`file_name_for`). */
+export function fileNameFor(sessionId) {
+    let name = "";
+    for (const ch of sessionId)
+        name += /^[A-Za-z0-9._-]$/.test(ch) ? ch : "_";
+    if (name === "")
+        name = "session";
+    return `${name}.jsonl`;
+}
+/** The JSONL path used for a session id under a directory (`file_path`). */
+export function filePathFor(dir, sessionId) {
+    return join(dir, fileNameFor(sessionId));
+}
+/** Strip one trailing `\n` and an optional `\r` (`trim_line_end`). */
+export function trimLineEnd(line) {
+    let end = line.length;
+    if (end > 0 && line[end - 1] === 0x0a)
+        end -= 1;
+    if (end > 0 && line[end - 1] === 0x0d)
+        end -= 1;
+    return line.subarray(0, end);
+}
+/**
+ * True when the file is non-empty and its last byte is not a newline — only a
+ * hand-crafted/corrupt file can be in this state (`file_lacks_final_newline`).
+ */
+export function fileLacksFinalNewline(path) {
+    if (!existsSync(path))
+        return false;
+    const buf = readFileSync(path);
+    if (buf.length === 0)
+        return false;
+    return buf[buf.length - 1] !== 0x0a;
+}
+/** Replay a JSONL file line by line, keeping the longest valid prefix. */
+export function replayFile(path) {
+    const events = [];
+    if (!existsSync(path))
+        return { events, validBytes: 0, truncated: false, torn: null };
+    const buf = readFileSync(path);
+    let offset = 0;
+    let validBytes = 0;
+    let lineNumber = 0;
+    while (offset < buf.length) {
+        const newline = buf.indexOf(0x0a, offset);
+        const end = newline === -1 ? buf.length : newline + 1;
+        const start = offset;
+        offset = end;
+        lineNumber += 1;
+        const record = trimLineEnd(buf.subarray(start, end));
+        if (record.length === 0) {
+            // Blank line: harmless padding, part of the valid region.
+            validBytes = offset;
+            continue;
+        }
+        const parsed = parseSessionEvent(record.toString("utf8"));
+        if (!parsed.ok) {
+            return {
+                events,
+                validBytes,
+                truncated: true,
+                torn: { line: lineNumber, offset: start, raw: record.toString("utf8"), error: parsed.errors.join("; ") },
+            };
+        }
+        events.push(parsed.event);
+        validBytes = offset;
+    }
+    return { events, validBytes, truncated: false, torn: null };
+}

package/dist/log/memory.d.ts

@@ -0,0 +1,27 @@
+/**
+ * InMemorySessionLog — port of `crates/session/src/log.rs:16-66`.
+ *
+ * An in-memory, append-only session log: insertion order is the single source
+ * of truth and the model history is always derived from it, never stored
+ * separately. The turn-id counter is owned by the LOG (not the agent loop) and
+ * never resets — not even on `clear` — so ids never repeat across loop
+ * instances (P0-A unique turn identity).
+ */
+import { type Message, type SessionEvent, type SessionLog } from "@celestea/core";
+export declare class InMemorySessionLog implements SessionLog {
+    private recorded;
+    private turnCounter;
+    /** Create an empty session log. */
+    static create(): InMemorySessionLog;
+    append(event: SessionEvent): void;
+    /** A copy of the recorded events (`events()` clones the Vec). */
+    events(): SessionEvent[];
+    deriveMessages(): Message[];
+    /** Drop every event; the id counter deliberately survives (`clear`). */
+    clear(): void;
+    nextTurnId(): string;
+    /** The next number the counter would hand out (diagnostics / recovery). */
+    peekTurnNumber(): number;
+    /** Restore the counter after a replay (`PersistentSessionLog` recovery). */
+    restoreTurnCounter(next: number): void;
+}