@cloud411716/fancy-webnovel 2.2.0 → 3.0.3

package/plugins/fancy-story-builder/storydb/store.js

@@ -0,0 +1,891 @@
+/**
+ * Story graph store: CRUD, edges, requirements, change sets, decisions,
+ * validation and the work queue.
+ *
+ * All writes go through `apply()` so data + decisions are one transaction.
+ */
+
+import {
+  ENTITIES,
+  EDGES,
+  TABLE_TO_ENTITY,
+  TABLE_TO_EDGE,
+  entityFor,
+  edgeFor,
+} from './definitions.js';
+import {
+  recordLiteral,
+  parseRef,
+  refString,
+  surrealString,
+  uuid,
+} from './ids.js';
+import { StoryDbError, flattenError, STORY_RECORD } from './client.js';
+
+const STORY = 'story:main';
+
+const ID_FIELDS = {
+  volume: 'volume_id',
+  act: 'act_id',
+  line: 'line_id',
+  line_node: 'node_id',
+  ending: 'ending_id',
+  role_slot: 'role_id',
+  chapter: 'chapter_id',
+  outline: 'chapter_id',
+  chapter_text: 'chapter_id',
+  handoff: 'chapter_id',
+};
+
+const SINGLETONS = {
+  story: 'main',
+  scale: 'main',
+  world_doc: 'world',
+  story_doc: 'story',
+  emotion_doc: 'emotion',
+};
+
+function defOf(kind) {
+  return ENTITIES[kind] || TABLE_TO_ENTITY[kind] || null;
+}
+
+function edgeOf(kind) {
+  return EDGES[kind] || TABLE_TO_EDGE[kind] || null;
+}
+
+function fail(code, message, detail) {
+  throw new StoryDbError(code, message, detail);
+}
+
+export function entityKey(kind) {
+  const def = defOf(kind);
+  if (!def) fail('UNKNOWN_KIND', '未知实体：' + kind);
+  return def.table;
+}
+
+export function normalizeKind(kind) {
+  const def = defOf(kind);
+  if (!def) fail('UNKNOWN_KIND', '未知实体：' + kind);
+  return def.table;
+}
+
+// ---------------------------------------------------------------------------
+// field validation
+// ---------------------------------------------------------------------------
+
+function checkValue(field, value) {
+  if (value === undefined || value === null) return null;
+  switch (field.type) {
+    case 'string':
+    case 'text':
+      if (typeof value !== 'string') return '必须是字符串';
+      if (field.required && !value.trim()) return '不能为空';
+      return null;
+    case 'int':
+      if (!Number.isInteger(Number(value))) return '必须是整数';
+      return null;
+    case 'float':
+      if (!Number.isFinite(Number(value))) return '必须是数字';
+      return null;
+    case 'bool':
+      if (typeof value !== 'boolean') return '必须是布尔值';
+      return null;
+    case 'datetime':
+      if (typeof value !== 'string' && !(value instanceof Date)) return '必须是日期时间';
+      return null;
+    case 'array':
+      if (!Array.isArray(value)) return '必须是数组';
+      if (field.required && field.nonEmpty && value.length === 0) return '不能为空数组';
+      return null;
+    case 'object':
+      if (typeof value !== 'object' || Array.isArray(value)) return '必须是对象';
+      return null;
+    case 'record':
+      if (typeof value !== 'string') return '必须是记录 ID 字符串';
+      return null;
+    case 'enum':
+      if (!field.values.includes(value)) return '必须是 ' + field.values.join(' / ');
+      return null;
+    default:
+      return null;
+  }
+}
+
+export function validateData(kind, data, opts = {}) {
+  const def = ENTITIES[kind] || EDGES[kind] || TABLE_TO_ENTITY[kind] || TABLE_TO_EDGE[kind];
+  if (!def) fail('UNKNOWN_KIND', '未知实体：' + kind);
+  const errors = [];
+  const partial = Boolean(opts.partial);
+  for (const [name, field] of Object.entries(def.fields || {})) {
+    const value = data[name];
+    if (value === undefined || value === null || value === '') {
+      if (!partial && field.required) {
+        errors.push({ field: name, code: 'REQUIRED', message: name + ' 必填' });
+      }
+      continue;
+    }
+    const msg = checkValue(field, value);
+    if (msg) errors.push({ field: name, code: 'TYPE', message: name + ' ' + msg });
+  }
+  return errors;
+}
+
+function normalizeData(kind, data) {
+  const def = defOf(kind);
+  const out = { ...data };
+  for (const [name, field] of Object.entries(def.fields || {})) {
+    if (out[name] === undefined || out[name] === null) {
+      if (field.default !== undefined) out[name] = field.default;
+      else if (field.type === 'array') out[name] = [];
+      else if (field.type === 'object') out[name] = {};
+    }
+  }
+  if (out.status === undefined) out.status = 'seed';
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// ids
+// ---------------------------------------------------------------------------
+
+export function idFor(kind, data) {
+  const def = defOf(kind);
+  if (SINGLETONS[kind]) return SINGLETONS[kind];
+  if (ID_FIELDS[kind]) {
+    const value = data[ID_FIELDS[kind]] || data.id || data.entity_id;
+    if (!value) fail('ID_REQUIRED', kind + ' 缺少 ' + ID_FIELDS[kind]);
+    return String(value);
+  }
+  if (kind === 'scene') {
+    if (!data.outline_id) fail('ID_REQUIRED', 'scene 缺少 outline_id');
+    return 'SC_' + String(data.outline_id) + '_' + String(data.scene_order || 0);
+  }
+  if (data.id || data.entity_id) return String(data.id || data.entity_id);
+  fail('ID_REQUIRED', kind + ' 缺少 id');
+  return null;
+}
+
+function fieldsForWrite(kind, data) {
+  const def = ENTITIES[kind] || EDGES[kind] || TABLE_TO_ENTITY[kind] || TABLE_TO_EDGE[kind];
+  const out = {};
+  for (const name of Object.keys(def.fields || {})) {
+    if (data[name] !== undefined) out[name] = data[name];
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// requirements
+// ---------------------------------------------------------------------------
+
+async function ensureRequirements(sdb, kind, id, data) {
+  const def = defOf(kind);
+  if (!def || !def.requirements || !def.requirements.length) return;
+  const subject = def.table + ':' + id;
+  const existing = await sdb.rows(
+    `SELECT * FROM requirement WHERE story = ${STORY} AND subject = $subject;`,
+    { subject },
+  );
+  const have = new Set(existing.map((row) => row.kind));
+  for (const req of def.requirements) {
+    if (have.has(req.kind)) continue;
+    const due = req.due === 'chapter'
+      ? (data.due_chapter !== undefined ? Number(data.due_chapter) : undefined)
+      : undefined;
+    await sdb.query(
+      `UPSERT type::record('requirement:⟨' + $id + '⟩') SET
+         story = ${STORY},
+         kind = $kind,
+         subject = $subject,
+         status = 'pending',
+         hard = $hard,
+         due_chapter = $due_chapter,
+         label = $label,
+         payload = {};`,
+      {
+        id: uuid(),
+        kind: req.kind,
+        subject,
+        hard: req.hard !== false,
+        due_chapter: due,
+        label: req.label || req.kind,
+      },
+    );
+  }
+}
+
+export async function requirementsFor(sdb, subject) {
+  return sdb.rows(
+    `SELECT * FROM requirement WHERE story = ${STORY} AND subject = $subject ORDER BY kind;`,
+    { subject },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// CRUD
+// ---------------------------------------------------------------------------
+
+async function upsertChapterMetric(sdb, chapterId, displayNo, data) {
+  const chapLit = recordLiteral('chapter', chapterId);
+  await sdb.query(
+    `UPSERT chapter_metric SET
+       story = ${STORY},
+       chapter = ${chapLit},
+       chapter_no = $chapter_no,
+       emotion_value = $emotion_value,
+       hook_strength = $hook_strength,
+       word_target = $word_target
+     WHERE story = ${STORY} AND chapter_no = $chapter_no;`,
+    {
+      chapter_no: Number(displayNo),
+      emotion_value: Number(data.emotion && data.emotion.value) || undefined,
+      hook_strength: data.hook && data.hook.strength || undefined,
+      word_target: Number(data.word_target) || 0,
+    },
+  );
+}
+
+async function resetKnowledgeState(sdb, charLit, subject, state) {
+  await sdb.query(
+    `DELETE knowledge_state WHERE story = ${STORY}
+       AND character = ${charLit} AND subject_type = $subject_type AND subject_id = $subject_id;`,
+    subject,
+  );
+  if (state) {
+    await sdb.query(
+      `CREATE knowledge_state SET story = ${STORY},
+         character = ${charLit}, subject_type = $subject_type,
+         subject_id = $subject_id, state = $state;`,
+      { ...subject, state },
+    );
+  }
+}
+
+/**
+ * Write one knowledge change. Re-submitting the same chapter + character +
+ * subject replaces that chapter's event instead of appending a duplicate; the
+ * materialized `knowledge_state` is recomputed before and after the write so
+ * earlier-chapter rewrites do not trip the chronology guard.
+ */
+export async function addKnowledgeEvent(sdb, input) {
+  const data = input || {};
+  if (!data.chapter_id && !data.chapter) fail('VALIDATION', 'knowledge_event 缺少 chapter_id');
+  if (!data.subject_id || !data.character_id) fail('VALIDATION', 'knowledge_event 缺少 subject_id / character_id');
+  const chapterId = data.chapter_id || String(data.chapter).split(':').pop();
+  let chapterNo = Number(data.chapter_no);
+  if (!chapterNo) {
+    const chapter = await sdb.one(
+      `SELECT display_no FROM chapter WHERE story = ${STORY} AND chapter_id = $id LIMIT 1;`,
+      { id: chapterId },
+    );
+    if (!chapter) fail('BAD_REF', '章节不存在：chapter:' + chapterId);
+    chapterNo = Number(chapter.display_no);
+  }
+  const sourceId = data.source_character_id || (data.source_character ? String(data.source_character).split(':').pop() : null);
+  const sourceExpr = sourceId ? recordLiteral('character', sourceId) : 'NONE';
+  const chapterLit = recordLiteral('chapter', chapterId);
+  const charLit = recordLiteral('character', data.character_id);
+  const subject = {
+    subject_type: data.subject_type || 'information',
+    subject_id: String(data.subject_id),
+  };
+  const key = {
+    ...subject,
+    chapter_no: chapterNo,
+  };
+
+  // A chapter rewrite replaces its own knowledge event, not appends another.
+  await sdb.query(
+    `DELETE knowledge_event WHERE story = ${STORY} AND chapter = ${chapterLit}
+       AND character = ${charLit} AND subject_type = $subject_type AND subject_id = $subject_id;`,
+    subject,
+  );
+
+  // The chronology guard must see the state as of the previous chapter, even
+  // when events from later chapters already exist.
+  const before = await sdb.rows(
+    `SELECT coverage FROM knowledge_event WHERE story = ${STORY}
+       AND character = ${charLit} AND subject_type = $subject_type AND subject_id = $subject_id
+       AND chapter_no < $chapter_no
+       ORDER BY chapter_no DESC, created_at DESC LIMIT 1;`,
+    key,
+  );
+  await resetKnowledgeState(sdb, charLit, subject, before[0] ? before[0].coverage : null);
+
+  await sdb.query(
+    `CREATE knowledge_event SET
+       story = ${STORY},
+       chapter = ${chapterLit},
+       chapter_no = $chapter_no,
+       subject_type = $subject_type,
+       subject_id = $subject_id,
+       character = ${charLit},
+       character_id = $character_id,
+       change = $change,
+       coverage = $coverage,
+       knowledge = $knowledge,
+       how = $how,
+       source_character = ${sourceExpr},
+       scene = $scene,
+       evidence = $evidence,
+       payload = {};`,
+    {
+      ...key,
+      character_id: String(data.character_id),
+      change: data.change || 'learns',
+      coverage: data.coverage || 'partial',
+      knowledge: data.knowledge || '',
+      how: data.how || 'other',
+      scene: data.scene || '',
+      evidence: data.evidence || '',
+    },
+  );
+
+  // Later chapters may already hold a newer state; the materialized row must
+  // reflect the newest event after the rewrite.
+  const latest = await sdb.rows(
+    `SELECT coverage FROM knowledge_event WHERE story = ${STORY}
+       AND character = ${charLit} AND subject_type = $subject_type AND subject_id = $subject_id
+       ORDER BY chapter_no DESC, created_at DESC LIMIT 1;`,
+    subject,
+  );
+  await resetKnowledgeState(sdb, charLit, subject, latest[0] ? latest[0].coverage : null);
+
+  return { ok: true };
+}
+
+export async function createEntity(sdb, kind, input) {
+  const def = defOf(kind);
+  if (!def) fail('UNKNOWN_KIND', '未知实体：' + kind);
+  const data = normalizeData(kind, input || {});
+  const errors = validateData(kind, data);
+  if (errors.length) {
+    fail('VALIDATION', kind + ' 字段不合法：' + errors.map((e) => e.message).join('；'), errors);
+  }
+  const id = idFor(kind, data);
+  const table = def.table;
+  const fields = fieldsForWrite(kind, data);
+  const payload = input || {};
+  const sets = [];
+  const vars = { id, payload };
+  if (table !== 'story') {
+    sets.push(`story = ${STORY}`, 'entity_id = $entity_id');
+    vars.entity_id = id;
+  }
+  sets.push('payload = $payload');
+  for (const [name, value] of Object.entries(fields)) {
+    sets.push(name + ' = $' + name);
+    vars[name] = value;
+  }
+  await sdb.query(
+    `UPSERT type::record(${surrealString(table + ':⟨')} + $id + '⟩') SET ${sets.join(', ')};`,
+    vars,
+  );
+  await ensureRequirements(sdb, kind, id, data);
+  if (kind === 'chapter') await upsertChapterMetric(sdb, id, data.display_no, data);
+  if (kind === 'chapter_text' && data.display_no) {
+    await sdb.query(
+      `UPDATE chapter_metric SET word_count = $word_count WHERE story = ${STORY} AND chapter_no = $chapter_no;`,
+      {
+        word_count: Number(data.word_count) || String(data.content || '').replace(/\s/g, '').length,
+        chapter_no: Number(data.display_no),
+      },
+    );
+  }
+  return { id: table + ':' + id, kind, table };
+}
+
+export async function updateEntity(sdb, kind, id, patch) {
+  const def = defOf(kind);
+  if (!def) fail('UNKNOWN_KIND', '未知实体：' + kind);
+  const errors = validateData(kind, patch || {}, { partial: true });
+  if (errors.length) {
+    fail('VALIDATION', kind + ' 字段不合法：' + errors.map((e) => e.message).join('；'), errors);
+  }
+  const fields = fieldsForWrite(kind, patch || {});
+  const sets = ['updated_at = time::now()'];
+  const vars = { id };
+  for (const [name, value] of Object.entries(fields)) {
+    sets.push(name + ' = $' + name);
+    vars[name] = value;
+  }
+  if (!Object.keys(fields).length) return { id: def.table + ':' + id, changed: 0 };
+  await sdb.query(
+    `UPDATE type::record(${surrealString(def.table + ':⟨')} + $id + '⟩') SET ${sets.join(', ')};`,
+    vars,
+  );
+  if (kind === 'chapter' && (patch.emotion || patch.hook || patch.word_target !== undefined)) {
+    await upsertChapterMetric(sdb, id, patch.display_no || vars.display_no, patch);
+  }
+  return { id: def.table + ':' + id, changed: Object.keys(fields).length };
+}
+
+export async function getEntity(sdb, kind, id) {
+  const def = defOf(kind);
+  if (!def) fail('UNKNOWN_KIND', '未知实体：' + kind);
+  const row = await sdb.one(`SELECT * FROM ${recordLiteral(def.table, id)};`);
+  if (!row) fail('NOT_FOUND', '未找到 ' + def.table + ':' + id);
+  return row;
+}
+
+export async function searchEntities(sdb, kind, opts = {}) {
+  const def = defOf(kind);
+  const edge = edgeOf(kind);
+  if (!def && !edge) fail('UNKNOWN_KIND', '未知实体或边：' + kind);
+  const target = def || edge;
+  const where = [(def && kind === 'story') ? null : `story = ${STORY}`].filter(Boolean);
+  const vars = {};
+  const fields = target.fields || {};
+  for (const [key, value] of Object.entries(opts.where || {})) {
+    const allowed = key in fields || (edge && ['from_id', 'to_id'].includes(key));
+    if (!allowed) continue;
+    where.push(key + ' = $w_' + key);
+    vars['w_' + key] = value;
+  }
+  const limit = Math.max(1, Math.min(Number(opts.limit) || 50, 500));
+  const sql = `SELECT * FROM ${target.table}${where.length ? ' WHERE ' + where.join(' AND ') : ''} LIMIT ${limit};`;
+  return sdb.rows(sql, vars);
+}
+
+// ---------------------------------------------------------------------------
+// edges
+// ---------------------------------------------------------------------------
+
+function endpoint(value, fallbackTable) {
+  const ref = parseRef(value, fallbackTable);
+  if (!ref) fail('BAD_REF', '无法解析记录引用：' + value);
+  return ref;
+}
+
+export async function linkEdge(sdb, edgeKind, fromValue, toValue, input) {
+  const edge = edgeOf(edgeKind);
+  if (!edge) fail('UNKNOWN_EDGE', '未知边：' + edgeKind);
+  const from = endpoint(fromValue, edge.in);
+  const to = endpoint(toValue, edge.out);
+  if (from.table !== edge.in) fail('BAD_EDGE_ENDPOINT', edge.table + ' 的起点必须是 ' + edge.in + '，收到 ' + from.table);
+  if (to.table !== edge.out) fail('BAD_EDGE_ENDPOINT', edge.table + ' 的终点必须是 ' + edge.out + '，收到 ' + to.table);
+
+  const data = { ...(input || {}) };
+  const errors = validateData(edgeKind, data);
+  if (errors.length) {
+    fail('VALIDATION', edge.table + ' 字段不合法：' + errors.map((e) => e.message).join('；'), errors);
+  }
+
+  // Action edges need a chapter number for ordering checks.
+  if (edge.fills && data.chapter_no === undefined) {
+    if (from.table === 'chapter') {
+      const chapter = await sdb.one(
+        `SELECT display_no FROM chapter WHERE story = ${STORY} AND chapter_id = $id LIMIT 1;`,
+        { id: from.id },
+      );
+      if (!chapter) fail('BAD_REF', '章节不存在：chapter:' + from.id);
+      data.chapter_no = Number(chapter.display_no);
+    }
+  }
+
+  const fromLit = recordLiteral(from.table, from.id);
+  const toLit = recordLiteral(to.table, to.id);
+
+  // Idempotency: remove the same edge before re-creating it.
+  if (edge.fills) {
+    await sdb.query(
+      `DELETE ${edge.table} WHERE story = ${STORY} AND in = ${fromLit} AND out = ${toLit} AND action = $action;`,
+      { action: data.action },
+    );
+  } else {
+    await sdb.query(
+      `DELETE ${edge.table} WHERE story = ${STORY} AND in = ${fromLit} AND out = ${toLit};`,
+    );
+  }
+
+  const sets = [`story = ${STORY}`, 'from_id = $from_id', 'to_id = $to_id', 'payload = $payload'];
+  const vars = { from_id: from.id, to_id: to.id, payload: input || {} };
+  for (const [name, value] of Object.entries(fieldsForWrite(edgeKind, data))) {
+    sets.push(name + ' = $' + name);
+    vars[name] = value;
+  }
+  await sdb.query(
+    `RELATE ${fromLit}->${edge.table}->${toLit} SET ${sets.join(', ')};`,
+    vars,
+  );
+  return { edge: edge.table, from: refString(from), to: refString(to) };
+}
+
+export async function unlinkEdge(sdb, edgeKind, fromValue, toValue, data = {}) {
+  const edge = edgeOf(edgeKind);
+  if (!edge) fail('UNKNOWN_EDGE', '未知边：' + edgeKind);
+  const from = endpoint(fromValue, edge.in);
+  const to = endpoint(toValue, edge.out);
+  const fromLit = recordLiteral(from.table, from.id);
+  const toLit = recordLiteral(to.table, to.id);
+  const extra = data.action !== undefined ? ' AND action = $action' : '';
+  await sdb.query(
+    `DELETE ${edge.table} WHERE story = ${STORY} AND in = ${fromLit} AND out = ${toLit}${extra};`,
+    data.action !== undefined ? { action: data.action } : {},
+  );
+  return { removed: true };
+}
+
+// ---------------------------------------------------------------------------
+// apply / change_set / decisions
+// ---------------------------------------------------------------------------
+
+const CHAPTER_EDGES = [
+  'chapter_cast',
+  'chapter_location',
+  'chapter_line_node',
+  'chapter_branch',
+  'chapter_conflict',
+  'foreshadow_action',
+  'payoff_action',
+  'info_action',
+  'ending_action',
+];
+
+/**
+ * Replace the chapter-scoped graph of one chapter. A chapter submission is a
+ * complete unit: re-submitting it must not leave old cast/actions behind.
+ */
+async function clearChapterEdges(sdb, chapterId) {
+  const lit = recordLiteral('chapter', String(chapterId).replace(/^chapter:/, ''));
+  // has_chapter points act -> chapter, so it is cleared from the other side.
+  await sdb.query(`DELETE has_chapter WHERE story = ${STORY} AND out = ${lit};`);
+  for (const table of CHAPTER_EDGES) {
+    await sdb.query(
+      `DELETE ${table} WHERE story = ${STORY} AND in = ${lit};`,
+    );
+  }
+}
+
+/**
+ * Submit several chapters in one CLI call. Each chapter is still its own
+ * transaction and its own change_set, so one bad chapter does not roll back
+ * the chapters before or after it. Rhythm chapters replace their own
+ * cast/action edges by default; pass `"replaceChapter": false` to append.
+ * Outline/write chapters leave the rhythm graph untouched.
+ *
+ * Payload:
+ *   {
+ *     "perChapter": true,
+ *     "workflow": "rhythm",
+ *     "chapters": [
+ *       { "chapter": "CH001", "ops": [...], "decisions": [...] },
+ *       ...
+ *     ]
+ *   }
+ */
+async function applyPerChapter(sdb, body) {
+  const chapters = Array.isArray(body.chapters) ? body.chapters : [];
+  if (!chapters.length) {
+    fail('BAD_INPUT', 'perChapter 需要非空的 chapters 数组');
+  }
+  if (chapters.length > 10) {
+    fail('BATCH_TOO_LARGE', '一次 apply --per-chapter 最多 10 章；请拆成多次提交');
+  }
+  const results = [];
+  for (let i = 0; i < chapters.length; i += 1) {
+    const item = chapters[i] || {};
+    const label = item.chapter || item.chapter_id || item.subject || ('#' + (i + 1));
+    try {
+      const workflow = item.workflow || body.workflow || 'per-chapter';
+      const replaceChapter = item.replaceChapter !== undefined
+        ? item.replaceChapter === true
+        : workflow === 'rhythm';
+      const result = await apply(sdb, {
+        workflow,
+        summary: item.summary || body.summary || ('chapter ' + label),
+        parent: item.parent || body.parent,
+        chapter: label,
+        replaceChapter,
+        ops: Array.isArray(item.ops) ? item.ops : [],
+        decisions: Array.isArray(item.decisions) ? item.decisions : [],
+        supersedeSubjects: item.supersedeSubjects || body.supersedeSubjects,
+      });
+      results.push({ ok: true, chapter: label, ...result });
+    } catch (err) {
+      results.push({
+        ok: false,
+        chapter: label,
+        error: {
+          code: err && err.code ? err.code : 'ERROR',
+          message: flattenError(err),
+          detail: err && err.detail !== undefined ? err.detail : null,
+        },
+      });
+    }
+  }
+  const failed = results.filter((row) => row.ok !== true);
+  return {
+    ok: failed.length === 0,
+    per_chapter: true,
+    committed: results.length - failed.length,
+    failed: failed.length,
+    chapters: results,
+  };
+}
+
+/**
+ * Shape-only dry run used by `story_preview`. It never writes; the real
+ * `apply` still enforces every schedule, event, permission and uniqueness rule.
+ */
+export async function previewApply(sdb, payload) {
+  const body = payload || {};
+  const errors = [];
+  const ops = Array.isArray(body.ops) ? body.ops : [];
+  const decisions = Array.isArray(body.decisions) ? body.decisions : [];
+  if (body.perChapter !== true && !Array.isArray(body.chapters) && !ops.length) {
+    errors.push({ code: 'OPS_EMPTY', message: '没有可写入的 ops' });
+  }
+  const check = (index, condition, code, message) => {
+    if (!condition) errors.push({ code, message: '第 ' + (index + 1) + ' 个操作：' + message, op_index: index });
+  };
+  for (let i = 0; i < ops.length; i += 1) {
+    const op = ops[i] || {};
+    if (op.op === 'create') {
+      check(i, typeof op.kind === 'string' && op.kind, 'BAD_OP', 'create 缺少 kind');
+      check(i, op.data && typeof op.data === 'object' && !Array.isArray(op.data), 'BAD_OP', 'create 缺少 data 对象');
+    } else if (op.op === 'update') {
+      check(i, typeof op.kind === 'string' && op.kind, 'BAD_OP', 'update 缺少 kind');
+      check(i, typeof op.id === 'string' && op.id, 'BAD_OP', 'update 缺少 id');
+      check(i, op.data && typeof op.data === 'object' && !Array.isArray(op.data), 'BAD_OP', 'update 缺少 data 对象');
+    } else if (op.op === 'link') {
+      check(i, typeof op.edge === 'string' && op.edge, 'BAD_OP', 'link 缺少 edge');
+      check(i, typeof op.from === 'string' && op.from, 'BAD_OP', 'link 缺少 from');
+      check(i, typeof op.to === 'string' && op.to, 'BAD_OP', 'link 缺少 to');
+    } else if (op.op === 'unlink') {
+      check(i, typeof op.edge === 'string' && op.edge, 'BAD_OP', 'unlink 缺少 edge');
+      check(i, typeof op.from === 'string' && op.from, 'BAD_OP', 'unlink 缺少 from');
+      check(i, typeof op.to === 'string' && op.to, 'BAD_OP', 'unlink 缺少 to');
+    } else if (op.op === 'knowledge') {
+      check(i, op.data && typeof op.data === 'object' && !Array.isArray(op.data), 'BAD_OP', 'knowledge 缺少 data 对象');
+    } else {
+      check(i, false, 'BAD_OP', '未知操作：' + String(op.op));
+    }
+  }
+  for (const decision of decisions) {
+    if (!decision || typeof decision !== 'object' || !decision.subject || !decision.text) {
+      errors.push({ code: 'BAD_DECISION', message: '每条 decision 都需要 subject 和 text' });
+      break;
+    }
+  }
+  const chapters = Array.isArray(body.chapters) ? body.chapters : [];
+  if (body.perChapter === true) {
+    if (!chapters.length) errors.push({ code: 'CHAPTERS_EMPTY', message: 'perChapter 模式需要 chapters 数组' });
+    if (chapters.length > 10) errors.push({ code: 'BATCH_TOO_LARGE', message: '单批最多 10 章，当前 ' + chapters.length + ' 章' });
+  }
+  return {
+    ok: errors.length === 0,
+    operations: body.perChapter === true ? chapters.length : ops.length,
+    decisions: decisions.length,
+    chapters: chapters.length,
+    errors,
+  };
+}
+
+export async function apply(sdb, payload) {
+  const body = payload || {};
+  if (body.perChapter === true || Array.isArray(body.chapters)) {
+    return applyPerChapter(sdb, body);
+  }
+  const ops = Array.isArray(body.ops) ? body.ops : [];
+  const decisions = Array.isArray(body.decisions) ? body.decisions : [];
+  const changeSetId = uuid();
+  const results = [];
+
+  return sdb.tx(async () => {
+    await sdb.query(
+      `UPSERT type::record('change_set:⟨' + $id + '⟩') SET
+         story = ${STORY},
+         workflow = $workflow,
+         summary = $summary,
+         status = 'committed',
+         parent = $parent,
+         payload = {};`,
+      {
+        id: changeSetId,
+        workflow: body.workflow || 'manual',
+        summary: body.summary || '',
+        parent: body.parent || undefined,
+      },
+    );
+
+    if (Array.isArray(body.supersedeSubjects) && body.supersedeSubjects.length) {
+      await sdb.query(
+        `UPDATE decision SET status = 'superseded'
+         WHERE story = ${STORY} AND subject IN $subjects AND status = 'active';`,
+        { subjects: body.supersedeSubjects },
+      );
+    }
+
+    if (body.replaceChapter === true && body.chapter) {
+      await clearChapterEdges(sdb, body.chapter);
+    }
+
+    for (let i = 0; i < ops.length; i += 1) {
+      const op = ops[i];
+      try {
+        if (op.op === 'create') {
+          results.push(await createEntity(sdb, op.kind, op.data));
+        } else if (op.op === 'update') {
+          if (op.edge) {
+            fail('USE_LINK_FOR_EDGE', '边不能使用 update；请用 link 重新写同一条边（会覆盖 data），或用 unlink 删除');
+          }
+          results.push(await updateEntity(sdb, op.kind, op.id, op.data));
+        } else if (op.op === 'link') {
+          results.push(await linkEdge(sdb, op.edge, op.from, op.to, op.data));
+        } else if (op.op === 'unlink') {
+          results.push(await unlinkEdge(sdb, op.edge, op.from, op.to, op.data));
+        } else if (op.op === 'knowledge') {
+          results.push(await addKnowledgeEvent(sdb, op.data));
+        } else {
+          fail('BAD_OP', '未知操作：' + op.op);
+        }
+      } catch (err) {
+        const message = flattenError(err);
+        fail('OP_FAILED', '第 ' + (i + 1) + ' 个操作失败：' + message, {
+          op_index: i,
+          op,
+          cause: message,
+        });
+      }
+    }
+
+    for (const decision of decisions) {
+      await sdb.query(
+        `UPSERT type::record('decision:⟨' + $id + '⟩') SET
+           story = ${STORY},
+           change_set = $change_set,
+           scope = $scope,
+           subject = $subject,
+           text = $text,
+           source = $source,
+           reference = $reference,
+           reason = $reason,
+           status = 'active',
+           supersedes = $supersedes,
+           payload = {};`,
+        {
+          id: uuid(),
+          change_set: 'change_set:' + changeSetId,
+          scope: decision.scope || decision.subject || '',
+          subject: decision.subject || decision.scope || '',
+          text: decision.text || '',
+          source: decision.source || undefined,
+          reference: decision.reference || undefined,
+          reason: decision.reason || undefined,
+          supersedes: decision.supersedes || undefined,
+        },
+      );
+    }
+
+    return {
+      ok: true,
+      change_set: 'change_set:' + changeSetId,
+      operations: ops.length,
+      decisions: decisions.length,
+      results,
+    };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// validation
+// ---------------------------------------------------------------------------
+
+function parseSubject(subject) {
+  const idx = String(subject).indexOf(':');
+  if (idx < 0) return null;
+  return { table: subject.slice(0, idx), id: subject.slice(idx + 1) };
+}
+
+async function subjectStatus(sdb, subject) {
+  const ref = parseSubject(subject);
+  if (!ref) return null;
+  try {
+    const row = await sdb.one(`SELECT status FROM ${recordLiteral(ref.table, ref.id)};`);
+    return row ? row.status : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function validate(sdb, opts = {}) {
+  const scope = opts.scope || null;
+  try {
+    const out = await sdb.query('RETURN fn::fancy::validate($scope);', { scope: scope || undefined });
+    const value = Array.isArray(out) && out[0] && typeof out[0] === 'object' && !Array.isArray(out[0])
+      ? out[0]
+      : (Array.isArray(out) && Array.isArray(out[0]) ? out[0][0] : null);
+    if (!value || typeof value !== 'object') {
+      fail('VALIDATION_RESULT', '数据库校验函数没有返回结果');
+    }
+    return {
+      errors: Array.isArray(value.errors) ? value.errors : [],
+      pending: Array.isArray(value.pending) ? value.pending : [],
+      warnings: Array.isArray(value.warnings) ? value.warnings : [],
+    };
+  } catch (err) {
+    fail('VALIDATION_FAILED', '数据库校验失败：' + flattenError(err));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// work queue / decisions
+// ---------------------------------------------------------------------------
+
+export async function nextWork(sdb, limit = 20) {
+  const rows = await sdb.rows(
+    `SELECT * FROM requirement WHERE story = ${STORY} AND status = 'pending'
+     ORDER BY hard DESC, due_chapter ASC LIMIT $limit;`,
+    { limit },
+  );
+  const out = [];
+  for (const row of rows) {
+    const ref = parseSubject(row.subject);
+    let subject = null;
+    if (ref) {
+      try {
+        subject = await sdb.one(`SELECT * FROM ${recordLiteral(ref.table, ref.id)};`);
+      } catch { /* missing */ }
+    }
+    out.push({
+      kind: row.kind,
+      subject: row.subject,
+      hard: Boolean(row.hard),
+      due_chapter: row.due_chapter,
+      label: row.label,
+      name: subject && (subject.name || subject.title || subject.info_name || subject.chapter_id) || null,
+      status: subject && subject.status || null,
+    });
+  }
+  return out;
+}
+
+export async function decisionsFor(sdb, subject, opts = {}) {
+  const where = [`story = ${STORY}`, 'subject = $subject'];
+  if (opts.activeOnly !== false) where.push("status = 'active'");
+  return sdb.rows(
+    `SELECT * FROM decision WHERE ${where.join(' AND ')} ORDER BY created_at DESC;`,
+    { subject },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// read-only SQL
+// ---------------------------------------------------------------------------
+
+const READ_ONLY = /^\s*(SELECT|INFO|RETURN|SHOW|DESCRIBE|EXPLAIN)\b/i;
+
+export async function readQuery(sdb, sql) {
+  const text = String(sql || '').trim().replace(/;+\s*$/, '');
+  if (!text) fail('QUERY_EMPTY', '查询语句为空');
+  if (!READ_ONLY.test(text) || /;\s*(DELETE|CREATE|UPDATE|UPSERT|REMOVE|DEFINE|RELATE|INSERT|ALTER|KILL)\b/i.test(text)) {
+    fail('QUERY_NOT_READ_ONLY', '只允许只读查询（SELECT / INFO / RETURN / SHOW / DESCRIBE / EXPLAIN）');
+  }
+  try {
+    const out = await sdb.query(text + ';');
+    return Array.isArray(out) && out.length === 1 ? out[0] : out;
+  } catch (err) {
+    fail('QUERY_FAILED', '查询失败：' + flattenError(err));
+  }
+}