@patterkit/runtime 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -33,6 +33,92 @@ version number always means the same runtime behaviour. This package is versione
 
 ## [Unreleased]
 
+## [0.20.0] - 2026-10-06
+
+### Added
+
+- **`hostScopes`, the engine option every other runtime takes**: the scopes the game binds, by token, each a `{
+  get, set? }` over values it owns, as in `hostScopes: { world: { get, set } }`. A resolver's type is
+  `HostScope`.
+- **`engine.buildId`**, as the other runtimes have: the bundle's content hash, the build a debug link handshakes
+  with.
+- **A bundle-description section in the conformance corpus.** What `describeBundle` says about one bundle, field
+  for field, held on every runtime.
+- **`getVisitCounts()` on the engine and on a flow**, on every runtime: how many times each node has been
+  entered, across every flow or in this one, read without a save.
+
+### Changed
+
+- **Less work per step.** A decision's log entry is built only while the log is on or something is tracing, and
+  a quality's stage ladder is looked up once per set of declarations rather than scanned for on every
+  comparison.
+
+### Deprecated
+
+- **`flow.start()` is deprecated: use `flow.reset()`.** They were the same call under two names. `flow.reset()`
+  is the one public name for beginning a flow again on every runtime (opening a flow begins a new one);
+  `flow.start()` goes in a later release.
+- **The `world` option and the `WorldResolver` type: use `hostScopes: { world }` and `HostScope`.** `world` is
+  still the world scope, and goes in a later release.
+- **The `TraceHandler` type.** Nothing takes one: `onTrace` takes an `EngineTraceHandler`. It goes in a later
+  release.
+
+### Fixed
+
+- **`reset()` no longer replays a prompt from the run it abandoned.** With prompt replay on, `choose()` leaves
+  the chosen option's prompt waiting for the next `advance()`. `reset()` in between cleared only the choice, so
+  the old prompt played as the restarted run's first beat. Every move that leaves the flow's place (`reset()`,
+  `goto`, `close`) now drops both, through one helper.
+- **`onTrace` hears every decision with the log off.** A `run` walk past a snippet whose condition failed, and a
+  write's previous value, were only worked out when the log was on, so a tool tracing a run without the log
+  missed the one and got a write without the other. They are now worked out whenever anything is tracing.
+
+## [0.19.0] - 2026-10-06
+
+### Added
+
+- **`EngineOptions.onError` and `PlayError`.** Each condition or effect that fails while the story plays is
+  reported to `onError` with the flow, what failed (`condition`, `effect`, or `best-match`), the node, the
+  expression's source, and the error. With no `onError`, each goes to `console.warn`. With the log on, each is
+  also a `diagnostic` entry in the decision log.
+
+### Changed
+
+- **A condition or effect that fails no longer stops the story.** A failing condition counts as false, and a
+  failing effect is skipped while the rest of its list still runs, including a story write a read-only `@world`
+  value refuses. This is the same on all four runtimes; JS used to throw out of `advance()`.
+- **A part of a Best-match condition that fails scores as false**, as on the other three runtimes. JS threw
+  while scoring.
+- **A selector evaluates each condition once.** It evaluated each child's condition twice, so a condition
+  calling `random(a, b)` drew twice and the logged verdict could disagree with the pick.
+- **A shuffle draws only from the children in its bag that are still eligible.** A child whose condition went
+  false after the bag was filled could be drawn, and the group then played nothing. When no child left in the
+  bag is eligible, the pass ends as if the bag were empty. Seeded results do not change while every child in the
+  bag stays eligible.
+- **`openFlow`, `goto` and the engine's lookups read an address the same way:** a scene's game id first, then
+  its internal id, and a block only within its scene. `openFlow` tried the internal id first, so the two could
+  land in different scenes when one scene's id was another's game id.
+- **A choice whose every remaining option is greyed out runs dry**, as a choice with no options does: the
+  fallback follows if there is one, otherwise the flow moves on and `onDryChoice` fires. It used to be offered
+  with nothing the player could take.
+- **An option's prompt beat carries tags**: its own and the option's. A replayed prompt and the outline lost
+  them.
+- **`loadGame` checks a save before changing anything.** A save missing its flows used to close every flow and
+  load the registry before failing, leaving the engine half-loaded.
+
+### Fixed
+
+- **`@wildwinter/expr` 0.5.1 and `@wildwinter/scoperegistry` 0.8.1 (kernel `k492cf234`):** a listener's own
+  error is no longer reported as a read-only refusal, every listener registered when a write starts hears it
+  exactly once, and the hot path allocates less, with no leaks.
+- **A rollback after a load keeps a scene's saved `@scene` values.** After a load, a scene the flow is not
+  standing in keeps its saved values waiting until the flow enters it. Entering it inside a checkpoint and then
+  rolling back used to drop those values, so the next real entry found the defaults and the next save left them
+  out. A new corpus case pins this on all four runtimes.
+- **The decision log's `seq` keeps counting after a clear.** The engine's log numbered entries by its length, so
+  after `clearLog()` the numbers started again at 0 and entries read either side of the clear could not be put
+  in order.
+
 ## [0.18.0] - 2026-10-05
 
 ### Changed

package/README.md

@@ -44,9 +44,10 @@ for (;;) {
 }
 ```
 
-`new Engine(bundle, options)` takes `{ rng?, seed?, locale?, world?, registry?, replayPromptOnChoose?, closedCaptions? }`:
-- `world` is the host's resolver for `@world` properties (World Properties): `{ get(name), set?(name, value) }`.
-  Omit it and the runtime self-backs `@world` from the declared defaults, as a property it saves.
+`new Engine(bundle, options)` takes `{ rng?, seed?, locale?, hostScopes?, registry?, replayPromptOnChoose?, closedCaptions? }`:
+- `hostScopes` binds the scopes your game owns, by token, each `{ get(name), set?(name, value) }`: for World
+  Properties, `hostScopes: { world: { get, set } }`. Leave `world` unbound and the runtime self-backs `@world`
+  from the declared defaults, as a property it saves.
 - `registry` is the game's one `ScopeRegistry` (from `@wildwinter/scoperegistry`), holding every
   engine's properties. Omit it and the engine makes its own. See *One registry per game* below.
 - `locale` plays a non-default language (embedded localisation; an IDs-only bundle ignores it).

package/dist/index.cjs

@@ -54,6 +54,7 @@ function buildTagIndex(bundle) {
   const visit = (node, inherited) => {
     const acc = dedupe([...inherited, ...node.tags ?? []]);
     index.set(node.id, acc);
+    if (node.type === "group" && node.prompt) index.set(node.prompt.id, dedupe([...acc, ...node.prompt.tags ?? []]));
     if (node.type === "group") {
       for (const child of node.children) visit(child, acc);
     } else {
@@ -113,11 +114,13 @@ var Engine = class _Engine {
   sceneGameIdToId = /* @__PURE__ */ new Map();
   blockGameIdToId = /* @__PURE__ */ new Map();
   /** The options this engine was built with - reused verbatim by `hotSwap` so the replacement
-   *  engine keeps the same world resolver, custom RNG, and diagnostic hooks. */
+   *  engine keeps the same host scopes, custom RNG, and diagnostic hooks. */
   creationOptions;
   /** The run's ordered stream: every flow's events, each naming its flow. Empty and
    *  unwritten unless `options.log` asked for it. */
   engineLog = [];
+  /** The next engine-log `seq`: its own counter, since the log's length restarts after a clear. */
+  engineSeq = 0;
   engineTraceHandlers = /* @__PURE__ */ new Set();
   constructor(bundle, options = {}) {
     this.creationOptions = options;
@@ -163,12 +166,12 @@ var Engine = class _Engine {
       registry.mountOwned("patter", patterBag, { owner: OWNER });
       registered.push("patter");
       const hostBound = /* @__PURE__ */ new Set();
-      if (options.world) {
-        const worldSpec = bundle.scopeRegistry?.scopes.find((s) => s.token === "world");
-        const decls = (worldSpec?.declarations ?? []).map(toForeignDecl);
-        registry.defineForeign("world", options.world, decls, { writable: worldSpec?.writable ?? true, owner: OWNER });
-        registered.push("world");
-        hostBound.add("world");
+      for (const [token, resolver] of Object.entries(boundScopes(options))) {
+        const spec = bundle.scopeRegistry?.scopes.find((s) => s.token === token);
+        const decls = (spec?.declarations ?? []).map(toForeignDecl);
+        registry.defineForeign(token, resolver, decls, { writable: spec?.writable ?? true, owner: OWNER });
+        registered.push(token);
+        hostBound.add(token);
       }
       for (const spec of ownsRegistry ? bundle.scopeRegistry?.scopes ?? [] : []) {
         if (hostBound.has(spec.token) || registry.has(spec.token)) continue;
@@ -188,6 +191,7 @@ var Engine = class _Engine {
     }
     this.host = {
       logEnabled: options.log ?? false,
+      tracing: options.log ?? false,
       emitEngine: (flow, event, scene) => this.emitEngine(flow, event, scene),
       bundle,
       emitIds,
@@ -210,11 +214,13 @@ var Engine = class _Engine {
       patterSharedNames,
       sceneSharedNames,
       sharedVisits: /* @__PURE__ */ new Map(),
+      qualityLadders: /* @__PURE__ */ new Map(),
       sharedSelectors: /* @__PURE__ */ new Map(),
       stageBags: /* @__PURE__ */ new Map(),
       journal: null,
       customRng: options.rng,
       onDryChoice: options.onDryChoice,
+      onError: options.onError ?? ((e) => console.warn(`Patterplay: ${e.kind} on ${e.node} in flow '${e.flow}' failed, played through: ${e.message}`)),
       replayPromptOnChoose: options.replayPromptOnChoose ?? false,
       captionsOn: options.closedCaptions ?? true,
       // captions shown by default (full text)
@@ -235,6 +241,11 @@ var Engine = class _Engine {
   get isSourceDebug() {
     return this.sourceDebug;
   }
+  /** The bundle's build identity (its content hash), the one a debug link handshakes with, or an empty
+   *  string for a bundle compiled without one. */
+  get buildId() {
+    return this.host.bundle.content?.hash ?? "";
+  }
   /**
    * Switch the active locale LIVE - a real game's "language" setting can change mid-session. Subsequent
    * string lookups (new beats, re-resolved character names, `{@ref}` interpolation) render in the new
@@ -355,7 +366,7 @@ var Engine = class _Engine {
       });
     }
     this.flowsById.set(id, flow);
-    flow.start(sceneId, blockId);
+    flow.begin(sceneId, blockId);
     return flow;
   }
   /**
@@ -408,10 +419,10 @@ var Engine = class _Engine {
    */
   resolveOpenAddress(scene, block) {
     if (scene !== void 0) {
-      const sceneId = this.resolveSceneRef(scene);
-      if (!this.host.bundle.scenes[sceneId]) throw new Error(`unknown scene: ${scene}`);
+      const sceneId = resolveScene(this.host, scene);
+      if (sceneId === void 0) throw new Error(`unknown scene: ${scene}`);
       if (block === void 0) return { sceneId };
-      const blockId = this.blockGameIdToId.get(sceneId)?.get(block) ?? (this.host.blockIndex.get(block)?.sceneId === sceneId ? block : void 0);
+      const blockId = resolveBlock(this.host, sceneId, block);
       if (blockId === void 0) throw new Error(`unknown block: ${block}`);
       return { sceneId, blockId };
     }
@@ -422,21 +433,19 @@ var Engine = class _Engine {
     if (Object.keys(this.host.bundle.scenes).length === 0) throw new Error("no scenes in bundle");
     return {};
   }
-  /** Resolve a scene reference (a gameId address OR an internal id) to its internal id. */
+  /** Resolve a scene reference to its internal id by the one address rule (see resolveScene); an
+   *  unknown one passes through, for the caller to find nothing. */
   resolveSceneRef(ref) {
     if (ref == null) return void 0;
-    if (this.host.bundle.scenes[ref]) return ref;
-    return this.sceneGameIdToId.get(ref) ?? ref;
+    return resolveScene(this.host, ref) ?? ref;
   }
-  /** Resolve a block reference (a scene-scoped gameId OR an internal id) to its internal id. */
+  /** Resolve a block reference to its internal id by the one address rule (see resolveBlock): within its
+   *  scene, so a block of another scene resolves to nothing. With no scene, only an internal id resolves,
+   *  since a block's gameId is only unique within its scene. */
   resolveBlockRef(sceneId, ref) {
     if (ref == null) return void 0;
-    if (this.host.blockById.has(ref)) return ref;
-    if (sceneId != null) {
-      const id = this.blockGameIdToId.get(sceneId)?.get(ref);
-      if (id) return id;
-    }
-    return ref;
+    if (sceneId == null) return ref;
+    return resolveBlock(this.host, sceneId, ref);
   }
   /** The host-facing address (gameId) of a scene / block by internal id, or undefined if unknown.
    *  The inverse of the resolve helpers - for a host that wants to display / log the address. */
@@ -721,7 +730,7 @@ var Engine = class _Engine {
     for (const s of this.host.stageBags.keys()) reg.remove(keys.stage(s), { keep });
     this.host.stageBags.clear();
     for (const t of ["patter", ...this.host.hostScopes]) if (reg.has(t)) reg.remove(t, { keep });
-    if (this.creationOptions.world && reg.has("world")) reg.remove("world");
+    for (const t of Object.keys(boundScopes(this.creationOptions))) if (reg.has(t)) reg.remove(t);
   }
   /** Read a shared (`@patter` / foreign) property by ref. `@scene` refs are rejected (flow-level). */
   getProperty(ref) {
@@ -758,12 +767,21 @@ var Engine = class _Engine {
    *  retained. Returns its own unsubscribe. */
   onTrace(handler) {
     this.engineTraceHandlers.add(handler);
-    return () => this.engineTraceHandlers.delete(handler);
+    this.host.tracing = true;
+    return () => {
+      this.engineTraceHandlers.delete(handler);
+      this.host.tracing = this.host.logEnabled || this.engineTraceHandlers.size > 0;
+    };
   }
   emitEngine(flow, event, scene) {
     for (const h of this.engineTraceHandlers) h(flow, event);
     if (!this.host.logEnabled) return;
-    this.engineLog.push({ ...event, flow, seq: this.engineLog.length, ...scene ? { scene } : {} });
+    this.engineLog.push({ ...event, flow, seq: this.engineSeq++, ...scene ? { scene } : {} });
+  }
+  /** How many times each node has been entered across every flow, by node id: the shared count. With a
+   *  flow's own {@link Flow.getVisitCounts}, every visit count the run keeps, read without a save. */
+  getVisitCounts() {
+    return Object.fromEntries(this.host.sharedVisits);
   }
   listProperties() {
     return this.host.patterSharedDecls.map((d) => ({
@@ -829,6 +847,8 @@ var Engine = class _Engine {
     this.refuseInCheckpoint("loadGame");
     const version = save.version;
     if (version !== 2 && version !== import_model2.SAVE_VERSION) throw new Error(`unsupported save version: ${String(version)}`);
+    const flows = save.flows;
+    if (typeof flows !== "object" || flows === null || Array.isArray(flows)) throw new Error("malformed save: no flows");
     this.assertExternalScopes();
     const reg = this.host.registry;
     for (const [id, flow] of this.flowsById) {
@@ -967,19 +987,21 @@ var Flow = class {
    *  lowercase, as the compiler emits references (the selfBackedResolver lesson). */
   stagesFor(scope, name) {
     const key = name.toLowerCase();
-    const fromDecls = (decls) => decls?.find((d) => d.name.toLowerCase() === key && d.type === "quality")?.stages;
     if (scope === "patter") {
-      return fromDecls(this.host.patterSharedDecls) ?? fromDecls(this.host.patterLocalDecls);
+      return ladders(this.host, "patter", () => [...this.host.patterSharedDecls, ...this.host.patterLocalDecls]).get(key);
     }
     if (scope === "scene") {
-      const scene = this.currentSceneId != null ? this.host.bundle.scenes[this.currentSceneId] : void 0;
-      return fromDecls(scene?.sceneProps);
+      const sceneId = this.currentSceneId;
+      if (sceneId == null) return void 0;
+      return ladders(this.host, `scene/${sceneId}`, () => this.host.bundle.scenes[sceneId]?.sceneProps).get(key);
     }
-    return this.registryQualities?.(scope, name) ?? fromDecls(this.host.bundle.scopeRegistry?.scopes.find((s) => s.token === scope)?.declarations);
+    return this.registryQualities?.(scope, name) ?? ladders(this.host, `host/${scope}`, () => this.host.bundle.scopeRegistry?.scopes.find((s) => s.token === scope)?.declarations).get(key);
   }
   // -- Host API -------------------------------------------------------------
-  /** Begin this flow at a scene (and optionally a specific block within it). */
-  start(sceneId, blockId) {
+  /** Begin this flow at a scene (and optionally a specific block within it). The engine's own entry point:
+   *  openFlow and a goto on an unstarted flow begin a flow here. A game calls {@link reset}.
+   *  @internal */
+  begin(sceneId, blockId) {
     if (this.host.journal && !this.host.journal.opened.has(this)) throw new Error("a flow can't be started or reset while a checkpoint is open");
     this.releaseBags(false);
     this.host.registry.discardParked(keys.flow(this.id));
@@ -991,7 +1013,7 @@ var Flow = class {
     this.flowEnded = false;
     this.activeSnippet = null;
     this.beatIndex = 0;
-    this.pendingChoice = null;
+    this.clearPending();
     this.started = true;
     if (blockId) {
       const loc = this.host.blockIndex.get(blockId);
@@ -1016,10 +1038,15 @@ var Flow = class {
    * Forget everything in this flow and begin again - its per-flow state (not-shared
    * `@patter` globals + `@scene` props), cursor, callstack, selector cursors, and
    * visit counts. Shared state (shared `@patter` / `@scene`, world visit counts) is
-   * untouched. A clearer-named alias of `start()`.
+   * untouched. The one public way to begin a flow again (openFlow begins a new one).
    */
   reset(sceneId, blockId) {
-    this.start(sceneId, blockId);
+    this.begin(sceneId, blockId);
+  }
+  /** @deprecated Use {@link reset}, the one public name for beginning a flow again on every runtime. `start`
+   *  was the same call under a second name, and goes in a later release. */
+  start(sceneId, blockId) {
+    this.reset(sceneId, blockId);
   }
   /**
    * Send this flow's cursor to an ADDRESS, exactly as an authored `go` jump would: the target scene's
@@ -1043,29 +1070,25 @@ var Flow = class {
     this.touch();
     if (scene === "END") {
       this.started = true;
-      this.pendingChoice = null;
-      this.pendingPrompt = null;
-      this.pendingPromptOwnerId = null;
+      this.clearPending();
       this.activeSnippet = null;
       this.beatIndex = 0;
       this.flowEnded = true;
       this.stack = [];
       return true;
     }
-    const sceneId = this.host.sceneGameIdToId.get(scene) ?? (this.host.bundle.scenes[scene] ? scene : void 0);
+    const sceneId = resolveScene(this.host, scene);
     if (sceneId === void 0) return false;
     let blockId;
     if (block !== void 0) {
-      blockId = this.host.blockGameIdToId.get(sceneId)?.get(block) ?? (this.host.blockIndex.get(block)?.sceneId === sceneId ? block : void 0);
+      blockId = resolveBlock(this.host, sceneId, block);
       if (blockId === void 0) return false;
     }
     if (!this.started) {
-      this.start(sceneId, blockId);
+      this.begin(sceneId, blockId);
       return true;
     }
-    this.pendingChoice = null;
-    this.pendingPrompt = null;
-    this.pendingPromptOwnerId = null;
+    this.clearPending();
     this.activeSnippet = null;
     this.beatIndex = 0;
     this.flowEnded = false;
@@ -1090,6 +1113,15 @@ var Flow = class {
     this.stack = [];
     this.activeSnippet = null;
     this.beatIndex = 0;
+    this.clearPending();
+  }
+  /**
+   * Drop everything waiting to be delivered: an open choice, and a chosen option's prompt still to be
+   * replayed. Every move that abandons the flow's place (start and reset, goto, close) does this, so none
+   * leaves a stale prompt behind. start() cleared only the choice, so a reset between choose() and the
+   * next advance() replayed the abandoned run's prompt as the new run's first beat.
+   */
+  clearPending() {
     this.pendingChoice = null;
     this.pendingPrompt = null;
     this.pendingPromptOwnerId = null;
@@ -1166,7 +1198,7 @@ var Flow = class {
       if (this.flowEnded || this.pendingChoice) return;
       if (this.activeSnippet) {
         if (this.beatIndex < (this.activeSnippet.beats?.length ?? 0)) return;
-        this.runEffects(this.activeSnippet.onExit);
+        this.runEffects(this.activeSnippet.onExit, this.activeSnippet.id);
         const jump = this.activeSnippet.jump;
         this.activeSnippet = null;
         this.beatIndex = 0;
@@ -1186,7 +1218,7 @@ var Flow = class {
       }
       const from = frame.index;
       while (frame.index < children.length && !this.eligible(children[frame.index])) frame.index++;
-      if (this.host.logEnabled && frame.index !== from) {
+      if (this.host.tracing && frame.index !== from) {
         this.emit({
           type: "select",
           group: frame.containerId,
@@ -1222,14 +1254,18 @@ var Flow = class {
   clearLog() {
     this.flowLog.length = 0;
   }
-  /** Record one decision, on this flow's log and the engine's. Cheap to call with logging
-   *  off: the entry is never built. */
+  /** Record one decision, on this flow's log and the engine's, and hand it to any `onTrace`. Each call
+   *  site checks `host.tracing` first, so with nothing logging or tracing the entry is never built. */
   emit(event) {
     const scene = this.currentSceneId ?? void 0;
     this.host.emitEngine(this.id, event, scene);
     if (!this.host.logEnabled) return;
     this.flowLog.push({ ...event, seq: this.flowSeq++, ...scene ? { scene } : {} });
   }
+  /** How many times this flow has entered each node, by node id. */
+  getVisitCounts() {
+    return Object.fromEntries(this.visitCounts);
+  }
   /** The options of a pending choice (empty when not at a choice point). */
   getChoices() {
     return this.pendingChoice?.options ?? [];
@@ -1243,7 +1279,7 @@ var Flow = class {
     if (!option.eligible) throw new Error(`choice option is not eligible: ${id}`);
     this.touch();
     const node = choice.byId.get(id);
-    this.emit({ type: "chose", group: choice.groupId, option: id });
+    if (this.host.tracing) this.emit({ type: "chose", group: choice.groupId, option: id });
     this.pendingChoice = null;
     const authored = this.host.replayPromptOnChoose ? this.authoredPromptOf(node) : void 0;
     this.pendingPrompt = authored && option.prompt ? { beat: authored, shown: { ...option.prompt } } : null;
@@ -1382,7 +1418,7 @@ var Flow = class {
     this.currentSceneId = sceneId;
     this.enter(sceneId);
     this.seedScene(scene);
-    this.runEffects(scene.onEntry);
+    this.runEffects(scene.onEntry, scene.id);
   }
   /**
    * Play one child of the active run. A snippet begins delivering. A group is
@@ -1418,7 +1454,7 @@ var Flow = class {
     return void 0;
   }
   beginSnippet(snippet) {
-    this.runEffects(snippet.onEnter);
+    this.runEffects(snippet.onEnter, snippet.id);
     this.activeSnippet = snippet;
     this.beatIndex = 0;
   }
@@ -1438,8 +1474,8 @@ var Flow = class {
       options.push({ id: child.id, prompt: this.promptFor(child), eligible, gameData: child.gameData });
       byId.set(child.id, child);
     }
-    if (options.length > 0) {
-      this.emit({ type: "choice", group: group.id, options: options.map((o) => ({ id: o.id, eligible: o.eligible })) });
+    if (options.some((o) => o.eligible)) {
+      if (this.host.tracing) this.emit({ type: "choice", group: group.id, options: options.map((o) => ({ id: o.id, eligible: o.eligible })) });
       this.pendingChoice = { groupId: group.id, options, byId };
       return;
     }
@@ -1448,7 +1484,7 @@ var Flow = class {
       this.enterChild(fallback);
       return;
     }
-    this.emit({ type: "dry", group: group.id });
+    if (this.host.tracing) this.emit({ type: "dry", group: group.id });
     this.host.onDryChoice?.(group.id);
   }
   // -- Jumps (jump / call-return) ----------------------------------------
@@ -1463,7 +1499,7 @@ var Flow = class {
    * hard-ends the flow regardless of the callstack.
    */
   enterTarget(to, mode) {
-    this.emit({ type: "jump", to, mode });
+    if (this.host.tracing) this.emit({ type: "jump", to, mode });
     if (to === "END") {
       this.flowEnded = true;
       this.stack = [];
@@ -1496,11 +1532,11 @@ var Flow = class {
   // -- Selectors ------------------------------------------------------------
   selectChild(group) {
     const verdicts = group.children.map((c) => ({ id: c.id, eligible: this.eligible(c) }));
-    const eligible = group.children.filter((c) => this.eligible(c));
+    const eligible = group.children.filter((_, i) => verdicts[i].eligible);
     const order = group.options?.order ?? "sequential";
     const exhaust = group.options?.exhaust ?? "once";
     const trace = (picked) => {
-      this.emit({
+      if (this.host.tracing) this.emit({
         type: "select",
         group: group.id,
         selector: group.selector ?? "default",
@@ -1543,8 +1579,9 @@ var Flow = class {
     const len = eligible.length;
     const stick = exhaust === "stick";
     const fill = () => (stick ? eligible.slice(0, len - 1) : eligible).map((c) => c.id);
+    const eligibleIds = new Set(eligible.map((c) => c.id));
     if (st.bag === void 0) st.bag = fill();
-    if (st.bag.length === 0) {
+    if (!st.bag.some((id2) => eligibleIds.has(id2))) {
       if (exhaust === "once") return null;
       if (stick) {
         const last = eligible[len - 1];
@@ -1552,13 +1589,14 @@ var Flow = class {
         return last;
       }
       st.bag = fill();
+      if (st.bag.length === 0) return null;
     }
-    const pool = st.bag;
+    const pool = st.bag.filter((id2) => eligibleIds.has(id2));
     const p = st.last !== void 0 && pool.length > 1 ? pool.indexOf(st.last) : -1;
     let i = Math.floor(this.rng() * (p >= 0 ? pool.length - 1 : pool.length));
     if (p >= 0 && i >= p) i++;
     const id = pool[i];
-    pool.splice(i, 1);
+    st.bag.splice(st.bag.indexOf(id), 1);
     st.last = id;
     return eligible.find((c) => c.id === id);
   }
@@ -1607,7 +1645,7 @@ var Flow = class {
   /** A child's Best-match score against the current state: 0 when it has no condition (the filler
    *  tier), else the specificity of its (already-passing) condition. */
   specScore(node) {
-    return node.condition ? this.matchedSpec(this.conditionAst(node.condition), true) : 0;
+    return node.condition ? this.matchedSpec(this.conditionAst(node.condition), true, node) : 0;
   }
   /**
    * The **matched-specificity** metric (parity contract): how many atomic constraints are actively
@@ -1617,8 +1655,15 @@ var Flow = class {
    * to hold?" (true at the root). Only `and`/`or`/`not`/`check_flags` are structural; every other
    * node (comparisons, scoped vars, literals, other calls) is an atom, evaluated whole.
    */
-  matchedSpec(node, want) {
-    const evalTruthy = (n) => truthy((0, import_expr.evaluate)(n, this.context(), import_dialect.patterDialect));
+  matchedSpec(node, want, owner) {
+    const evalTruthy = (n) => {
+      try {
+        return truthy((0, import_expr.evaluate)(n, this.context(), import_dialect.patterDialect));
+      } catch (err) {
+        this.reportError("best-match", owner.id, owner.condition, err);
+        return false;
+      }
+    };
     return (0, import_expr_specificity.matchedSpecificity)(node, evalTruthy, { want });
   }
   /** A selector's cursor state - shared across flows (`group.shared`) or this flow's own. */
@@ -1650,17 +1695,36 @@ var Flow = class {
     return st;
   }
   // -- Effects + expressions ------------------------------------------------
-  runEffects(effects) {
+  /** Run an effect list. `owner` is the snippet or scene it belongs to, for an error report. */
+  runEffects(effects, owner) {
     for (const e of effects ?? []) {
-      const value = this.evalExpr(e.value);
-      const prev = this.host.logEnabled ? this.getProperty(e.target) : void 0;
-      this.writeProperty(e.target, value, false);
-      this.emit({ type: "write", target: e.target, value, ...prev !== void 0 ? { prev } : {} });
+      let value;
+      try {
+        value = this.evalExpr(e.value);
+        const prev = this.host.tracing ? this.getProperty(e.target) : void 0;
+        this.writeProperty(e.target, value, false);
+        if (this.host.tracing) this.emit({ type: "write", target: e.target, value, ...prev !== void 0 ? { prev } : {} });
+      } catch (err) {
+        this.reportError("effect", owner, e.value, err);
+      }
     }
   }
+  /** Whether a node's condition holds. A condition that fails to evaluate counts as false (see PlayError). */
   eligible(node) {
     if (!node.condition) return true;
-    return truthy(this.evalExpr(node.condition));
+    try {
+      return truthy(this.evalExpr(node.condition));
+    } catch (err) {
+      this.reportError("condition", node.id, node.condition, err);
+      return false;
+    }
+  }
+  /** Report a content error the engine is playing through: to the host's onError, and to the log. */
+  reportError(kind, node, expr, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const source = expr?.src;
+    this.host.onError({ flow: this.id, kind, node, ...source ? { source } : {}, message });
+    if (this.host.tracing) this.emit({ type: "diagnostic", kind, node, ...source ? { source } : {}, message });
   }
   evalExpr(expr) {
     return (0, import_expr.evaluate)(this.conditionAst(expr), this.context(), import_dialect.patterDialect);
@@ -1856,23 +1920,23 @@ var Flow = class {
     if (!this.sceneBags.has(s)) {
       const bag = new import_scoperegistry2.PropertyBag(props.filter((d) => !shared.has(d.name.toLowerCase())), { pathPrefix: "@scene." });
       const key = keys.flowScene(this.id, s);
-      this.host.registry.mountOwned(key, bag, { owner: OWNER });
+      const claimed = mountClaims(this.host.registry, key, bag, journal !== null);
       this.registered.add(key);
       this.sceneBags.set(s, bag);
       if (journal) journal.undo.push(() => {
         if (this.sceneBags.get(s) !== bag) return;
-        this.host.registry.remove(key);
+        this.host.registry.remove(key, claimed ? { keep: true } : void 0);
         this.registered.delete(key);
         this.sceneBags.delete(s);
       });
     }
     if (!this.host.stageBags.has(s)) {
       const bag = new import_scoperegistry2.PropertyBag(props.filter((d) => shared.has(d.name.toLowerCase())), { pathPrefix: "@scene." });
-      this.host.registry.mountOwned(keys.stage(s), bag, { owner: OWNER });
+      const claimed = mountClaims(this.host.registry, keys.stage(s), bag, journal !== null);
       this.host.stageBags.set(s, bag);
       if (journal) journal.undo.push(() => {
         if (this.host.stageBags.get(s) !== bag) return;
-        this.host.registry.remove(keys.stage(s));
+        this.host.registry.remove(keys.stage(s), claimed ? { keep: true } : void 0);
         this.host.stageBags.delete(s);
       });
     }
@@ -1939,9 +2003,29 @@ function deserialiseSelectors(rec) {
   }
   return map;
 }
+function mountClaims(registry, key, bag, ask) {
+  const before = ask ? JSON.stringify(bag.save()) : "";
+  registry.mountOwned(key, bag, { owner: OWNER });
+  return ask && JSON.stringify(bag.save()) !== before;
+}
 function toDecl(decl) {
   return { name: decl.name, type: decl.type, values: decl.values, stages: decl.stages, default: decl.default };
 }
+function boundScopes(options) {
+  return { ...options.world ? { world: options.world } : {}, ...options.hostScopes };
+}
+function ladders(host, cacheKey, decls) {
+  let found = host.qualityLadders.get(cacheKey);
+  if (!found) {
+    found = /* @__PURE__ */ new Map();
+    for (const d of decls() ?? []) {
+      const k = d.name.toLowerCase();
+      if (d.type === "quality" && d.stages && !found.has(k)) found.set(k, d.stages);
+    }
+    host.qualityLadders.set(cacheKey, found);
+  }
+  return found;
+}
 function toForeignDecl(decl) {
   return { name: decl.name, type: decl.type, values: decl.values, stages: decl.stages, default: decl.default, writable: decl.writable };
 }
@@ -1950,6 +2034,12 @@ function selfBackedDecl(decl, scopeWritable) {
   const writable = decl.writable ?? scopeWritable;
   return writable === void 0 ? d : { ...d, writable };
 }
+function resolveScene(host, ref) {
+  return host.sceneGameIdToId.get(ref) ?? (host.bundle.scenes[ref] ? ref : void 0);
+}
+function resolveBlock(host, sceneId, ref) {
+  return host.blockGameIdToId.get(sceneId)?.get(ref) ?? (host.blockIndex.get(ref)?.sceneId === sceneId ? ref : void 0);
+}
 function splitHostRef(host, ref) {
   if (host.refSplitRevision !== host.registry.revision) {
     host.refSplitCache.clear();