@namzu/sdk 42.0.2 → 44.0.0

package/dist/runtime/query/checkpoint.js

@@ -1,7 +1,9 @@
+import { readFoldedHistory } from '../../manager/session/turn-recorder.js';
 import { NamzuError } from '../../types/errors/index.js';
-import { ZERO_COST } from '../../utils/cost.js';
-import { buildToolResultHashes } from '../../utils/hash.js';
-import { asCheckpointId, asEmergencySaveId, asGoalId, generateCheckpointId, } from '../../utils/id.js';
+import { createRuntimeContextMessage, } from '../../types/message/index.js';
+import { CHECKPOINT_DOCUMENT_VERSION } from '../../types/session/checkpoint.js';
+import { asGoalId, generateCheckpointId } from '../../utils/id.js';
+import { formatSteeringNote, readSteeringNote } from './steering.js';
 /** Keep intent text/provenance without copying attachment payloads into a second slot. */
 function snapshotUserIntent(value) {
     const invalid = () => {
@@ -42,104 +44,88 @@ function snapshotUserIntent(value) {
     };
     return result;
 }
-/**
- * Projection from a full checkpoint payload to the public listing entry.
- * Exported for the replay `listCheckpoints` entry point, which projects
- * store results without constructing a `CheckpointManager`.
- */
+/** Projection from a checkpoint document to the public listing entry. */
 export function toCheckpointListEntry(cp) {
     return {
-        id: cp.id,
-        runId: cp.runId,
+        id: cp.checkpointId,
+        sessionId: cp.sessionId,
+        turnId: cp.turnId,
         iteration: cp.iteration,
-        createdAt: cp.createdAt,
-        messageCount: cp.messages.length,
+        createdAt: Date.parse(cp.createdAt),
+        throughSeq: cp.throughSeq,
     };
 }
 /**
- * Project an {@link EmergencySaveData} dump to an {@link IterationCheckpoint}
- * shape so `replay({ fromCheckpoint: 'emergency' })` can consume it through
- * the same restore path as any other checkpoint.
- *
- * The projection is lossy: `costInfo`, `guardState.elapsedMs` and
- * `toolResultHashes` are not captured at emergency-save time. The synthetic
- * checkpoint id is derived deterministically from the emergency save id so
- * re-projecting the same dump yields the same {@link CheckpointId}.
- *
- * ## The cost projection says "unknown", not "zero"
- *
- * `costInfo` used to default to `{ ...ZERO_COST }` beside a `tokenUsage` the
- * dump preserves faithfully — a run that had spent real money coming back as
- * one that had spent nothing. That is the same lie the price catalogue was
- * added to end, arriving through the restore path instead of the accumulation
- * one, and it took `runConfig.costLimitUsd` back to being enforced against a
- * zero with it.
- *
- * It also broke the accumulator downstream. `accumulateCost` decides whether
- * one rate card describes the whole total by asking whether the total is
- * FRESH — zero cost, zero unpriced tokens, no rates — and `ZERO_COST` is
- * exactly that shape. So the first turn after such a resume adopted its own
- * rate card as covering the pre-crash spend too, and reported a number that
- * was confidently wrong while looking like a measured one.
- *
- * Saying instead that the pre-crash tokens are UNPRICED is the true statement,
- * in the vocabulary {@link CostInfo} already has: nobody knows what they cost,
- * because nothing recorded it. It needs no marker of its own to stay correct,
- * and it is not fresh-shaped, so the accumulator does the right thing without
- * being told about this path at all.
- *
- * See ses_005-deterministic-replay design §2 + §5.2.
+ * Every park a session log records, newest last: `decision_requested`, and
+ * whether a `decision_resolved` or `decision_expired` has answered it.
  */
-export function projectEmergencyToCheckpoint(dump) {
-    const emergencyId = asEmergencySaveId(dump.id);
-    // The checkpoint is another view of the same snapshot and retains its key.
-    const checkpointId = asCheckpointId(emergencyId);
-    return {
-        id: checkpointId,
-        runId: dump.runId,
-        // The dump records the run's start, so this projection carries the
-        // same stamp an ordinary checkpoint of that run would — a run whose
-        // only surviving record is an emergency dump still has a real
-        // attribution instant, and dropping it here would put that run in the
-        // "never recorded" bucket for no reason.
-        runCreatedAt: dump.startedAt,
-        iteration: dump.currentIteration,
-        messages: dump.messages,
-        tokenUsage: dump.tokenUsage,
-        budgetBinding: dump.budgetBinding,
-        budgetAccountId: dump.budgetAccountId,
-        costInfo: { ...ZERO_COST, unpricedTokens: dump.tokenUsage.totalTokens },
-        guardState: {
-            iterationCount: dump.currentIteration,
-            elapsedMs: Math.max(0, dump.savedAt - dump.startedAt),
+export async function readParks(log, options = {}) {
+    const parks = new Map();
+    for await (const { record } of log.read({ mode: 'tolerant' })) {
+        const r = record;
+        if (r.type === 'decision_requested') {
+            if (options.turnId !== undefined && r.turnId !== options.turnId)
+                continue;
+            parks.set(r.decisionId, {
+                decisionId: r.decisionId,
+                turnId: r.turnId,
+                checkpointId: r.checkpointId,
+                request: r.request,
+                parkedAt: Date.parse(r.ts),
+                ...(r.deadlineAt !== undefined ? { deadlineAt: Date.parse(r.deadlineAt) } : {}),
+            });
+        }
+        else if (r.type === 'decision_resolved') {
+            const park = parks.get(r.decisionId);
+            if (park) {
+                park.resolvedAt = Date.parse(r.ts);
+                park.decision = r.decision;
+            }
+        }
+        else if (r.type === 'decision_expired') {
+            const park = parks.get(r.decisionId);
+            if (park) {
+                park.resolvedAt = Date.parse(r.ts);
+                // The park ended by running out of time, not by a decision. An
+                // `abort` here would read as somebody having refused it.
+                park.decision = {
+                    action: 'pause',
+                    reason: 'The approval request expired without an answer.',
+                };
+            }
+        }
+    }
+    return [...parks.values()].map((park) => ({
+        decisionId: park.decisionId,
+        turnId: park.turnId,
+        checkpointId: park.checkpointId,
+        pending: {
+            request: park.request,
+            parkedAt: park.parkedAt,
+            ...(park.deadlineAt !== undefined ? { deadlineAt: park.deadlineAt } : {}),
+            ...(park.resolvedAt !== undefined ? { resolvedAt: park.resolvedAt } : {}),
+            ...(park.decision !== undefined ? { decision: park.decision } : {}),
         },
-        createdAt: dump.savedAt,
-    };
+    }));
 }
 /**
- * The newest checkpoint of a run that is still awaiting a human decision,
- * or `null` when the run is not parked.
+ * The newest park of a session (or of one of its turns) that is still
+ * awaiting a human decision, or `null` when nothing is parked.
  *
- * Standalone (not a `CheckpointManager` method) so a host can ask the
- * question without constructing a run: an approval-queue worker in a
- * different process has a store and a scope, and nothing else.
+ * Standalone so a host can ask the question without constructing a turn: an
+ * approval-queue worker in a different process has the session log and
+ * nothing else. An expired park is not outstanding.
  */
-export async function findPendingCheckpoint(store, scope, options) {
-    const all = await store.listCheckpoints(scope);
-    const now = options?.now ?? Date.now();
-    // `listCheckpoints` is contractually ascending by `createdAt`; the
-    // newest outstanding park is the one a human should be answering.
-    for (let i = all.length - 1; i >= 0; i--) {
-        const cp = all[i];
-        if (!cp.pending || cp.pending.resolvedAt !== undefined)
+export async function findPendingCheckpoint(log, options = {}) {
+    const parks = await readParks(log, options.turnId ? { turnId: options.turnId } : {});
+    const now = options.now ?? Date.now();
+    for (let i = parks.length - 1; i >= 0; i--) {
+        const park = parks[i];
+        if (park.pending.resolvedAt !== undefined)
             continue;
-        // An expired park is not outstanding. Serving it re-presents an
-        // approval whose window has closed, and every queue reader would
-        // keep re-presenting it forever — a redeployed worker leaves a park
-        // nobody will ever answer and nothing in-process can time out.
-        if (isExpiredPark(cp.pending, now))
+        if (isExpiredPark(park.pending, now))
             continue;
-        return cp;
+        return park;
     }
     return null;
 }
@@ -148,95 +134,59 @@ export function isExpiredPark(pending, now = Date.now()) {
     return pending.deadlineAt !== undefined && now >= pending.deadlineAt;
 }
 /**
- * Every outstanding park in a run, expired ones included, so a host can
- * sweep them.
- *
- * The out-of-process timer stays a host concern — consistent with the same
- * decision made for retention — but a host cannot sweep what it cannot
- * enumerate, and this is the read that makes a sweep a few lines rather
- * than a re-implementation of the store contract.
+ * Every outstanding park of a session whose deadline has passed, so a host
+ * can sweep them (`CheckpointManager.expire`, or `decision_expired` appended
+ * under the session lease).
  */
-export async function listExpiredParks(store, scope, options) {
-    const all = await store.listCheckpoints(scope);
-    const now = options?.now ?? Date.now();
-    return all.filter((cp) => cp.pending && cp.pending.resolvedAt === undefined && isExpiredPark(cp.pending, now));
+export async function listExpiredParks(log, options = {}) {
+    const parks = await readParks(log, options.turnId ? { turnId: options.turnId } : {});
+    const now = options.now ?? Date.now();
+    return parks.filter((park) => park.pending.resolvedAt === undefined && isExpiredPark(park.pending, now));
+}
+/** Who answered a decision the turn itself carried out. */
+function resolver(recorder) {
+    return {
+        kind: 'system',
+        role: 'sys_approval_policy',
+        tenantId: recorder.tenantId,
+    };
 }
+/**
+ * A turn's checkpoints: documents in the session's checkpoint store,
+ * committed by a `checkpoint_written` record, and the parks (`decision_*`
+ * records) that reference them.
+ *
+ * A checkpoint holds no messages. Its context is the fold of the session log
+ * through `throughSeq`; `restore` reads it back from the log and refuses a
+ * checkpoint whose document or covered prefix no longer matches its record.
+ */
 export class CheckpointManager {
+    recorder;
     store;
     scope;
-    /**
-     * Compaction's state source, when the run has one.
-     *
-     * Every checkpoint snapshots it, so a resumed run can carry forward the
-     * state its earlier summary was built from. Without that the next
-     * compaction supersedes that summary with one covering only post-resume
-     * activity, and the record of everything before the resume is gone.
-     */
     workingStateSource;
     latestUserMessageSource;
     restoredUserMessage;
+    restoredUserMessageId;
     answerReviewAttemptsSource;
     restoredAnswerAttempts = 0;
     structuredReviewAttemptsSource;
     restoredReviewAttempts = 0;
     nativeStructuredAttemptsSource;
     restoredNativeAttempts = 0;
-    /**
-     * The most recent checkpoint this manager wrote, if any.
-     *
-     * A run that fails on a transient error needs to name the state a host
-     * should resume from. Re-listing the store to find it would be a disk
-     * read on the failure path, at the moment the run is least able to
-     * afford one; the id is already in hand.
-     */
     lastCreatedId;
-    /** See {@link setTraceSource}. */
     traceSource;
-    /** See {@link setParkTtl}. */
     parkTtlMs;
     /**
-     * The claim this run holds, presented on every checkpoint write.
-     *
-     * Unset means unfenced, which is correct for a single-writer deployment
-     * and is what every run did before claims existed. Set it and a write from
-     * a superseded holding is refused by the store.
-     *
-     * This existed nowhere for one release, and the omission was invisible in
-     * the worst way: the claim, the fence and the refusal were all built and
-     * tested, and no code path between a run and its store carried the number,
-     * so every checkpoint a RUN wrote went out unfenced. A capability that is
-     * complete except for the wire between its halves reads exactly like a
-     * working one.
-     */
-    claimFence;
-    /**
-     * The run's attribution instant, stamped onto every checkpoint this
-     * manager writes.
-     *
-     * Settled exactly once, by whichever of two things happens first, and
-     * never reassigned — every write to it below is `??=`, and there are only
-     * two:
-     *
-     *  - `restore` ADOPTS it from the checkpoint a resume came back through.
-     *    A resumed run is the same run, and its creation is already on the
-     *    record; a fresh process minting a new one would move the key that
-     *    exists specifically because it does not move.
-     *  - `create` MINTS it from the run's own start instant when nothing was
-     *    adopted, which is the fresh-run case.
-     *
-     * Restore runs during run setup, before the first iteration and therefore
-     * before the first `create`, so the adopt always wins on the resume path
-     * without either site needing to know which path it is on.
-     */
-    runCreatedAt;
-    /**
-     * @param store scope-keyed checkpoint persistence. The default query
-     *   pipeline passes the run's disk-backed store
-     *   ({@link import('../../store/run/checkpoint-disk.js').DiskCheckpointStore});
-     *   hosts inject their own via `QueryParams.checkpointStore`.
-     * @param scope the run every operation of this manager is keyed to.
+     * The turn's attribution instant, identical on every checkpoint of the
+     * turn: adopted from the checkpoint a resume came back through, or minted
+     * from the turn's own start.
      */
-    constructor(store, scope) {
+    turnCreatedAt;
+    /** The turn where its iteration loop began; see {@link markLoopStart}. */
+    loopStart;
+    constructor(recorder, store, scope) {
+        this.recorder = recorder;
         this.store = store;
         this.scope = scope;
     }
@@ -269,278 +219,357 @@ export class CheckpointManager {
     get restoredStructuredReviewAttempts() {
         return this.restoredReviewAttempts;
     }
-    /**
-     * The run's root span, so every checkpoint records the trace it was
-     * taken inside and a resume can join it rather than starting a second,
-     * unlinked one.
-     */
+    /** The turn's root span, so every checkpoint records the trace it was taken inside. */
     setTraceSource(source) {
         this.traceSource = source;
     }
-    async create(runMgr, iteration, extra) {
-        // The run's own start, not `Date.now()`. This is meant to say when the
-        // run was attributed; taking the clock at the first checkpoint would
-        // say when it first became durable, which is a different and later
-        // fact, and naming it after the earlier one would make it wrong in
-        // exactly the way that is hard to notice.
-        this.runCreatedAt ??= runMgr.getSession().startedAt ?? Date.now();
+    /** Default time-to-live applied to every park this manager records. */
+    setParkTtl(ttlMs) {
+        this.parkTtlMs = ttlMs;
+    }
+    /**
+     * Write a checkpoint of the turn as it stands: every queued record lands
+     * first, the document names the log's head as `throughSeq`, and a
+     * `checkpoint_written` record commits it.
+     */
+    async create(recorder, iteration) {
+        await recorder.budget?.flush();
+        const state = await this.captureState(recorder);
+        if (!state)
+            throw new Error('A checkpoint needs a session log with records in it.');
+        return this.write(recorder, iteration, state);
+    }
+    /**
+     * Remember the turn as it stands where its iteration loop begins, before
+     * the loop's first provider request. Nothing is written: the state is
+     * only committed, by {@link createAtLoopStart}, when the turn has to
+     * pause before it wrote a checkpoint of its own.
+     */
+    async markLoopStart(recorder) {
+        this.loopStart = await this.captureState(recorder);
+    }
+    /**
+     * A checkpoint of the turn as {@link markLoopStart} found it, so a turn
+     * that fails recoverably before any checkpoint of its own has something
+     * to pause on and resume from. It covers the log only through the loop's
+     * start and counts none of the guards used since, so resuming from it
+     * discards every iteration the turn ran before the fault, completed ones
+     * included (a `max_tokens` continuation request opens a new iteration).
+     * Its iteration is the one the loop began at: 0 for a fresh
+     * turn, the restored count for a resumed one. `undefined` when no loop
+     * start was marked.
+     */
+    async createAtLoopStart(recorder) {
+        const state = this.loopStart;
+        if (!state)
+            return undefined;
+        // The ledger is the account, not the turn's view of it: whatever the
+        // failed request spent stays spent.
+        await recorder.budget?.flush();
+        return this.write(recorder, state.guards.iteration, state);
+    }
+    /** The part of a checkpoint document that describes the turn at one instant. */
+    async captureState(recorder) {
+        const startedAt = recorder.getTurn().startedAt;
+        this.turnCreatedAt ??= new Date(startedAt).toISOString();
         const latestUserMessage = this.latestUserMessageSource?.() ?? this.restoredUserMessage;
-        const checkpoint = {
-            id: generateCheckpointId(),
-            runId: runMgr.id,
-            runCreatedAt: this.runCreatedAt,
-            iteration,
-            messages: [...runMgr.messages],
-            answerReviewAttempts: this.answerReviewAttemptsSource?.() ?? this.restoredAnswerAttempts,
-            nativeStructuredAttempts: this.nativeStructuredAttemptsSource?.() ?? this.restoredNativeAttempts,
-            structuredReviewAttempts: this.structuredReviewAttemptsSource?.() ?? this.restoredReviewAttempts,
-            ...(latestUserMessage ? { latestUserMessage: snapshotUserIntent(latestUserMessage) } : {}),
-            tokenUsage: { ...runMgr.tokenUsage },
-            budgetBinding: runMgr.budget?.binding,
-            budgetAccountId: runMgr.budget?.accountId,
-            costInfo: { ...runMgr.costInfo },
-            guardState: {
-                iterationCount: runMgr.currentIteration,
-                elapsedMs: Date.now() - (runMgr.getSession().startedAt ?? Date.now()),
+        const head = await recorder.head();
+        if (!head)
+            return undefined;
+        const latestUserMessageId = latestUserMessage
+            ? this.messageIdOf(recorder, latestUserMessage)
+            : undefined;
+        return {
+            throughSeq: head.pointer.seq,
+            throughSha256: head.pointer.sha256,
+            tokenUsage: { ...recorder.tokenUsage },
+            costInfo: { ...recorder.costInfo },
+            guards: {
+                iteration: recorder.currentIteration,
+                elapsedMs: Math.max(0, Date.now() - startedAt),
+            },
+            review: {
+                structuredAttempts: this.structuredReviewAttemptsSource?.() ?? this.restoredReviewAttempts,
+                answerAttempts: this.answerReviewAttemptsSource?.() ?? this.restoredAnswerAttempts,
+                nativeStructuredAttempts: this.nativeStructuredAttemptsSource?.() ?? this.restoredNativeAttempts,
             },
-            createdAt: Date.now(),
-            toolResultHashes: extra?.toolResults ? buildToolResultHashes(extra.toolResults) : undefined,
-            workingState: extra?.workingState ?? this.workingStateSource?.(),
-            traceContext: this.traceSource?.(),
+            ...(latestUserMessageId ? { latestUserMessageId } : {}),
+            ...withDefined('workingState', this.workingStateSource?.()),
+        };
+    }
+    async write(recorder, iteration, state) {
+        const binding = recorder.budget?.binding;
+        const accountId = recorder.budget?.accountId;
+        const document = {
+            v: CHECKPOINT_DOCUMENT_VERSION,
+            kind: 'checkpoint',
+            checkpointId: generateCheckpointId(),
+            sessionId: this.scope.sessionId,
+            turnId: this.scope.turnId,
+            iteration,
+            throughSeq: state.throughSeq,
+            throughSha256: state.throughSha256,
+            tokenUsage: state.tokenUsage,
+            costInfo: state.costInfo,
+            ...(accountId !== undefined
+                ? { budget: { ...(binding ? { binding } : {}), accountId } }
+                : {}),
+            guards: state.guards,
+            review: state.review,
+            ...(state.latestUserMessageId ? { latestUserMessageId: state.latestUserMessageId } : {}),
+            ...withDefined('workingState', state.workingState),
+            ...withDefined('trace', this.traceSource?.()),
+            turnCreatedAt: this.turnCreatedAt ?? new Date(recorder.getTurn().startedAt).toISOString(),
+            createdAt: new Date().toISOString(),
         };
-        await runMgr.budget?.flush();
-        await this.store.writeCheckpoint(this.scope, checkpoint, this.claimFence);
-        this.lastCreatedId = checkpoint.id;
-        return checkpoint;
+        const receipt = await this.store.write(this.scope, document);
+        await recorder.appendRecord({
+            type: 'checkpoint_written',
+            turnId: this.scope.turnId,
+            ...receipt,
+        });
+        this.lastCreatedId = document.checkpointId;
+        return { id: document.checkpointId, document };
+    }
+    /**
+     * The id of the record that carries a message's text: its own record,
+     * or — for operator guidance delivered attached to a tool result — the
+     * record of the tool result that carries it.
+     */
+    messageIdOf(recorder, message) {
+        if (message === this.restoredUserMessage)
+            return this.restoredUserMessageId;
+        return recorder.recordedIdOf(message) ?? this.steeringCarrierOf(recorder, message);
+    }
+    /** Found once and kept: a compaction may later drop the carrier from the context. */
+    steeringCarriers = new WeakMap();
+    steeringCarrierOf(recorder, message) {
+        const known = this.steeringCarriers.get(message);
+        if (known)
+            return known;
+        const source = message.source;
+        if (message.role !== 'user' ||
+            typeof message.content !== 'string' ||
+            source?.type !== 'runtime-context' ||
+            source.kind !== 'steering') {
+            return undefined;
+        }
+        const note = formatSteeringNote(message.content);
+        const messages = recorder.messages;
+        for (let i = messages.length - 1; i >= 0; i--) {
+            const candidate = messages[i];
+            if (candidate.role === 'tool' &&
+                typeof candidate.content === 'string' &&
+                candidate.content.endsWith(note)) {
+                const id = recorder.recordedIdOf(candidate);
+                if (id)
+                    this.steeringCarriers.set(message, id);
+                return id;
+            }
+        }
+        return undefined;
     }
-    /** See {@link lastCreatedId}. */
+    /** The most recent checkpoint this manager wrote, if any. */
     get lastCheckpointId() {
         return this.lastCreatedId;
     }
     /**
-     * The trace a checkpoint was taken inside, for parenting a resumed run.
-     *
-     * Read separately and BEFORE the run's root span, because a span's
-     * parent can only be set at creation and the root is minted before the
-     * restore branch runs.
-     *
-     * Never throws. Telemetry continuity is worth a disk read; it is not
-     * worth failing a resume over, and the restore path immediately after
-     * will report a genuinely unreadable checkpoint far better than a
-     * tracing helper could.
+     * The trace a checkpoint was taken inside, for parenting a resumed turn.
+     * Never throws: telemetry continuity is not worth failing a resume over.
      */
     async readTraceContext(checkpointId) {
         try {
-            const checkpoint = await this.store.readCheckpoint(this.scope, checkpointId);
-            return checkpoint?.traceContext;
+            const checkpoint = await this.store.read(this.scope, checkpointId);
+            return checkpoint?.trace;
         }
         catch {
             return undefined;
         }
     }
     /**
-     * Record that the run parked at `checkpoint` awaiting a human, and
-     * return the updated checkpoint.
-     *
-     * A park used to exist only as a suspended `await`: the checkpoint
-     * written just before it was indistinguishable from any mid-run
-     * checkpoint, so a host could not tell from durable state that a
-     * decision was outstanding — and a process boundary lost the request
-     * entirely. Writing the request down is what lets an approval queue be
-     * rebuilt, and what lets a resumed run apply the answer to the exact
-     * tool calls the human saw.
-     *
-     * Called after `create` rather than as an argument to it because the
-     * request carries the checkpoint's own id.
+     * Record that the turn parked at `checkpoint` awaiting a human: a
+     * `decision_requested` record naming the checkpoint, with an absolute
+     * deadline when the turn has a park time-to-live.
      */
     async park(checkpoint, request, options) {
         const parkedAt = Date.now();
         const ttl = options?.ttlMs ?? this.parkTtlMs;
-        const parked = {
-            ...checkpoint,
-            pending: {
-                request,
-                parkedAt,
-                // Absolute, so it survives the process that set it. A
-                // duration plus an in-process timer cannot: the worker gets
-                // redeployed and the park becomes immortal.
-                ...(ttl !== undefined && ttl > 0 ? { deadlineAt: parkedAt + ttl } : {}),
-            },
-        };
-        await this.store.writeCheckpoint(this.scope, parked, this.claimFence);
-        return parked;
-    }
-    /**
-     * Present this claim on every subsequent write. See {@link claimFence}.
-     *
-     * A setter rather than a constructor argument because a run is claimed at
-     * a different moment than it is constructed — a worker draining a queue
-     * takes the run, then builds the pipeline around it — and because a
-     * renewal mints a NEW fence mid-run that has to replace the old one.
-     */
-    setClaimFence(fence) {
-        this.claimFence = fence;
-    }
-    /** The claim currently presented on writes, if any. */
-    get presentedFence() {
-        return this.claimFence;
-    }
-    /** Default time-to-live applied to every park this manager records. */
-    setParkTtl(ttlMs) {
-        this.parkTtlMs = ttlMs;
+        const deadlineAt = ttl !== undefined && ttl > 0 ? parkedAt + ttl : undefined;
+        await this.recorder.appendRecord({
+            type: 'decision_requested',
+            turnId: this.scope.turnId,
+            decisionId: checkpoint.id,
+            checkpointId: checkpoint.id,
+            request: request,
+            ...(deadlineAt !== undefined ? { deadlineAt: new Date(deadlineAt).toISOString() } : {}),
+        });
+        return { request, parkedAt, ...(deadlineAt !== undefined ? { deadlineAt } : {}) };
     }
     /**
-     * Mark an expired park as no longer outstanding.
-     *
-     * Recorded rather than deleted: the checkpoint showing what was asked
-     * and that nobody answered in time is the evidence an approval gate is
-     * worth having, and the same reasoning already keeps a resolved
-     * decision on the record.
+     * Mark an expired park as no longer outstanding: `decision_expired`. The
+     * request stays in the log as evidence of what was asked.
      */
     async expire(checkpointId) {
-        const checkpoint = await this.store.readCheckpoint(this.scope, checkpointId);
-        if (!checkpoint?.pending || checkpoint.pending.resolvedAt !== undefined)
+        const park = await this.openPark(checkpointId);
+        if (!park)
             return null;
-        const expired = {
-            ...checkpoint,
-            pending: {
-                ...checkpoint.pending,
-                resolvedAt: Date.now(),
-                // The park ended by running out of time, not by a decision.
-                // An `abort` here would read as somebody having refused it.
-                decision: { action: 'pause', reason: 'The approval request expired without an answer.' },
-            },
-        };
-        await this.store.writeCheckpoint(this.scope, expired, this.claimFence);
-        return expired;
+        await this.recorder.appendRecord({
+            type: 'decision_expired',
+            turnId: this.scope.turnId,
+            decisionId: park.decisionId,
+        });
+        return park;
     }
     /**
-     * Record the answer, so an outstanding park stops looking outstanding.
-     *
-     * The decision is kept rather than erased: a checkpoint that shows both
-     * what was asked and what was answered is the evidence trail an
-     * approval gate is worth having. A no-op when the checkpoint is gone
-     * (pruned) or was never parked.
+     * Record the answer, so an outstanding park stops looking outstanding:
+     * `decision_resolved`. A no-op when the checkpoint was never parked or the
+     * park is already answered.
      */
     async unpark(checkpointId, decision) {
-        const checkpoint = await this.store.readCheckpoint(this.scope, checkpointId);
-        if (!checkpoint?.pending)
+        const park = await this.openPark(checkpointId);
+        if (!park)
             return null;
-        const resolved = {
-            ...checkpoint,
-            pending: { ...checkpoint.pending, resolvedAt: Date.now(), decision },
-        };
-        await this.store.writeCheckpoint(this.scope, resolved, this.claimFence);
-        return resolved;
+        await this.recorder.appendRecord({
+            type: 'decision_resolved',
+            turnId: this.scope.turnId,
+            decisionId: park.decisionId,
+            decision,
+            resolvedBy: resolver(this.recorder),
+        });
+        return park;
     }
-    /**
-     * The run's outstanding park, if it has one — the newest checkpoint
-     * whose `pending` has no `resolvedAt`.
-     *
-     * This is the read a host's approval queue is built from, and it works
-     * across a process boundary because it consults the store rather than
-     * in-memory state.
-     */
+    async openPark(checkpointId) {
+        await this.recorder.flush();
+        const parks = await readParks(this.recorder.log, { turnId: this.scope.turnId });
+        return (parks.find((park) => park.checkpointId === checkpointId && park.pending.resolvedAt === undefined) ?? null);
+    }
+    /** The turn's outstanding park, if it has one. */
     async findPending() {
-        return findPendingCheckpoint(this.store, this.scope);
+        await this.recorder.flush();
+        return findPendingCheckpoint(this.recorder.log, { turnId: this.scope.turnId });
     }
+    /**
+     * Read a checkpoint back for a resume. Refused when it is missing, when
+     * its document no longer matches its record, or when the log prefix it
+     * covers changed.
+     */
     async restore(checkpointId) {
-        const checkpoint = await this.store.readCheckpoint(this.scope, checkpointId);
-        if (!checkpoint) {
+        const document = await this.store.restore(this.scope, checkpointId);
+        if (!document) {
             throw new NamzuError({
                 code: 'not_found',
                 message: `Checkpoint not found: ${checkpointId}`,
-                details: { checkpointId, runId: this.scope.runId },
+                details: { checkpointId, sessionId: this.scope.sessionId, turnId: this.scope.turnId },
             });
         }
-        // Adopt the run's recorded attribution. A resumed run is the SAME run
-        // under the same id, and its creation is already on the record; a
-        // fresh process minting a new one would step the stamp forward on
-        // every resume, which is the motion it exists to avoid.
-        //
-        // This needs no "is it really my run" guard, and one was written and
-        // removed: `readCheckpoint` is keyed by THIS manager's scope, so the
-        // only checkpoints reachable here are the ones belonging to
-        // `scope.runId`. A replay fork never arrives here at all — it reads
-        // its origin through the SOURCE scope in `prepareReplayState` and
-        // starts a fresh run, so it mints its own stamp rather than claiming
-        // its origin's age. A guard that no input can trip would have read as
-        // protection and been none.
-        this.runCreatedAt ??= checkpoint.runCreatedAt;
-        const answerAttempts = checkpoint.answerReviewAttempts ?? 0;
-        if (!Number.isSafeInteger(answerAttempts) || answerAttempts < 0)
-            throw new Error('Checkpoint answerReviewAttempts must be a nonnegative safe integer');
-        this.restoredAnswerAttempts = answerAttempts;
-        const nativeAttempts = checkpoint.nativeStructuredAttempts ?? 0;
-        if (!Number.isSafeInteger(nativeAttempts) || nativeAttempts < 0)
-            throw new Error('Invalid nativeStructuredAttempts in checkpoint');
-        this.restoredNativeAttempts = nativeAttempts;
-        const reviewAttempts = checkpoint.structuredReviewAttempts ?? 0;
-        if (!Number.isSafeInteger(reviewAttempts) || reviewAttempts < 0)
-            throw new Error('Checkpoint structuredReviewAttempts must be a nonnegative safe integer');
-        this.restoredReviewAttempts = reviewAttempts;
-        this.restoredUserMessage =
-            checkpoint.latestUserMessage === undefined
-                ? undefined
-                : snapshotUserIntent(checkpoint.latestUserMessage);
-        return checkpoint;
+        const restored = await restoreCheckpointContext(this.recorder.log, document);
+        this.turnCreatedAt ??= document.turnCreatedAt;
+        this.restoredAnswerAttempts = document.review.answerAttempts;
+        this.restoredNativeAttempts = document.review.nativeStructuredAttempts;
+        this.restoredReviewAttempts = document.review.structuredAttempts;
+        this.restoredUserMessage = restored.latestUserMessage;
+        this.restoredUserMessageId = restored.latestUserMessage
+            ? document.latestUserMessageId
+            : undefined;
+        return restored;
     }
+    /** The turn's checkpoint documents, oldest first. */
     async list() {
-        return this.store.listCheckpoints(this.scope);
+        return this.store.list(this.scope);
     }
-    /**
-     * Listing projection used by the public `listCheckpoints` API. Returns
-     * only the fields a consumer needs to pick a fork point for
-     * {@link import('./replay/prepare.js').prepareReplayState} — not the
-     * full checkpoint payload. See ses_005-deterministic-replay design §3.1.
-     */
+    /** Listing projection used by the public `listCheckpoints` API. */
     async listEntries() {
-        const checkpoints = await this.store.listCheckpoints(this.scope);
-        return checkpoints.map(toCheckpointListEntry);
+        return (await this.list()).map(toCheckpointListEntry);
     }
     /**
-     * Collect old checkpoints until `keepLast` newer ones remain.
-     *
-     * Growth control, and growth control stops at a park. A checkpoint with
-     * an unresolved `pending` is the durable fact that a human was asked
-     * something: it is what `findPendingCheckpoint` serves to an approval
-     * queue and what `listExpiredParks` enumerates for a sweep. Collecting
-     * one deletes the only record of a question somebody may be in the middle
-     * of answering, and their answer then lands nowhere — the store refuses
-     * the unpark and the run it belonged to resumes without it.
-     *
-     * So the candidates are still the oldest `all.length - keepLast`, which
-     * is what keeps the newest `keepLast` — the run's resume point — out of
-     * reach, and a park among them is skipped rather than counted. Pruning
-     * therefore holds a few more rows while a park is outstanding. That is
-     * the right side to err on: parks resolve, and the next prune collects
-     * them. Expired ones are skipped too — the host's sweep is
-     * {@link expire}, which resolves the park by running out of time rather
-     * than by deleting the evidence, and `prune` racing it would take the
-     * question away before it was read.
+     * Collect old checkpoints until `keepLast` newer ones remain, never one an
+     * open decision references; a `checkpoint_pruned` record names what went.
      */
     async prune(keepLast) {
-        const all = await this.list();
-        if (all.length <= keepLast)
-            return;
-        const toDelete = all.sort((a, b) => a.createdAt - b.createdAt).slice(0, all.length - keepLast);
-        for (const cp of toDelete) {
-            if (cp.pending && cp.pending.resolvedAt === undefined)
-                continue;
-            await this.store.deleteCheckpoint(this.scope, cp.id);
+        await this.recorder.flush();
+        const pruned = await this.store.prune(this.scope, keepLast);
+        if (pruned.length > 0) {
+            await this.recorder.appendRecord({
+                type: 'checkpoint_pruned',
+                turnId: this.scope.turnId,
+                checkpointIds: pruned,
+            });
         }
     }
-    static buildSummary(runMgr, iteration) {
-        const lastAssistant = [...runMgr.messages]
+    static buildSummary(recorder, iteration) {
+        const lastAssistant = [...recorder.messages]
             .reverse()
             .find((m) => m.role === 'assistant' && m.content !== null);
         return {
             iteration,
-            messageCount: runMgr.messages.length,
-            tokenUsage: { ...runMgr.tokenUsage },
-            costInfo: { ...runMgr.costInfo },
+            messageCount: recorder.messages.length,
+            tokenUsage: { ...recorder.tokenUsage },
+            costInfo: { ...recorder.costInfo },
             lastAssistantMessage: lastAssistant?.content ?? undefined,
         };
     }
 }
+/**
+ * The context a checkpoint restores: the fold of its session log through
+ * `throughSeq`, the decision it is parked on, and the operator intent it
+ * names.
+ */
+export async function restoreCheckpointContext(log, document) {
+    const history = await readFoldedHistory(log, { throughSeq: document.throughSeq });
+    const messages = history.map((entry) => entry.message);
+    const messageIds = new Map();
+    for (const entry of history) {
+        if (entry.messageId)
+            messageIds.set(entry.message, entry.messageId);
+    }
+    const park = (await readParks(log, { turnId: document.turnId }))
+        .filter((candidate) => candidate.checkpointId === document.checkpointId)
+        .at(-1);
+    // The operator intent a checkpoint names survives compaction: when the
+    // fold no longer holds it, its own record (with any replacement) does.
+    const intentId = document.latestUserMessageId;
+    const intent = intentId === undefined
+        ? undefined
+        : (history.find((entry) => entry.messageId === intentId)?.message ??
+            (await readRecordedMessage(log, intentId, document.throughSeq)));
+    if (intentId !== undefined && intent === undefined) {
+        throw new Error(`Checkpoint latestUserMessage names message ${intentId}, which its session log does not hold`);
+    }
+    // Guidance delivered attached to a tool result: the intent is the note.
+    const guidance = intent?.role === 'tool' && typeof intent.content === 'string'
+        ? readSteeringNote(intent.content)
+        : undefined;
+    const operatorIntent = guidance !== undefined ? createRuntimeContextMessage(guidance, 'steering') : intent;
+    return {
+        id: document.checkpointId,
+        document,
+        messages,
+        messageIds,
+        ...(park ? { pending: park.pending } : {}),
+        ...(operatorIntent ? { latestUserMessage: snapshotUserIntent(operatorIntent) } : {}),
+    };
+}
+/**
+ * A message as its own record left it (with any `message_replaced` applied),
+ * whether or not a compaction has since dropped it from the fold.
+ */
+async function readRecordedMessage(log, messageId, throughSeq) {
+    let found;
+    for await (const { record } of log.read({ throughSeq })) {
+        const entry = record;
+        if ((entry.type === 'message' && entry.messageId === messageId) ||
+            (entry.type === 'message_replaced' && entry.targetMessageId === messageId)) {
+            found = { content: entry.content, ...(entry.spill ? { spill: entry.spill } : {}) };
+        }
+    }
+    if (!found)
+        return undefined;
+    if (found.spill) {
+        return JSON.parse(await log.readSpill(found.spill));
+    }
+    return found.content;
+}
+function withDefined(key, value) {
+    return (value === undefined ? {} : { [key]: value });
+}
 //# sourceMappingURL=checkpoint.js.map