@celestea/session 2.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mcd0LUO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# @celestea/session
+
+The session log: in-memory and JSONL-backed `SessionLog` implementations, the
+replay/repair path, the monotonic turn-id owner, and the two message
+projections (Studio + engine). Depends only on `@celestea/core`.
+
+Ports (1:1 against the legacy engine):
+
+| TS module | Legacy source |
+|---|---|
+| `log/derive.ts` | `crates/session/src/log.rs` (`derive_messages_from`, `flush_tool_calls`, `balance_tool_calls`, `project`) |
+| `log/memory.ts` | `crates/session/src/log.rs` (`InMemorySessionLog`) |
+| `log/file.ts` | `crates/session/src/persistent.rs` (naming, replay, torn-tail truncation) |
+| `log/persistent.ts` | `crates/session/src/persistent.rs` (`PersistentSessionLog`) |
+| `turn-id.ts` | `session_log.rs:94-98` + `persistent.rs:382-402` (turn id ownership) |
+| `messages.ts` | `crates/session/src/log.rs` + Studio `src/api.rs:94-135` |
+| `replay.ts` | P0 replay analysis + SSE transcript derivation |
+
+## Public API (via `index.ts` only)
+
+- **Logs** — `InMemorySessionLog`, `PersistentSessionLog.open(dir, sessionId,
+  opts?)`, `defaultPersistentOptions()`, `PersistentOptions`.
+- **Plugins** — `inMemorySessionLogPlugin()`, `persistentSessionLogPlugin(cfg)`;
+  both provide the log under core's `SESSION_LOG_SERVICE` token. Core never
+  imports this package: register the plugin into a `Context` at compose time.
+- **Projections** — `projectMessages` (Studio: per-event, keeps thinking rows,
+  keeps `parent_id` rows) and `deriveMessages` (engine: model-visible history —
+  drops turn markers, thinking and `parent_id` sub-calls, merges consecutive
+  tool calls into one assistant message, balances unanswered calls with a
+  synthetic cancelled result).
+- **JSONL** — `parseSessionJsonl`, `serializeSessionJsonl`, plus re-exports of
+  the serde-exact row codec (`validateSessionEvent`, `parseSessionEvent`,
+  `serializeSessionEvent`, `outcomePhase`, `outcomeError`) from core.
+- **Files** — `fileNameFor`, `filePathFor`, `replayFile` (longest valid prefix +
+  torn record), `nextTurnId`, `nextTurnNumber`, `auditTurnIds`.
+- **Analysis** — `analyzeReplay`, `deriveSseTranscript` (P0 replay toolchain).
+
+## Extension points
+
+```ts
+import { Context, mountPlugins, SESSION_LOG_SERVICE, type SessionLog } from "@celestea/core";
+import { persistentSessionLogPlugin } from "@celestea/session";
+
+const ctx = mountPlugins(Context.root(), [
+  persistentSessionLogPlugin({ dir: "~/.celestea/sessions", sessionId: "session-1" }),
+]);
+const log = ctx.require<SessionLog>(SESSION_LOG_SERVICE);
+log.append({ type: "user_message", text: "hi" });
+log.nextTurnId();      // "turn-0" — owned by the log, monotonic, restored on open
+log.deriveMessages();  // engine Message[] (role / content[] / tool_call_id)
+```
+
+Swap in `inMemorySessionLogPlugin()` for tests; a later mount of the same token
+wins (patch semantics), so composition never needs editing.
+
+## Durability semantics
+
+- One record == one JSON line; `append` writes through to the OS immediately
+  (`fs.writeSync`), so `flushEachAppend:false` cannot lose a record (documented
+  deviation from the engine's `BufWriter`, in the safe direction); `sync()` is the
+  fsync/power-loss durability point and `syncEachAppend` fsyncs every record.
+- On open the file is replayed and validated: the **longest valid prefix** is
+  kept and everything from the first unparsable record (a torn tail) is
+  truncated away; blank lines are harmless padding; a missing final newline is
+  repaired before the next append.
+- The turn counter is restored from the max `turn-<n>` id on disk (+1), so ids
+  are never reused after a restart. `clear()` truncates the file and resets the
+  counter (legacy behaviour); the in-memory log's counter deliberately never
+  resets.
+- A failed disk write degrades gracefully: the event stays in the in-memory
+  view (`deriveMessages` keeps working) and `writeErrorCount()` counts it.
+
+## derive_messages contract (engine parity)
+
+`derive_messages_from` walks the log and: skips `TurnStart`/`TurnEnd`; skips
+`ThinkingDelta`; accumulates `ToolCall` rows (skipping `parent_id` sub-calls)
+and flushes them into ONE assistant message before any other event and at the
+end; projects `ToolResult` as `Error: {err}` (non-empty error) or the
+serde_json text of the value; then `balance_tool_calls` inserts
+`Error: tool call was cancelled before execution (no result recorded)` for every
+unanswered call (engine commit b046564 / W267).
+
+**Ported upstream quirks** (parity over silent divergence, reported upstream):
+
+1. `balance_tool_calls` advances its cursor with `i = j + inserted + 1`, so the
+   message right after a fully-answered call's results is never balance-checked;
+   an unbalanced trailing call in exactly that position stays unbalanced.
+   Covered by `log/derive.test.ts` and reproduced against the real engine.
+2. A whitespace-only JSONL line is an unparsable record (`record.is_empty()`),
+   not padding.
+
+## Golden fixtures & the parity test
+
+`fixtures/sessions/*/derive-messages-expected.json` is a **frozen golden**: since
+the engine exposes `derive_messages` over no HTTP surface, the expected JSON is
+stored in `fixtures/`. `src/parity.test.ts` asserts, per session and field for
+field: `deriveMessages` vs that golden, `projectMessages` vs the frozen HTTP
+golden, and a byte-identical JSONL round-trip of every event line.
+
+```sh
+pnpm vitest run packages/session/src/parity.test.ts    # golden parity suite
+```
+
+## File layout
+
+```
+src/log/derive.test.ts    184  derive_messages parity suite (legacy tests ported)
+src/replay.ts             160  replay analysis + SSE transcript (P0)
+src/log/derive.ts         147  derive_messages + balance_tool_calls
+src/log/persistent.ts     143  PersistentSessionLog (JSONL, replay, restore)
+src/log/file.ts           106  file naming + replay/truncate helpers
+src/jsonl.test.ts          99  file-level JSONL contract
+src/parity.test.ts         89  golden parity (parity.test.ts)
+src/turn-id.ts             83  turn id math + audit
+src/jsonl.ts               80  file-level parse/serialize + codec re-exports
+src/messages.ts            74  Studio projection + deriveMessages facade
+src/log/persistent.test.ts 174 torn tail / blank lines / counter restore
+src/log/memory.ts          55  InMemorySessionLog
+src/plugin.ts              40  Context registration
+src/index.ts               33  the only public entry point
+```

package/dist/checkpoint-log.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The checkpoint decorator: a `SessionLog` that records its own turn boundary.
+ *
+ * WHY a decorator and not a hook in the runtime: the `turn_start`/`turn_end`
+ * rows are appended by the AGENT LOOP (the log is resolved from the Context per
+ * turn), so the ONLY place that sees every boundary — whoever drives the turn —
+ * is the log itself. Wrapping it keeps the checkpoint exact without touching
+ * the frozen `SessionLog` seam (no new method, no new event, K5/K4).
+ *
+ * Discipline:
+ *   - forwarding is transparent (a Proxy binds every other member to the inner
+ *     log, so `path` / `close()` / `writeErrorCount()` keep working for the host
+ *     and for the registry's `turnNo` restoration);
+ *   - the checkpoint is written AFTER the row reached the log, so a crash in
+ *     between can only lose an OPEN-TURN MARKER, never invent a repair: the boot
+ *     decision table then reads "no checkpoint" and does nothing (fail-safe);
+ *   - a checkpoint failure NEVER propagates into a turn (observation only).
+ */
+import type { SessionLog } from "@celestea/core";
+import { CheckpointStore } from "./checkpoint.js";
+/** Access key of the wrapped store (symbol: invisible to JSON / spread). */
+export declare const CHECKPOINT_STORE: unique symbol;
+/** Wrap `log` so every turn boundary lands in `store` (§1.2.2 write timings). */
+export declare function checkpointedLog(log: SessionLog, store: CheckpointStore): SessionLog;
+/** The store behind a decorated log (null for a plain / missing log). */
+export declare function checkpointStoreOf(log: SessionLog | null | undefined): CheckpointStore | null;
+/** Graceful-exit mark of a decorated log (`true` = the next boot repairs nothing). */
+export declare function markCleanShutdown(log: SessionLog | null | undefined): boolean;
+/** The log's own degradation counter, when it has one (0 otherwise). */
+export declare function writeErrorCountOf(log: SessionLog | null | undefined): number;

package/dist/checkpoint-log.js

@@ -0,0 +1,78 @@
+/**
+ * The checkpoint decorator: a `SessionLog` that records its own turn boundary.
+ *
+ * WHY a decorator and not a hook in the runtime: the `turn_start`/`turn_end`
+ * rows are appended by the AGENT LOOP (the log is resolved from the Context per
+ * turn), so the ONLY place that sees every boundary — whoever drives the turn —
+ * is the log itself. Wrapping it keeps the checkpoint exact without touching
+ * the frozen `SessionLog` seam (no new method, no new event, K5/K4).
+ *
+ * Discipline:
+ *   - forwarding is transparent (a Proxy binds every other member to the inner
+ *     log, so `path` / `close()` / `writeErrorCount()` keep working for the host
+ *     and for the registry's `turnNo` restoration);
+ *   - the checkpoint is written AFTER the row reached the log, so a crash in
+ *     between can only lose an OPEN-TURN MARKER, never invent a repair: the boot
+ *     decision table then reads "no checkpoint" and does nothing (fail-safe);
+ *   - a checkpoint failure NEVER propagates into a turn (observation only).
+ */
+import { CheckpointStore } from "./checkpoint.js";
+/** Access key of the wrapped store (symbol: invisible to JSON / spread). */
+export const CHECKPOINT_STORE = Symbol.for("celestea.session.checkpointStore");
+/** Wrap `log` so every turn boundary lands in `store` (§1.2.2 write timings). */
+export function checkpointedLog(log, store) {
+    const handler = {
+        get(target, prop) {
+            if (prop === CHECKPOINT_STORE)
+                return store;
+            if (prop === "append")
+                return (event) => appendObserved(target, store, event);
+            if (prop === "clear") {
+                return () => {
+                    target.clear();
+                    store.clearOpenTurn(); // an emptied log has no open turn any more
+                };
+            }
+            const value = Reflect.get(target, prop, target);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    };
+    return new Proxy(log, handler);
+}
+/** The store behind a decorated log (null for a plain / missing log). */
+export function checkpointStoreOf(log) {
+    if (log === null || log === undefined)
+        return null;
+    const store = log[CHECKPOINT_STORE];
+    return store instanceof CheckpointStore ? store : null;
+}
+/** Graceful-exit mark of a decorated log (`true` = the next boot repairs nothing). */
+export function markCleanShutdown(log) {
+    const store = checkpointStoreOf(log);
+    if (store === null)
+        return false;
+    store.noteLogWriteErrors();
+    store.markCleanShutdown();
+    return true;
+}
+/** The log's own degradation counter, when it has one (0 otherwise). */
+export function writeErrorCountOf(log) {
+    const read = log?.writeErrorCount;
+    return typeof read === "function" ? Number(read.call(log)) : 0;
+}
+function appendObserved(log, store, event) {
+    log.append(event);
+    try {
+        if (event.type === "turn_start")
+            store.turnStarted(event.id);
+        else if (event.type === "turn_end")
+            store.turnEnded(event.outcome);
+        // E §1.3 P1 ③: a write that the disk refused leaves memory and disk forked —
+        // sample it HERE too, so even a degraded non-boundary row is sidecar-visible.
+        if (writeErrorCountOf(log) > 0)
+            store.noteLogWriteErrors();
+    }
+    catch (e) {
+        process.stderr.write(`[celestea-session] checkpoint not updated: ${String(e)}\n`);
+    }
+}

package/dist/checkpoint-recovery.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The boot decision table of §1.2.3, as one pure function over an OPEN log.
+ *
+ *   checkpoint         | log                        | action
+ *   -------------------|----------------------------|-------------------------------
+ *   missing            | dangling turn_start        | NOTHING (may be another writer)
+ *   invalid / foreign  | anything                   | NOTHING + observation
+ *   clean_shutdown     | anything                   | NOTHING (a clean exit is not a crash)
+ *   open_turn = null   | dangling (legacy/another)  | NOTHING (not ours to close)
+ *   open_turn = turn-N | no turn_start turn-N      | NOTHING (log cleared/rotated)
+ *   open_turn = turn-N | turn_start + turn_end     | clear open_turn only (idempotent)
+ *   open_turn = turn-N | turn_start, no turn_end   | APPEND turn_end:interrupted
+ *
+ * The repair is triggered by a DOUBLE SIGNATURE — the checkpoint says a turn was
+ * open AND the log actually holds that `turn_start` without its `turn_end` — so
+ * it can never append a row the engine would not have written itself (K4: the
+ * log is append-only, and every synthesized row is a legal `TurnOutcome`).
+ *
+ * Idempotence: the second boot sees the `turn_end` its predecessor appended, so
+ * it takes the "clear open_turn only" row and appends nothing (A2).
+ */
+import type { SessionEvent, SessionLog } from "@celestea/core";
+import { CheckpointStore } from "./checkpoint.js";
+export type RecoveryAction = "closed_turn" | "cleared_open_turn" | "skipped_no_checkpoint" | "skipped_invalid_checkpoint" | "skipped_clean_shutdown" | "skipped_untracked" | "skipped_no_signature";
+export interface RecoveryOutcome {
+    action: RecoveryAction;
+    /** The turn the checkpoint named (null when there was none). */
+    turn_id: string | null;
+    /** True only for [RecoveryAction.closed_turn]: exactly ONE row was appended. */
+    appended: boolean;
+    dangling_before: string[];
+    dangling_after: string[];
+    /** Fail-safe observations (ignored checkpoint, failed sidecar write). */
+    warnings: string[];
+}
+/** `turn_start` ids that have no matching `turn_end` (crash residue, G1-1). */
+export declare function danglingTurnIds(events: readonly SessionEvent[]): string[];
+/** Decide + repair ONE session. Never throws, never rewrites an existing row. */
+export declare function recoverOpenTurn(log: SessionLog, store: CheckpointStore): RecoveryOutcome;

package/dist/checkpoint-recovery.js

@@ -0,0 +1,69 @@
+/**
+ * The boot decision table of §1.2.3, as one pure function over an OPEN log.
+ *
+ *   checkpoint         | log                        | action
+ *   -------------------|----------------------------|-------------------------------
+ *   missing            | dangling turn_start        | NOTHING (may be another writer)
+ *   invalid / foreign  | anything                   | NOTHING + observation
+ *   clean_shutdown     | anything                   | NOTHING (a clean exit is not a crash)
+ *   open_turn = null   | dangling (legacy/another)  | NOTHING (not ours to close)
+ *   open_turn = turn-N | no turn_start turn-N      | NOTHING (log cleared/rotated)
+ *   open_turn = turn-N | turn_start + turn_end     | clear open_turn only (idempotent)
+ *   open_turn = turn-N | turn_start, no turn_end   | APPEND turn_end:interrupted
+ *
+ * The repair is triggered by a DOUBLE SIGNATURE — the checkpoint says a turn was
+ * open AND the log actually holds that `turn_start` without its `turn_end` — so
+ * it can never append a row the engine would not have written itself (K4: the
+ * log is append-only, and every synthesized row is a legal `TurnOutcome`).
+ *
+ * Idempotence: the second boot sees the `turn_end` its predecessor appended, so
+ * it takes the "clear open_turn only" row and appends nothing (A2).
+ */
+import { CheckpointStore } from "./checkpoint.js";
+/** `turn_start` ids that have no matching `turn_end` (crash residue, G1-1). */
+export function danglingTurnIds(events) {
+    const started = [];
+    const closed = new Set();
+    for (const ev of events) {
+        if (ev.type === "turn_start")
+            started.push(ev.id);
+        else if (ev.type === "turn_end")
+            closed.add(ev.id);
+    }
+    return started.filter((id) => !closed.has(id));
+}
+function outcomeOf(parts) {
+    return {
+        action: parts.action,
+        turn_id: parts.turnId,
+        appended: parts.appended,
+        dangling_before: parts.before,
+        dangling_after: parts.after,
+        warnings: parts.warnings,
+    };
+}
+/** Decide + repair ONE session. Never throws, never rewrites an existing row. */
+export function recoverOpenTurn(log, store) {
+    const read = store.load();
+    const before = danglingTurnIds(log.events());
+    const skip = (action, turnId = null) => outcomeOf({ action, turnId, appended: false, before, after: before, warnings: store.warnings() });
+    if (read.kind === "missing")
+        return skip("skipped_no_checkpoint");
+    if (read.kind === "invalid")
+        return skip("skipped_invalid_checkpoint");
+    if (read.value.clean_shutdown)
+        return skip("skipped_clean_shutdown");
+    const open = read.value.open_turn;
+    if (open === null)
+        return skip("skipped_untracked");
+    const events = log.events();
+    if (!events.some((ev) => ev.type === "turn_start" && ev.id === open.id))
+        return skip("skipped_no_signature", open.id);
+    if (events.some((ev) => ev.type === "turn_end" && ev.id === open.id)) {
+        store.clearOpenTurn(); // the previous boot already repaired it: nothing to append
+        return outcomeOf({ action: "cleared_open_turn", turnId: open.id, appended: false, before, after: before, warnings: store.warnings() });
+    }
+    log.append({ type: "turn_end", id: open.id, outcome: "interrupted" });
+    store.recordSynthesizedTurnEnd(open.id);
+    return outcomeOf({ action: "closed_turn", turnId: open.id, appended: true, before, after: danglingTurnIds(log.events()), warnings: store.warnings() });
+}

package/dist/checkpoint.d.ts

@@ -0,0 +1,194 @@
+/**
+ * `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 { type TurnOutcome } from "@celestea/core";
+/** File name inside a session directory (contract). */
+export declare const CHECKPOINT_FILE_NAME = "checkpoint.json";
+/** The only accepted `version`; anything else is "unknown schema" -> ignored. */
+export declare const CHECKPOINT_VERSION = 1;
+/** The turn a crashed process left open (null = no turn is running). */
+export interface CheckpointOpenTurn {
+    id: string;
+    started_at: number;
+}
+/** One log repair this engine performed (the honest audit trail, R1-1). */
+export interface CheckpointRepair {
+    at: number;
+    action: "synthesize_turn_end";
+    turn_id: string;
+}
+/**
+ * One queued message exactly as the inbox holds it (E §1.2.1: the lanes are the
+ * ONE thing the log cannot express — a message that was ACCEPTED and not yet
+ * injected). Structurally typed so `packages/session` stays free of an L1
+ * sibling import (K1): the runtime's `InjectedMessage` satisfies this shape.
+ */
+export interface CheckpointLaneMessage {
+    text: string;
+    from: string;
+    at: number;
+    lane: string;
+    kind: string;
+    id: string;
+    source: unknown;
+    duplicate?: boolean;
+}
+/**
+ * E §1.3 P1 ①: the two injection lanes plus the bounded ledger of already
+ * accepted ids. `delivered_ids` is what makes a receipt's idempotency key
+ * survive a restart (the cross-process key of capability 2).
+ */
+export interface CheckpointLanes {
+    next_turn: CheckpointLaneMessage[];
+    next_step: CheckpointLaneMessage[];
+}
+export interface Checkpoint {
+    version: number;
+    /** Self-description `<workspace>/<session>`; a mismatch voids the file. */
+    session: string;
+    pid: number;
+    /** One id per process start (a constant for the life of the process). */
+    boot_id: string;
+    updated_at: number;
+    /** True only after a graceful shutdown; a clean exit is never repaired. */
+    clean_shutdown: boolean;
+    open_turn: CheckpointOpenTurn | null;
+    /** Redundant with the log, kept for operators reading the sidecar directly. */
+    last_outcome: string | null;
+    degraded: {
+        log_write_errors: number;
+    };
+    lanes: CheckpointLanes;
+    /** Bounded (oldest-first) ledger of accepted injection ids (§1.2.1 / W515). */
+    delivered_ids: string[];
+    repaired: CheckpointRepair[];
+}
+/** Who is writing (`process.pid` + one random id per process start). */
+export interface CheckpointIdentity {
+    boot_id: string;
+    pid: number;
+}
+/** `b-<8 hex>` — short, greppable, unique per process start. */
+export declare function newBootId(): string;
+/** The identity of THIS process (stable for its whole life). */
+export declare function currentProcessIdentity(): CheckpointIdentity;
+/** Read outcome of the sidecar: three states, never an exception. */
+export type CheckpointRead = {
+    kind: "missing";
+} | {
+    kind: "invalid";
+    error: string;
+} | {
+    kind: "ok";
+    value: Checkpoint;
+};
+export declare function checkpointPathFor(dir: string): string;
+/** A fresh, empty checkpoint of the current process. */
+export declare function freshCheckpoint(session: string, identity: CheckpointIdentity, now: number): Checkpoint;
+/** Atomic write: tmp file in the same directory -> rename, mode 0600. */
+export declare function writeCheckpointFile(path: string, value: Checkpoint): void;
+/** Read + validate; missing / corrupt / foreign files are never an exception. */
+export declare function readCheckpointFile(path: string, session: string): CheckpointRead;
+/** Shape gate: version, self-description, open_turn and the repair list. */
+export declare function validateCheckpoint(raw: unknown, session: string): CheckpointRead;
+export interface CheckpointStoreOptions {
+    /** Session directory the sidecar lives in. */
+    dir: string;
+    /** Self-description written into the file (`<workspace>/<session>`). */
+    session: string;
+    identity?: CheckpointIdentity;
+    now?: () => number;
+    /** Observation channel (stderr by default); never a failure. */
+    warn?: (message: string) => void;
+    /** Sample the log's own degradation counter at every write (§1.2.2). */
+    logWriteErrors?: () => number;
+    /**
+     * E §1.3 P1 ③: the audit channel of a DEGRADED log (`log_write_errors` just
+     * became non-zero). Called AT MOST ONCE per store — the fact is sticky, so
+     * repeating it every turn would be log spam, not truth.
+     */
+    onDegraded?: (info: {
+        session: string;
+        count: number;
+    }) => void;
+}
+/**
+ * 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 declare class CheckpointStore {
+    readonly path: string;
+    readonly session: string;
+    private readonly identity;
+    private readonly now;
+    private readonly warn;
+    private readonly sample;
+    private loaded;
+    private state;
+    private readonly observations;
+    private degradedReported;
+    private readonly onDegraded;
+    constructor(opts: CheckpointStoreOptions);
+    /** The sidecar as found on disk (cached; never throws). */
+    load(): CheckpointRead;
+    /** The current state (a fresh, empty checkpoint when missing / ignored). */
+    get current(): Checkpoint;
+    /** Observations gathered so far (ignored files, failed writes). */
+    warnings(): string[];
+    /** A turn is open from now on (written RIGHT AFTER `turn_start`). */
+    turnStarted(id: string): void;
+    /** The turn closed normally: no open turn, outcome recorded (§1.2.2). */
+    turnEnded(outcome: TurnOutcome | undefined): void;
+    /** Clear a stale open turn WITHOUT touching the log (already-closed case). */
+    clearOpenTurn(): void;
+    /**
+     * 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: string): void;
+    /** Graceful exit: `true` forbids any repair on the next boot. */
+    markCleanShutdown(): void;
+    /** Sample the log's degradation counter (sticky: a fork must stay visible). */
+    noteLogWriteErrors(): void;
+    /**
+     * 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: readonly CheckpointLaneMessage[], nextStep: readonly CheckpointLaneMessage[], deliveredIds: readonly string[]): void;
+    /** The persisted lanes + delivered ledger of the file on disk (null = unusable). */
+    persistedQueues(): {
+        lanes: CheckpointLanes;
+        delivered_ids: string[];
+    } | null;
+    private persist;
+    /** §5.2③: a silent disk/memory fork is exactly what must never stay silent. */
+    private reportDegraded;
+    private observe;
+}