aifsmjs 0.5.3 → 0.5.6

package/llms-full.txt

@@ -14,14 +14,16 @@ The short index lives at `llms.txt` (see https://llmstxt.org/).
 # aifsmjs
 
 [![npm version](https://img.shields.io/npm/v/aifsmjs.svg)](https://www.npmjs.com/package/aifsmjs)
-[![CI](https://github.com/yshengliao/aifsmjs/actions/workflows/ci.yml/badge.svg)](https://github.com/yshengliao/aifsmjs/actions/workflows/ci.yml)
+[![CI](https://github.com/islumina/aifsmjs/actions/workflows/ci.yml/badge.svg)](https://github.com/islumina/aifsmjs/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE)
 [![AI Generated](https://img.shields.io/badge/AI_Generated-Claude_Code_Opus_4.7_Max-blueviolet.svg)](https://www.anthropic.com/claude-code)
 [![繁體中文](https://img.shields.io/badge/lang-繁體中文-red.svg)](README_ZHTW.md)
 
 > A small, strict FSM library for any TypeScript/JS app that needs deterministic, replayable state transitions. Lifecycle is a pure `step()` function. Chain-of-Responsibility intuition is reserved for cross-cutting concerns (observe / persist / replay), never for the transition core.
 
-Part of the [ai\*js micro-runtime ecosystem](https://github.com/yshengliao) — see also [aibridgejs](https://github.com/yshengliao/aibridgejs) (cross-context RPC) and [aiecsjs](https://github.com/yshengliao/aiecsjs) (ECS).
+Part of the [ai\*js micro-runtime ecosystem](https://github.com/islumina) — see also [aibridgejs](https://github.com/islumina/aibridgejs) (cross-context RPC) and [aiecsjs](https://github.com/islumina/aiecsjs) (ECS).
+
+> **Status: 0.5.6.** Core FSM, hierarchical sub-machines, guards & effects, scheduler, replay, inspect, and PBT helpers are all live. See [CHANGELOG.md](CHANGELOG.md) for release history.
 
 **Primary audience**: developers building stateful flows — multi-step forms, checkout funnels, auth flows, tutorial sequences, document-status workflows, scene flow in interactive apps, and the same patterns in browser-based games (PixiJS / Svelte 5 / plain Canvas / WebGL). The core is **environment-neutral** (pure function + adapter boundary): browser, Node, Bun, Deno, Flutter WebView, and Web Workers all work. The Roadmap section keeps gaming-specific niceties (tick hook, ECS bridge) as opt-in subpaths, not core surface.
 
@@ -302,6 +304,8 @@ const runtime = createRuntime(def, impl, {
 
 Koa-style `(ctx, next) => void` pipeline. `ctx` is `{ prev, next, event, effects, changed }`, all deep-frozen. **Cannot cancel a transition** — `next()` must be called; the return value carries no meaning.
 
+Two boundaries to respect (both stable for 1.x, detailed in [STABILITY.md](STABILITY.md)): skipping `next()` is **not** enforced and silently drops every later middleware (and the `recorder` / `persist` sinks) for that event; and a synchronous throw from a middleware (e.g. `persist` on non-serialisable context) propagates to the caller but leaves the snapshot **committed yet unannounced** — `notify()` and `on('transition')` are skipped. Do **not** call `runtime.send()` from inside the pipeline: the inner event runs its full pipeline before the outer frame finishes, so the `recorder` log is reordered and `replay()` diverges.
+
 ### `aifsmjs/replay` — Pure event log replay
 
 ```typescript
@@ -506,8 +510,8 @@ Example-first, PBT-augmented. Lesson from jssm: "3000+ tests / 100% coverage" tu
 
 - **Example tests** (vitest): for every src module, write happy path + edge + error-message triplets.
 - **PBT smoke**: each generic property runs 50 iterations as an invariant guard, not as a coverage source.
-- **CI-enforced thresholds**: `@vitest/coverage-v8` is wired to **100% statements / 100% lines / 100% functions / ≥90% branches**. The few defensive invariant-guard branches (e.g. runtime determinism mismatch) carry `/* v8 ignore */` annotations with rationale.
-- **Size budget**: `scripts/check-size.mjs` enforces per-subpath gzip caps in CI — core ≤4.7 KB (raised in 0.3.0 for sub-machine sugar), replay ≤1.8 KB, pbt ≤5.5 KB (raised in 0.3.0 because `pbt` transitively imports `createRuntime`), others ≤1 KB. Exceeding any cap fails the build.
+- **CI-enforced thresholds**: `@vitest/coverage-v8` is wired to **100% lines / 100% functions / ≥95% statements / ≥90% branches**. The few defensive invariant-guard branches (e.g. runtime determinism mismatch) carry `/* v8 ignore */` annotations with rationale.
+- **Size budget**: `scripts/check-size.mjs` enforces per-subpath gzip caps in CI, measured as each entry's transitive closure (entry + shared chunks — the build code-splits so error classes keep cross-subpath identity) — core ≤6.5 KB, pbt ≤8.5 KB (transitively imports `createRuntime`), replay ≤3.3 KB, effects ≤1.7 KB, guards ≤1.5 KB, timer ≤1.2 KB, inspect ≤1 KB. Exceeding any cap fails the build.
 
 ### The 6 built-in generic properties
 
@@ -579,6 +583,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.6] - 2026-06-10
+
+### Fixed
+
+- **Guard combinators route through the async-guard safety net** — `and()` / `or()` / `not()` now pass each resolved guard's return value through the same `isThenable` check as top-level guards, throwing `AsyncGuardError` instead of coercing a pending thenable to `true`/`false`. The 0.2.0 async-guard protection was bypassable through any combinator. (Review wave 2026-06-10, FSM-S-01.)
+- **`reset()` captures the committed snapshot before notifying** (mirroring the 0.2.0 `send()` fix), so a listener that re-enters `send()` during reset can no longer make the `'transition'` payload report a state pair that never occurred. (FSM-B-01.)
+- **Scheduler `pending` registry no longer leaks** on any of its three escape paths: signal-abort cancellation, scheduling on an already-aborted signal, and a custom scheduler that fires synchronously during `after()`. Signal handling is owned by the scheduler layer now; fire/cancel/abort all remove the tracked handle and detach the abort listener. (FSM-R-01.)
+- PBT property #5 `guardsFalseNoTransition` actually asserts `changed === false` (its body was vacuous — it returned `true` unconditionally); the other five generic properties were audited and are non-vacuous. (FSM-B-02.)
+- Hierarchical `sub.initial` is validated as a member of `sub.states` at definition time. (FSM-S-02.)
+- Effect results are detected with `isThenable` instead of `instanceof Promise` at both dispatch sites, so cross-realm / userland PromiseLike values are awaited and error-routed correctly. (FSM-B-03.)
+- `emit()` / `notify()` snapshot their listener sets before iterating (family-canonical), pinning unsubscribe/re-subscribe-during-dispatch semantics. (FAM-S-03.)
+
+### Changed
+
+- **Code splitting enabled (`tsup splitting: true`)** — the published 0.5.x dist inlined a private copy of the shared runtime (including every error class) into each subpath bundle, so an error raised through `aifsmjs/guards` failed `instanceof` checks against the root export. Shared chunks restore cross-subpath class identity; total dist JS shrank 50.7 KB → 31.1 KB. `check:size` now measures each entry's transitive chunk closure, with budgets recalibrated and the README size-budget bullet updated to match.
+- Triplicated child init/wire logic extracted into a single `initChildFor()` helper (behaviour-preserving).
+- Supply-chain and release hardening: CI/publish actions SHA-pinned, npm CLI pinned (`11.16.0`), `permissions: contents: read` on CI, job timeouts, `npm publish --ignore-scripts`, manual dispatch defaults to dry-run, new `verify:docs` banner gate, two-stage typecheck (tests are now type-checked), `llms-full.txt` embeds `STABILITY.md`, and a cross-subpath dist smoke (`verify:dist`).
+
+### Docs
+
+- README coverage claim corrected to the enforced thresholds (95% statements); middleware sync-throw commit/notify boundary and `next()`-skip behaviour documented (with characterisation tests); README status banner added (EN + ZHTW).
+
+## [0.5.5] - 2026-06-08
+
+### Changed
+
+- Project home migrated to the [`islumina`](https://github.com/islumina) GitHub org; the package is now published from there via npm trusted publisher (OIDC + SLSA provenance). Family-wide version alignment at `0.5.5` — no runtime or API changes.
+
 ## [0.5.3] - 2026-06-05
 
 ### Added
@@ -918,6 +950,131 @@ Hierarchical / compound states, parallel state regions, actor invocation
 
 ---
 
+# Stability tiers (`STABILITY.md`)
+
+# 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.
+
+### Sub-machines (stable since 0.4.0)
+
+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
+  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.
+
+#### Design boundaries
+
+- **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 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. 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.
+
+### Middleware, effects & notification ordering (documented boundaries)
+
+These are intentional ordering boundaries of the read-only middleware /
+effect pipeline, not bugs. They are stable for the 1.x line.
+
+- **A synchronous throw from a middleware or effect handler leaves the
+  snapshot committed but unannounced.** Inside `send()` / `reset()` the new
+  snapshot is committed (so `getSnapshot()` already reflects it) *before*
+  `runMiddleware()` and effect dispatch run. If a middleware or effect
+  handler throws synchronously, the throw propagates to the `send()` /
+  `reset()` caller (as documented), but `notify()`, `on('transition')`
+  listeners, and — for a middleware throw — the collected effects are
+  skipped. Observers therefore desynchronise from `getSnapshot()`. The
+  shipped `persist` middleware throws on non-serialisable context, making
+  this reachable without exotic code. Wrap throwing middleware/effects in
+  your own `try/catch` if you need observers to fire regardless. (Contrast:
+  the sub-machine init/dispose failure path *rolls back* instead — see
+  above.) A future **major** may move the commit after the pipeline; the
+  current order is frozen for 1.x.
+- **`next()` must be called by every middleware; skipping it is not
+  enforced.** Calling `next()` twice throws; calling it zero times is
+  silently tolerated and drops every later middleware (and the recorder /
+  persist sinks) for that event — no throw, no warning. The state transition
+  itself is unaffected (the snapshot is committed before the pipeline). Treat
+  `next()` as mandatory.
+- **Re-entrant `send()` from inside middleware reorders recorder logs.**
+  Middleware is documented read-only; a middleware that re-entrantly calls
+  `runtime.send()` runs the inner event's full pipeline (including the
+  recorder push) before the outer frame reaches the recorder. The
+  `recorder` sink — intended to feed `replay()` — then lists `[inner,
+  outer]` for an application order of `[outer, inner]`, so replaying that log
+  diverges. Do not `send()` from within the middleware pipeline.
+
+## 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` (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.
+
+---
+
 <!-- ===== CONTRIBUTING.md ===== -->
 
 # Contributing to aifsmjs
@@ -1044,10 +1201,10 @@ pnpm example:form-wizard      # 04-form-wizard
 
 | # | Example | What it shows | Real-world pattern |
 |---|---|---|---|
-| 01 | [traffic-light](https://github.com/yshengliao/aifsmjs/blob/main/examples/01-traffic-light/index.ts) | Minimal `setup → defineMachine → createRuntime → send` loop with `assign` and a snapshot subscriber. | Cyclic scene flow (loading → menu → playing → result → loading) — or any 3-state cycle. |
-| 02 | [approval-workflow](https://github.com/yshengliao/aifsmjs/blob/main/examples/02-approval-workflow/index.ts) | Multi-candidate guarded transitions (`and([...])`), effects + handlers, `persist` + `recorder` middleware, and `replay()` to reproduce the final snapshot. | Document approval, ticket triage, turn-based games with branching outcomes + post-mortem replay. |
-| 03 | [checkout-funnel](https://github.com/yshengliao/aifsmjs/blob/main/examples/03-checkout-funnel/index.ts) | E-commerce checkout: cart → shipping → payment → review → confirmed. Per-stage validation as guards, payment + analytics as effects, full replay of the funnel. | Plain web app — no canvas, no game loop. Demonstrates that aifsmjs models classic UX funnels. |
-| 04 | [form-wizard](https://github.com/yshengliao/aifsmjs/blob/main/examples/04-form-wizard/index.ts) | Multi-step form wizard with back / next / jump-to-step navigation. Per-step validation, draft persistence via the `persist` middleware. | Account onboarding, settings editor, multi-page survey. |
+| 01 | [traffic-light](https://github.com/islumina/aifsmjs/blob/main/examples/01-traffic-light/index.ts) | Minimal `setup → defineMachine → createRuntime → send` loop with `assign` and a snapshot subscriber. | Cyclic scene flow (loading → menu → playing → result → loading) — or any 3-state cycle. |
+| 02 | [approval-workflow](https://github.com/islumina/aifsmjs/blob/main/examples/02-approval-workflow/index.ts) | Multi-candidate guarded transitions (`and([...])`), effects + handlers, `persist` + `recorder` middleware, and `replay()` to reproduce the final snapshot. | Document approval, ticket triage, turn-based games with branching outcomes + post-mortem replay. |
+| 03 | [checkout-funnel](https://github.com/islumina/aifsmjs/blob/main/examples/03-checkout-funnel/index.ts) | E-commerce checkout: cart → shipping → payment → review → confirmed. Per-stage validation as guards, payment + analytics as effects, full replay of the funnel. | Plain web app — no canvas, no game loop. Demonstrates that aifsmjs models classic UX funnels. |
+| 04 | [form-wizard](https://github.com/islumina/aifsmjs/blob/main/examples/04-form-wizard/index.ts) | Multi-step form wizard with back / next / jump-to-step navigation. Per-step validation, draft persistence via the `persist` middleware. | Account onboarding, settings editor, multi-page survey. |
 
 ## Notes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aifsmjs",
-  "version": "0.5.3",
+  "version": "0.5.6",
   "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",
@@ -20,13 +20,13 @@
   ],
   "author": "yshengliao",
   "license": "MIT",
-  "homepage": "https://github.com/yshengliao/aifsmjs#readme",
+  "homepage": "https://github.com/islumina/aifsmjs#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/yshengliao/aifsmjs.git"
+    "url": "git+https://github.com/islumina/aifsmjs.git"
   },
   "bugs": {
-    "url": "https://github.com/yshengliao/aifsmjs/issues"
+    "url": "https://github.com/islumina/aifsmjs/issues"
   },
   "type": "module",
   "sideEffects": false,
@@ -84,7 +84,9 @@
     "test:watch": "vitest",
     "lint": "biome check src test",
     "format": "biome format --write src test",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "verify:docs": "node scripts/verify-docs.mjs",
+    "verify:dist": "node scripts/check-dist-subpaths.mjs",
     "verify:exports": "node scripts/verify-exports.mjs",
     "check:size": "node scripts/check-size.mjs",
     "build:llms": "node scripts/build-llms-full.mjs",
@@ -94,7 +96,7 @@
     "example:approval": "tsx examples/02-approval-workflow/index.ts",
     "example:checkout-funnel": "tsx examples/03-checkout-funnel/index.ts",
     "example:form-wizard": "tsx examples/04-form-wizard/index.ts",
-    "prepublishOnly": "pnpm typecheck && pnpm lint && pnpm coverage && pnpm build && pnpm verify:exports && pnpm verify:llms && pnpm check:size"
+    "prepublishOnly": "pnpm typecheck && pnpm lint && pnpm verify:docs && pnpm coverage && pnpm build && pnpm verify:dist && pnpm verify:exports && pnpm verify:llms && pnpm check:size"
   },
   "peerDependencies": {
     "fast-check": "^3.20.0 || ^4.0.0"