@patterkit/runtime 0.9.0 → 0.11.0

package/dist/index.d.cts

@@ -1,79 +1,11 @@
 import { ScalarValue } from '@wildwinter/expr';
-import { ScopeResolver, ScopeRegistry, ScopeDeclaration, PropertyBag, PropertyRow } from '@wildwinter/scoperegistry';
+import { ScopeResolver, ScopeRegistry, ScopeDeclaration, PropertyBag, LogMount, 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';
+import { GameData, Bundle, CompiledGroup, CompiledSnippet, CompiledBlock, FlowSnapshot, EngineSave, SaveGame, PropertyType, ScalarValue as ScalarValue$1, GameDataNodeKind, GameDataField } from '@patterkit/model';
+export { Bundle, EngineSave, FlowCursor, FlowSnapshot, SaveEnvelope, SaveGame, SavedChoice, SavedChoiceOption, SavedChoicePrompt, SelectorSnapshot, StackFrame } from '@patterkit/model';
 
 type SelectableNode = CompiledGroup | CompiledSnippet;
-/** A property-state snapshot: owned scope -> property name -> value. */
-type EngineSave = Record<string, Record<string, ScalarValue>>;
-/** Serialised `sequence` selector visit state for one group (spec §4 / §7). */
-interface SelectorSnapshot {
-    seq?: number;
-    bag?: string[];
-    last?: string;
-}
-/** One entry on a flow's continuation stack: a position within a container's children. */
-interface StackFrame {
-    sceneId: string;
-    /** A block id or a run-group id (both are sequential containers). */
-    containerId: string;
-    index: number;
-    /** SNAPSHOT-ONLY (never set on a live frame): the id of the child at `index` when the save was
-     *  taken. On restore the child is re-found by this id, so a save survives siblings being inserted,
-     *  removed, or reordered before the cursor (live bundle refresh / patched-game saves). Absent (an
-     *  older save, or a frame saved at its container's end) falls back to the raw `index`. */
-    nextId?: string;
-}
-/** The serialised cursor + scopes + PRNG of a single flow. */
-interface FlowSnapshot {
-    /** This flow's owned-scope values = the NOT-shared `@patter` globals (under token "patter"). */
-    scopes: EngineSave;
-    /** Per-scene NOT-shared `@scene` bags (scene id -> name -> value); persist across re-entries (spec §7). */
-    sceneBags: Record<string, Record<string, ScalarValue>>;
-    /** This flow's built-in PRNG position (mulberry32 state). */
-    rngState: number;
-    /** This flow's per-node entry counts (node id -> times entered by this flow). */
-    visits: Record<string, number>;
-    cursor: {
-        flowEnded: boolean;
-        currentSceneId: string | null;
-        /** The continuation stack (call frames + the active block run). */
-        stack: StackFrame[];
-        activeSnippetId: string | null;
-        beatIndex: number;
-        /** The pending choice's exact option set, REPLAYED on load (schema 9.3). */
-        pendingChoice: SavedChoice | null;
-        /** The chosen option owning a prompt still to be replayed (save taken between choose + advance).
-         *  Optional / absent in older saves -> no pending prompt. */
-        pendingPromptOwnerId?: string | null;
-        /** This flow's `sequence` selector cursors. */
-        selectors: Record<string, SelectorSnapshot>;
-    };
-}
-/**
- * A pending choice as saved: the option set the player was shown, restored
- * verbatim - re-deriving on load would re-evaluate conditions (consuming PRNG
- * draws a second time) and could mutate the choice under the player.
- */
-interface SavedChoice {
-    groupId: string;
-    options: ChoiceOption[];
-}
-/** A full resumable save-game: shared `@patter` state + every live flow. */
-interface SaveGame {
-    version: number;
-    /** Shared `@patter` globals (owned scope "patter"). */
-    shared: EngineSave;
-    /** World-wide per-node entry counts (node id -> times entered by any flow). */
-    sharedVisits: Record<string, number>;
-    /** Shared selector cursors (node id -> snapshot) for `shared` memoried selectors. */
-    sharedSelectors: Record<string, SelectorSnapshot>;
-    /** Shared, scene-namespaced `@scene` bags (scene id -> name -> value) - the shared scene props. */
-    stageBags: Record<string, Record<string, ScalarValue>>;
-    /** Each live flow's snapshot, keyed by flow id. */
-    flows: Record<string, FlowSnapshot>;
-}
+
 /** What `Flow.advance()` surfaces to the host at each stop. */
 type StepResult = {
     type: "line";
@@ -569,6 +501,18 @@ declare class Engine {
     getFlow(id: string): Flow | undefined;
     /** All currently-open flows. */
     flows(): Flow[];
+    /**
+     * The SHARED kernel bags with the path each answers to in a log: the `@patter` globals,
+     * and one per scene for the shared `@scene` props. Parity with the Storylet Engine's
+     * listBags of the same name - it is what a state logger mounts.
+     *
+     * A stage bag's log path is `@scene:<sceneId>.`, not the bag's own `@scene.`: a property
+     * is ADDRESSED relative to a flow's current scene, but a log spans scenes and has to say
+     * which one. That is why a mount may override the bag's prefix.
+     *
+     * loadGame() replaces every bag, so re-enumerate after a load.
+     */
+    listBags(): LogMount[];
     /** Close (remove) a flow. The flow object is FINISHED, not merely unregistered, so a host still
      *  holding it cannot keep advancing it into the shared world (see {@link Flow.close}). */
     closeFlow(id: string): void;
@@ -702,7 +646,12 @@ declare class Flow {
      * to its caller (call-return) or ends the flow.
      */
     private settle;
-    /** The options of a pending choice (empty when not at a choice point). */
+    /**
+     * THIS flow's own kernel bags: its not-shared `@patter` half and its per-scene `@scene`
+     * props, each prefixed with the flow id so one path space holds every flow. The shared
+     * halves are the Engine's listBags.
+     */
+    listBags(): LogMount[];
     /** 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. */
@@ -712,6 +661,7 @@ declare class Flow {
     /** 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;
+    /** 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. */
     choose(id: string): void;
@@ -1000,4 +950,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 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 };
+export { type AddressSummary, type AdvanceToStopResult, type BeatInfo, type BundleCounts, type BundleDescription, type BundleIdentity, 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 };

package/dist/index.d.ts

@@ -1,79 +1,11 @@
 import { ScalarValue } from '@wildwinter/expr';
-import { ScopeResolver, ScopeRegistry, ScopeDeclaration, PropertyBag, PropertyRow } from '@wildwinter/scoperegistry';
+import { ScopeResolver, ScopeRegistry, ScopeDeclaration, PropertyBag, LogMount, 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';
+import { GameData, Bundle, CompiledGroup, CompiledSnippet, CompiledBlock, FlowSnapshot, EngineSave, SaveGame, PropertyType, ScalarValue as ScalarValue$1, GameDataNodeKind, GameDataField } from '@patterkit/model';
+export { Bundle, EngineSave, FlowCursor, FlowSnapshot, SaveEnvelope, SaveGame, SavedChoice, SavedChoiceOption, SavedChoicePrompt, SelectorSnapshot, StackFrame } from '@patterkit/model';
 
 type SelectableNode = CompiledGroup | CompiledSnippet;
-/** A property-state snapshot: owned scope -> property name -> value. */
-type EngineSave = Record<string, Record<string, ScalarValue>>;
-/** Serialised `sequence` selector visit state for one group (spec §4 / §7). */
-interface SelectorSnapshot {
-    seq?: number;
-    bag?: string[];
-    last?: string;
-}
-/** One entry on a flow's continuation stack: a position within a container's children. */
-interface StackFrame {
-    sceneId: string;
-    /** A block id or a run-group id (both are sequential containers). */
-    containerId: string;
-    index: number;
-    /** SNAPSHOT-ONLY (never set on a live frame): the id of the child at `index` when the save was
-     *  taken. On restore the child is re-found by this id, so a save survives siblings being inserted,
-     *  removed, or reordered before the cursor (live bundle refresh / patched-game saves). Absent (an
-     *  older save, or a frame saved at its container's end) falls back to the raw `index`. */
-    nextId?: string;
-}
-/** The serialised cursor + scopes + PRNG of a single flow. */
-interface FlowSnapshot {
-    /** This flow's owned-scope values = the NOT-shared `@patter` globals (under token "patter"). */
-    scopes: EngineSave;
-    /** Per-scene NOT-shared `@scene` bags (scene id -> name -> value); persist across re-entries (spec §7). */
-    sceneBags: Record<string, Record<string, ScalarValue>>;
-    /** This flow's built-in PRNG position (mulberry32 state). */
-    rngState: number;
-    /** This flow's per-node entry counts (node id -> times entered by this flow). */
-    visits: Record<string, number>;
-    cursor: {
-        flowEnded: boolean;
-        currentSceneId: string | null;
-        /** The continuation stack (call frames + the active block run). */
-        stack: StackFrame[];
-        activeSnippetId: string | null;
-        beatIndex: number;
-        /** The pending choice's exact option set, REPLAYED on load (schema 9.3). */
-        pendingChoice: SavedChoice | null;
-        /** The chosen option owning a prompt still to be replayed (save taken between choose + advance).
-         *  Optional / absent in older saves -> no pending prompt. */
-        pendingPromptOwnerId?: string | null;
-        /** This flow's `sequence` selector cursors. */
-        selectors: Record<string, SelectorSnapshot>;
-    };
-}
-/**
- * A pending choice as saved: the option set the player was shown, restored
- * verbatim - re-deriving on load would re-evaluate conditions (consuming PRNG
- * draws a second time) and could mutate the choice under the player.
- */
-interface SavedChoice {
-    groupId: string;
-    options: ChoiceOption[];
-}
-/** A full resumable save-game: shared `@patter` state + every live flow. */
-interface SaveGame {
-    version: number;
-    /** Shared `@patter` globals (owned scope "patter"). */
-    shared: EngineSave;
-    /** World-wide per-node entry counts (node id -> times entered by any flow). */
-    sharedVisits: Record<string, number>;
-    /** Shared selector cursors (node id -> snapshot) for `shared` memoried selectors. */
-    sharedSelectors: Record<string, SelectorSnapshot>;
-    /** Shared, scene-namespaced `@scene` bags (scene id -> name -> value) - the shared scene props. */
-    stageBags: Record<string, Record<string, ScalarValue>>;
-    /** Each live flow's snapshot, keyed by flow id. */
-    flows: Record<string, FlowSnapshot>;
-}
+
 /** What `Flow.advance()` surfaces to the host at each stop. */
 type StepResult = {
     type: "line";
@@ -569,6 +501,18 @@ declare class Engine {
     getFlow(id: string): Flow | undefined;
     /** All currently-open flows. */
     flows(): Flow[];
+    /**
+     * The SHARED kernel bags with the path each answers to in a log: the `@patter` globals,
+     * and one per scene for the shared `@scene` props. Parity with the Storylet Engine's
+     * listBags of the same name - it is what a state logger mounts.
+     *
+     * A stage bag's log path is `@scene:<sceneId>.`, not the bag's own `@scene.`: a property
+     * is ADDRESSED relative to a flow's current scene, but a log spans scenes and has to say
+     * which one. That is why a mount may override the bag's prefix.
+     *
+     * loadGame() replaces every bag, so re-enumerate after a load.
+     */
+    listBags(): LogMount[];
     /** Close (remove) a flow. The flow object is FINISHED, not merely unregistered, so a host still
      *  holding it cannot keep advancing it into the shared world (see {@link Flow.close}). */
     closeFlow(id: string): void;
@@ -702,7 +646,12 @@ declare class Flow {
      * to its caller (call-return) or ends the flow.
      */
     private settle;
-    /** The options of a pending choice (empty when not at a choice point). */
+    /**
+     * THIS flow's own kernel bags: its not-shared `@patter` half and its per-scene `@scene`
+     * props, each prefixed with the flow id so one path space holds every flow. The shared
+     * halves are the Engine's listBags.
+     */
+    listBags(): LogMount[];
     /** 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. */
@@ -712,6 +661,7 @@ declare class Flow {
     /** 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;
+    /** 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. */
     choose(id: string): void;
@@ -1000,4 +950,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 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 };
+export { type AddressSummary, type AdvanceToStopResult, type BeatInfo, type BundleCounts, type BundleDescription, type BundleIdentity, 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 };

package/dist/index.js

@@ -463,6 +463,22 @@ var Engine = class _Engine {
   flows() {
     return [...this.flowsById.values()];
   }
+  /**
+   * The SHARED kernel bags with the path each answers to in a log: the `@patter` globals,
+   * and one per scene for the shared `@scene` props. Parity with the Storylet Engine's
+   * listBags of the same name - it is what a state logger mounts.
+   *
+   * A stage bag's log path is `@scene:<sceneId>.`, not the bag's own `@scene.`: a property
+   * is ADDRESSED relative to a flow's current scene, but a log spans scenes and has to say
+   * which one. That is why a mount may override the bag's prefix.
+   *
+   * loadGame() replaces every bag, so re-enumerate after a load.
+   */
+  listBags() {
+    const mounts = [{ bag: this.host.shared.ownedBag("patter") }];
+    for (const [sceneId, bag] of this.host.stageBags) mounts.push({ bag, pathPrefix: `@scene:${sceneId}.` });
+    return mounts;
+  }
   /** Close (remove) a flow. The flow object is FINISHED, not merely unregistered, so a host still
    *  holding it cannot keep advancing it into the shared world (see {@link Flow.close}). */
   closeFlow(id) {
@@ -902,7 +918,16 @@ var Flow = class {
       this.enterChild(children[frame.index++]);
     }
   }
-  /** The options of a pending choice (empty when not at a choice point). */
+  /**
+   * THIS flow's own kernel bags: its not-shared `@patter` half and its per-scene `@scene`
+   * props, each prefixed with the flow id so one path space holds every flow. The shared
+   * halves are the Engine's listBags.
+   */
+  listBags() {
+    const mounts = [{ bag: this.local.ownedBag("patter"), pathPrefix: `${this.id}/@patter.` }];
+    for (const [sceneId, bag] of this.sceneBags) mounts.push({ bag, pathPrefix: `${this.id}/@scene:${sceneId}.` });
+    return mounts;
+  }
   /** 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. */
@@ -921,6 +946,7 @@ var Flow = class {
     if (!this.host.logEnabled) return;
     this.flowLog.push({ ...event, seq: this.flowSeq++, ...scene ? { scene } : {} });
   }
+  /** The options of a pending choice (empty when not at a choice point). */
   getChoices() {
     return this.pendingChoice?.options ?? [];
   }