elanous 0.2.28 → 0.2.31

package/src/self-implement/pr-title.ts

@@ -0,0 +1,123 @@
+import { readFileSync } from 'node:fs';
+import { parseAskProseTitle } from '../self-dev/launch-preflight.js';
+import { extractVerbatimOriginalAsk } from './goal-author.js';
+
+export function goalDocumentForReleaseNote(goalFile?: string): string {
+  if (!goalFile) return '';
+  try { return readFileSync(goalFile, 'utf8'); }
+  catch { return ''; }
+}
+
+function isRepositoryRelativePath(candidate: string): boolean {
+  if (/^(?:[A-Za-z][A-Za-z0-9+.-]*:\/\/|[\\/]|[A-Za-z]:[\\/])/.test(candidate)) return false;
+  const parts = candidate.split('/');
+  return parts.length > 1
+    && parts.every((part) => part !== '.' && part !== '..' && /^[A-Za-z0-9_.-]+$/.test(part))
+    && /\.[A-Za-z0-9]+$/.test(parts.at(-1)!);
+}
+
+function extractRepositoryRelativePaths(first: string): string[] {
+  const candidates = first.split(/[\s,;()[\]{}"'`<>]+/).filter(Boolean);
+  return candidates.filter(isRepositoryRelativePath);
+}
+
+function parseAskMarkdownH1(feature: string): string | undefined {
+  // ⛔ 펜스는 «문자»만이 아니라 «길이»로 닫힌다(CommonMark): 닫는 줄은 같은 문자 · 여는 줄 이상의 길이 · 뒤에 정보 문자열 없음.
+  //   🩸 2026-09-23(#20050 착지 직후 실물): GOAL 문서가 원래 ask 를 ```` 네 개 펜스로 싸고, 그 안에 ``` 블록이 있다.
+  //   문자만 보면 안쪽 ``` 이 바깥 ```` 를 «닫아» 안팎이 뒤집히고 ```bash 안의 `# 주석` 이 다시 제목이 됐다.
+  let fence: { marker: '`' | '~'; run: number } | undefined;
+  for (const line of feature.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    const marker = trimmed[0] === '`' || trimmed[0] === '~' ? trimmed[0] : undefined;
+    let run = 0;
+    if (marker) {
+      while (run < trimmed.length && trimmed[run] === marker) run += 1;
+    }
+    if (marker && run >= 3) {
+      if (!fence) {
+        fence = { marker, run };
+        continue;
+      }
+      if (fence.marker === marker && run >= fence.run && trimmed.slice(run).trim() === '') {
+        fence = undefined;
+        continue;
+      }
+    }
+    if (fence) continue;
+    if (line[0] !== '#' || line[1] === '#') continue;
+    if (line.length < 2 || !/\s/.test(line[1]!)) continue;
+    const text = line.slice(1).trim();
+    if (text) return text;
+  }
+  return undefined;
+}
+
+function prTitleCodePointCount(text: string): number {
+  return Array.from(text).length;
+}
+
+function truncatePrTitle(text: string): string {
+  const points = Array.from(text);
+  return points.length <= 72 ? text : `${points.slice(0, 69).join('')}...`;
+}
+
+export function goalChecklistIds(feature: string, goalFile?: string): string[] {
+  const document = goalFile ? goalDocumentForReleaseNote(goalFile) : feature;
+  const declaration = document.split(/\r?\n/).find((line) => line.startsWith('- 칸 id: '));
+  const declared = declaration?.slice('- 칸 id: '.length).trim();
+  if (declared && declared !== 'not declared') {
+    return [...new Set(declared.split(' · ').map((id) => id.trim()).filter(Boolean))];
+  }
+  const firstLine = feature.split(/\r?\n/, 1)[0] ?? '';
+  return [...new Set(Array.from(firstLine.matchAll(/\b[A-Z][A-Z0-9]+-[A-Z0-9]+\b/g), (match) => match[0]))];
+}
+
+function prTitleWithoutChecklistId(feature: string): string {
+  const proseTitle = parseAskProseTitle(feature);
+  if (proseTitle) return truncatePrTitle(proseTitle);
+
+  const headingTitle = parseAskMarkdownH1(feature);
+  if (headingTitle) return truncatePrTitle(headingTitle);
+
+  // ⛔ GOAL 문서는 원래 ask 를 `Original ask (verbatim, unmodified):` 아래 ```` 펜스로 싣는다 — 그 안은 «코드»가 아니라 인용된 마크다운이다.
+  //   🩸 2026-09-23: #20051 이 펜스를 길이로 닫게 고치자 그 인용 블록 안의 H1 까지 «건너뛰어»,
+  //   첫 줄이 `대상 경로:` 인 GOAL 문서 대부분이 경로 요약 제목으로 떨어졌다(실물: #20055 `src/self-implement: gate-baseline.ts, …`).
+  //   ⇒ 인용된 ask 를 꺼내 그 «안»에서 같은 규칙(제목: 줄 → 펜스 밖 H1)으로 한 번 더 찾는다.
+  //   ⚠️ 정보 문자열이 붙은 펜스(```bash 등)로 싸였으면 그 안은 «코드»다 — 인용된 마크다운으로 보지 않는다.
+  const verbatim = extractVerbatimOriginalAsk(feature);
+  const opener = verbatim?.range ? feature.slice(0, verbatim.range.start).split(/\r?\n/).filter((line, i, all) => i === all.length - 2)[0] ?? '' : '';
+  const verbatimAsk = verbatim && /^\s*(`{3,}|~{3,})\s*$/.test(opener) ? verbatim.ask : undefined;
+  if (verbatimAsk) {
+    const askTitle = parseAskProseTitle(verbatimAsk) ?? parseAskMarkdownH1(verbatimAsk);
+    if (askTitle) return truncatePrTitle(askTitle);
+  }
+
+  const first = feature.split('\n')[0]!.trim();
+  const paths = extractRepositoryRelativePaths(first);
+  if (!paths.length) return truncatePrTitle(first);
+
+  const pathParts = paths.map((path) => path.split('/'));
+  const commonParts: string[] = [];
+  for (let index = 0; index < pathParts[0]!.length - 1; index++) {
+    const part = pathParts[0]![index]!;
+    if (!pathParts.every((parts) => parts[index] === part)) break;
+    commonParts.push(part);
+  }
+  const fileNames = pathParts.map((parts) => parts.at(-1)!);
+  const directoryPrefix = commonParts.length ? `${commonParts.join('/')}: ` : '';
+  const titlePrefix = prTitleCodePointCount(directoryPrefix) + prTitleCodePointCount(fileNames[0]!) <= 72 ? directoryPrefix : '';
+  const title = fileNames.reduce((result, fileName) => {
+    const next = result ? `${result}, ${fileName}` : fileName;
+    return prTitleCodePointCount(titlePrefix) + prTitleCodePointCount(next) <= 72 ? next : result;
+  }, '');
+  if (title) return `${titlePrefix}${title}`;
+  const firstFileName = fileNames[0]!;
+  return truncatePrTitle(firstFileName);
+}
+
+export function prTitle(feature: string, goalFile?: string): string {
+  const title = prTitleWithoutChecklistId(feature);
+  const id = goalChecklistIds(feature, goalFile)[0];
+  if (!id) return title;
+  return truncatePrTitle(title.startsWith(`${id}: `) ? title : `${id}: ${title}`);
+}

package/src/self-implement/review-mustfix-class.ts

@@ -0,0 +1,115 @@
+// ── REVIEW-MUSTFIX-CLASSIFY — 리뷰 must-fix 를 «수의 추이»가 아니라 «회차 짝»으로 가른다 ──
+//
+// 수의 추이(improving·stable·worsening·oscillating)는 «새 실결함이 매번 나오는 정상 수렴»과
+// «원리상 못 닫는 요구»를 못 가른다(#26644 · 10-12 · 5→3→2→3). 이 판정은 회차 짝으로 가른다:
+//
+//   ① new-defect        앞 회차에 없던 새 지적 — 그대로 수렴 간다(계속).
+//   ② post-land-evidence 착지 뒤에만 낼 수 있는 증거(운영 소비·실물 착지·live 호출자)를 요구하는
+//                          지적 — 같은 런 재수리 0 · «그림자 착지 → 관측 → live» 쪼개기 결정.
+//   ③ recurring          수리 뒤 같은 지적이 다시 나옴 — intent 경계 자동 명시 ⊕ 다른 모델 교차 리뷰 제안.
+//   unmeasured           이 회차 must-fix 를 안 쟀다 — 분류 불가, 슈퍼바이저 지금 동작 그대로.
+//
+// ⛔ 임의 임계(«두 번») 금지 — 짝은 «정규화 문면이 같다»는 사실 하나로 맞는다.
+
+/** Evidence a must-fix item demands that only a landing can produce. */
+export type MustFixEvidenceKind = 'ops-consumption' | 'artifact-landing' | 'live-caller';
+
+export interface MustFixItem {
+  /** Verbatim reviewer must-fix text. */
+  readonly text: string;
+  /** Evidence this item demands that only a landing can produce. */
+  readonly evidence?: MustFixEvidenceKind;
+  /** Pairing scope — the task that raised it (supervisor ledger); pairing never crosses tasks. */
+  readonly taskId?: string;
+}
+
+/** One round's observed must-fix list; `items` undefined/empty = the round's review was not observed. */
+export interface MustFixRoundObservation {
+  readonly items?: readonly MustFixItem[];
+}
+
+export type MustFixClass = 'new-defect' | 'post-land-evidence' | 'recurring' | 'unmeasured';
+
+export interface MustFixRoundClassification {
+  readonly class: MustFixClass;
+  readonly reason: string;
+  /** ② post-land-evidence — 같은 런 재수리 0, «그림자 착지 → 관측 → live» 쪼개기 결정. */
+  readonly split?: 'shadow-land → observe → live';
+  /** ③ recurring — intent 경계 자동 명시 ⊕ 다른 모델 교차 리뷰 제안. */
+  readonly crossReview?: true;
+  /** Evidence kinds this round's items demand (②). */
+  readonly evidence?: readonly MustFixEvidenceKind[];
+  /** Recurring item texts, normalized (③). */
+  readonly recurring?: readonly string[];
+}
+
+/** Evidence subjects, each matched as a whole word group. */
+const EVIDENCE_SUBJECTS: ReadonlyArray<readonly [MustFixEvidenceKind, string]> = [
+  ['live-caller', String.raw`(?:live|라이브)\s*(?:호출자|caller)`],
+  ['ops-consumption', String.raw`(?:운영(?:에서)?\s*소비|(?:prod(?:uction)?|ops)\s*consumption)`],
+  ['artifact-landing', String.raw`(?:(?:실물|실제)\s*착지|artifact\s*landing)`],
+];
+/** Korean: «<대상>[ 증거](를|을)? <요구>» or «<대상> 증거가 없다». */
+const KO_DEMAND = String.raw`(?:\s*(?:증거|증명)\s*(?:를|을)?|\s*(?:를|을))?\s*(?:보여라|보여\s*달라|대라|증명하라|입증하라|못\s*봤다|관측되지\s*않았다|확인되지\s*않았다)`;
+const KO_MISSING = String.raw`\s*(?:증거|증명)\s*(?:가|이)?\s*없다`;
+/** English: «show|prove|demonstrate [the] <subject> [evidence]» or «no <subject> evidence». */
+const EN_PREFIX = String.raw`(?:show|prove|demonstrate)\s+(?:the\s+)?`;
+
+/**
+ * Derive the post-land evidence kind a must-fix text *demands* — allow-list only: the WHOLE text (trimmed,
+ * one optional terminal «.»/«!») must be one of the pure evidence-demand forms above. Anything else — a second
+ * sentence, a comma, «그리고», a defect word, a different verb — stays undefined, i.e. ① same-run repair
+ * (의심스러우면 ① = 안전한 기본). Widening the recognised forms is a follow-up; outside them is ① on purpose.
+ */
+export function inferMustFixEvidence(text: string): MustFixEvidenceKind | undefined {
+  const t = text.trim().toLowerCase().replace(/\s+/gu, ' ').replace(/[.!]$/u, '');
+  for (const [kind, subject] of EVIDENCE_SUBJECTS) {
+    const forms = [
+      `${subject}${KO_DEMAND}`,
+      `${subject}${KO_MISSING}`,
+      `${EN_PREFIX}${subject}(?:\\s+evidence)?`,
+      `no\\s+${subject}\\s+evidence`,
+    ];
+    if (forms.some((form) => new RegExp(`^${form}$`, 'u').test(t))) return kind;
+  }
+  return undefined;
+}
+
+/** Pairing key: whitespace collapsed, lower-cased — same discipline as `noPrStreakKey`. */
+function mustFixKey(text: string): string {
+  return text.trim().replace(/\s+/gu, ' ').toLowerCase();
+}
+
+export function classifyMustFixRound(
+  prev: MustFixRoundObservation | undefined,
+  cur: MustFixRoundObservation,
+): MustFixRoundClassification {
+  const curItems = cur.items ?? [];
+  if (curItems.length === 0) {
+    return { class: 'unmeasured', reason: '이 회차 리뷰 must-fix 를 안 쟀다 — 분류 불가, 슈퍼바이저 지금 동작 그대로' };
+  }
+  const prevItems = prev?.items ?? [];
+  // Pairing never crosses tasks: same normalized text AND both sides name the same task — unknown origin never pairs.
+  const pairs = (p: MustFixItem, c: MustFixItem): boolean => mustFixKey(p.text) === mustFixKey(c.text)
+    && p.taskId !== undefined && c.taskId !== undefined && p.taskId === c.taskId;
+  const recurring = curItems.filter((item) => prevItems.some((p) => pairs(p, item)));
+  if (prevItems.length > 0 && recurring.length > 0) {
+    return {
+      class: 'recurring',
+      reason: `같은 지적이 수리 뒤에 다시 나왔다(${recurring.length}) — intent 경계를 명시하고 다른 모델 교차 리뷰를 제안한다`,
+      crossReview: true,
+      recurring: recurring.map((item) => mustFixKey(item.text)),
+    };
+  }
+  // ② only when every item demands post-land evidence — a real defect mixed in still gets its same-run repair (①).
+  const evidence = [...new Set(curItems.flatMap((item) => (item.evidence ? [item.evidence] : [])))];
+  if (curItems.every((item) => item.evidence !== undefined)) {
+    return {
+      class: 'post-land-evidence',
+      reason: `증거는 착지 뒤에만 난다(${evidence.join(' · ')}) — 같은 런 재수리 0, 그림자 착지 → 관측 → live 로 쪼갠다`,
+      evidence,
+      split: 'shadow-land → observe → live',
+    };
+  }
+  return { class: 'new-defect', reason: '앞 회차에 없던 새 지적 — 새 실결함 수렴으로 그대로 간다' };
+}

package/src/self-implement/run-checkpoint.ts

@@ -0,0 +1,235 @@
+/**
+ * run-checkpoint/v1 묶음 스키마 — 런의 «체크포인트» 스냅샷을 판 번호 있는 타입으로 직렬화한다.
+ *
+ * ⛔ 이 판은 «묶음 정의 ⊕ 조립 ⊕ 디스크 기록»까지만 담는다. orchestrator 배선 · run-ledger
+ *    additive 이벤트('checkpoint'/'resumed'/'checkpoint-failed') · salvage CLI 명령은
+ *    같은 골의 형제 조각이 담당한다(의도적 경계 — 분해 판 4조각의 1번).
+ *
+ * 📐 run-ledger 패턴을 «어느 것을 왜» 따르나(원문이 'writeCheckpoi'에서 끊겨 임의로 정하지 않는다):
+ *   ① `runLedgerDir`(run-ledger.ts:205) — 상태 뿌리에서 «자기 저장소 이름»의 디렉터리를 여는 방식.
+ *      여기도 `elanousStateRoot()` 아래 `run-checkpoint/` 디렉터리로 열어, 저장 위치가 run-ledger 와
+ *      같은 축(state root)에 있게 한다. 원문이 저장 위치의 경로를 정하지 않았으므로 이 패턴을 따른다.
+ *   ② `runLedgerPath`(run-ledger.ts:209) — runId 를 «normalizeRunId 의 산출 집합»으로 검증하고
+ *      거부는 유지하되 정규화는 «하지 않는다»(경로 탈출 방어). 여기도 같은 검사를 쓰되 파일은
+ *      스냅샷이므로 JSONL 추가가 아니라 «덮어쓰기» 하나로 `<runId>.checkpoint.json` 을 쓴다.
+ *      JSONL 이 아닌 이유: 원장은 사건의 «추가», 체크포인트는 마지막 상태의 «스냅샷»이다 —
+ *      appendRunLedgerEntry 가 줄을 «쌓는» 것과 달리 resume 은 «최신 하나»만 읽으면 된다.
+ *   ③ `appendRunLedgerEntry`(run-ledger.ts:411) — 쓰기 전 ①`refuseProductionLedgerWriteInTest`
+ *      가드(테스트 중 운영 원장 쓰기 차단) ② `mkdirSync(dir, { recursive: true })` 순서를 그대로 따른다.
+ *      «run-ledger 줄 하나»가 아니라 «JSON 파일 하나»이지만 쓰기 관문·디렉터리 보증은 같아야 한다.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { refuseProductionLedgerWriteInTest } from '../harness/ledger-write-guard.js';
+import { normalizeRunId } from '../harness/harness-space.js';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+
+/** 판 번호 — 묶음 필드 구성이 바뀌면 이 값을 올리고 읽는 쪽은 판을 검사한다. */
+export const CHECKPOINT_SCHEMA_VERSION = 1;
+
+/** 판 번호가 문자열 표면(직렬화된 JSON 안)에 남는 형태. */
+export const CHECKPOINT_SCHEMA_ID = 'run-checkpoint/v1';
+
+/** 라운드 카드 — 조립 시점에 판을 정하지 않는다(원문이 카드의 필드를 정하지 않았다). */
+export type CheckpointRoundCard = Record<string, unknown>;
+
+/** 미배달 감독 지시 한 줄 — 조립자가 주는 문면 그대로. */
+export type UndeliveredSupervisorDirective = string;
+
+/**
+ * run-checkpoint/v1 묶음 — 전 필드의 원문 명세:
+ * runId · 골 문면(goalText) · 판정 상태(verdictStatus) · salvage 가지 sha(salvageBranchSha) ·
+ * 세션 대화 기록(sessionTranscript) · 라운드 카드(roundCards) · EVIDENCE/RESULT(evidenceResult) ·
+ * 미배달 감독 지시(undeliveredSupervisorDirectives) · 자식 모델(childModel) · 쓴 토큰(tokensUsed) ·
+ * sha256(«전 필드 포함» — sha256 자기 자신만 제외한 나머지 전 필드의 정규화 직렬화에 걸친다).
+ */
+export interface RunCheckpointBundle {
+  /** 판이자 종류 표지 — 항상 `${CHECKPOINT_SCHEMA_ID}`. */
+  schema: typeof CHECKPOINT_SCHEMA_ID;
+  /** 판 번호(정수) — CHECKPOINT_SCHEMA_VERSION 과 같다. */
+  schemaVersion: typeof CHECKPOINT_SCHEMA_VERSION;
+  runId: string;
+  goalText: string;
+  verdictStatus: string;
+  /** 없으면 null — «모름»과 «없음»을 나눈다. */
+  salvageBranchSha: string | null;
+  /** null = «미확인»(조립자가 주지 않음) — 빈 문자열(«실제로 비어 있음»)과 구별한다. */
+  sessionTranscript: string | null;
+  /** null = «미확인» — 빈 배열(«카드 0장»)과 구별한다. */
+  roundCards: readonly CheckpointRoundCard[] | null;
+  /** null = «미확인» — 빈 문자열과 구별한다. */
+  evidenceResult: string | null;
+  /** null = «미확인» — 빈 배열(«미배달 지시 0건»)과 구별한다. */
+  undeliveredSupervisorDirectives: readonly UndeliveredSupervisorDirective[] | null;
+  childModel: string | null;
+  tokensUsed: number | null;
+  /** sha256 — 자기를 제외한 전 필드 정규화 직렬화에 대한 sha256 hex. */
+  sha256: string;
+  recordedAt: string;
+}
+
+/** 조립 재료 — run 사실 원형. `buildCheckpointBundle` 이 여기서 묶음을 만든다. */
+export interface RunCheckpointFacts {
+  runId: string;
+  goalText: string;
+  verdictStatus: string;
+  salvageBranchSha?: string | null;
+  sessionTranscript?: string | null;
+  roundCards?: readonly CheckpointRoundCard[] | null;
+  evidenceResult?: string | null;
+  undeliveredSupervisorDirectives?: readonly UndeliveredSupervisorDirective[] | null;
+  childModel?: string | null;
+  tokensUsed?: number | null;
+  recordedAt?: string;
+}
+
+/** 정렬된 키 직렬화 — 입력은 이미 «JSON 값»(toJSON·undefined·NaN 이 풀린 뒤)이어야 한다. */
+function sortedJson(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map((item) => sortedJson(item)).join(',')}]`;
+  const entries = Object.entries(value as Record<string, unknown>)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${sortedJson(v)}`).join(',')}}`;
+}
+
+/**
+ * 객체 키를 «정렬된» 안정 직렬화로 — 같은 값이면 같은 문자열(sha256 재현성).
+ * ⭐ 해시와 저장이 «같은 직렬화»를 보도록 먼저 `JSON.stringify` 의미론(toJSON·Date→ISO ·
+ *    배열 속 undefined→null · 객체 속 undefined 제거 · NaN→null)으로 한 번 풀고 키만 정렬한다.
+ *    그래야 `writeCheckpoint` 가 쓴 파일을 `readCheckpoint` 가 다시 해시해도 같은 값이 나온다.
+ */
+function canonicalJson(value: unknown): string {
+  const json = JSON.stringify(value);
+  if (json === undefined) return 'null';
+  return sortedJson(JSON.parse(json));
+}
+
+/** sha256 조수 — hex 문자열. 묶음의 sha256 필드에 넣는 값과 같은 계산이다. */
+export function sha256Hex(value: unknown): string {
+  return createHash('sha256').update(canonicalJson(value), 'utf8').digest('hex');
+}
+
+/** sha256 자기 자신을 제외한 «전 필드»를 걸치는 다이제스트(원문: 'sha256 전 필드 포함'). */
+export function bundleSha256(bundle: Omit<RunCheckpointBundle, 'sha256'>): string {
+  const { sha256: _omit, ...rest } = bundle as RunCheckpointBundle;
+  return sha256Hex(rest);
+}
+
+const isStringArray = (v: unknown): boolean => Array.isArray(v) && v.every((x) => typeof x === 'string');
+const isNullableString = (v: unknown): boolean => v === null || typeof v === 'string';
+
+/**
+ * 묶음의 판(schema ⊕ schemaVersion)과 필수 필드의 존재·타입을 검증한다 — 쓰기·읽기 공통 관문.
+ * 판 번호는 «지원하는 판»과 정확히 같아야 한다(다른 판을 v1 으로 받아들이지 않는다).
+ */
+export function assertCheckpointShape(value: unknown): asserts value is RunCheckpointBundle {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('invalid checkpoint: not an object');
+  }
+  const b = value as Record<string, unknown>;
+  if (b.schema !== CHECKPOINT_SCHEMA_ID) {
+    throw new Error(`unknown checkpoint schema: ${String(b.schema)}`);
+  }
+  if (b.schemaVersion !== CHECKPOINT_SCHEMA_VERSION) {
+    throw new Error(`unsupported checkpoint schemaVersion: ${String(b.schemaVersion)}`);
+  }
+  const bad: string[] = [];
+  for (const key of ['runId', 'goalText', 'verdictStatus', 'sha256', 'recordedAt']) {
+    if (typeof b[key] !== 'string') bad.push(key);
+  }
+  if (!isNullableString(b.salvageBranchSha)) bad.push('salvageBranchSha');
+  // null = «미확인» 을 받아들인다(빈 값과 다른 값) — 키 자체가 없으면(undefined) 거부한다.
+  if (!isNullableString(b.sessionTranscript)) bad.push('sessionTranscript');
+  if (!isNullableString(b.evidenceResult)) bad.push('evidenceResult');
+  if (!isNullableString(b.childModel)) bad.push('childModel');
+  if (!(b.tokensUsed === null || (typeof b.tokensUsed === 'number' && Number.isFinite(b.tokensUsed)))) {
+    bad.push('tokensUsed');
+  }
+  if (b.roundCards !== null && (!Array.isArray(b.roundCards) || !b.roundCards.every((c) => c !== null && typeof c === 'object' && !Array.isArray(c)))) {
+    bad.push('roundCards');
+  }
+  if (b.undeliveredSupervisorDirectives !== null && !isStringArray(b.undeliveredSupervisorDirectives)) bad.push('undeliveredSupervisorDirectives');
+  if (bad.length > 0) throw new Error(`invalid checkpoint fields: ${bad.join(', ')}`);
+}
+
+/** run 사실에서 run-checkpoint/v1 묶음을 조립한다 — sha256 도 이 안에서 계산해 넣는다. */
+export function buildCheckpointBundle(facts: RunCheckpointFacts): RunCheckpointBundle {
+  const runId = facts.runId;
+  // runLedgerPath 패턴: 정규화는 하지 않고, normalizeRunId 의 «산출 집합»만 받아들인다.
+  if (!runId || runId !== normalizeRunId(runId)) throw new Error(`invalid runId: ${runId}`);
+  const partial: Omit<RunCheckpointBundle, 'sha256'> = {
+    schema: CHECKPOINT_SCHEMA_ID,
+    schemaVersion: CHECKPOINT_SCHEMA_VERSION,
+    runId,
+    goalText: facts.goalText,
+    verdictStatus: facts.verdictStatus,
+    salvageBranchSha: facts.salvageBranchSha ?? null,
+    // 생략 = «미확인»(null) — 빈 값으로 채워 «실제로 비어 있음»으로 위장하지 않는다.
+    sessionTranscript: facts.sessionTranscript ?? null,
+    roundCards: facts.roundCards ?? null,
+    evidenceResult: facts.evidenceResult ?? null,
+    undeliveredSupervisorDirectives: facts.undeliveredSupervisorDirectives ?? null,
+    childModel: facts.childModel ?? null,
+    tokensUsed: facts.tokensUsed ?? null,
+    recordedAt: facts.recordedAt ?? new Date().toISOString(),
+  };
+  // 저장될 꼴(JSON 값)로 한 번 풀어, 메모리 묶음 = 파일에서 읽은 묶음이 되게 한다(Date→ISO 등).
+  const stored = JSON.parse(JSON.stringify(partial)) as Omit<RunCheckpointBundle, 'sha256'>;
+  return { ...stored, sha256: bundleSha256(stored) };
+}
+
+/** runLedgerDir 패턴 — state root 아래 «자기 저장소 이름» 디렉터리. */
+export function checkpointDir(stateDir?: string): string {
+  return join(stateDir ?? elanousStateRoot(), 'run-checkpoint');
+}
+
+/** runLedgerPath 패턴 — runId 검증(정규화 아님) 후 경로 결정. */
+export function checkpointPath(runId: string, dir = checkpointDir()): string {
+  if (runId !== normalizeRunId(runId) || !runId) throw new Error(`invalid runId: ${runId}`);
+  return join(dir, `${runId}.checkpoint.json`);
+}
+
+/**
+ * 묶음을 디스크에 기록한다(appendRunLedgerEntry 의 쓰기 관문·디렉터리 보증을 따른다).
+ * 반환값은 기록한 파일 경로 — 형제 조각의 원장 이벤트 'checkpoint' {bundleRef} 가 여기 담긴다.
+ *
+ * ⛔ 스냅샷은 «최신 하나»라 덮어쓰기가 곧 이전 상태의 소실이다. 그래서
+ *    ① 쓰기 «전»에 판·sha256 을 검증해 무효 묶음이면 던지고 기존 파일을 건드리지 않는다.
+ *    ② 임시 파일에 쓴 뒤 rename 으로 원자 교체한다(쓰다 죽어도 반쪽 파일이 남지 않는다).
+ */
+export function writeCheckpoint(bundle: RunCheckpointBundle, dir = checkpointDir()): string {
+  assertCheckpointShape(bundle);
+  const path = checkpointPath(bundle.runId, dir);
+  const body = `${JSON.stringify(bundle, null, 2)}\n`;
+  // 저장될 꼴 그대로를 다시 해시한다 — 읽기 쪽 검증과 같은 입력이다.
+  const expected = bundleSha256(JSON.parse(body) as RunCheckpointBundle);
+  if (bundle.sha256 !== expected) {
+    throw new Error(`checkpoint sha256 mismatch: ${bundle.sha256} != ${expected}`);
+  }
+  if (refuseProductionLedgerWriteInTest(dir, 'run-checkpoint')) return '';
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(tmp, body, 'utf8');
+    renameSync(tmp, path);
+  } catch (error) {
+    rmSync(tmp, { force: true });
+    throw error;
+  }
+  return path;
+}
+
+/** 기록된 묶음을 읽어 sha256 이 전 필드에 대해 아직 성립하는지 검증과 함께 돌려준다. */
+export function readCheckpoint(runId: string, dir = checkpointDir()): RunCheckpointBundle {
+  const raw: unknown = JSON.parse(readFileSync(checkpointPath(runId, dir), 'utf8'));
+  assertCheckpointShape(raw);
+  if (raw.runId !== runId) {
+    throw new Error(`checkpoint runId mismatch: requested ${runId}, file has ${raw.runId}`);
+  }
+  const expected = bundleSha256(raw);
+  if (raw.sha256 !== expected) {
+    throw new Error(`checkpoint sha256 mismatch: ${raw.sha256} != ${expected}`);
+  }
+  return raw;
+}