@celestea/studio 2.7.1

package/dist/question-registry.js

@@ -0,0 +1,212 @@
+/**
+ * The pending-question table (W783 §5.1) — one [PendingQuestion] per unanswered
+ * request, plus the process-wide registry the HTTP layer answers into.
+ *
+ * Shape mirrors the official DSH `PendingQuestion` (same four members, same
+ * delegation sentinel, same abort wiring), with the two behaviours this repo
+ * adds:
+ *
+ *   1. **it can EXPEND** (§6). `expires_at` is an ABSOLUTE deadline judged at
+ *      read time (the `grants.ts: isExpired` pattern), and `timeout()` is the
+ *      active half that makes the parked `await` settle even if nobody ever
+ *      reads the table. The timer is cleared on every settlement, so a live
+ *      registry never holds a stray handle.
+ *   2. **the §6.2 race is not a bug.** The user answering and the clock
+ *      expiring are both legitimate; whoever arrives first wins and the loser
+ *      is TOLD it lost (`answer()` returns false) instead of throwing. The
+ *      strict double-settle guard stays internal, where a second settlement
+ *      really is a defect.
+ *
+ * `result` is the promise the waterfall layer hands back, so an answer RESOLVES
+ * the parked tool call directly — the answer never travels as a message (§4.2).
+ */
+import { UserQuestionError } from "@celestea/core";
+function deferred() {
+    let resolve;
+    let reject;
+    let done = false;
+    const promise = new Promise((res, rej) => {
+        resolve = (value) => {
+            done = true;
+            res(value);
+        };
+        reject = (reason) => {
+            done = true;
+            rej(reason);
+        };
+    });
+    return { promise, resolve, reject, settled: () => done };
+}
+/** The empty answer a timeout returns — the system decides NOTHING for the model. */
+export const TIMED_OUT_OUTCOME = { answers: [], timed_out: true };
+/** One unanswered question, awaiting the human. */
+export class PendingQuestion {
+    requestId;
+    sessionId;
+    questions;
+    expiresAt;
+    /** The resolved maximum wait in ms (§6.4). */
+    timeoutMs;
+    /** The promise the answerer waterfall returns to the parked tool call. */
+    result;
+    completion = deferred();
+    signal;
+    onAbort;
+    /** Rejection sentinel that asks the waterfall to try the layer behind us. */
+    delegated = Symbol("pending question delegated");
+    settled = false;
+    timer = null;
+    outcome = null;
+    constructor(init) {
+        this.requestId = init.requestId;
+        this.sessionId = init.sessionId;
+        this.questions = init.questions;
+        this.expiresAt = init.expiresAt;
+        this.timeoutMs = init.timeoutMs;
+        this.result = this.completion.promise;
+        this.signal = init.signal;
+        if (init.signal === undefined) {
+            this.onAbort = undefined;
+            return;
+        }
+        this.onAbort = () => this.abort(abortedQuestion());
+        init.signal.addEventListener("abort", this.onAbort, { once: true });
+        // A signal that was ALREADY aborted never fires the event again.
+        if (init.signal.aborted)
+            this.onAbort();
+    }
+    /** Has this question already been settled (answered, expired, cancelled…)? */
+    get isSettled() {
+        return this.settled;
+    }
+    /** How it ended, or null while it is still answerable. */
+    get settlement() {
+        return this.outcome;
+    }
+    /** Read-time expiry (§6.1, the authoritative half): `now >= expires_at`. */
+    isExpired(now) {
+        return now >= this.expiresAt;
+    }
+    /** Milliseconds left, floored at 0 (what the UI counts down). */
+    remainingMs(now) {
+        return Math.max(0, this.expiresAt - now);
+    }
+    /**
+     * The human answered. Returns false when the question was already settled —
+     * that is the §6.2 race, not a defect, so the caller reports it instead of
+     * throwing. `timed_out` is always false here: a real answer arrived.
+     */
+    answer(answers) {
+        return this.settle("answered", () => this.completion.resolve({ answers, timed_out: false }));
+    }
+    /** The deadline passed: settle with the EMPTY answer set (§6.3). */
+    timeout() {
+        return this.settle("timed_out", () => this.completion.resolve(TIMED_OUT_OUTCOME));
+    }
+    /** The user dismissed the card (§5.1 `cancel`). */
+    cancel(reason = "the user cancelled ask_user_question") {
+        return this.settle("cancelled", () => this.completion.reject(new UserQuestionError(reason, "ASK_CANCELLED")));
+    }
+    /** Transport / scope / plugin lifetime ended (§5.1 `abort`). */
+    abort(reason) {
+        return this.settle("aborted", () => this.completion.reject(reason));
+    }
+    /**
+     * This layer will not answer: reject with the delegation sentinel so the
+     * waterfall runs the next layer. Silent when already settled (DSH behaviour).
+     */
+    delegate() {
+        if (this.settled)
+            return false;
+        return this.settle("aborted", () => this.completion.reject(this.delegated));
+    }
+    /** Did [delegate] produce this rejection reason? */
+    isDelegation(reason) {
+        return reason === this.delegated;
+    }
+    /**
+     * Arm the active half of the double track (§6.1). The timer only ever calls
+     * [timeout], which is a no-op once the user answered first.
+     */
+    armTimer(now) {
+        if (this.settled || this.timer !== null)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.timeout();
+        }, Math.max(0, this.expiresAt - now()));
+        // Never hold the process open for a question nobody is waiting on.
+        this.timer.unref?.();
+    }
+    /** One settlement, ever: the strict guard that exposes a real double-settle. */
+    settle(kind, commit) {
+        if (this.settled)
+            return false;
+        this.settled = true;
+        this.outcome = kind;
+        this.disarm();
+        commit();
+        return true;
+    }
+    /** Drop the timer and the abort listener — no handle outlives the question. */
+    disarm() {
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (this.signal !== undefined && this.onAbort !== undefined) {
+            this.signal.removeEventListener("abort", this.onAbort);
+        }
+    }
+}
+/** The rejection an aborted wait produces (§5.3 `ASK_ABORTED`). */
+export function abortedQuestion(cause) {
+    return new UserQuestionError("ask_user_question was aborted before the user answered", "ASK_ABORTED", cause === undefined ? undefined : { cause });
+}
+/**
+ * The process-wide pending table.
+ *
+ * It is ONE registry per host process, not one per session: the answer endpoint
+ * addresses a request by id alone and must find it without being told which
+ * session asked. Each generation's own service registers into this shared table,
+ * which is also what lets `GET /api/sessions/{id}/questions` filter by session.
+ */
+export class QuestionRegistry {
+    pending = new Map();
+    counter = 0;
+    /** Mint a request id (`q-<n>`); unique for the life of the process. */
+    nextRequestId() {
+        this.counter += 1;
+        return `q-${this.counter}`;
+    }
+    /** Register a question; a duplicate id is a bug, so it fails loudly. */
+    add(question) {
+        if (this.pending.has(question.requestId)) {
+            throw new Error(`question '${question.requestId}' is already pending`);
+        }
+        this.pending.set(question.requestId, question);
+    }
+    /** Drop a settled question (idempotent). */
+    remove(requestId) {
+        this.pending.delete(requestId);
+    }
+    get(requestId) {
+        return this.pending.get(requestId);
+    }
+    /** Every unanswered question, oldest first (registration order). */
+    all() {
+        return [...this.pending.values()];
+    }
+    /** The unanswered questions of ONE session (`null` = the detached generation). */
+    ofSession(sessionId) {
+        return this.all().filter((question) => question.sessionId === sessionId);
+    }
+    /** How many questions are still parked (diagnostics / tests). */
+    size() {
+        return this.pending.size;
+    }
+}
+/** A fresh table (one per host process). */
+export function createQuestionRegistry() {
+    return new QuestionRegistry();
+}

package/dist/question-rows.d.ts

@@ -0,0 +1,32 @@
+/**
+ * W783 §7 — the two session-log rows of the user-question feature.
+ *
+ * WHY THEY EXIST AT ALL: `tool_result` has no `decision` field, so a question's
+ * state would otherwise live only in an SSE frame and vanish on reload. These
+ * rows are the durable record: a reconnecting client rebuilds the card from
+ * `user_question`, and a replay can tell "the user answered" from "the clock ran
+ * out" by finding (or not finding) the matching `user_answer`.
+ *
+ * WHAT THEY ARE NOT: model-visible history. Both projections SKIP them, because
+ * the model already receives the outcome as the ordinary `tool_result` of
+ * `ask_user_question` — projecting them too would invent a second copy of the
+ * same decision and break the tool_call/tool_result pairing.
+ *
+ * The row shape is additive (W783 §7.2): a reader that does not know these two
+ * types treats them exactly like any other unknown row — a torn tail.
+ */
+import type { AskUserQuestionAnswerItem, AskUserQuestionItem, SessionEvent } from "@celestea/core";
+import type { PendingQuestion } from "./question-registry.js";
+/** The `user_question` row of one parked request. */
+export declare function questionAskedRow(question: PendingQuestion): SessionEvent;
+/**
+ * The `user_answer` row of one settled request.
+ *
+ * `timedOut` is written as `timed_out` and is what distinguishes the §6.3
+ * expiry ("nobody was there") from a real answer that selected nothing.
+ */
+export declare function questionAnsweredRow(requestId: string, answers: readonly AskUserQuestionAnswerItem[], timedOut: boolean): SessionEvent;
+/** The questions of a `user_question` row, as the seam's item shape. */
+export declare function askedItemsOf(event: {
+    questions?: unknown;
+}): AskUserQuestionItem[];

package/dist/question-rows.js

@@ -0,0 +1,43 @@
+/**
+ * W783 §7 — the two session-log rows of the user-question feature.
+ *
+ * WHY THEY EXIST AT ALL: `tool_result` has no `decision` field, so a question's
+ * state would otherwise live only in an SSE frame and vanish on reload. These
+ * rows are the durable record: a reconnecting client rebuilds the card from
+ * `user_question`, and a replay can tell "the user answered" from "the clock ran
+ * out" by finding (or not finding) the matching `user_answer`.
+ *
+ * WHAT THEY ARE NOT: model-visible history. Both projections SKIP them, because
+ * the model already receives the outcome as the ordinary `tool_result` of
+ * `ask_user_question` — projecting them too would invent a second copy of the
+ * same decision and break the tool_call/tool_result pairing.
+ *
+ * The row shape is additive (W783 §7.2): a reader that does not know these two
+ * types treats them exactly like any other unknown row — a torn tail.
+ */
+/** The `user_question` row of one parked request. */
+export function questionAskedRow(question) {
+    return {
+        type: "user_question",
+        id: question.requestId,
+        questions: [...question.questions],
+        // Both timings are written explicitly, so a replay can compute "expired"
+        // from the row alone (read-time judgement, §6.1) with no timer involved.
+        expires_at: question.expiresAt,
+        timeout_ms: question.timeoutMs,
+    };
+}
+/**
+ * The `user_answer` row of one settled request.
+ *
+ * `timedOut` is written as `timed_out` and is what distinguishes the §6.3
+ * expiry ("nobody was there") from a real answer that selected nothing.
+ */
+export function questionAnsweredRow(requestId, answers, timedOut) {
+    return { type: "user_answer", id: requestId, answers: [...answers], timed_out: timedOut };
+}
+/** The questions of a `user_question` row, as the seam's item shape. */
+export function askedItemsOf(event) {
+    const raw = event.questions;
+    return Array.isArray(raw) ? raw : [];
+}

package/dist/replay/compare.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Comparison primitives + the finding vocabulary of the P5 report.
+ *
+ * Four evidence classes, deliberately distinguished (the point of a double-run
+ * report is to say WHICH claims are golden and which are self-consistency):
+ *   - `byte-exact`   the artifact was reproduced byte for byte (JSONL logs,
+ *                    SSE wire frames, backups);
+ *   - `golden`       compared against a capture of the retired backend
+ *                    (`messages-expected.json`);
+ *   - `spec-derived` compared against an independent re-derivation of the
+ *                    frozen spec (compaction planning), i.e. cross-implementation;
+ *   - `self-check`   compared against a TS-derived artifact (SSE transcript of a
+ *                    session whose transcript was never captured);
+ *   - `info` / `skip` — reported, never a failure.
+ */
+export type FindingKind = "byte-exact" | "golden" | "spec-derived" | "self-check" | "info";
+export type FindingVerdict = "match" | "diff" | "skip";
+export interface Finding {
+    scope: string;
+    kind: FindingKind;
+    verdict: FindingVerdict;
+    detail: string;
+    /** Up to a handful of concrete divergences (paths + values). */
+    diffs?: string[];
+}
+/** sha256 of a text or buffer (fixture manifests are hash-checked). */
+export declare function sha256(text: string | Buffer): string;
+/** Short single-line rendering of a value for a diff detail line. */
+export declare function brief(value: unknown, max?: number): string;
+/** First index where two byte strings differ (-1 = equal). */
+export declare function firstByteDiff(a: string, b: string): number;
+/** Byte-level comparison of two artifacts. */
+export declare function compareBytes(scope: string, expected: string, actual: string, note: string): Finding;
+/** How many concrete divergences one finding carries (keeps reports readable). */
+export declare const MAX_DIFFS = 3;
+/** Element-wise JSON comparison with the first [MAX_DIFFS] divergences. */
+export declare function compareJson(scope: string, kind: FindingKind, expected: unknown, actual: unknown, note: string): Finding;
+/** A `skip`/`info` finding (never fails the run). */
+export declare function note(scope: string, kind: FindingKind, detail: string, verdict?: FindingVerdict): Finding;
+/** Count findings by verdict. */
+export declare function tally(findings: readonly Finding[]): {
+    matched: number;
+    diffed: number;
+    skipped: number;
+    byteExact: number;
+    golden: number;
+};

package/dist/replay/compare.js

@@ -0,0 +1,89 @@
+/**
+ * Comparison primitives + the finding vocabulary of the P5 report.
+ *
+ * Four evidence classes, deliberately distinguished (the point of a double-run
+ * report is to say WHICH claims are golden and which are self-consistency):
+ *   - `byte-exact`   the artifact was reproduced byte for byte (JSONL logs,
+ *                    SSE wire frames, backups);
+ *   - `golden`       compared against a capture of the retired backend
+ *                    (`messages-expected.json`);
+ *   - `spec-derived` compared against an independent re-derivation of the
+ *                    frozen spec (compaction planning), i.e. cross-implementation;
+ *   - `self-check`   compared against a TS-derived artifact (SSE transcript of a
+ *                    session whose transcript was never captured);
+ *   - `info` / `skip` — reported, never a failure.
+ */
+import { createHash } from "node:crypto";
+import { firstJsonDiff, stableStringify } from "@celestea/core";
+/** sha256 of a text or buffer (fixture manifests are hash-checked). */
+export function sha256(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+/** Short single-line rendering of a value for a diff detail line. */
+export function brief(value, max = 120) {
+    const text = typeof value === "string" ? value : stableStringify(value ?? null);
+    return text.length <= max ? text : `${text.slice(0, max)}…`;
+}
+/** First index where two byte strings differ (-1 = equal). */
+export function firstByteDiff(a, b) {
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++)
+        if (a[i] !== b[i])
+            return i;
+    return a.length === b.length ? -1 : n;
+}
+/** Byte-level comparison of two artifacts. */
+export function compareBytes(scope, expected, actual, note) {
+    if (expected === actual) {
+        return { scope, kind: "byte-exact", verdict: "match", detail: `${note}: ${Buffer.byteLength(actual)} bytes identical (sha256 ${sha256(actual).slice(0, 12)})` };
+    }
+    const at = firstByteDiff(expected, actual);
+    return {
+        scope,
+        kind: "byte-exact",
+        verdict: "diff",
+        detail: `${note}: byte ${at} differs (expected ${Buffer.byteLength(expected)} B, actual ${Buffer.byteLength(actual)} B)`,
+        diffs: [
+            `expected@${at}: ${brief(expected.slice(Math.max(0, at - 40), at + 80))}`,
+            `actual@${at}:   ${brief(actual.slice(Math.max(0, at - 40), at + 80))}`,
+        ],
+    };
+}
+/** How many concrete divergences one finding carries (keeps reports readable). */
+export const MAX_DIFFS = 3;
+/** Element-wise JSON comparison with the first [MAX_DIFFS] divergences. */
+export function compareJson(scope, kind, expected, actual, note) {
+    const max = MAX_DIFFS;
+    if (stableStringify(expected) === stableStringify(actual)) {
+        const size = Array.isArray(actual) ? `${actual.length} item(s)` : "value";
+        return { scope, kind, verdict: "match", detail: `${note}: ${size} identical` };
+    }
+    const diffs = [];
+    if (Array.isArray(expected) && Array.isArray(actual)) {
+        if (expected.length !== actual.length)
+            diffs.push(`length ${expected.length} != ${actual.length}`);
+        for (let i = 0; i < Math.min(expected.length, actual.length) && diffs.length < max; i++) {
+            const d = firstJsonDiff(expected[i], actual[i], `$[${i}]`);
+            if (d !== null)
+                diffs.push(d);
+        }
+    }
+    else {
+        diffs.push(firstJsonDiff(expected, actual, "$") ?? "values differ");
+    }
+    return { scope, kind, verdict: "diff", detail: `${note}: ${diffs.length} divergence(s)`, diffs };
+}
+/** A `skip`/`info` finding (never fails the run). */
+export function note(scope, kind, detail, verdict = "skip") {
+    return { scope, kind, detail, verdict };
+}
+/** Count findings by verdict. */
+export function tally(findings) {
+    return {
+        matched: findings.filter((f) => f.verdict === "match").length,
+        diffed: findings.filter((f) => f.verdict === "diff").length,
+        skipped: findings.filter((f) => f.verdict === "skip").length,
+        byteExact: findings.filter((f) => f.verdict === "match" && f.kind === "byte-exact").length,
+        golden: findings.filter((f) => f.verdict === "match" && f.kind === "golden").length,
+    };
+}

package/dist/replay/e2e-replay.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The P5 double-run driver: replay every golden session through the TS host and
+ * aggregate the structured report.
+ *
+ * The run is SEQUENTIAL on purpose (one host, one engine generation, one session
+ * at a time): a replay mutates the session copy it works on (probe turn +
+ * compaction), and a shared host would let one session's compaction be observed
+ * by another's comparison.
+ */
+import { type Finding } from "./compare.js";
+import { type SessionE2E } from "./session-e2e.js";
+export interface ReplayE2EOptions {
+    fixturesDir?: string;
+    /** Input of the real probe turn appended to every session copy. */
+    probeInput?: string;
+    /** Replay only the first N sessions (smoke runs). */
+    maxSessions?: number;
+}
+export interface ReplayE2ESummary {
+    sessions: number;
+    findings: number;
+    matched: number;
+    byteExact: number;
+    golden: number;
+    diffed: number;
+    skipped: number;
+    errors: number;
+    verdict: "match" | "diff" | "error";
+}
+export interface ReplayE2EReport {
+    generatedAt: string;
+    fixtures: string;
+    fixturesGeneratedAt: string;
+    probeInput: string;
+    summary: ReplayE2ESummary;
+    sessions: SessionE2E[];
+    findings: Finding[];
+    errors: string[];
+    gaps: string[];
+}
+/** What is NOT yet golden after P5 (each item names the missing capture). */
+export declare const P6_GAPS: readonly string[];
+/** Replay all fixture sessions and aggregate the report. */
+export declare function runReplayE2E(opts?: ReplayE2EOptions): Promise<ReplayE2EReport>;
+/** Exit code of a report: 0 match, 1 diff, 2 harness error. */
+export declare function exitCodeOf(report: ReplayE2EReport): number;

package/dist/replay/e2e-replay.js

@@ -0,0 +1,91 @@
+/**
+ * The P5 double-run driver: replay every golden session through the TS host and
+ * aggregate the structured report.
+ *
+ * The run is SEQUENTIAL on purpose (one host, one engine generation, one session
+ * at a time): a replay mutates the session copy it works on (probe turn +
+ * compaction), and a shared host would let one session's compaction be observed
+ * by another's comparison.
+ */
+import { resolve } from "node:path";
+import { note, tally } from "./compare.js";
+import { loadManifest, splitSessionId } from "./fixtures.js";
+import { createReplayHost } from "./host.js";
+import { replaySession } from "./session-e2e.js";
+/** What is NOT yet golden after P5 (each item names the missing capture). */
+export const P6_GAPS = [
+    "compact 后日志：TS 侧与「独立重推导（spec-derived）」逐字节一致，但实机 compact 产物尚未捕获 —— P6 需用打桩上游（非流式摘要）跑一次 compact，导出 compact-expected.jsonl 作为真黄金。",
+    "SSE 序列：逐帧对比的黄金是 TS 自推导 transcript（P0 导出器生成），fixtures/sse/live-capture.raw.txt 为 0 字节（P0 禁止 POST /api/turn）—— P6 需驱动一次真实 turn 抓取 live SSE（8 事件 + lagged 降级），并把 JSONL transcript 换成实机原生产物。",
+    "LLM 是离线确定性 mock：usage / cache_hit_ratio / context_usage 的数值来自 mock 的 usage 帧，未经真实 provider 的 SSE/usage 解析链路 —— P6 需接 packages/llm 的 mock-upstream（本地假上游，仍禁真网）验证解析与状态线口径。",
+    "live/*.json（实机只读快照）尚未纳入 e2e 逐字段对拍（本阶段只验形状与口径）—— P6 把 status/config/tools/health 快照纳入逐字段对比。",
+    "worker 编排：spawn/send/status 走真实 registry 且 driven=true，但表是内存实现（tsvPath=null，不写共享 registry.tsv），receipt/report 文件协议未对拍 —— P6 与实机的 registry.tsv / WORKER_<wid>_DONE 回执对拍。",
+    "compact 摘要正文由 mock 生成，只做结构性校验（头部轮、保留轮、重编号、备份）—— P6 接入真实/打桩摘要后再逐字节对拍摘要正文。",
+    "大 fixture 的 SSE 采用分批推送（每批 < 总线容量 512），未覆盖容量溢出后的 lagged 降级 —— 该路径由 apps/studio/src/sse.test.ts 覆盖，P6 需在 e2e 中补一条真机溢出用例。",
+];
+/** Replay all fixture sessions and aggregate the report. */
+export async function runReplayE2E(opts = {}) {
+    const fixturesDir = resolve(opts.fixturesDir ?? "fixtures");
+    const manifest = loadManifest(fixturesDir);
+    const entries = (opts.maxSessions === undefined ? manifest.sessions : manifest.sessions.slice(0, opts.maxSessions));
+    const host = createReplayHost({ workspaces: [...new Set(entries.map((e) => splitSessionId(e.id).workspace))] });
+    const probeInput = opts.probeInput ?? "P5 重放探针";
+    const sessions = [];
+    const errors = [];
+    try {
+        for (const entry of entries)
+            sessions.push(await replayOne(host, fixturesDir, entry, probeInput, errors));
+    }
+    finally {
+        host.cleanup();
+    }
+    return buildReport({ fixturesDir, manifestGeneratedAt: manifest.generatedAt, probeInput, sessions, errors });
+}
+async function replayOne(host, fixturesDir, entry, probeInput, errors) {
+    try {
+        return await replaySession({ host, fixturesDir, entry, probeInput });
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        errors.push(`${entry.id}: ${message}`);
+        return {
+            id: entry.id,
+            slug: entry.slug,
+            roles: entry.roles,
+            events: entry.events,
+            turns: entry.turns,
+            findings: [note(`${entry.id} :: replay`, "info", `replay aborted: ${message}`, "diff")],
+            verdict: "diff",
+        };
+    }
+}
+function buildReport(input) {
+    const findings = input.sessions.flatMap((s) => s.findings);
+    const counts = tally(findings);
+    return {
+        generatedAt: new Date().toISOString(),
+        fixtures: input.fixturesDir,
+        fixturesGeneratedAt: input.manifestGeneratedAt,
+        probeInput: input.probeInput,
+        summary: {
+            sessions: input.sessions.length,
+            findings: findings.length,
+            matched: counts.matched,
+            byteExact: counts.byteExact,
+            golden: counts.golden,
+            diffed: counts.diffed,
+            skipped: counts.skipped,
+            errors: input.errors.length,
+            verdict: input.errors.length > 0 ? "error" : counts.diffed > 0 ? "diff" : "match",
+        },
+        sessions: input.sessions,
+        findings,
+        errors: input.errors,
+        gaps: [...P6_GAPS],
+    };
+}
+/** Exit code of a report: 0 match, 1 diff, 2 harness error. */
+export function exitCodeOf(report) {
+    if (report.summary.errors > 0)
+        return 2;
+    return report.summary.diffed > 0 ? 1 : 0;
+}

package/dist/replay/expect-compact.d.ts

@@ -0,0 +1,31 @@
+/**
+ * INDEPENDENT re-derivation of the frozen compaction plan (W259).
+ *
+ * This is deliberately a SECOND implementation: the runtime's planner lives in
+ * `packages/runtime/src/compact/plan.ts` (written as a straight port of
+ * `celestea_studio/src/compact.rs`), while this one is written from the spec text
+ * with a different shape (index scan + slice, no helper reuse). A P5 comparison
+ * between the two is therefore a cross-implementation check of the STRUCTURE
+ * (head turn, kept-tail selection, renumbering, dropping an unterminated tail),
+ * not a tautology.
+ *
+ * The summary string is passed in (the replay reads it back out of the compacted
+ * log), so the summary itself is out of scope for this comparison.
+ */
+import type { SessionEvent } from "@celestea/core";
+export declare const SPEC_THRESHOLD = 8;
+export declare const SPEC_KEEP = 4;
+export declare const SPEC_HEAD_PREFIX = "\u3010\u4E0A\u4E0B\u6587\u538B\u7F29\u3011";
+export declare const SPEC_HEAD_ASSISTANT = "\u4E0A\u4E0B\u6587\u5DF2\u538B\u7F29\uFF0C\u4EE5\u4E0A\u4E3A\u5386\u53F2\u6458\u8981\u3002";
+/** Index ranges [start, end) of every complete turn (`turn_start` .. `turn_end`). */
+export declare function completeTurnRanges(events: readonly SessionEvent[]): Array<[number, number]>;
+/** The expected post-compaction log, or null when the history is too short. */
+export declare function expectedCompactLog(events: readonly SessionEvent[], summary: string, keep?: number): SessionEvent[] | null;
+/** The inner (non-boundary) rows of a turn: what renumbering must NOT touch. */
+export declare function turnBody(events: readonly SessionEvent[]): SessionEvent[];
+/** Split a serialized log into one entry per complete turn (raw text lines). */
+export declare function rawTurnBodies(text: string, parse: (t: string) => {
+    events: SessionEvent[];
+}): string[][];
+/** The summary text embedded in a compacted log's head turn (null when absent). */
+export declare function headSummary(events: readonly SessionEvent[]): string | null;