@zwbigi/ink-xy 0.1.2 → 0.1.4

package/inkos/packages/core/src/utils/hook-health.ts

@@ -0,0 +1,189 @@
+import type { AuditIssue } from "../agents/continuity.js";
+import type { HookRecord, RuntimeStateDelta } from "../models/runtime-state.js";
+import { classifyHookDisposition, collectStaleHookDebt } from "./hook-governance.js";
+import { describeHookLifecycle, localizeHookPayoffTiming } from "./hook-lifecycle.js";
+import { HOOK_HEALTH_DEFAULTS } from "./hook-policy.js";
+
+export function analyzeHookHealth(params: {
+  readonly language: "zh" | "en";
+  readonly chapterNumber: number;
+  readonly targetChapters?: number;
+  readonly hooks: ReadonlyArray<HookRecord>;
+  readonly delta?: Pick<RuntimeStateDelta, "chapter" | "hookOps">;
+  readonly existingHookIds?: ReadonlyArray<string>;
+  readonly maxActiveHooks?: number;
+  readonly staleAfterChapters?: number;
+  readonly noAdvanceWindow?: number;
+  readonly newHookBurstThreshold?: number;
+}): AuditIssue[] {
+  const maxActiveHooks = params.maxActiveHooks ?? HOOK_HEALTH_DEFAULTS.maxActiveHooks;
+  const staleAfterChapters = params.staleAfterChapters ?? HOOK_HEALTH_DEFAULTS.staleAfterChapters;
+  const noAdvanceWindow = params.noAdvanceWindow ?? HOOK_HEALTH_DEFAULTS.noAdvanceWindow;
+  const newHookBurstThreshold = params.newHookBurstThreshold ?? HOOK_HEALTH_DEFAULTS.newHookBurstThreshold;
+  const issues: AuditIssue[] = [];
+
+  const activeHooks = params.hooks.filter((hook) => hook.status !== "resolved");
+  const lifecycleEntries = activeHooks.map((hook) => ({
+    hook,
+    lifecycle: describeHookLifecycle({
+      payoffTiming: hook.payoffTiming,
+      expectedPayoff: hook.expectedPayoff,
+      notes: hook.notes,
+      startChapter: hook.startChapter,
+      lastAdvancedChapter: hook.lastAdvancedChapter,
+      status: hook.status,
+      chapterNumber: params.chapterNumber,
+      targetChapters: params.targetChapters,
+    }),
+  }));
+
+  if (activeHooks.length > maxActiveHooks) {
+    issues.push(warning(
+      params.language,
+      params.language === "en"
+        ? `There are ${activeHooks.length} active hooks, above the recommended cap of ${maxActiveHooks}.`
+        : `当前有 ${activeHooks.length} 个活跃伏笔，已经高于建议上限 ${maxActiveHooks} 个。`,
+      params.language === "en"
+        ? "Prefer advancing, resolving, or deferring existing debt before opening more hooks."
+        : "优先推进、回收或延后已有伏笔，再继续开新伏笔。",
+    ));
+  }
+
+  const staleHookIds = new Set(collectStaleHookDebt({
+    hooks: activeHooks,
+    chapterNumber: params.chapterNumber,
+    targetChapters: params.targetChapters,
+    staleAfterChapters,
+  }).map((hook) => hook.hookId));
+  const pressuredHooks = lifecycleEntries.filter(({ hook, lifecycle }) =>
+    staleHookIds.has(hook.hookId)
+    || lifecycle.readyToResolve
+    || lifecycle.overdue,
+  );
+  const unresolvedPressure = pressuredHooks.filter(({ hook }) => {
+    if (!params.delta) {
+      return true;
+    }
+
+    const disposition = classifyHookDisposition({
+      hookId: hook.hookId,
+      delta: params.delta,
+    });
+    return disposition === "none" || disposition === "mention";
+  });
+  if (unresolvedPressure.length > 0) {
+    issues.push(warning(
+      params.language,
+      buildPressureDescription({
+        language: params.language,
+        entries: unresolvedPressure,
+        mentionsCurrentChapter: Boolean(params.delta),
+      }),
+      params.language === "en"
+        ? "Move one pressured hook with a real payoff, escalation, or explicit defer before opening adjacent debt."
+        : "先让一个已进入压力区的伏笔发生真实推进、回收或明确延后，再继续扩展同类债务。",
+    ));
+  } else {
+    const latestRealAdvance = activeHooks.reduce(
+      (max, hook) => Math.max(max, hook.lastAdvancedChapter),
+      0,
+    );
+    if (
+      params.noAdvanceWindow !== undefined
+      && activeHooks.length > 0
+      && params.chapterNumber - latestRealAdvance >= noAdvanceWindow
+    ) {
+      issues.push(warning(
+        params.language,
+        params.language === "en"
+          ? `No real hook advancement has landed for ${params.chapterNumber - latestRealAdvance} chapters.`
+          : `已经连续 ${params.chapterNumber - latestRealAdvance} 章没有真实伏笔推进。`,
+        params.language === "en"
+          ? "Schedule one old hook for real movement instead of opening parallel restatements."
+          : "下一章优先让一个旧伏笔发生真实推进，而不是继续平行重述。",
+      ));
+    }
+  }
+
+  if (params.delta) {
+    const existingHookIds = new Set(params.existingHookIds ?? []);
+    const resultingHookIds = new Set(params.hooks.map((hook) => hook.hookId));
+    const newHookIds = params.delta.hookOps.upsert
+      .map((hook) => hook.hookId)
+      .filter((hookId) => !existingHookIds.has(hookId) && resultingHookIds.has(hookId));
+
+    if (newHookIds.length >= newHookBurstThreshold && params.delta.hookOps.resolve.length === 0) {
+      issues.push(warning(
+        params.language,
+        params.language === "en"
+          ? `Opened ${newHookIds.length} new hooks without resolving any older debt.`
+          : `本章新开了 ${newHookIds.length} 个伏笔，但没有回收任何旧债。`,
+        params.language === "en"
+          ? "Keep the hook table from ballooning by pairing new openings with old payoffs."
+          : "控制伏笔膨胀，新开伏笔时尽量配套回收旧伏笔。",
+      ));
+    }
+  }
+
+  return issues;
+}
+
+function buildPressureDescription(params: {
+  readonly language: "zh" | "en";
+  readonly entries: ReadonlyArray<{
+    readonly hook: HookRecord;
+    readonly lifecycle: ReturnType<typeof describeHookLifecycle>;
+  }>;
+  readonly mentionsCurrentChapter: boolean;
+}): string {
+  const summarized = params.entries
+    .slice(0, 3)
+    .map(({ hook, lifecycle }) => {
+      const timing = localizeHookPayoffTiming(lifecycle.timing, params.language);
+      const pressure = localizePressureLabel(lifecycle, params.language);
+      return params.language === "en"
+        ? `${hook.hookId} (${timing}, ${pressure})`
+        : `${hook.hookId}（${timing}，${pressure}）`;
+    });
+  const suffix = params.entries.length > summarized.length
+    ? params.language === "en"
+      ? `, +${params.entries.length - summarized.length} more`
+      : `，另有 ${params.entries.length - summarized.length} 条`
+    : "";
+
+  if (params.language === "en") {
+    return params.mentionsCurrentChapter
+      ? `Hooks are already under payoff pressure but this chapter left them untouched: ${summarized.join(", ")}${suffix}.`
+      : `Hooks are already under payoff pressure without recent movement: ${summarized.join(", ")}${suffix}.`;
+  }
+
+  return params.mentionsCurrentChapter
+    ? `这些伏笔已经进入回收/推进压力，但本章没有真正处理：${summarized.join("、")}${suffix}。`
+    : `这些伏笔已经进入回收/推进压力，但近期没有真实推进：${summarized.join("、")}${suffix}。`;
+}
+
+function localizePressureLabel(
+  lifecycle: ReturnType<typeof describeHookLifecycle>,
+  language: "zh" | "en",
+): string {
+  if (lifecycle.overdue) {
+    return language === "en" ? "overdue" : "已逾期";
+  }
+  if (lifecycle.readyToResolve) {
+    return language === "en" ? "ready to pay off" : "可回收";
+  }
+  return language === "en" ? "stale" : "陈旧";
+}
+
+function warning(
+  language: "zh" | "en",
+  description: string,
+  suggestion: string,
+): AuditIssue {
+  return {
+    severity: "warning",
+    category: language === "en" ? "Hook Debt" : "伏笔债务",
+    description,
+    suggestion,
+  };
+}

package/inkos/packages/core/src/utils/hook-ledger-validator.ts

@@ -0,0 +1,277 @@
+/**
+ * Phase 9-3: hard gate that a chapter draft actually acts on the hook ledger
+ * the planner declared in the memo's "## 本章 hook 账" / "## Hook ledger for
+ * this chapter" section.
+ *
+ * The planner commits, per chapter, to:
+ *   - advance: <hook_id> "name" → state-change
+ *   - resolve: <hook_id> "name" → action
+ *
+ * The validator parses those two lists and checks that every committed hook
+ * has observable evidence in the draft. "Evidence" means the draft mentions
+ * at least one keyword from the ledger line's descriptor (hook name, key
+ * noun, etc.). We deliberately do NOT require the draft to repeat the raw
+ * hook_id like "H007" — writers don't embed IDs in prose.
+ */
+
+export interface HookLedgerViolation {
+  readonly severity: "critical";
+  readonly category: string;
+  readonly description: string;
+  readonly suggestion: string;
+}
+
+export interface HookLedgerEntry {
+  readonly id: string;
+  /** Raw text of the ledger line after the hook_id. */
+  readonly descriptor: string;
+  /** 2+ char CJK sequences and 3+ letter ASCII words extracted from descriptor. */
+  readonly keywords: ReadonlyArray<string>;
+}
+
+export interface HookLedger {
+  readonly open: ReadonlyArray<HookLedgerEntry>;
+  readonly advance: ReadonlyArray<HookLedgerEntry>;
+  readonly resolve: ReadonlyArray<HookLedgerEntry>;
+  readonly defer: ReadonlyArray<HookLedgerEntry>;
+  /**
+   * Count of `[new] ...` placeholder lines in the `open:` subsection. These
+   * are brand-new hooks declared by the planner that have no pre-existing
+   * hook_id (extractLedgerEntry rejects them because they carry no id to
+   * match downstream), but they still count as "a new hook opened" for the
+   * 揭 1 埋 1 floor check.
+   */
+  readonly newOpenCount: number;
+}
+
+const LEDGER_HEADING_PATTERNS = [
+  /^#{2,3}\s*本章\s*hook\s*账\s*$/im,
+  /^#{2,3}\s*Hook\s+ledger\s+for\s+this\s+chapter\s*$/im,
+];
+
+const SUBSECTION_KEYS: ReadonlyArray<keyof HookLedger> = ["open", "advance", "resolve", "defer"];
+
+/**
+ * Tokens that look like hook_ids but are placeholders meaning "no hooks in
+ * this slot". Writers sometimes emit "- 无" or "- none" under an empty slot
+ * instead of leaving it blank.
+ */
+const PLACEHOLDER_TOKENS = /^(无|空|none|nil|null|暂无|n\/a|na|n-a|tbd|todo|待定)$/i;
+
+/** Subsection heading words that must not be parsed as hook_ids. */
+const SUBSECTION_WORDS = /^(open|advance|resolve|defer|new)$/i;
+
+export function parseHookLedger(memoBody: string): HookLedger {
+  const section = extractLedgerSection(memoBody);
+  if (!section) {
+    return { open: [], advance: [], resolve: [], defer: [], newOpenCount: 0 };
+  }
+
+  type Subsection = "open" | "advance" | "resolve" | "defer";
+  const result: Record<Subsection, HookLedgerEntry[]> = {
+    open: [],
+    advance: [],
+    resolve: [],
+    defer: [],
+  };
+  let newOpenCount = 0;
+
+  let current: Subsection | null = null;
+  for (const rawLine of section.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line.length === 0) continue;
+
+    const subHeadingMatch = line.match(/^(open|advance|resolve|defer)\s*[:：]?\s*$/i);
+    if (subHeadingMatch) {
+      current = subHeadingMatch[1]!.toLowerCase() as Subsection;
+      continue;
+    }
+
+    if (!current) continue;
+    if (!line.startsWith("-")) continue;
+
+    // `[new]` placeholder lines have no hook_id but still count as a new hook
+    // opened (揭 1 埋 1 floor check). extractLedgerEntry filters them out for
+    // advance/resolve evidence matching; we tally them separately here.
+    const cleaned = line.replace(/^-+\s*/, "").trim();
+    if (current === "open" && /^\[new\]/i.test(cleaned)) {
+      newOpenCount += 1;
+      continue;
+    }
+
+    const entry = extractLedgerEntry(line);
+    if (entry) result[current].push(entry);
+  }
+
+  return { ...result, newOpenCount };
+}
+
+/**
+ * Enforce: every hook declared under advance / resolve must have observable
+ * evidence in the draft text. We do NOT validate `open` (new hooks don't have
+ * a pre-existing id/descriptor to echo) or `defer` (deferred = deliberately
+ * not touched).
+ *
+ * Additionally enforces the "揭 1 埋 1" hard floor (Xu Er Jia De Mao, 番茄文章
+ * 10): whenever a chapter resolves one or more hooks, it must open at least
+ * as many new hooks in the same memo. "Resolve without opening" leaves the
+ * reader feeling "解完即索然无味" — the story loses forward pull. The softer
+ * "揭 1 埋 2" rule is a planner-prompt recommendation, not a hard gate here,
+ * because enforcing ×2 would conflict with the "≤ 2 new hooks per chapter"
+ * cap on the planner side when resolve=2.
+ */
+export function validateHookLedger(
+  memoBody: string,
+  draftContent: string,
+): ReadonlyArray<HookLedgerViolation> {
+  const ledger = parseHookLedger(memoBody);
+  const violations: HookLedgerViolation[] = [];
+
+  // Evidence check for everything the memo committed to land in prose.
+  const committed = dedupeById([...ledger.advance, ...ledger.resolve]);
+  for (const entry of committed) {
+    if (!draftEchoesEntry(draftContent, entry)) {
+      violations.push({
+        severity: "critical",
+        category: "hook 账未兑现",
+        description: `memo 在 advance/resolve 里声明要处理 ${entry.id}，但正文没有对应的落地动作`,
+        suggestion: `在正文中加入对 ${entry.id} 的具体情节推进（动作、对话、环境变化），或把它从 hook 账里移到 defer 并给出理由`,
+      });
+    }
+  }
+
+  // "揭 1 埋 1" hard floor: when anything was resolved, at least the same
+  // number of new hooks must have been opened. We count both `[new]`
+  // placeholder lines (newOpenCount — the normal way planners declare fresh
+  // hooks without an id) and any id-bearing lines under `open:` (rare, but
+  // legal if a planner re-opens a previously paused hook).
+  const resolvedCount = ledger.resolve.length;
+  const openedCount = ledger.open.length + ledger.newOpenCount;
+  if (resolvedCount > 0 && openedCount < resolvedCount) {
+    violations.push({
+      severity: "critical",
+      category: "hook 账揭 1 埋 1 违规",
+      description: `本章 resolve 了 ${resolvedCount} 个钩子，但 open 只有 ${openedCount} 个新钩子。只揭不埋会让读者豁然开朗后索然无味，本书的前进拉力被削弱。`,
+      suggestion: `在 memo 的 open 段下至少再埋 ${resolvedCount - openedCount} 个与本章已揭钩子相关的新钩子（番茄老师徐二家的猫："掀开一个伏笔的同时，再埋两个伏笔"）。新钩子最好与已揭钩子彼此关联，不要凭空冒出来。`,
+    });
+  }
+
+  return violations;
+}
+
+function extractLedgerSection(memoBody: string): string | undefined {
+  for (const pattern of LEDGER_HEADING_PATTERNS) {
+    const match = memoBody.match(pattern);
+    if (!match || match.index === undefined) continue;
+    const start = match.index + match[0].length;
+    const rest = memoBody.slice(start);
+    const nextHeading = rest.match(/\n#{2,3}\s/);
+    const end = nextHeading ? nextHeading.index ?? rest.length : rest.length;
+    return rest.slice(0, end);
+  }
+  return undefined;
+}
+
+function extractLedgerEntry(line: string): HookLedgerEntry | undefined {
+  const cleaned = line.replace(/^-+\s*/, "").trim();
+  if (cleaned.startsWith("[new]") || cleaned.startsWith("[NEW]")) return undefined;
+
+  // Reject whole-line placeholders first — "- 无", "- n/a", "- none" etc.
+  const firstWord = cleaned.split(/\s+/)[0] ?? "";
+  if (PLACEHOLDER_TOKENS.test(firstWord)) return undefined;
+
+  const idMatch = cleaned.match(/^([A-Za-z\u4e00-\u9fff][A-Za-z0-9_\-\u4e00-\u9fff]{0,19})/);
+  if (!idMatch) return undefined;
+
+  const candidate = idMatch[1]!;
+  if (SUBSECTION_WORDS.test(candidate)) return undefined;
+  if (PLACEHOLDER_TOKENS.test(candidate)) return undefined;
+
+  const descriptor = cleaned.slice(candidate.length).trim();
+  return { id: candidate, descriptor, keywords: extractKeywords(descriptor) };
+}
+
+/**
+ * Extract content-matching tokens from a ledger line's descriptor.
+ *
+ * Priority 1: quoted hook name — `H007 "胖虎借条" → ...` — this is the most
+ * informative token the planner attached, and it's what the writer should
+ * echo. We split compound CJK names into leading/trailing 2-grams so
+ * partial echoes still count.
+ *
+ * Priority 2: if no quoted name, fall back to the descriptor text UP TO the
+ * first state-transition arrow (→ or ->), same CJK/ASCII splitting. Anything
+ * AFTER the arrow describes new state, not the hook itself, and risks
+ * character-name false positives.
+ */
+function extractKeywords(descriptor: string): ReadonlyArray<string> {
+  if (!descriptor) return [];
+
+  // Try the quoted-name anchor first — matches "..." or "..." quotes.
+  const quotedMatch = descriptor.match(/[""]([^""\n]+)[""]/);
+  const source = quotedMatch ? quotedMatch[1]! : descriptor.split(/[→]|->/, 1)[0]!;
+
+  const cjkRuns = source.match(/[\u4e00-\u9fff]{2,}/g) ?? [];
+  const cjkTokens: string[] = [];
+  for (const run of cjkRuns) {
+    cjkTokens.push(run);
+    if (run.length >= 3) {
+      for (let index = 0; index <= run.length - 2; index++) {
+        cjkTokens.push(run.slice(index, index + 2));
+      }
+    }
+    if (run.length >= 4) {
+      cjkTokens.push(run.slice(0, 3));
+      cjkTokens.push(run.slice(-3));
+    }
+  }
+  const ascii = (source.match(/[A-Za-z]{3,}/g) ?? []).map((w) => w.toLowerCase());
+  return dedupeStrings([...cjkTokens, ...ascii].filter((tok) => !ASCII_STOPWORDS.has(tok)));
+}
+
+const ASCII_STOPWORDS = new Set([
+  "and", "the", "for", "with", "from", "that", "into", "then",
+  "open", "close", "advance", "resolve", "defer", "new",
+  "planted", "pressured", "near", "payoff", "ready", "stale",
+]);
+
+function draftEchoesEntry(draft: string, entry: HookLedgerEntry): boolean {
+  if (entry.keywords.length > 0) {
+    const draftLower = draft.toLowerCase();
+    return entry.keywords.some((kw) => {
+      // ASCII keywords are already lowercased; CJK keywords case doesn't matter.
+      return /^[a-z]/.test(kw) ? draftLower.includes(kw) : draft.includes(kw);
+    });
+  }
+  // Bare-id ledger line with no descriptor — fall back to ID match.
+  if (/^[A-Za-z0-9_-]+$/.test(entry.id)) {
+    return new RegExp(`\\b${escapeRegex(entry.id)}\\b`).test(draft);
+  }
+  return draft.includes(entry.id);
+}
+
+function dedupeById(entries: ReadonlyArray<HookLedgerEntry>): HookLedgerEntry[] {
+  const seen = new Set<string>();
+  const result: HookLedgerEntry[] = [];
+  for (const entry of entries) {
+    if (seen.has(entry.id)) continue;
+    seen.add(entry.id);
+    result.push(entry);
+  }
+  return result;
+}
+
+function dedupeStrings(values: ReadonlyArray<string>): string[] {
+  return [...new Set(values)];
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export const INTERNAL = {
+  SUBSECTION_KEYS,
+  extractLedgerSection,
+  extractLedgerEntry,
+  extractKeywords,
+};

package/inkos/packages/core/src/utils/hook-lifecycle.ts

@@ -0,0 +1,224 @@
+import type { HookPayoffTiming } from "../models/runtime-state.js";
+import type { StoredHook } from "../state/memory-db.js";
+import {
+  HOOK_ACTIVITY_THRESHOLDS,
+  HOOK_PHASE_THRESHOLDS,
+  HOOK_PHASE_WEIGHT,
+  HOOK_PRESSURE_WEIGHTS,
+  HOOK_TIMING_PROFILES,
+  type HookPhase,
+} from "./hook-policy.js";
+
+export const DEFAULT_HOOK_LOOKAHEAD_CHAPTERS = 3;
+
+function normalizeStoredHookStatus(status: string): "resolved" | "deferred" | "progressing" | "open" {
+  if (/^(resolved|closed|done|已回收|已解决)$/i.test(status.trim())) return "resolved";
+  if (/^(deferred|paused|hold|延后|延期|搁置|暂缓)$/i.test(status.trim())) return "deferred";
+  if (/^(progressing|advanced|重大推进|持续推进)$/i.test(status.trim())) return "progressing";
+  return "open";
+}
+
+export function filterActiveHooks(hooks: ReadonlyArray<StoredHook>): StoredHook[] {
+  return hooks.filter((hook) => normalizeStoredHookStatus(hook.status) !== "resolved");
+}
+
+export function isFuturePlannedHook(
+  hook: StoredHook,
+  chapterNumber: number,
+  lookahead: number = DEFAULT_HOOK_LOOKAHEAD_CHAPTERS,
+): boolean {
+  return hook.lastAdvancedChapter <= 0 && hook.startChapter > chapterNumber + lookahead;
+}
+
+export function isHookWithinChapterWindow(
+  hook: StoredHook,
+  chapterNumber: number,
+  recentWindow: number = 5,
+  lookahead: number = DEFAULT_HOOK_LOOKAHEAD_CHAPTERS,
+): boolean {
+  const recentCutoff = Math.max(0, chapterNumber - recentWindow);
+
+  if (hook.lastAdvancedChapter > 0 && hook.lastAdvancedChapter >= recentCutoff) {
+    return true;
+  }
+
+  if (hook.lastAdvancedChapter > 0) {
+    return false;
+  }
+
+  if (hook.startChapter <= 0) {
+    return true;
+  }
+
+  if (hook.startChapter >= recentCutoff && hook.startChapter <= chapterNumber) {
+    return true;
+  }
+
+  return hook.startChapter > chapterNumber && hook.startChapter <= chapterNumber + lookahead;
+}
+
+const LABELS: Record<"zh" | "en", Record<HookPayoffTiming, string>> = {
+  en: {
+    immediate: "immediate",
+    "near-term": "near-term",
+    "mid-arc": "mid-arc",
+    "slow-burn": "slow-burn",
+    endgame: "endgame",
+  },
+  zh: {
+    immediate: "立即",
+    "near-term": "近期",
+    "mid-arc": "中程",
+    "slow-burn": "慢烧",
+    endgame: "终局",
+  },
+};
+
+const TIMING_ALIASES: Array<[HookPayoffTiming, RegExp]> = [
+  ["immediate", /^(?:立即|马上|当章|本章|下一章|immediate|instant|next(?:\s+chapter|\s+beat)?|right\s+away)$/i],
+  ["near-term", /^(?:近期|近几章|短线|soon|short(?:\s+run)?|near(?:\s*-\s*|\s+)term|current\s+sequence)$/i],
+  ["mid-arc", /^(?:中程|中期|卷中|mid(?:\s*-\s*|\s+)arc|mid(?:\s*-\s*|\s+)book|middle)$/i],
+  ["slow-burn", /^(?:慢烧|长线|后续|later|late(?:r)?|long(?:\s*-\s*|\s+)arc|slow(?:\s*-\s*|\s+)burn)$/i],
+  ["endgame", /^(?:终局|终章|大结局|最终|climax|finale|endgame|late\s+book)$/i],
+];
+
+const SIGNAL_PATTERNS: Array<[HookPayoffTiming, RegExp]> = [
+  ["endgame", /(终局|终章|大结局|最终揭晓|最终摊牌|climax|finale|endgame|final reveal|last act)/i],
+  ["immediate", /(当章|本章|下一章|马上|立刻|即刻|immediate|next chapter|right away|at once)/i],
+  ["near-term", /(近期|近几章|很快|短线|soon|near-term|short run|current sequence)/i],
+  ["mid-arc", /(中期|卷中|本卷中段|mid-book|mid arc|middle of the arc)/i],
+  ["slow-burn", /(长线|慢烧|后续发酵|慢慢揭开|later|slow burn|long arc|long tail)/i],
+];
+
+export function normalizeHookPayoffTiming(value: string | undefined | null): HookPayoffTiming | undefined {
+  const normalized = value?.trim();
+  if (!normalized) return undefined;
+
+  for (const [timing, pattern] of TIMING_ALIASES) {
+    if (pattern.test(normalized)) {
+      return timing;
+    }
+  }
+
+  return undefined;
+}
+
+export function inferHookPayoffTiming(params: {
+  readonly expectedPayoff?: string;
+  readonly notes?: string;
+}): HookPayoffTiming {
+  const combined = [params.expectedPayoff, params.notes]
+    .filter((value): value is string => Boolean(value && value.trim()))
+    .join(" ")
+    .trim();
+  if (!combined) return "mid-arc";
+
+  for (const [timing, pattern] of SIGNAL_PATTERNS) {
+    if (pattern.test(combined)) {
+      return timing;
+    }
+  }
+
+  return "mid-arc";
+}
+
+export function resolveHookPayoffTiming(params: {
+  readonly payoffTiming?: string | null;
+  readonly expectedPayoff?: string;
+  readonly notes?: string;
+}): HookPayoffTiming {
+  return normalizeHookPayoffTiming(params.payoffTiming)
+    ?? inferHookPayoffTiming({
+      expectedPayoff: params.expectedPayoff,
+      notes: params.notes,
+    });
+}
+
+export function localizeHookPayoffTiming(
+  timing: HookPayoffTiming,
+  language: "zh" | "en",
+): string {
+  return LABELS[language][timing];
+}
+
+export function describeHookLifecycle(params: {
+  readonly payoffTiming?: string | null;
+  readonly expectedPayoff?: string;
+  readonly notes?: string;
+  readonly startChapter: number;
+  readonly lastAdvancedChapter: number;
+  readonly status: string;
+  readonly chapterNumber: number;
+  readonly targetChapters?: number;
+}): {
+  readonly timing: HookPayoffTiming;
+  readonly phase: HookPhase;
+  readonly age: number;
+  readonly dormancy: number;
+  readonly readyToResolve: boolean;
+  readonly stale: boolean;
+  readonly overdue: boolean;
+  readonly advancePressure: number;
+  readonly resolvePressure: number;
+} {
+  const timing = resolveHookPayoffTiming(params);
+  const profile = HOOK_TIMING_PROFILES[timing];
+  const phase = resolveHookPhase(params.chapterNumber, params.targetChapters);
+  const age = Math.max(0, params.chapterNumber - Math.max(1, params.startChapter));
+  const lastTouchChapter = Math.max(params.startChapter, params.lastAdvancedChapter);
+  const dormancy = Math.max(0, params.chapterNumber - Math.max(1, lastTouchChapter));
+  const explicitProgressing = /^(progressing|advanced|重大推进|持续推进)$/i.test(params.status.trim());
+  const phaseReady = HOOK_PHASE_WEIGHT[phase] >= HOOK_PHASE_WEIGHT[profile.minimumPhase];
+  const recentlyTouched = dormancy <= HOOK_ACTIVITY_THRESHOLDS.recentlyTouchedDormancy;
+  const overdue = phaseReady && age >= profile.overdueAge;
+  const cadenceReady = timing === "slow-burn"
+    ? phase === "late" || overdue
+    : timing === "endgame"
+      ? phase === "late"
+      : true;
+  const momentum = explicitProgressing || recentlyTouched;
+  const stale = phaseReady && (
+    dormancy >= profile.staleDormancy
+    || (overdue && !momentum)
+  );
+  const readyToResolve = phaseReady
+    && cadenceReady
+    && age >= profile.earliestResolveAge
+    && (momentum || (overdue && explicitProgressing));
+
+  return {
+    timing,
+    phase,
+    age,
+    dormancy,
+    readyToResolve,
+    stale,
+    overdue,
+    advancePressure: age
+      + dormancy
+      + (stale ? HOOK_PRESSURE_WEIGHTS.staleAdvanceBonus : 0)
+      + (overdue ? HOOK_PRESSURE_WEIGHTS.overdueAdvanceBonus : 0),
+    resolvePressure: readyToResolve
+      ? profile.resolveBias * HOOK_PRESSURE_WEIGHTS.resolveBiasMultiplier
+        + (explicitProgressing ? HOOK_PRESSURE_WEIGHTS.progressingResolveBonus : 0)
+        + Math.min(
+          HOOK_PRESSURE_WEIGHTS.maxDormancyResolveBonus,
+          dormancy * HOOK_PRESSURE_WEIGHTS.dormancyResolveMultiplier,
+        )
+        + (overdue ? HOOK_PRESSURE_WEIGHTS.overdueResolveBonus : 0)
+      : 0,
+  };
+}
+
+function resolveHookPhase(chapterNumber: number, targetChapters?: number): HookPhase {
+  if (targetChapters && targetChapters > 0) {
+    const progress = chapterNumber / targetChapters;
+    if (progress >= HOOK_PHASE_THRESHOLDS.lateProgress) return "late";
+    if (progress >= HOOK_PHASE_THRESHOLDS.middleProgress) return "middle";
+    return "opening";
+  }
+
+  if (chapterNumber >= HOOK_PHASE_THRESHOLDS.lateChapter) return "late";
+  if (chapterNumber >= HOOK_PHASE_THRESHOLDS.middleChapter) return "middle";
+  return "opening";
+}