@floken-io/engine 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+本包遵循 [Semantic Versioning](https://semver.org/)，格式参考 [Keep a Changelog](https://keepachangelog.com/)。
+0.x 阶段跨包依赖写 `>=x.y.z <1.0.0`（不用 `^`）。
+
+## 0.0.1 — 2026-10-01
+
+首发。令牌制流程内核 + 中国式审批动作，覆盖 `03` 的阶段 **E1~E9**（685 单测 / `verify` 六道门禁全绿 /
+冷启动探针 98 项跑真 `dist/`）。
+
+### 新增
+
+- **内核**：10 个业务无知原语 + 令牌推进 + run-to-wait（跑到稳定点才停）；状态分 Header（宿主建列）+ Body
+  （不透明 JSON）两层，`JSON.stringify` 出得来（AC-E8）。
+- **19 项审批动作**：其中 **17 项内核原生执行**；超时与暂存 2 项在内核外（经 `Scheduler` SPI 驱动）。
+  设计期未开启的动作提交即抛错（AC-E2）；`enabledActionNames()` 是「按钮该不该灰」的唯一判据。
+- **会签 / 或签 / 票签**：计票口径为「已表态 + 仍在途」，含 `03` §5.3 的**反向提前终止三条**；
+  组结算后解散、承接令牌另造。
+- **节点**：22 类 L3 执行语义，含子流程 / 调用活动（版本绑定，**绝不回退到别的版本**）、
+  `intermediateCatchEvent` / `receiveTask` 的等待语义、边界事件（中断 / 非中断）、
+  `Transaction` 的 `cancel`、`EventBasedGateway` 竞速。
+- **两条集成路径**：`submit()`（门 1，save 后触发 hooks）与 `plan()`（门 2 纯函数，宿主自己包事务）——
+  两条路径的状态演化**完全一致**，由测试钉死，不靠纪律。
+- **一致性**：快照 + `rev` CAS（`expectedRev === 0` = INSERT 信号）+ 进程内 per-instance 串行队列。
+- **投递**：`deliverMessage`（点对点）/ `deliverSignal`（广播）；未命中抛错并列出合法取值。
+- **令牌轨迹**：`exportTrace()` 返回 `TraceResult`（含 `truncated`），是 `auditTrail` 的只读投影，不新增存储。
+- **11 项 SPI**；`createMemoryStore()` 不传即用；`runStoreConformance` / `runProjectionConformance` /
+  `runDefinitionConformance` 三套契约测试供宿主验证自研实现。
+
+### 刻意不做（不是欠账，是设计取向）
+
+- **内核不定时**：`ScheduleRequest` 只交 `fromAt` + 原始 `TimeoutSpec`，**不交 `dueAt`**——
+  工作日历是业务数据，且时态库不得进 `dist`。不注入 `Scheduler` 就是真的不排程。
+- **原语级审计已否决**（差异表 D-87）：run-to-wait 的令牌推进不走 `advance` 原语，
+  按原语记账会造出一份「没有令牌移动的轨迹」，且一次提交炸几十条会扭曲 `maxAuditEntries`。
+  故审计恒定**一次动作一条**。
+- 已知但未实现的节点类型一律**显式抛错**并指名归属需求编号，不降级成自动直通
+  （`sendTask` / `intermediateThrowEvent` / `implicitThrowEvent` / `complexGateway` /
+  `AdHocSubProcess` / 补偿处理器；捕获事件目前只认 `message` / `signal`）。

package/LICENSE

@@ -0,0 +1,153 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or agreed
+      to in writing, Licensor provides the Work (and each Contributor
+      provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES
+      OR CONDITIONS OF ANY KIND, either express or implied.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages, including any direct,
+      indirect, special, incidental, or consequential damages of any
+      character arising as a result of this License or out of the use or
+      inability to use the Work.
+
+   9. Accepting Warranty or Additional Liability. While redistributing the
+      Work or Derivative Works thereof, You may choose to offer, and charge
+      a fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information.
+
+   Copyright 2026 floken contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,138 @@
+# @floken-io/engine
+
+[![npm](https://img.shields.io/npm/v/@floken-io/engine)](https://www.npmjs.com/package/@floken-io/engine)
+[![license](https://img.shields.io/npm/l/@floken-io/engine)](./LICENSE)
+
+令牌制流程内核 + 中国式审批动作（会签 / 或签 / 票签 / 加签 / 转办 / 驳回 / 撤回）。
+
+零 DOM、零数据库、零定时——持久化与调度全部经 SPI 注入，**核心引擎零基础设施依赖**。
+
+## 安装
+
+```bash
+npm i @floken-io/engine
+```
+
+`@floken-io/feel` 是默认依赖，装完即可在网关上写 `amount > 5000` 这样的条件，无需额外接线。
+
+## 快速开始
+
+一个三段报销流程，从发起到办结：
+
+```ts
+import { createEngine, createMemoryStore } from '@floken-io/engine';
+
+// 流程定义：通常由 @floken-io/moddle 从 BPMN XML 读进来，这里直接手写
+const def = {
+  schemaVersion: '1.0.0',
+  id: 'Definitions_1',
+  processes: [{
+    id: 'Process_1',
+    nodes: [
+      { id: 'Start_1', type: 'startEvent' },
+      { id: 'Task_1', type: 'userTask',
+        extension: { 'floken:approval': { approvers: [{ type: 'user', value: 'u_manager' }] } } },
+      { id: 'Task_2', type: 'userTask',
+        extension: { 'floken:approval': { approvers: [{ type: 'user', value: 'u_finance' }] } } },
+      { id: 'End_1', type: 'endEvent' },
+    ],
+    flows: [
+      { id: 'f1', from: 'Start_1', to: 'Task_1' },
+      { id: 'f2', from: 'Task_1', to: 'Task_2' },
+      { id: 'f3', from: 'Task_2', to: 'End_1' },
+    ],
+  }],
+};
+
+const engine = createEngine({
+  // 定义源是「图纸」：只读、按版本取。改版不影响在途实例
+  definitionSource: {
+    async getDefinition(processId, version) {
+      return processId === 'Process_1' && version === 1 ? def : null;
+    },
+  },
+  store: createMemoryStore(),        // 不传也是它
+  clock: () => new Date().toISOString(), // 不传用 Date.now()，但显式传可让测试完全可复现
+});
+
+const id = await engine.start('Process_1', {
+  definitionVersion: 1,
+  starter: 'u_applicant',
+  variables: { amount: 8600 },
+});
+
+await engine.submit(id, { action: 'approve', actor: 'u_manager', comment: '同意' });
+await engine.submit(id, { action: 'approve', actor: 'u_finance' });
+
+const trace = await engine.exportTrace(id);
+console.log(trace.entries.map((e) => `${e.seq} ${e.actor} ${e.action} ${e.from} → ${e.to}`));
+// [
+//   '1 u_applicant start Start_1 → Task_1',
+//   '2 u_manager approve Task_1 → Task_2',
+//   '3 u_finance approve Task_2 → End_1'
+// ]
+```
+
+## API 面
+
+| 方法 | 用途 |
+|---|---|
+| `start(processId, opts)` | 发起实例，返回 `instanceId` |
+| `submit(instanceId, action)` | 提交一次审批动作，返回待办差分 `TaskDelta` |
+| `deliverMessage(instanceId, input)` | **点对点**投递消息，唤醒在等它的令牌 |
+| `deliverSignal(instanceIds, input)` | **广播**信号，唤醒候选里所有在等的实例 |
+| `exportTrace(instanceId)` | 导出令牌轨迹（`auditTrail` 的只读投影，不新增存储） |
+| `plan(state, action, options?)` | ★ 纯函数入口：给宿主自己包事务用（不碰存储） |
+
+`submit()` 只是 `plan()` + 落库的便利封装——**两条路径的状态演化完全一致**，由测试钉死。
+
+## 19 项审批动作
+
+`approve` / `reject` / `rejectTo` / `rollback` / `rollbackTo` / `transfer` / `delegate` /
+`delegateBack` / `addSignBefore` / `addSignAfter` / `addSignParallel` / `reduceSign` /
+`takeBack` / `revoke` / `urge` / `suspend` / `resume` / `terminate` / `skip`。
+
+其中 **17 项由内核原生执行**；**超时**与**暂存** 2 项在内核外（由调度层经 `Scheduler` SPI 驱动）。
+当前配置下哪些动作可用，用 `enabledActionNames(config)` 问——按钮该不该灰，只有这一处判据。
+
+## 11 项 SPI
+
+| 组 | 接口 | 默认 |
+|---|---|---|
+| 存储三线 | `StateStore`（真相）/ `TaskProjection`（视图）/ `DefinitionSource`（图纸） | 内存 store；后两项**必须**注入 |
+| 业务接入 | `ApproverSource` / `ServiceHandler` / `AuthResolver` / `FormProvider` | 无（不注入 = 相关节点走不通并显式报错） |
+| 求值 | `conditionHandler` / `decisionHandler` | **条件有**默认 FEEL 实现；决策无默认 |
+| 出口 | `EventSink` / `Scheduler` | 无（不注入 `Scheduler` = **不排程**，不假装做了） |
+
+## 一致性
+
+- **快照 + `rev` CAS**：`save(next, expectedRev)`，`expectedRev === 0` 是 INSERT 信号，否则 CAS UPDATE；不匹配抛 `ENGINE_PERSIST_CONFLICT`，不静默覆盖。
+- **并发三道防线**：进程内 per-instance 串行队列（主力）+ rev CAS（跨进程兜底）；不开读从库、不加悲观锁。
+- **引擎内不做事务**：要么走 `submit()`（门 1：save 后触发 hooks，至少一次 + 宿主幂等），要么用 `plan()`（门 2：纯函数，宿主自己包事务）。
+
+## 能力边界（诚实清单）
+
+已知但**未实现**的节点类型一律**显式抛错**并指名归属需求编号——引擎刻意不把它们降级成"自动直通"，
+因为那会让「这件事从来没发生过」变成一个没有报错的静默事实：
+
+`sendTask` · `intermediateThrowEvent` · `implicitThrowEvent` · `complexGateway` · `AdHocSubProcess` ·
+补偿处理器（`compensate`）；捕获事件目前只认 `message` / `signal`（等 `timer` / `error` 仍抛）。
+
+`endEvent` 的 `eventDefinition`（terminate / message）尚未区分。
+
+同样**没有**的：复杂查询与报表、作业执行器与重试框架、多租户、批量操作 API、历史归档、可视化运维台、
+时间旅行重放、分布式锁（只有 CAS 重试）。这些归宿主——`03-包需求` §9.6 写明这是设计取向，不是欠账。
+
+## 相关包
+
+| 包 | 用途 |
+|---|---|
+| [`@floken-io/feel`](https://www.npmjs.com/package/@floken-io/feel) | FEEL 表达式语言 |
+| [`@floken-io/moddle`](https://www.npmjs.com/package/@floken-io/moddle) | BPMN 2.0 模型与 XML 转换 |
+| [`@floken-io/dmn`](https://www.npmjs.com/package/@floken-io/dmn) | DMN 1.5 决策引擎 |
+| `@floken-io/engine` | 流程内核与审批动作（本包） |
+| `@floken-io/designer` | 流程画布与审批配置面板（开发中） |
+
+## 许可证
+
+[Apache-2.0](./LICENSE)