jssm 5.162.9 → 5.162.11

package/jssm.es5.d.cts

@@ -74,6 +74,27 @@ type JssmDefaultSize = {
     width?: number;
     height?: number;
 };
+/**
+ *  A parsed semantic-version breakdown, as produced by the FSL parser for
+ *  version-valued directives (`machine_version`, `fsl_version`).  `major`,
+ *  `minor`, and `patch` are the three numeric components; `full` preserves
+ *  the exact source text of the version.  `loc` is present only when the
+ *  source was parsed with `{ locations: true }`.
+ *
+ *  ```typescript
+ *  const m = sm`machine_version: 1.2.3; a -> b;`;
+ *  m.machine_version();  // { major: 1, minor: 2, patch: 3, full: '1.2.3' }
+ *  ```
+ *  @see Machine.machine_version
+ *  @see Machine.fsl_version
+ */
+type JssmParsedSemver = {
+    major: number;
+    minor: number;
+    patch: number;
+    full: string;
+    loc?: FslSourceLocation;
+};
 /**
  *  Runtime-iterable list of valid `flow` directions for FSL diagrams.
  *  Use this when you need to enumerate directions; for the type itself
@@ -564,10 +585,10 @@ type JssmGenericConfig<StateType, DataType> = {
     machine_language?: string;
     machine_license?: string;
     machine_name?: string;
-    machine_version?: string;
+    machine_version?: JssmParsedSemver;
     npm_name?: string;
     default_size?: JssmDefaultSize;
-    fsl_version?: string;
+    fsl_version?: JssmParsedSemver;
     auto_api?: boolean | string;
     instance_name?: string | undefined;
     default_state_config?: JssmStateStyleKeyList;
@@ -2009,10 +2030,10 @@ declare class Machine<mDT> {
     _machine_language?: string;
     _machine_license?: string;
     _machine_name?: string;
-    _machine_version?: string;
+    _machine_version?: JssmParsedSemver;
     _npm_name?: string;
     _default_size?: JssmDefaultSize;
-    _fsl_version?: string;
+    _fsl_version?: JssmParsedSemver;
     _raw_state_declaration?: Array<object>;
     _state_declarations: Map<StateType, JssmStateDeclaration>;
     _data?: mDT;
@@ -2635,10 +2656,18 @@ declare class Machine<mDT> {
      */
     default_size(): JssmDefaultSize | undefined;
     /**
-     * Get the machine's version string.  Set via the FSL `machine_version` directive.
-     *  @returns The version string.
+     * Get the machine's declared version, parsed.  Set via the FSL
+     *  `machine_version` directive, which takes a semver triple; the parser
+     *  breaks it into numeric `major`/`minor`/`patch` fields and keeps the
+     *  exact source text in `full`.  Returns `undefined` when the directive
+     *  was not given.
+     *  @returns The parsed {@link JssmParsedSemver}, or `undefined` if unset.
+     *  @example
+     *    const m = sm`machine_version: 1.2.3; a -> b;`;
+     *    m.machine_version();  // => { major: 1, minor: 2, patch: 3, full: '1.2.3' }
+     *  @see fsl_version
      */
-    machine_version(): string;
+    machine_version(): JssmParsedSemver | undefined;
     /**
      * Get the raw state declaration objects as parsed from the FSL source.
      *  @returns An array of raw state declaration objects.
@@ -2656,10 +2685,18 @@ declare class Machine<mDT> {
      */
     state_declarations(): Map<StateType, JssmStateDeclaration>;
     /**
-     * Get the FSL language version this machine was compiled under.
-     *  @returns The FSL version string.
+     * Get the FSL language version this machine declares, parsed.  Set via
+     *  the FSL `fsl_version` directive, which takes a semver triple; the
+     *  parser breaks it into numeric `major`/`minor`/`patch` fields and keeps
+     *  the exact source text in `full`.  Returns `undefined` when the
+     *  directive was not given.
+     *  @returns The parsed {@link JssmParsedSemver}, or `undefined` if unset.
+     *  @example
+     *    const m = sm`fsl_version: 1.0.0; a -> b;`;
+     *    m.fsl_version();  // => { major: 1, minor: 0, patch: 0, full: '1.0.0' }
+     *  @see machine_version
      */
-    fsl_version(): string;
+    fsl_version(): JssmParsedSemver | undefined;
     /**
      * Get the complete internal state of the machine as a serializable
      *  structure.  Includes actions, edges, edge map, named transitions,
@@ -2862,7 +2899,19 @@ declare class Machine<mDT> {
     get themes(): FslTheme | FslTheme[];
     /**
      * Set the active theme(s).  Accepts a single theme name or an array.
+     *  Also drops every memoized static state config, so styles resolved
+     *  before the change re-resolve under the new theme stack.
+     *
+     *  ```typescript
+     *  const m = sm`a -> b;`;
+     *  m.style_for('b');                 // resolved under the default theme
+     *  m.themes = 'ocean';
+     *  m.style_for('b').backgroundColor; // 'cadetblue1' — ocean, not a stale default
+     *  ```
+     *
      *  @param to - A theme name or array of theme names to apply.
+     *
+     *  @see resolve_state_config
      */
     set themes(to: FslTheme | FslTheme[]);
     /**
@@ -2972,10 +3021,34 @@ declare class Machine<mDT> {
      *  @throws {JssmError} If the state does not exist.
      */
     probable_exits_for(whichState: StateType): Array<JssmTransition<StateType, mDT>>;
+    /**
+     * Guard for the random-selection paths ({@link Machine.probabilistic_transition},
+     *  {@link Machine.stochastic_runs}): rejects a candidate pool whose total
+     *  selectable weight is zero, because weighted selection over an all-zero
+     *  pool has no meaningful answer (StoneCypher/fsl#1248).  Undeclared
+     *  probabilities count as weight 1, matching {@link weighted_rand_select}.
+     *  An empty pool is not this guard's concern (terminality is handled by the
+     *  callers) and passes through untouched.
+     *
+     *  ```typescript
+     *  const m = sm`a 0% -> b; a 0% -> c;`;
+     *  m.probabilistic_transition();  // throws JssmError — every exit is 0%
+     *  ```
+     *  @param whichState - The state the pool exits from, named in the error.
+     *  @param exits - The candidate pool, as built by {@link Machine.probable_exits_for}.
+     *  @throws {JssmError} If the pool is non-empty and every candidate edge
+     *  has probability 0 — including the case where explicit `0%` edges
+     *  excluded their unweighted sibling edges from the candidate pool.
+     *  @see probable_exits_for
+     */
+    private _assert_selectable_exit_pool;
     /**
      * Take a single random transition from the current state, weighted by
      *  edge probabilities.
      *  @returns `true` if a transition was taken, `false` otherwise.
+     *  @throws {JssmError} If the candidate exit pool is non-empty but its
+     *  total weight is zero — every candidate declares `0%` — per
+     *  StoneCypher/fsl#1248.
      */
     probabilistic_transition(): boolean;
     /**
@@ -2983,6 +3056,8 @@ declare class Machine<mDT> {
      *  of states visited (before each transition).
      *  @param n - Number of steps to walk.
      *  @returns An array of state names visited during the walk.
+     *  @throws {JssmError} If a visited state's candidate exit pool is
+     *  non-empty but all-zero-weight (StoneCypher/fsl#1248).
      */
     probabilistic_walk(n: number): Array<StateType>;
     /**
@@ -2990,6 +3065,8 @@ declare class Machine<mDT> {
      *  each state was visited.
      *  @param n - Number of steps to walk.
      *  @returns A `Map` from state name to visit count.
+     *  @throws {JssmError} If a visited state's candidate exit pool is
+     *  non-empty but all-zero-weight (StoneCypher/fsl#1248).
      */
     probabilistic_histo_walk(n: number): Map<StateType, number>;
     /**
@@ -3009,6 +3086,9 @@ declare class Machine<mDT> {
      *    the derived arrays — RNG draw order is untouched, so seeded walks
      *    reproduce exactly.
      *  @returns The {@link JssmStochasticRun} for this walk.
+     *  @throws {JssmError} If a visited state's candidate exit pool is
+     *  non-empty but all-zero-weight — see
+     *  {@link Machine._assert_selectable_exit_pool} (StoneCypher/fsl#1248).
      */
     private _stochastic_one_walk;
     /**
@@ -4175,8 +4255,12 @@ declare class Machine<mDT> {
      *  For any state OTHER than the current one, this returns the memoized static
      *  resolution (tiers 1–5; see `_compose_state_config`) — theme →
      *  `default_state_config` → per-kind defaults → depth-ordered group metadata →
-     *  per-state config.  The cache is keyed by state and never invalidated, since
-     *  those tiers do not depend on which state is current.
+     *  per-state config.  The cache is keyed by state; those tiers do not depend
+     *  on which state is current, so it survives transitions, but the mutable
+     *  cascade inputs each clear it when they change — hook registration and
+     *  removal ({@link Machine.set_hook}, {@link Machine.remove_hook}; the
+     *  hooked layer) and theme assignment (the `themes` setter; tier 1 and the
+     *  per-kind theme layers).
      *
      *  For the machine's CURRENTLY-occupied state the result is recomputed each
      *  call (never cached) and additionally carries the dynamic `active_state`

package/jssm.es6.d.ts

@@ -74,6 +74,27 @@ type JssmDefaultSize = {
     width?: number;
     height?: number;
 };
+/**
+ *  A parsed semantic-version breakdown, as produced by the FSL parser for
+ *  version-valued directives (`machine_version`, `fsl_version`).  `major`,
+ *  `minor`, and `patch` are the three numeric components; `full` preserves
+ *  the exact source text of the version.  `loc` is present only when the
+ *  source was parsed with `{ locations: true }`.
+ *
+ *  ```typescript
+ *  const m = sm`machine_version: 1.2.3; a -> b;`;
+ *  m.machine_version();  // { major: 1, minor: 2, patch: 3, full: '1.2.3' }
+ *  ```
+ *  @see Machine.machine_version
+ *  @see Machine.fsl_version
+ */
+type JssmParsedSemver = {
+    major: number;
+    minor: number;
+    patch: number;
+    full: string;
+    loc?: FslSourceLocation;
+};
 /**
  *  Runtime-iterable list of valid `flow` directions for FSL diagrams.
  *  Use this when you need to enumerate directions; for the type itself
@@ -564,10 +585,10 @@ type JssmGenericConfig<StateType, DataType> = {
     machine_language?: string;
     machine_license?: string;
     machine_name?: string;
-    machine_version?: string;
+    machine_version?: JssmParsedSemver;
     npm_name?: string;
     default_size?: JssmDefaultSize;
-    fsl_version?: string;
+    fsl_version?: JssmParsedSemver;
     auto_api?: boolean | string;
     instance_name?: string | undefined;
     default_state_config?: JssmStateStyleKeyList;
@@ -2009,10 +2030,10 @@ declare class Machine<mDT> {
     _machine_language?: string;
     _machine_license?: string;
     _machine_name?: string;
-    _machine_version?: string;
+    _machine_version?: JssmParsedSemver;
     _npm_name?: string;
     _default_size?: JssmDefaultSize;
-    _fsl_version?: string;
+    _fsl_version?: JssmParsedSemver;
     _raw_state_declaration?: Array<object>;
     _state_declarations: Map<StateType, JssmStateDeclaration>;
     _data?: mDT;
@@ -2635,10 +2656,18 @@ declare class Machine<mDT> {
      */
     default_size(): JssmDefaultSize | undefined;
     /**
-     * Get the machine's version string.  Set via the FSL `machine_version` directive.
-     *  @returns The version string.
+     * Get the machine's declared version, parsed.  Set via the FSL
+     *  `machine_version` directive, which takes a semver triple; the parser
+     *  breaks it into numeric `major`/`minor`/`patch` fields and keeps the
+     *  exact source text in `full`.  Returns `undefined` when the directive
+     *  was not given.
+     *  @returns The parsed {@link JssmParsedSemver}, or `undefined` if unset.
+     *  @example
+     *    const m = sm`machine_version: 1.2.3; a -> b;`;
+     *    m.machine_version();  // => { major: 1, minor: 2, patch: 3, full: '1.2.3' }
+     *  @see fsl_version
      */
-    machine_version(): string;
+    machine_version(): JssmParsedSemver | undefined;
     /**
      * Get the raw state declaration objects as parsed from the FSL source.
      *  @returns An array of raw state declaration objects.
@@ -2656,10 +2685,18 @@ declare class Machine<mDT> {
      */
     state_declarations(): Map<StateType, JssmStateDeclaration>;
     /**
-     * Get the FSL language version this machine was compiled under.
-     *  @returns The FSL version string.
+     * Get the FSL language version this machine declares, parsed.  Set via
+     *  the FSL `fsl_version` directive, which takes a semver triple; the
+     *  parser breaks it into numeric `major`/`minor`/`patch` fields and keeps
+     *  the exact source text in `full`.  Returns `undefined` when the
+     *  directive was not given.
+     *  @returns The parsed {@link JssmParsedSemver}, or `undefined` if unset.
+     *  @example
+     *    const m = sm`fsl_version: 1.0.0; a -> b;`;
+     *    m.fsl_version();  // => { major: 1, minor: 0, patch: 0, full: '1.0.0' }
+     *  @see machine_version
      */
-    fsl_version(): string;
+    fsl_version(): JssmParsedSemver | undefined;
     /**
      * Get the complete internal state of the machine as a serializable
      *  structure.  Includes actions, edges, edge map, named transitions,
@@ -2862,7 +2899,19 @@ declare class Machine<mDT> {
     get themes(): FslTheme | FslTheme[];
     /**
      * Set the active theme(s).  Accepts a single theme name or an array.
+     *  Also drops every memoized static state config, so styles resolved
+     *  before the change re-resolve under the new theme stack.
+     *
+     *  ```typescript
+     *  const m = sm`a -> b;`;
+     *  m.style_for('b');                 // resolved under the default theme
+     *  m.themes = 'ocean';
+     *  m.style_for('b').backgroundColor; // 'cadetblue1' — ocean, not a stale default
+     *  ```
+     *
      *  @param to - A theme name or array of theme names to apply.
+     *
+     *  @see resolve_state_config
      */
     set themes(to: FslTheme | FslTheme[]);
     /**
@@ -2972,10 +3021,34 @@ declare class Machine<mDT> {
      *  @throws {JssmError} If the state does not exist.
      */
     probable_exits_for(whichState: StateType): Array<JssmTransition<StateType, mDT>>;
+    /**
+     * Guard for the random-selection paths ({@link Machine.probabilistic_transition},
+     *  {@link Machine.stochastic_runs}): rejects a candidate pool whose total
+     *  selectable weight is zero, because weighted selection over an all-zero
+     *  pool has no meaningful answer (StoneCypher/fsl#1248).  Undeclared
+     *  probabilities count as weight 1, matching {@link weighted_rand_select}.
+     *  An empty pool is not this guard's concern (terminality is handled by the
+     *  callers) and passes through untouched.
+     *
+     *  ```typescript
+     *  const m = sm`a 0% -> b; a 0% -> c;`;
+     *  m.probabilistic_transition();  // throws JssmError — every exit is 0%
+     *  ```
+     *  @param whichState - The state the pool exits from, named in the error.
+     *  @param exits - The candidate pool, as built by {@link Machine.probable_exits_for}.
+     *  @throws {JssmError} If the pool is non-empty and every candidate edge
+     *  has probability 0 — including the case where explicit `0%` edges
+     *  excluded their unweighted sibling edges from the candidate pool.
+     *  @see probable_exits_for
+     */
+    private _assert_selectable_exit_pool;
     /**
      * Take a single random transition from the current state, weighted by
      *  edge probabilities.
      *  @returns `true` if a transition was taken, `false` otherwise.
+     *  @throws {JssmError} If the candidate exit pool is non-empty but its
+     *  total weight is zero — every candidate declares `0%` — per
+     *  StoneCypher/fsl#1248.
      */
     probabilistic_transition(): boolean;
     /**
@@ -2983,6 +3056,8 @@ declare class Machine<mDT> {
      *  of states visited (before each transition).
      *  @param n - Number of steps to walk.
      *  @returns An array of state names visited during the walk.
+     *  @throws {JssmError} If a visited state's candidate exit pool is
+     *  non-empty but all-zero-weight (StoneCypher/fsl#1248).
      */
     probabilistic_walk(n: number): Array<StateType>;
     /**
@@ -2990,6 +3065,8 @@ declare class Machine<mDT> {
      *  each state was visited.
      *  @param n - Number of steps to walk.
      *  @returns A `Map` from state name to visit count.
+     *  @throws {JssmError} If a visited state's candidate exit pool is
+     *  non-empty but all-zero-weight (StoneCypher/fsl#1248).
      */
     probabilistic_histo_walk(n: number): Map<StateType, number>;
     /**
@@ -3009,6 +3086,9 @@ declare class Machine<mDT> {
      *    the derived arrays — RNG draw order is untouched, so seeded walks
      *    reproduce exactly.
      *  @returns The {@link JssmStochasticRun} for this walk.
+     *  @throws {JssmError} If a visited state's candidate exit pool is
+     *  non-empty but all-zero-weight — see
+     *  {@link Machine._assert_selectable_exit_pool} (StoneCypher/fsl#1248).
      */
     private _stochastic_one_walk;
     /**
@@ -4175,8 +4255,12 @@ declare class Machine<mDT> {
      *  For any state OTHER than the current one, this returns the memoized static
      *  resolution (tiers 1–5; see `_compose_state_config`) — theme →
      *  `default_state_config` → per-kind defaults → depth-ordered group metadata →
-     *  per-state config.  The cache is keyed by state and never invalidated, since
-     *  those tiers do not depend on which state is current.
+     *  per-state config.  The cache is keyed by state; those tiers do not depend
+     *  on which state is current, so it survives transitions, but the mutable
+     *  cascade inputs each clear it when they change — hook registration and
+     *  removal ({@link Machine.set_hook}, {@link Machine.remove_hook}; the
+     *  hooked layer) and theme assignment (the `themes` setter; tier 1 and the
+     *  per-kind theme layers).
      *
      *  For the machine's CURRENTLY-occupied state the result is recomputed each
      *  call (never cached) and additionally carries the dynamic `active_state`

package/jssm.fence.d.ts

@@ -210,6 +210,27 @@ type JssmDefaultSize = {
     width?: number;
     height?: number;
 };
+/**
+ *  A parsed semantic-version breakdown, as produced by the FSL parser for
+ *  version-valued directives (`machine_version`, `fsl_version`).  `major`,
+ *  `minor`, and `patch` are the three numeric components; `full` preserves
+ *  the exact source text of the version.  `loc` is present only when the
+ *  source was parsed with `{ locations: true }`.
+ *
+ *  ```typescript
+ *  const m = sm`machine_version: 1.2.3; a -> b;`;
+ *  m.machine_version();  // { major: 1, minor: 2, patch: 3, full: '1.2.3' }
+ *  ```
+ *  @see Machine.machine_version
+ *  @see Machine.fsl_version
+ */
+type JssmParsedSemver = {
+    major: number;
+    minor: number;
+    patch: number;
+    full: string;
+    loc?: FslSourceLocation;
+};
 /**
  *  Runtime-iterable list of valid `flow` directions for FSL diagrams.
  *  Use this when you need to enumerate directions; for the type itself
@@ -700,10 +721,10 @@ type JssmGenericConfig<StateType, DataType> = {
     machine_language?: string;
     machine_license?: string;
     machine_name?: string;
-    machine_version?: string;
+    machine_version?: JssmParsedSemver;
     npm_name?: string;
     default_size?: JssmDefaultSize;
-    fsl_version?: string;
+    fsl_version?: JssmParsedSemver;
     auto_api?: boolean | string;
     instance_name?: string | undefined;
     default_state_config?: JssmStateStyleKeyList;
@@ -1352,10 +1373,10 @@ declare class Machine<mDT> {
     _machine_language?: string;
     _machine_license?: string;
     _machine_name?: string;
-    _machine_version?: string;
+    _machine_version?: JssmParsedSemver;
     _npm_name?: string;
     _default_size?: JssmDefaultSize;
-    _fsl_version?: string;
+    _fsl_version?: JssmParsedSemver;
     _raw_state_declaration?: Array<object>;
     _state_declarations: Map<StateType, JssmStateDeclaration>;
     _data?: mDT;
@@ -1978,10 +1999,18 @@ declare class Machine<mDT> {
      */
     default_size(): JssmDefaultSize | undefined;
     /**
-     * Get the machine's version string.  Set via the FSL `machine_version` directive.
-     *  @returns The version string.
+     * Get the machine's declared version, parsed.  Set via the FSL
+     *  `machine_version` directive, which takes a semver triple; the parser
+     *  breaks it into numeric `major`/`minor`/`patch` fields and keeps the
+     *  exact source text in `full`.  Returns `undefined` when the directive
+     *  was not given.
+     *  @returns The parsed {@link JssmParsedSemver}, or `undefined` if unset.
+     *  @example
+     *    const m = sm`machine_version: 1.2.3; a -> b;`;
+     *    m.machine_version();  // => { major: 1, minor: 2, patch: 3, full: '1.2.3' }
+     *  @see fsl_version
      */
-    machine_version(): string;
+    machine_version(): JssmParsedSemver | undefined;
     /**
      * Get the raw state declaration objects as parsed from the FSL source.
      *  @returns An array of raw state declaration objects.
@@ -1999,10 +2028,18 @@ declare class Machine<mDT> {
      */
     state_declarations(): Map<StateType, JssmStateDeclaration>;
     /**
-     * Get the FSL language version this machine was compiled under.
-     *  @returns The FSL version string.
+     * Get the FSL language version this machine declares, parsed.  Set via
+     *  the FSL `fsl_version` directive, which takes a semver triple; the
+     *  parser breaks it into numeric `major`/`minor`/`patch` fields and keeps
+     *  the exact source text in `full`.  Returns `undefined` when the
+     *  directive was not given.
+     *  @returns The parsed {@link JssmParsedSemver}, or `undefined` if unset.
+     *  @example
+     *    const m = sm`fsl_version: 1.0.0; a -> b;`;
+     *    m.fsl_version();  // => { major: 1, minor: 0, patch: 0, full: '1.0.0' }
+     *  @see machine_version
      */
-    fsl_version(): string;
+    fsl_version(): JssmParsedSemver | undefined;
     /**
      * Get the complete internal state of the machine as a serializable
      *  structure.  Includes actions, edges, edge map, named transitions,
@@ -2205,7 +2242,19 @@ declare class Machine<mDT> {
     get themes(): FslTheme | FslTheme[];
     /**
      * Set the active theme(s).  Accepts a single theme name or an array.
+     *  Also drops every memoized static state config, so styles resolved
+     *  before the change re-resolve under the new theme stack.
+     *
+     *  ```typescript
+     *  const m = sm`a -> b;`;
+     *  m.style_for('b');                 // resolved under the default theme
+     *  m.themes = 'ocean';
+     *  m.style_for('b').backgroundColor; // 'cadetblue1' — ocean, not a stale default
+     *  ```
+     *
      *  @param to - A theme name or array of theme names to apply.
+     *
+     *  @see resolve_state_config
      */
     set themes(to: FslTheme | FslTheme[]);
     /**
@@ -2315,10 +2364,34 @@ declare class Machine<mDT> {
      *  @throws {JssmError} If the state does not exist.
      */
     probable_exits_for(whichState: StateType): Array<JssmTransition<StateType, mDT>>;
+    /**
+     * Guard for the random-selection paths ({@link Machine.probabilistic_transition},
+     *  {@link Machine.stochastic_runs}): rejects a candidate pool whose total
+     *  selectable weight is zero, because weighted selection over an all-zero
+     *  pool has no meaningful answer (StoneCypher/fsl#1248).  Undeclared
+     *  probabilities count as weight 1, matching {@link weighted_rand_select}.
+     *  An empty pool is not this guard's concern (terminality is handled by the
+     *  callers) and passes through untouched.
+     *
+     *  ```typescript
+     *  const m = sm`a 0% -> b; a 0% -> c;`;
+     *  m.probabilistic_transition();  // throws JssmError — every exit is 0%
+     *  ```
+     *  @param whichState - The state the pool exits from, named in the error.
+     *  @param exits - The candidate pool, as built by {@link Machine.probable_exits_for}.
+     *  @throws {JssmError} If the pool is non-empty and every candidate edge
+     *  has probability 0 — including the case where explicit `0%` edges
+     *  excluded their unweighted sibling edges from the candidate pool.
+     *  @see probable_exits_for
+     */
+    private _assert_selectable_exit_pool;
     /**
      * Take a single random transition from the current state, weighted by
      *  edge probabilities.
      *  @returns `true` if a transition was taken, `false` otherwise.
+     *  @throws {JssmError} If the candidate exit pool is non-empty but its
+     *  total weight is zero — every candidate declares `0%` — per
+     *  StoneCypher/fsl#1248.
      */
     probabilistic_transition(): boolean;
     /**
@@ -2326,6 +2399,8 @@ declare class Machine<mDT> {
      *  of states visited (before each transition).
      *  @param n - Number of steps to walk.
      *  @returns An array of state names visited during the walk.
+     *  @throws {JssmError} If a visited state's candidate exit pool is
+     *  non-empty but all-zero-weight (StoneCypher/fsl#1248).
      */
     probabilistic_walk(n: number): Array<StateType>;
     /**
@@ -2333,6 +2408,8 @@ declare class Machine<mDT> {
      *  each state was visited.
      *  @param n - Number of steps to walk.
      *  @returns A `Map` from state name to visit count.
+     *  @throws {JssmError} If a visited state's candidate exit pool is
+     *  non-empty but all-zero-weight (StoneCypher/fsl#1248).
      */
     probabilistic_histo_walk(n: number): Map<StateType, number>;
     /**
@@ -2352,6 +2429,9 @@ declare class Machine<mDT> {
      *    the derived arrays — RNG draw order is untouched, so seeded walks
      *    reproduce exactly.
      *  @returns The {@link JssmStochasticRun} for this walk.
+     *  @throws {JssmError} If a visited state's candidate exit pool is
+     *  non-empty but all-zero-weight — see
+     *  {@link Machine._assert_selectable_exit_pool} (StoneCypher/fsl#1248).
      */
     private _stochastic_one_walk;
     /**
@@ -3518,8 +3598,12 @@ declare class Machine<mDT> {
      *  For any state OTHER than the current one, this returns the memoized static
      *  resolution (tiers 1–5; see `_compose_state_config`) — theme →
      *  `default_state_config` → per-kind defaults → depth-ordered group metadata →
-     *  per-state config.  The cache is keyed by state and never invalidated, since
-     *  those tiers do not depend on which state is current.
+     *  per-state config.  The cache is keyed by state; those tiers do not depend
+     *  on which state is current, so it survives transitions, but the mutable
+     *  cascade inputs each clear it when they change — hook registration and
+     *  removal ({@link Machine.set_hook}, {@link Machine.remove_hook}; the
+     *  hooked layer) and theme assignment (the `themes` setter; tier 1 and the
+     *  per-kind theme layers).
      *
      *  For the machine's CURRENTLY-occupied state the result is recomputed each
      *  call (never cached) and additionally carries the dynamic `active_state`