@storylet-studio/runtime 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { ScalarValue, ScopeResolver, ExprNode } from '@wildwinter/expr';
+import { ScalarValue, ScopeResolver, ExprNode, EvalContext } from '@wildwinter/expr';
 export { Prng, makePrng, shuffleInPlace } from '@wildwinter/expr';
-import { Bundle, FlowSave, LoadReport, Card, Expression, Deck, Box, Hand, HandTemplate, TagGroup, PropertyDecl, SaveEnvelope, PropertyType, ScalarValue as ScalarValue$1 } from '@storylet-studio/model';
-import { PropertyBag, PropertyRow } from '@wildwinter/scoperegistry';
+import { Bundle, FlowSave, LoadReport, Card, Expression, Deck, Box, Hand, HandTemplate, TagGroup, PropertyDecl, SaveEnvelope, SaveEnvelopeV1, PropertyType, ScalarValue as ScalarValue$1 } from '@storylet-studio/model';
+import { PropertyBag, ScopeRegistry, PropertyRow } from '@wildwinter/scoperegistry';
 export { PropertyRow } from '@wildwinter/scoperegistry';
 
 interface EngineOptions {
@@ -18,12 +18,25 @@ interface EngineOptions {
     };
     /**
      * The host's resolver for @world - the values the game owns and the
-     * story reads (and, where `set` is offered, writes). Omit it and the
-     * engine self-backs @world from the declared defaults. Engine-level,
-     * shared by all flows, never in saveGame(): the host saves its container
-     * once, each engine saves its own envelope (design/flows.md).
+     * story reads (and, where `set` is offered, writes). Engine-level, shared
+     * by all flows, never saved: the game keeps these values. Omit it and a
+     * standalone engine self-backs @world from the declared defaults, as a
+     * property its registry stores and saves. A game running several engines
+     * registers @world in its registry itself instead.
      */
     world?: ScopeResolver;
+    /**
+     * 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 (@story under `story`, every other bag
+     * under a key starting `storylets/`, and @world if `world` is passed),
+     * reads every other scope from it, and `saveGame()` leaves the property
+     * values to the game. @world is then the game's to register: owned if the
+     * registry should store it, foreign if the game keeps it. 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;
     /**
      * Diagnostics hook (opt-in, dev tooling only): fired when `openFlow` REPLACES
      * a flow that still had cards dealt, with the flow id and how many. The
@@ -133,7 +146,8 @@ type TraceEvent = {
     card: string;
     reason: TraceVerdict | "hand-condition" | "vanished";
 }
-/** Card and outcome gameIds. */
+/** Card and outcome gameIds; `outcome` is "" for a card with no outcomes,
+ *  played with none. */
  | {
     type: "play";
     card: string;
@@ -312,9 +326,24 @@ interface Internals {
      *  what the shared side WOULD hold without building a bag, which is what
      *  makes previewLoad pure. */
     sharedDecls: DeclSet;
-    /** The shared stores. Reassigned wholesale by loadGame/reset. */
+    /** The shared stores, registered in the registry for the engine's life.
+     *  Reseeded in place by reset and by a load that carries values. */
     shared: Partition;
-    /** @world: the host's resolver, or the self-backed bag's. */
+    /** The game's one registry (or the engine's own, when it is standalone). */
+    registry: ScopeRegistry;
+    /** True when the engine made the registry: `saveGame()` then carries its values. */
+    ownsRegistry: boolean;
+    /** True when the engine self-backed @world (standalone, no resolver bound). */
+    selfWorld: boolean;
+    /** Every OTHER scope in the registry, as an eval context sees it (instance
+     *  keys left out), rebuilt only when the registry's set of scopes moves. */
+    registryView: () => {
+        scopes: EvalContext["scopes"];
+        qualities: EvalContext["qualities"];
+    };
+    /** @world, read through the registry by name (the scope's own normalisation),
+     *  so a @world the game registered folded to lower case still answers the
+     *  names as authored. */
     worldResolver: ScopeResolver;
     /** The @world WRITE seam. `host` says the caller is the GAME's own surface -
      *  setProperty, the coverage harness, the CLI's --set - which the shared
@@ -347,10 +376,19 @@ declare class Engine {
      *  outlives reset/loadGame (the host's container is the host's). The
      *  self-backed resolver is rebuilt instead. */
     private readonly hostWorld?;
+    /** The options this engine was built with: hotSwap builds its replacement from them. */
+    private readonly creationOptions;
+    /** How to register each shared scope again, in registration order: a failed
+     *  hotSwap puts this engine back exactly as it was. */
+    private readonly sharedMounts;
     constructor(bundle: Bundle, opts?: EngineOptions);
-    /** Build the shared stores and the @world seam. `hostWorld` sticks for the
-     *  engine's lifetime; reset/loadGame rebuild the shared bags around it. */
+    /** Build the shared stores, register them and @world, and set up the @world
+     *  seam. Once, for the engine's life: reset and loads reseed the bags in
+     *  place, so the registry never sees them come and go. */
     private initShared;
+    /** Every shared bag back to its declared defaults, in place (the registry
+     *  keeps them registered), the self-backed @world included. */
+    private reseedShared;
     /** Quality ladders by scope for the eval channel (design/quality.md):
      *  world/story keyed by name; box/deck/value keyed by owner id then name.
      *  Built once - a bundle's declarations never change. Ladders are
@@ -361,6 +399,10 @@ declare class Engine {
      *  state; shared state is untouched. There is no default flow: "main" is
      *  a caller convention, not an engine rule. */
     openFlow(id: string, opts?: OpenFlowOptions): Flow;
+    /** openFlow, and loadGame's rebuild. `claim` says the new flow's bags take
+     *  the values the registry holds for them (a load); a fresh open is a reset
+     *  of that name, so anything waiting for it is discarded first. */
+    private open;
     getFlow(id: string): Flow | undefined;
     /** Every live flow, open order. */
     flows(): Flow[];
@@ -375,6 +417,11 @@ declare class Engine {
      *  self-backed @world included; a host-bound @world is the host's and is
      *  not touched). */
     reset(): void;
+    /** End the run: clear the log, close every flow, forget spent cards. Each
+     *  flow's bags leave the registry; `keepFlows` names the flows whose values
+     *  are kept there for the flow that replaces them (a load into the game's
+     *  registry). */
+    private dropRun;
     /** Cards a shared `redraw: "never"` has taken out of the world, by card id.
      *  The claim ledger is DERIVED from live boards and so needs no storage;
      *  this one is durable, so it rides the save's shared half. */
@@ -417,6 +464,12 @@ declare class Engine {
      *  carries no flow. It reaches the run log and the engine tap; there is
      *  nowhere else for it to go, and it fires only on a legacy address. */
     private diagnose;
+    /** Content that names another engine's scope (`@patter.visits`) 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, 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;
     /** The shared surface as examiner rows: @world (read through the
      *  resolver) then the shared partitions. Per-flow rows live on each Flow. */
     listProperties(): PropertyRow[];
@@ -426,9 +479,33 @@ declare class Engine {
     listBags(): BagMount[];
     /** Every flow's trace, one stream, each event tagged with its flow id. */
     subscribeTrace(handler: EngineTraceHandler): () => void;
-    /** The whole engine, one envelope: the shared partitions once, then
-     *  every live flow keyed by its id. @world is NEVER here - the host
-     *  saves its container, each engine saves its own envelope. */
+    /**
+     * Live bundle refresh: rebuild on an edited bundle with the whole run carried
+     * over, and return the replacement with the report its load produced.
+     *
+     * Standalone, that is a save and a load into a new engine, and this one is left
+     * untouched (discard it). With the game's registry the two cannot both hold the
+     * same keys, so this engine is spent afterwards (its flows closed, the
+     * replacement holding everything on the same registry): it carries its
+     * own values into the snapshot, steps out of the registry, and the replacement
+     * loads them the way a standalone save loads: so the report covers the
+     * properties the edit dropped, defaulted, or retyped, and a dropped property
+     * is dropped rather than kept. Values the game loaded that were still waiting
+     * for a flow of this engine carry across as they were, and nothing belonging
+     * to any other engine is touched. A save for another project is refused before
+     * anything moves; if the rebuild fails for any other reason, this engine takes
+     * its registrations back and is left exactly as it was.
+     */
+    hotSwap(bundle: Bundle, opts?: EngineOptions): {
+        engine: Engine;
+        report: LoadReport;
+    };
+    /** The whole engine's NON-property state, one envelope: the spent cards
+     *  once, then every live flow (board, clocks, cooldowns, PRNG, play log)
+     *  keyed by its id. The property values are the registry's: a standalone
+     *  engine (one that made its own registry) carries them here under
+     *  `registry`, self-backed @world included; a game that passed a registry
+     *  saves it once itself, beside each engine's envelope. */
     saveGame(): SaveEnvelope;
     /** ONE flow's blob, to park a visit that is walking away: the same shape
      *  the envelope carries per flow, and the same shape `openFlow`'s `restore`
@@ -441,7 +518,7 @@ declare class Engine {
      *  doing any of it (design/engine-server.md 4.9). Pure: nothing on this
      *  engine moves. A project mismatch is refused here exactly as `loadGame`
      *  refuses it - it is the one thing neither call will tolerate. */
-    previewLoad(envelope: SaveEnvelope): LoadReport;
+    previewLoad(envelope: SaveEnvelope | SaveEnvelopeV1): LoadReport;
     /** What `openFlow(id, { restore: saved })` would do to a flow of that name,
      *  without doing it: the same report shape, since a visit parked under one
      *  build and resumed under the next raises the same questions. Pure. */
@@ -450,10 +527,18 @@ declare class Engine {
      *  Handles held from before the load are closed and inert (Patter's
      *  rule); take fresh ones from getFlow()/flows().
      *
+     *  Property values come from the registry. An envelope that carries them
+     *  (a standalone engine's, or a version 1 envelope) has them walked, cleaned,
+     *  and moved into the registry here, over fresh defaults. Otherwise the game
+     *  loads its registry itself, before or after this call: each flow's bags
+     *  are handed back to the registry with their values, and the restored
+     *  flows claim them. The report then covers only what this envelope holds;
+     *  the registry's own load rule applies to the values.
+     *
      *  Returns the report `previewLoad` would have given for this envelope: the
      *  drift tolerance that makes a load forgiving is what hides its cost, so
      *  the cost comes back with the load whether or not anybody looked first. */
-    loadGame(envelope: SaveEnvelope): LoadReport;
+    loadGame(envelope: SaveEnvelope | SaveEnvelopeV1): LoadReport;
     private assertSameProject;
     /** The whole-envelope walk: the report, and the cleaned state the apply
      *  half writes. Nothing here touches the engine, which is what lets
@@ -481,8 +566,12 @@ declare class Flow {
     private lastPlayOf;
     private tagPlayCount;
     private lastPlayInTag;
-    /** The per-flow property partitions (the not-shared halves). */
+    /** The per-flow property partitions (the not-shared halves), each bag
+     *  that declares something registered under this flow's keys. */
     private stores;
+    private readonly registered;
+    /** This flow's bags that declare something, under their registry keys. */
+    private readonly bagKeys;
     private traceHandlers;
     private logEntries;
     private logSeq;
@@ -500,6 +589,15 @@ declare class Flow {
     close(): void;
     /** @internal */
     markClosed(): void;
+    /** @internal - take this flow's bags out of the registry; with `keep`, their
+     *  values wait there for the flow that replaces this one (a load into the
+     *  game's registry). Idempotent. */
+    releaseBags(keep: boolean): void;
+    /** @internal - the registry keys this flow holds right now. */
+    registeredKeys(): string[];
+    /** @internal - register this flow's bags (again): at construction, and when a
+     *  failed hotSwap hands them back. Each claims what the registry holds for it. */
+    mountBags(): void;
     private assertOpen;
     /** A box's current turn (schema 3.4), on THIS flow's clock. */
     turn(boxRef: string): number;
@@ -660,7 +758,16 @@ declare class Flow {
     outcomes(cardId: string, from: string): OutcomeView[];
     /** Apply an outcome (schema 3.7): the card must sit in a hand on the
      *  board (you never play a card from inside the deck). Throws before any
-     *  mutation on a gated-shut outcome or a bad write target. */
+     *  mutation on a gated-shut outcome or a bad write target.
+     *
+     *  A card with NO outcomes is played with none, named as "" (the
+     *  no-outcome-play brief, 2026-09-14): a masthead, a notice, a codex entry,
+     *  whose play means "shown". It is everything a play is except the writes:
+     *  the play log and the history functions count it, the box's turn moves by
+     *  the usual rule, the redraw rests it and it leaves its hand. "" is the one
+     *  spelling in all four runtimes, because a Blueprint pin cannot be absent.
+     *  Only the empty-for-empty case is new: "" on a card that has outcomes is
+     *  refused, and a named outcome on a card with none is refused as before. */
     play(cardId: string, outcomeGameId: string, from: string, opts?: PlayOptions): void;
     /** One owned property's address, owner segment and all (4.4). */
     private address;
@@ -699,8 +806,9 @@ declare class Flow {
     getProperty(path: string): ScalarValue;
     setProperty(path: string, value: ScalarValue): void;
     private resolvePath;
-    /** @internal - this flow's blob inside the engine's envelope. */
-    snapshot(): FlowSave;
+    /** @internal - this flow's blob: inside the engine's envelope without its
+     *  properties (the registry has them), or parked whole by saveFlow. */
+    snapshot(withProps: boolean): FlowSave;
     /** @internal - restore a freshly opened flow from its blob (loadGame).
      *  Orphaned keys (deleted entities) drop; new declarations keep defaults. */
     restore(saved: FlowSave): void;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { ScalarValue, ScopeResolver, ExprNode } from '@wildwinter/expr';
+import { ScalarValue, ScopeResolver, ExprNode, EvalContext } from '@wildwinter/expr';
 export { Prng, makePrng, shuffleInPlace } from '@wildwinter/expr';
-import { Bundle, FlowSave, LoadReport, Card, Expression, Deck, Box, Hand, HandTemplate, TagGroup, PropertyDecl, SaveEnvelope, PropertyType, ScalarValue as ScalarValue$1 } from '@storylet-studio/model';
-import { PropertyBag, PropertyRow } from '@wildwinter/scoperegistry';
+import { Bundle, FlowSave, LoadReport, Card, Expression, Deck, Box, Hand, HandTemplate, TagGroup, PropertyDecl, SaveEnvelope, SaveEnvelopeV1, PropertyType, ScalarValue as ScalarValue$1 } from '@storylet-studio/model';
+import { PropertyBag, ScopeRegistry, PropertyRow } from '@wildwinter/scoperegistry';
 export { PropertyRow } from '@wildwinter/scoperegistry';
 
 interface EngineOptions {
@@ -18,12 +18,25 @@ interface EngineOptions {
     };
     /**
      * The host's resolver for @world - the values the game owns and the
-     * story reads (and, where `set` is offered, writes). Omit it and the
-     * engine self-backs @world from the declared defaults. Engine-level,
-     * shared by all flows, never in saveGame(): the host saves its container
-     * once, each engine saves its own envelope (design/flows.md).
+     * story reads (and, where `set` is offered, writes). Engine-level, shared
+     * by all flows, never saved: the game keeps these values. Omit it and a
+     * standalone engine self-backs @world from the declared defaults, as a
+     * property its registry stores and saves. A game running several engines
+     * registers @world in its registry itself instead.
      */
     world?: ScopeResolver;
+    /**
+     * 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 (@story under `story`, every other bag
+     * under a key starting `storylets/`, and @world if `world` is passed),
+     * reads every other scope from it, and `saveGame()` leaves the property
+     * values to the game. @world is then the game's to register: owned if the
+     * registry should store it, foreign if the game keeps it. 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;
     /**
      * Diagnostics hook (opt-in, dev tooling only): fired when `openFlow` REPLACES
      * a flow that still had cards dealt, with the flow id and how many. The
@@ -133,7 +146,8 @@ type TraceEvent = {
     card: string;
     reason: TraceVerdict | "hand-condition" | "vanished";
 }
-/** Card and outcome gameIds. */
+/** Card and outcome gameIds; `outcome` is "" for a card with no outcomes,
+ *  played with none. */
  | {
     type: "play";
     card: string;
@@ -312,9 +326,24 @@ interface Internals {
      *  what the shared side WOULD hold without building a bag, which is what
      *  makes previewLoad pure. */
     sharedDecls: DeclSet;
-    /** The shared stores. Reassigned wholesale by loadGame/reset. */
+    /** The shared stores, registered in the registry for the engine's life.
+     *  Reseeded in place by reset and by a load that carries values. */
     shared: Partition;
-    /** @world: the host's resolver, or the self-backed bag's. */
+    /** The game's one registry (or the engine's own, when it is standalone). */
+    registry: ScopeRegistry;
+    /** True when the engine made the registry: `saveGame()` then carries its values. */
+    ownsRegistry: boolean;
+    /** True when the engine self-backed @world (standalone, no resolver bound). */
+    selfWorld: boolean;
+    /** Every OTHER scope in the registry, as an eval context sees it (instance
+     *  keys left out), rebuilt only when the registry's set of scopes moves. */
+    registryView: () => {
+        scopes: EvalContext["scopes"];
+        qualities: EvalContext["qualities"];
+    };
+    /** @world, read through the registry by name (the scope's own normalisation),
+     *  so a @world the game registered folded to lower case still answers the
+     *  names as authored. */
     worldResolver: ScopeResolver;
     /** The @world WRITE seam. `host` says the caller is the GAME's own surface -
      *  setProperty, the coverage harness, the CLI's --set - which the shared
@@ -347,10 +376,19 @@ declare class Engine {
      *  outlives reset/loadGame (the host's container is the host's). The
      *  self-backed resolver is rebuilt instead. */
     private readonly hostWorld?;
+    /** The options this engine was built with: hotSwap builds its replacement from them. */
+    private readonly creationOptions;
+    /** How to register each shared scope again, in registration order: a failed
+     *  hotSwap puts this engine back exactly as it was. */
+    private readonly sharedMounts;
     constructor(bundle: Bundle, opts?: EngineOptions);
-    /** Build the shared stores and the @world seam. `hostWorld` sticks for the
-     *  engine's lifetime; reset/loadGame rebuild the shared bags around it. */
+    /** Build the shared stores, register them and @world, and set up the @world
+     *  seam. Once, for the engine's life: reset and loads reseed the bags in
+     *  place, so the registry never sees them come and go. */
     private initShared;
+    /** Every shared bag back to its declared defaults, in place (the registry
+     *  keeps them registered), the self-backed @world included. */
+    private reseedShared;
     /** Quality ladders by scope for the eval channel (design/quality.md):
      *  world/story keyed by name; box/deck/value keyed by owner id then name.
      *  Built once - a bundle's declarations never change. Ladders are
@@ -361,6 +399,10 @@ declare class Engine {
      *  state; shared state is untouched. There is no default flow: "main" is
      *  a caller convention, not an engine rule. */
     openFlow(id: string, opts?: OpenFlowOptions): Flow;
+    /** openFlow, and loadGame's rebuild. `claim` says the new flow's bags take
+     *  the values the registry holds for them (a load); a fresh open is a reset
+     *  of that name, so anything waiting for it is discarded first. */
+    private open;
     getFlow(id: string): Flow | undefined;
     /** Every live flow, open order. */
     flows(): Flow[];
@@ -375,6 +417,11 @@ declare class Engine {
      *  self-backed @world included; a host-bound @world is the host's and is
      *  not touched). */
     reset(): void;
+    /** End the run: clear the log, close every flow, forget spent cards. Each
+     *  flow's bags leave the registry; `keepFlows` names the flows whose values
+     *  are kept there for the flow that replaces them (a load into the game's
+     *  registry). */
+    private dropRun;
     /** Cards a shared `redraw: "never"` has taken out of the world, by card id.
      *  The claim ledger is DERIVED from live boards and so needs no storage;
      *  this one is durable, so it rides the save's shared half. */
@@ -417,6 +464,12 @@ declare class Engine {
      *  carries no flow. It reaches the run log and the engine tap; there is
      *  nowhere else for it to go, and it fires only on a legacy address. */
     private diagnose;
+    /** Content that names another engine's scope (`@patter.visits`) 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, 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;
     /** The shared surface as examiner rows: @world (read through the
      *  resolver) then the shared partitions. Per-flow rows live on each Flow. */
     listProperties(): PropertyRow[];
@@ -426,9 +479,33 @@ declare class Engine {
     listBags(): BagMount[];
     /** Every flow's trace, one stream, each event tagged with its flow id. */
     subscribeTrace(handler: EngineTraceHandler): () => void;
-    /** The whole engine, one envelope: the shared partitions once, then
-     *  every live flow keyed by its id. @world is NEVER here - the host
-     *  saves its container, each engine saves its own envelope. */
+    /**
+     * Live bundle refresh: rebuild on an edited bundle with the whole run carried
+     * over, and return the replacement with the report its load produced.
+     *
+     * Standalone, that is a save and a load into a new engine, and this one is left
+     * untouched (discard it). With the game's registry the two cannot both hold the
+     * same keys, so this engine is spent afterwards (its flows closed, the
+     * replacement holding everything on the same registry): it carries its
+     * own values into the snapshot, steps out of the registry, and the replacement
+     * loads them the way a standalone save loads: so the report covers the
+     * properties the edit dropped, defaulted, or retyped, and a dropped property
+     * is dropped rather than kept. Values the game loaded that were still waiting
+     * for a flow of this engine carry across as they were, and nothing belonging
+     * to any other engine is touched. A save for another project is refused before
+     * anything moves; if the rebuild fails for any other reason, this engine takes
+     * its registrations back and is left exactly as it was.
+     */
+    hotSwap(bundle: Bundle, opts?: EngineOptions): {
+        engine: Engine;
+        report: LoadReport;
+    };
+    /** The whole engine's NON-property state, one envelope: the spent cards
+     *  once, then every live flow (board, clocks, cooldowns, PRNG, play log)
+     *  keyed by its id. The property values are the registry's: a standalone
+     *  engine (one that made its own registry) carries them here under
+     *  `registry`, self-backed @world included; a game that passed a registry
+     *  saves it once itself, beside each engine's envelope. */
     saveGame(): SaveEnvelope;
     /** ONE flow's blob, to park a visit that is walking away: the same shape
      *  the envelope carries per flow, and the same shape `openFlow`'s `restore`
@@ -441,7 +518,7 @@ declare class Engine {
      *  doing any of it (design/engine-server.md 4.9). Pure: nothing on this
      *  engine moves. A project mismatch is refused here exactly as `loadGame`
      *  refuses it - it is the one thing neither call will tolerate. */
-    previewLoad(envelope: SaveEnvelope): LoadReport;
+    previewLoad(envelope: SaveEnvelope | SaveEnvelopeV1): LoadReport;
     /** What `openFlow(id, { restore: saved })` would do to a flow of that name,
      *  without doing it: the same report shape, since a visit parked under one
      *  build and resumed under the next raises the same questions. Pure. */
@@ -450,10 +527,18 @@ declare class Engine {
      *  Handles held from before the load are closed and inert (Patter's
      *  rule); take fresh ones from getFlow()/flows().
      *
+     *  Property values come from the registry. An envelope that carries them
+     *  (a standalone engine's, or a version 1 envelope) has them walked, cleaned,
+     *  and moved into the registry here, over fresh defaults. Otherwise the game
+     *  loads its registry itself, before or after this call: each flow's bags
+     *  are handed back to the registry with their values, and the restored
+     *  flows claim them. The report then covers only what this envelope holds;
+     *  the registry's own load rule applies to the values.
+     *
      *  Returns the report `previewLoad` would have given for this envelope: the
      *  drift tolerance that makes a load forgiving is what hides its cost, so
      *  the cost comes back with the load whether or not anybody looked first. */
-    loadGame(envelope: SaveEnvelope): LoadReport;
+    loadGame(envelope: SaveEnvelope | SaveEnvelopeV1): LoadReport;
     private assertSameProject;
     /** The whole-envelope walk: the report, and the cleaned state the apply
      *  half writes. Nothing here touches the engine, which is what lets
@@ -481,8 +566,12 @@ declare class Flow {
     private lastPlayOf;
     private tagPlayCount;
     private lastPlayInTag;
-    /** The per-flow property partitions (the not-shared halves). */
+    /** The per-flow property partitions (the not-shared halves), each bag
+     *  that declares something registered under this flow's keys. */
     private stores;
+    private readonly registered;
+    /** This flow's bags that declare something, under their registry keys. */
+    private readonly bagKeys;
     private traceHandlers;
     private logEntries;
     private logSeq;
@@ -500,6 +589,15 @@ declare class Flow {
     close(): void;
     /** @internal */
     markClosed(): void;
+    /** @internal - take this flow's bags out of the registry; with `keep`, their
+     *  values wait there for the flow that replaces this one (a load into the
+     *  game's registry). Idempotent. */
+    releaseBags(keep: boolean): void;
+    /** @internal - the registry keys this flow holds right now. */
+    registeredKeys(): string[];
+    /** @internal - register this flow's bags (again): at construction, and when a
+     *  failed hotSwap hands them back. Each claims what the registry holds for it. */
+    mountBags(): void;
     private assertOpen;
     /** A box's current turn (schema 3.4), on THIS flow's clock. */
     turn(boxRef: string): number;
@@ -660,7 +758,16 @@ declare class Flow {
     outcomes(cardId: string, from: string): OutcomeView[];
     /** Apply an outcome (schema 3.7): the card must sit in a hand on the
      *  board (you never play a card from inside the deck). Throws before any
-     *  mutation on a gated-shut outcome or a bad write target. */
+     *  mutation on a gated-shut outcome or a bad write target.
+     *
+     *  A card with NO outcomes is played with none, named as "" (the
+     *  no-outcome-play brief, 2026-09-14): a masthead, a notice, a codex entry,
+     *  whose play means "shown". It is everything a play is except the writes:
+     *  the play log and the history functions count it, the box's turn moves by
+     *  the usual rule, the redraw rests it and it leaves its hand. "" is the one
+     *  spelling in all four runtimes, because a Blueprint pin cannot be absent.
+     *  Only the empty-for-empty case is new: "" on a card that has outcomes is
+     *  refused, and a named outcome on a card with none is refused as before. */
     play(cardId: string, outcomeGameId: string, from: string, opts?: PlayOptions): void;
     /** One owned property's address, owner segment and all (4.4). */
     private address;
@@ -699,8 +806,9 @@ declare class Flow {
     getProperty(path: string): ScalarValue;
     setProperty(path: string, value: ScalarValue): void;
     private resolvePath;
-    /** @internal - this flow's blob inside the engine's envelope. */
-    snapshot(): FlowSave;
+    /** @internal - this flow's blob: inside the engine's envelope without its
+     *  properties (the registry has them), or parked whole by saveFlow. */
+    snapshot(withProps: boolean): FlowSave;
     /** @internal - restore a freshly opened flow from its blob (loadGame).
      *  Orphaned keys (deleted entities) drop; new declarations keep defaults. */
     restore(saved: FlowSave): void;