@patterkit/runtime 0.17.0 → 0.19.0

package/dist/index.d.cts

@@ -194,12 +194,34 @@ 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;
+}
 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;
@@ -256,6 +278,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
@@ -365,6 +391,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, {
@@ -396,6 +424,8 @@ declare class Engine {
     /** 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). */
@@ -501,9 +531,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. */
@@ -684,10 +717,13 @@ declare class Flow {
     private activeSnippet;
     private beatIndex;
     private pendingChoice;
-    /** When `replayPromptOnChoose`, the chosen option's prompt beat to deliver before its content. */
-    private pendingPromptBeat;
-    /** The chosen option that owns `pendingPromptBeat`, so a save taken between choose() and the next
-     *  advance() can re-derive the prompt on load (the beat isn't otherwise reachable by id). */
+    /** When `replayPromptOnChoose`, the chosen option's AUTHORED prompt to deliver before its content: its
+     *  beat (id, gameData, tags) and the prompt exactly as the choice showed it (text and speaker fields).
+     *  `shown` is missing only after loading a save written before saves carried it: the beat is then
+     *  resolved when it is delivered, as it always was. */
+    private pendingPrompt;
+    /** The chosen option that owns `pendingPrompt`, so a save taken between choose() and the next
+     *  advance() can find the prompt beat again on load (it isn't otherwise reachable by id). */
     private pendingPromptOwnerId;
     private selectors;
     /** Per-node entry counts for this flow (node id -> times entered). */
@@ -867,8 +903,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. */
@@ -907,6 +947,11 @@ declare class Flow {
      * option's first content line. NO look-ahead. Undefined only when even that is absent.
      */
     private promptFor;
+    /** An option's AUTHORED prompt beat: an Option group's own `prompt`. The only prompt a replay speaks. */
+    private authoredPromptOf;
+    /** A replayed prompt as a step: the beat's id, gameData, and tags, and the text and speaker fields the
+     *  choice showed. */
+    private promptResult;
     /** The prompt BEAT of an option: the Option group's `prompt`, else (tolerance) its first content line. */
     private promptBeatOf;
     /** The first snippet with a line/text beat within a child list, depth-first in authored order. */
@@ -1087,11 +1132,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 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

@@ -194,12 +194,34 @@ 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;
+}
 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;
@@ -256,6 +278,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
@@ -365,6 +391,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, {
@@ -396,6 +424,8 @@ declare class Engine {
     /** 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). */
@@ -501,9 +531,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. */
@@ -684,10 +717,13 @@ declare class Flow {
     private activeSnippet;
     private beatIndex;
     private pendingChoice;
-    /** When `replayPromptOnChoose`, the chosen option's prompt beat to deliver before its content. */
-    private pendingPromptBeat;
-    /** The chosen option that owns `pendingPromptBeat`, so a save taken between choose() and the next
-     *  advance() can re-derive the prompt on load (the beat isn't otherwise reachable by id). */
+    /** When `replayPromptOnChoose`, the chosen option's AUTHORED prompt to deliver before its content: its
+     *  beat (id, gameData, tags) and the prompt exactly as the choice showed it (text and speaker fields).
+     *  `shown` is missing only after loading a save written before saves carried it: the beat is then
+     *  resolved when it is delivered, as it always was. */
+    private pendingPrompt;
+    /** The chosen option that owns `pendingPrompt`, so a save taken between choose() and the next
+     *  advance() can find the prompt beat again on load (it isn't otherwise reachable by id). */
     private pendingPromptOwnerId;
     private selectors;
     /** Per-node entry counts for this flow (node id -> times entered). */
@@ -867,8 +903,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. */
@@ -907,6 +947,11 @@ declare class Flow {
      * option's first content line. NO look-ahead. Undefined only when even that is absent.
      */
     private promptFor;
+    /** An option's AUTHORED prompt beat: an Option group's own `prompt`. The only prompt a replay speaks. */
+    private authoredPromptOf;
+    /** A replayed prompt as a step: the beat's id, gameData, and tags, and the text and speaker fields the
+     *  choice showed. */
+    private promptResult;
     /** The prompt BEAT of an option: the Option group's `prompt`, else (tolerance) its first content line. */
     private promptBeatOf;
     /** The first snippet with a line/text beat within a child list, depth-first in authored order. */
@@ -1087,11 +1132,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 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 };