@longzai-intelligence-state-machine/core 0.0.0-stage → 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,663 @@
+import { Result } from "@longzai-intelligence-shared-kernel/core";
+//#region src/definition.types.d.ts
+/**
+ * 状态机定义层类型集
+ *
+ * @remarks
+ *   定义层是纯数据契约，由初始状态、状态元信息与流转规则构成，不携带任何运行时状态
+ */
+/**
+ * 状态守卫函数
+ *
+ * @remarks
+ *   守卫在迁移提交前求值，返回 false 时本次迁移被拒绝，状态保持不变
+ * @typeParam C - 实例上下文类型
+ * @typeParam E - 事件名类型
+ * @param context - 实例上下文
+ * @param event - 触发事件，目标驱动迁移未携带事件时为 null
+ */
+type StateGuard<C, E> = (context: C, event: E | null) => boolean;
+/**
+ * 状态动作函数
+ *
+ * @remarks
+ *   动作在迁移提交后执行，此时状态已更新为目标状态，动作内抛出的异常向上透传
+ * @typeParam C - 实例上下文类型
+ * @typeParam E - 事件名类型
+ * @param context - 实例上下文
+ * @param event - 触发事件，目标驱动迁移未携带事件时为 null
+ */
+type StateAction<C, E> = (context: C, event: E | null) => void;
+/**
+ * 流转规则
+ *
+ * @remarks
+ *   描述一条从起始状态到目标状态的迁移通道，可选携带事件名、守卫与动作
+ * @typeParam S - 状态名类型
+ * @typeParam E - 事件名类型
+ * @typeParam C - 实例上下文类型
+ */
+type TransitionConfig<S extends string, E extends string, C> = {
+  /**
+   * 起始状态
+   */
+  from: S;
+  /**
+   * 目标状态
+   */
+  to: S;
+  /**
+   * 触发事件名
+   *
+   * @remarks
+   *   缺省时该规则仅可经实例层的目标驱动迁移触达
+   */
+  event?: E;
+  /**
+   * 状态守卫
+   *
+   * @default 不设守卫
+   */
+  guard?: StateGuard<C, E>;
+  /**
+   * 迁移提交后的动作
+   *
+   * @default 不设动作
+   */
+  action?: StateAction<C, E>;
+};
+/**
+ * 状态元信息
+ */
+type StateMeta = {
+  /**
+   * 终态标记
+   *
+   * @remarks
+   *   终态不再接受任何迁移，无出边的状态自动视为终态，无需显式标记
+   * @default false
+   */
+  terminal?: boolean;
+};
+/**
+ * 状态机定义
+ *
+ * @remarks
+ *   定义为开发期静态数据，建议书写时保留字面量类型推断以便类型层校验状态名与事件名
+ * @typeParam S - 状态名类型
+ * @typeParam E - 事件名类型
+ * @typeParam C - 实例上下文类型
+ */
+type StateMachineDefinition<S extends string, E extends string, C> = {
+  /**
+   * 初始状态
+   */
+  initial: S;
+  /**
+   * 状态元信息表
+   *
+   * @remarks
+   *   键为状态名，未列出的状态取默认元信息
+   * @default 空表
+   */
+  states?: Readonly<Partial<Record<S, StateMeta>>>;
+  /**
+   * 流转规则列表
+   */
+  transitions: readonly TransitionConfig<S, E, C>[];
+};
+//#endregion
+//#region src/validate.utils.d.ts
+/**
+ * 定义问题严重级别
+ *
+ * @remarks
+ *   `error` 表示定义不可用，`warning` 表示定义可用但存在可疑之处
+ */
+type DefinitionIssueSeverity = 'error' | 'warning';
+/**
+ * 定义问题种类标识
+ *
+ * @remarks
+ *   `duplicate-route` 为同一起始状态与同一事件对应多条流转规则
+ *   `unreachable-state` 为自初始状态出发经流转规则不可达的状态
+ *   `no-terminal` 为全定义不存在任何终态
+ */
+type DefinitionIssueKind = 'duplicate-route' | 'unreachable-state' | 'no-terminal';
+/**
+ * 定义问题条目
+ */
+type DefinitionIssue = {
+  /**
+   * 问题严重级别
+   */
+  severity: DefinitionIssueSeverity;
+  /**
+   * 问题种类标识
+   */
+  kind: DefinitionIssueKind;
+  /**
+   * 人读问题描述
+   */
+  message: string;
+};
+/**
+ * 校验状态机定义
+ *
+ * @remarks
+ *   校验项分两类，`error` 级为事件路由歧义，`warning` 级为不可达状态与无终态
+ *   全部问题按上述顺序汇总，存在 `error` 级问题时返回失败并只携带 `error` 级清单
+ * @typeParam S - 状态名类型
+ * @typeParam E - 事件名类型
+ * @typeParam C - 实例上下文类型
+ * @param definition - 待校验的状态机定义
+ * @returns 无 `error` 级问题时返回全量问题清单，否则返回定义校验失败错误
+ */
+declare function validateDefinition<S extends string, E extends string, C>(definition: StateMachineDefinition<S, E, C>): Result<readonly DefinitionIssue[], DefinitionValidationError>;
+//#endregion
+//#region src/state-machine.errors.d.ts
+/**
+ * 状态机错误基类
+ */
+declare class StateMachineError extends Error {
+  /**
+   * 创建状态机错误
+   *
+   * @param message - 人读错误描述
+   */
+  constructor(message: string);
+}
+/**
+ * 非法迁移错误
+ *
+ * @remarks
+ *   目标驱动迁移在流转表中找不到对应规则时产生
+ */
+declare class InvalidTransitionError extends StateMachineError {
+  /**
+   * 起始状态
+   */
+  readonly from: string;
+  /**
+   * 目标状态
+   */
+  readonly to: string;
+  /**
+   * 创建非法迁移错误
+   *
+   * @param from - 起始状态
+   * @param to - 目标状态
+   */
+  constructor(from: string, to: string);
+}
+/**
+ * 未路由事件错误
+ *
+ * @remarks
+ *   事件驱动迁移在当前状态下找不到事件路由时产生
+ */
+declare class UnhandledEventError extends StateMachineError {
+  /**
+   * 事件发生时所处的状态
+   */
+  readonly state: string;
+  /**
+   * 未被路由的事件
+   */
+  readonly event: string;
+  /**
+   * 创建未路由事件错误
+   *
+   * @param state - 事件发生时所处的状态
+   * @param event - 未被路由的事件
+   */
+  constructor(state: string, event: string);
+}
+/**
+ * 守卫拒绝错误
+ *
+ * @remarks
+ *   流转规则存在但守卫求值未放行时产生，状态保持不变
+ */
+declare class GuardRejectedError extends StateMachineError {
+  /**
+   * 起始状态
+   */
+  readonly from: string;
+  /**
+   * 目标状态
+   */
+  readonly to: string;
+  /**
+   * 触发事件
+   *
+   * @remarks
+   *   目标驱动迁移未携带事件时为 null
+   */
+  readonly event: string | null;
+  /**
+   * 创建守卫拒绝错误
+   *
+   * @param from - 起始状态
+   * @param to - 目标状态
+   * @param event - 触发事件，目标驱动迁移未携带事件时传 null
+   */
+  constructor(from: string, to: string, event: string | null);
+}
+/**
+ * 终态封锁错误
+ *
+ * @remarks
+ *   实例已进入终态后再发起任何迁移时产生
+ */
+declare class TerminalStateReachedError extends StateMachineError {
+  /**
+   * 已进入的终态
+   */
+  readonly state: string;
+  /**
+   * 创建终态封锁错误
+   *
+   * @param state - 已进入的终态
+   */
+  constructor(state: string);
+}
+/**
+ * 未知状态错误
+ *
+ * @remarks
+ *   引用了定义状态集之外的状态时产生，见于快照恢复与实例创建
+ */
+declare class UnknownStateError extends StateMachineError {
+  /**
+   * 定义状态集之外的状态
+   */
+  readonly state: string;
+  /**
+   * 创建未知状态错误
+   *
+   * @param state - 定义状态集之外的状态
+   */
+  constructor(state: string);
+}
+/**
+ * 定义校验失败错误
+ *
+ * @remarks
+ *   定义存在 `error` 级校验问题时产生，携带全部 `error` 级问题清单
+ */
+declare class DefinitionValidationError extends StateMachineError {
+  /**
+   * 令校验失败的 `error` 级问题清单
+   */
+  readonly issues: readonly DefinitionIssue[];
+  /**
+   * 创建定义校验失败错误
+   *
+   * @param issues - 令校验失败的 `error` 级问题清单
+   */
+  constructor(issues: readonly DefinitionIssue[]);
+}
+//#endregion
+//#region src/machine.types.d.ts
+/**
+ * 状态机规格层类型集
+ *
+ * @remarks
+ *   规格层基于定义构建索引并提供流转查询，不持有任何实例状态
+ */
+/**
+ * 状态机规格
+ *
+ * @remarks
+ *   规格可安全跨实例共享，同一规格可派生任意多个相互隔离的实例
+ * @typeParam S - 状态名类型
+ * @typeParam E - 事件名类型
+ * @typeParam C - 实例上下文类型
+ */
+type StateMachine<S extends string, E extends string, C> = {
+  /**
+   * 构建规格所用的状态机定义
+   */
+  readonly definition: StateMachineDefinition<S, E, C>;
+  /**
+   * 全量状态清单
+   *
+   * @remarks
+   *   初始状态置于首位，其余按定义中的出现顺序排列
+   */
+  readonly states: readonly S[];
+  /**
+   * 判断状态迁移是否合法
+   *
+   * @param from - 起始状态
+   * @param to - 目标状态
+   * @returns 存在 `from` 到 `to` 的流转规则时为 true
+   */
+  canTransition(from: S, to: S): boolean;
+  /**
+   * 判断状态能否响应指定事件
+   *
+   * @param state - 起始状态
+   * @param event - 触发事件
+   * @returns 存在对应事件路由时为 true
+   */
+  canHandle(state: S, event: E): boolean;
+  /**
+   * 列出某状态可达的全部目标状态
+   *
+   * @param state - 起始状态
+   * @returns 按定义顺序去重后的目标状态列表
+   */
+  availableTargets(state: S): readonly S[];
+  /**
+   * 列出某状态可响应的全部事件
+   *
+   * @param state - 起始状态
+   * @returns 按定义顺序去重后的事件列表
+   */
+  availableEvents(state: S): readonly E[];
+  /**
+   * 解析事件路由到的流转规则
+   *
+   * @param state - 起始状态
+   * @param event - 触发事件
+   * @returns 命中时返回对应流转规则，未命中时返回 `UnhandledEventError`
+   */
+  resolveTransition(state: S, event: E): Result<TransitionConfig<S, E, C>, UnhandledEventError>;
+  /**
+   * 判断是否为终态
+   *
+   * @remarks
+   *   显式标记 `terminal` 的状态与无出边状态均为终态
+   * @param state - 待判定的状态
+   * @returns 终态为 true
+   */
+  isTerminal(state: S): boolean;
+};
+//#endregion
+//#region src/instance.types.d.ts
+/**
+ * 状态机实例层类型集
+ *
+ * @remarks
+ *   实例层持有单个状态机实例的运行时状态，提供事件驱动与目标驱动两类迁移入口
+ */
+/**
+ * 迁移记录
+ *
+ * @remarks
+ *   一次成功迁移的完整留痕，字段均为可 JSON 序列化数据
+ * @typeParam S - 状态名类型
+ * @typeParam E - 事件名类型
+ * @typeParam C - 实例上下文类型
+ */
+type TransitionRecord<S extends string, E extends string, C> = {
+  /**
+   * 发生迁移的实例标识
+   */
+  instanceId: string;
+  /**
+   * 迁移前状态
+   */
+  from: S;
+  /**
+   * 迁移后状态
+   */
+  to: S;
+  /**
+   * 触发事件
+   *
+   * @remarks
+   *   目标驱动迁移未携带事件时为 null
+   */
+  event: E | null;
+  /**
+   * 迁移完成时的实例上下文
+   */
+  context: C;
+  /**
+   * 迁移发生时刻
+   *
+   * @remarks
+   *   ISO 8601 文本形态
+   */
+  occurredAt: string;
+};
+/**
+ * 状态机实例快照
+ *
+ * @remarks
+ *   快照为纯 JSON 数据，用于持久化与断点续跑，恢复时经 `restore` 回填实例
+ * @typeParam S - 状态名类型
+ * @typeParam E - 事件名类型
+ * @typeParam C - 实例上下文类型
+ */
+type MachineSnapshot<S extends string, E extends string, C> = {
+  /**
+   * 实例标识
+   */
+  id: string;
+  /**
+   * 当前状态
+   */
+  state: S;
+  /**
+   * 上一状态
+   *
+   * @remarks
+   *   实例尚无迁移时为 null
+   */
+  previousState: S | null;
+  /**
+   * 实例上下文
+   */
+  context: C;
+  /**
+   * 迁移历史
+   *
+   * @remarks
+   *   最新在后，容量受创建时 `maxHistory` 约束
+   */
+  history: readonly TransitionRecord<S, E, C>[];
+};
+/**
+ * 状态变更监听器
+ *
+ * @remarks
+ *   迁移提交并执行完动作后同步通知，监听器内抛出的异常向上透传
+ * @typeParam S - 状态名类型
+ * @typeParam E - 事件名类型
+ * @typeParam C - 实例上下文类型
+ * @param record - 本次迁移的留痕记录
+ */
+type StateChangeListener<S extends string, E extends string, C> = (record: TransitionRecord<S, E, C>) => void;
+/**
+ * 实例创建选项
+ *
+ * @typeParam S - 状态名类型
+ * @typeParam C - 实例上下文类型
+ */
+type MachineInstanceOptions<S extends string, C> = {
+  /**
+   * 实例标识
+   *
+   * @remarks
+   *   同一规格下多实例以标识区分，标识随迁移记录与快照携带
+   */
+  id: string;
+  /**
+   * 初始状态
+   *
+   * @default 取定义的 `initial`
+   */
+  initialState?: S;
+  /**
+   * 实例上下文
+   *
+   * @remarks
+   *   供守卫与动作读写，随快照一并序列化
+   */
+  context: C;
+  /**
+   * 迁移历史容量上限
+   *
+   * @default 0
+   */
+  maxHistory?: number;
+};
+/**
+ * 状态机实例
+ *
+ * @remarks
+ *   实例之间相互隔离，全部迁移入口以 `Result` 信封返回结果
+ * @typeParam S - 状态名类型
+ * @typeParam E - 事件名类型
+ * @typeParam C - 实例上下文类型
+ */
+type MachineInstance<S extends string, E extends string, C> = {
+  /**
+   * 实例标识
+   */
+  readonly id: string;
+  /**
+   * 实例所基于的规格
+   */
+  readonly machine: StateMachine<S, E, C>;
+  /**
+   * 以事件驱动一次迁移
+   *
+   * @param event - 触发事件
+   * @returns 成功时返回迁移记录，失败时返回状态机错误
+   */
+  send(event: E): Result<TransitionRecord<S, E, C>, StateMachineError>;
+  /**
+   * 以目标状态驱动一次迁移
+   *
+   * @remarks
+   *   从当前状态到目标状态存在多条规则时，取定义顺序上首条守卫放行的规则
+   * @param target - 目标状态
+   * @returns 成功时返回迁移记录，失败时返回状态机错误
+   */
+  transitionTo(target: S): Result<TransitionRecord<S, E, C>, StateMachineError>;
+  /**
+   * 读取当前状态
+   *
+   * @returns 当前状态
+   */
+  getState(): S;
+  /**
+   * 读取实例上下文
+   *
+   * @returns 实例上下文引用
+   */
+  getContext(): C;
+  /**
+   * 判断当前状态是否为终态
+   *
+   * @returns 终态为 true
+   */
+  isTerminal(): boolean;
+  /**
+   * 读取实例快照
+   *
+   * @returns 可 JSON 序列化的实例快照
+   */
+  getSnapshot(): MachineSnapshot<S, E, C>;
+  /**
+   * 从快照恢复实例状态
+   *
+   * @remarks
+   *   恢复会整体覆盖当前状态、上一状态、上下文与迁移历史
+   * @param snapshot - 此前经 `getSnapshot` 取出的快照
+   * @returns 快照状态在定义状态集内时成功，否则返回 `UnknownStateError`
+   */
+  restore(snapshot: MachineSnapshot<S, E, C>): Result<void, StateMachineError>;
+  /**
+   * 订阅状态变更
+   *
+   * @param listener - 状态变更监听器
+   * @returns 退订函数，调用后不再收到通知
+   */
+  subscribe(listener: StateChangeListener<S, E, C>): () => void;
+};
+//#endregion
+//#region src/state-name.utils.d.ts
+/**
+ * 状态名键收窄守卫
+ *
+ * @remarks
+ *   `Object.keys` 只产出字符串，而状态名的运行时形态本就是字符串
+ *   本守卫仅校验候选键为字符串，用于把映射表键收窄回状态名类型
+ * @typeParam S - 状态名类型
+ * @param key - 映射表读出的候选键
+ * @returns 候选键为字符串时为真
+ */
+declare function isStateName<S extends string>(key: string): key is S;
+//#endregion
+//#region src/adjacency.utils.d.ts
+/**
+ * 邻接表形态的状态迁移表
+ *
+ * @typeParam S - 状态名类型
+ */
+type StateAdjacency<S extends string> = Readonly<Record<S, readonly S[]>>;
+/**
+ * 邻接表转换选项
+ *
+ * @typeParam S - 状态名类型
+ */
+type FromAdjacencyOptions<S extends string> = {
+  /**
+   * 初始状态
+   */
+  initial: S;
+};
+/**
+ * 邻接表转换入口
+ *
+ * @remarks
+ *   产出的流转规则不携带事件名，仅可经实例层的目标驱动迁移触达
+ *   空目标列表或缺失键的起始状态无出边，自动视为终态
+ * @typeParam S - 状态名类型
+ * @param adjacency - 邻接表形态的状态迁移表
+ * @param options - 转换选项，须提供初始状态
+ * @returns 状态机定义
+ */
+declare function fromAdjacency<S extends string>(adjacency: StateAdjacency<S>, options: FromAdjacencyOptions<S>): StateMachineDefinition<S, never, unknown>;
+//#endregion
+//#region src/machine.factory.d.ts
+/**
+ * 创建状态机规格
+ *
+ * @remarks
+ *   创建时执行定义校验，存在 `error` 级问题时抛出 `DefinitionValidationError` 快速失败
+ *   定义属开发期静态数据，非法定义视为程序缺陷而非运行时错误
+ *   `warning` 级问题不阻断创建，可另行调用 `validateDefinition` 查看
+ * @typeParam S - 状态名类型
+ * @typeParam E - 事件名类型
+ * @typeParam C - 实例上下文类型
+ * @param definition - 状态机定义
+ * @returns 状态机规格
+ * @throws {@link DefinitionValidationError} 定义存在 `error` 级校验问题时抛出
+ */
+declare function createMachine<S extends string, E extends string, C>(definition: StateMachineDefinition<S, E, C>): StateMachine<S, E, C>;
+//#endregion
+//#region src/instance.factory.d.ts
+/**
+ * 创建状态机实例
+ *
+ * @remarks
+ *   实例与规格解耦，同一规格可派生多个相互隔离的实例
+ *   迁移提交顺序为状态更新、动作执行、历史留痕、监听器通知
+ * @typeParam S - 状态名类型
+ * @typeParam E - 事件名类型
+ * @typeParam C - 实例上下文类型
+ * @param machine - 实例所基于的规格
+ * @param options - 实例创建选项
+ * @returns 状态机实例
+ * @throws {@link UnknownStateError} 显式指定的初始状态不在定义状态集内时抛出
+ */
+declare function createMachineInstance<S extends string, E extends string, C>(machine: StateMachine<S, E, C>, options: MachineInstanceOptions<S, C>): MachineInstance<S, E, C>;
+//#endregion
+export { DefinitionIssue, DefinitionIssueKind, DefinitionIssueSeverity, DefinitionValidationError, FromAdjacencyOptions, GuardRejectedError, InvalidTransitionError, MachineInstance, MachineInstanceOptions, MachineSnapshot, StateAction, StateAdjacency, StateChangeListener, StateGuard, StateMachine, StateMachineDefinition, StateMachineError, StateMeta, TerminalStateReachedError, TransitionConfig, TransitionRecord, UnhandledEventError, UnknownStateError, createMachine, createMachineInstance, fromAdjacency, isStateName, validateDefinition };

package/dist/index.js

@@ -0,0 +1 @@
+import{failure as e,success as t}from"@longzai-intelligence-shared-kernel/core";var n=class extends Error{constructor(e){super(e),this.name=`StateMachineError`}},r=class extends n{from;to;constructor(e,t){super(`无效的状态迁移：${e} → ${t}`),this.name=`InvalidTransitionError`,this.from=e,this.to=t}},i=class extends n{state;event;constructor(e,t){super(`状态 ${e} 无法响应事件 ${t}`),this.name=`UnhandledEventError`,this.state=e,this.event=t}},a=class extends n{from;to;event;constructor(e,t,n){super(`迁移被守卫拒绝：${e} → ${t}`),this.name=`GuardRejectedError`,this.from=e,this.to=t,this.event=n}},o=class extends n{state;constructor(e){super(`状态 ${e} 已是终态，不再接受迁移`),this.name=`TerminalStateReachedError`,this.state=e}},s=class extends n{state;constructor(e){super(`未知状态：${e}`),this.name=`UnknownStateError`,this.state=e}},c=class extends n{issues;constructor(e){super(`状态机定义校验未通过，共 ${e.length} 项错误级问题`),this.name=`DefinitionValidationError`,this.issues=e}};function l(e){return typeof e==`string`}function u(e,t){let n=[];for(let t of Object.keys(e)){if(!l(t))continue;let r=e[t];for(let e of r)n.push({from:t,to:e})}return{initial:t.initial,transitions:n}}function d(n){let r=[],i=/* @__PURE__ */ new Map;for(let e of n.transitions){let t=i.get(e.from)??[];t.push(e),i.set(e.from,t)}let a=/* @__PURE__ */ new Map;for(let e of n.transitions){if(e.event===void 0)continue;let t=`${e.from}::${e.event}`,n=a.get(t)??{from:e.from,event:e.event,count:0};n.count+=1,a.set(t,n)}for(let e of a.values())e.count>1&&r.push({severity:`error`,kind:`duplicate-route`,message:`起始状态 ${e.from} 的事件 ${e.event} 对应 ${e.count} 条流转规则，事件路由存在歧义`});let o=/* @__PURE__ */ new Set([n.initial]),s=[n.initial];for(;s.length>0;){let e=s.shift();if(e!==void 0)for(let t of i.get(e)??[])o.has(t.to)||(o.add(t.to),s.push(t.to))}let u=/* @__PURE__ */ new Set([n.initial]);for(let e of Object.keys(n.states??{}))l(e)&&u.add(e);for(let e of n.transitions)u.add(e.from),u.add(e.to);for(let e of u)o.has(e)||r.push({severity:`warning`,kind:`unreachable-state`,message:`状态 ${e} 自初始状态 ${n.initial} 出发不可达`});let d=!1;for(let e of u){let t=n.states?.[e]?.terminal===!0,r=i.get(e)??[];if(t||r.length===0){d=!0;break}}d||r.push({severity:`warning`,kind:`no-terminal`,message:`状态机定义不存在任何终态，请确认是否为刻意设计的循环状态机`});let f=r.filter(e=>e.severity===`error`);return f.length>0?e(new c(f)):t(r)}function f(n){let r=d(n);if(r.isFailure)throw r.error;let a=/* @__PURE__ */ new Map,o=/* @__PURE__ */ new Map,s=[n.initial],c=/* @__PURE__ */ new Set([n.initial]);for(let e of Object.keys(n.states??{}))l(e)&&!c.has(e)&&(c.add(e),s.push(e));for(let e of n.transitions){for(let t of[e.from,e.to])c.has(t)||(c.add(t),s.push(t));let t=a.get(e.from)??[];t.push(e),a.set(e.from,t),e.event!==void 0&&o.set(`${e.from}::${e.event}`,e)}return{definition:n,states:s,canTransition(e,t){return(a.get(e)??[]).some(e=>e.to===t)},canHandle(e,t){return o.has(`${e}::${t}`)},availableTargets(e){let t=/* @__PURE__ */ new Set,n=[];for(let r of a.get(e)??[])t.has(r.to)||(t.add(r.to),n.push(r.to));return n},availableEvents(e){let t=/* @__PURE__ */ new Set,n=[];for(let r of a.get(e)??[])r.event!==void 0&&!t.has(r.event)&&(t.add(r.event),n.push(r.event));return n},resolveTransition(n,r){let a=o.get(`${n}::${r}`);return a===void 0?e(new i(n,r)):t(a)},isTerminal(e){return n.states?.[e]?.terminal===!0||(a.get(e)??[]).length===0}}}function p(n,i){let c=i.initialState??n.definition.initial;if(!n.states.includes(c))throw new s(c);let l=c,u=null,d=i.context,f=[],p=i.maxHistory??0,m=[];function h(e,t){u=l,l=e.to,e.action?.(d,t);let n={instanceId:i.id,from:u,to:l,event:t,context:d,occurredAt:(/* @__PURE__ */ new Date()).toISOString()};if(p>0)for(f.push(n);f.length>p;)f.shift();for(let e of m)e(n);return n}return{id:i.id,machine:n,send(r){if(n.isTerminal(l))return e(new o(l));let i=n.resolveTransition(l,r);if(i.isFailure)return e(i.error);let s=i.value;return s.guard?.(d,r)===!1?e(new a(s.from,s.to,r)):t(h(s,r))},transitionTo(i){if(n.isTerminal(l))return e(new o(l));let s=n.definition.transitions.filter(e=>e.from===l&&e.to===i);if(s.length===0)return e(new r(l,i));let c=s.find(e=>e.guard?.(d,null)!==!1);return c===void 0?e(new a(l,i,null)):t(h(c,null))},getState(){return l},getContext(){return d},isTerminal(){return n.isTerminal(l)},getSnapshot(){return{id:i.id,state:l,previousState:u,context:d,history:[...f]}},restore(r){if(!n.states.includes(r.state))return e(new s(r.state));for(l=r.state,u=r.previousState,d=r.context,f.length=0,f.push(...r.history);f.length>p;)f.shift();return t(void 0)},subscribe(e){return m.push(e),()=>{let t=m.indexOf(e);t>=0&&m.splice(t,1)}}}}export{c as DefinitionValidationError,a as GuardRejectedError,r as InvalidTransitionError,n as StateMachineError,o as TerminalStateReachedError,i as UnhandledEventError,s as UnknownStateError,f as createMachine,p as createMachineInstance,u as fromAdjacency,l as isStateName,d as validateDefinition};

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@longzai-intelligence-state-machine/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Longzai Intelligence 状态机核心能力包",
+  "keywords": [
+    "fsm",
+    "guard",
+    "longzai-intelligence",
+    "state-machine",
+    "transition-table"
+  ],
+  "license": "UNLICENSED",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "lzi-builder",
+    "build:prod": "NODE_ENV=production bun run build",
+    "prepublishOnly": "bun run build:prod",
+    "typecheck": "lzi-tsgo typecheck tsconfig/app.json && lzi-tsgo typecheck tsconfig/test.json",
+    "typecheck:app": "lzi-tsgo typecheck tsconfig/app.json",
+    "typecheck:test": "lzi-tsgo typecheck tsconfig/test.json",
+    "lint": "oxlint && oxfmt --check",
+    "lint:fix": "oxlint --fix && oxfmt",
+    "test": "lzi-bun-cli test",
+    "test:watch": "lzi-bun-cli test --watch",
+    "test:coverage": "lzi-bun-cli test --coverage",
+    "clean": "lzi-dev-cli clean"
+  },
+  "dependencies": {
+    "@longzai-intelligence-shared-kernel/core": "^0.1.4"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.