@storylet-studio/runtime 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { ScalarValue, ScopeResolver, ExprNode } from '@wildwinter/expr';
 export { Prng, makePrng, shuffleInPlace } from '@wildwinter/expr';
-import { Bundle, Card, Expression, Deck, Box, Hand, HandTemplate, TagGroup, PropertyDecl, FlowSave, SaveEnvelope, PropertyType, ScalarValue as ScalarValue$1 } from '@storylet-studio/model';
+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';
 export { PropertyRow } from '@wildwinter/scoperegistry';
 
@@ -38,6 +38,25 @@ interface EngineOptions {
 interface OpenFlowOptions {
     /** Seed for this flow's PRNG (defaults to the engine's `seed`). */
     seed?: number;
+    /**
+     * Open this flow AS IT WAS: a blob from `saveFlow`, applied to the freshly
+     * opened (or replaced) flow before the handle comes back
+     * (design/engine-server.md 4.1).
+     *
+     * An option on `openFlow` rather than a `Flow.restore` verb on purpose:
+     * restoring INTO a running flow is the trap hosts keep falling into
+     * (openFlow REPLACES), and "open this flow as it was" is one act. Drift is
+     * tolerated exactly as `loadGame` tolerates it, with one addition, because
+     * this restore lands in a LIVE engine: a shared card whose world copies are
+     * all held by the OTHER open flows is not put back, and is reported as
+     * `claimed-elsewhere`. Ask `previewFlowRestore` first to see that coming.
+     */
+    restore?: FlowSave;
+    /** Handed the `restore`'s LoadReport as it happens - the same report
+     *  `previewFlowRestore` returns for the same blob. Ignored without
+     *  `restore`; the report has nowhere else to go, since `openFlow` returns
+     *  the handle. */
+    onRestoreReport?: (report: LoadReport) => void;
 }
 /** A card view in a dealt hand or a peeked list. Carries NO outcome
  *  availability - ask `outcomes()` for current truth (schema 5). */
@@ -63,7 +82,8 @@ interface RankedList {
     cards: DealtCard[];
 }
 interface PlayOptions {
-    /** Turn advance override; default settings.playAdvancesTurns. */
+    /** Turn advance override; default settings.playAdvancesTurns, or 0 when the
+     *  card's box is timed (design/engine-server.md 4.8). */
     advanceTurns?: number;
 }
 /** Why a card did or did not make an ask, in availability order (schema 3.1). */
@@ -71,11 +91,18 @@ type TraceVerdict = "dealt" | "capped" | "cooldown" | "deck-gate" | "tags" | "co
 /** One event on the deal/play log - "why did Ambush at the ford get dealt
  *  here?" is answered by the ask event's per-card verdicts and keys. The
  *  verb is the event type, so a peek is distinguishable from a deal when
- *  reading a run back. */
+ *  reading a run back.
+ *
+ *  IDENTITY IS BY GAMEID throughout (design/engine-server.md 4.4). It was
+ *  mixed until then: `deal.hand` and `peek.box` were gameIds while
+ *  `evict.hand`, `play.card` and every `cards[].id` were internal ids, so
+ *  every consumer outside the engine - the Board, the four examiners, the
+ *  Live Link, a wire a kiosk reads - mapped one to the other itself. */
 type TraceEvent = {
     type: "deal";
     /** Hand gameId. */
     hand: string;
+    /** `id` is the card's GAMEID (design/engine-server.md 4.4). */
     cards: {
         id: string;
         verdict: TraceVerdict;
@@ -87,24 +114,31 @@ type TraceEvent = {
     /** Box gameId. */
     box: string;
     criteria: Record<string, string>;
+    /** `id` is the card's GAMEID (design/engine-server.md 4.4). */
     cards: {
         id: string;
         verdict: TraceVerdict;
         priority?: number;
         specificity?: number;
     }[];
-} | {
+}
+/** Hand and card gameIds. A card the build no longer has (`vanished`) has
+ *  no gameId left and is named by the id the board carried. */
+ | {
     type: "evict";
     hand: string;
     card: string;
     reason: TraceVerdict | "hand-condition" | "vanished";
-} | {
+}
+/** Card and outcome gameIds. */
+ | {
     type: "play";
     card: string;
     outcome: string;
     turn: number;
 }
-/** One landed outcome change; `path` is the resolved store location (a
+/** One landed outcome change; `path` is the resolved store location, in the
+ *  address grammar `getProperty` takes - the owner segment is its gameId (a
  *  routed @hand write shows where it actually went, schema 3.6). `prev`
  *  is the value it replaced, so a log can read "0 -> 1". */
  | {
@@ -153,8 +187,8 @@ interface CardEntry {
     deck: Deck<Expression>;
     box: Box<Expression>;
 }
-/** One kernel bag with its store path prefix (story / box.<id> / deck.<id>
- *  / hand.<id> / value.<id>): the state logger's mount surface
+/** One kernel bag with its store path prefix (story / box.<gameId> / deck.<gameId>
+ *  / hand.<gameId> / value.<gameId>): the state logger's mount surface
  *  (design/engine-runtimes.md 3.4 - the logger builds on the PropertyBag
  *  audit hook, so it needs the bags themselves, not just their rows).
  *  The Engine lists the shared bags, a Flow its own; the @world container
@@ -172,6 +206,50 @@ interface BoxView {
     title?: string;
     turn: number;
 }
+/** One side's five declaration lists, keyed by owner id where the scope has
+ *  owners. The bags are built from these; so is the load report's answer to
+ *  "what does this build declare that the save does not carry". */
+interface DeclSet {
+    story: PropertyDecl[];
+    box: Map<string, PropertyDecl[]>;
+    deck: Map<string, PropertyDecl[]>;
+    hand: Map<string, PropertyDecl[]>;
+    value: Map<string, PropertyDecl[]>;
+}
+/** The four owned property scopes: the ones whose address carries an owner
+ *  segment. `story` has no owner and `world` is the host's. */
+type OwnedScope = "box" | "deck" | "hand" | "value";
+/** The owner segment of a property address, both ways round
+ *  (design/engine-server.md 4.4).
+ *
+ * `gameId` is the segment the ADDRESS uses; `id` is the internal id everything
+ * inside the engine is keyed by - the bags, the save envelope, the ladders.
+ * Both maps are built in bundle order and a repeated gameId does NOT
+ * overwrite the first.
+ *
+ * Box, deck, hand and card gameIds are unique bundle-wide, so for three of the
+ * four scopes the segment is simply the gameId. A TAG's is unique only within
+ * its group, and a group's only within its box, so two boxes may each name a
+ * tag "docks": the value scope's segment is box-qualified,
+ * `value.<boxGameId>/<tagGameId>.<name>`, wherever a gameId repeats, and the
+ * short form is REFUSED there rather than resolved to the first in bundle
+ * order. `valueAddresses` in the model is the one definition of that rule -
+ * the Board draws these addresses from the bundle while the engine builds them
+ * from this index, and the two have to agree - and `repeated` is what it
+ * found, so a refusal can name the candidates.
+ *
+ * Two GROUPS in one box naming the same tag is the case the box qualifier
+ * cannot separate, and it is closing at the source rather than here (question
+ * 16, ruled 2026-09-06): the compiler warns that a tag gameId must be unique
+ * within its box, and refuses it from the next release. Until then the first
+ * in bundle order answers, as it always did.
+ */
+interface OwnerIndex {
+    gameId: Map<string, string>;
+    id: Map<string, string>;
+    repeated: Map<string, string[]>;
+}
+type OwnerIndexes = Record<OwnedScope, OwnerIndex>;
 /** One side's five stores (shared on the engine, per-flow on each flow). */
 interface Partition {
     story: PropertyBag;
@@ -199,6 +277,8 @@ interface Internals {
         hand: Hand<Expression>;
         box: Box<Expression>;
     }>;
+    /** The owner segment of a property address, both ways round (4.4). */
+    owners: OwnerIndexes;
     templatesById: Map<string, HandTemplate<Expression>>;
     groupsById: Map<string, {
         group: TagGroup;
@@ -223,17 +303,26 @@ interface Internals {
     hasShared: boolean;
     /** The per-flow halves of every declaration list, precomputed once: each
      *  new flow builds its bags from these. */
-    flowDecls: {
-        story: PropertyDecl[];
-        box: Map<string, PropertyDecl[]>;
-        deck: Map<string, PropertyDecl[]>;
-        hand: Map<string, PropertyDecl[]>;
-        value: Map<string, PropertyDecl[]>;
-    };
+    flowDecls: DeclSet;
+    /** The shared halves, the same way. Not used to build anything - the shared
+     *  bags are built straight from the bundle - but a load report has to say
+     *  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. */
     shared: Partition;
     /** @world: the host's resolver, or the self-backed bag's. */
     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
+     *  kernel lets past a `writable: false` (scoperegistry 0.6.0): that flag is
+     *  the story's promise, not the game's. The story's refusal is the
+     *  worldReadOnly table below, consulted before this seam is reached. A BOUND
+     *  resolver is opaque - it takes a name and a value and keeps whatever rule
+     *  the game has - so the flag only ever reaches the self-backed bag.
+     *  Undefined when @world cannot be written at all (a resolver bound with no
+     *  `set`). */
+    worldSet?: (name: string, value: ScalarValue, host?: boolean) => void;
     /** @world names declared `writable: false`: the story's promise, kept at
      *  runtime as the compiler keeps it at publish (Reboot.md 10). */
     worldReadOnly: Set<string>;
@@ -307,15 +396,24 @@ declare class Engine {
      *  Derived, which is what makes closeFlow and the openFlow replace release
      *  what a flow was holding: its board leaves the map with it. */
     sharedClaims(): Map<string, number>;
+    /** The same ledger with one name left out: what the REST of the world
+     *  holds, which is the question a resume under that name has to ask. */
+    private sharedClaimsExcept;
     /**
      * Read shared state by path: "world.x", "story.gold" (when shared),
-     * "box.b_x.heat" (when shared). A ref that resolves PER-FLOW throws,
+     * "box.village.heat" (when shared) - the owner segment is its GAMEID
+     * (design/engine-server.md 4.4). A ref that resolves PER-FLOW throws,
      * naming the fix - silently answering with some flow's copy (or a junk
      * default) was the bug Patter's engine.getProperty guard exists to stop.
      */
     getProperty(path: string): ScalarValue;
     setProperty(path: string, value: ScalarValue): void;
     private resolveShared;
+    /** The engine's own surface has no flow, so an engine-level diagnostic
+     *  carries the empty flow id - the same way a LoadReport's shared half
+     *  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;
     /** The shared surface as examiner rows: @world (read through the
      *  resolver) then the shared partitions. Per-flow rows live on each Flow. */
     listProperties(): PropertyRow[];
@@ -329,10 +427,40 @@ declare class Engine {
      *  every live flow keyed by its id. @world is NEVER here - the host
      *  saves its container, each engine saves its own 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`
+     *  option takes back (design/engine-server.md 4.1). Saving the whole
+     *  envelope to park one of four hundred players is wrong in cost and in
+     *  meaning. Throws for a name that is not open - a closed flow has nothing
+     *  left to save. */
+    saveFlow(id: string): FlowSave;
+    /** What `loadGame(envelope)` would do that is not a plain restore, without
+     *  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;
+    /** 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. */
+    previewFlowRestore(id: string, saved: FlowSave): LoadReport;
     /** Restore: shared state once, then every flow REBUILT from its blob.
      *  Handles held from before the load are closed and inert (Patter's
-     *  rule); take fresh ones from getFlow()/flows(). */
-    loadGame(envelope: SaveEnvelope): void;
+     *  rule); take fresh ones from getFlow()/flows().
+     *
+     *  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;
+    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
+     *  previewLoad and loadGame share it. */
+    private planLoad;
+    /** One flow's walk. `otherClaims` is the rest of the world's shared ledger
+     *  and is present only for a SINGLE-flow restore into a live engine: a
+     *  whole-envelope load rebuilds every flow from one consistent moment, so
+     *  there is nobody else to compete with. */
+    private planFlowRestore;
 }
 declare class Flow {
     readonly id: string;
@@ -432,6 +560,23 @@ declare class Flow {
     /** A peek's ask: raw criteria ({group gameId: tag gameId}), bindings only,
      *  no condition slot (schema 3.1; the boundary, Reboot 4). */
     private askForPeek;
+    /**
+     * Fill one hole from the property its value names: the hand that moves
+     * (design/engine-server.md 4.6).
+     *
+     * The semantics are `bindStateGroups`' below, word for word, applied per
+     * HOLE instead of per group: resolved at ask time, and a value naming no tag
+     * leaves the hole UNBOUND (a wildcard) with a diagnostic rather than dealing
+     * a silently empty hand. What is added is the `@hand` scope - the asking
+     * hand's OWN declared state, read here from the flow's merged view (the
+     * shared half under the flow's own, so a `shared: true` declaration moves
+     * the hole for every flow and a per-flow one moves it for this flow alone).
+     *
+     * Read BEFORE tag composition, which is the whole reason it is safe: the
+     * @hand bag a card sees is built from the bound tags, so resolving a hole
+     * from it would be circular. A hand's own declarations are not, so they are.
+     */
+    private fillHoleFromProperty;
     /**
      * Bind every `boundBy` group in the box from the property it names.
      *
@@ -477,7 +622,9 @@ declare class Flow {
      *  null for available. `trace` (when a subscriber exists) collects the
      *  per-card verdicts. */
     private runAsk;
-    /** Flip eligible-but-not-taken trace entries to "capped". */
+    /** Flip eligible-but-not-taken trace entries to "capped". `taken` is keyed
+     *  by GAMEID, as the trace rows are (4.4): the two must move together or
+     *  every dealt card silently reads as capped. */
     private capTrace;
     private view;
     private handCapacity;
@@ -512,6 +659,8 @@ declare class Flow {
      *  board (you never play a card from inside the deck). Throws before any
      *  mutation on a gated-shut outcome or a bad write target. */
     play(cardId: string, outcomeGameId: string, from: string, opts?: PlayOptions): void;
+    /** One owned property's address, owner segment and all (4.4). */
+    private address;
     /** Land one change in whichever partition declares the name: the flow's
      *  bag when the property is per-flow, the shared bag when it is shared -
      *  the union/partition invariant made executable. */
@@ -536,9 +685,14 @@ declare class Flow {
      *  Bundle order: world, story, then per-box / per-deck / per-hand /
      *  per-tag stores. */
     listProperties(): PropertyRow[];
-    /** Read by path: "world.x", "story.gold", "value.v_docks.danger",
-     *  "box.b_x.heat", "deck.k_main.n", "hand.h_board.owner" - the flow's
-     *  merged view, routed by the declaration's sharing. */
+    /** Read by path: "world.x", "story.gold", "value.docks.danger",
+     *  "box.village.heat", "deck.wares.n", "hand.the-elder.zone" - the flow's
+     *  merged view, routed by the declaration's sharing.
+     *
+     *  The owner segment is the entity's GAMEID, the name it is called by
+     *  everywhere else (4.4). Its internal id is accepted for this release and
+     *  earns a `diagnostic` naming the address to move to; the next lockstep
+     *  release refuses it. */
     getProperty(path: string): ScalarValue;
     setProperty(path: string, value: ScalarValue): void;
     private resolvePath;
@@ -562,6 +716,13 @@ interface BundleIdentity {
     /** "full" | "stripped": whether authoring metadata (titles) survived. */
     metadata: string;
 }
+/** One hole this hand fills from a property rather than with a tag: the hand
+ *  MOVES when that property is written (design/engine-server.md 4.6). `group`
+ *  is the tag group's gameId, `from` the reference exactly as authored. */
+interface MovableHole {
+    group: string;
+    from: string;
+}
 /** One hand: the deal() surface. `gameId` is the name deal() is called with. */
 interface HandSummary {
     gameId: string;
@@ -573,6 +734,16 @@ interface HandSummary {
     slots: number | "unbounded";
     /** The hand template's gameId; absent for a standalone (inline-rule) hand. */
     template?: string;
+    /**
+     * The holes filled from a property, in bundle order. Absent when the hand
+     * has none, which is the ordinary case.
+     *
+     * Reported because it is the one thing about a hand an integrator cannot see
+     * from its name: a movable hole means writing that property MOVES the hand,
+     * so it is the difference between a fixed kiosk and a performer who walks
+     * about. `setProperty` is the whole verb; there is no other.
+     */
+    movable?: MovableHole[];
 }
 /** One tag group and its tags, by gameId: the peek() criteria surface (a
  *  criteria entry is `{ [group gameId]: tag gameId }`). */
@@ -588,6 +759,19 @@ interface BoxSummary {
     ranking: {
         specificity: boolean;
     };
+    /** Present on a TIMED box (design/engine-server.md 4.8): how long one of
+     *  its turns lasts. An integrator reading a bundle needs it to know which
+     *  boxes their host must tick, and how often. Absent is the ordinary box. */
+    turn?: {
+        seconds: number;
+    };
+    /** How many cards in this box are DURABLE (design/engine-server.md 4.2):
+     *  their `redraw: "never"` spend outlives the run, and a server has to lift
+     *  and restore it. A count rather than a list, like every other number here:
+     *  an integrator needs to know whether this box has any such cards at all,
+     *  and which ones is the authoring tool's question. Absent when there are
+     *  none, which is the ordinary bundle. */
+    durableCards?: number;
     tagGroups: TagGroupSummary[];
     counts: {
         decks: number;
@@ -604,6 +788,11 @@ interface PropertySummary {
     default: ScalarValue$1;
     /** Enum / flags options, where declared. */
     values?: string[];
+    /** Declared DURABLE (design/engine-server.md 4.2): the value survives a run,
+     *  and a server lifts and restores it across one. The engine never reads it;
+     *  it is reported because it is the difference between a value an integrator
+     *  may reset and one somebody is going to expect back. Absent = run-scoped. */
+    durable?: true;
     purpose?: string;
 }
 /** The scope a declaration block belongs to. `tag` declarations compose into
@@ -634,6 +823,9 @@ interface MapSummary {
     group: string;
     zones: number;
     backgrounds: number;
+    /** Placed hands standing on this map (design/engine-server.md 4.3): where the
+     *  kiosks are, in a bundle that carries geometry at all. */
+    sites: number;
 }
 /** What a bundle offers a host, read from the asset alone. */
 interface BundleDescription {
@@ -663,4 +855,4 @@ interface BundleDescription {
  *  throughout; the same shape every runtime returns. */
 declare function describeBundle(bundle: Bundle): BundleDescription;
 
-export { type BagMount, type BoxSummary, type BoxView, type BundleDescription, type BundleIdentity, type DealtCard, Engine, type EngineLogEntry, type EngineOptions, type EngineTraceHandler, Flow, type HandSummary, type LogEntry, type MapSummary, type OpenFlowOptions, type OutcomeView, type PlayOptions, type PropertyScopeKind, type PropertyScopeSummary, type PropertySummary, type RankedList, type TagGroupSummary, type TraceEvent, type TraceHandler, type TraceVerdict, describeBundle };
+export { type BagMount, type BoxSummary, type BoxView, type BundleDescription, type BundleIdentity, type DealtCard, Engine, type EngineLogEntry, type EngineOptions, type EngineTraceHandler, Flow, type HandSummary, type LogEntry, type MapSummary, type MovableHole, type OpenFlowOptions, type OutcomeView, type PlayOptions, type PropertyScopeKind, type PropertyScopeSummary, type PropertySummary, type RankedList, type TagGroupSummary, type TraceEvent, type TraceHandler, type TraceVerdict, describeBundle };