@danceiny/gotry 0.0.1-rc.21 → 0.0.1-rc.24

package/dist/src/booking-saga.js

@@ -1,120 +1,83 @@
+/**
+ * 预订 saga 状态机(booking_saga_fsm.v1)——issue #17 采纳三点的具名化落点。
+ *
+ * 立场(docs/design/booking-saga-fsm.md / ADR-17):不引入编排框架;预订 saga 的状态字母表与边表
+ * 就是账本 pending_writes(status CHECK:pending|confirmed|compensated)的显式化。
+ * 本模块是纯函数词汇层,零依赖、零行为、不接线任何 seam——M5 拍板 WriteGate 生产化时
+ * 以此为唯一状态推进词汇(具名化 = 状态与边不再散落在 SQL 字符串里)。
+ *
+ * 物理对账目标(state-ledger.ts,TS-4 基座):
+ *  - propose  = requestPendingWrite(∅ → pending,L2 只登记不执行;idem_key UNIQUE,重复提议 no-op)
+ *  - confirm  = confirmPendingWrite(pending → confirmed,L3 具名 seam 确认,携 receipt;无 receipt 则视为缺省空串)
+ *  - compensate = compensatePendingWrite(pending|confirmed → compensated,吸收态,无出边)
+ *  - 审计事件 kind:write.pending / write.confirmed / write.compensated
+ */
 export const BOOKING_SAGA_SCHEMA = 'booking_saga_fsm.v1';
-export const SAGA_STATUSES = [
-    'pending',
-    'confirmed',
-    'compensated'
-];
+/** 状态字母表(与 pending_writes.status CHECK 约束逐字一致) */
+export const SAGA_STATUSES = ['pending', 'confirmed', 'compensated'];
+/**
+ * 边表(预订流程 FSM 的全部合法转移):
+ *  ∅ --propose--> pending --confirm--> confirmed
+ *        │             │
+ *        └---(任何状态) --compensate--> compensated(吸收态,无出边)
+ */
 export const SAGA_EDGES = [
-    {
-        from: 'none',
-        trigger: 'propose',
-        to: 'pending',
-        event: 'write.pending',
-        guard: 'L2 只登记不执行;idem_key UNIQUE(重复提议 no-op)'
-    },
-    {
-        from: 'pending',
-        trigger: 'confirm',
-        to: 'confirmed',
-        event: 'write.confirmed',
-        guard: 'L3 具名 seam 确认,必携 receipt;已确认不可再确认'
-    },
-    {
-        from: 'pending',
-        trigger: 'compensate',
-        to: 'compensated',
-        event: 'write.compensated',
-        guard: '外部写未发生,取消即终态(无补偿动作)'
-    },
-    {
-        from: 'confirmed',
-        trigger: 'compensate',
-        to: 'compensated',
-        event: 'write.compensated',
-        guard: '已发生副作用的 saga 补偿(退改),receipt 保留(COALESCE)'
-    }
+    { from: 'none', trigger: 'propose', to: 'pending', event: 'write.pending', guard: 'L2 只登记不执行;idem_key UNIQUE(重复提议 no-op)' },
+    { from: 'pending', trigger: 'confirm', to: 'confirmed', event: 'write.confirmed', guard: 'L3 具名 seam 确认,必携 receipt;已确认不可再确认' },
+    { from: 'pending', trigger: 'compensate', to: 'compensated', event: 'write.compensated', guard: '外部写未发生,取消即终态(无补偿动作)' },
+    { from: 'confirmed', trigger: 'compensate', to: 'compensated', event: 'write.compensated', guard: '已发生副作用的 saga 补偿(退改),receipt 保留(COALESCE)' },
 ];
+/** 非边组合的拒绝理由(结构化,拒绝即不动——与账本 changes=0 同义) */
 export const SAGA_REJECTIONS = [
-    {
-        from: 'none',
-        trigger: 'confirm',
-        reason: 'missing-subject'
-    },
-    {
-        from: 'none',
-        trigger: 'compensate',
-        reason: 'missing-subject'
-    },
-    {
-        from: 'pending',
-        trigger: 'propose',
-        reason: 'idem-exists'
-    },
-    {
-        from: 'confirmed',
-        trigger: 'propose',
-        reason: 'idem-exists'
-    },
-    {
-        from: 'confirmed',
-        trigger: 'confirm',
-        reason: 'already-confirmed'
-    },
-    {
-        from: 'compensated',
-        trigger: 'propose',
-        reason: 'idem-exists'
-    },
-    {
-        from: 'compensated',
-        trigger: 'confirm',
-        reason: 'absorbed-compensated'
-    },
-    {
-        from: 'compensated',
-        trigger: 'compensate',
-        reason: 'already-compensated'
-    }
+    { from: 'none', trigger: 'confirm', reason: 'missing-subject' },
+    { from: 'none', trigger: 'compensate', reason: 'missing-subject' },
+    { from: 'pending', trigger: 'propose', reason: 'idem-exists' },
+    { from: 'confirmed', trigger: 'propose', reason: 'idem-exists' },
+    { from: 'confirmed', trigger: 'confirm', reason: 'already-confirmed' },
+    { from: 'compensated', trigger: 'propose', reason: 'idem-exists' },
+    { from: 'compensated', trigger: 'confirm', reason: 'absorbed-compensated' },
+    { from: 'compensated', trigger: 'compensate', reason: 'already-compensated' },
 ];
+/** 触发解析:唯一归宿或结构化拒绝(预订 seam 的状态推进只许走这张表的边) */
 export function resolveSagaTrigger(origin, trigger) {
-    const edge = SAGA_EDGES.find((e)=>e.from === origin && e.trigger === trigger);
-    if (edge) return {
-        ok: true,
-        from: origin,
-        trigger,
-        to: edge.to,
-        event: edge.event,
-        guard: edge.guard,
-        reason: null
-    };
-    const rejection = SAGA_REJECTIONS.find((e)=>e.from === origin && e.trigger === trigger);
-    return {
-        ok: false,
-        from: origin,
-        trigger,
-        to: null,
-        event: null,
-        guard: null,
-        reason: rejection.reason
-    };
+    const edge = SAGA_EDGES.find(e => e.from === origin && e.trigger === trigger);
+    if (edge)
+        return { ok: true, from: origin, trigger, to: edge.to, event: edge.event, guard: edge.guard, reason: null };
+    const rejection = SAGA_REJECTIONS.find(e => e.from === origin && e.trigger === trigger);
+    return { ok: false, from: origin, trigger, to: null, event: null, guard: null, reason: rejection.reason };
 }
+/** 触发器 → 账本事件 kind 的唯一映射(写入侧命名不再各处硬编码) */
 export const SAGA_TRIGGER_EVENT = {
     propose: 'write.pending',
     confirm: 'write.confirmed',
-    compensate: 'write.compensated'
+    compensate: 'write.compensated',
 };
+/** 账本事件 kind → 触发器(读取/审计侧);非 saga 事件返回 null */
 export function triggerOfEventKind(kind) {
-    if (kind === 'write.pending') return 'propose';
-    if (kind === 'write.confirmed') return 'confirm';
-    if (kind === 'write.compensated') return 'compensate';
+    if (kind === 'write.pending')
+        return 'propose';
+    if (kind === 'write.confirmed')
+        return 'confirm';
+    if (kind === 'write.compensated')
+        return 'compensate';
     return null;
 }
+/**
+ * 审计链校验(单 idem_key 的 write.* 事件序列):必须恰好走出边表的一条合法路径。
+ *  - 链以 write.pending 开头;
+ *  - confirm/compensate 至多各一次;
+ *  - compensated 之后不允许任何 saga 事件(吸收态);
+ *  - write.confirmed 的 receipt 为空(缺省/空串)即违例——L3 具名确认必携外部回执;
+ *  - 非 write.* 事件(其他域审计)穿插不计。
+ * 返回违例清单(空数组 = 链合法)。
+ */
 export function sagaTraceViolations(events) {
     const violations = [];
     let stage = 'none';
-    for (const ev of events){
+    for (const ev of events) {
         const trigger = triggerOfEventKind(ev.kind);
-        if (!trigger) continue;
+        if (!trigger)
+            continue;
         const verdict = resolveSagaTrigger(stage, trigger);
         const at = `seq=${ev.seq ?? '?'} ${ev.kind}`;
         if (!verdict.ok) {
@@ -128,26 +91,7 @@ export function sagaTraceViolations(events) {
     }
     return violations;
 }
+/** 完整合法路径集合(文档/测试共用):∅→pending→confirmed→compensated 与其前缀 */
 export function sagaLegalPaths() {
-    return [
-        [
-            'propose'
-        ],
-        [
-            'propose',
-            'compensate'
-        ],
-        [
-            'propose',
-            'confirm'
-        ],
-        [
-            'propose',
-            'confirm',
-            'compensate'
-        ]
-    ];
+    return [['propose'], ['propose', 'compensate'], ['propose', 'confirm'], ['propose', 'confirm', 'compensate']];
 }
-
-
-//# sourceURL=ts/src/booking-saga.ts