hanlint 0.0.9 → 0.0.10

package/src/cli/main.js

@@ -10,35 +10,54 @@
  * hanlint rules                 규칙 목록을 부류로 묶어서
  * hanlint explain <규칙>        규칙의 기술서
  * hanlint patterns             문장 틀. --rule 로 그 규칙을 피하는 것만
+ * hanlint primer --preset <종류> 쓰기 전에 읽는 한 장. 켜진 규칙의 고치는 법과 본보기 전후
+ * hanlint hook                  Claude Code가 쓴 마크다운을 같은 턴에 비차단 검사
  * hanlint baseline 글들/        지금 있는 지적을 잠근다. 그다음부터 새것만 막힌다
  * hanlint baseline 글들/        지금 있는 지적을 잠근다. 그다음부터 새것만 막힌다
  * hanlint doctor                설정과 꺼진 규칙
  * hanlint init                  주석 달린 hanlint.toml. --output 과 --preset blog|report|docs
+ * hanlint contract init 글.md   원문에서 최소 Reader Contract 초안
  * ```
  * audit, guard, arena, blueprint, evidence, entailment 같은 확장 명령은 파이썬 패키지에 있다.
  */
 import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 
-import { fingerprint, lintText, ruleDoc, ruleNames, ruleSummary, version } from "../index.js";
+import {
+  Patch,
+  check,
+  contractFromText,
+  contractFromTextV2,
+  fingerprint,
+  lintText,
+  parseContract,
+  renderCheck,
+  ruleDoc,
+  ruleNames,
+  ruleSummary,
+  verifyPatch,
+  version,
+} from "../index.js";
 import { Baseline, build as buildBaseline, DEFAULT_NAME as DEFAULT_BASELINE, load as loadBaseline, prune as pruneBaseline, render as renderBaseline } from "../baseline/store.js";
 import { loadConfig } from "../config/loadConfig.js";
-import { DEFAULT_PRESET, defaultConfig, offRules, PRESET_NAMES, PRESETS } from "../config/settings.js";
+import { defaultConfig, offRules, PRESET_NAMES, PRESETS } from "../config/settings.js";
 import { applyFixes } from "../edit/applyFixes.js";
 import { exemplarFor } from "../data/exemplars.js";
 import { patterns, patternsAvoiding } from "../data/patterns.js";
 import { HAPNIDA, REGISTERS } from "../analysis/grammar/index.js";
-import { CATEGORY_TITLES, MECHANISMS, ruleCategory, ruleMechanism, runAll } from "../rules/registry.js";
+import { CATEGORY_TITLES, MECHANISMS, ruleCategory, ruleFix, ruleMechanism, runAll } from "../rules/registry.js";
 import { MARKDOWN, SKIPPED_FOLDERS, markdownUnder } from "./walk.js";
 import { welcome } from "./welcome.js";
+import { rootHelp } from "./help.js";
 import { renderCompact } from "../report/compactReport.js";
 import { LAYERS, renderFingerprintJson } from "../report/fingerprintJson.js";
 import { renderGithub } from "../report/githubReport.js";
 import { renderJson } from "../report/jsonReport.js";
 import { renderText } from "../report/textReport.js";
+import { renderWritingSpec, writingSpec } from "../report/writingSpec.js";
 import { exemplarInRegister, patternInRegister } from "../report/registerMatch.js";
 
-const COMMANDS = ["lint", "fix", "print", "rules", "explain", "patterns", "baseline", "doctor", "init"];
+const COMMANDS = ["lint", "fix", "print", "rules", "explain", "patterns", "primer", "spec", "hook", "baseline", "doctor", "init", "contract", "check", "verify-patch"];
 const PYTHON_ONLY = [
   "audit",
   "map",
@@ -82,23 +101,7 @@ const THRESHOLD_FIELDS = [
 ];
 const FLOAT_FIELDS = new Set(["headingUniformRatio", "factListMaxMeanLength"]);
 
-const USAGE = `사용법: hanlint 글.md [다른.md ...] [--format text|compact|json|github] [--severity all|error|notice] [--errors-only]
-                [--config 파일] [--preset blog|report|docs] [--disable 규칙] [--baseline [파일]] [--output 파일] [--quiet]
-                [--path 이름 (stdin 의 이름)]
-        hanlint fix 글.md [--dry-run]
-        hanlint print 글.md [--layer all|sentences|paragraphs|sections|document]
-        hanlint rules [--names]
-        hanlint explain <규칙>
-        hanlint patterns [--rule 규칙]
-        hanlint baseline 글들/ [--prune] [--output 파일]
-        hanlint doctor
-        hanlint init [--output hanlint.toml] [--preset blog|report|docs] [--force]
-        hanlint --version
-
-파일 자리에 폴더를 주면 그 아래 마크다운을 전부 검사한다 (점으로 시작하는 폴더와 node_modules 는 건너뛴다).
-인자가 없으면 첫 화면이 나온다.
-한국어 글에서 반복되는 결함을 결정적으로 잡는다. 종료 코드는 0 (지적 없음), 1 (error 지적), 2 (파일이나 설정 문제).
-${PYTHON_ONLY.join(", ")} 는 파이썬 패키지 (pip install hanlint) 에 있다.`;
+const USAGE = rootHelp();
 
 /** @type {Record<string, "value" | "list" | "flag">} */
 const OPTION_KINDS = {
@@ -116,9 +119,15 @@ const OPTION_KINDS = {
   "--dry-run": "flag",
   "--names": "flag",
   "--force": "flag",
+  "--reply": "flag",
+  "--reader": "value",
+  "--goal": "value",
+  "--outline": "value",
+  "--fact": "list",
   "--preset": "value",
   "--rule": "value",
   "--register": "value",
+  "--chars": "value",
   "--baseline": "optional",
   "--prune": "flag",
 };
@@ -224,8 +233,8 @@ function checkDisabled(config) {
 }
 
 /** @param {Record<string, string | string[] | boolean>} options @param {string[]} paths */
-function configFrom(options, paths) {
-  const config = loadConfig(/** @type {string | undefined} */ (options["--config"]) ?? null, startFolder(paths));
+function configFrom(options, paths, start = null) {
+  const config = loadConfig(/** @type {string | undefined} */ (options["--config"]) ?? null, start ?? startFolder(paths));
   if (options["--preset"]) config.preset = choose(/** @type {string} */ (options["--preset"]), PRESET_NAMES, "--preset");
   for (const rule of /** @type {string[]} */ (options["--disable"] ?? [])) config.disable.add(rule);
   if (options["--profile"]) config.profile = /** @type {string} */ (options["--profile"]);
@@ -242,11 +251,10 @@ function configLabel(config) {
   return label.split(sep).join("/");
 }
 
-/** 설정 출처와 지금 도는 프리셋. 기본 프리셋이면 이름을 빼서 줄이 길어지지 않게 한다.
- * @param {import("../config/settings.js").Config} config */
+/** 설정 출처와 지금 도는 프리셋. @param {import("../config/settings.js").Config} config */
 function header(config) {
   const where = configLabel(config);
-  return config.preset === DEFAULT_PRESET ? `설정: ${where}` : `설정: ${where}, 프리셋 ${config.preset}`;
+  return `설정: ${where}, 프리셋 ${config.preset}`;
 }
 
 /** @param {Map<string, import("../rules/finding.js").Finding[]>} results */
@@ -382,6 +390,73 @@ function runBaseline(args) {
   return 0;
 }
 
+/** @param {string} path */
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch (error) {
+    if (error instanceof SyntaxError) throw new Error(`${path} JSON을 읽지 못했다: ${error.message}`);
+    throw error;
+  }
+}
+
+/** @param {string[]} args */
+function runCheck(args) {
+  const { options, positionals } = parseArgs(args);
+  if (positionals.length !== 2) throw new UsageError("Reader Contract JSON과 검사할 마크다운 파일이 필요하다");
+  const format = choose(/** @type {string} */ (options["--format"] ?? "json"), ["json", "text"], "--format");
+  const [contractPath, path] = positionals;
+  const contract = parseContract(readJson(contractPath));
+  const config = configFrom(options, [path]);
+  const result = check(readOne(path), contract, config, path);
+  const rendered = format === "text" ? renderCheck(result) : JSON.stringify(result.asDict(), null, 2);
+  emit(rendered, /** @type {string | undefined} */ (options["--output"]));
+  return result.violationCount === 0 ? 0 : 1;
+}
+
+/** @param {string[]} args */
+function runContract(args) {
+  const { options, positionals } = parseArgs(args);
+  if (positionals.length !== 2 || positionals[0] !== "init") {
+    throw new UsageError("contract init과 계약 초안을 만들 마크다운 파일이 필요하다");
+  }
+  const reader = options["--reader"];
+  const goal = options["--goal"];
+  if (typeof reader !== "string" || typeof goal !== "string") {
+    throw new UsageError("contract init에는 --reader와 --goal이 필요하다");
+  }
+  const output = options["--output"];
+  if (typeof output === "string" && existsSync(output) && !options["--force"]) {
+    throw new Error(`${output} 가 이미 있다. 덮어쓰려면 --force`);
+  }
+  const outline = options["--outline"];
+  const facts = /** @type {string[]} */ (options["--fact"] ?? []);
+  let contract;
+  if (outline !== undefined) {
+    const selected = choose(/** @type {string} */ (outline), ["h1", "h2", "h3", "h4", "h5", "h6"], "--outline");
+    contract = contractFromTextV2(readOne(positionals[1]), reader, goal, Number(selected.slice(1)), facts);
+  } else {
+    if (facts.length) throw new UsageError("--fact는 --outline과 함께 version 2 계약에서 쓴다");
+    contract = contractFromText(readOne(positionals[1]), reader, goal);
+  }
+  emit(JSON.stringify(contract.asDict(), null, 2), typeof output === "string" ? output : undefined);
+  return 0;
+}
+
+/** @param {string[]} args */
+function runVerifyPatch(args) {
+  const { options, positionals } = parseArgs(args);
+  if (positionals.length !== 3) throw new UsageError("Reader Contract JSON, 수정 전 마크다운, Patch JSON이 필요하다");
+  choose(/** @type {string} */ (options["--format"] ?? "json"), ["json"], "--format");
+  const [contractPath, path, patchPath] = positionals;
+  const contract = parseContract(readJson(contractPath));
+  const patch = Patch.fromMapping(readJson(patchPath));
+  const config = configFrom(options, [path]);
+  const result = verifyPatch(readOne(path), patch, contract, config, path);
+  emit(JSON.stringify(result.asDict(), null, 2), /** @type {string | undefined} */ (options["--output"]));
+  return result.verified ? 0 : 1;
+}
+
 /** @param {string[]} args */
 function runLint(args) {
   const { options, positionals } = parseArgs(args);
@@ -514,7 +589,8 @@ function runRules(args) {
   }
   const config = configFrom(options, []);
   const off = new Set(offRules(config));
-  if (options["--format"] === "json") {
+  const format = choose(/** @type {string} */ (options["--format"] ?? "text"), ["text", "json"], "--format");
+  if (format === "json") {
     const rules = names.map((name) => {
       const exemplar = exemplarFor(name, config.preset, config.exemplars);
       /** @type {Record<string, unknown>} */
@@ -646,6 +722,136 @@ function runPatterns(args) {
   return 0;
 }
 
+/** 여러 줄을 한 줄로. 줄바꿈은 ¶ 다. 파이썬 cli/commands/primer.py 의 flat 과 같다. @param {string} text */
+function flat(text) {
+  return text
+    .split("\n")
+    .map((line) => line.trim().split(/\s+/).filter(Boolean).join(" "))
+    .filter(Boolean)
+    .join(" ¶ ");
+}
+
+/**
+ * 설정에서 켜진 규칙마다 항목 하나. 부류 순서, 그 안은 이름 순서. 파이썬 primerEntries 와 같다.
+ * @param {import("../config/settings.js").Config} config @param {string} register
+ */
+function primerEntries(config, register) {
+  const off = new Set(offRules(config));
+  const entries = [];
+  for (const category of Object.keys(CATEGORY_TITLES)) {
+    for (const name of ruleNames()) {
+      if (ruleCategory(name) !== category || off.has(name)) continue;
+      const exemplar = exemplarFor(name, config.preset, config.exemplars);
+      if (!exemplar) throw new Error(`본보기가 없는 규칙: ${name}`);
+      const shown = exemplarInRegister(exemplar, register);
+      entries.push({ rule: name, category, fix: ruleFix(name), before: shown.before, after: shown.after });
+    }
+  }
+  return entries;
+}
+
+/** 사람과 AI 가 읽는 한 장. 파이썬 renderPrimer 와 글자 단위로 같다. @param {ReturnType<typeof primerEntries>} entries @param {string} preset @param {string} register */
+function renderPrimer(entries, preset, register) {
+  const lines = [
+    `hanlint primer  ${preset} 종류, ${register}체, 규칙 ${entries.length}개. 줄마다 규칙 이름, 고치는 법, 전 (그 규칙에 잡히는 글), 후 (같은 뜻으로 통과하는 글) 순서다. 본보기의 줄바꿈은 ¶ 다`,
+  ];
+  for (const [category, title] of Object.entries(CATEGORY_TITLES)) {
+    const inside = entries.filter((entry) => entry.category === category);
+    if (!inside.length) continue;
+    lines.push("", `${title} (${inside.length})`);
+    for (const entry of inside) lines.push(`${entry.rule}  ${entry.fix}  전: ${flat(entry.before)}  후: ${flat(entry.after)}`);
+  }
+  lines.push("", "후는 전부 hanlint 를 error 0 으로 통과한다 (게이트가 확인한다). 규칙 하나를 깊게 보려면 hanlint explain <규칙>");
+  return lines.join("\n");
+}
+
+/** @param {string[]} args */
+function runPrimer(args) {
+  const { options } = parseArgs(args);
+  const config = configFrom(options, []);
+  const register = choose(/** @type {string} */ (options["--register"] ?? HAPNIDA), REGISTERS, "--register");
+  const entries = primerEntries(config, register);
+  const output = /** @type {string | undefined} */ (options["--output"]);
+  const format = choose(/** @type {string} */ (options["--format"] ?? "text"), ["text", "json"], "--format");
+  if (format === "json") {
+    emit(JSON.stringify({ version: 1, preset: config.preset, register, rules: entries }, null, 2), output);
+    return 0;
+  }
+  emit(renderPrimer(entries, config.preset, register), output);
+  return 0;
+}
+
+/** @param {string[]} args */
+function runSpec(args) {
+  const { options } = parseArgs(args);
+  const config = configFrom(options, []);
+  const register = choose(/** @type {string} */ (options["--register"] ?? HAPNIDA), REGISTERS, "--register");
+  let targetChars = null;
+  if (options["--chars"] !== undefined) {
+    const raw = /** @type {string} */ (options["--chars"]);
+    targetChars = Number(raw);
+    if (!Number.isInteger(targetChars) || targetChars <= 0) throw new UsageError(`--chars 는 1 이상의 정수다: ${raw}`);
+  }
+  const result = writingSpec(config, register, targetChars);
+  const output = /** @type {string | undefined} */ (options["--output"]);
+  const format = choose(/** @type {string} */ (options["--format"] ?? "text"), ["text", "json"], "--format");
+  emit(format === "json" ? JSON.stringify(result, null, 2) : renderWritingSpec(result), output);
+  return 0;
+}
+
+/** Claude Code가 다음 모델 요청에 넣는 비차단 Finding 문맥. */
+function hookContext(eventName, name, findings) {
+  const where = eventName === "Stop" ? "마지막 답변" : "방금 쓴 마크다운";
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: eventName,
+      additionalContext: `hanlint가 ${where}에서 센 Finding입니다.\n${renderCompact(name, findings)}`,
+    },
+  });
+}
+
+/** 명령 훅 JSON을 stdin에서 읽어 저장 파일이나 마지막 답변을 검사한다. 언제나 종료 코드 0이다. @param {string[]} args */
+function runHook(args) {
+  try {
+    const { options, positionals } = parseArgs(args);
+    if (positionals.length) return 0;
+    const payload = JSON.parse(readFileSync(0, "utf-8"));
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) return 0;
+    let eventName;
+    let name;
+    let findings;
+    if (options["--reply"]) {
+      if (payload.hook_event_name !== "Stop" || payload.stop_hook_active === true) return 0;
+      const text = payload.last_assistant_message;
+      if (typeof text !== "string" || !text.trim()) return 0;
+      const start = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd();
+      const config = configFrom(options, [], start);
+      config.preset = "chat";
+      eventName = "Stop";
+      name = "<assistant>";
+      findings = lintText(text, config, name);
+    } else {
+      if (payload.hook_event_name !== "PostToolUse" || !["Write", "Edit"].includes(payload.tool_name)) return 0;
+      const rawPath = payload.tool_input?.file_path;
+      if (typeof rawPath !== "string" || !rawPath || !MARKDOWN.includes(extname(rawPath).toLowerCase())) return 0;
+      try {
+        if (!statSync(rawPath).isFile()) return 0;
+      } catch {
+        return 0;
+      }
+      const config = configFrom(options, [rawPath]);
+      eventName = "PostToolUse";
+      name = rawPath;
+      findings = lintText(readFileSync(rawPath, "utf-8"), config, name);
+      if (config.baseline) findings = loadBaseline(config.baseline).keep(name, findings);
+    }
+    if (findings.length) process.stdout.write(`${hookContext(eventName, name, findings)}\n`);
+  } catch {
+    return 0;
+  }
+  return 0;
+}
+
 /** 잠근 지적이 몇 건인지. baseline 이 빚을 감추는 자리가 되지 않게 늘 보인다. @param {import("../config/settings.js").Config} config */
 function baselineState(config) {
   if (!config.baseline) return "없다 (hanlint baseline 글들/ 로 지금 지적을 잠근다)";
@@ -730,6 +936,7 @@ export function renderInit(preset = "blog") {
     "",
     "# 표면 치환이 바꾸면 안 되는 한국어 고유명사와 프로젝트 용어. 수치와 라틴 식별자는 자동으로 보호한다",
     '# protectedTerms = ["한린트", "김민지"]',
+    '# enforceStyle = ["noQuestion", "nounPile"]  # 선택한 문체 신호만 error로 강제한다',
     "",
     "# 사람이 승인한 프로젝트 본보기. 같은 규칙과 프리셋의 내장 본보기를 덮어쓴다",
     "# [[exemplars]]",
@@ -793,11 +1000,17 @@ function dispatch(argv) {
     throw new Error(`${command} 는 파이썬 패키지에 있다 (pip install hanlint). npm 은 ${COMMANDS.join(", ")} 을 제공한다`);
   }
   if (command === "lint") return runLint(rest);
+  if (command === "contract") return runContract(rest);
+  if (command === "check") return runCheck(rest);
+  if (command === "verify-patch") return runVerifyPatch(rest);
   if (command === "fix") return runFix(rest);
   if (command === "print") return runPrint(rest);
   if (command === "rules") return runRules(rest);
   if (command === "explain") return runExplain(rest);
   if (command === "patterns") return runPatterns(rest);
+  if (command === "primer") return runPrimer(rest);
+  if (command === "spec") return runSpec(rest);
+  if (command === "hook") return runHook(rest);
   if (command === "baseline") return runBaseline(rest);
   if (command === "doctor") return runDoctor(rest);
   return runInit(rest);

package/src/config/patch.js

@@ -0,0 +1,48 @@
+// @ts-check
+/** 이유가 붙은 정확 국소 Patch 입력 계약. */
+import { createHash } from "node:crypto";
+
+/** @param {unknown} value @param {string} where */
+function checkedString(value, where) {
+  if (typeof value !== "string" || !value || value !== value.trim()) {
+    throw new Error(`${where} 는 양끝 공백 없는 문자열이다`);
+  }
+  if (value !== value.normalize("NFC")) throw new Error(`${where} 는 NFC 문자열이어야 한다`);
+  return value;
+}
+
+export class Patch {
+  /** @param {string} reason @param {string} before @param {string} after */
+  constructor(reason, before, after) {
+    this.reason = checkedString(reason, "reason");
+    this.before = checkedString(before, "before");
+    this.after = checkedString(after, "after");
+    if (this.before === this.after) throw new Error("patch before 와 after 는 달라야 한다");
+    Object.freeze(this);
+  }
+
+  /** @param {unknown} raw */
+  static fromMapping(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("patch 는 JSON 객체다");
+    const data = /** @type {Record<string, unknown>} */ (raw);
+    const expected = ["reason", "before", "after"];
+    const unknown = Object.keys(data).filter((key) => !expected.includes(key)).sort();
+    const missing = expected.filter((key) => !(key in data)).sort();
+    if (unknown.length) throw new Error(`patch 의 모르는 키: ${unknown.join(", ")}`);
+    if (missing.length) throw new Error(`patch 의 빠진 키: ${missing.join(", ")}`);
+    return new Patch(
+      /** @type {string} */ (data.reason),
+      /** @type {string} */ (data.before),
+      /** @type {string} */ (data.after),
+    );
+  }
+
+  get digest() {
+    const encoded = JSON.stringify({ after: this.after, before: this.before, reason: this.reason });
+    return createHash("sha256").update(encoded, "utf8").digest("hex");
+  }
+
+  asDict() {
+    return { reason: this.reason, before: this.before, after: this.after };
+  }
+}

package/src/config/readerContract.js

@@ -0,0 +1,245 @@
+// @ts-check
+/** 모델과 실행 환경에 독립적인 최소 Reader Contract와 정확 Patch. */
+import { createHash } from "node:crypto";
+
+export const CONTRACT_VERSION = 1;
+export const LATEST_CONTRACT_VERSION = 2;
+export const CONTRACT_VERSIONS = Object.freeze([CONTRACT_VERSION, LATEST_CONTRACT_VERSION]);
+
+/** @param {unknown} value @param {string} where */
+function checkedString(value, where) {
+  if (typeof value !== "string" || !value || value !== value.trim()) {
+    throw new Error(`${where} 는 양끝 공백 없는 문자열이다`);
+  }
+  if (value !== value.normalize("NFC")) throw new Error(`${where} 는 NFC 문자열이어야 한다`);
+  return value;
+}
+
+/** @param {unknown} value @param {string} where @param {boolean} [allowEmpty] */
+function checkedStrings(value, where, allowEmpty = false) {
+  if (!Array.isArray(value) || (!allowEmpty && !value.length)) {
+    throw new Error(`${where} 는 ${allowEmpty ? "문자열 배열" : "비지 않은 문자열 배열"}이다`);
+  }
+  const found = value.map((item, index) => checkedString(item, `${where} ${index + 1}번째`));
+  if (new Set(found).size !== found.length) throw new Error(`${where} 에 같은 값이 두 번 있다`);
+  return found;
+}
+
+/** 파이썬 문자열 순서와 같은 코드 포인트 순서. @param {string} left @param {string} right */
+function compareText(left, right) {
+  const leftPoints = [...left].map((value) => /** @type {number} */ (value.codePointAt(0)));
+  const rightPoints = [...right].map((value) => /** @type {number} */ (value.codePointAt(0)));
+  const limit = Math.min(leftPoints.length, rightPoints.length);
+  for (let index = 0; index < limit; index += 1) {
+    if (leftPoints[index] !== rightPoints[index]) return leftPoints[index] - rightPoints[index];
+  }
+  return leftPoints.length - rightPoints.length;
+}
+
+/** @param {string} text */
+function digest(text) {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+export class Contract {
+  /** @param {string} reader @param {string} goal @param {string[]} facts @param {number} [version] */
+  constructor(reader, goal, facts, version = CONTRACT_VERSION) {
+    if (!Number.isInteger(version) || version !== CONTRACT_VERSION) {
+      throw new Error(`reader contract version 은 ${CONTRACT_VERSION}이다: ${version}`);
+    }
+    this.reader = checkedString(reader, "reader");
+    this.goal = checkedString(goal, "goal");
+    this.facts = Object.freeze(checkedStrings(facts, "facts"));
+    this.version = version;
+    Object.freeze(this);
+  }
+
+  /** @param {unknown} raw */
+  static fromMapping(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("reader contract 는 JSON 객체다");
+    const data = /** @type {Record<string, unknown>} */ (raw);
+    const expected = ["version", "reader", "goal", "facts"];
+    const unknown = Object.keys(data).filter((key) => !expected.includes(key)).sort();
+    const missing = expected.filter((key) => !(key in data)).sort();
+    if (unknown.length) throw new Error(`reader contract 의 모르는 키: ${unknown.join(", ")}`);
+    if (missing.length) throw new Error(`reader contract 의 빠진 키: ${missing.join(", ")}`);
+    return new Contract(
+      /** @type {string} */ (data.reader),
+      /** @type {string} */ (data.goal),
+      /** @type {string[]} */ (data.facts),
+      /** @type {number} */ (data.version),
+    );
+  }
+
+  get text() {
+    return [this.reader, this.goal, ...this.facts].join("\n");
+  }
+
+  get digest() {
+    return digest(JSON.stringify({ facts: this.facts, goal: this.goal, reader: this.reader, version: this.version }));
+  }
+
+  asDict() {
+    return { version: this.version, reader: this.reader, goal: this.goal, facts: [...this.facts] };
+  }
+}
+
+export class ProtectedSurface {
+  /** @param {string[]} [numbers] @param {string[]} [urls] @param {string[]} [code] @param {string[]} [links] */
+  constructor(numbers = [], urls = [], code = [], links = []) {
+    this.numbers = Object.freeze(checkedStrings(numbers, "surface.numbers", true).sort(compareText));
+    this.urls = Object.freeze(checkedStrings(urls, "surface.urls", true).sort(compareText));
+    this.code = Object.freeze(checkedStrings(code, "surface.code", true).sort(compareText));
+    this.links = Object.freeze(checkedStrings(links, "surface.links", true).sort(compareText));
+    Object.freeze(this);
+  }
+
+  /** @param {unknown} raw */
+  static fromMapping(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("surface 는 JSON 객체다");
+    const data = /** @type {Record<string, unknown>} */ (raw);
+    const expected = ["numbers", "urls", "code", "links"];
+    const unknown = Object.keys(data).filter((key) => !expected.includes(key)).sort();
+    const missing = expected.filter((key) => !(key in data)).sort();
+    if (unknown.length) throw new Error(`surface 의 모르는 키: ${unknown.join(", ")}`);
+    if (missing.length) throw new Error(`surface 의 빠진 키: ${missing.join(", ")}`);
+    return new ProtectedSurface(
+      /** @type {string[]} */ (data.numbers),
+      /** @type {string[]} */ (data.urls),
+      /** @type {string[]} */ (data.code),
+      /** @type {string[]} */ (data.links),
+    );
+  }
+
+  get text() {
+    return [
+      ...this.numbers,
+      ...this.urls,
+      ...this.code.map((value) => `\`${value}\``),
+      ...this.links.map((value) => `[](${value})`),
+    ].join("\n");
+  }
+
+  asDict() {
+    return { numbers: [...this.numbers], urls: [...this.urls], code: [...this.code], links: [...this.links] };
+  }
+}
+
+export class Outline {
+  /** @param {number} level @param {string[]} headings */
+  constructor(level, headings) {
+    if (!Number.isInteger(level) || level < 1 || level > 6) throw new Error(`outline.level 은 1~6 정수다: ${level}`);
+    this.level = level;
+    this.headings = Object.freeze(checkedStrings(headings, "outline.headings"));
+    Object.freeze(this);
+  }
+
+  /** @param {unknown} raw */
+  static fromMapping(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("outline 은 JSON 객체다");
+    const data = /** @type {Record<string, unknown>} */ (raw);
+    const expected = ["level", "headings"];
+    const unknown = Object.keys(data).filter((key) => !expected.includes(key)).sort();
+    const missing = expected.filter((key) => !(key in data)).sort();
+    if (unknown.length) throw new Error(`outline 의 모르는 키: ${unknown.join(", ")}`);
+    if (missing.length) throw new Error(`outline 의 빠진 키: ${missing.join(", ")}`);
+    return new Outline(/** @type {number} */ (data.level), /** @type {string[]} */ (data.headings));
+  }
+
+  asDict() {
+    return { level: this.level, headings: [...this.headings] };
+  }
+}
+
+export class ContractV2 {
+  /** @param {string} reader @param {string} goal @param {string[]} facts @param {ProtectedSurface | Record<string, unknown>} surface @param {Outline | Record<string, unknown>} outline @param {number} [version] */
+  constructor(reader, goal, facts, surface, outline, version = LATEST_CONTRACT_VERSION, lockedFacts = [], editPolicy = {}) {
+    if (!Number.isInteger(version) || version !== LATEST_CONTRACT_VERSION) {
+      throw new Error(`reader contract version 은 ${LATEST_CONTRACT_VERSION}다: ${version}`);
+    }
+    this.reader = checkedString(reader, "reader");
+    this.goal = checkedString(goal, "goal");
+    this.facts = Object.freeze(checkedStrings(facts, "facts", true));
+    this.surface = surface instanceof ProtectedSurface ? surface : ProtectedSurface.fromMapping(surface);
+    this.outline = outline instanceof Outline ? outline : Outline.fromMapping(outline);
+    this.lockedFacts = Object.freeze(checkedStrings(lockedFacts, "lockedFacts", true));
+    if (this.lockedFacts.some((fact) => !this.facts.includes(fact))) throw new Error("lockedFacts must select approved facts");
+    if (!editPolicy || typeof editPolicy !== "object" || Array.isArray(editPolicy)) throw new Error("editPolicy must be an object");
+    this.editPolicy = Object.freeze(Object.fromEntries(Object.entries(editPolicy).sort(([a], [b]) => compareText(a, b)).map(([rule, limits]) => {
+      if (!rule || rule !== rule.trim()) throw new Error("editPolicy requires rule names");
+      if (!limits || typeof limits !== "object" || Array.isArray(limits) || Object.keys(limits).sort().join(",") !== "maxChars,maxLines") {
+        throw new Error("editPolicy requires maxChars and maxLines");
+      }
+      if (Object.values(limits).some((n) => !Number.isInteger(n) || n < 1)) throw new Error("editPolicy limits must be positive integers");
+      return [rule, Object.freeze({maxChars: limits.maxChars, maxLines: limits.maxLines})];
+    })));
+    this.version = version;
+    Object.freeze(this);
+  }
+
+  /** @param {unknown} raw */
+  static fromMapping(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("reader contract 는 JSON 객체다");
+    const data = /** @type {Record<string, unknown>} */ (raw);
+    const expected = ["version", "reader", "goal", "facts", "surface", "outline"];
+    const unknown = Object.keys(data).filter((key) => !expected.includes(key) && !["lockedFacts", "editPolicy"].includes(key)).sort();
+    const missing = expected.filter((key) => !(key in data)).sort();
+    if (unknown.length) throw new Error(`reader contract 의 모르는 키: ${unknown.join(", ")}`);
+    if (missing.length) throw new Error(`reader contract 의 빠진 키: ${missing.join(", ")}`);
+    return new ContractV2(
+      /** @type {string} */ (data.reader),
+      /** @type {string} */ (data.goal),
+      /** @type {string[]} */ (data.facts),
+      /** @type {Record<string, unknown>} */ (data.surface),
+      /** @type {Record<string, unknown>} */ (data.outline),
+      /** @type {number} */ (data.version),
+      Object.hasOwn(data, "lockedFacts") ? data.lockedFacts : [],
+      Object.hasOwn(data, "editPolicy") ? data.editPolicy : {},
+    );
+  }
+
+  get text() {
+    return [this.reader, this.goal, ...this.facts, this.surface.text].filter(Boolean).join("\n");
+  }
+
+  get digest() {
+    const encoded = {
+      ...(Object.keys(this.editPolicy).length ? {editPolicy: this.editPolicy} : {}),
+      facts: this.facts,
+      goal: this.goal,
+      ...(this.lockedFacts.length ? {lockedFacts: this.lockedFacts} : {}),
+      outline: { headings: this.outline.headings, level: this.outline.level },
+      reader: this.reader,
+      surface: {
+        code: this.surface.code,
+        links: this.surface.links,
+        numbers: this.surface.numbers,
+        urls: this.surface.urls,
+      },
+      version: this.version,
+    };
+    return digest(JSON.stringify(encoded));
+  }
+
+  asDict() {
+    return {
+      version: this.version,
+      reader: this.reader,
+      goal: this.goal,
+      facts: [...this.facts],
+      surface: this.surface.asDict(),
+      outline: this.outline.asDict(),
+      ...(this.lockedFacts.length ? {lockedFacts: [...this.lockedFacts]} : {}),
+      ...(Object.keys(this.editPolicy).length ? {editPolicy: this.editPolicy} : {}),
+    };
+  }
+}
+
+/** @param {unknown} raw */
+export function parseContract(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("reader contract 는 JSON 객체다");
+  const version = /** @type {Record<string, unknown>} */ (raw).version;
+  if (version === CONTRACT_VERSION) return Contract.fromMapping(raw);
+  if (version === LATEST_CONTRACT_VERSION) return ContractV2.fromMapping(raw);
+  throw new Error(`reader contract version 은 ${CONTRACT_VERSIONS.join(",")} 가운데 하나다: ${version}`);
+}