@floken-io/engine 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -3,6 +3,37 @@
 本包遵循 [Semantic Versioning](https://semver.org/)，格式参考 [Keep a Changelog](https://keepachangelog.com/)。
 0.x 阶段跨包依赖写 `>=x.y.z <1.0.0`（不用 `^`）。
 
+## 0.0.2 — 2026-10-02
+
+### 新增
+
+- ★ **宿主自定义扩展属性（ADR-009）**：`@floken-io/designer` 上配的自定义属性（`node.extension['acme:priority']`）
+  现在能被条件直接用，不必再注入 `conditionHandler` 手写回查。分两级：
+  - **第一级（恒给，无需配置）**：`ConditionCtx` 增 `nodeExtensions`（当前节点）与
+    `targetExtensions`（该分支的**目标节点**）两个只读字段。键**带前缀**原样给出，排除 `floken:*`、**只含标量**。
+  - **第二级（opt-in）**：配置 `EngineConfig.extensionVars` 后并入求值上下文，
+    挂成 `variables.node` / `variables.target`，条件可直接写 `target.priority = "high"`。
+- ★ **类型还原可按声明做**：`extensionVars.casts`（如 `{ 'acme:slaHours': 'number' }`）。
+  起因是 XML 往返后扩展属性的值**一律是字符串**（实测 `48 → "48"`），而 `"48" > 24` 会按字符串比较；
+  引擎**不猜类型**（猜 = 静默错误），按声明转换，转不动就抛 `ENGINE_OPTION_INVALID`。
+
+### 变更
+
+- `ConditionUnresolved` 内部哨兵增 `toNodeId`（原先只带源节点，取不到目标节点的扩展属性）。
+  该哨兵**不是**公开 API 的一部分（引擎吞掉并重试），宿主不会收到它。
+
+### 兼容性
+
+- **不声明 `extensionVars` 时行为与 0.0.1 逐字一致**：只读字段是纯增量，`variables` 一个键都不多。
+- ⚠️ 已知代价（行为已钉死、文档如实写明）：**不 opt-in 却在表达式里写 `target.*`
+  → 不报错、静默走另一条分支**（`target` 未定义时等值比较求值为 `false`，
+  与 `amount > 5000` 缺变量求值为 `null` 而抛错的语义不同）。
+
+### 验证
+
+- 单测 **701**（+16，新增 `test/extension-vars.test.ts`）；冷启动探针 **103**（+5，跑真 `dist/`）；
+  `verify` 六道门禁全绿。
+
 ## 0.0.1 — 2026-10-01
 
 首发。令牌制流程内核 + 中国式审批动作，覆盖 `03` 的阶段 **E1~E9**（685 单测 / `verify` 六道门禁全绿 /

package/dist/conformance.d.ts

@@ -1,4 +1,4 @@
-import { S as StateStore, T as TaskView, a as TaskProjection, D as DefinitionSource } from './spi-BABH0Tcs.js';
+import { S as StateStore, T as TaskView, a as TaskProjection, D as DefinitionSource } from './spi-BVNWxdCQ.js';
 import { ProcessDefinition } from '@floken-io/moddle';
 
 /**

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { A as ActionRecord, I as InstanceStateHeader, b as TaskDelta, c as Token, d as InstanceState, T as TaskView, V as VoteOutcome, e as InstanceParent, E as EngineEvent, f as TimeoutSpec, g as TraceEntry, h as InstanceStatus, i as EventSink, j as InstanceEventName, S as StateStore, D as DefinitionSource, a as TaskProjection, k as ApproverSource, l as ServiceHandler, m as AuthResolver, F as FormProvider, C as ConditionHandler, n as DecisionHandler, o as Scheduler, p as ConditionCtx } from './spi-BABH0Tcs.js';
-export { q as ApproverCtx, r as AuditEntry, s as DecisionCtx, t as ENGINE_EVENT_NAMES, u as EngineEventName, v as FormCtx, w as INSTANCE_EVENT_NAMES, x as INSTANCE_STATUSES, y as InstanceEvent, z as InstanceStateBody, B as SPI_GROUPS, G as SPI_NAMES, H as STATE_SCHEMA_VERSION, J as ScheduleRequest, K as ServiceCtx, L as ServiceHandlerFn, M as SpiInterfaces, N as SpiName, O as TASK_EVENT_NAMES, P as TASK_STATUSES, Q as TERMINAL_STATUSES, R as TOKEN_STATES, U as TaskEvent, W as TaskEventName, X as TaskStatus, Y as TokenAwait, Z as TokenState, _ as isInstanceEvent, $ as isTaskEvent, a0 as isTerminalStatus, a1 as subjectTokenOf } from './spi-BABH0Tcs.js';
+import { A as ActionRecord, I as InstanceStateHeader, b as TaskDelta, c as Token, d as InstanceState, T as TaskView, V as VoteOutcome, e as InstanceParent, E as EngineEvent, f as TimeoutSpec, g as TraceEntry, h as InstanceStatus, i as EventSink, j as InstanceEventName, S as StateStore, D as DefinitionSource, a as TaskProjection, k as ApproverSource, l as ServiceHandler, m as AuthResolver, F as FormProvider, C as ConditionHandler, n as DecisionHandler, o as Scheduler, p as ConditionCtx } from './spi-BVNWxdCQ.js';
+export { q as ApproverCtx, r as AuditEntry, s as DecisionCtx, t as ENGINE_EVENT_NAMES, u as EngineEventName, v as FormCtx, w as INSTANCE_EVENT_NAMES, x as INSTANCE_STATUSES, y as InstanceEvent, z as InstanceStateBody, B as SPI_GROUPS, G as SPI_NAMES, H as STATE_SCHEMA_VERSION, J as ScheduleRequest, K as ServiceCtx, L as ServiceHandlerFn, M as SpiInterfaces, N as SpiName, O as TASK_EVENT_NAMES, P as TASK_STATUSES, Q as TERMINAL_STATUSES, R as TOKEN_STATES, U as TaskEvent, W as TaskEventName, X as TaskStatus, Y as TokenAwait, Z as TokenState, _ as isInstanceEvent, $ as isTaskEvent, a0 as isTerminalStatus, a1 as subjectTokenOf } from './spi-BVNWxdCQ.js';
 import { NormalizedApproval, ApprovalMode, OnReject, TimeoutAction, NormalizedTimeout } from '@floken-io/moddle';
 
 /**
@@ -1209,6 +1209,17 @@ interface ProcessGraph {
      * 而不是等触发 —— 那时已经写了一半状态。
      */
     boundaryOf(nodeId: string): readonly BoundaryBinding[];
+    /**
+     * ★ 该节点上的**宿主自定义**扩展属性（ADR-009 细则①②③④）。
+     *
+     * 给出去的是**原样键值**，引擎**不解释** `acme:priority` 是什么意思 ——
+     * 解释权 100% 在宿主（源码里不得出现任何具体宿主前缀）。
+     *
+     * - 排除 `floken:*`（引擎自己的键）与 `_extensionElements`（第三方原样快照）；
+     * - **只留标量**；
+     * - **一个都没有 → `undefined`**（不填空对象 —— 调用方要能区分「没配」与「配了但被过滤空」）。
+     */
+    extensionsOf(nodeId: string): Readonly<Record<string, unknown>> | undefined;
 }
 
 /**
@@ -1790,6 +1801,42 @@ interface EngineConfig {
     clock?: () => string;
     /** INV-17 审计上限 */
     maxAuditEntries?: number;
+    /**
+     * ★ ADR-009：把宿主自定义扩展属性**并入求值上下文**（opt-in）。
+     *
+     * 不声明 → 只给 `ctx.nodeExtensions` / `ctx.targetExtensions` 两个**只读**字段，
+     * **不并入** `variables`（0.0.1 语义逐字不变）。
+     */
+    extensionVars?: ExtensionVarsOption;
+}
+/**
+ * ★ ADR-009 的 opt-in 配置。
+ *
+ * 为什么并入形态是**两个对象**而不是把键平铺进 `variables`：
+ * 平铺的撞车面是「每个键」（表单字段 / 脚本产出的变量都可能同名），
+ * 撞了就要决出胜负 —— 静默覆盖正是 §7.2 要防的头号事故。
+ * 挂成 `variables.node` / `variables.target` 后，撞车面降到「两个名字」，
+ * 且语义天然分层：**设计期配置** vs **运行期数据**。
+ */
+interface ExtensionVarsOption {
+    /**
+     * ★ **当前节点**扩展属性并入后的顶层键名（默认 `'node'`）。
+     *
+     * ⚠️ 若流程变量里已有同名键 → 抛 `ENGINE_OPTION_INVALID`（**不静默覆盖**，细则⑦）。
+     * 撞了就改这个名字，不要去改业务变量 —— 那会把业务数据挤掉。
+     */
+    key?: string;
+    /** ★ **目标节点**扩展属性并入后的顶层键名（默认 `'target'`）；冲突处置同 `key` */
+    targetKey?: string;
+    /**
+     * ★ 类型还原表：`'acme:slaHours'` → `'number'`。
+     *
+     * 为什么必须有：`moddle` 从 XML 读回的扩展属性**一律是字符串**（实测 `48 → "48"`），
+     * 而 `slaHours > 24` 遇到 `"48"` 会按字符串比较 → 抛错。
+     * 引擎**不猜类型**（`"48"` 究竟是数字还是编号？猜 = 静默错误），按本表声明转换。
+     * 二期改由模型内 `floken:extensionTypes` 声明块承载（仍是 `floken:` 命名空间）。
+     */
+    casts?: Readonly<Record<string, 'number' | 'boolean' | 'iso-date'>>;
 }
 interface StartOptions {
     /** ✅ 必填（AC-E10：实例绑定定义版本，改版不影响在途） */

package/dist/index.js

@@ -1377,6 +1377,11 @@ function boundaryTokenOf(state, fire, host) {
 // src/nodes/graph.ts
 var WAITING_NODE_TYPES = ["userTask"];
 var APPROVAL_EXT_KEY = "floken:approval";
+var FLOKEN_EXT_PREFIX = "floken:";
+var RAW_SNAPSHOT_KEY = "_extensionElements";
+function isScalarValue(v) {
+  return v === null || typeof v === "string" || typeof v === "number" || typeof v === "boolean";
+}
 function isWaitingNode(type) {
   return WAITING_NODE_TYPES.includes(type);
 }
@@ -1431,6 +1436,7 @@ function createProcessGraph(definition, processId, definitionVersion) {
     throw definitionMissing(processId, definitionVersion);
   }
   const approvalCache = /* @__PURE__ */ new Map();
+  const extCache = /* @__PURE__ */ new Map();
   const boundaries = /* @__PURE__ */ new Map();
   for (const n of flatNodes) {
     if (n === null || typeof n !== "object" || n.type !== "boundaryEvent") continue;
@@ -1515,6 +1521,23 @@ function createProcessGraph(definition, processId, definitionVersion) {
       return value;
     },
     hasApproval: (nodeId) => nodes.get(nodeId)?.extension?.[APPROVAL_EXT_KEY] !== void 0,
+    extensionsOf(nodeId) {
+      if (extCache.has(nodeId)) return extCache.get(nodeId);
+      const raw = nodes.get(nodeId)?.extension;
+      let value;
+      if (raw !== void 0 && typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+        const out2 = {};
+        for (const [key, v] of Object.entries(raw)) {
+          if (key.startsWith(FLOKEN_EXT_PREFIX)) continue;
+          if (key === RAW_SNAPSHOT_KEY) continue;
+          if (!isScalarValue(v)) continue;
+          out2[key] = v;
+        }
+        value = Object.keys(out2).length > 0 ? Object.freeze(out2) : void 0;
+      }
+      extCache.set(nodeId, value);
+      return value;
+    },
     scriptOf: (nodeId) => {
       const s = nodes.get(nodeId)?.script;
       if (typeof s !== "string") return void 0;
@@ -2753,6 +2776,14 @@ var ConditionUnresolved = class extends Error {
   flowId;
   expression;
   nodeId;
+  /**
+   * ★ 该条件所在顺序流的**目标节点**（ADR-009 细则②）。
+   *
+   * 只有带上它，重跑时才能取出「这条分支通向的那个节点」的自定义扩展属性。
+   * 拿不到时为 `undefined`（宿主在门 2 自提供 `conditionsOf` 闭包时不会发生本哨兵，
+   * 但引擎自己的调用点**恒有** `OutFlow.to`）。
+   */
+  toNodeId;
   /**
    * ★ **到达该网关那一刻**的变量快照（T17）。
    *
@@ -2761,16 +2792,17 @@ var ConditionUnresolved = class extends Error {
    * 就被忽略了 —— 表现为「脚本把 amount 改成了 9000，网关却按旧值走了分支」。
    */
   variables;
-  constructor(flowId, expression, nodeId, variables = {}) {
+  constructor(flowId, expression, nodeId, variables = {}, toNodeId = void 0) {
     super(`condition of flow '${flowId}' is not resolved yet`);
     this.flowId = flowId;
     this.expression = expression;
     this.nodeId = nodeId;
     this.variables = variables;
+    this.toNodeId = toNodeId;
   }
 };
-function unresolvedCondition(flowId, expression, nodeId, variables = {}) {
-  return new ConditionUnresolved(flowId, expression, nodeId, variables);
+function unresolvedCondition(flowId, expression, nodeId, variables = {}, toNodeId = void 0) {
+  return new ConditionUnresolved(flowId, expression, nodeId, variables, toNodeId);
 }
 function asUnresolved(e) {
   if (e instanceof ConditionUnresolved) return e;
@@ -2819,7 +2851,8 @@ var ENGINE_CONFIG_KEYS = [
   "scheduler",
   "hooks",
   "clock",
-  "maxAuditEntries"
+  "maxAuditEntries",
+  "extensionVars"
 ];
 function assertEngineConfig(config) {
   if (typeof config !== "object" || config === null || Array.isArray(config)) {
@@ -2862,6 +2895,45 @@ function assertEngineConfig(config) {
       throw optionInvalid("maxAuditEntries", "must be a positive integer", n);
     }
   }
+  assertExtensionVars(c.extensionVars);
+}
+function assertExtensionVars(v) {
+  if (v === void 0) return;
+  if (typeof v !== "object" || v === null || Array.isArray(v)) {
+    throw optionInvalid("extensionVars", "must be a plain object", v);
+  }
+  const o = v;
+  const allowed = ["key", "targetKey", "casts"];
+  for (const key of Object.keys(o)) {
+    if (!allowed.includes(key)) {
+      throw optionUnknown(`extensionVars.${key}`, allowed);
+    }
+  }
+  const assertKeyName = (field) => {
+    const k = o[field];
+    if (k === void 0) return;
+    if (typeof k !== "string" || k.length === 0 || k.includes(".")) {
+      throw optionInvalid(`extensionVars.${field}`, 'must be a non-empty string without "."', k);
+    }
+  };
+  assertKeyName("key");
+  assertKeyName("targetKey");
+  if (o.casts !== void 0) {
+    const casts = o.casts;
+    if (typeof casts !== "object" || casts === null || Array.isArray(casts)) {
+      throw optionInvalid("extensionVars.casts", "must be a plain object", casts);
+    }
+    const kinds = ["number", "boolean", "iso-date"];
+    for (const [key, kind] of Object.entries(casts)) {
+      if (!kinds.includes(kind)) {
+        throw optionInvalid(
+          `extensionVars.casts['${key}']`,
+          `must be one of ${kinds.join(" | ")}`,
+          kind
+        );
+      }
+    }
+  }
 }
 function assertStartOptions(opts) {
   if (typeof opts !== "object" || opts === null || Array.isArray(opts)) {
@@ -2907,6 +2979,70 @@ function newInstanceId() {
   const rand = Math.random().toString(36).slice(2, 10);
   return `pi_${Date.now().toString(36)}_${instanceSeq.toString(36)}_${rand}`;
 }
+function applyExtensionCast(key, value, kind) {
+  if (kind === "number") {
+    if (typeof value === "number") return value;
+    if (typeof value === "string" && value.trim() !== "") {
+      const n = Number(value);
+      if (!Number.isNaN(n)) return n;
+    }
+  } else if (kind === "boolean") {
+    if (typeof value === "boolean") return value;
+    if (value === "true") return true;
+    if (value === "false") return false;
+  } else {
+    return value;
+  }
+  throw optionInvalid(
+    `extensionVars.casts['${key}']`,
+    `declared as '${kind}' but the value cannot be converted`,
+    value
+  );
+}
+function stripExtPrefix(key) {
+  const i = key.indexOf(":");
+  return i === -1 ? key : key.slice(i + 1);
+}
+function castExtensionBag(bag, casts) {
+  if (bag === void 0) return void 0;
+  const out = {};
+  for (const [key, value] of Object.entries(bag)) {
+    const kind = casts?.[key];
+    const v = kind === void 0 ? value : applyExtensionCast(key, value, kind);
+    const name = stripExtPrefix(key);
+    if (Object.prototype.hasOwnProperty.call(out, name)) {
+      throw optionInvalid(
+        "extensionVars",
+        `two extension keys collapse to the same variable name '${name}' after stripping the namespace prefix`,
+        { name, bag: Object.keys(bag) }
+      );
+    }
+    out[name] = v;
+  }
+  return out;
+}
+function mergeExtensionVars(base, nodeExt, targetExt, opt) {
+  if (opt === void 0) return base;
+  const casts = opt.casts;
+  const nodeBag = castExtensionBag(nodeExt, casts);
+  const targetBag = castExtensionBag(targetExt, casts);
+  if (nodeBag === void 0 && targetBag === void 0) return base;
+  const out = { ...base };
+  const put = (name, bag) => {
+    if (bag === void 0) return;
+    if (Object.prototype.hasOwnProperty.call(out, name)) {
+      throw optionInvalid(
+        "extensionVars",
+        `cannot merge extension vars: a variable named '${name}' already exists \u2014 rename via extensionVars.key / targetKey`,
+        { name, existing: out[name] }
+      );
+    }
+    out[name] = bag;
+  };
+  put(opt.key ?? "node", nodeBag);
+  put(opt.targetKey ?? "target", targetBag);
+  return out;
+}
 function createEngine(config) {
   assertEngineConfig(config);
   const clock = config.clock ?? defaultClock;
@@ -2916,6 +3052,7 @@ function createEngine(config) {
   const scheduler = config.scheduler;
   const approverSource = config.approverSource ?? DEFAULT_APPROVER_SOURCE;
   const condition = config.conditionHandler ?? createFeelConditionHandler();
+  const extensionVars = config.extensionVars;
   const handlers = config.handlers;
   const decisionHandler = config.decisionHandler;
   const maxAuditEntries = config.maxAuditEntries;
@@ -2943,7 +3080,7 @@ function createEngine(config) {
       if (flow.expression === void 0) return true;
       const value = conditions.get(flow.id);
       if (value === void 0) {
-        throw unresolvedCondition(flow.id, flow.expression, nodeId, variables);
+        throw unresolvedCondition(flow.id, flow.expression, nodeId, variables, flow.to);
       }
       return value;
     };
@@ -3029,13 +3166,18 @@ function createEngine(config) {
             instanceId: state.instanceId
           });
         }
+        const nodeExt = graph.extensionsOf(pending.nodeId);
+        const targetExt = pending.toNodeId === void 0 ? void 0 : graph.extensionsOf(pending.toNodeId);
         conditions.set(
           pending.flowId,
           await evaluateCondition(condition, pending.expression, {
             instanceId: state.instanceId,
             nodeId: pending.nodeId,
             // ★ 用**到达该网关那一刻**的变量快照（哨兵带来），不是提交前的旧值
-            variables: pending.variables
+            //   ⚠️ 扩展属性只在**求值上下文**里并入，绝不写回 state（ADR-009 细则⑨）
+            variables: mergeExtensionVars(pending.variables, nodeExt, targetExt, extensionVars),
+            nodeExtensions: nodeExt,
+            targetExtensions: targetExt
           })
         );
       }

package/dist/{spi-BABH0Tcs.d.ts → spi-BVNWxdCQ.d.ts}

@@ -521,6 +521,25 @@ interface ConditionCtx {
     instanceId: string;
     nodeId: string;
     variables: Readonly<Record<string, unknown>>;
+    /**
+     * ★ **当前节点**（`nodeId`，即条件所在的网关 / 活动）上的宿主自定义扩展属性（ADR-009）。
+     *
+     * - 键**带前缀**原样给出（`acme:priority`），引擎**不解释**其语义；
+     * - 排除 `floken:*`（引擎自己的键）；**只含标量**；
+     * - 没有 → `undefined`（不填空对象）。
+     *
+     * ⚠️ 它**恒给**（不需任何配置）；"自动并入 `variables`"才需要 opt-in（见 `EngineConfig.extensionVars`）。
+     */
+    nodeExtensions: Readonly<Record<string, unknown>> | undefined;
+    /**
+     * ★ 该条件所在**顺序流的目标节点**上的自定义扩展属性（ADR-009 细则②）。
+     *
+     * 为什么必须两个都给：条件挂在**顺序流**上，而"加急等级"这类业务属性通常挂在
+     * **审批节点**（目标）而不是网关（当前节点）上 —— 只给一个，另一个场景就得回退到手写 handler。
+     *
+     * ⚠️ 求值时**拿不到目标**（如宿主在门 2 自提供 `conditionsOf` 闭包）→ `undefined`。
+     */
+    targetExtensions: Readonly<Record<string, unknown>> | undefined;
 }
 /**
  * 网关分支 / 顺序流条件求值。**不注入 = 内置 `@floken-io/feel`**（S-FEEL 子集）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floken-io/engine",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Token-based process engine with Chinese-style approval actions for floken",
   "repository": { "type": "git", "url": "git+https://github.com/floken-io/floken-engine.git" },
   "bugs": { "url": "https://github.com/floken-io/floken-engine/issues" },