aifsmjs 0.3.1 → 0.4.0

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/STABILITY.md

@@ -27,10 +27,13 @@ Fully stable. Breaking changes only at a major version bump (1.0+).
   `on('transition', ...)` API; listed under Stable because the underlying
   contract is unchanged.
 
-## Experimental (since 0.3.0)
+### Sub-machines (stable since 0.4.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.
+The hierarchical sub-machine surface shipped experimentally in 0.3.0 is
+stable as of 0.4.0. Signatures and runtime semantics — including the
+init-failure quarantine behaviour described below — are frozen for the 1.x
+line. The boundaries listed are intentional design trade-offs, not bugs or
+pending instability.
 
 - `StateDef.sub` (optional `SubMachineDef`) — when present, a child runtime
   is lazily initialised on entry and disposed on exit. Per-transition
@@ -45,7 +48,7 @@ is OK; expect a one-line patch on minor upgrades.
   failure. Fields: `parentState`, `phase ("init" | "dispose")`, `cause`.
 - `SubMachineDef` type alias.
 
-### Known boundaries (0.3.0)
+#### Design boundaries
 
 - **Replay / PBT do not see child state.** `replay()` and
   `commandsFromMachine` only inspect parent snapshots. If your business
@@ -54,24 +57,31 @@ is OK; expect a one-line patch on minor upgrades.
   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.
+  child is disposed and reinitialised. The dispatcher re-resolves guards to
+  identify the chosen transition before deciding external vs internal, so
+  guarded internal transitions on the same event do not 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.
+  attempts re-init) before sending further events. This quarantine
+  behaviour is part of the stable contract; a future **major** version may
+  switch to a two-phase "init before dispose" commit strategy (a breaking
+  change reserved for 1.0+), but the current semantics are frozen for the
+  1.x line.
 
-## Draft (planned, not implemented in 0.3.0)
+## Experimental
+
+No experimental APIs as of 0.4.0. The 0.3.0 sub-machine surface graduated to
+Stable in 0.4.0 — see "Sub-machines" above.
+
+## Draft (planned, not implemented)
 
 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.
+- `historyState` (candidate for a future minor) — 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.

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,34 @@ 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.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.0",
   "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",