@storylet-studio/runtime 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -2,6 +2,7 @@ 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 { PropertyBag, PropertyRow } from '@wildwinter/scoperegistry';
+export { PropertyRow } from '@wildwinter/scoperegistry';
 
 interface EngineOptions {
     /** Default seed for each flow's PRNG; override per flow in openFlow
@@ -23,6 +24,16 @@ interface EngineOptions {
      * once, each engine saves its own envelope (design/flows.md).
      */
     world?: ScopeResolver;
+    /**
+     * 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
+     * behaviour is unchanged - replacing is deliberate and the same in Patter -
+     * this only makes it observable, because the case it catches is a host
+     * calling `openFlow` straight after `loadGame` to "re-take" its handle and
+     * silently discarding the hand the save just restored (`getFlow` is the
+     * call). Zero cost when unset; leave it unset in shipped games.
+     */
+    onReplacedFlow?: (id: string, dealt: number) => void;
 }
 interface OpenFlowOptions {
     /** Seed for this flow's PRNG (defaults to the engine's `seed`). */
@@ -142,11 +153,6 @@ interface CardEntry {
     deck: Deck<Expression>;
     box: Box<Expression>;
 }
-/** One examiner row, addressed by the property-path grammar
- *  (getProperty / setProperty take the same `path`). */
-interface PropertyView extends PropertyRow {
-    path: string;
-}
 /** One kernel bag with its store path prefix (story / box.<id> / deck.<id>
  *  / hand.<id> / value.<id>): the state logger's mount surface
  *  (design/engine-runtimes.md 3.4 - the logger builds on the PropertyBag
@@ -228,6 +234,9 @@ interface Internals {
     shared: Partition;
     /** @world: the host's resolver, or the self-backed bag's. */
     worldResolver: ScopeResolver;
+    /** @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>;
     /** `turn` is the box clock the event happened on, where the caller knows it
      *  - the same stamp the flow's own log carries. Unity and Unreal passed it
      *  from the start; JS and Godot dropped it, so their examiners printed "[-]"
@@ -239,6 +248,7 @@ interface Internals {
 declare class Engine {
     private readonly internals;
     private readonly seed;
+    private readonly onReplacedFlow;
     private readonly flowsById;
     private readonly engineTraceHandlers;
     /** The host's @world binding, if the engine was built with one: it
@@ -308,7 +318,7 @@ declare class Engine {
     private resolveShared;
     /** The shared surface as examiner rows: @world (read through the
      *  resolver) then the shared partitions. Per-flow rows live on each Flow. */
-    listProperties(): PropertyView[];
+    listProperties(): PropertyRow[];
     /** The SHARED kernel bags with their store path prefixes (the state
      *  logger's mount surface). The @world container is the host's own bag -
      *  the host mounts it itself. */
@@ -525,7 +535,7 @@ declare class Flow {
      *  resolver, then per scope the shared values and this flow's own.
      *  Bundle order: world, story, then per-box / per-deck / per-hand /
      *  per-tag stores. */
-    listProperties(): PropertyView[];
+    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. */
@@ -653,4 +663,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 PropertyView, 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 OpenFlowOptions, type OutcomeView, type PlayOptions, type PropertyScopeKind, type PropertyScopeSummary, type PropertySummary, type RankedList, type TagGroupSummary, type TraceEvent, type TraceHandler, type TraceVerdict, describeBundle };

package/dist/index.d.ts

@@ -2,6 +2,7 @@ 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 { PropertyBag, PropertyRow } from '@wildwinter/scoperegistry';
+export { PropertyRow } from '@wildwinter/scoperegistry';
 
 interface EngineOptions {
     /** Default seed for each flow's PRNG; override per flow in openFlow
@@ -23,6 +24,16 @@ interface EngineOptions {
      * once, each engine saves its own envelope (design/flows.md).
      */
     world?: ScopeResolver;
+    /**
+     * 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
+     * behaviour is unchanged - replacing is deliberate and the same in Patter -
+     * this only makes it observable, because the case it catches is a host
+     * calling `openFlow` straight after `loadGame` to "re-take" its handle and
+     * silently discarding the hand the save just restored (`getFlow` is the
+     * call). Zero cost when unset; leave it unset in shipped games.
+     */
+    onReplacedFlow?: (id: string, dealt: number) => void;
 }
 interface OpenFlowOptions {
     /** Seed for this flow's PRNG (defaults to the engine's `seed`). */
@@ -142,11 +153,6 @@ interface CardEntry {
     deck: Deck<Expression>;
     box: Box<Expression>;
 }
-/** One examiner row, addressed by the property-path grammar
- *  (getProperty / setProperty take the same `path`). */
-interface PropertyView extends PropertyRow {
-    path: string;
-}
 /** One kernel bag with its store path prefix (story / box.<id> / deck.<id>
  *  / hand.<id> / value.<id>): the state logger's mount surface
  *  (design/engine-runtimes.md 3.4 - the logger builds on the PropertyBag
@@ -228,6 +234,9 @@ interface Internals {
     shared: Partition;
     /** @world: the host's resolver, or the self-backed bag's. */
     worldResolver: ScopeResolver;
+    /** @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>;
     /** `turn` is the box clock the event happened on, where the caller knows it
      *  - the same stamp the flow's own log carries. Unity and Unreal passed it
      *  from the start; JS and Godot dropped it, so their examiners printed "[-]"
@@ -239,6 +248,7 @@ interface Internals {
 declare class Engine {
     private readonly internals;
     private readonly seed;
+    private readonly onReplacedFlow;
     private readonly flowsById;
     private readonly engineTraceHandlers;
     /** The host's @world binding, if the engine was built with one: it
@@ -308,7 +318,7 @@ declare class Engine {
     private resolveShared;
     /** The shared surface as examiner rows: @world (read through the
      *  resolver) then the shared partitions. Per-flow rows live on each Flow. */
-    listProperties(): PropertyView[];
+    listProperties(): PropertyRow[];
     /** The SHARED kernel bags with their store path prefixes (the state
      *  logger's mount surface). The @world container is the host's own bag -
      *  the host mounts it itself. */
@@ -525,7 +535,7 @@ declare class Flow {
      *  resolver, then per scope the shared values and this flow's own.
      *  Bundle order: world, story, then per-box / per-deck / per-hand /
      *  per-tag stores. */
-    listProperties(): PropertyView[];
+    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. */
@@ -653,4 +663,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 PropertyView, 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 OpenFlowOptions, type OutcomeView, type PlayOptions, type PropertyScopeKind, type PropertyScopeSummary, type PropertySummary, type RankedList, type TagGroupSummary, type TraceEvent, type TraceHandler, type TraceVerdict, describeBundle };

package/dist/index.js

@@ -423,8 +423,12 @@ var PropertyBag = class _PropertyBag {
    *  long-standing contract); a product whose names are case-significant
    *  passes identity. */
   norm;
+  /** The address prefix this bag's rows carry, separator included (`@`,
+   *  `@scene.`, `world.`, `deck.<id>.`). Empty means a row's path is its name. */
+  pathPrefix;
   constructor(declarations = [], opts) {
     this.norm = opts?.normalise ?? ((n) => n.toLowerCase());
+    this.pathPrefix = opts?.pathPrefix ?? "";
     this.seed(declarations);
   }
   seed(declarations) {
@@ -468,7 +472,7 @@ var PropertyBag = class _PropertyBag {
   /** Examiner rows: the declared surface only (stray values are storage,
    *  not surface). */
   rows() {
-    return [...this.decls.entries()].map(([name, d]) => rowFor(d, this.get(name), void 0, name));
+    return [...this.decls.entries()].map(([name, d]) => rowFor(d, this.get(name), void 0, name, this.pathPrefix));
   }
   declarations() {
     return [...this.decls.values()];
@@ -477,7 +481,7 @@ var PropertyBag = class _PropertyBag {
    *  duplicated, the normalisation policy carried, subscriptions NOT
    *  carried. */
   clone() {
-    const c = new _PropertyBag([], { normalise: this.norm });
+    const c = new _PropertyBag([], { normalise: this.norm, pathPrefix: this.pathPrefix });
     c.decls = new Map(this.decls);
     Object.assign(c.values, structuredClone(this.values));
     return c;
@@ -500,13 +504,19 @@ var PropertyBag = class _PropertyBag {
     for (const [k, v] of Object.entries(values)) this.values[this.norm(k)] = v;
   }
 };
-function rowFor(d, value, writable, name) {
+function rowFor(d, value, writable, name, pathPrefix = "") {
+  const rowName = name ?? d.name.toLowerCase();
   return {
-    name: name ?? d.name.toLowerCase(),
+    name: rowName,
+    path: pathPrefix + rowName,
     type: d.type,
     value,
     default: d.default ?? defaultFor(d),
     ...d.values !== void 0 ? { values: d.values } : {},
+    // `stages` was added to the row so an examiner could offer a quality's ladder
+    // instead of a free-text box, and then never populated here: every quality row
+    // this function built came out without one. Fixed 2026-09-02.
+    ...d.stages !== void 0 ? { stages: d.stages } : {},
     writable: writable ?? d.writable ?? true
   };
 }
@@ -526,6 +536,13 @@ function defaultFor(d) {
     // A quality starts at the first rung of its ladder.
     case "quality":
       return d.stages?.[0] ?? "";
+    // Unreachable for a well-typed declaration, and deliberately present anyway: a bundle
+    // is DATA, and a hand-edited or newer-than-this-build one can carry a type string the
+    // union does not have. Falling off the switch would seed `undefined`, which is not a
+    // ScalarValue and travels a long way before it fails. Patterplay's copy of this had the
+    // guard and this one did not, which is the drift you only find by removing a duplicate.
+    default:
+      return false;
   }
 }
 
@@ -533,7 +550,7 @@ function defaultFor(d) {
 var tagKey = (groupId, tagId) => `${groupId}${tagId}`;
 var cardIsShared = (card, deckShared) => card.shared ?? deckShared;
 var sharedCap = (card) => card.sharedCopies ?? card.copies ?? 1;
-var bagFromDecls = (decls) => new PropertyBag(decls, { normalise: (n) => n });
+var bagFromDecls = (decls, pathPrefix) => new PropertyBag(decls, { normalise: (n) => n, pathPrefix });
 function conditionPasses(v) {
   if (typeof v === "boolean") return v;
   if (typeof v === "number") return v !== 0;
@@ -553,18 +570,18 @@ var handDeclsOf = (internals, hand) => {
 var buildPartition = (internals, half) => {
   const b = internals.bundle;
   return {
-    story: bagFromDecls(half("story", b.story.properties)),
-    box: new Map(b.boxes.map((box) => [box.id, bagFromDecls(half("box", box.properties))])),
+    story: bagFromDecls(half("story", b.story.properties), "story."),
+    box: new Map(b.boxes.map((box) => [box.id, bagFromDecls(half("box", box.properties), `box.${box.id}.`)])),
     deck: new Map(b.boxes.flatMap((box) => box.decks.map(
-      (deck) => [deck.id, bagFromDecls(half("deck", deck.properties))]
+      (deck) => [deck.id, bagFromDecls(half("deck", deck.properties), `deck.${deck.id}.`)]
     ))),
     // A template instance inherits the template's property declarations;
     // a standalone hand declares its own (schema 2.6).
     hand: new Map(b.boxes.flatMap((box) => box.hands.map(
-      (hand) => [hand.id, bagFromDecls(half("hand", handDeclsOf(internals, hand)))]
+      (hand) => [hand.id, bagFromDecls(half("hand", handDeclsOf(internals, hand)), `hand.${hand.id}.`)]
     ))),
     value: new Map(b.boxes.flatMap((box) => box.tagGroups.flatMap((group) => group.tags.map(
-      (tag) => [tag.id, bagFromDecls(half("value", tag.properties ?? []))]
+      (tag) => [tag.id, bagFromDecls(half("value", tag.properties ?? []), `value.${tag.id}.`)]
     ))))
   };
 };
@@ -586,6 +603,7 @@ var loadPartition = (p, values) => {
 var Engine = class {
   internals;
   seed;
+  onReplacedFlow;
   flowsById = /* @__PURE__ */ new Map();
   engineTraceHandlers = /* @__PURE__ */ new Set();
   /** The host's @world binding, if the engine was built with one: it
@@ -594,6 +612,7 @@ var Engine = class {
   hostWorld;
   constructor(bundle, opts = {}) {
     this.seed = opts.seed ?? 0;
+    this.onReplacedFlow = opts.onReplacedFlow;
     if (opts.world !== void 0) this.hostWorld = opts.world;
     const internals = {
       bundle,
@@ -614,6 +633,7 @@ var Engine = class {
       flowDecls: { story: [], box: /* @__PURE__ */ new Map(), deck: /* @__PURE__ */ new Map(), hand: /* @__PURE__ */ new Map(), value: /* @__PURE__ */ new Map() },
       shared: void 0,
       worldResolver: void 0,
+      worldReadOnly: /* @__PURE__ */ new Set(),
       emitEngine: (flow, event, turn) => {
         if (this.internals.logCap !== void 0) {
           this.engineLog.push({ ...event, flow, seq: this.engineSeq++, ...turn !== void 0 ? { turn } : {} });
@@ -671,10 +691,11 @@ var Engine = class {
   initShared(hostWorld) {
     const internals = this.internals;
     internals.shared = buildPartition(internals, sharedHalf);
+    internals.worldReadOnly = new Set(internals.bundle.world.properties.filter((d) => d.writable === false).map((d) => d.name));
     if (hostWorld !== void 0) {
       internals.worldResolver = hostWorld;
     } else {
-      const bag = bagFromDecls(internals.bundle.world.properties);
+      const bag = bagFromDecls(internals.bundle.world.properties, "world.");
       internals.worldResolver = {
         get: (n) => bag.get(n),
         set: (n, v) => {
@@ -714,7 +735,12 @@ var Engine = class {
    *  state; shared state is untouched. There is no default flow: "main" is
    *  a caller convention, not an engine rule. */
   openFlow(id, opts = {}) {
-    this.flowsById.get(id)?.markClosed();
+    const existing = this.flowsById.get(id);
+    if (existing) {
+      const dealt = existing.heldCardIds().length;
+      if (dealt > 0) this.onReplacedFlow?.(id, dealt);
+      existing.markClosed();
+    }
     const flow = new Flow(this, this.internals, id, opts.seed ?? this.seed);
     this.flowsById.set(id, flow);
     return flow;
@@ -850,11 +876,16 @@ var Engine = class {
         value: value ?? d.default,
         default: d.default,
         ...d.values !== void 0 ? { values: d.values } : {},
-        ...d.stages !== void 0 ? { stages: d.stages } : {}
+        ...d.stages !== void 0 ? { stages: d.stages } : {},
+        // @world is FOREIGN - a host resolver backs it - so writability is whether that
+        // resolver can be written at all, which is the shared registry's own rule for a
+        // foreign scope. The `as PropertyView` cast this replaced was hiding the field's
+        // absence: the row type has always required it, and these rows shipped without one.
+        writable: this.internals.worldResolver.set !== void 0
       });
     }
-    const add = (prefix, bag) => {
-      for (const row of bag.rows()) out.push({ path: `${prefix}.${row.name}`, ...row });
+    const add = (_prefix, bag) => {
+      for (const row of bag.rows()) out.push(row);
     };
     add("story", this.internals.shared.story);
     for (const [id, bag] of this.internals.shared.box) add(`box.${id}`, bag);
@@ -1675,6 +1706,7 @@ var Flow = class {
       case "world": {
         const resolver = this.internals.worldResolver;
         if (!resolver.set) throw new Error(`@world.${name} cannot be written: the host bound @world read-only`);
+        if (this.internals.worldReadOnly.has(name)) throw new Error(`'@world.${name}' is read-only (writable: false)`);
         const prev = resolver.get(name);
         resolver.set(name, value);
         return { path: `world.${name}`, ...prev !== void 0 ? { prev } : {} };
@@ -1746,13 +1778,18 @@ var Flow = class {
         value: value ?? d.default,
         default: d.default,
         ...d.values !== void 0 ? { values: d.values } : {},
-        ...d.stages !== void 0 ? { stages: d.stages } : {}
+        ...d.stages !== void 0 ? { stages: d.stages } : {},
+        // @world is FOREIGN - a host resolver backs it - so writability is whether that
+        // resolver can be written at all, which is the shared registry's own rule for a
+        // foreign scope. The `as PropertyView` cast this replaced was hiding the field's
+        // absence: the row type has always required it, and these rows shipped without one.
+        writable: this.internals.worldResolver.set !== void 0
       });
     }
-    const add = (prefix, shared, own) => {
+    const add = (_prefix, shared, own) => {
       for (const bag of [shared, own]) {
         if (bag === void 0) continue;
-        for (const row of bag.rows()) out.push({ path: `${prefix}.${row.name}`, ...row });
+        for (const row of bag.rows()) out.push(row);
       }
     };
     add("story", this.internals.shared.story, this.stores.story);