@zwbigi/ink-xy 0.1.2 → 0.1.4

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

@@ -0,0 +1,236 @@
+import { describe, it, expect } from "vitest";
+import {
+  parseHookLedger,
+  validateHookLedger,
+} from "../utils/hook-ledger-validator.js";
+
+const ZH_MEMO = `## 当前任务
+林秋潜入账房取回账册。
+
+## 本章 hook 账
+open:
+- [new] 旧港眼线盯梢 || 理由：留给下一卷
+
+advance:
+- H007 "胖虎借条" → planted → pressured
+- H012 "雷架焦痕" → pressured → near_payoff
+
+resolve:
+- H003 "杂役腰牌" → 林秋主动摘下
+
+defer:
+- H009 "守拙诀来历" → 本章不动
+
+## 不要做
+- 不要点破母亲身份`;
+
+const EN_MEMO = `## Current task
+Lin Qiu lifts the ledger from the Old Port accounting hall.
+
+## Hook ledger for this chapter
+open:
+- [new] Old Port tail || reason: save for later arc
+
+advance:
+- H007 "Huzi's IOU" → planted → pressured
+
+resolve:
+- H003 "errand badge" → Lin Qiu unpins it himself
+
+defer:
+- H009 "Shou-Zhuo Jue origin" → timing not right
+
+## Do not
+- Do not reveal the mother's name`;
+
+describe("parseHookLedger", () => {
+  it("extracts all four sub-lists from a zh memo", () => {
+    const ledger = parseHookLedger(ZH_MEMO);
+    expect(ledger.advance.map((e) => e.id)).toEqual(["H007", "H012"]);
+    expect(ledger.resolve.map((e) => e.id)).toEqual(["H003"]);
+    expect(ledger.defer.map((e) => e.id)).toEqual(["H009"]);
+    // open uses [new] so no hook_id is extracted
+    expect(ledger.open).toEqual([]);
+  });
+
+  it("captures descriptor + keywords for each entry", () => {
+    const ledger = parseHookLedger(ZH_MEMO);
+    const h007 = ledger.advance[0]!;
+    expect(h007.id).toBe("H007");
+    expect(h007.descriptor).toContain("胖虎借条");
+    expect(h007.keywords).toContain("胖虎");
+    expect(h007.keywords).toContain("借条");
+
+    const h003 = ledger.resolve[0]!;
+    expect(h003.keywords).toContain("杂役");
+    expect(h003.keywords).toContain("腰牌");
+  });
+
+  it("extracts all four sub-lists from an en memo", () => {
+    const ledger = parseHookLedger(EN_MEMO);
+    expect(ledger.advance.map((e) => e.id)).toEqual(["H007"]);
+    expect(ledger.resolve.map((e) => e.id)).toEqual(["H003"]);
+    expect(ledger.defer.map((e) => e.id)).toEqual(["H009"]);
+  });
+
+  it("returns empty lists when no ledger section is present", () => {
+    const ledger = parseHookLedger("## 当前任务\n正文\n\n## 不要做\n- 无");
+    expect(ledger).toEqual({ open: [], advance: [], resolve: [], defer: [], newOpenCount: 0 });
+  });
+
+  it("counts [new] placeholder lines under open as new hooks opened", () => {
+    const memo = `## 本章 hook 账
+open:
+- [new] 下一卷伏笔 || 理由
+- [new] 第二条埋点 || 理由
+advance:
+- H001 "x" → y
+`;
+    const ledger = parseHookLedger(memo);
+    expect(ledger.open).toEqual([]); // [new] lines have no id → not in .open
+    expect(ledger.newOpenCount).toBe(2);
+  });
+
+  it("stops at the next H2 heading and does not pollute across sections", () => {
+    const memo = `## 本章 hook 账
+advance:
+- H007 "xxx" → ...
+
+## 不要做
+- H999 looks-like-a-hook-but-its-under-do-not`;
+    const ledger = parseHookLedger(memo);
+    expect(ledger.advance.map((e) => e.id)).toEqual(["H007"]);
+    expect(ledger.defer).toEqual([]);
+  });
+
+  it("ignores placeholder tokens like 无 / none / n/a under empty slots", () => {
+    const memo = `## 本章 hook 账
+advance:
+- 无
+- none
+- H007 "真的钩子" → planted
+resolve:
+- 暂无
+defer:
+- n/a
+`;
+    const ledger = parseHookLedger(memo);
+    expect(ledger.advance.map((e) => e.id)).toEqual(["H007"]);
+    expect(ledger.resolve).toEqual([]);
+    expect(ledger.defer).toEqual([]);
+  });
+});
+
+describe("validateHookLedger", () => {
+  it("passes when draft echoes keyword from each committed ledger entry", () => {
+    // Draft mentions 胖虎/借条 (→H007), 雷架 or 焦痕 (→H012), 杂役 or 腰牌 (→H003).
+    const draft =
+      "林秋在账房找到胖虎借条，又在后巷被雷架焦痕刮到眼角。他摘下杂役腰牌后退入暗处。";
+    const violations = validateHookLedger(ZH_MEMO, draft);
+    expect(violations).toEqual([]);
+  });
+
+  it("flags a critical violation for each un-echoed advance/resolve entry", () => {
+    // Only 胖虎 (H007) present; 雷架/焦痕 (H012) and 杂役/腰牌 (H003) missing.
+    const draft = "林秋只摸出胖虎借条，其他都没写。";
+    const violations = validateHookLedger(ZH_MEMO, draft);
+    expect(violations).toHaveLength(2);
+    expect(violations.every((v) => v.severity === "critical")).toBe(true);
+    expect(violations.map((v) => v.description).join(" ")).toContain("H012");
+    expect(violations.map((v) => v.description).join(" ")).toContain("H003");
+  });
+
+  it("does NOT flag hooks that are only under defer", () => {
+    // H009 is deferred — keyword 守拙诀 absence is fine.
+    const draft = "林秋翻出胖虎借条与雷架焦痕推进情节，随后摘下杂役腰牌。";
+    const violations = validateHookLedger(ZH_MEMO, draft);
+    expect(violations).toEqual([]);
+  });
+
+  it("does NOT flag [new] open entries (they have no pre-existing id)", () => {
+    const memo = `## 本章 hook 账
+open:
+- [new] 新钩子 || 理由
+advance:
+- H001 "测试项" → x
+`;
+    const draft = "正文提到测试项的细节。";
+    const violations = validateHookLedger(memo, draft);
+    expect(violations).toEqual([]);
+  });
+
+  it("returns empty array when memo has no ledger section at all", () => {
+    const violations = validateHookLedger("## 别的东西\n正文", "draft");
+    expect(violations).toEqual([]);
+  });
+
+  it("falls back to strict ID match when ledger line has no descriptor", () => {
+    const memo = `## 本章 hook 账
+advance:
+- H1
+`;
+    // Draft contains H12 — must NOT accidentally satisfy H1 commitment.
+    const draft = "剧情涉及 H12 和 H123。";
+    const violations = validateHookLedger(memo, draft);
+    expect(violations).toHaveLength(1);
+    expect(violations[0]!.description).toContain("H1");
+  });
+
+  it("accepts english keyword match for en memos", () => {
+    const draft =
+      "Lin Qiu finds Huzi's IOU folded inside the ledger and tucks it away. Later he unpins the errand badge before slipping out.";
+    const violations = validateHookLedger(EN_MEMO, draft);
+    expect(violations).toEqual([]);
+  });
+
+  it("flags 揭 1 埋 1 violation when a chapter resolves hooks without opening any", () => {
+    const memo = `## 本章 hook 账
+advance:
+- H007 "胖虎借条" → planted
+resolve:
+- H003 "杂役腰牌" → 林秋主动摘下
+`;
+    const draft = "林秋翻看胖虎借条，随后摘下杂役腰牌。";
+    const violations = validateHookLedger(memo, draft);
+    expect(violations).toHaveLength(1);
+    expect(violations[0]!.category).toContain("揭 1 埋 1");
+  });
+
+  it("accepts 揭 1 埋 1 floor when a [new] line balances the resolved hook", () => {
+    const memo = `## 本章 hook 账
+open:
+- [new] 母亲留下的半枚玉佩 || 理由：下一卷线索
+advance:
+- H007 "胖虎借条" → planted
+resolve:
+- H003 "杂役腰牌" → 林秋主动摘下
+`;
+    const draft = "林秋翻看胖虎借条，随后摘下杂役腰牌。";
+    const violations = validateHookLedger(memo, draft);
+    expect(violations).toEqual([]);
+  });
+
+  it("does not let placeholder 无 raise a false critical", () => {
+    const memo = `## 本章 hook 账
+open:
+- [new] 下一卷伏笔 || 理由
+advance:
+- 无
+resolve:
+- H005 "通行印验号" → ok
+`;
+    const draft = "主峰的通行印验号按部就班完成。";
+    const violations = validateHookLedger(memo, draft);
+    expect(violations).toEqual([]);
+  });
+
+  it("accepts middle keywords from a longer Chinese hook name", () => {
+    const memo = `## 本章 hook 账
+advance:
+- H007 "被定位的安全威胁" → evoked → pressured
+`;
+    const draft = "旧手机弹出定位结果，林知夏发现店外有人盯梢，安全空间塌了。";
+    const violations = validateHookLedger(memo, draft);
+    expect(violations).toEqual([]);
+  });
+});

package/inkos/packages/core/src/__tests__/hook-promotion.test.ts

@@ -0,0 +1,192 @@
+import { describe, expect, it } from "vitest";
+import type { StoredHook } from "../state/memory-db.js";
+import {
+  defaultHalfLifeChapters,
+  resolveHalfLifeChapters,
+  shouldPromoteHook,
+  type PromotionContext,
+  type VolumeBoundary,
+} from "../utils/hook-promotion.js";
+
+function makeHook(overrides: Partial<StoredHook>): StoredHook {
+  return {
+    hookId: "H01",
+    startChapter: 1,
+    type: "主线",
+    status: "open",
+    lastAdvancedChapter: 0,
+    expectedPayoff: "回收",
+    notes: "",
+    ...overrides,
+  };
+}
+
+function makeContext(overrides: Partial<PromotionContext>): PromotionContext {
+  return {
+    volumeBoundaries: [],
+    currentChapter: 10,
+    advancedCounts: new Map(),
+    allSeedStartChapters: new Map(),
+    ...overrides,
+  };
+}
+
+const VOL_MAP: ReadonlyArray<VolumeBoundary> = [
+  { name: "第一卷", startCh: 1, endCh: 20 },
+  { name: "第二卷", startCh: 21, endCh: 40 },
+  { name: "第三卷", startCh: 41, endCh: 60 },
+];
+
+describe("shouldPromoteHook — Phase 7 four-rule promotion", () => {
+  it("promotes a core_hook even when nothing else fires", () => {
+    const hook = makeHook({ coreHook: true, startChapter: 5 });
+    const decision = shouldPromoteHook(hook, makeContext({ volumeBoundaries: VOL_MAP }));
+    expect(decision.promote).toBe(true);
+    expect(decision.reasons).toContain("core_hook");
+  });
+
+  it("promotes a hook with any depends_on entries", () => {
+    const hook = makeHook({ dependsOn: ["H02"], startChapter: 5 });
+    const decision = shouldPromoteHook(hook, makeContext({ volumeBoundaries: VOL_MAP }));
+    expect(decision.promote).toBe(true);
+    expect(decision.reasons).toContain("depends_on");
+  });
+
+  it("promotes a hook that has been advanced in two or more chapters", () => {
+    const hook = makeHook({ hookId: "H07", startChapter: 3, advancedCount: 2 });
+    const decision = shouldPromoteHook(hook, makeContext({ volumeBoundaries: VOL_MAP }));
+    expect(decision.promote).toBe(true);
+    expect(decision.reasons).toContain("advanced_count");
+  });
+
+  it("reads advancedCount from context when hook itself has none", () => {
+    const hook = makeHook({ hookId: "H07", startChapter: 3 });
+    const decision = shouldPromoteHook(
+      hook,
+      makeContext({
+        volumeBoundaries: VOL_MAP,
+        advancedCounts: new Map([["H07", 3]]),
+      }),
+    );
+    expect(decision.promote).toBe(true);
+    expect(decision.reasons).toContain("advanced_count");
+  });
+
+  it("promotes when depends_on upstream lives in a later volume (cross_volume)", () => {
+    // Planted in vol 1 (ch 5), depends on H_future which is planted in vol 2 (ch 25).
+    const hook = makeHook({
+      startChapter: 5,
+      dependsOn: ["H_FUTURE"],
+    });
+    const decision = shouldPromoteHook(
+      hook,
+      makeContext({
+        volumeBoundaries: VOL_MAP,
+        allSeedStartChapters: new Map([["H_FUTURE", 25]]),
+      }),
+    );
+    expect(decision.promote).toBe(true);
+    // Both depends_on and cross_volume should fire.
+    expect(decision.reasons).toContain("depends_on");
+    expect(decision.reasons).toContain("cross_volume");
+  });
+
+  it("promotes a slow-burn hook planted in volume 1 as cross_volume", () => {
+    const hook = makeHook({
+      startChapter: 3,
+      payoffTiming: "slow-burn",
+    });
+    const decision = shouldPromoteHook(
+      hook,
+      makeContext({ volumeBoundaries: VOL_MAP }),
+    );
+    expect(decision.promote).toBe(true);
+    expect(decision.reasons).toContain("cross_volume");
+  });
+
+  it("promotes when pays_off_in_arc mentions a different volume in Chinese", () => {
+    const hook = makeHook({
+      startChapter: 5,
+      paysOffInArc: "第二卷中段揭晓",
+    });
+    const decision = shouldPromoteHook(
+      hook,
+      makeContext({ volumeBoundaries: VOL_MAP }),
+    );
+    expect(decision.promote).toBe(true);
+    expect(decision.reasons).toContain("cross_volume");
+  });
+
+  it("promotes when pays_off_in_arc mentions a different volume in English", () => {
+    const hook = makeHook({
+      startChapter: 5,
+      paysOffInArc: "mid of volume 3",
+    });
+    const decision = shouldPromoteHook(
+      hook,
+      makeContext({ volumeBoundaries: VOL_MAP }),
+    );
+    expect(decision.promote).toBe(true);
+    expect(decision.reasons).toContain("cross_volume");
+  });
+
+  it("does NOT promote a plain local seed with no rules firing", () => {
+    const hook = makeHook({
+      hookId: "H99",
+      startChapter: 5,
+      payoffTiming: "near-term",
+      coreHook: false,
+      dependsOn: [],
+    });
+    const decision = shouldPromoteHook(
+      hook,
+      makeContext({ volumeBoundaries: VOL_MAP }),
+    );
+    expect(decision.promote).toBe(false);
+    expect(decision.reasons).toEqual([]);
+  });
+
+  it("does NOT promote when advancedCount is 1 (below threshold)", () => {
+    const hook = makeHook({ hookId: "H1", startChapter: 5, advancedCount: 1 });
+    const decision = shouldPromoteHook(
+      hook,
+      makeContext({ volumeBoundaries: VOL_MAP }),
+    );
+    expect(decision.promote).toBe(false);
+  });
+
+  it("combines multiple reasons when several conditions hold", () => {
+    const hook = makeHook({
+      startChapter: 3,
+      coreHook: true,
+      dependsOn: ["H03"],
+      advancedCount: 4,
+      payoffTiming: "endgame",
+    });
+    const decision = shouldPromoteHook(
+      hook,
+      makeContext({ volumeBoundaries: VOL_MAP }),
+    );
+    expect(decision.promote).toBe(true);
+    expect(new Set(decision.reasons)).toEqual(
+      new Set(["core_hook", "depends_on", "advanced_count", "cross_volume"]),
+    );
+  });
+
+  it("defaultHalfLifeChapters maps timing to the prompt defaults", () => {
+    expect(defaultHalfLifeChapters("immediate")).toBe(10);
+    expect(defaultHalfLifeChapters("near-term")).toBe(10);
+    expect(defaultHalfLifeChapters("mid-arc")).toBe(30);
+    expect(defaultHalfLifeChapters("slow-burn")).toBe(80);
+    expect(defaultHalfLifeChapters("endgame")).toBe(80);
+    expect(defaultHalfLifeChapters(undefined)).toBe(30);
+  });
+
+  it("resolveHalfLifeChapters prefers explicit halfLifeChapters over derived default", () => {
+    const explicit = makeHook({ payoffTiming: "mid-arc", halfLifeChapters: 50 });
+    expect(resolveHalfLifeChapters(explicit)).toBe(50);
+
+    const derived = makeHook({ payoffTiming: "mid-arc" });
+    expect(resolveHalfLifeChapters(derived)).toBe(30);
+  });
+});

package/inkos/packages/core/src/__tests__/hook-stale-detection.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from "vitest";
+import type { StoredHook } from "../state/memory-db.js";
+import {
+  computeHookDiagnostics,
+  renderHookDiagnosticMarker,
+} from "../utils/hook-stale-detection.js";
+
+function hook(overrides: Partial<StoredHook>): StoredHook {
+  return {
+    hookId: "H01",
+    startChapter: 1,
+    type: "主线",
+    status: "open",
+    lastAdvancedChapter: 0,
+    expectedPayoff: "",
+    notes: "",
+    ...overrides,
+  };
+}
+
+describe("computeHookDiagnostics — Phase 7 stale / blocked detection", () => {
+  it("flags a hook as stale when distance exceeds half-life and hook is unresolved", () => {
+    // near-term default half-life is 10, plant at ch 5, current ch 25 => distance 20 > 10.
+    const h = hook({ startChapter: 5, payoffTiming: "near-term" });
+    const diag = computeHookDiagnostics({ hooks: [h], currentChapter: 25 }).get("H01")!;
+    expect(diag.stale).toBe(true);
+    expect(diag.distance).toBe(20);
+    expect(diag.halfLife).toBe(10);
+  });
+
+  it("does NOT flag a hook as stale when distance is within half-life", () => {
+    const h = hook({ startChapter: 5, payoffTiming: "mid-arc" });
+    const diag = computeHookDiagnostics({ hooks: [h], currentChapter: 25 }).get("H01")!;
+    expect(diag.stale).toBe(false);
+  });
+
+  it("honors explicit halfLifeChapters over the timing default", () => {
+    const h = hook({
+      startChapter: 5,
+      payoffTiming: "near-term", // default 10
+      halfLifeChapters: 50,
+    });
+    const diag = computeHookDiagnostics({ hooks: [h], currentChapter: 30 }).get("H01")!;
+    expect(diag.stale).toBe(false); // distance 25 < explicit 50
+    expect(diag.halfLife).toBe(50);
+  });
+
+  it("never flags a resolved hook as stale", () => {
+    const h = hook({ startChapter: 5, status: "resolved", payoffTiming: "immediate" });
+    const diag = computeHookDiagnostics({ hooks: [h], currentChapter: 90 }).get("H01")!;
+    expect(diag.stale).toBe(false);
+  });
+
+  it("flags a hook as blocked when its depends_on upstream is unplanted", () => {
+    const downstream = hook({
+      hookId: "H-down",
+      startChapter: 10,
+      dependsOn: ["H-up"],
+    });
+    // upstream missing entirely
+    const diag = computeHookDiagnostics({
+      hooks: [downstream],
+      currentChapter: 20,
+    }).get("H-down")!;
+    expect(diag.blocked).toBe(true);
+    expect(diag.missingUpstream).toEqual(["H-up"]);
+  });
+
+  it("flags a hook as blocked when the upstream is planted but unresolved", () => {
+    const upstream = hook({ hookId: "H-up", startChapter: 3, status: "open" });
+    const downstream = hook({
+      hookId: "H-down",
+      startChapter: 10,
+      dependsOn: ["H-up"],
+    });
+    const result = computeHookDiagnostics({
+      hooks: [upstream, downstream],
+      currentChapter: 20,
+    });
+    expect(result.get("H-down")!.blocked).toBe(true);
+    expect(result.get("H-up")!.blocked).toBe(false);
+  });
+
+  it("clears the blocked flag once every upstream is resolved", () => {
+    const upstream = hook({ hookId: "H-up", startChapter: 3, status: "resolved" });
+    const downstream = hook({
+      hookId: "H-down",
+      startChapter: 10,
+      dependsOn: ["H-up"],
+    });
+    const result = computeHookDiagnostics({
+      hooks: [upstream, downstream],
+      currentChapter: 20,
+    });
+    expect(result.get("H-down")!.blocked).toBe(false);
+    expect(result.get("H-down")!.missingUpstream).toEqual([]);
+  });
+
+  it("pre-planting seeds (startChapter 0) are not marked stale", () => {
+    const h = hook({ startChapter: 0, payoffTiming: "immediate" });
+    const diag = computeHookDiagnostics({ hooks: [h], currentChapter: 50 }).get("H01")!;
+    expect(diag.stale).toBe(false);
+  });
+
+  it("renderHookDiagnosticMarker formats zh / en markers correctly", () => {
+    // Hotfix 3: marker now embeds blocked distance (已阻 N 章 / blocked N chapters)
+    // so the reviewer can apply the 5/6-chapter threshold directly.
+    const diag = {
+      stale: true,
+      blocked: true,
+      missingUpstream: ["H-up"],
+      distance: 20,
+      halfLife: 10,
+      blockedDistance: 7,
+    } as const;
+    expect(renderHookDiagnosticMarker(diag, "zh")).toBe(
+      "过期 (距=20/半衰=10); 受阻于 H-up (已阻 7 章)",
+    );
+    expect(renderHookDiagnosticMarker(diag, "en")).toBe(
+      "stale (d=20/half=10); blocked on H-up (blocked 7 chapters)",
+    );
+  });
+
+  it("renders empty marker when nothing is flagged", () => {
+    const diag = {
+      stale: false,
+      blocked: false,
+      missingUpstream: [],
+      distance: 1,
+      halfLife: 10,
+      blockedDistance: 0,
+    } as const;
+    expect(renderHookDiagnosticMarker(diag, "zh")).toBe("");
+    expect(renderHookDiagnosticMarker(diag, "en")).toBe("");
+  });
+});

package/inkos/packages/core/src/__tests__/index-notify-lazy.test.ts

@@ -0,0 +1,20 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+afterEach(() => {
+  vi.doUnmock("../notify/telegram.js");
+  vi.resetModules();
+});
+
+describe("core root exports", () => {
+  it("does not load Telegram notification transport during root import", async () => {
+    vi.resetModules();
+    vi.doMock("../notify/telegram.js", () => {
+      throw new Error("telegram module should not load during root import");
+    });
+
+    const core = await import("../index.js");
+
+    expect(core).toHaveProperty("PipelineRunner");
+    expect(core).toHaveProperty("sendTelegram");
+  }, 10_000);
+});