@floken-io/engine 0.0.1

package/dist/chunk-RMCROXES.js

@@ -0,0 +1,376 @@
+// src/core/errors.ts
+var ENGINE_ERROR_CODES = {
+  // —— 动作层：19 项动作的受理、开关、目标与意见校验 ——
+  /** 动作名不在 19 项之内 */
+  ACTION_UNKNOWN: "ENGINE_ACTION_UNKNOWN",
+  /** 设计期开关未开启（`approval.X.allowed === false`，DV-2） */
+  ACTION_NOT_ALLOWED: "ENGINE_ACTION_NOT_ALLOWED",
+  /**
+   * 门 1 `beforeAction` 返回 `false` 否决了本次动作（T12）。
+   *
+   * ★ 与 `ACTION_NOT_ALLOWED` 的区别：后者是**设计期**开关（读定义就知道），
+   *   本码是**运行期**宿主否决（只有跑起来才知道）。合成一个码的话，宿主分不清
+   *   「按钮本来就不该显示」与「业务条件不满足」—— 前者是前端 bug，后者要提示用户。
+   * ⚠️ 否决**必须**抛错：静默返回空差分会让用户以为办完了（红线：不得静默无效果）。
+   */
+  ACTION_VETOED: "ENGINE_ACTION_VETOED",
+  /** 驳回 / 退回目标非法（INV-6：须同时满足 ∈ `completedNodes` 且 ∈ `allowedTargets`） */
+  ACTION_TARGET_INVALID: "ENGINE_ACTION_TARGET_INVALID",
+  /** `requireComment` 为 true 但未填意见（DV-3） */
+  ACTION_COMMENT_REQUIRED: "ENGINE_ACTION_COMMENT_REQUIRED",
+  /** 审批人解析为空集且 `onEmpty === 'error'`（INV-13，不得产生 0 办待人的 active 节点） */
+  ACTION_APPROVER_EMPTY: "ENGINE_ACTION_APPROVER_EMPTY",
+  /** 加签超出设计期 `addSign.maxCount`（INV-12） */
+  ACTION_ADD_SIGN_LIMIT: "ENGINE_ACTION_ADD_SIGN_LIMIT",
+  /** 票签配置非法（INV-7：`mode:'vote'` ⟺ `vote` 存在，且 `count` / `threshold` 恰有其一） */
+  ACTION_VOTE_CONFIG: "ENGINE_ACTION_VOTE_CONFIG",
+  // —— 状态层：实例定位、生命周期、结构不变量 ——
+  /** `StateStore.load()` 返回 null */
+  STATE_NOT_FOUND: "ENGINE_STATE_NOT_FOUND",
+  /** 实例已终态（completed / terminated / cancelled）后仍尝试推进（INV-2） */
+  STATE_TERMINAL: "ENGINE_STATE_TERMINAL",
+  /** 实例处于 suspended，除 `resume` 外一律不受理（INV-5） */
+  STATE_SUSPENDED: "ENGINE_STATE_SUSPENDED",
+  /** 状态结构不合契约（含 AC-E8 / INV-14：出现函数 / Map / Set / 类实例） */
+  STATE_SHAPE_INVALID: "ENGINE_STATE_SHAPE_INVALID",
+  /** `tokens[].nodeId` 不在该实例**绑定版本**的定义图中（INV-3，不得静默忽略） */
+  STATE_TOKEN_ORPHAN: "ENGINE_STATE_TOKEN_ORPHAN",
+  /** `DefinitionSource.getDefinition()` 返回 null（AC-E10 要求按实例绑定版本取定义） */
+  STATE_DEFINITION_MISSING: "ENGINE_STATE_DEFINITION_MISSING",
+  /** 快照结构版本无迁移路径（`stateSchema` 只升不降；升级须登记迁移函数） */
+  STATE_SCHEMA_UNSUPPORTED: "ENGINE_STATE_SCHEMA_UNSUPPORTED",
+  // —— 持久层：StateStore 的 INSERT / CAS 两条路径 ——
+  /** CAS UPDATE 影响 0 行：`expectedRev` 与库中当前 rev 不符（INV-1） */
+  PERSIST_CONFLICT: "ENGINE_PERSIST_CONFLICT",
+  /** INSERT 冲突：`expectedRev === 0` 但该 `instanceId` 已存在 */
+  PERSIST_ALREADY_EXISTS: "ENGINE_PERSIST_ALREADY_EXISTS",
+  // —— 选项层：createEngine 配置 ——
+  /** 未知配置项（**禁止静默忽略**，与 feel 的 `FEEL_OPTION_UNKNOWN` 同口径） */
+  OPTION_UNKNOWN: "ENGINE_OPTION_UNKNOWN",
+  /** 配置项取值非法（如 `maxAuditEntries` 非正整数） */
+  OPTION_INVALID: "ENGINE_OPTION_INVALID"
+};
+var ENGINE_DIAGNOSTIC_CODES = {
+  /** INV-18：`pendingProjectionRev` 存在 —— 该 rev 的投影尚未追平，`load()` 会先 `sync()` 补做 */
+  EFFECT_PENDING: "ENGINE_EFFECT_PENDING",
+  /** INV-17：`auditTrail` 达 `maxAuditEntries` 上限已裁剪；溢出区间记在 `details.dropped*`，**未静默丢弃**
+   *  ⚠️ engine **不**把溢出条目投 `EventSink`：事件集由 ADR-006 定死为 10 个，审计不走事件通道
+   *  （审计主源是 `auditTrail` 本身；被裁掉的部分宿主应从 `diagnostics` 转存到自己的归档） */
+  AUDIT_TRUNCATED: "ENGINE_AUDIT_TRUNCATED"
+};
+function engineDiagnostic(init) {
+  const out = {
+    severity: init.severity ?? "warn",
+    code: init.code,
+    message: init.message
+  };
+  if (init.node !== void 0) out.node = init.node;
+  if (init.instanceId !== void 0) out.instanceId = init.instanceId;
+  if (init.details !== void 0) out.details = init.details;
+  return out;
+}
+var EngineError = class extends Error {
+  /** 五包统一印记：宿主可据此判断「这是 floken 的结构化错误」 */
+  floken = true;
+  pkg = "engine";
+  code;
+  constructor(message, init) {
+    super(message);
+    this.name = new.target.name;
+    this.code = init.code;
+    if (init.node) this.node = init.node;
+    if (init.instanceId) this.instanceId = init.instanceId;
+    if (init.hint) this.hint = init.hint;
+    if (init.details) this.details = init.details;
+  }
+};
+var EngineActionError = class extends EngineError {
+};
+var EngineStateError = class extends EngineError {
+};
+var EnginePersistError = class extends EngineError {
+};
+var EngineOptionError = class extends EngineError {
+};
+function actionUnknown(name, allowed) {
+  return new EngineActionError(`Unknown action '${name}'`, {
+    code: ENGINE_ERROR_CODES.ACTION_UNKNOWN,
+    hint: "\u52A8\u4F5C\u540D\u5FC5\u987B\u662F 19 \u9879\u4E4B\u4E00\uFF1B\u5408\u6CD5\u53D6\u503C\u89C1 details.allowed",
+    details: { action: name, allowed: [...allowed] }
+  });
+}
+function actionNotAllowed(name, allowed) {
+  return new EngineActionError(`Action '${name}' is not enabled for this node`, {
+    code: ENGINE_ERROR_CODES.ACTION_NOT_ALLOWED,
+    hint: "\u5728\u6D41\u7A0B\u5B9A\u4E49\u7684 approval \u914D\u7F6E\u4E2D\u6253\u5F00\u8BE5\u5F00\u5173\uFF0C\u6216\u6539\u7528\u5DF2\u5F00\u542F\u7684\u52A8\u4F5C",
+    details: { action: name, allowed: [...allowed] }
+  });
+}
+function actionVetoed(action, instanceId) {
+  return new EngineActionError(`Action '${action}' was vetoed by hooks.beforeAction`, {
+    code: ENGINE_ERROR_CODES.ACTION_VETOED,
+    hint: "\u5BBF\u4E3B\u5728 beforeAction \u91CC\u8FD4\u56DE\u4E86 false\uFF1B\u9700\u8981\u5E26\u539F\u56E0\u8BF7\u6539\u4E3A\u5728\u94A9\u5B50\u4E2D throw",
+    details: { action, instanceId }
+  });
+}
+function actionTargetInvalid(action, target, completed, allowedTargets) {
+  return new EngineActionError(`Action '${action}' cannot target node '${target}'`, {
+    code: ENGINE_ERROR_CODES.ACTION_TARGET_INVALID,
+    node: { id: target },
+    hint: "\u76EE\u6807\u5FC5\u987B\u540C\u65F6\u5C5E\u4E8E details.completedNodes \u4E0E details.allowedTargets",
+    details: {
+      action,
+      target,
+      completedNodes: [...completed],
+      allowedTargets: [...allowedTargets]
+    }
+  });
+}
+function commentRequired(action) {
+  return new EngineActionError(`Action '${action}' requires a comment`, {
+    code: ENGINE_ERROR_CODES.ACTION_COMMENT_REQUIRED,
+    hint: "\u5728 ActionInput.comment \u4E2D\u8865\u5145\u610F\u89C1\uFF1B\u8BE5\u7C7B\u52A8\u4F5C\u9ED8\u8BA4\u8981\u6C42\u7559\u75D5",
+    details: { action }
+  });
+}
+function approverEmpty(nodeId, onEmpty, details = {}) {
+  return new EngineActionError(`No approver resolved for node '${nodeId}'`, {
+    code: ENGINE_ERROR_CODES.ACTION_APPROVER_EMPTY,
+    node: { id: nodeId },
+    hint: "\u6539 ApproverSource \u7684\u89E3\u6790\u89C4\u5219\uFF0C\u6216\u628A\u8BE5\u8282\u70B9\u7684 approval.onEmpty \u8BBE\u4E3A 'skip' / \u663E\u5F0F\u4F7F\u7528 {type:'all'}",
+    details: { nodeId, onEmpty, ...details }
+  });
+}
+function addSignLimit(nodeId, limit, current) {
+  return new EngineActionError(`Add-sign limit exceeded on node '${nodeId}'`, {
+    code: ENGINE_ERROR_CODES.ACTION_ADD_SIGN_LIMIT,
+    node: { id: nodeId },
+    hint: "\u8C03\u5927\u8BE5\u8282\u70B9 approval.addSign.maxCount\uFF0C\u6216\u51CF\u5C11\u52A0\u7B7E\u4EBA\u6570",
+    details: { nodeId, limit, current }
+  });
+}
+function deliverNoTarget(instanceId, kind, name, waiting, details = {}) {
+  const message = instanceId === void 0 ? `No instance among the candidates is waiting for ${kind} '${name}'` : `No token in instance '${instanceId}' is waiting for ${kind} '${name}'`;
+  return new EngineActionError(message, {
+    code: ENGINE_ERROR_CODES.ACTION_TARGET_INVALID,
+    ...instanceId === void 0 ? {} : { instanceId },
+    hint: waiting.length === 0 ? "\u6B64\u523B**\u6CA1\u6709**\u4EFB\u4F55\u7B49\u5F85\u4E2D\u7684\u4EE4\u724C\uFF08\u53EF\u80FD\u5DF2\u7ECF\u8D70\u8FC7\u90A3\u4E2A\u8282\u70B9\uFF0C\u6216\u5B9E\u4F8B\u5DF2\u4E0D\u5728\u7B49\u5F85\uFF09\uFF1B\u8BF7\u786E\u8BA4\u6295\u9012\u76EE\u6807\u4E0E\u65F6\u673A" : "\u6D88\u606F / \u4FE1\u53F7\u540D\u5FC5\u987B\u4E0E\u5B9A\u4E49\u91CC\u7684 messageRef / signalRef **\u9010\u5B57\u4E00\u81F4**\uFF1Bdetails.waiting \u662F\u6B64\u523B\u5728\u7B49\u7684\u4E1C\u897F",
+    details: { kind, name, waiting: [...waiting], ...details }
+  });
+}
+function voteConfigInvalid(message, details = {}) {
+  return new EngineActionError(message, {
+    code: ENGINE_ERROR_CODES.ACTION_VOTE_CONFIG,
+    hint: "mode:'vote' \u8981\u6C42 vote \u5B57\u6BB5\u5B58\u5728\uFF0C\u4E14 count / threshold \u6070\u6709\u5176\u4E00",
+    details
+  });
+}
+function stateNotFound(instanceId) {
+  return new EngineStateError(`Process instance '${instanceId}' not found`, {
+    code: ENGINE_ERROR_CODES.STATE_NOT_FOUND,
+    instanceId,
+    hint: "\u786E\u8BA4 instanceId \u6B63\u786E\uFF0C\u4E14\u8BE5\u5B9E\u4F8B\u5DF2 start() \u5E76\u6210\u529F\u843D\u5E93",
+    details: { instanceId }
+  });
+}
+function stateTerminal(instanceId, status, action) {
+  return new EngineStateError(`Process instance '${instanceId}' is already '${status}'`, {
+    code: ENGINE_ERROR_CODES.STATE_TERMINAL,
+    instanceId,
+    hint: "\u7EC8\u6001\u5B9E\u4F8B\u4E0D\u53EF\u518D\u63A8\u8FDB\uFF1B\u5982\u9700\u7EE7\u7EED\u8BF7\u4EE5\u65B0\u5B9E\u4F8B\u53D1\u8D77",
+    details: { instanceId, status, action }
+  });
+}
+function stateSuspended(instanceId, action) {
+  return new EngineStateError(`Process instance '${instanceId}' is suspended`, {
+    code: ENGINE_ERROR_CODES.STATE_SUSPENDED,
+    instanceId,
+    hint: "\u5148\u63D0\u4EA4 { action: 'resume' } \u518D\u63A8\u8FDB",
+    details: { instanceId, action }
+  });
+}
+function stateShapeInvalid(reason, details = {}) {
+  return new EngineStateError(`InstanceState shape is invalid: ${reason}`, {
+    code: ENGINE_ERROR_CODES.STATE_SHAPE_INVALID,
+    hint: "\u72B6\u6001\u5FC5\u987B\u662F\u7EAF\u6570\u636E\uFF08\u65E0\u51FD\u6570 / Map / Set / \u7C7B\u5B9E\u4F8B\uFF09\uFF0C\u4E14 JSON \u5F80\u8FD4\u6DF1\u7B49",
+    details: { reason, ...details }
+  });
+}
+function tokenOrphan(instanceId, tokenId, nodeId) {
+  return new EngineStateError(`Token '${tokenId}' points to unknown node '${nodeId}'`, {
+    code: ENGINE_ERROR_CODES.STATE_TOKEN_ORPHAN,
+    instanceId,
+    node: { id: nodeId },
+    hint: "\u68C0\u67E5\u5B9A\u4E49\u7248\u672C\u7ED1\u5B9A\uFF1A\u5B9E\u4F8B\u6309 definitionVersion \u6267\u884C\uFF0C\u8282\u70B9\u5FC5\u987B\u5B58\u5728\u4E8E\u8BE5\u7248\u672C",
+    details: { instanceId, tokenId, nodeId }
+  });
+}
+function definitionMissing(processId, version) {
+  return new EngineStateError(`Definition '${processId}' version ${version} not found`, {
+    code: ENGINE_ERROR_CODES.STATE_DEFINITION_MISSING,
+    hint: "\u786E\u8BA4 DefinitionSource \u5DF2\u53D1\u5E03\u8BE5 processId \u7684\u8BE5\u7248\u672C",
+    details: { processId, definitionVersion: version }
+  });
+}
+function persistConflict(instanceId, expectedRev, actualRev) {
+  const init = {
+    code: ENGINE_ERROR_CODES.PERSIST_CONFLICT,
+    instanceId,
+    hint: "\u91CD\u65B0 load() \u53D6\u6700\u65B0\u72B6\u6001\u540E\u91CD\u8BD5\uFF1B\u672C\u9519\u8BEF\u8868\u793A\u5E76\u53D1\u7684\u53E6\u4E00\u7B14\u5199\u5165\u5DF2\u5148\u63D0\u4EA4",
+    details: { instanceId, expectedRev, ...actualRev === void 0 ? {} : { actualRev } }
+  };
+  return new EnginePersistError(`Rev conflict on instance '${instanceId}'`, init);
+}
+function persistAlreadyExists(instanceId) {
+  return new EnginePersistError(`Process instance '${instanceId}' already exists`, {
+    code: ENGINE_ERROR_CODES.PERSIST_ALREADY_EXISTS,
+    instanceId,
+    hint: "expectedRev === 0 \u8868\u793A\u65B0\u5EFA\uFF1B\u540C\u4E00 instanceId \u4E0D\u5F97\u91CD\u590D\u63D2\u5165",
+    details: { instanceId }
+  });
+}
+function optionUnknown(key, allowed) {
+  return new EngineOptionError(`Unknown engine option '${key}'`, {
+    code: ENGINE_ERROR_CODES.OPTION_UNKNOWN,
+    hint: "\u5408\u6CD5\u914D\u7F6E\u9879\u89C1 details.allowed",
+    details: { option: key, allowed: [...allowed] }
+  });
+}
+function optionInvalid(key, reason, value) {
+  const init = {
+    code: ENGINE_ERROR_CODES.OPTION_INVALID,
+    hint: "\u6309 details.reason \u4FEE\u6B63\u8BE5\u914D\u7F6E\u9879\u53D6\u503C",
+    details: { option: key, reason, ...value === void 0 ? {} : { value } }
+  };
+  return new EngineOptionError(`Invalid value for engine option '${key}'`, init);
+}
+function conditionInvalid(expression, reason, details = {}) {
+  const init = {
+    code: ENGINE_ERROR_CODES.OPTION_INVALID,
+    hint: "\u6761\u4EF6\u8868\u8FBE\u5F0F\u5FC5\u987B\u662F\u6C42\u503C\u4E3A true / false \u7684 FEEL \u8868\u8FBE\u5F0F\uFF1B\u53D8\u91CF\u76F4\u63A5\u5199\u540D\u5B57\uFF08amount\uFF09\uFF0C\u4E0D\u8981\u5199 ${...}",
+    details: { option: "condition", expression, reason, ...details }
+  };
+  return new EngineOptionError(`Invalid condition expression '${expression}'`, init);
+}
+
+// src/core/state.ts
+var STATE_SCHEMA_VERSION = 1;
+var INSTANCE_STATUSES = [
+  "running",
+  "suspended",
+  "completed",
+  "terminated",
+  "cancelled"
+];
+var TERMINAL_STATUSES = [
+  "completed",
+  "terminated",
+  "cancelled"
+];
+function isTerminalStatus(status) {
+  return TERMINAL_STATUSES.includes(status);
+}
+var TOKEN_STATES = [
+  "active",
+  "waiting",
+  "completed",
+  "cancelled"
+];
+function headerOf(s) {
+  const h = {
+    instanceId: s.instanceId,
+    processId: s.processId,
+    definitionVersion: s.definitionVersion,
+    status: s.status,
+    rev: s.rev,
+    stateSchema: s.stateSchema,
+    startedAt: s.startedAt,
+    updatedAt: s.updatedAt
+  };
+  if (s.businessKey !== void 0) h.businessKey = s.businessKey;
+  if (s.tenantId !== void 0) h.tenantId = s.tenantId;
+  if (s.lastAction !== void 0) h.lastAction = s.lastAction;
+  if (s.pendingProjectionRev !== void 0) h.pendingProjectionRev = s.pendingProjectionRev;
+  if (s.endedAt !== void 0) h.endedAt = s.endedAt;
+  return h;
+}
+function findNonSerializable(value, path, ancestors) {
+  switch (typeof value) {
+    case "string":
+    case "boolean":
+      return null;
+    case "number":
+      return Number.isFinite(value) ? null : { path, kind: "non-finite-number", detail: String(value) };
+    case "undefined":
+      return { path, kind: "undefined" };
+    case "bigint":
+      return { path, kind: "bigint", detail: `${value}n` };
+    case "symbol":
+      return { path, kind: "symbol", detail: value.description ?? "" };
+    case "function":
+      return { path, kind: "function", detail: value.name || "(anonymous)" };
+    case "object":
+      break;
+    default:
+      return { path, kind: "class-instance", detail: typeof value };
+  }
+  if (value === null) return null;
+  const obj = value;
+  if (ancestors.has(obj)) return { path, kind: "circular" };
+  if (obj instanceof Map) return { path, kind: "map" };
+  if (obj instanceof Set) return { path, kind: "set" };
+  if (obj instanceof Date) return { path, kind: "date", detail: obj.toISOString() };
+  ancestors.add(obj);
+  try {
+    if (Array.isArray(obj)) {
+      for (let i = 0; i < obj.length; i += 1) {
+        const bad = findNonSerializable(obj[i], `${path}[${i}]`, ancestors);
+        if (bad) return bad;
+      }
+      return null;
+    }
+    const proto = Object.getPrototypeOf(obj);
+    if (proto !== Object.prototype && proto !== null) {
+      const ctor = obj.constructor?.name ?? "Object";
+      return { path, kind: "class-instance", detail: ctor };
+    }
+    const syms = Object.getOwnPropertySymbols(obj);
+    if (syms.length > 0) {
+      return { path, kind: "symbol-key", detail: String(syms[0]) };
+    }
+    for (const [key, v] of Object.entries(obj)) {
+      const bad = findNonSerializable(v, `${path}.${key}`, ancestors);
+      if (bad) return bad;
+    }
+    return null;
+  } finally {
+    ancestors.delete(obj);
+  }
+}
+function findNonSerializableValue(value, path = "$") {
+  return findNonSerializable(value, path, /* @__PURE__ */ new Set());
+}
+function assertSerializable(value, path = "$") {
+  const bad = findNonSerializableValue(value, path);
+  if (!bad) return;
+  throw stateShapeInvalid(`non-serializable ${bad.kind} at ${bad.path}`, {
+    path: bad.path,
+    kind: bad.kind,
+    ...bad.detail === void 0 ? {} : { detail: bad.detail }
+  });
+}
+function cloneState(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function deepEqual(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+function assertRoundTrip(value, path = "$") {
+  assertSerializable(value, path);
+  const cloned = cloneState(value);
+  if (!deepEqual(value, cloned)) {
+    throw stateShapeInvalid("state is not JSON round-trip stable", { path });
+  }
+}
+
+export { ENGINE_DIAGNOSTIC_CODES, ENGINE_ERROR_CODES, EngineActionError, EngineError, EngineOptionError, EnginePersistError, EngineStateError, INSTANCE_STATUSES, STATE_SCHEMA_VERSION, TERMINAL_STATUSES, TOKEN_STATES, actionNotAllowed, actionTargetInvalid, actionUnknown, actionVetoed, addSignLimit, approverEmpty, assertRoundTrip, assertSerializable, cloneState, commentRequired, conditionInvalid, deepEqual, definitionMissing, deliverNoTarget, engineDiagnostic, headerOf, isTerminalStatus, optionInvalid, optionUnknown, persistAlreadyExists, persistConflict, stateNotFound, stateShapeInvalid, stateSuspended, stateTerminal, tokenOrphan, voteConfigInvalid };

package/dist/conformance.d.ts

@@ -0,0 +1,162 @@
+import { S as StateStore, T as TaskView, a as TaskProjection, D as DefinitionSource } from './spi-BABH0Tcs.js';
+import { ProcessDefinition } from '@floken-io/moddle';
+
+/**
+ * @floken-io/engine/conformance · 报告与用例驱动器
+ *
+ * 契约来源：`ARCHITECTURE.md` §9 T6；`03-engine` §9.2（宿主自研实现的两类静默错误）。
+ *
+ * ═══════════════════════════════════════════════════════════════
+ * ★ 三条设计裁决（不是随手写的，改之前先看理由）
+ * ═══════════════════════════════════════════════════════════════
+ *
+ * ① **绝不 import 测试框架**。本套件**随包发布**（`./conformance` 子路径），宿主拿它去验
+ *    自己写的 Postgres / MySQL 实现 —— 此时宿主用什么 runner 是宿主的自由（vitest /
+ *    jest / `node:test` / 一个没框架的脚本都行）。套件若 `import { expect } from 'vitest'`，
+ *    等于给整个宿主应用强塞一个测试框架依赖；而且 `check:deps` 的依赖白名单也会直接拦下来。
+ *    → 所以这里**只返回报告、不抛断言**；怎么把报告变成 CI 上的红/绿，由调用方决定。
+ *
+ * ② **返回报告而非 fail-fast**。逐条 `try/catch`，一次跑完给出**完整缺口清单**。
+ *    fail-fast 会让人「修一条跑一次」，而宿主的实现缺陷通常是**成簇**出现的
+ *    （比如「不抛冲突」往往连带「失败路径不留痕」也不成立）。
+ *
+ * ③ **断言体可以抛任何错**，套件把它转成 `error: string`。所以套件内部用**纯 `Error`**
+ *    做断言失败信号 —— 它**不是** `EngineError`。理由：`EngineError` 是**引擎对宿主**的
+ *    错误契约（码表 / 四禁 / 双命名空间），而「你的实现不满足契约」是**开发期**的结论，
+ *    不该混进那套码表里去占用码名。详见 `AGENTS.md` §5。
+ */
+
+/** 单条契约用例的结果 */
+interface ConformanceCase {
+    /** 判据名：**人类可读、直接进 CI 日志**（说明"哪条契约没兑现"） */
+    name: string;
+    /** 该用例覆盖的规格锚点（`INV-x` / `AC-Ex` / 文档小节），失败时可直接回溯规范 */
+    refs: readonly string[];
+    ok: boolean;
+    /** 失败原因；`ok === true` 时**不存在该键** */
+    error?: string;
+}
+/** 一次契约测试的完整结果（`ok` = 全绿） */
+interface ConformanceReport {
+    /** 套件名：`'store'` | `'projection'` | `'definition'` */
+    suite: string;
+    /** 被测实现的自述（宿主传入，便于日志里区分多套实现） */
+    subject?: string;
+    cases: ConformanceCase[];
+    total: number;
+    passed: number;
+    failed: number;
+    ok: boolean;
+}
+/** 人类可读结论（宿主 `console.log` 它即可） */
+declare function formatConformanceReport(report: ConformanceReport): string;
+
+interface StoreConformanceOptions {
+    /** 被测实现的自述（进报告抬头，便于区分多套实现） */
+    subject?: string;
+    /** 实例 id 前缀，便于在 SQL 里定位这些行（默认 `floken-conf`） */
+    idPrefix?: string;
+}
+/**
+ * 跑 `StateStore` 全量契约用例。
+ *
+ * 前置：传入的 `store` 可用即可 —— **不需要是空的**（用例各自用唯一 id）。
+ */
+declare function runStoreConformance(store: StateStore, options?: StoreConformanceOptions): Promise<ConformanceReport>;
+
+/**
+ * 宿主提供的「读自己的待办表」。
+ * ⚠️ 顺序不作要求（套件内部按 `taskId` 归一），但**必须只返回该实例的行**。
+ */
+type ProjectionReadback = (instanceId: string) => Promise<TaskView[]>;
+interface ProjectionConformanceOptions {
+    /** 被测实现的自述（进报告抬头） */
+    subject?: string;
+    /** 实例 id 前缀（默认 `floken-conf`） */
+    idPrefix?: string;
+}
+/**
+ * 跑 `TaskProjection` 全量契约用例。
+ *
+ * @param projection 被测投影实现
+ * @param readback   宿主提供的「读自己的待办表」（见文件头说明）；**必须**只返回该实例的行
+ */
+declare function runProjectionConformance(projection: TaskProjection, readback: ProjectionReadback, options?: ProjectionConformanceOptions): Promise<ConformanceReport>;
+
+/**
+ * @floken-io/engine/conformance · `DefinitionSource` 契约测试套件
+ *
+ * 契约来源：`ARCHITECTURE.md` §7.2（`DefinitionSource`）/ §6.4（INV-19）/ §9 T19；
+ * `03-engine` §8.1、`AC-E10`。
+ *
+ * ═══════════════════════════════════════════════════════════════
+ * 宿主怎么用
+ * ═══════════════════════════════════════════════════════════════
+ * ```ts
+ * import { runDefinitionConformance, formatConformanceReport } from '@floken-io/engine/conformance';
+ *
+ * const report = await runDefinitionConformance(mySource, [
+ *   { processId: 'expense', version: 1, definition: defV1 },
+ *   { processId: 'expense', version: 2, definition: defV2 },
+ * ]);
+ * console.log(formatConformanceReport(report));
+ * ```
+ *
+ * ═══════════════════════════════════════════════════════════════
+ * ★ 为什么必须由宿主额外交 `fixtures`（与 `store` 套件最大的不同）
+ * ═══════════════════════════════════════════════════════════════
+ * `StateStore` 的用例能**自己造**假状态（状态是引擎的数据），但**定义是业务的资产** ——
+ * 套件随包发布，它不可能知道你的仓库里有哪些流程。所以这里反过来：
+ * 由宿主声明「我的仓库里这一格长这样」（`{ processId, version, definition }`），
+ * 套件拿着它去**按格取回**并逐格比对。这不是接口缺陷，而是「引擎不认识你的定义库」
+ * 这条边界必须付出的代价 —— 与 `TaskProjection` 要宿主交 `readback` 同理
+ * （见 `projection.ts` 文件头）。
+ *
+ * ═══════════════════════════════════════════════════════════════
+ * ★ 它在抓什么（`AC-E10` 的两类静默错误）
+ * ═══════════════════════════════════════════════════════════════
+ * ① **忽略 `version` 参数**（`getDefinition(pid, v)` 里压根没用 `v`，永远返回最新版）。
+ *    症状：在途实例跑到了它发起时**还不存在的节点**上，且**没有任何报错** ——
+ *    「昨天发起的单子今天忽然多出一个审批人」就是它。
+ *    这是本套件的**头号目标**，判据名里直接写明了「防忽略 version」。
+ * ② **未知版本回退**（取不到第 v 版就退到上一版 / 最新版）。
+ *    返回 `null` 才是「这一版不存在」的唯一诚实表达 —— 引擎会把它翻成
+ *    `ENGINE_STATE_DEFINITION_MISSING`（可观测、可告警）；回退则是一次静默的偷换。
+ *
+ * ═══════════════════════════════════════════════════════════════
+ * ★ 断言边界（诚实说明，**不是**遗漏）
+ * ═══════════════════════════════════════════════════════════════
+ * 只断言「按格取回的内容与宿主声明的深等」+ 上述两类反例。套件**不验**定义本身的
+ * 合法性（能不能建图、节点类型对不对）—— 那是 `@floken-io/moddle` 的职责，
+ * 且定义不合法时引擎会在 `createProcessGraph()` 抛错，不需要两套判据。
+ *
+ * 比较语义与 `assertDeepEqual` **同源**（`core/state.deepEqual` = JSON 串比较，故键序
+ * 也算内容的一部分）。这不是偷懒：定义一律由 moddle 产出，键序稳定；
+ * 只为"比较两个定义"再发明一套比较器，才是真正会漂移的东西。
+ */
+
+/**
+ * 宿主声明的「一格图纸」。
+ *
+ * ⚠️ `definition` 必须是**宿主仓库里这一格的真实内容** —— 套件拿它当期望值。
+ *    声明错了套件会红（第一条用例就是干这个的），不会静默放过。
+ */
+interface DefinitionFixture {
+    processId: string;
+    version: number;
+    /** 该 `(processId, version)` 期望取回的内容 */
+    definition: ProcessDefinition;
+}
+interface DefinitionConformanceOptions {
+    /** 被测实现的自述（进报告抬头，便于区分多套实现） */
+    subject?: string;
+}
+/**
+ * 跑 `DefinitionSource` 全量契约用例。
+ *
+ * 前置：`fixtures` 须含**同一 `processId` 的 ≥2 个版本**，且这些版本的内容**互不相同**
+ * —— 否则「忽略 `version`」这类缺陷**无法被观测**（返回什么都一样），套件第一条会点名。
+ */
+declare function runDefinitionConformance(source: DefinitionSource, fixtures: readonly DefinitionFixture[], options?: DefinitionConformanceOptions): Promise<ConformanceReport>;
+
+export { type ConformanceCase, type ConformanceReport, type DefinitionConformanceOptions, type DefinitionFixture, type ProjectionConformanceOptions, type ProjectionReadback, type StoreConformanceOptions, formatConformanceReport, runDefinitionConformance, runProjectionConformance, runStoreConformance };