aifsmjs 0.3.1 → 0.4.1

package/README.md

@@ -107,7 +107,7 @@ The three layers are fully decoupled: take `step()` alone for replay, take `Mach
 | Will do (v1)                                        | Won't do                                          |
 | --------------------------------------------------- | ------------------------------------------------- |
 | Flat states + transitions                           | Parallel state regions                            |
-| Hierarchical sugar via `state.sub` (experimental, since 0.3.0) | Closures embedded in definition (breaks serialize) |
+| Hierarchical sugar via `state.sub` (stable since 0.4.0) | Closures embedded in definition (breaks serialize) |
 | Guards (sync only; inline async throws `InvalidDefinitionError` at `defineMachine`; runtime throws `AsyncGuardError` on thenable return) | Async guards                                      |
 | Actions (assign + enqueue effects)                  | Async API inside an action (use an effect)        |
 | Fire-and-forget effects                             | Actor invocation / spawn                          |
@@ -357,7 +357,7 @@ Non-goals:
 - No async lifecycle hook
 - Inspect middleware cannot alter the transition outcome
 
-### Sub-machine lifecycle (since 0.3.0, experimental)
+### Sub-machine lifecycle (stable since 0.4.0)
 
 When a state declares `sub`, the per-transition ordering is:
 
@@ -497,8 +497,8 @@ Example-first, PBT-augmented. Lesson from jssm: "3000+ tests / 100% coverage" tu
 | ------- | ------------------------------------------------------------------ |
 | v0.1    | core + guards + effects + inspect + replay + pbt (this release)    |
 | v0.2    | Async-guard detection, coverage tuning, llms-full.txt verify gate  |
-| v0.3    | Hierarchical sugar via `state.sub` (experimental, this release)    |
-| v0.4    | `historyState` — remember last active sub-state on re-entry        |
+| v0.3    | Hierarchical sugar via `state.sub` (experimental)                  |
+| v0.4    | Sub-machine API promoted to stable; dependency-reduction cycle     |
 | v0.5    | `aifsmjs-bridge-bitecs` / `aifsmjs-bridge-pixi` (separate sub-packages) |
 | v1.0    | API freeze and stability guarantee                                  |
 
@@ -509,7 +509,7 @@ Example-first, PBT-augmented. Lesson from jssm: "3000+ tests / 100% coverage" tu
 - **Tick / game-loop hook** (out of scope for v1)
 - **ECS / Pixi bridges** (out of scope for v1)
 
-**v0.4 candidate**: `historyState` — remember last active sub-state on
+**Future candidate**: `historyState` — remember last active sub-state on
 re-entry. Workaround today: snapshot via `onTransition` and restore
 manually.
 

package/README_ZHTW.md

@@ -106,7 +106,7 @@ console.log(runtime.getSnapshot().context); // { ticks: 1 }
 | 會做（v1）                                          | 不會做                                            |
 | --------------------------------------------------- | ------------------------------------------------- |
 | Flat states + transitions                           | Parallel state regions                            |
-| 透過 `state.sub` 的階層式 sugar（experimental，since 0.3.0） | Definition 內直接綁 closure（會無法序列化）    |
+| 透過 `state.sub` 的階層式 sugar（stable since 0.4.0） | Definition 內直接綁 closure（會無法序列化）    |
 | Guards（sync only；inline async 在 `defineMachine` 時丟 `InvalidDefinitionError`；runtime 偵測到 thenable 回傳則丟 `AsyncGuardError`） | Async guards                                      |
 | Actions（assign + enqueue effects）                 | 在 action 內呼叫 async API（請放到 effect）        |
 | Fire-and-forget effects                             | Actor invocation / spawn                          |
@@ -356,7 +356,7 @@ sched.cancelAll();
 - async lifecycle hook
 - Inspect middleware 影響 transition 結果
 
-### Sub-machine lifecycle（since 0.3.0，experimental）
+### Sub-machine lifecycle（stable since 0.4.0）
 
 當一個 state 宣告 `sub` 時，每次 transition 的執行順序為：
 
@@ -491,8 +491,8 @@ aifsmjs 在幾個常見議題上做了刻意取捨，跟主流 FSM library 寫
 | ---- | ----------------------------------------------------------------- |
 | v0.1 | core + guards + effects + inspect + replay + pbt（本次發佈）       |
 | v0.2 | Async-guard 偵測、coverage 調整、llms-full.txt verify gate        |
-| v0.3 | 透過 `state.sub` 的階層式 sugar（experimental，本次發佈）          |
-| v0.4 | `historyState` — re-entry 時恢復上一次的 sub-state                 |
+| v0.3 | 透過 `state.sub` 的階層式 sugar（experimental）                    |
+| v0.4 | sub-machine API 升 stable；降依賴 cycle                            |
 | v0.5 | `aifsmjs-bridge-bitecs` / `aifsmjs-bridge-pixi`（獨立 sub-package） |
 | v1.0 | API freeze 與 stability guarantee                                  |
 
@@ -503,7 +503,7 @@ aifsmjs 在幾個常見議題上做了刻意取捨，跟主流 FSM library 寫
 - **Tick / game-loop hook**（v1 不做）
 - **ECS / Pixi bridges**（v1 不做）
 
-**v0.4 候選**：`historyState` — re-entry 時自動恢復上一次的 sub-state。0.3.0 的暫代方案：透過 `onTransition` snapshot sub-runtime 的 value，之後手動還原。
+**未來候選**：`historyState` — re-entry 時自動恢復上一次的 sub-state。0.3.0 的暫代方案：透過 `onTransition` snapshot sub-runtime 的 value，之後手動還原。
 
 ---
 

package/llms-full.txt

@@ -120,7 +120,7 @@ The three layers are fully decoupled: take `step()` alone for replay, take `Mach
 | Will do (v1)                                        | Won't do                                          |
 | --------------------------------------------------- | ------------------------------------------------- |
 | Flat states + transitions                           | Parallel state regions                            |
-| Hierarchical sugar via `state.sub` (experimental, since 0.3.0) | Closures embedded in definition (breaks serialize) |
+| Hierarchical sugar via `state.sub` (stable since 0.4.0) | Closures embedded in definition (breaks serialize) |
 | Guards (sync only; inline async throws `InvalidDefinitionError` at `defineMachine`; runtime throws `AsyncGuardError` on thenable return) | Async guards                                      |
 | Actions (assign + enqueue effects)                  | Async API inside an action (use an effect)        |
 | Fire-and-forget effects                             | Actor invocation / spawn                          |
@@ -370,7 +370,7 @@ Non-goals:
 - No async lifecycle hook
 - Inspect middleware cannot alter the transition outcome
 
-### Sub-machine lifecycle (since 0.3.0, experimental)
+### Sub-machine lifecycle (stable since 0.4.0)
 
 When a state declares `sub`, the per-transition ordering is:
 
@@ -510,8 +510,8 @@ Example-first, PBT-augmented. Lesson from jssm: "3000+ tests / 100% coverage" tu
 | ------- | ------------------------------------------------------------------ |
 | v0.1    | core + guards + effects + inspect + replay + pbt (this release)    |
 | v0.2    | Async-guard detection, coverage tuning, llms-full.txt verify gate  |
-| v0.3    | Hierarchical sugar via `state.sub` (experimental, this release)    |
-| v0.4    | `historyState` — remember last active sub-state on re-entry        |
+| v0.3    | Hierarchical sugar via `state.sub` (experimental)                  |
+| v0.4    | Sub-machine API promoted to stable; dependency-reduction cycle     |
 | v0.5    | `aifsmjs-bridge-bitecs` / `aifsmjs-bridge-pixi` (separate sub-packages) |
 | v1.0    | API freeze and stability guarantee                                  |
 
@@ -522,7 +522,7 @@ Example-first, PBT-augmented. Lesson from jssm: "3000+ tests / 100% coverage" tu
 - **Tick / game-loop hook** (out of scope for v1)
 - **ECS / Pixi bridges** (out of scope for v1)
 
-**v0.4 candidate**: `historyState` — remember last active sub-state on
+**Future candidate**: `historyState` — remember last active sub-state on
 re-entry. Workaround today: snapshot via `onTransition` and restore
 manually.
 
@@ -543,6 +543,47 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.1] — 2026-05-29
+
+### Changed
+
+- **`STABILITY.md` is now repo-only** — removed from the npm `files`
+  allowlist, aligning with the majority of the ai*js family (5 of 7
+  packages already ship the stability contract repo-only). The file stays
+  in the repository and remains visible on GitHub and the rendered npm
+  package page; it is simply no longer bundled inside the published
+  tarball. Packaging consistency patch: **no runtime API change, no
+  signature change**; the built bundles (`dist/`) are byte-identical to
+  0.4.0 (core gzip 4,387 B).
+
+## [0.4.0] — 2026-05-29
+
+### Changed
+
+- **Sub-machine API promoted experimental → stable.** The hierarchical
+  sub-machine surface shipped in 0.3.0 — `StateDef.sub`, `StateDef.subImpl`,
+  `Runtime.subRuntime()`, `SubMachineError`, and the `SubMachineDef` type
+  alias — is now stable. Signatures and runtime semantics, including the
+  init-failure quarantine behaviour, are frozen for the 1.x line; the
+  boundaries documented in `STABILITY.md` are intentional design trade-offs,
+  not instability. **No signature changed from 0.3.x.**
+
+### Dependency reduction
+
+- Part of the ai*js v0.4.0 dependency-reduction cycle. `fast-check` remains
+  an **optional** peer dependency isolated to the `aifsmjs/pbt` subpath. A
+  fresh build confirms the core entry and the five non-pbt subpaths
+  (`guards` / `effects` / `inspect` / `replay` / `timer`) are tree-shake-free
+  of `fast-check` (only `dist/pbt/index.js` references it). `pnpm audit`
+  reports zero advisories. No `devDependency` changes.
+
+### Compatibility
+
+This release adds **no runtime API** and changes **no signature**. The core
+bundle is byte-identical to 0.3.1 (gzip 4,387 B); existing 0.3.x consumer
+code is unaffected. The only substantive change is the documented stability
+tier of the sub-machine API.
+
 ## [0.3.1] — 2026-05-29
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aifsmjs",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Small, strict FSM library for deterministic, replayable state machines in any TypeScript/JS app — multi-step forms, checkout funnels, auth flows, tutorials, scene flow. Pure step() lifecycle, opt-in effects, inspect, replay, and a fast-check property-based testing adapter. Browser / Node / Bun / Deno / WebView / Worker friendly.",
   "keywords": [
     "fsm",
@@ -74,7 +74,6 @@
     "dist",
     "README.md",
     "README_ZHTW.md",
-    "STABILITY.md",
     "LICENSE",
     "llms.txt",
     "llms-full.txt"

package/STABILITY.md

@@ -1,77 +0,0 @@
-# Stability
-
-This document defines the stability tier of every public symbol exported by
-`aifsmjs`. Tiers govern what breaks may occur in future minor / major bumps.
-
-## Stable (since 0.1.0)
-
-Fully stable. Breaking changes only at a major version bump (1.0+).
-
-- `createMachine`, `defineMachine`, `setup`, `createRuntime`, `initialSnapshot`
-- `step`, `resolveTransitions`, `evalGuard`, `resolveGuard`, `isAsyncGuardFn`
-- `assign`, `mergeContext`, `createSnapshot`, `deepFreeze`, `freezeSnapshot`
-- `Runtime.send`, `Runtime.reset`, `Runtime.can`, `Runtime.getSnapshot`,
-  `Runtime.snapshot`, `Runtime.subscribe`, `Runtime.on`, `Runtime.dispose`,
-  `Runtime.signal`, `Runtime.disposed`
-- All error classes from 0.1.0–0.2.1: `RuntimeDisposedError`,
-  `InvalidDefinitionError`, `UnknownActionError`, `UnknownGuardError`,
-  `AsyncGuardError`
-- Types: `MachineDef`, `StateDef` (fields `on`, `entry`, `exit`, `final`),
-  `TransitionDef`, `Snapshot`, `Implementations`, `Guard`, `Action`,
-  `EffectHandler`, `Effect`, `Enqueuer`, `Middleware`, `MiddlewareContext`,
-  `RuntimeOptions`, `StepResult`, `ResetEvent`, `RESET_EVENT_TYPE`,
-  `RuntimeTransitionEvent`, `RuntimeErrorEvent`, `RuntimeEventMap`
-- All subpath exports: `aifsmjs/guards`, `aifsmjs/effects`, `aifsmjs/inspect`,
-  `aifsmjs/replay`, `aifsmjs/pbt`, `aifsmjs/timer`
-- `Runtime.onTransition` (added in 0.3.0) — pure sugar over the stable
-  `on('transition', ...)` API; listed under Stable because the underlying
-  contract is unchanged.
-
-## Experimental (since 0.3.0)
-
-Shape and behaviour may change in any minor bump until 1.0. Production use
-is OK; expect a one-line patch on minor upgrades.
-
-- `StateDef.sub` (optional `SubMachineDef`) — when present, a child runtime
-  is lazily initialised on entry and disposed on exit. Per-transition
-  ordering is parent `step()` (exit / actions / entry) → child dispose →
-  child init → snapshot commit.
-- `StateDef.subImpl` (optional `Implementations`) — paired with `sub`;
-  passed to the child `createRuntime`. Defaults to `{}`.
-- `Runtime.subRuntime()` — returns the live child handle, or `undefined`.
-  Returned generic is `Runtime<unknown, { type: string }, string>`; caller
-  narrows via cast if necessary.
-- `SubMachineError` — thrown by `send()` / `reset()` on child init/dispose
-  failure. Fields: `parentState`, `phase ("init" | "dispose")`, `cause`.
-- `SubMachineDef` type alias.
-
-### Known boundaries (0.3.0)
-
-- **Replay / PBT do not see child state.** `replay()` and
-  `commandsFromMachine` only inspect parent snapshots. If your business
-  logic lives in the parent layer, replay is still deterministic.
-- **`subRuntime()` may return a disposed handle** if an external caller
-  disposed it. The handle is not reinitialised until the parent leaves and
-  re-enters the sub-bearing state. Detect with `child.disposed`.
-- **Self-targeting external (`A → A`) is treated as full exit/entry**:
-  child is disposed and reinitialised. The 0.3.0 dispatcher re-resolves
-  guards to identify the chosen transition before deciding external vs
-  internal, so guarded internal transitions on the same event no longer
-  trigger a reinit.
-- **Init-failure mid-transition leaves the parent without a live child.**
-  If `applySubLifecycle` successfully disposes the old child and then the
-  new child's `createRuntime` throws, the parent's snapshot is rolled back
-  to `prev` but `subRuntime()` returns `undefined`. Callers catching
-  `SubMachineError(phase: "init")` should treat the runtime as quarantined
-  — call `runtime.dispose()` (idempotent) or `runtime.reset()` (which
-  attempts re-init) before sending further events. A future major may
-  switch to a two-phase "init before dispose" commit strategy; for 0.3.x
-  this remains opt-in only when child failures are expected.
-
-## Draft (planned, not implemented in 0.3.0)
-
-API sketched, not shipped. May change before release.
-
-- `historyState` (v0.4 candidate) — opt-in pseudo-state that remembers
-  the last active sub-state on re-entry. Workaround in 0.3.0: snapshot
-  the sub-runtime's value on exit via `onTransition`, restore manually.