@zwbigi/ink-xy 0.1.2 → 0.1.4

package/inkos/packages/core/src/__tests__/governed-working-set.test.ts

@@ -0,0 +1,155 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildGovernedCharacterMatrixWorkingSet,
+  buildGovernedHookWorkingSet,
+} from "../utils/governed-working-set.js";
+
+describe("governed-working-set", () => {
+  it("filters out far-future hooks from the governed hook working set", () => {
+    const hooks = [
+      "| hook_id | 起始章节 | 类型 | 状态 | 最近推进 | 预期回收 | 备注 |",
+      "| --- | --- | --- | --- | --- | --- | --- |",
+      "| opening-call | 1 | mystery | open | 0 | 8 | 匿名来电开篇出现 |",
+      "| nearby-ledger | 4 | evidence | open | 0 | 12 | 近期开启的账本线 |",
+      "| future-pr-machine | 22 | conspiracy | open | 0 | 60 | 远期舆情操盘线 |",
+      "| future-template | 45 | system | open | 0 | 80 | 远期系统性话术线 |",
+    ].join("\n");
+
+    const filtered = buildGovernedHookWorkingSet({
+      hooksMarkdown: hooks,
+      contextPackage: {
+        chapter: 1,
+        selectedContext: [
+          {
+            source: "story/pending_hooks.md#opening-call",
+            reason: "Current chapter opening hook.",
+            excerpt: "mystery | open | 8 | 匿名来电开篇出现",
+          },
+        ],
+      },
+      chapterNumber: 1,
+      language: "zh",
+    });
+
+    expect(filtered).toContain("opening-call");
+    expect(filtered).toContain("nearby-ledger");
+    expect(filtered).not.toContain("future-pr-machine");
+    expect(filtered).not.toContain("future-template");
+  });
+
+  it("includes hook agenda debt items even when they are not selected or recent", () => {
+    const hooks = [
+      "| hook_id | start_chapter | type | status | last_advanced | expected_payoff | notes |",
+      "| --- | --- | --- | --- | --- | --- | --- |",
+      "| mentor-oath | 8 | relationship | open | 99 | 101 | Mentor oath debt with Lin Yue |",
+      "| stale-ledger | 14 | mystery | open | 70 | 120 | Old ledger debt is dormant but unresolved |",
+      "| future-pr-machine | 45 | system | open | 0 | 80 | Future hook should stay hidden |",
+    ].join("\n");
+
+    const filtered = buildGovernedHookWorkingSet({
+      hooksMarkdown: hooks,
+      contextPackage: {
+        chapter: 100,
+        selectedContext: [
+          {
+            source: "story/pending_hooks.md#mentor-oath",
+            reason: "Carry forward unresolved hook.",
+            excerpt: "relationship | open | 101 | Mentor oath debt with Lin Yue",
+          },
+        ],
+      },
+      chapterIntent: [
+        "# Chapter Intent",
+        "",
+        "## Hook Agenda",
+        "### Must Advance",
+        "- mentor-oath",
+        "",
+        "### Eligible Resolve",
+        "- none",
+        "",
+        "### Stale Debt",
+        "- stale-ledger",
+        "",
+        "### Avoid New Hook Families",
+        "- none",
+      ].join("\n"),
+      chapterNumber: 100,
+      language: "en",
+    });
+
+    expect(filtered).toContain("mentor-oath");
+    expect(filtered).toContain("stale-ledger");
+    expect(filtered).not.toContain("future-pr-machine");
+  });
+
+  it("keeps recently-advanced hooks in the governed working set while filtering far-future hooks", () => {
+    const hooks = [
+      "| hook_id | start_chapter | type | status | last_advanced | expected_payoff | payoff_timing | notes |",
+      "| --- | --- | --- | --- | --- | --- | --- | --- |",
+      "| river-oath | 8 | relationship | progressing | 16 | Reveal why the river oath was broken | slow-burn | Long debt should stay visible through the middle game |",
+      "| future-pr-machine | 45 | system | open | 0 | Future hook should stay hidden | endgame | Future hook should stay hidden |",
+    ].join("\n");
+
+    const filtered = buildGovernedHookWorkingSet({
+      hooksMarkdown: hooks,
+      contextPackage: {
+        chapter: 20,
+        selectedContext: [],
+      },
+      chapterNumber: 20,
+      language: "en",
+    });
+
+    expect(filtered).toContain("river-oath");
+    expect(filtered).not.toContain("future-pr-machine");
+  });
+
+  it("filters character matrix by exact governed character mentions instead of broad capitalized tokens", () => {
+    const matrix = [
+      "# Character Matrix",
+      "",
+      "### Character Profiles",
+      "| Character | Core Tags | Contrast Detail | Speech Style | Personality Core | Relationship to Protagonist | Core Motivation | Current Goal |",
+      "| --- | --- | --- | --- | --- | --- | --- | --- |",
+      "| Lin Yue | oath | restraint | clipped | stubborn | self | repay debt | find mentor |",
+      "| Guildmaster Ren | guild | swagger | loud | opportunistic | rival | stall Mara | seize seal |",
+      "",
+      "### Encounter Log",
+      "| Character A | Character B | First Meeting Chapter | Latest Interaction Chapter | Relationship Type | Relationship Change |",
+      "| --- | --- | --- | --- | --- | --- |",
+      "| Lin Yue | Guildmaster Ren | 1 | 5 | rivalry | strained |",
+      "",
+      "### Information Boundaries",
+      "| Character | Known Information | Unknown Information | Source Chapter |",
+      "| --- | --- | --- | --- |",
+      "| Lin Yue | Mentor left without explanation | Why the oath was broken | 99 |",
+      "| Guildmaster Ren | Harbor roster | Mentor oath debt | 12 |",
+    ].join("\n");
+
+    const filtered = buildGovernedCharacterMatrixWorkingSet({
+      matrixMarkdown: matrix,
+      chapterIntent: "# Chapter Intent\n\n## Goal\nBring the focus back to the mentor oath conflict.\n",
+      contextPackage: {
+        chapter: 100,
+        selectedContext: [
+          {
+            source: "story/chapter_summaries.md#99",
+            reason: "Relevant episodic memory.",
+            excerpt: "Locked Gate | Lin Yue chooses the mentor line over the guild line | mentor-oath advanced",
+          },
+          {
+            source: "story/pending_hooks.md#mentor-oath",
+            reason: "Carry forward unresolved hook.",
+            excerpt: "relationship | open | 101 | Mentor oath debt with Lin Yue",
+          },
+        ],
+      },
+    });
+
+    expect(filtered).toContain("| Lin Yue | oath | restraint | clipped | stubborn | self | repay debt | find mentor |");
+    expect(filtered).not.toContain("| Guildmaster Ren | guild | swagger | loud | opportunistic | rival | stall Mara | seize seal |");
+    expect(filtered).not.toContain("| Lin Yue | Guildmaster Ren | 1 | 5 | rivalry | strained |");
+    expect(filtered).not.toContain("| Guildmaster Ren | Harbor roster | Mentor oath debt | 12 |");
+  });
+});

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

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+import type { HookRecord, RuntimeStateDelta } from "../models/runtime-state.js";
+import { arbitrateRuntimeStateDeltaHooks } from "../utils/hook-arbiter.js";
+
+function createHook(overrides: Partial<HookRecord> = {}): HookRecord {
+  return {
+    hookId: overrides.hookId ?? "H001",
+    startChapter: overrides.startChapter ?? 1,
+    type: overrides.type ?? "mystery",
+    status: overrides.status ?? "open",
+    lastAdvancedChapter: overrides.lastAdvancedChapter ?? 1,
+    expectedPayoff: overrides.expectedPayoff ?? "Reveal the hidden ledger",
+    notes: overrides.notes ?? "Still unresolved",
+  };
+}
+
+function createDelta(overrides: Partial<RuntimeStateDelta> = {}): RuntimeStateDelta {
+  return {
+    chapter: overrides.chapter ?? 12,
+    hookOps: {
+      upsert: overrides.hookOps?.upsert ?? [],
+      mention: overrides.hookOps?.mention ?? [],
+      resolve: overrides.hookOps?.resolve ?? [],
+      defer: overrides.hookOps?.defer ?? [],
+    },
+    newHookCandidates: overrides.newHookCandidates ?? [],
+    subplotOps: [],
+    emotionalArcOps: [],
+    characterMatrixOps: [],
+    notes: [],
+  };
+}
+
+describe("arbitrateRuntimeStateDeltaHooks", () => {
+  it("maps a duplicate-family candidate back onto the matched existing hook", () => {
+    const result = arbitrateRuntimeStateDeltaHooks({
+      hooks: [
+        createHook({
+          hookId: "anonymous-source-scope",
+          type: "source-risk",
+          startChapter: 3,
+          lastAdvancedChapter: 8,
+          expectedPayoff: "Reveal how much the anonymous source already knew about the route.",
+          notes: "The source knowledge question remains unresolved.",
+        }),
+      ],
+      delta: createDelta({
+        newHookCandidates: [
+          {
+            type: "source-risk",
+            expectedPayoff: "Reveal how much the anonymous source already knew about the route and address.",
+            notes: "This chapter adds the address angle to the anonymous source question.",
+          },
+        ],
+      }),
+    });
+
+    expect(result.resolvedDelta.hookOps.upsert).toEqual([
+      expect.objectContaining({
+        hookId: "anonymous-source-scope",
+        lastAdvancedChapter: 12,
+      }),
+    ]);
+    expect(result.resolvedDelta.newHookCandidates).toEqual([]);
+  });
+
+  it("downgrades a pure restatement candidate into a mention instead of opening a new hook", () => {
+    const result = arbitrateRuntimeStateDeltaHooks({
+      hooks: [
+        createHook({
+          hookId: "mentor-debt",
+          type: "relationship",
+          expectedPayoff: "Reveal the real mentor debt.",
+          notes: "The mentor debt is still unresolved.",
+        }),
+      ],
+      delta: createDelta({
+        newHookCandidates: [
+          {
+            type: "relationship",
+            expectedPayoff: "Reveal the real mentor debt.",
+            notes: "The mentor debt is still unresolved.",
+          },
+        ],
+      }),
+    });
+
+    expect(result.resolvedDelta.hookOps.upsert).toEqual([]);
+    expect(result.resolvedDelta.hookOps.mention).toContain("mentor-debt");
+    expect(result.resolvedDelta.newHookCandidates).toEqual([]);
+  });
+
+  it("creates a canonical hook when the candidate is genuinely new", () => {
+    const result = arbitrateRuntimeStateDeltaHooks({
+      hooks: [
+        createHook({
+          hookId: "mentor-debt",
+          type: "relationship",
+          expectedPayoff: "Reveal the real mentor debt.",
+        }),
+      ],
+      delta: createDelta({
+        chapter: 15,
+        newHookCandidates: [
+          {
+            type: "artifact",
+            expectedPayoff: "Reveal why the seal answers only at midnight.",
+            notes: "A fresh unresolved rule around the seal appears in this chapter.",
+          },
+        ],
+      }),
+    });
+
+    expect(result.resolvedDelta.hookOps.upsert).toHaveLength(1);
+    expect(result.resolvedDelta.hookOps.upsert[0]).toEqual(expect.objectContaining({
+      startChapter: 15,
+      lastAdvancedChapter: 15,
+      type: "artifact",
+      status: "open",
+    }));
+    expect(result.resolvedDelta.hookOps.upsert[0]?.hookId).not.toBe("mentor-debt");
+    expect(result.resolvedDelta.newHookCandidates).toEqual([]);
+  });
+});

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

@@ -0,0 +1,228 @@
+import { describe, expect, it } from "vitest";
+import type { HookRecord, RuntimeStateDelta } from "../models/runtime-state.js";
+import {
+  classifyHookDisposition,
+  collectStaleHookDebt,
+  evaluateHookAdmission,
+} from "../utils/hook-governance.js";
+
+function createHook(overrides: Partial<HookRecord> = {}): HookRecord {
+  return {
+    hookId: overrides.hookId ?? "H001",
+    startChapter: overrides.startChapter ?? 1,
+    type: overrides.type ?? "mystery",
+    status: overrides.status ?? "open",
+    lastAdvancedChapter: overrides.lastAdvancedChapter ?? 1,
+    expectedPayoff: overrides.expectedPayoff ?? "Reveal the hidden ledger",
+    notes: overrides.notes ?? "The hidden room is still sealed",
+  };
+}
+
+function createDelta(overrides: Partial<RuntimeStateDelta> = {}): RuntimeStateDelta {
+  return {
+    chapter: overrides.chapter ?? 12,
+    hookOps: {
+      upsert: overrides.hookOps?.upsert ?? [],
+      mention: overrides.hookOps?.mention ?? [],
+      resolve: overrides.hookOps?.resolve ?? [],
+      defer: overrides.hookOps?.defer ?? [],
+    },
+    newHookCandidates: overrides.newHookCandidates ?? [],
+    subplotOps: overrides.subplotOps ?? [],
+    emotionalArcOps: overrides.emotionalArcOps ?? [],
+    characterMatrixOps: overrides.characterMatrixOps ?? [],
+    notes: overrides.notes ?? [],
+  };
+}
+
+describe("collectStaleHookDebt", () => {
+  it("returns unresolved stale hooks and excludes resolved or deferred hooks", () => {
+    const result = collectStaleHookDebt({
+      hooks: [
+        createHook({ hookId: "H001", status: "open", lastAdvancedChapter: 3 }),
+        createHook({ hookId: "H002", status: "progressing", lastAdvancedChapter: 8 }),
+        createHook({ hookId: "H003", status: "deferred", lastAdvancedChapter: 1 }),
+        createHook({ hookId: "H004", status: "resolved", lastAdvancedChapter: 2 }),
+      ],
+      chapterNumber: 20,
+      staleAfterChapters: 10,
+    });
+
+    expect(result.map((hook) => hook.hookId)).toEqual(["H001", "H002"]);
+  });
+});
+
+describe("evaluateHookAdmission", () => {
+  const activeHooks = [
+    createHook({
+      hookId: "H019",
+      type: "mystery",
+      expectedPayoff: "Reveal the hidden room behind the correction mark",
+      notes: "The hidden room converts public disputes into standing questions",
+    }),
+  ];
+
+  it("rejects hook candidates without payoff-bearing signal", () => {
+    const decision = evaluateHookAdmission({
+      candidate: {
+        type: "mystery",
+        expectedPayoff: "",
+        notes: "   ",
+      },
+      activeHooks,
+    });
+
+    expect(decision).toEqual({
+      admit: false,
+      reason: "missing_payoff_signal",
+    });
+  });
+
+  it("rejects hook candidates with blank type values", () => {
+    const decision = evaluateHookAdmission({
+      candidate: {
+        type: "   ",
+        expectedPayoff: "Reveal why the witness changed her statement",
+        notes: "A courtroom contradiction keeps widening",
+      },
+      activeHooks,
+    });
+
+    expect(decision).toEqual({
+      admit: false,
+      reason: "missing_type",
+    });
+  });
+
+  it("rejects duplicate or restated hook candidates", () => {
+    const decision = evaluateHookAdmission({
+      candidate: {
+        type: "mystery",
+        expectedPayoff: "Reveal the hidden room behind the correction mark",
+        notes: "The hidden room still reframes public disputes as standing questions",
+      },
+      activeHooks,
+    });
+
+    expect(decision).toEqual({
+      admit: false,
+      reason: "duplicate_family",
+      matchedHookId: "H019",
+    });
+  });
+
+  it("admits materially distinct hook candidates", () => {
+    const decision = evaluateHookAdmission({
+      candidate: {
+        type: "relationship",
+        expectedPayoff: "Expose why the mentor buried the oath",
+        notes: "A separate emotional debt keeps surfacing in private scenes",
+      },
+      activeHooks,
+    });
+
+    expect(decision).toEqual({
+      admit: true,
+      reason: "admit",
+    });
+  });
+
+  it("rejects Chinese paraphrase candidates from the same hook family", () => {
+    const decision = evaluateHookAdmission({
+      candidate: {
+        type: "神秘",
+        expectedPayoff: "弄明白雨夜匿名来电背后是谁",
+        notes: "一下雨就有陌生号码劝她远离旧码头",
+      },
+      activeHooks: [
+        createHook({
+          hookId: "H020",
+          type: "神秘",
+          expectedPayoff: "查出匿名号码为何总在雨夜响起",
+          notes: "每次雨夜都有人用匿名电话提醒她别去旧码头",
+        }),
+      ],
+    });
+
+    expect(decision).toEqual({
+      admit: false,
+      reason: "duplicate_family",
+      matchedHookId: "H020",
+    });
+  });
+});
+
+describe("classifyHookDisposition", () => {
+  it("classifies mention, advance, resolve, and defer with strict priority", () => {
+    expect(classifyHookDisposition({
+      hookId: "H001",
+      delta: createDelta({
+        hookOps: {
+          upsert: [],
+          mention: ["H001"],
+          resolve: [],
+          defer: [],
+        },
+      }),
+    })).toBe("mention");
+
+    expect(classifyHookDisposition({
+      hookId: "H002",
+      delta: createDelta({
+        chapter: 12,
+        hookOps: {
+          upsert: [createHook({ hookId: "H002", lastAdvancedChapter: 12 })],
+          mention: [],
+          resolve: [],
+          defer: [],
+        },
+      }),
+    })).toBe("advance");
+
+    expect(classifyHookDisposition({
+      hookId: "H003",
+      delta: createDelta({
+        hookOps: {
+          upsert: [createHook({ hookId: "H003", lastAdvancedChapter: 12 })],
+          mention: ["H003"],
+          resolve: ["H003"],
+          defer: [],
+        },
+      }),
+    })).toBe("resolve");
+
+    expect(classifyHookDisposition({
+      hookId: "H004",
+      delta: createDelta({
+        hookOps: {
+          upsert: [],
+          mention: ["H004"],
+          resolve: [],
+          defer: ["H004"],
+        },
+      }),
+    })).toBe("defer");
+  });
+
+  it("returns none when the hook is untouched in the chapter delta", () => {
+    expect(classifyHookDisposition({
+      hookId: "H099",
+      delta: createDelta(),
+    })).toBe("none");
+  });
+
+  it("reports defer when resolve and defer both target the same hook", () => {
+    expect(classifyHookDisposition({
+      hookId: "H021",
+      delta: createDelta({
+        chapter: 12,
+        hookOps: {
+          upsert: [createHook({ hookId: "H021", lastAdvancedChapter: 12 })],
+          mention: ["H021"],
+          resolve: ["H021"],
+          defer: ["H021"],
+        },
+      }),
+    })).toBe("defer");
+  });
+});

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

@@ -0,0 +1,166 @@
+import { describe, expect, it } from "vitest";
+import type { HookRecord, RuntimeStateDelta } from "../models/runtime-state.js";
+import { analyzeHookHealth } from "../utils/hook-health.js";
+
+function createHook(overrides: Partial<HookRecord> = {}): HookRecord {
+  return {
+    hookId: overrides.hookId ?? "H001",
+    startChapter: overrides.startChapter ?? 1,
+    type: overrides.type ?? "mystery",
+    status: overrides.status ?? "open",
+    lastAdvancedChapter: overrides.lastAdvancedChapter ?? 1,
+    expectedPayoff: overrides.expectedPayoff ?? "Reveal the hidden ledger",
+    payoffTiming: overrides.payoffTiming,
+    notes: overrides.notes ?? "Still unresolved",
+  };
+}
+
+function createDelta(overrides: Partial<RuntimeStateDelta> = {}): RuntimeStateDelta {
+  return {
+    chapter: overrides.chapter ?? 20,
+    hookOps: {
+      upsert: overrides.hookOps?.upsert ?? [],
+      mention: overrides.hookOps?.mention ?? [],
+      resolve: overrides.hookOps?.resolve ?? [],
+      defer: overrides.hookOps?.defer ?? [],
+    },
+    newHookCandidates: overrides.newHookCandidates ?? [],
+    subplotOps: [],
+    emotionalArcOps: [],
+    characterMatrixOps: [],
+    notes: [],
+  };
+}
+
+describe("analyzeHookHealth", () => {
+  it("warns when active hook count exceeds the recommended cap", () => {
+    const issues = analyzeHookHealth({
+      language: "en",
+      chapterNumber: 20,
+      hooks: [
+        createHook({ hookId: "H001" }),
+        createHook({ hookId: "H002" }),
+        createHook({ hookId: "H003" }),
+        createHook({ hookId: "H004" }),
+        createHook({ hookId: "H005" }),
+      ],
+      maxActiveHooks: 4,
+    });
+
+    expect(issues.some((issue) => issue.category === "Hook Debt" && issue.description.includes("5 active hooks"))).toBe(true);
+  });
+
+  it("warns when a short-payoff hook is already under payoff pressure without real movement", () => {
+    const issues = analyzeHookHealth({
+      language: "en",
+      chapterNumber: 4,
+      hooks: [
+        createHook({
+          hookId: "H001",
+          startChapter: 1,
+          lastAdvancedChapter: 1,
+          payoffTiming: "immediate",
+          expectedPayoff: "Reveal the hidden ledger immediately after the theft.",
+        }),
+      ],
+    });
+
+    expect(issues.some((issue) => issue.description.includes("payoff pressure"))).toBe(true);
+  });
+
+  it("does not warn when only endgame hooks are dormant before the story reaches late phase", () => {
+    const issues = analyzeHookHealth({
+      language: "en",
+      chapterNumber: 20,
+      targetChapters: 40,
+      hooks: [
+        createHook({
+          hookId: "H001",
+          startChapter: 10,
+          lastAdvancedChapter: 15,
+          payoffTiming: "endgame",
+          expectedPayoff: "Final reveal in the endgame.",
+        }),
+      ],
+    });
+
+    expect(issues).toHaveLength(0);
+  });
+
+  it("warns when stale hooks receive no disposition in the current chapter", () => {
+    const issues = analyzeHookHealth({
+      language: "en",
+      chapterNumber: 20,
+      hooks: [
+        createHook({ hookId: "H001", lastAdvancedChapter: 5 }),
+        createHook({ hookId: "H002", lastAdvancedChapter: 6 }),
+      ],
+      delta: createDelta({
+        chapter: 20,
+        hookOps: {
+          upsert: [],
+          mention: ["H001"],
+          resolve: [],
+          defer: [],
+        },
+      }),
+      staleAfterChapters: 10,
+    });
+
+    expect(issues.some((issue) => issue.description.includes("H001") || issue.description.includes("H002"))).toBe(true);
+  });
+
+  it("warns when multiple new hooks open without resolving older debt", () => {
+    const issues = analyzeHookHealth({
+      language: "en",
+      chapterNumber: 20,
+      hooks: [
+        createHook({ hookId: "old-debt", lastAdvancedChapter: 8 }),
+        createHook({ hookId: "new-a", startChapter: 20, lastAdvancedChapter: 20 }),
+        createHook({ hookId: "new-b", startChapter: 20, lastAdvancedChapter: 20 }),
+      ],
+      delta: createDelta({
+        chapter: 20,
+        hookOps: {
+          upsert: [
+            createHook({ hookId: "new-a", startChapter: 20, lastAdvancedChapter: 20 }),
+            createHook({ hookId: "new-b", startChapter: 20, lastAdvancedChapter: 20 }),
+          ],
+          mention: [],
+          resolve: [],
+          defer: [],
+        },
+      }),
+      existingHookIds: ["old-debt"],
+      newHookBurstThreshold: 2,
+    });
+
+    expect(issues.some((issue) => issue.description.includes("Opened 2 new hooks"))).toBe(true);
+  });
+
+  it("does not count absorbed duplicate-family upserts as genuinely new hooks", () => {
+    const issues = analyzeHookHealth({
+      language: "en",
+      chapterNumber: 20,
+      hooks: [
+        createHook({ hookId: "old-debt", lastAdvancedChapter: 20 }),
+      ],
+      delta: createDelta({
+        chapter: 20,
+        hookOps: {
+          upsert: [
+            createHook({ hookId: "duplicate-restated", lastAdvancedChapter: 20 }),
+            createHook({ hookId: "second-duplicate", lastAdvancedChapter: 20 }),
+          ],
+          mention: [],
+          resolve: [],
+          defer: [],
+        },
+      }),
+      existingHookIds: ["old-debt"],
+      newHookBurstThreshold: 2,
+    });
+
+    expect(issues.some((issue) => issue.description.includes("Opened 2 new hooks"))).toBe(false);
+  });
+});