@zwbigi/ink-xy 0.1.2 → 0.1.4

package/inkos/packages/core/src/state/state-projections.ts

@@ -0,0 +1,255 @@
+import type {
+  ChapterSummariesState,
+  CurrentStateState,
+  HooksState,
+} from "../models/runtime-state.js";
+import {
+  localizeHookPayoffTiming,
+  resolveHookPayoffTiming,
+} from "../utils/hook-lifecycle.js";
+import {
+  computeHookDiagnostics,
+  renderHookDiagnosticMarker,
+} from "../utils/hook-stale-detection.js";
+
+export function renderHooksProjection(
+  state: HooksState,
+  language: "zh" | "en" = "zh",
+  options?: { readonly currentChapter?: number },
+): string {
+  const title = language === "en" ? "# Pending Hooks" : "# 伏笔池";
+  // Phase 7 + hotfixes 1 & 2: depends_on / pays_off_in_arc / core_hook / half_life / promoted
+  // are visible columns, so writer and reviewer both see the causal chain, planned payoff arc,
+  // stale threshold, and promotion flag. stale / blocked diagnostic flags are appended to the
+  // status cell.
+  const headers = language === "en"
+    ? [
+      "| hook_id | start_chapter | type | status | last_advanced_chapter | expected_payoff | payoff_timing | depends_on | pays_off_in_arc | core_hook | half_life | promoted | notes |",
+      "| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |",
+    ]
+    : [
+      "| hook_id | 起始章节 | 类型 | 状态 | 最近推进 | 预期回收 | 回收节奏 | 上游依赖 | 回收卷 | 核心 | 半衰期 | 升级 | 备注 |",
+      "| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |",
+    ];
+
+  const currentChapter = options?.currentChapter;
+  const diagnostics = typeof currentChapter === "number"
+    ? computeHookDiagnostics({ hooks: state.hooks, currentChapter })
+    : null;
+
+  const rows = [...state.hooks]
+    .sort((left, right) => (
+      left.startChapter - right.startChapter
+      || left.lastAdvancedChapter - right.lastAdvancedChapter
+      || left.hookId.localeCompare(right.hookId)
+    ))
+    .map((hook) => {
+      const diag = diagnostics?.get(hook.hookId);
+      const marker = diag ? renderHookDiagnosticMarker(diag, language) : "";
+      const statusCell = marker
+        ? `${hook.status} (${marker})`
+        : hook.status;
+      return `| ${
+        [
+          hook.hookId,
+          hook.startChapter,
+          hook.type,
+          statusCell,
+          hook.lastAdvancedChapter,
+          hook.expectedPayoff,
+          localizeHookPayoffTiming(resolveHookPayoffTiming(hook), language),
+          renderDependsOnCell(hook.dependsOn ?? [], language),
+          hook.paysOffInArc ?? "",
+          renderCoreHookCell(hook.coreHook === true, language),
+          renderHalfLifeCell(hook.halfLifeChapters),
+          renderPromotedCell(hook.promoted, language),
+          hook.notes,
+        ].map(escapeTableCell).join(" | ")
+      } |`;
+    });
+
+  return [title, "", ...headers, ...rows, ""].join("\n");
+}
+
+function renderDependsOnCell(ids: ReadonlyArray<string>, language: "zh" | "en"): string {
+  if (ids.length === 0) return language === "en" ? "none" : "无";
+  return `[${ids.join(", ")}]`;
+}
+
+function renderCoreHookCell(isCore: boolean, language: "zh" | "en"): string {
+  if (language === "en") return isCore ? "true" : "false";
+  return isCore ? "是" : "否";
+}
+
+function renderHalfLifeCell(value: number | undefined): string {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return "";
+  return String(Math.trunc(value));
+}
+
+function renderPromotedCell(value: boolean | undefined, language: "zh" | "en"): string {
+  if (value === undefined) return "";
+  if (language === "en") return value ? "true" : "false";
+  return value ? "是" : "否";
+}
+
+export function renderChapterSummariesProjection(
+  state: ChapterSummariesState,
+  language: "zh" | "en" = "zh",
+): string {
+  const title = language === "en" ? "# Chapter Summaries" : "# 章节摘要";
+  const headers = language === "en"
+    ? [
+      "| Chapter | Title | Characters | Key Events | State Changes | Hook Activity | Mood | Chapter Type |",
+      "| --- | --- | --- | --- | --- | --- | --- | --- |",
+    ]
+    : [
+      "| 章节 | 标题 | 出场人物 | 关键事件 | 状态变化 | 伏笔动态 | 情绪基调 | 章节类型 |",
+      "| --- | --- | --- | --- | --- | --- | --- | --- |",
+    ];
+
+  const rows = [...state.rows]
+    .sort((left, right) => left.chapter - right.chapter)
+    .map((summary) => `| ${
+      [
+        summary.chapter,
+        summary.title,
+        summary.characters,
+        summary.events,
+        summary.stateChanges,
+        summary.hookActivity,
+        summary.mood,
+        summary.chapterType,
+      ].map(escapeTableCell).join(" | ")
+    } |`);
+
+  return [title, "", ...headers, ...rows, ""].join("\n");
+}
+
+export function renderCurrentStateProjection(
+  state: CurrentStateState,
+  language: "zh" | "en" = "zh",
+): string {
+  const layout = language === "en"
+    ? {
+      title: "# Current State",
+      tableHeader: "| Field | Value |",
+      labels: {
+        chapter: "Current Chapter",
+        location: "Current Location",
+        protagonistState: "Protagonist State",
+        goal: "Current Goal",
+        constraint: "Current Constraint",
+        alliances: "Current Alliances",
+        conflict: "Current Conflict",
+      },
+      placeholders: "(not set)",
+      additionalTitle: "## Additional State",
+    }
+    : {
+      title: "# 当前状态",
+      tableHeader: "| 字段 | 值 |",
+      labels: {
+        chapter: "当前章节",
+        location: "当前位置",
+        protagonistState: "主角状态",
+        goal: "当前目标",
+        constraint: "当前限制",
+        alliances: "当前敌我",
+        conflict: "当前冲突",
+      },
+      placeholders: "（未设定）",
+      additionalTitle: "## 其他状态",
+    };
+
+  const slots = [
+    {
+      label: layout.labels.location,
+      aliases: ["Current Location", "当前位置"],
+    },
+    {
+      label: layout.labels.protagonistState,
+      aliases: ["Protagonist State", "主角状态"],
+    },
+    {
+      label: layout.labels.goal,
+      aliases: ["Current Goal", "当前目标"],
+    },
+    {
+      label: layout.labels.constraint,
+      aliases: ["Current Constraint", "当前限制"],
+    },
+    {
+      label: layout.labels.alliances,
+      aliases: ["Current Alliances", "Current Relationships", "当前敌我"],
+    },
+    {
+      label: layout.labels.conflict,
+      aliases: ["Current Conflict", "当前冲突"],
+    },
+  ] as const;
+
+  const knownPredicates = new Set(
+    slots.flatMap((slot) => slot.aliases.map(normalizePredicate)),
+  );
+  const lines = [
+    layout.title,
+    "",
+    layout.tableHeader,
+    "| --- | --- |",
+    `| ${layout.labels.chapter} | ${escapeTableCell(state.chapter)} |`,
+    ...slots.map((slot) => {
+      const value = findFactValue(state, slot.aliases) ?? layout.placeholders;
+      return `| ${slot.label} | ${escapeTableCell(value)} |`;
+    }),
+  ];
+
+  const additionalFacts = [...state.facts]
+    .filter((fact) => !knownPredicates.has(normalizePredicate(fact.predicate)))
+    .sort((left, right) => compareAdditionalFacts(left.predicate, right.predicate));
+
+  if (additionalFacts.length === 0) {
+    return [...lines, ""].join("\n");
+  }
+
+  return [
+    ...lines,
+    "",
+    layout.additionalTitle,
+    ...additionalFacts.map((fact) => renderAdditionalFact(fact.predicate, fact.object)),
+    "",
+  ].join("\n");
+}
+
+function findFactValue(
+  state: CurrentStateState,
+  aliases: ReadonlyArray<string>,
+): string | undefined {
+  const aliasSet = new Set(aliases.map(normalizePredicate));
+  return state.facts.find((fact) => aliasSet.has(normalizePredicate(fact.predicate)))?.object;
+}
+
+function renderAdditionalFact(predicate: string, object: string): string {
+  if (/^note_\d+$/i.test(predicate)) {
+    return `- ${object}`;
+  }
+  return `- ${predicate}: ${object}`;
+}
+
+function compareAdditionalFacts(left: string, right: string): number {
+  const leftNote = left.match(/^note_(\d+)$/i);
+  const rightNote = right.match(/^note_(\d+)$/i);
+  if (leftNote && rightNote) {
+    return Number.parseInt(leftNote[1] ?? "0", 10) - Number.parseInt(rightNote[1] ?? "0", 10);
+  }
+  if (leftNote) return -1;
+  if (rightNote) return 1;
+  return left.localeCompare(right);
+}
+
+function normalizePredicate(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+function escapeTableCell(value: string | number): string {
+  return String(value).replace(/\|/g, "\\|").trim();
+}

package/inkos/packages/core/src/state/state-reducer.ts

@@ -0,0 +1,260 @@
+import {
+  ChapterSummariesStateSchema,
+  CurrentStateStateSchema,
+  HooksStateSchema,
+  RuntimeStateDeltaSchema,
+  StateManifestSchema,
+  type HookRecord,
+  type ChapterSummariesState,
+  type CurrentStateState,
+  type HooksState,
+  type RuntimeStateDelta,
+  type StateManifest,
+} from "../models/runtime-state.js";
+import { evaluateHookAdmission } from "../utils/hook-governance.js";
+import { resolveHookPayoffTiming } from "../utils/hook-lifecycle.js";
+import { validateRuntimeState } from "./state-validator.js";
+
+export interface RuntimeStateSnapshot {
+  readonly manifest: StateManifest;
+  readonly currentState: CurrentStateState;
+  readonly hooks: HooksState;
+  readonly chapterSummaries: ChapterSummariesState;
+}
+
+export function applyRuntimeStateDelta(params: {
+  readonly snapshot: RuntimeStateSnapshot;
+  readonly delta: RuntimeStateDelta;
+  readonly allowReapply?: boolean;
+}): RuntimeStateSnapshot {
+  const snapshot = {
+    manifest: StateManifestSchema.parse(params.snapshot.manifest),
+    currentState: CurrentStateStateSchema.parse(params.snapshot.currentState),
+    hooks: HooksStateSchema.parse(params.snapshot.hooks),
+    chapterSummaries: ChapterSummariesStateSchema.parse(params.snapshot.chapterSummaries),
+  };
+  const delta = RuntimeStateDeltaSchema.parse(params.delta);
+  const allowReapply = params.allowReapply ?? false;
+
+  if (allowReapply ? delta.chapter < snapshot.manifest.lastAppliedChapter : delta.chapter <= snapshot.manifest.lastAppliedChapter) {
+    throw new Error(`delta chapter ${delta.chapter} goes backwards`);
+  }
+
+  if (delta.chapterSummary && delta.chapterSummary.chapter !== delta.chapter) {
+    throw new Error(`chapter summary ${delta.chapterSummary.chapter} does not match delta chapter ${delta.chapter}`);
+  }
+
+  if (
+    delta.chapterSummary
+    && snapshot.chapterSummaries.rows.some((row) => row.chapter === delta.chapterSummary?.chapter)
+    && !allowReapply
+  ) {
+    throw new Error(`duplicate summary row for chapter ${delta.chapterSummary.chapter}`);
+  }
+
+  const hooks = applyHookOps(snapshot.hooks, delta);
+  const currentState = applyCurrentStatePatch(
+    snapshot.currentState,
+    snapshot.manifest.language,
+    delta,
+  );
+  const chapterSummaries = applySummaryDelta(snapshot.chapterSummaries, delta, allowReapply);
+
+  const next: RuntimeStateSnapshot = {
+    manifest: {
+      ...snapshot.manifest,
+      lastAppliedChapter: delta.chapter,
+    },
+    currentState,
+    hooks,
+    chapterSummaries,
+  };
+
+  const issues = validateRuntimeState(next);
+  if (issues.length > 0) {
+    throw new Error(issues.map((issue) => `${issue.code}: ${issue.message}`).join("; "));
+  }
+
+  return next;
+}
+
+function applyHookOps(hooksState: HooksState, delta: RuntimeStateDelta): HooksState {
+  const hooksById = new Map(hooksState.hooks.map((hook) => [hook.hookId, { ...hook }]));
+
+  for (const hook of delta.hookOps.upsert) {
+    if (!hooksById.has(hook.hookId)) {
+      const admission = evaluateHookAdmission({
+        candidate: {
+          type: hook.type,
+          expectedPayoff: hook.expectedPayoff,
+          notes: hook.notes,
+        },
+        activeHooks: [...hooksById.values()].filter((candidate) => candidate.status !== "resolved"),
+      });
+
+      if (!admission.admit && admission.reason === "duplicate_family") {
+        const matchedHookId = admission.matchedHookId;
+        const existing = matchedHookId ? hooksById.get(matchedHookId) : undefined;
+        if (!existing) {
+          throw new Error(`duplicate active hook family: ${hook.hookId} overlaps ${admission.matchedHookId}`);
+        }
+        hooksById.set(existing.hookId, mergeDuplicateHookFamily(existing, hook));
+        continue;
+      }
+    }
+
+    hooksById.set(hook.hookId, { ...hook });
+  }
+
+  for (const hookId of delta.hookOps.resolve) {
+    const existing = hooksById.get(hookId);
+    if (!existing) {
+      // Hook may have been cleared by a previous settlement or not yet created — skip gracefully
+      continue;
+    }
+    hooksById.set(hookId, {
+      ...existing,
+      status: "resolved",
+      lastAdvancedChapter: Math.max(existing.lastAdvancedChapter, delta.chapter),
+    });
+  }
+
+  for (const hookId of delta.hookOps.defer) {
+    const existing = hooksById.get(hookId);
+    if (!existing) {
+      continue;
+    }
+    hooksById.set(hookId, {
+      ...existing,
+      status: "deferred",
+      lastAdvancedChapter: Math.max(existing.lastAdvancedChapter, delta.chapter),
+    });
+  }
+
+  return {
+    hooks: [...hooksById.values()].sort((left, right) => (
+      left.startChapter - right.startChapter
+      || left.lastAdvancedChapter - right.lastAdvancedChapter
+      || left.hookId.localeCompare(right.hookId)
+    )),
+  };
+}
+
+function mergeDuplicateHookFamily(existing: HookRecord, incoming: HookRecord): HookRecord {
+  const expectedPayoff = preferRicherText(existing.expectedPayoff, incoming.expectedPayoff);
+  const notes = preferRicherText(existing.notes, incoming.notes);
+  const advanced = Math.max(existing.lastAdvancedChapter, incoming.lastAdvancedChapter);
+  const progressed = advanced > existing.lastAdvancedChapter;
+
+  return {
+    ...existing,
+    startChapter: Math.min(existing.startChapter, incoming.startChapter),
+    type: preferRicherText(existing.type, incoming.type),
+    status: progressed
+      ? "progressing"
+      : existing.status === "progressing" || incoming.status === "progressing"
+        ? "progressing"
+        : existing.status,
+    lastAdvancedChapter: advanced,
+    expectedPayoff,
+    payoffTiming: resolveHookPayoffTiming({
+      payoffTiming: incoming.payoffTiming ?? existing.payoffTiming,
+      expectedPayoff,
+      notes,
+    }),
+    notes,
+  };
+}
+
+function preferRicherText(primary: string, fallback: string): string {
+  const left = primary.trim();
+  const right = fallback.trim();
+
+  if (!left) return right;
+  if (!right) return left;
+  if (left === right) return left;
+  return right.length > left.length ? right : left;
+}
+
+function applyCurrentStatePatch(
+  currentState: CurrentStateState,
+  language: "zh" | "en",
+  delta: RuntimeStateDelta,
+): CurrentStateState {
+  if (!delta.currentStatePatch) {
+    return {
+      chapter: delta.chapter,
+      facts: [...currentState.facts],
+    };
+  }
+
+  const nextFacts = [...currentState.facts];
+  const labels = language === "en"
+    ? {
+      currentLocation: ["Current Location", "当前位置"],
+      protagonistState: ["Protagonist State", "主角状态"],
+      currentGoal: ["Current Goal", "当前目标"],
+      currentConstraint: ["Current Constraint", "当前限制"],
+      currentAlliances: ["Current Alliances", "Current Relationships", "当前敌我"],
+      currentConflict: ["Current Conflict", "当前冲突"],
+    }
+    : {
+      currentLocation: ["当前位置", "Current Location"],
+      protagonistState: ["主角状态", "Protagonist State"],
+      currentGoal: ["当前目标", "Current Goal"],
+      currentConstraint: ["当前限制", "Current Constraint"],
+      currentAlliances: ["当前敌我", "Current Alliances", "Current Relationships"],
+      currentConflict: ["当前冲突", "Current Conflict"],
+    };
+
+  for (const [patchKey, aliases] of Object.entries(labels) as Array<[
+    keyof typeof labels,
+    string[],
+  ]>) {
+    const value = delta.currentStatePatch[patchKey];
+    if (value === undefined) continue;
+
+    for (let index = nextFacts.length - 1; index >= 0; index -= 1) {
+      const predicate = nextFacts[index]?.predicate ?? "";
+      if (aliases.some((alias) => alias.toLowerCase() === predicate.toLowerCase())) {
+        nextFacts.splice(index, 1);
+      }
+    }
+
+    nextFacts.push({
+      subject: "protagonist",
+      predicate: aliases[0]!,
+      object: value,
+      validFromChapter: delta.chapter,
+      validUntilChapter: null,
+      sourceChapter: delta.chapter,
+    });
+  }
+
+  return {
+    chapter: delta.chapter,
+    facts: nextFacts.sort((left, right) => (
+      left.predicate.localeCompare(right.predicate)
+      || left.object.localeCompare(right.object)
+    )),
+  };
+}
+
+function applySummaryDelta(
+  state: ChapterSummariesState,
+  delta: RuntimeStateDelta,
+  allowReapply = false,
+): ChapterSummariesState {
+  if (!delta.chapterSummary) {
+    return {
+      rows: [...state.rows].sort((left, right) => left.chapter - right.chapter),
+    };
+  }
+
+  return {
+    rows: [
+      ...(allowReapply ? state.rows.filter((row) => row.chapter !== delta.chapterSummary!.chapter) : state.rows),
+      delta.chapterSummary,
+    ].sort((left, right) => left.chapter - right.chapter),
+  };
+}

package/inkos/packages/core/src/state/state-validator.ts

@@ -0,0 +1,117 @@
+import {
+  ChapterSummariesStateSchema,
+  CurrentStateStateSchema,
+  HooksStateSchema,
+  StateManifestSchema,
+} from "../models/runtime-state.js";
+
+export interface RuntimeStateValidationIssue {
+  readonly code: string;
+  readonly message: string;
+  readonly path?: string;
+}
+
+export function validateRuntimeState(input: {
+  readonly manifest: unknown;
+  readonly currentState: unknown;
+  readonly hooks: unknown;
+  readonly chapterSummaries: unknown;
+}): RuntimeStateValidationIssue[] {
+  try {
+    const issues: RuntimeStateValidationIssue[] = [];
+
+    const manifest = parseOrIssue(
+      StateManifestSchema,
+      input.manifest,
+      issues,
+      "invalid_manifest",
+      "manifest",
+    );
+    const currentState = parseOrIssue(
+      CurrentStateStateSchema,
+      input.currentState,
+      issues,
+      "invalid_current_state",
+      "currentState",
+    );
+    const hooks = parseOrIssue(
+      HooksStateSchema,
+      input.hooks,
+      issues,
+      "invalid_hooks_state",
+      "hooks",
+    );
+    const chapterSummaries = parseOrIssue(
+      ChapterSummariesStateSchema,
+      input.chapterSummaries,
+      issues,
+      "invalid_chapter_summaries_state",
+      "chapterSummaries",
+    );
+
+    if (hooks) {
+      const seen = new Set<string>();
+      for (const hook of hooks.hooks) {
+        if (seen.has(hook.hookId)) {
+          issues.push({
+            code: "duplicate_hook_id",
+            message: `duplicate hook id: ${hook.hookId}`,
+            path: `hooks.${hook.hookId}`,
+          });
+        }
+        seen.add(hook.hookId);
+      }
+    }
+
+    if (chapterSummaries) {
+      const seen = new Set<number>();
+      for (const row of chapterSummaries.rows) {
+        if (seen.has(row.chapter)) {
+          issues.push({
+            code: "duplicate_summary_chapter",
+            message: `duplicate summary chapter: ${row.chapter}`,
+            path: `chapterSummaries.${row.chapter}`,
+          });
+        }
+        seen.add(row.chapter);
+      }
+    }
+
+    if (manifest && currentState && currentState.chapter > manifest.lastAppliedChapter) {
+      issues.push({
+        code: "current_state_ahead_of_manifest",
+        message: `current state chapter ${currentState.chapter} exceeds manifest ${manifest.lastAppliedChapter}`,
+        path: "currentState.chapter",
+      });
+    }
+
+    return issues;
+  } catch (error) {
+    return [
+      {
+        code: "validator_crash",
+        message: String(error),
+        path: "",
+      },
+    ];
+  }
+}
+
+function parseOrIssue<T>(
+  schema: { parse(value: unknown): T },
+  value: unknown,
+  issues: RuntimeStateValidationIssue[],
+  code: string,
+  path: string,
+): T | undefined {
+  try {
+    return schema.parse(value);
+  } catch (error) {
+    issues.push({
+      code,
+      message: String(error),
+      path,
+    });
+    return undefined;
+  }
+}