@patterkit/runtime 0.12.1 → 0.14.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { ScalarValue } from '@wildwinter/expr';
-import { ScopeResolver, ScopeRegistry, ScopeDeclaration, PropertyBag, LogMount, PropertyRow } from '@wildwinter/scoperegistry';
+import { ScopeResolver, ScopeRegistry, PropertyBag, ScopeDeclaration, LogMount, PropertyRow } from '@wildwinter/scoperegistry';
 export { PropertyRow } from '@wildwinter/scoperegistry';
-import { GameData, Bundle, CompiledGroup, CompiledSnippet, CompiledBlock, FlowSnapshot, EngineSave, SaveGame, PropertyType, ScalarValue as ScalarValue$1, GameDataNodeKind, GameDataField } from '@patterkit/model';
+import { GameData, Bundle, CompiledGroup, CompiledSnippet, CompiledBlock, FlowSnapshot, EngineSave, SaveGame, SaveGameV2, 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;
@@ -224,8 +224,18 @@ interface EngineOptions {
      *  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. Shared by all flows. */
+     *  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 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),
+     *  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
+     *  its own game: it self-backs `@world`, and `saveGame()` carries the registry's values too. */
+    registry?: ScopeRegistry;
     /**
      * Replay a chosen option's `prompt` as its first played beat (spec §5). Default `false`:
      * the prompt is a label only and `choose()` plays just the option's content. `true`: the
@@ -291,8 +301,14 @@ interface FlowHost {
     blockGameIdToId: Map<string, Map<string, string>>;
     /** Author tags (#215): node id -> accumulated tags (own + every ancestor's, deduped). Built once. */
     tagIndex: Map<string, string[]>;
-    /** The SHARED `@patter` globals (owned scope "patter") + world properties (`@world`). */
-    shared: ScopeRegistry;
+    /** The game's one registry: `@patter` (the SHARED globals), host scopes, every instance bag. */
+    registry: ScopeRegistry;
+    /** True when the engine made the registry (a standalone game): `saveGame()` then carries its values. */
+    readonly ownsRegistry: boolean;
+    /** The SHARED `@patter` globals' bag, registered under `patter`. */
+    patterBag: PropertyBag;
+    /** Host scopes this engine self-backed and registered (the game bound none, nobody else had). */
+    hostScopes: string[];
     /** Decls for the shared `@patter` globals - (re)seed on `engine.reset()`. */
     patterSharedDecls: ScopeDeclaration[];
     /** Decls for the per-flow `@patter` globals - seed each flow's local registry. */
@@ -305,11 +321,8 @@ interface FlowHost {
     sharedVisits: Map<string, number>;
     /** 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. */
-    /** 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. */
+    /** Per-scene SHARED scene props, each registered under `keys.stage(sceneId)`. Made the first time any
+     *  flow needs the scene, so a bag loaded before then waits in the registry and is claimed here. */
     stageBags: Map<string, PropertyBag>;
     customRng?: () => number;
     /** Play a chosen option's prompt as its first beat (spec §5); default false. */
@@ -327,12 +340,13 @@ 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;
-    /** Memoised `splitRef` results (ref string -> {scope,name}). The split depends only on `shared`'s scope
-     *  set, which is fixed for the engine's life, so every effect target / `{@ref}` slot parses once. */
+    /** 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, {
         scope: string;
         name: string;
     }>;
+    refSplitRevision: number;
 }
 declare class Engine {
     private readonly host;
@@ -390,10 +404,12 @@ declare class Engine {
      * content-drift policy (§9.8) resolves edits under the cursor: stack frames re-find their next
      * child by id, drifted options drop, a vanished snippet is skipped.
      *
-     * Returns the REPLACEMENT engine; this one is left untouched and should be discarded. Hosts
-     * re-bind their flow handles via `next.getFlow(id)`. If the restore throws (defensive - §9.8
-     * makes this unreachable for ordinary edits), the swap falls back to a cold engine with each
-     * saved flow restarted from the top of the scene it was in.
+     * Returns the REPLACEMENT engine, on the same registry. This one hands its bags over (each is
+     * removed from the registry with its values kept, and the replacement claims them as it
+     * registers), its flows are closed, and it should be discarded. Hosts re-bind their flow handles
+     * via `next.getFlow(id)`. If the restore throws (defensive - §9.8 makes this unreachable for
+     * ordinary edits), the swap falls back to a fresh engine with each saved flow restarted from the
+     * top of the scene it was in; the shared properties carry over.
      */
     hotSwap(bundle: Bundle): Engine;
     /** Whether closed captions are currently shown (full dialogue text). */
@@ -444,6 +460,11 @@ declare class Engine {
      * fetch it with `engine.getFlow(name)?.getChoices()`.
      */
     runFlow(flow: string, scene: string, block?: string): AdvanceToStopResult["played"];
+    /** Content that names another engine's scope (`@story.act`) runs only where that engine is on this
+     *  registry: without it every read would answer false and every write fail, so the flow is refused as
+     *  it opens (or the save as it loads), before anything changes. By then a game has built all of its
+     *  engines, whatever order it built them in. The same message on every runtime. */
+    private assertExternalScopes;
     /** Resolve a scene reference (a gameId address OR an internal id) to its internal id. */
     private resolveSceneRef;
     /** Resolve a block reference (a scene-scoped gameId OR an internal id) to its internal id. */
@@ -523,9 +544,18 @@ declare class Engine {
      * After reset, open fresh flows with `openFlow`.
      */
     reset(): void;
+    /** Remove every bag this engine registered, keeping the values parked when `keep` (a live reload
+     *  handing its state to a replacement), and close its flows. The engine is inert afterwards. */
+    private release;
     /** Read a shared (`@patter` / foreign) property by ref. `@scene` refs are rejected (flow-level). */
     getProperty(ref: string): ScalarValue | undefined;
-    /** Write a shared (`@patter` / foreign) property by ref. `@scene` refs are rejected (flow-level). */
+    /** Write a shared (`@patter` / foreign) property by ref. `@scene` refs are rejected (flow-level).
+     *
+     *  This is the GAME's surface, so it writes with host authority: a host-scope declaration's
+     *  `writable: false` is the story's promise not to write the value, never a lock on the game that
+     *  owns it. The story's own writes come through `Flow.runEffects`, which never claims it. (Ruled
+     *  across the family 2026-09-05, after a Storylets venue clock and this project's coverage driver
+     *  were each refused the one property they existed to move.) */
     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. */
@@ -542,19 +572,33 @@ declare class Engine {
     private emitEngine;
     listProperties(): PropertyRow[];
     private splitShared;
-    /** Snapshot shared `@patter` state only (for a unified cross-engine save blob, Phase D). */
+    /** The shared `@patter` values alone, as `{ patter: {...} }`.
+     *  @deprecated The registry holds every property now: a game saves `registry.save()` once, and a
+     *  standalone engine's `saveGame()` carries its registry's values. Removed at the next breaking release. */
     save(): EngineSave;
-    /** Restore shared `@patter` values (world properties untouched). */
+    /** Lay a `{ patter: {...} }` section over the shared `@patter` values; anything else is ignored.
+     *  @deprecated See `save`. Removed at the next breaking release. */
     load(blob: EngineSave): void;
-    /** Snapshot the whole game: shared `@patter` + visit counts + every live flow. */
+    /** Snapshot the whole game's NON-property state: visit counts, shared selector cursors, and every
+     *  live flow's cursor and PRNG. The property values are the registry's: a standalone engine (one that
+     *  made its own registry) carries them here under `registry`; a game that passed a registry saves it
+     *  once itself, beside each engine's `saveGame()`. */
     saveGame(): SaveGame;
-    /** Restore a `saveGame()`: shared globals + visit counts + shared scene bags + reconstruct every flow. */
-    loadGame(save: SaveGame): void;
+    /**
+     * Restore a `saveGame()`: visit counts, shared selector cursors, and every flow. Property values come
+     * from the registry. A save that carries them (a standalone engine's, or a version 2 save from before
+     * the registry held them) has them moved into the registry here; otherwise the game loads its
+     * registry itself, before or after this call. Either order works: this engine's bags are handed back
+     * to the registry (values kept) and the restored flows claim them as they register.
+     */
+    loadGame(save: SaveGame | SaveGameV2): void;
 }
 declare class Flow {
     readonly id: string;
     private readonly host;
     private local;
+    /** The registry keys this flow has registered (its globals and each scene bag). */
+    private readonly registered;
     private rngState;
     private started;
     private flowEnded;
@@ -579,10 +623,14 @@ declare class Flow {
     private readonly patterResolver;
     private readonly sceneResolver;
     private readonly evalCtx;
+    private ctxRevision;
+    private registryQualities;
     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 eval context, its scopes refreshed if the registry's set of scopes has moved since. */
+    private context;
     /** 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;
@@ -668,9 +716,14 @@ declare class Flow {
     isEnded(): boolean;
     /** Read a property by ref - `@patter` / `@scene` (each routed by its `shared` flag) or foreign. */
     getProperty(ref: string): ScalarValue | undefined;
-    /** Write a property by ref (routed by scope, then by the property's `shared` flag). */
+    /** Write a property by ref (routed by scope, then by the property's `shared` flag). The GAME's
+     *  surface: it writes with host authority, so a `writable: false` host declaration does not refuse
+     *  it (see `Engine.setProperty`). The story's writes go through `writeProperty` instead. */
     setProperty(ref: string, value: ScalarValue): void;
-    /** @internal Snapshot this flow's cursor + per-flow scopes (not-shared `@patter`/`@scene`) + PRNG. */
+    /** The write itself. `host` says WHO is writing, which is the only thing `writable: false` cares
+     *  about: the story is refused, the game is not. */
+    private writeProperty;
+    /** @internal Snapshot this flow's cursor + PRNG + visits. Its properties are the registry's. */
     snapshot(): FlowSnapshot;
     /** @internal Restore this flow from a snapshot. */
     restore(snap: FlowSnapshot): void;
@@ -782,10 +835,20 @@ declare class Flow {
      *  locale, else the authoring `displayName`. Undefined when the character has no display name at all
      *  (the host falls back to the `character` token itself). */
     private resolveCharacterName;
-    /** Split a ref into scope + name. Tokens: `@scene`, foreign tokens, else `@patter` (incl. bare `@name`). */
+    /** Split a ref into scope + name. Tokens: `@scene`, registered tokens, else `@patter` (incl. bare `@name`). */
     private splitRef;
-    /** The per-flow registry: the NOT-shared `@patter` globals (the shared ones live on the host). */
-    private freshLocal;
+    /** A fresh, unregistered bag for the NOT-shared `@patter` globals (the shared ones live on the host). */
+    private newLocal;
+    /** Register a fresh globals bag under this flow's key; it claims any values waiting there. */
+    private mountLocal;
+    /** @internal Remove every bag this flow registered; with `keep`, their values wait in the registry for
+     *  the flow that replaces this one. Engine-driven (close, loadGame, hotSwap). */
+    releaseBags(keep: boolean): void;
+    /** The bag a `@scene` property of scene `s` lives in (stage or this flow's), made if missing. */
+    private sceneBagFor;
+    /** Make (and register) scene `s`'s stage bag and this flow's bag for it, if not made yet. A bag made
+     *  here claims whatever values the registry holds for its key: that is how a loaded save reaches it. */
+    private ensureSceneBags;
     /**
      * Seed a scene's `@scene` props (spec §7). The not-shared props seed THIS flow's
      * bag the first time it enters (persist across re-entries thereafter); the shared

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { ScalarValue } from '@wildwinter/expr';
-import { ScopeResolver, ScopeRegistry, ScopeDeclaration, PropertyBag, LogMount, PropertyRow } from '@wildwinter/scoperegistry';
+import { ScopeResolver, ScopeRegistry, PropertyBag, ScopeDeclaration, LogMount, PropertyRow } from '@wildwinter/scoperegistry';
 export { PropertyRow } from '@wildwinter/scoperegistry';
-import { GameData, Bundle, CompiledGroup, CompiledSnippet, CompiledBlock, FlowSnapshot, EngineSave, SaveGame, PropertyType, ScalarValue as ScalarValue$1, GameDataNodeKind, GameDataField } from '@patterkit/model';
+import { GameData, Bundle, CompiledGroup, CompiledSnippet, CompiledBlock, FlowSnapshot, EngineSave, SaveGame, SaveGameV2, 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;
@@ -224,8 +224,18 @@ interface EngineOptions {
      *  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. Shared by all flows. */
+     *  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 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),
+     *  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
+     *  its own game: it self-backs `@world`, and `saveGame()` carries the registry's values too. */
+    registry?: ScopeRegistry;
     /**
      * Replay a chosen option's `prompt` as its first played beat (spec §5). Default `false`:
      * the prompt is a label only and `choose()` plays just the option's content. `true`: the
@@ -291,8 +301,14 @@ interface FlowHost {
     blockGameIdToId: Map<string, Map<string, string>>;
     /** Author tags (#215): node id -> accumulated tags (own + every ancestor's, deduped). Built once. */
     tagIndex: Map<string, string[]>;
-    /** The SHARED `@patter` globals (owned scope "patter") + world properties (`@world`). */
-    shared: ScopeRegistry;
+    /** The game's one registry: `@patter` (the SHARED globals), host scopes, every instance bag. */
+    registry: ScopeRegistry;
+    /** True when the engine made the registry (a standalone game): `saveGame()` then carries its values. */
+    readonly ownsRegistry: boolean;
+    /** The SHARED `@patter` globals' bag, registered under `patter`. */
+    patterBag: PropertyBag;
+    /** Host scopes this engine self-backed and registered (the game bound none, nobody else had). */
+    hostScopes: string[];
     /** Decls for the shared `@patter` globals - (re)seed on `engine.reset()`. */
     patterSharedDecls: ScopeDeclaration[];
     /** Decls for the per-flow `@patter` globals - seed each flow's local registry. */
@@ -305,11 +321,8 @@ interface FlowHost {
     sharedVisits: Map<string, number>;
     /** 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. */
-    /** 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. */
+    /** Per-scene SHARED scene props, each registered under `keys.stage(sceneId)`. Made the first time any
+     *  flow needs the scene, so a bag loaded before then waits in the registry and is claimed here. */
     stageBags: Map<string, PropertyBag>;
     customRng?: () => number;
     /** Play a chosen option's prompt as its first beat (spec §5); default false. */
@@ -327,12 +340,13 @@ 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;
-    /** Memoised `splitRef` results (ref string -> {scope,name}). The split depends only on `shared`'s scope
-     *  set, which is fixed for the engine's life, so every effect target / `{@ref}` slot parses once. */
+    /** 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, {
         scope: string;
         name: string;
     }>;
+    refSplitRevision: number;
 }
 declare class Engine {
     private readonly host;
@@ -390,10 +404,12 @@ declare class Engine {
      * content-drift policy (§9.8) resolves edits under the cursor: stack frames re-find their next
      * child by id, drifted options drop, a vanished snippet is skipped.
      *
-     * Returns the REPLACEMENT engine; this one is left untouched and should be discarded. Hosts
-     * re-bind their flow handles via `next.getFlow(id)`. If the restore throws (defensive - §9.8
-     * makes this unreachable for ordinary edits), the swap falls back to a cold engine with each
-     * saved flow restarted from the top of the scene it was in.
+     * Returns the REPLACEMENT engine, on the same registry. This one hands its bags over (each is
+     * removed from the registry with its values kept, and the replacement claims them as it
+     * registers), its flows are closed, and it should be discarded. Hosts re-bind their flow handles
+     * via `next.getFlow(id)`. If the restore throws (defensive - §9.8 makes this unreachable for
+     * ordinary edits), the swap falls back to a fresh engine with each saved flow restarted from the
+     * top of the scene it was in; the shared properties carry over.
      */
     hotSwap(bundle: Bundle): Engine;
     /** Whether closed captions are currently shown (full dialogue text). */
@@ -444,6 +460,11 @@ declare class Engine {
      * fetch it with `engine.getFlow(name)?.getChoices()`.
      */
     runFlow(flow: string, scene: string, block?: string): AdvanceToStopResult["played"];
+    /** Content that names another engine's scope (`@story.act`) runs only where that engine is on this
+     *  registry: without it every read would answer false and every write fail, so the flow is refused as
+     *  it opens (or the save as it loads), before anything changes. By then a game has built all of its
+     *  engines, whatever order it built them in. The same message on every runtime. */
+    private assertExternalScopes;
     /** Resolve a scene reference (a gameId address OR an internal id) to its internal id. */
     private resolveSceneRef;
     /** Resolve a block reference (a scene-scoped gameId OR an internal id) to its internal id. */
@@ -523,9 +544,18 @@ declare class Engine {
      * After reset, open fresh flows with `openFlow`.
      */
     reset(): void;
+    /** Remove every bag this engine registered, keeping the values parked when `keep` (a live reload
+     *  handing its state to a replacement), and close its flows. The engine is inert afterwards. */
+    private release;
     /** Read a shared (`@patter` / foreign) property by ref. `@scene` refs are rejected (flow-level). */
     getProperty(ref: string): ScalarValue | undefined;
-    /** Write a shared (`@patter` / foreign) property by ref. `@scene` refs are rejected (flow-level). */
+    /** Write a shared (`@patter` / foreign) property by ref. `@scene` refs are rejected (flow-level).
+     *
+     *  This is the GAME's surface, so it writes with host authority: a host-scope declaration's
+     *  `writable: false` is the story's promise not to write the value, never a lock on the game that
+     *  owns it. The story's own writes come through `Flow.runEffects`, which never claims it. (Ruled
+     *  across the family 2026-09-05, after a Storylets venue clock and this project's coverage driver
+     *  were each refused the one property they existed to move.) */
     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. */
@@ -542,19 +572,33 @@ declare class Engine {
     private emitEngine;
     listProperties(): PropertyRow[];
     private splitShared;
-    /** Snapshot shared `@patter` state only (for a unified cross-engine save blob, Phase D). */
+    /** The shared `@patter` values alone, as `{ patter: {...} }`.
+     *  @deprecated The registry holds every property now: a game saves `registry.save()` once, and a
+     *  standalone engine's `saveGame()` carries its registry's values. Removed at the next breaking release. */
     save(): EngineSave;
-    /** Restore shared `@patter` values (world properties untouched). */
+    /** Lay a `{ patter: {...} }` section over the shared `@patter` values; anything else is ignored.
+     *  @deprecated See `save`. Removed at the next breaking release. */
     load(blob: EngineSave): void;
-    /** Snapshot the whole game: shared `@patter` + visit counts + every live flow. */
+    /** Snapshot the whole game's NON-property state: visit counts, shared selector cursors, and every
+     *  live flow's cursor and PRNG. The property values are the registry's: a standalone engine (one that
+     *  made its own registry) carries them here under `registry`; a game that passed a registry saves it
+     *  once itself, beside each engine's `saveGame()`. */
     saveGame(): SaveGame;
-    /** Restore a `saveGame()`: shared globals + visit counts + shared scene bags + reconstruct every flow. */
-    loadGame(save: SaveGame): void;
+    /**
+     * Restore a `saveGame()`: visit counts, shared selector cursors, and every flow. Property values come
+     * from the registry. A save that carries them (a standalone engine's, or a version 2 save from before
+     * the registry held them) has them moved into the registry here; otherwise the game loads its
+     * registry itself, before or after this call. Either order works: this engine's bags are handed back
+     * to the registry (values kept) and the restored flows claim them as they register.
+     */
+    loadGame(save: SaveGame | SaveGameV2): void;
 }
 declare class Flow {
     readonly id: string;
     private readonly host;
     private local;
+    /** The registry keys this flow has registered (its globals and each scene bag). */
+    private readonly registered;
     private rngState;
     private started;
     private flowEnded;
@@ -579,10 +623,14 @@ declare class Flow {
     private readonly patterResolver;
     private readonly sceneResolver;
     private readonly evalCtx;
+    private ctxRevision;
+    private registryQualities;
     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 eval context, its scopes refreshed if the registry's set of scopes has moved since. */
+    private context;
     /** 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;
@@ -668,9 +716,14 @@ declare class Flow {
     isEnded(): boolean;
     /** Read a property by ref - `@patter` / `@scene` (each routed by its `shared` flag) or foreign. */
     getProperty(ref: string): ScalarValue | undefined;
-    /** Write a property by ref (routed by scope, then by the property's `shared` flag). */
+    /** Write a property by ref (routed by scope, then by the property's `shared` flag). The GAME's
+     *  surface: it writes with host authority, so a `writable: false` host declaration does not refuse
+     *  it (see `Engine.setProperty`). The story's writes go through `writeProperty` instead. */
     setProperty(ref: string, value: ScalarValue): void;
-    /** @internal Snapshot this flow's cursor + per-flow scopes (not-shared `@patter`/`@scene`) + PRNG. */
+    /** The write itself. `host` says WHO is writing, which is the only thing `writable: false` cares
+     *  about: the story is refused, the game is not. */
+    private writeProperty;
+    /** @internal Snapshot this flow's cursor + PRNG + visits. Its properties are the registry's. */
     snapshot(): FlowSnapshot;
     /** @internal Restore this flow from a snapshot. */
     restore(snap: FlowSnapshot): void;
@@ -782,10 +835,20 @@ declare class Flow {
      *  locale, else the authoring `displayName`. Undefined when the character has no display name at all
      *  (the host falls back to the `character` token itself). */
     private resolveCharacterName;
-    /** Split a ref into scope + name. Tokens: `@scene`, foreign tokens, else `@patter` (incl. bare `@name`). */
+    /** Split a ref into scope + name. Tokens: `@scene`, registered tokens, else `@patter` (incl. bare `@name`). */
     private splitRef;
-    /** The per-flow registry: the NOT-shared `@patter` globals (the shared ones live on the host). */
-    private freshLocal;
+    /** A fresh, unregistered bag for the NOT-shared `@patter` globals (the shared ones live on the host). */
+    private newLocal;
+    /** Register a fresh globals bag under this flow's key; it claims any values waiting there. */
+    private mountLocal;
+    /** @internal Remove every bag this flow registered; with `keep`, their values wait in the registry for
+     *  the flow that replaces this one. Engine-driven (close, loadGame, hotSwap). */
+    releaseBags(keep: boolean): void;
+    /** The bag a `@scene` property of scene `s` lives in (stage or this flow's), made if missing. */
+    private sceneBagFor;
+    /** Make (and register) scene `s`'s stage bag and this flow's bag for it, if not made yet. A bag made
+     *  here claims whatever values the registry holds for its key: that is how a loaded save reaches it. */
+    private ensureSceneBags;
     /**
      * Seed a scene's `@scene` props (spec §7). The not-shared props seed THIS flow's
      * bag the first time it enters (persist across re-entries thereafter); the shared