@patterkit/runtime 0.8.0 → 0.9.0

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { ScalarValue } from '@wildwinter/expr';
-import { ScopeResolver, ScopeRegistry, ScopeDeclaration } from '@wildwinter/scoperegistry';
+import { ScopeResolver, ScopeRegistry, ScopeDeclaration, PropertyBag, PropertyRow } from '@wildwinter/scoperegistry';
+export { PropertyRow } from '@wildwinter/scoperegistry';
 import { GameData, Bundle, CompiledGroup, CompiledSnippet, CompiledBlock, PropertyType, ScalarValue as ScalarValue$1, GameDataNodeKind, GameDataField } from '@patterkit/model';
 export { Bundle } from '@patterkit/model';
 
@@ -196,6 +197,88 @@ interface ChoiceOption {
  * are never stored or saved by this engine.
  */
 type WorldResolver = ScopeResolver;
+/** 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.
+ *
+ *  The reasoning is IN the entry, not implied by it. `select` carries every child it looked at
+ *  with its own verdict, the way a deal in the Storylet Engine carries every card it considered.
+ *  A log that recorded only the winner would answer "what happened" and not "why", and "why"
+ *  is the question a dialogue author cannot otherwise answer: the line you expected is missing
+ *  and nothing anywhere says which condition dropped it.
+ *
+ *  Patter's vocabulary, not the Storylet Engine's: there are no cards or hands here. The
+ *  structure is shared (an ordered retained log, `seq`, a flow-level and an engine-level tap);
+ *  the events are this engine's own. */
+type TraceEvent = {
+    type: "select";
+    /** The group whose children were being chosen among. */
+    group: string;
+    /** `branch` | `sequence` | `run` | `choice`, and for `sequence` its order/exhaust policy. */
+    selector: string;
+    order?: string;
+    exhaust?: string;
+    /** Every child considered, in authored order, each with why it was or was not takeable. */
+    children: {
+        id: string;
+        eligible: boolean;
+    }[];
+    /** The child selected, or null when nothing was takeable. */
+    picked: string | null;
+} | {
+    type: "choice";
+    group: string;
+    /** Every option the group offered, with the ones a condition dropped marked. */
+    options: {
+        id: string;
+        eligible: boolean;
+    }[];
+}
+/** A choice the player answered. `option` is what they took. */
+ | {
+    type: "chose";
+    group: string;
+    option: string;
+}
+/** A choice with no takeable option and no eligible fallback, which falls through
+ *  silently. Also reported through `onDryChoice`, which stays: a log is an audit read
+ *  afterwards, that callback is live feedback a host acts on. */
+ | {
+    type: "dry";
+    group: string;
+} | {
+    type: "jump";
+    to: string;
+    mode: "jump" | "call";
+}
+/** One landed effect; `prev` is the value it replaced, so a reader can say "0 -> 1". */
+ | {
+    type: "write";
+    target: string;
+    value: ScalarValue;
+    prev?: ScalarValue;
+}
+/** An expression that would not evaluate: never a silent pass, always visible. */
+ | {
+    type: "diagnostic";
+    where: 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;
+/** A retained entry: the event plus its place in flow time. `seq` is monotonic across the
+ *  flow and survives clearLog, so two reads of the log agree about order. */
+type LogEntry = TraceEvent & {
+    seq: number;
+    scene?: string;
+};
+/** One entry on the ENGINE's log: the same event plus the flow it happened in. A run is
+ *  several flows over shared state, so "what happened in this run" is only answerable in one
+ *  ordered stream, and only if each line says who. */
+type EngineLogEntry = LogEntry & {
+    flow: string;
+};
 interface EngineOptions {
     /**
      * Custom float-in-[0,1) source for `random()` / shuffle, shared by all flows.
@@ -227,17 +310,11 @@ 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;
-}
-/** One shared `@patter` property, for a live state inspector: its ref, declared type, current value,
- *  declared default (for reset), and enum options. Mirrors the Unity / Godot ports' ListProperties. */
-interface PropertyRow {
-    ref: string;
-    type: PropertyType;
-    value: ScalarValue | undefined;
-    default: ScalarValue;
-    values?: string[];
-    /** A quality's ordered stage ladder (lets an inspector offer stages instead of free text). */
-    stages?: string[];
+    /** 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
+     *  with the log off - it is live feedback, not an audit read afterwards. */
+    log?: boolean;
 }
 /** Options for opening a flow. */
 interface OpenFlowOptions {
@@ -256,6 +333,10 @@ interface SelectorState {
 }
 /** 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. */
+    logEnabled: 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;
     /** IDs-only build (`localisation.mode === "ids"`, no source-debug): the engine emits each beat's ID as
      *  its text and omits character display names, leaving localisation to the game (use `flow.interpolate`
@@ -293,7 +374,11 @@ interface FlowHost {
     /** Shared selector cursors (node id -> SelectorState) for `shared` memoried selectors. */
     sharedSelectors: Map<string, SelectorState>;
     /** Shared, scene-namespaced `@scene` bags (scene id -> name -> value) for shared scene props. */
-    stageBags: Map<string, Record<string, ScalarValue>>;
+    /** Per-scene SHARED scene props. A PropertyBag rather than a bare record since
+     *  2026-09-02: seeding, name normalisation and the mutable-default clone were all
+     *  written out by hand here, and the shared bag already had them. The SAVE is
+     *  unchanged - bag.save() is a bare record, which is what the envelope carries. */
+    stageBags: Map<string, PropertyBag>;
     customRng?: () => number;
     /** Play a chosen option's prompt as its first beat (spec §5); default false. */
     replayPromptOnChoose?: boolean;
@@ -337,6 +422,10 @@ declare class Engine {
     /** 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. */
     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;
+    private readonly engineTraceHandlers;
     constructor(bundle: Bundle, options?: EngineOptions);
     /** The active locale (string + character-name lookups resolve in it). */
     get locale(): string;
@@ -496,6 +585,17 @@ declare class Engine {
     setProperty(ref: string, value: ScalarValue): void;
     /** The shared `@patter` properties, for a live state inspector: each with its ref, type, current
      *  value, declared default (for reset), and enum options. Mirrors the Unity / Godot ports. */
+    /** The run's decisions, in order, each naming the flow it happened in. Empty unless the
+     *  run was opened with `log: true`. A flow's own log stays flow-local; this is the only
+     *  place a story spanning several flows reads as one sequence. */
+    log(): readonly EngineLogEntry[];
+    /** Drop the retained entries. `seq` does NOT restart: two reads of a log either side of a
+     *  clear still agree about what came first. */
+    clearLog(): void;
+    /** Live tap on the run's decisions, for tooling that wants them as they happen rather than
+     *  retained. Returns its own unsubscribe. */
+    onTrace(handler: EngineTraceHandler): () => void;
+    private emitEngine;
     listProperties(): PropertyRow[];
     private splitShared;
     /** Snapshot shared `@patter` state only (for a unified cross-engine save blob, Phase D). */
@@ -530,10 +630,14 @@ declare class Flow {
     private selectors;
     /** Per-node entry counts for this flow (node id -> times entered). */
     private visitCounts;
+    /** This flow's per-scene LOCAL scene props; see FlowHost.stageBags. */
     private sceneBags;
     private readonly patterResolver;
     private readonly sceneResolver;
     private readonly evalCtx;
+    private readonly flowLog;
+    /** Monotonic across the flow's life; survives clearLog so two reads agree on order. */
+    private flowSeq;
     constructor(id: string, host: FlowHost, seed: number);
     /** 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). */
@@ -599,6 +703,15 @@ declare class Flow {
      */
     private settle;
     /** The options of a pending choice (empty when not at a choice point). */
+    /** This flow's decisions, in order. Empty unless the run was opened with `log: true`.
+     *  The engine's log carries the same events tagged with the flow; this one is what a
+     *  single conversation reads as. */
+    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. */
+    private emit;
     getChoices(): ChoiceOption[];
     /** Pick an eligible option by id; the next `advance()` runs it. */
     choose(id: string): void;
@@ -887,4 +1000,4 @@ declare function effectiveGameData(fields: GameDataField[], node: GameData | und
  */
 declare function buildTagIndex(bundle: Bundle): Map<string, string[]>;
 
-export { type AddressSummary, type AdvanceToStopResult, type BeatInfo, type BundleCounts, type BundleDescription, type BundleIdentity, type ChoiceOption, Engine, type EngineOptions, type EngineSave, type FlatBeat, Flow, type FlowSnapshot, type GameDataFieldSummary, type GameDataSummary, type HostScopeSummary, type OpenFlowOptions, type OutlineBlock, type OutlineNode, type OutlineScene, type OwnedProperties, type PropertyRow, type PropertySummary, type SaveGame, type SavedChoice, type SelectorSnapshot, type StackFrame, type StepResult, type WorldResolver, buildTagIndex, describeBundle, effectiveGameData, gameDataFields, gameDataValue };
+export { type AddressSummary, type AdvanceToStopResult, type BeatInfo, type BundleCounts, type BundleDescription, type BundleIdentity, type ChoiceOption, Engine, type EngineLogEntry, type EngineOptions, type EngineSave, type EngineTraceHandler, type FlatBeat, Flow, type FlowSnapshot, type GameDataFieldSummary, type GameDataSummary, type HostScopeSummary, type LogEntry, type OpenFlowOptions, type OutlineBlock, type OutlineNode, type OutlineScene, type OwnedProperties, type PropertySummary, type SaveGame, type SavedChoice, type SelectorSnapshot, type StackFrame, type StepResult, type TraceEvent, type TraceHandler, type WorldResolver, buildTagIndex, describeBundle, effectiveGameData, gameDataFields, gameDataValue };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { ScalarValue } from '@wildwinter/expr';
-import { ScopeResolver, ScopeRegistry, ScopeDeclaration } from '@wildwinter/scoperegistry';
+import { ScopeResolver, ScopeRegistry, ScopeDeclaration, PropertyBag, PropertyRow } from '@wildwinter/scoperegistry';
+export { PropertyRow } from '@wildwinter/scoperegistry';
 import { GameData, Bundle, CompiledGroup, CompiledSnippet, CompiledBlock, PropertyType, ScalarValue as ScalarValue$1, GameDataNodeKind, GameDataField } from '@patterkit/model';
 export { Bundle } from '@patterkit/model';
 
@@ -196,6 +197,88 @@ interface ChoiceOption {
  * are never stored or saved by this engine.
  */
 type WorldResolver = ScopeResolver;
+/** 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.
+ *
+ *  The reasoning is IN the entry, not implied by it. `select` carries every child it looked at
+ *  with its own verdict, the way a deal in the Storylet Engine carries every card it considered.
+ *  A log that recorded only the winner would answer "what happened" and not "why", and "why"
+ *  is the question a dialogue author cannot otherwise answer: the line you expected is missing
+ *  and nothing anywhere says which condition dropped it.
+ *
+ *  Patter's vocabulary, not the Storylet Engine's: there are no cards or hands here. The
+ *  structure is shared (an ordered retained log, `seq`, a flow-level and an engine-level tap);
+ *  the events are this engine's own. */
+type TraceEvent = {
+    type: "select";
+    /** The group whose children were being chosen among. */
+    group: string;
+    /** `branch` | `sequence` | `run` | `choice`, and for `sequence` its order/exhaust policy. */
+    selector: string;
+    order?: string;
+    exhaust?: string;
+    /** Every child considered, in authored order, each with why it was or was not takeable. */
+    children: {
+        id: string;
+        eligible: boolean;
+    }[];
+    /** The child selected, or null when nothing was takeable. */
+    picked: string | null;
+} | {
+    type: "choice";
+    group: string;
+    /** Every option the group offered, with the ones a condition dropped marked. */
+    options: {
+        id: string;
+        eligible: boolean;
+    }[];
+}
+/** A choice the player answered. `option` is what they took. */
+ | {
+    type: "chose";
+    group: string;
+    option: string;
+}
+/** A choice with no takeable option and no eligible fallback, which falls through
+ *  silently. Also reported through `onDryChoice`, which stays: a log is an audit read
+ *  afterwards, that callback is live feedback a host acts on. */
+ | {
+    type: "dry";
+    group: string;
+} | {
+    type: "jump";
+    to: string;
+    mode: "jump" | "call";
+}
+/** One landed effect; `prev` is the value it replaced, so a reader can say "0 -> 1". */
+ | {
+    type: "write";
+    target: string;
+    value: ScalarValue;
+    prev?: ScalarValue;
+}
+/** An expression that would not evaluate: never a silent pass, always visible. */
+ | {
+    type: "diagnostic";
+    where: 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;
+/** A retained entry: the event plus its place in flow time. `seq` is monotonic across the
+ *  flow and survives clearLog, so two reads of the log agree about order. */
+type LogEntry = TraceEvent & {
+    seq: number;
+    scene?: string;
+};
+/** One entry on the ENGINE's log: the same event plus the flow it happened in. A run is
+ *  several flows over shared state, so "what happened in this run" is only answerable in one
+ *  ordered stream, and only if each line says who. */
+type EngineLogEntry = LogEntry & {
+    flow: string;
+};
 interface EngineOptions {
     /**
      * Custom float-in-[0,1) source for `random()` / shuffle, shared by all flows.
@@ -227,17 +310,11 @@ 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;
-}
-/** One shared `@patter` property, for a live state inspector: its ref, declared type, current value,
- *  declared default (for reset), and enum options. Mirrors the Unity / Godot ports' ListProperties. */
-interface PropertyRow {
-    ref: string;
-    type: PropertyType;
-    value: ScalarValue | undefined;
-    default: ScalarValue;
-    values?: string[];
-    /** A quality's ordered stage ladder (lets an inspector offer stages instead of free text). */
-    stages?: string[];
+    /** 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
+     *  with the log off - it is live feedback, not an audit read afterwards. */
+    log?: boolean;
 }
 /** Options for opening a flow. */
 interface OpenFlowOptions {
@@ -256,6 +333,10 @@ interface SelectorState {
 }
 /** 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. */
+    logEnabled: 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;
     /** IDs-only build (`localisation.mode === "ids"`, no source-debug): the engine emits each beat's ID as
      *  its text and omits character display names, leaving localisation to the game (use `flow.interpolate`
@@ -293,7 +374,11 @@ interface FlowHost {
     /** Shared selector cursors (node id -> SelectorState) for `shared` memoried selectors. */
     sharedSelectors: Map<string, SelectorState>;
     /** Shared, scene-namespaced `@scene` bags (scene id -> name -> value) for shared scene props. */
-    stageBags: Map<string, Record<string, ScalarValue>>;
+    /** Per-scene SHARED scene props. A PropertyBag rather than a bare record since
+     *  2026-09-02: seeding, name normalisation and the mutable-default clone were all
+     *  written out by hand here, and the shared bag already had them. The SAVE is
+     *  unchanged - bag.save() is a bare record, which is what the envelope carries. */
+    stageBags: Map<string, PropertyBag>;
     customRng?: () => number;
     /** Play a chosen option's prompt as its first beat (spec §5); default false. */
     replayPromptOnChoose?: boolean;
@@ -337,6 +422,10 @@ declare class Engine {
     /** 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. */
     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;
+    private readonly engineTraceHandlers;
     constructor(bundle: Bundle, options?: EngineOptions);
     /** The active locale (string + character-name lookups resolve in it). */
     get locale(): string;
@@ -496,6 +585,17 @@ declare class Engine {
     setProperty(ref: string, value: ScalarValue): void;
     /** The shared `@patter` properties, for a live state inspector: each with its ref, type, current
      *  value, declared default (for reset), and enum options. Mirrors the Unity / Godot ports. */
+    /** The run's decisions, in order, each naming the flow it happened in. Empty unless the
+     *  run was opened with `log: true`. A flow's own log stays flow-local; this is the only
+     *  place a story spanning several flows reads as one sequence. */
+    log(): readonly EngineLogEntry[];
+    /** Drop the retained entries. `seq` does NOT restart: two reads of a log either side of a
+     *  clear still agree about what came first. */
+    clearLog(): void;
+    /** Live tap on the run's decisions, for tooling that wants them as they happen rather than
+     *  retained. Returns its own unsubscribe. */
+    onTrace(handler: EngineTraceHandler): () => void;
+    private emitEngine;
     listProperties(): PropertyRow[];
     private splitShared;
     /** Snapshot shared `@patter` state only (for a unified cross-engine save blob, Phase D). */
@@ -530,10 +630,14 @@ declare class Flow {
     private selectors;
     /** Per-node entry counts for this flow (node id -> times entered). */
     private visitCounts;
+    /** This flow's per-scene LOCAL scene props; see FlowHost.stageBags. */
     private sceneBags;
     private readonly patterResolver;
     private readonly sceneResolver;
     private readonly evalCtx;
+    private readonly flowLog;
+    /** Monotonic across the flow's life; survives clearLog so two reads agree on order. */
+    private flowSeq;
     constructor(id: string, host: FlowHost, seed: number);
     /** 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). */
@@ -599,6 +703,15 @@ declare class Flow {
      */
     private settle;
     /** The options of a pending choice (empty when not at a choice point). */
+    /** This flow's decisions, in order. Empty unless the run was opened with `log: true`.
+     *  The engine's log carries the same events tagged with the flow; this one is what a
+     *  single conversation reads as. */
+    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. */
+    private emit;
     getChoices(): ChoiceOption[];
     /** Pick an eligible option by id; the next `advance()` runs it. */
     choose(id: string): void;
@@ -887,4 +1000,4 @@ declare function effectiveGameData(fields: GameDataField[], node: GameData | und
  */
 declare function buildTagIndex(bundle: Bundle): Map<string, string[]>;
 
-export { type AddressSummary, type AdvanceToStopResult, type BeatInfo, type BundleCounts, type BundleDescription, type BundleIdentity, type ChoiceOption, Engine, type EngineOptions, type EngineSave, type FlatBeat, Flow, type FlowSnapshot, type GameDataFieldSummary, type GameDataSummary, type HostScopeSummary, type OpenFlowOptions, type OutlineBlock, type OutlineNode, type OutlineScene, type OwnedProperties, type PropertyRow, type PropertySummary, type SaveGame, type SavedChoice, type SelectorSnapshot, type StackFrame, type StepResult, type WorldResolver, buildTagIndex, describeBundle, effectiveGameData, gameDataFields, gameDataValue };
+export { type AddressSummary, type AdvanceToStopResult, type BeatInfo, type BundleCounts, type BundleDescription, type BundleIdentity, type ChoiceOption, Engine, type EngineLogEntry, type EngineOptions, type EngineSave, type EngineTraceHandler, type FlatBeat, Flow, type FlowSnapshot, type GameDataFieldSummary, type GameDataSummary, type HostScopeSummary, type LogEntry, type OpenFlowOptions, type OutlineBlock, type OutlineNode, type OutlineScene, type OwnedProperties, type PropertySummary, type SaveGame, type SavedChoice, type SelectorSnapshot, type StackFrame, type StepResult, type TraceEvent, type TraceHandler, type WorldResolver, buildTagIndex, describeBundle, effectiveGameData, gameDataFields, gameDataValue };