@patterkit/runtime 0.18.0 → 0.20.0

package/dist/index.d.cts

@@ -127,12 +127,14 @@ interface ChoiceOption {
     gameData?: GameData;
 }
 /**
- * The host's **World Properties** resolver: a `{ get, set? }` the game provides so the story can read
- * (and, if you allow it, write) its `@world.*` values at runtime. Property metadata (types, read-only)
- * comes from the compiled bundle's declared world properties; the values themselves live in the host and
+ * A host scope's resolver: a `{ get, set? }` the game provides so the story can read (and, if you allow
+ * it, write) values the game owns, `@world.*` among them, at runtime. Property metadata (types,
+ * read-only) comes from the compiled bundle's declarations; the values themselves live in the host and
  * are never stored or saved by this engine.
  */
-type WorldResolver = ScopeResolver;
+type HostScope = ScopeResolver;
+/** @deprecated Use {@link HostScope}, the name every Patterplay runtime uses. */
+type WorldResolver = HostScope;
 /** What the engine DECIDED, as opposed to what it produced. A step tells you the line that
  *  played; a trace event tells you why that line and not its siblings - which children were
  *  eligible, where the selector's cursor stood, which choice options were live.
@@ -194,12 +196,36 @@ type TraceEvent = {
     value: ScalarValue;
     prev?: ScalarValue;
 }
-/** An expression that would not evaluate: never a silent pass, always visible. */
+/** Content the engine could not evaluate and played through (see {@link PlayError}): a condition
+ *  counted as false, an effect skipped, or a Best-match part scored as false. */
  | {
     type: "diagnostic";
-    where: string;
+    kind: PlayError["kind"];
+    node: string;
+    source?: string;
     message: string;
 };
+/**
+ * A content error the engine played through. Content can fail at run time in ways the compiler cannot
+ * see: a division by zero, a host value of the wrong type, a story write to a read-only `@world` value.
+ * The story never stops for one. A condition that fails counts as false; an effect that fails is skipped
+ * and the rest of its list still runs; a part of a Best-match condition that fails scores as false. Each
+ * is reported, through `EngineOptions.onError` and as a `diagnostic` entry in the decision log. The same
+ * rule holds on all four runtimes, including the two whose languages cannot throw.
+ */
+interface PlayError {
+    /** The flow it happened in. */
+    flow: string;
+    /** What failed: a condition, an effect, or a part of a condition being scored for Best match. */
+    kind: "condition" | "effect" | "best-match";
+    /** The snippet, group, or option whose condition failed, or that owns the effect (a scene, for its onEntry). */
+    node: string;
+    /** The expression's source text, when the bundle carries it. */
+    source?: string;
+    message: string;
+}
+/** @deprecated Nothing takes one: a flow has no tap of its own, and `onTrace` takes an
+ *  {@link EngineTraceHandler}. Goes in a later release. */
 type TraceHandler = (event: TraceEvent) => void;
 /** The engine-level tap: every flow's events, tagged with the flow id - one stream for tools. */
 type EngineTraceHandler = (flow: string, event: TraceEvent) => void;
@@ -227,14 +253,18 @@ interface EngineOptions {
     /** Active locale for string lookups (embedded localisation). Defaults to the bundle's default locale.
      *  Ignored by an "ids" bundle, which emits beat IDs for the game to localise itself. */
     locale?: string;
-    /** The host's resolver for **World Properties** (`@world.*`): the values the game owns and the story
-     *  reads. Omit it and the runtime self-backs `@world` from the declared defaults, as a property the
-     *  registry stores and saves. Shared by all flows. A game running several engines registers `@world`
-     *  in its registry itself instead, and no engine is given a resolver. */
-    world?: WorldResolver;
+    /** The host scopes the game binds, by token: for each, a resolver over values the game owns and the
+     *  story reads, such as `{ world: { get, set } }` for **World Properties** (`@world.*`). A declared
+     *  scope left unbound is self-backed from its defaults, as a property the registry stores and saves.
+     *  Shared by all flows. A game running several engines registers its scopes in its registry itself
+     *  instead, and binds none here. The same option on every runtime. */
+    hostScopes?: Record<string, HostScope>;
+    /** @deprecated Use `hostScopes: { world }`, the option every Patterplay runtime takes. Goes in a later
+     *  release. */
+    world?: HostScope;
     /** The game's registry: ONE per game, holding every engine's properties except those the game keeps
      *  itself, saved once. Given one, the engine registers its own scopes in it (`@patter` under `patter`,
-     *  its per-flow and per-scene bags under keys starting `patter/`, and `@world` if `world` is passed),
+     *  its per-flow and per-scene bags under keys starting `patter/`, and each scope `hostScopes` binds),
      *  reads every other scope from it, and `saveGame()` leaves the property values to the game. Host
      *  scopes the bundle declares (`@world`) are then the game's to register: owned if the registry should
      *  store them, foreign if the game keeps them. Omit it and the engine makes its own registry and acts as
@@ -256,6 +286,10 @@ interface EngineOptions {
      *  unchanged; this only makes the fall-through observable. The coverage harness uses it to flag choices
      *  that ran dry. Leave it unset in shipped games (zero cost). */
     onDryChoice?: (groupId: string) => void;
+    /** Called with each content error the engine played through (see {@link PlayError}): a condition
+     *  that failed and counted as false, an effect that failed and was skipped. Unset, each is written
+     *  to `console.warn`, so a content bug is never silent. */
+    onError?: (error: PlayError) => void;
     /** Retain a trace of the engine's DECISIONS (what it chose and why), readable through
      *  `engine.log()` and `flow.log()`. Off by default: a shipped game pays nothing for a
      *  debugging surface it never reads. `onDryChoice` above is unaffected and stays useful
@@ -298,8 +332,13 @@ declare class Checkpoint {
 }
 /** Shared, read-mostly context the engine hands to every flow it owns. */
 interface FlowHost {
-    /** True when the run asked for a log; flows skip building entries otherwise. */
+    /** True when the run asked for a log. */
     logEnabled: boolean;
+    /** Each declaration set's quality ladders, built on first use (see `ladders`). */
+    qualityLadders: Map<string, Map<string, readonly string[]>>;
+    /** True when anything takes the decisions: the log, or an {@link Engine.onTrace} handler. Flows skip
+     *  the work only a decision needs (a `run` walk's entry, a write's previous value) otherwise. */
+    tracing: boolean;
     /** A flow's events reach the ENGINE's stream through here, tagged with the flow id. */
     emitEngine: (flow: string, event: TraceEvent, scene?: string) => void;
     bundle: Bundle;
@@ -365,6 +404,8 @@ interface FlowHost {
      *  fallback - so it falls through and the flow continues past it. Zero cost when unset; the coverage
      *  harness passes it to surface silent fall-throughs. Not a gameplay signal (the behaviour is unchanged). */
     onDryChoice?: (groupId: string) => void;
+    /** Where a content error the engine played through is reported (see PlayError). */
+    onError: (error: PlayError) => void;
     /** Memoised `splitRef` results (ref string -> {scope,name}). The split depends only on the registry's
      *  scope set, so the cache is dropped whenever that moves (`refSplitRevision`). */
     refSplitCache: Map<string, {
@@ -391,11 +432,13 @@ declare class Engine {
     private readonly sceneGameIdToId;
     private readonly blockGameIdToId;
     /** The options this engine was built with - reused verbatim by `hotSwap` so the replacement
-     *  engine keeps the same world resolver, custom RNG, and diagnostic hooks. */
+     *  engine keeps the same host scopes, custom RNG, and diagnostic hooks. */
     private readonly creationOptions;
     /** The run's ordered stream: every flow's events, each naming its flow. Empty and
      *  unwritten unless `options.log` asked for it. */
     private readonly engineLog;
+    /** The next engine-log `seq`: its own counter, since the log's length restarts after a clear. */
+    private engineSeq;
     private readonly engineTraceHandlers;
     constructor(bundle: Bundle, options?: EngineOptions);
     /** The active locale (string + character-name lookups resolve in it). */
@@ -403,6 +446,9 @@ declare class Engine {
     /** True for a source-only DEBUG build: the embedded strings are the source language (for debugging),
      *  not a shippable localised build. An IDs-only ship build is `false`. */
     get isSourceDebug(): boolean;
+    /** The bundle's build identity (its content hash), the one a debug link handshakes with, or an empty
+     *  string for a bundle compiled without one. */
+    get buildId(): string;
     /**
      * Switch the active locale LIVE - a real game's "language" setting can change mid-session. Subsequent
      * string lookups (new beats, re-resolved character names, `{@ref}` interpolation) render in the new
@@ -501,9 +547,12 @@ declare class Engine {
      * is an internal id from any scene. Neither: the bundle's first scene. The same rule on every runtime.
      */
     private resolveOpenAddress;
-    /** Resolve a scene reference (a gameId address OR an internal id) to its internal id. */
+    /** Resolve a scene reference to its internal id by the one address rule (see resolveScene); an
+     *  unknown one passes through, for the caller to find nothing. */
     private resolveSceneRef;
-    /** Resolve a block reference (a scene-scoped gameId OR an internal id) to its internal id. */
+    /** Resolve a block reference to its internal id by the one address rule (see resolveBlock): within its
+     *  scene, so a block of another scene resolves to nothing. With no scene, only an internal id resolves,
+     *  since a block's gameId is only unique within its scene. */
     private resolveBlockRef;
     /** The host-facing address (gameId) of a scene / block by internal id, or undefined if unknown.
      *  The inverse of the resolve helpers - for a host that wants to display / log the address. */
@@ -644,6 +693,9 @@ declare class Engine {
      *  retained. Returns its own unsubscribe. */
     onTrace(handler: EngineTraceHandler): () => void;
     private emitEngine;
+    /** How many times each node has been entered across every flow, by node id: the shared count. With a
+     *  flow's own {@link Flow.getVisitCounts}, every visit count the run keeps, read without a save. */
+    getVisitCounts(): Record<string, number>;
     listProperties(): PropertyRow[];
     private splitShared;
     /** The shared `@patter` values alone, as `{ patter: {...} }`.
@@ -711,15 +763,20 @@ declare class Flow {
     /** The stage ladder of `@scope.name` when it is a declared quality, else undefined. Names compare
      *  lowercase, as the compiler emits references (the selfBackedResolver lesson). */
     private stagesFor;
-    /** Begin this flow at a scene (and optionally a specific block within it). */
-    start(sceneId?: string, blockId?: string): void;
+    /** Begin this flow at a scene (and optionally a specific block within it). The engine's own entry point:
+     *  openFlow and a goto on an unstarted flow begin a flow here. A game calls {@link reset}.
+     *  @internal */
+    begin(sceneId?: string, blockId?: string): void;
     /**
      * Forget everything in this flow and begin again - its per-flow state (not-shared
      * `@patter` globals + `@scene` props), cursor, callstack, selector cursors, and
      * visit counts. Shared state (shared `@patter` / `@scene`, world visit counts) is
-     * untouched. A clearer-named alias of `start()`.
+     * untouched. The one public way to begin a flow again (openFlow begins a new one).
      */
     reset(sceneId?: string, blockId?: string): void;
+    /** @deprecated Use {@link reset}, the one public name for beginning a flow again on every runtime. `start`
+     *  was the same call under a second name, and goes in a later release. */
+    start(sceneId?: string, blockId?: string): void;
     /**
      * Send this flow's cursor to an ADDRESS, exactly as an authored `go` jump would: the target scene's
      * `onEntry` effects run, entering counts as a visit, and the callstack is REPLACED - any pending
@@ -749,6 +806,13 @@ declare class Flow {
      * cannot quietly mutate the world. Terminal: unlike ending, a close is never revived.
      */
     close(): void;
+    /**
+     * Drop everything waiting to be delivered: an open choice, and a chosen option's prompt still to be
+     * replayed. Every move that abandons the flow's place (start and reset, goto, close) does this, so none
+     * leaves a stale prompt behind. start() cleared only the choice, so a reset between choose() and the
+     * next advance() replayed the abandoned run's prompt as the new run's first beat.
+     */
+    private clearPending;
     /** Inside a checkpoint, the first change to this flow records its cursor and PRNG, so a rollback can
      *  put them back: a handful of fields and a copy of the call stack (a few frames), never its history.
      *  Its visits, selector cursors, and property values are recorded change by change as they happen. */
@@ -787,9 +851,11 @@ declare class Flow {
     log(): readonly LogEntry[];
     /** Drop the retained entries. `seq` keeps counting, so order survives a clear. */
     clearLog(): void;
-    /** Record one decision, on this flow's log and the engine's. Cheap to call with logging
-     *  off: the entry is never built. */
+    /** Record one decision, on this flow's log and the engine's, and hand it to any `onTrace`. Each call
+     *  site checks `host.tracing` first, so with nothing logging or tracing the entry is never built. */
     private emit;
+    /** How many times this flow has entered each node, by node id. */
+    getVisitCounts(): Record<string, number>;
     /** The options of a pending choice (empty when not at a choice point). */
     getChoices(): ChoiceOption[];
     /** Pick an eligible option by id; the next `advance()` runs it. */
@@ -870,8 +936,12 @@ declare class Flow {
     private matchedSpec;
     /** A selector's cursor state - shared across flows (`group.shared`) or this flow's own. */
     private selectorState;
+    /** Run an effect list. `owner` is the snippet or scene it belongs to, for an error report. */
     private runEffects;
+    /** Whether a node's condition holds. A condition that fails to evaluate counts as false (see PlayError). */
     private eligible;
+    /** Report a content error the engine is playing through: to the host's onError, and to the log. */
+    private reportError;
     private evalExpr;
     /** The deserialised (in-memory) AST for an expression, cached per Expression. Shared by the
      *  evaluator and the Best-match specificity walker so both work off one parse. */
@@ -1095,11 +1165,11 @@ declare function gameDataValue(fields: GameDataField[], node: GameData | undefin
 declare function effectiveGameData(fields: GameDataField[], node: GameData | undefined): GameData;
 
 /**
- * Map every node id (scene / block / group / snippet / beat) to its accumulated
+ * Map every node id (scene / block / group / snippet / beat, prompt beats included) to its accumulated
  * tags. Node ids are globally unique within a project (the validator enforces
  * it), so one flat map suffices. Nodes with no tags anywhere up the chain map to
  * an empty array.
  */
 declare function buildTagIndex(bundle: Bundle): Map<string, string[]>;
 
-export { type AddressSummary, type AdvanceToStopResult, type BeatInfo, type BundleCounts, type BundleDescription, type BundleIdentity, Checkpoint, type ChoiceOption, Engine, type EngineLogEntry, type EngineOptions, type EngineTraceHandler, type FlatBeat, Flow, type GameDataFieldSummary, type GameDataSummary, type HostScopeSummary, type LogEntry, type OpenFlowOptions, type OutlineBlock, type OutlineNode, type OutlineScene, type OwnedProperties, type PropertySummary, type StepResult, type TraceEvent, type TraceHandler, type WorldResolver, buildTagIndex, describeBundle, effectiveGameData, gameDataFields, gameDataValue };
+export { type AddressSummary, type AdvanceToStopResult, type BeatInfo, type BundleCounts, type BundleDescription, type BundleIdentity, Checkpoint, type ChoiceOption, Engine, type EngineLogEntry, type EngineOptions, type EngineTraceHandler, type FlatBeat, Flow, type GameDataFieldSummary, type GameDataSummary, type HostScope, type HostScopeSummary, type LogEntry, type OpenFlowOptions, type OutlineBlock, type OutlineNode, type OutlineScene, type OwnedProperties, type PlayError, type PropertySummary, type StepResult, type TraceEvent, type TraceHandler, type WorldResolver, buildTagIndex, describeBundle, effectiveGameData, gameDataFields, gameDataValue };

package/dist/index.d.ts

@@ -127,12 +127,14 @@ interface ChoiceOption {
     gameData?: GameData;
 }
 /**
- * The host's **World Properties** resolver: a `{ get, set? }` the game provides so the story can read
- * (and, if you allow it, write) its `@world.*` values at runtime. Property metadata (types, read-only)
- * comes from the compiled bundle's declared world properties; the values themselves live in the host and
+ * A host scope's resolver: a `{ get, set? }` the game provides so the story can read (and, if you allow
+ * it, write) values the game owns, `@world.*` among them, at runtime. Property metadata (types,
+ * read-only) comes from the compiled bundle's declarations; the values themselves live in the host and
  * are never stored or saved by this engine.
  */
-type WorldResolver = ScopeResolver;
+type HostScope = ScopeResolver;
+/** @deprecated Use {@link HostScope}, the name every Patterplay runtime uses. */
+type WorldResolver = HostScope;
 /** What the engine DECIDED, as opposed to what it produced. A step tells you the line that
  *  played; a trace event tells you why that line and not its siblings - which children were
  *  eligible, where the selector's cursor stood, which choice options were live.
@@ -194,12 +196,36 @@ type TraceEvent = {
     value: ScalarValue;
     prev?: ScalarValue;
 }
-/** An expression that would not evaluate: never a silent pass, always visible. */
+/** Content the engine could not evaluate and played through (see {@link PlayError}): a condition
+ *  counted as false, an effect skipped, or a Best-match part scored as false. */
  | {
     type: "diagnostic";
-    where: string;
+    kind: PlayError["kind"];
+    node: string;
+    source?: string;
     message: string;
 };
+/**
+ * A content error the engine played through. Content can fail at run time in ways the compiler cannot
+ * see: a division by zero, a host value of the wrong type, a story write to a read-only `@world` value.
+ * The story never stops for one. A condition that fails counts as false; an effect that fails is skipped
+ * and the rest of its list still runs; a part of a Best-match condition that fails scores as false. Each
+ * is reported, through `EngineOptions.onError` and as a `diagnostic` entry in the decision log. The same
+ * rule holds on all four runtimes, including the two whose languages cannot throw.
+ */
+interface PlayError {
+    /** The flow it happened in. */
+    flow: string;
+    /** What failed: a condition, an effect, or a part of a condition being scored for Best match. */
+    kind: "condition" | "effect" | "best-match";
+    /** The snippet, group, or option whose condition failed, or that owns the effect (a scene, for its onEntry). */
+    node: string;
+    /** The expression's source text, when the bundle carries it. */
+    source?: string;
+    message: string;
+}
+/** @deprecated Nothing takes one: a flow has no tap of its own, and `onTrace` takes an
+ *  {@link EngineTraceHandler}. Goes in a later release. */
 type TraceHandler = (event: TraceEvent) => void;
 /** The engine-level tap: every flow's events, tagged with the flow id - one stream for tools. */
 type EngineTraceHandler = (flow: string, event: TraceEvent) => void;
@@ -227,14 +253,18 @@ interface EngineOptions {
     /** Active locale for string lookups (embedded localisation). Defaults to the bundle's default locale.
      *  Ignored by an "ids" bundle, which emits beat IDs for the game to localise itself. */
     locale?: string;
-    /** The host's resolver for **World Properties** (`@world.*`): the values the game owns and the story
-     *  reads. Omit it and the runtime self-backs `@world` from the declared defaults, as a property the
-     *  registry stores and saves. Shared by all flows. A game running several engines registers `@world`
-     *  in its registry itself instead, and no engine is given a resolver. */
-    world?: WorldResolver;
+    /** The host scopes the game binds, by token: for each, a resolver over values the game owns and the
+     *  story reads, such as `{ world: { get, set } }` for **World Properties** (`@world.*`). A declared
+     *  scope left unbound is self-backed from its defaults, as a property the registry stores and saves.
+     *  Shared by all flows. A game running several engines registers its scopes in its registry itself
+     *  instead, and binds none here. The same option on every runtime. */
+    hostScopes?: Record<string, HostScope>;
+    /** @deprecated Use `hostScopes: { world }`, the option every Patterplay runtime takes. Goes in a later
+     *  release. */
+    world?: HostScope;
     /** The game's registry: ONE per game, holding every engine's properties except those the game keeps
      *  itself, saved once. Given one, the engine registers its own scopes in it (`@patter` under `patter`,
-     *  its per-flow and per-scene bags under keys starting `patter/`, and `@world` if `world` is passed),
+     *  its per-flow and per-scene bags under keys starting `patter/`, and each scope `hostScopes` binds),
      *  reads every other scope from it, and `saveGame()` leaves the property values to the game. Host
      *  scopes the bundle declares (`@world`) are then the game's to register: owned if the registry should
      *  store them, foreign if the game keeps them. Omit it and the engine makes its own registry and acts as
@@ -256,6 +286,10 @@ interface EngineOptions {
      *  unchanged; this only makes the fall-through observable. The coverage harness uses it to flag choices
      *  that ran dry. Leave it unset in shipped games (zero cost). */
     onDryChoice?: (groupId: string) => void;
+    /** Called with each content error the engine played through (see {@link PlayError}): a condition
+     *  that failed and counted as false, an effect that failed and was skipped. Unset, each is written
+     *  to `console.warn`, so a content bug is never silent. */
+    onError?: (error: PlayError) => void;
     /** Retain a trace of the engine's DECISIONS (what it chose and why), readable through
      *  `engine.log()` and `flow.log()`. Off by default: a shipped game pays nothing for a
      *  debugging surface it never reads. `onDryChoice` above is unaffected and stays useful
@@ -298,8 +332,13 @@ declare class Checkpoint {
 }
 /** Shared, read-mostly context the engine hands to every flow it owns. */
 interface FlowHost {
-    /** True when the run asked for a log; flows skip building entries otherwise. */
+    /** True when the run asked for a log. */
     logEnabled: boolean;
+    /** Each declaration set's quality ladders, built on first use (see `ladders`). */
+    qualityLadders: Map<string, Map<string, readonly string[]>>;
+    /** True when anything takes the decisions: the log, or an {@link Engine.onTrace} handler. Flows skip
+     *  the work only a decision needs (a `run` walk's entry, a write's previous value) otherwise. */
+    tracing: boolean;
     /** A flow's events reach the ENGINE's stream through here, tagged with the flow id. */
     emitEngine: (flow: string, event: TraceEvent, scene?: string) => void;
     bundle: Bundle;
@@ -365,6 +404,8 @@ interface FlowHost {
      *  fallback - so it falls through and the flow continues past it. Zero cost when unset; the coverage
      *  harness passes it to surface silent fall-throughs. Not a gameplay signal (the behaviour is unchanged). */
     onDryChoice?: (groupId: string) => void;
+    /** Where a content error the engine played through is reported (see PlayError). */
+    onError: (error: PlayError) => void;
     /** Memoised `splitRef` results (ref string -> {scope,name}). The split depends only on the registry's
      *  scope set, so the cache is dropped whenever that moves (`refSplitRevision`). */
     refSplitCache: Map<string, {
@@ -391,11 +432,13 @@ declare class Engine {
     private readonly sceneGameIdToId;
     private readonly blockGameIdToId;
     /** The options this engine was built with - reused verbatim by `hotSwap` so the replacement
-     *  engine keeps the same world resolver, custom RNG, and diagnostic hooks. */
+     *  engine keeps the same host scopes, custom RNG, and diagnostic hooks. */
     private readonly creationOptions;
     /** The run's ordered stream: every flow's events, each naming its flow. Empty and
      *  unwritten unless `options.log` asked for it. */
     private readonly engineLog;
+    /** The next engine-log `seq`: its own counter, since the log's length restarts after a clear. */
+    private engineSeq;
     private readonly engineTraceHandlers;
     constructor(bundle: Bundle, options?: EngineOptions);
     /** The active locale (string + character-name lookups resolve in it). */
@@ -403,6 +446,9 @@ declare class Engine {
     /** True for a source-only DEBUG build: the embedded strings are the source language (for debugging),
      *  not a shippable localised build. An IDs-only ship build is `false`. */
     get isSourceDebug(): boolean;
+    /** The bundle's build identity (its content hash), the one a debug link handshakes with, or an empty
+     *  string for a bundle compiled without one. */
+    get buildId(): string;
     /**
      * Switch the active locale LIVE - a real game's "language" setting can change mid-session. Subsequent
      * string lookups (new beats, re-resolved character names, `{@ref}` interpolation) render in the new
@@ -501,9 +547,12 @@ declare class Engine {
      * is an internal id from any scene. Neither: the bundle's first scene. The same rule on every runtime.
      */
     private resolveOpenAddress;
-    /** Resolve a scene reference (a gameId address OR an internal id) to its internal id. */
+    /** Resolve a scene reference to its internal id by the one address rule (see resolveScene); an
+     *  unknown one passes through, for the caller to find nothing. */
     private resolveSceneRef;
-    /** Resolve a block reference (a scene-scoped gameId OR an internal id) to its internal id. */
+    /** Resolve a block reference to its internal id by the one address rule (see resolveBlock): within its
+     *  scene, so a block of another scene resolves to nothing. With no scene, only an internal id resolves,
+     *  since a block's gameId is only unique within its scene. */
     private resolveBlockRef;
     /** The host-facing address (gameId) of a scene / block by internal id, or undefined if unknown.
      *  The inverse of the resolve helpers - for a host that wants to display / log the address. */
@@ -644,6 +693,9 @@ declare class Engine {
      *  retained. Returns its own unsubscribe. */
     onTrace(handler: EngineTraceHandler): () => void;
     private emitEngine;
+    /** How many times each node has been entered across every flow, by node id: the shared count. With a
+     *  flow's own {@link Flow.getVisitCounts}, every visit count the run keeps, read without a save. */
+    getVisitCounts(): Record<string, number>;
     listProperties(): PropertyRow[];
     private splitShared;
     /** The shared `@patter` values alone, as `{ patter: {...} }`.
@@ -711,15 +763,20 @@ declare class Flow {
     /** The stage ladder of `@scope.name` when it is a declared quality, else undefined. Names compare
      *  lowercase, as the compiler emits references (the selfBackedResolver lesson). */
     private stagesFor;
-    /** Begin this flow at a scene (and optionally a specific block within it). */
-    start(sceneId?: string, blockId?: string): void;
+    /** Begin this flow at a scene (and optionally a specific block within it). The engine's own entry point:
+     *  openFlow and a goto on an unstarted flow begin a flow here. A game calls {@link reset}.
+     *  @internal */
+    begin(sceneId?: string, blockId?: string): void;
     /**
      * Forget everything in this flow and begin again - its per-flow state (not-shared
      * `@patter` globals + `@scene` props), cursor, callstack, selector cursors, and
      * visit counts. Shared state (shared `@patter` / `@scene`, world visit counts) is
-     * untouched. A clearer-named alias of `start()`.
+     * untouched. The one public way to begin a flow again (openFlow begins a new one).
      */
     reset(sceneId?: string, blockId?: string): void;
+    /** @deprecated Use {@link reset}, the one public name for beginning a flow again on every runtime. `start`
+     *  was the same call under a second name, and goes in a later release. */
+    start(sceneId?: string, blockId?: string): void;
     /**
      * Send this flow's cursor to an ADDRESS, exactly as an authored `go` jump would: the target scene's
      * `onEntry` effects run, entering counts as a visit, and the callstack is REPLACED - any pending
@@ -749,6 +806,13 @@ declare class Flow {
      * cannot quietly mutate the world. Terminal: unlike ending, a close is never revived.
      */
     close(): void;
+    /**
+     * Drop everything waiting to be delivered: an open choice, and a chosen option's prompt still to be
+     * replayed. Every move that abandons the flow's place (start and reset, goto, close) does this, so none
+     * leaves a stale prompt behind. start() cleared only the choice, so a reset between choose() and the
+     * next advance() replayed the abandoned run's prompt as the new run's first beat.
+     */
+    private clearPending;
     /** Inside a checkpoint, the first change to this flow records its cursor and PRNG, so a rollback can
      *  put them back: a handful of fields and a copy of the call stack (a few frames), never its history.
      *  Its visits, selector cursors, and property values are recorded change by change as they happen. */
@@ -787,9 +851,11 @@ declare class Flow {
     log(): readonly LogEntry[];
     /** Drop the retained entries. `seq` keeps counting, so order survives a clear. */
     clearLog(): void;
-    /** Record one decision, on this flow's log and the engine's. Cheap to call with logging
-     *  off: the entry is never built. */
+    /** Record one decision, on this flow's log and the engine's, and hand it to any `onTrace`. Each call
+     *  site checks `host.tracing` first, so with nothing logging or tracing the entry is never built. */
     private emit;
+    /** How many times this flow has entered each node, by node id. */
+    getVisitCounts(): Record<string, number>;
     /** The options of a pending choice (empty when not at a choice point). */
     getChoices(): ChoiceOption[];
     /** Pick an eligible option by id; the next `advance()` runs it. */
@@ -870,8 +936,12 @@ declare class Flow {
     private matchedSpec;
     /** A selector's cursor state - shared across flows (`group.shared`) or this flow's own. */
     private selectorState;
+    /** Run an effect list. `owner` is the snippet or scene it belongs to, for an error report. */
     private runEffects;
+    /** Whether a node's condition holds. A condition that fails to evaluate counts as false (see PlayError). */
     private eligible;
+    /** Report a content error the engine is playing through: to the host's onError, and to the log. */
+    private reportError;
     private evalExpr;
     /** The deserialised (in-memory) AST for an expression, cached per Expression. Shared by the
      *  evaluator and the Best-match specificity walker so both work off one parse. */
@@ -1095,11 +1165,11 @@ declare function gameDataValue(fields: GameDataField[], node: GameData | undefin
 declare function effectiveGameData(fields: GameDataField[], node: GameData | undefined): GameData;
 
 /**
- * Map every node id (scene / block / group / snippet / beat) to its accumulated
+ * Map every node id (scene / block / group / snippet / beat, prompt beats included) to its accumulated
  * tags. Node ids are globally unique within a project (the validator enforces
  * it), so one flat map suffices. Nodes with no tags anywhere up the chain map to
  * an empty array.
  */
 declare function buildTagIndex(bundle: Bundle): Map<string, string[]>;
 
-export { type AddressSummary, type AdvanceToStopResult, type BeatInfo, type BundleCounts, type BundleDescription, type BundleIdentity, Checkpoint, type ChoiceOption, Engine, type EngineLogEntry, type EngineOptions, type EngineTraceHandler, type FlatBeat, Flow, type GameDataFieldSummary, type GameDataSummary, type HostScopeSummary, type LogEntry, type OpenFlowOptions, type OutlineBlock, type OutlineNode, type OutlineScene, type OwnedProperties, type PropertySummary, type StepResult, type TraceEvent, type TraceHandler, type WorldResolver, buildTagIndex, describeBundle, effectiveGameData, gameDataFields, gameDataValue };
+export { type AddressSummary, type AdvanceToStopResult, type BeatInfo, type BundleCounts, type BundleDescription, type BundleIdentity, Checkpoint, type ChoiceOption, Engine, type EngineLogEntry, type EngineOptions, type EngineTraceHandler, type FlatBeat, Flow, type GameDataFieldSummary, type GameDataSummary, type HostScope, type HostScopeSummary, type LogEntry, type OpenFlowOptions, type OutlineBlock, type OutlineNode, type OutlineScene, type OwnedProperties, type PlayError, type PropertySummary, type StepResult, type TraceEvent, type TraceHandler, type WorldResolver, buildTagIndex, describeBundle, effectiveGameData, gameDataFields, gameDataValue };