@storylet-studio/runtime 0.8.1 → 0.8.2

package/dist/index.js

@@ -1,933 +1,20 @@
-// ../../../expr/packages/expr/src/ast.ts
-function deserialiseAst(node) {
-  switch (node[0]) {
-    case "b":
-      return { kind: "bool", value: node[1] };
-    case "n":
-      return { kind: "number", value: node[1] };
-    case "s":
-      return { kind: "string", value: node[1] };
-    case "sv":
-      return { kind: "scopedvar", scope: node[1], name: node[2] };
-    case "u":
-      return { kind: "unary", op: node[1], operand: deserialiseAst(node[2]) };
-    case "bin":
-      return { kind: "binary", op: node[1], left: deserialiseAst(node[2]), right: deserialiseAst(node[3]) };
-    case "call": {
-      const args = node.slice(2).map(deserialiseAst);
-      return { kind: "call", name: node[1], args };
-    }
-    case "fd":
-      return { kind: "flagdelta", sign: node[1], name: node[2] };
-  }
-}
-
-// ../../../expr/packages/expr/src/evaluate.ts
-var EvalError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "EvalError";
-  }
-};
-function evaluate(node, ctx, dialect) {
-  const missingPolicy = new Map(
-    dialect.scopes.map((s) => [s.token, s.missing ?? "false"])
-  );
-  const rec = (n) => {
-    switch (n.kind) {
-      case "bool":
-        return n.value;
-      case "number":
-        return n.value;
-      case "string":
-        return n.value;
-      case "scopedvar": {
-        const scope = ctx.scopes[n.scope];
-        if (scope === void 0) {
-          return false;
-        }
-        const val = typeof scope.get === "function" ? scope.get(n.name) : scope[n.name];
-        if (val === void 0) {
-          if (missingPolicy.get(n.scope) === "throw") {
-            throw new EvalError(`@${n.scope}.${n.name} is not declared on the current ${n.scope}.`);
-          }
-          return false;
-        }
-        return val;
-      }
-      case "call": {
-        if (n.name === "advance" && !dialect.functions[n.name]) {
-          const arg = n.args[0];
-          if (n.args.length !== 1 || arg === void 0) {
-            throw new EvalError(`advance() takes exactly 1 argument, got ${n.args.length}`);
-          }
-          const ladder = ladderOf(arg, ctx);
-          if (ladder === void 0) {
-            throw new EvalError("advance() needs a quality reference (@scope.name of a quality property)");
-          }
-          const current = stageIndex(rec(arg), ladder, "advance");
-          return ladder[Math.min(current + 1, ladder.length - 1)];
-        }
-        const def = dialect.functions[n.name];
-        if (!def) throw new EvalError(`unknown function '${n.name}'`);
-        return def.eval(n.args, { evaluate: rec, ctx });
-      }
-      case "flagdelta":
-        throw new EvalError("flagdelta node is only valid as an argument to a flag-delta function");
-      case "unary": {
-        if (n.op === "not") {
-          const val2 = rec(n.operand);
-          if (typeof val2 !== "boolean") throw new EvalError(`'not' requires a boolean operand, got ${typeof val2}`);
-          return !val2;
-        }
-        const val = rec(n.operand);
-        if (typeof val !== "number") throw new EvalError(`unary '-' requires a numeric operand, got ${typeof val}`);
-        return -val;
-      }
-      case "binary": {
-        if (n.op === "and") {
-          const l = rec(n.left);
-          if (typeof l !== "boolean") throw new EvalError(`'and' requires boolean operands, left is ${typeof l}`);
-          if (!l) return false;
-          const r = rec(n.right);
-          if (typeof r !== "boolean") throw new EvalError(`'and' requires boolean operands, right is ${typeof r}`);
-          return r;
-        }
-        if (n.op === "or") {
-          const l = rec(n.left);
-          if (typeof l !== "boolean") throw new EvalError(`'or' requires boolean operands, left is ${typeof l}`);
-          if (l) return true;
-          const r = rec(n.right);
-          if (typeof r !== "boolean") throw new EvalError(`'or' requires boolean operands, right is ${typeof r}`);
-          return r;
-        }
-        const left = rec(n.left);
-        const right = rec(n.right);
-        const lLadder = ladderOf(n.left, ctx);
-        const rLadder = ladderOf(n.right, ctx);
-        const ladder = lLadder ?? rLadder;
-        if (ladder !== void 0) {
-          if (lLadder && rLadder && !sameLadder(lLadder, rLadder)) {
-            if (n.op === ">" || n.op === ">=" || n.op === "<" || n.op === "<=") {
-              throw new EvalError(`'${n.op}' compares two different qualities, whose stage orders are unrelated`);
-            }
-          }
-          switch (n.op) {
-            case ">":
-              return stageIndex(left, ladder, ">") > stageIndex(right, ladder, ">");
-            case ">=":
-              return stageIndex(left, ladder, ">=") >= stageIndex(right, ladder, ">=");
-            case "<":
-              return stageIndex(left, ladder, "<") < stageIndex(right, ladder, "<");
-            case "<=":
-              return stageIndex(left, ladder, "<=") <= stageIndex(right, ladder, "<=");
-            case "+":
-            case "-":
-            case "*":
-            case "/":
-              throw new EvalError(`'${n.op}' cannot be applied to a quality - a stage is a position, not a number; use advance() to move it`);
-            default:
-              break;
-          }
-        }
-        switch (n.op) {
-          case "==":
-            return valueEquals(left, right);
-          case "!=":
-            return !valueEquals(left, right);
-          case ">":
-            assertNumbers(left, right, ">");
-            return left > right;
-          case ">=":
-            assertNumbers(left, right, ">=");
-            return left >= right;
-          case "<":
-            assertNumbers(left, right, "<");
-            return left < right;
-          case "<=":
-            assertNumbers(left, right, "<=");
-            return left <= right;
-          case "+":
-            if (typeof left === "number" && typeof right === "number") return left + right;
-            if (typeof left === "string" && typeof right === "string") return left + right;
-            throw new EvalError(`'+' requires two numbers or two strings, got ${typeof left} and ${typeof right}`);
-          case "-":
-            assertNumbers(left, right, "-");
-            return left - right;
-          case "*":
-            assertNumbers(left, right, "*");
-            return left * right;
-          case "/":
-            assertNumbers(left, right, "/");
-            if (right === 0) throw new EvalError("division by zero");
-            return left / right;
-        }
-      }
-    }
-  };
-  return rec(node);
-}
-function valueEquals(a, b) {
-  if (Array.isArray(a) || Array.isArray(b)) {
-    if (!Array.isArray(a) || !Array.isArray(b)) return false;
-    if (a.length !== b.length) return false;
-    const x = [...a].sort();
-    const y = [...b].sort();
-    for (let i = 0; i < x.length; i++) if (x[i] !== y[i]) return false;
-    return true;
-  }
-  return a === b;
-}
-function assertNumbers(l, r, op) {
-  if (typeof l !== "number" || typeof r !== "number") {
-    throw new EvalError(`'${op}' requires numeric operands, got ${typeof l} and ${typeof r}`);
-  }
-}
-function ladderOf(node, ctx) {
-  if (node.kind !== "scopedvar" || ctx.qualities === void 0) return void 0;
-  return ctx.qualities(node.scope, node.name);
-}
-function stageIndex(value, ladder, op) {
-  if (typeof value !== "string") {
-    throw new EvalError(`'${op}' on a quality compares stages, got ${typeof value}`);
-  }
-  const i = ladder.indexOf(value);
-  if (i < 0) throw new EvalError(`"${value}" is not a stage of this quality (stages: ${ladder.join(", ")})`);
-  return i;
-}
-var sameLadder = (a, b) => a.length === b.length && a.every((x, i) => x === b[i]);
-
-// ../../../expr/packages/expr/src/prng.ts
-function toUint32(seed) {
-  if (Number.isNaN(seed) || !Number.isFinite(seed)) return 0;
-  const modded = Math.trunc(seed) % 4294967296;
-  return modded < 0 ? modded + 4294967296 : modded;
-}
-function makePrng(seed) {
-  let s = toUint32(seed);
-  return {
-    next() {
-      s = s + 1831565813 >>> 0;
-      let t = Math.imul(s ^ s >>> 15, 1 | s);
-      t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
-      return ((t ^ t >>> 14) >>> 0) / 4294967296;
-    },
-    state() {
-      return s;
-    }
-  };
-}
-function shuffleInPlace(arr, prng) {
-  for (let i = arr.length - 1; i > 0; i--) {
-    const j = Math.floor(prng.next() * (i + 1));
-    [arr[i], arr[j]] = [arr[j], arr[i]];
-  }
-}
-
-// ../../../expr/packages/expr-specificity/src/index.ts
-var CHECK_FLAGS_COUNTING_CALL = {
-  name: "check_flags",
-  count: (node) => Math.max(1, node.args.length - 1)
-};
-var DEFAULT_COUNTING_CALLS = [CHECK_FLAGS_COUNTING_CALL];
-function matchedSpecificity(node, evalTruthy, opts) {
-  const countingCalls = opts?.countingCalls ?? DEFAULT_COUNTING_CALLS;
-  return walk(node, opts?.want ?? true, evalTruthy, countingCalls);
-}
-function walk(node, want, evalTruthy, countingCalls) {
-  if (node.kind === "binary" && (node.op === "and" || node.op === "or")) {
-    const l = walk(node.left, want, evalTruthy, countingCalls);
-    const r = walk(node.right, want, evalTruthy, countingCalls);
-    const behaveAsAnd = node.op === "and" === want;
-    if (behaveAsAnd) return l > 0 && r > 0 ? l + r : 0;
-    return Math.max(l, r);
-  }
-  if (node.kind === "unary" && node.op === "not") {
-    return walk(node.operand, !want, evalTruthy, countingCalls);
-  }
-  if (node.kind === "call") {
-    const rule = countingCalls.find((c) => c.name === node.name);
-    if (rule) {
-      const operands = rule.count(node);
-      const holds = evalTruthy(node);
-      if (want) return holds ? operands : 0;
-      return holds ? 0 : 1;
-    }
-  }
-  return evalTruthy(node) === want ? 1 : 0;
-}
-
-// ../dialect/src/engine-scopes.ts
-var ENGINE_SCOPES = [
-  { token: "patter", engine: "Patterplay", means: "Patter's shared globals" },
-  { token: "story", engine: "Storylet Engine", means: "the Storylet Engine's shared @story properties" }
-];
-
-// ../dialect/src/index.ts
-var NEVER_PLAYED = 9999;
-var host = (h) => h.ctx.host ?? {};
-var stringArg = (fn, args, h, i) => {
-  const v = h.evaluate(args[i]);
-  if (typeof v !== "string" || v === "") {
-    throw new EvalError(`${fn}() argument ${i + 1} must be a non-empty string`);
-  }
-  return v;
-};
-var flagsArg = (fn, args, h) => {
-  if (args.length === 0) {
-    throw new EvalError(`${fn}() requires at least one argument (the flags property)`);
-  }
-  const v = h.evaluate(args[0]);
-  if (Array.isArray(v)) return v;
-  if (v === false) return [];
-  throw new EvalError(`${fn}() first argument must be a flags property`);
-};
-var OWN_SCOPES = ["story", "world", "box", "deck", "hand"];
-var EXTERNAL_SCOPES = ENGINE_SCOPES.map((s) => s.token).filter((t) => !OWN_SCOPES.includes(t));
-var storyletsDialect = {
-  // A missing property in a PRESENT scope is always an error: every property
-  // is declared with a default, so absence means a publish bug, a drifted
-  // save, or a foreign scope the host never fed (schema 6.2). The same holds
-  // for another engine's scope: `@patter.glod` is a typo, and it says so the
-  // first time the card is evaluated rather than quietly reading false.
-  scopes: [
-    ...OWN_SCOPES.map((token) => ({ token, missing: "throw" })),
-    ...EXTERNAL_SCOPES.map((token) => ({ token, missing: "throw" }))
-  ],
-  defaultScope: "story",
-  functions: {
-    random: {
-      minArgs: 2,
-      maxArgs: 2,
-      returnType: "number",
-      eval(args, h) {
-        if (args.length !== 2) throw new EvalError("random(a, b) requires exactly 2 arguments");
-        const nextRandom = host(h).nextRandom;
-        if (!nextRandom) throw new EvalError("random() called without a PRNG in context");
-        const a = h.evaluate(args[0]);
-        const b = h.evaluate(args[1]);
-        if (typeof a !== "number" || typeof b !== "number") {
-          throw new EvalError("random(a, b) arguments must be numbers");
-        }
-        if (!Number.isInteger(a) || !Number.isInteger(b)) {
-          throw new EvalError("random(a, b) arguments must be integers");
-        }
-        const lo = Math.min(a, b);
-        const hi = Math.max(a, b);
-        return Math.floor(nextRandom() * (hi - lo + 1)) + lo;
-      }
-    },
-    check_flags: {
-      minArgs: 1,
-      returnType: "boolean",
-      flagDeltaArgs: true,
-      eval(args, h) {
-        const flags = flagsArg("check_flags", args, h);
-        for (let i = 1; i < args.length; i++) {
-          const arg = args[i];
-          if (arg.kind !== "flagdelta") {
-            throw new EvalError("check_flags() flag args must be +flagName or -flagName");
-          }
-          if (arg.sign === "+" ? !flags.includes(arg.name) : flags.includes(arg.name)) {
-            return false;
-          }
-        }
-        return true;
-      }
-    },
-    set_flags: {
-      minArgs: 1,
-      returnType: "flags",
-      flagDeltaArgs: true,
-      eval(args, h) {
-        const result = [...flagsArg("set_flags", args, h)];
-        for (let i = 1; i < args.length; i++) {
-          const arg = args[i];
-          if (arg.kind !== "flagdelta") {
-            throw new EvalError("set_flags() flag args must be +flagName or -flagName");
-          }
-          if (arg.sign === "+") {
-            if (!result.includes(arg.name)) result.push(arg.name);
-          } else {
-            const idx = result.indexOf(arg.name);
-            if (idx >= 0) result.splice(idx, 1);
-          }
-        }
-        return result.sort();
-      }
-    },
-    count_played: {
-      minArgs: 1,
-      maxArgs: 1,
-      returnType: "number",
-      eval(args, h) {
-        const card = stringArg("count_played", args, h, 0);
-        const fn = host(h).countPlayed;
-        if (!fn) throw new EvalError("count_played() called without a play log in context");
-        return fn(card);
-      }
-    },
-    turns_since_played: {
-      minArgs: 1,
-      maxArgs: 1,
-      returnType: "number",
-      eval(args, h) {
-        const card = stringArg("turns_since_played", args, h, 0);
-        const fn = host(h).turnsSincePlayed;
-        if (!fn) throw new EvalError("turns_since_played() called without a play log in context");
-        return fn(card);
-      }
-    },
-    count_played_in: {
-      minArgs: 2,
-      maxArgs: 2,
-      returnType: "number",
-      eval(args, h) {
-        const dimension = stringArg("count_played_in", args, h, 0);
-        const value = stringArg("count_played_in", args, h, 1);
-        const fn = host(h).countPlayedIn;
-        if (!fn) throw new EvalError("count_played_in() called without a play log in context");
-        return fn(dimension, value);
-      }
-    },
-    turns_since_played_in: {
-      minArgs: 2,
-      maxArgs: 2,
-      returnType: "number",
-      eval(args, h) {
-        const dimension = stringArg("turns_since_played_in", args, h, 0);
-        const value = stringArg("turns_since_played_in", args, h, 1);
-        const fn = host(h).turnsSincePlayedIn;
-        if (!fn) throw new EvalError("turns_since_played_in() called without a play log in context");
-        return fn(dimension, value);
-      }
-    }
-  }
-};
-
-// ../model/src/index.ts
-function gameIdify(text) {
-  return text.toLowerCase().replace(/['’]/g, "").replace(/[^a-z0-9-]+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
-}
-function effectiveGameId(entity) {
-  const pinned = entity.gameId?.trim();
-  if (pinned) return pinned;
-  const fromTitle = entity.title ? gameIdify(entity.title) : "";
-  return fromTitle || entity.id;
-}
-function valueAddresses(bundle) {
-  const tags = [];
-  for (const box of bundle.boxes) {
-    const boxGameId = effectiveGameId(box);
-    for (const group of box.tagGroups) {
-      for (const tag of group.tags) {
-        const gameId = effectiveGameId(tag);
-        tags.push({ id: tag.id, gameId, qualified: `${boxGameId}/${gameId}` });
-      }
-    }
-  }
-  const forms = /* @__PURE__ */ new Map();
-  for (const tag of tags) {
-    const list = forms.get(tag.gameId) ?? [];
-    if (!list.includes(tag.qualified)) list.push(tag.qualified);
-    forms.set(tag.gameId, list);
-  }
-  const print = /* @__PURE__ */ new Map();
-  const accept = /* @__PURE__ */ new Map();
-  const repeated = /* @__PURE__ */ new Map();
-  for (const tag of tags) {
-    const candidates = forms.get(tag.gameId) ?? [tag.qualified];
-    const ambiguous = candidates.length > 1;
-    print.set(tag.id, ambiguous ? tag.qualified : tag.gameId);
-    if (!accept.has(tag.qualified)) accept.set(tag.qualified, tag.id);
-    if (!ambiguous && !accept.has(tag.gameId)) accept.set(tag.gameId, tag.id);
-    if (ambiguous) repeated.set(tag.gameId, candidates);
-  }
-  return { print, accept, repeated };
-}
-function ambiguousValueAddressMessage(segment, name, candidates) {
-  const forms = candidates.map((q) => `"value.${q}.${name}"`);
-  const list = forms.length <= 1 ? forms[0] ?? "" : `${forms.slice(0, -1).join(", ")} or ${forms[forms.length - 1]}`;
-  return `"value.${segment}.${name}" names a tag in ${candidates.length} boxes; write ${list}`;
-}
-var PLACE_GROUP = "place";
-var HOLE_REF = /^@(hand|world|story)\.([a-z][a-z0-9_-]*)$/;
-var isHoleRef = (value) => value.startsWith("@");
-var parseHoleRef = (value) => {
-  const m = HOLE_REF.exec(value);
-  return m === null ? void 0 : { scope: m[1], name: m[2] };
-};
-var SAVE_SCHEMA = "storylets/save@2";
-var SAVE_SCHEMA_V1 = "storylets/save@1";
+// src/engine.ts
+import { deserialiseAst, evaluate } from "@wildwinter/expr";
+import { matchedSpecificity } from "@wildwinter/expr-specificity";
+import { storyletsDialect, NEVER_PLAYED } from "@storylet-studio/dialect";
+import {
+  PLACE_GROUP,
+  ambiguousValueAddressMessage,
+  effectiveGameId,
+  isHoleRef,
+  parseHoleRef,
+  valueAddresses
+} from "@storylet-studio/model";
+import { SAVE_SCHEMA, SAVE_SCHEMA_V1 } from "@storylet-studio/model";
+import { PropertyBag as StateBag, ScopeRegistry } from "@wildwinter/scoperegistry";
 
-// ../../../expr/packages/scoperegistry/src/index.ts
-var PropertyBag = class _PropertyBag {
-  /** The live values record (stable identity across reseed, so an
-   *  EvalContext built over it stays valid). Read-path for evaluation;
-   *  writes go through `set` so the firing rule applies. */
-  values = {};
-  decls = /* @__PURE__ */ new Map();
-  subscribers = /* @__PURE__ */ new Set();
-  auditors = /* @__PURE__ */ new Set();
-  /** Name normalisation policy: lowercase by default (the registry's
-   *  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) {
-    for (const d of declarations) {
-      const name = this.norm(d.name);
-      this.decls.set(name, d);
-      this.values[name] = structuredClone(d.default ?? defaultFor(d));
-    }
-  }
-  get(name) {
-    return this.values[this.norm(name)];
-  }
-  /** A name as this bag keys it: its normalisation policy applied. The registry
-   *  uses it to key quality ladders and the validation schema the bag's own way,
-   *  so a case-significant (identity) bag is not quietly folded to lower case
-   *  one layer up. */
-  normalise(name) {
-    return this.norm(name);
-  }
-  /** Write a property. Engine writes (the default) notify subscribers;
-   *  pass `silent: true` for a host write, which reaches only the audit
-   *  hook. Throws on a read-only property unless the caller says it is the
-   *  HOST (`host: true`), for whom `writable: false` was never a rule - it is
-   *  the story's promise, not the game's. `silent` and `host` are separate on
-   *  purpose: one is about who hears the write, the other about who may make
-   *  it. Returns the change. */
-  set(name, value, opts) {
-    const n = this.norm(name);
-    if (!opts?.host && this.decls.get(n)?.writable === false) throw new Error(`'${name}' is read-only`);
-    const change = {
-      name: n,
-      prev: this.values[n],
-      next: value,
-      silent: opts?.silent ?? false,
-      reason: opts?.reason
-    };
-    this.values[n] = value;
-    for (const audit of this.auditors) audit(change);
-    if (!change.silent) for (const fn of this.subscribers) fn(change);
-    return change;
-  }
-  /** Notified of engine (non-silent) writes. Returns the unsubscribe. */
-  subscribe(fn) {
-    this.subscribers.add(fn);
-    return () => this.subscribers.delete(fn);
-  }
-  /** Notified of EVERY write, silent or not. Returns the unsubscribe. */
-  onAudit(fn) {
-    this.auditors.add(fn);
-    return () => this.auditors.delete(fn);
-  }
-  /** 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, this.pathPrefix));
-  }
-  declarations() {
-    return [...this.decls.values()];
-  }
-  /** The one sanctioned copy door: values deep-copied, declarations
-   *  duplicated, the normalisation policy carried, subscriptions NOT
-   *  carried. */
-  clone() {
-    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;
-  }
-  /** Clear and re-seed from new declarations, in place (the values record
-   *  keeps its identity, so contexts built over it stay valid). */
-  reseed(declarations) {
-    for (const k of Object.keys(this.values)) delete this.values[k];
-    this.decls.clear();
-    this.seed(declarations);
-  }
-  /** Bare values, ready to embed in a product's save. */
-  save() {
-    return structuredClone(this.values);
-  }
-  /** Lay saved values over the current ones (call after a fresh seed:
-   *  orphans land as strays, new declarations keep their defaults; the
-   *  product decides whether to prune). Does not fire events. */
-  load(values) {
-    for (const [k, v] of Object.entries(values)) this.values[this.norm(k)] = v;
-  }
-};
-function rowFor(d, value, writable, name, pathPrefix = "") {
-  const rowName = name ?? d.name.toLowerCase();
-  return {
-    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
-  };
-}
-var lowerCase = (name) => name.toLowerCase();
-var SAVE_FRAGMENT_VERSION = 1;
-var ScopeRegistry = class {
-  scopes = /* @__PURE__ */ new Map();
-  /** Values loaded for keys nobody has registered yet, waiting to be claimed. */
-  parked = /* @__PURE__ */ new Map();
-  rev = 0;
-  /**
-   * A counter that moves whenever a scope is registered or removed, and at no
-   * other time: it starts at 0 and each registration or removal adds 1. Values
-   * changing does not move it. A caller that caches a context built by
-   * `toEvalContext()` rebuilds it when this moves, because the context's set of
-   * scopes is fixed when it is built while the values it reads stay live.
-   */
-  get revision() {
-    return this.rev;
-  }
-  /**
-   * Register a scope this registry **owns and stores**. Its bag is seeded from
-   * each declaration's `default` (or a type default). Owned scopes are
-   * type-checked (declarations) and serialized by `save`/`load`.
-   *
-   * The third argument may be the path prefix alone (the pre-0.7 form) or an
-   * options object.
-   */
-  defineOwned(token, declarations, opts) {
-    const o = typeof opts === "string" ? { pathPrefix: opts } : opts ?? {};
-    const bag = new PropertyBag(declarations, {
-      pathPrefix: o.pathPrefix ?? `${token}.`,
-      ...o.normalise ? { normalise: o.normalise } : {}
-    });
-    return this.mountOwned(token, bag, o.owner !== void 0 ? { owner: o.owner } : void 0);
-  }
-  /**
-   * Attach an EXISTING bag as an owned scope: an engine (or a host) holds the
-   * bag and this registry reads, writes, lists and saves it like its own.
-   *
-   * If values were loaded for this key before anyone registered it, the bag
-   * claims them now: laid over its seeded defaults by the bag's own `load` rule.
-   */
-  mountOwned(token, bag, opts) {
-    this.assertFree(token, opts?.owner);
-    this.scopes.set(token, { kind: "owned", bag, ...opts?.owner !== void 0 ? { owner: opts.owner } : {} });
-    this.rev++;
-    const waiting = this.parked.get(token);
-    if (waiting) {
-      bag.load(waiting);
-      this.parked.delete(token);
-    }
-    return this;
-  }
-  /**
-   * Unregister a scope. With `{ keep: true }` an owned scope's values are parked
-   * and handed back when the same key is next registered, which is how a live
-   * reload hands an engine's state to its replacement. Throws on an unknown key.
-   */
-  remove(token, opts) {
-    const e = this.scopes.get(token);
-    if (!e) throw new Error(`unknown scope '@${token}'`);
-    if (opts?.keep && e.kind === "owned") this.parked.set(token, e.bag.save());
-    this.scopes.delete(token);
-    this.rev++;
-    return this;
-  }
-  /**
-   * Drop parked values nobody claimed. Parked values are kept in the next save by
-   * default, so nothing loaded is lost to a flow or deck that simply has not
-   * reopened yet; a game that knows they are dead drops them here.
-   *
-   * With a `prefix`, only keys starting with it are dropped: an engine resetting
-   * itself drops its own instance keys (`my-engine/`) and leaves every other
-   * engine's alone.
-   */
-  discardParked(prefix) {
-    if (prefix === void 0) this.parked.clear();
-    else for (const key of [...this.parked.keys()]) if (key.startsWith(prefix)) this.parked.delete(key);
-    return this;
-  }
-  /** An owned scope's bag (subscribe, audit, rows live there). */
-  ownedBag(token) {
-    const e = this.scopes.get(token);
-    if (!e || e.kind !== "owned") throw new Error(`'@${token}' is not an owned scope`);
-    return e.bag;
-  }
-  /**
-   * Re-initialise an existing **owned** scope's bag from new declarations,
-   * clearing its current values. For scope-local state that resets on a context
-   * change (e.g. entering a new scene / site / deck) without disturbing other
-   * scopes. Mutates the bag in place, so an `EvalContext` already built from this
-   * registry stays valid.
-   */
-  reseedOwned(token, declarations) {
-    this.ownedBag(token).reseed(declarations);
-    return this;
-  }
-  /**
-   * Register a **foreign** scope backed by a host `{ get, set? }` resolver. The
-   * values live in the host/other engine and are never stored or saved here.
-   * `declarations` (optional, e.g. imported from a `scopeRegistrySpec`) are used
-   * only for validation; omit them for an opaque scope.
-   */
-  defineForeign(token, resolver, declarations = [], opts = true) {
-    const o = typeof opts === "boolean" ? { writable: opts } : opts;
-    this.assertFree(token, o.owner);
-    const norm = o.normalise ?? lowerCase;
-    const decls = /* @__PURE__ */ new Map();
-    for (const d of declarations) decls.set(norm(d.name), d);
-    this.scopes.set(token, {
-      kind: "foreign",
-      resolver,
-      decls,
-      scopeWritable: o.writable ?? true,
-      norm,
-      ...o.owner !== void 0 ? { owner: o.owner } : {}
-    });
-    this.rev++;
-    return this;
-  }
-  has(token) {
-    return this.scopes.has(token);
-  }
-  /** Read a property; undefined if the scope or property is not present. */
-  get(scope, name) {
-    const e = this.scopes.get(scope);
-    if (!e) return void 0;
-    return e.kind === "owned" ? e.bag.get(name) : e.resolver.get(e.norm(name));
-  }
-  /** Write a property (an ENGINE write: the bag's subscribers fire; use
-   *  the bag directly for silent host writes). Throws on an unknown scope.
-   *
-   *  `writable: false` is the STORY's promise, so a story write is refused and
-   *  a HOST write is not: pass `{ host: true }` from a host's own surface (its
-   *  `setProperty`, its tooling, a coverage driver) and never from the path an
-   *  outcome or effect takes. A foreign scope whose resolver has no `set` is
-   *  refused for everyone, host included - that is not a rule to bypass, it is
-   *  a game that gave no way to write. */
-  set(scope, name, value, opts) {
-    const e = this.scopes.get(scope);
-    if (!e) throw new Error(`unknown scope '@${scope}'`);
-    if (e.kind === "owned") {
-      try {
-        e.bag.set(name, value, opts?.host ? { host: true } : void 0);
-      } catch {
-        throw new Error(`'@${scope}.${name}' is read-only`);
-      }
-      return;
-    }
-    const n = e.norm(name);
-    if (!e.resolver.set) throw new Error(`'@${scope}.${name}' is read-only`);
-    if (!opts?.host && !this.foreignWritable(e, n)) throw new Error(`'@${scope}.${name}' is read-only`);
-    e.resolver.set(n, value);
-  }
-  foreignWritable(e, name) {
-    if (!e.resolver.set) return false;
-    return e.decls.get(name)?.writable ?? e.scopeWritable;
-  }
-  /** Examiner rows across every scope with a declared surface: owned bags
-   *  first, then declared foreign scopes (values read through, writability
-   *  reflecting the resolver). Opaque foreign scopes are not listed. */
-  listProperties() {
-    const out = [];
-    for (const [token, e] of this.scopes) {
-      const owner = e.owner !== void 0 ? { owner: e.owner } : {};
-      if (e.kind === "owned") {
-        for (const row of e.bag.rows()) out.push({ scope: token, ...owner, ...row });
-      } else {
-        for (const [n, d] of e.decls) {
-          out.push({
-            scope: token,
-            ...owner,
-            ...rowFor(d, e.resolver.get(n), this.foreignWritable(e, n), n, `${token}.`)
-          });
-        }
-      }
-    }
-    return out;
-  }
-  /**
-   * Build the `EvalContext` expr's `evaluate` consumes: owned scopes as static
-   * bags, foreign scopes as their resolvers. `host` carries dialect-function
-   * callbacks (PRNG, tag lookups) and is passed through untouched.
-   */
-  toEvalContext(host2, opts) {
-    const view = this.view(opts?.aliases);
-    const scopes = {};
-    for (const [token, e] of view) scopes[token] = e.kind === "owned" ? e.bag.values : e.resolver;
-    const qualities = this.qualityLadders(view);
-    return qualities.size === 0 ? { scopes, host: host2 } : {
-      scopes,
-      host: host2,
-      qualities: (scope, name) => {
-        const e = view.get(scope);
-        return e ? qualities.get(scope)?.get(normOf(e)(name)) : void 0;
-      }
-    };
-  }
-  /**
-   * The scopes an expression sees: every registered key under its own token,
-   * then each alias token pointing at its key's entry (an alias shadows a key of
-   * the same name). Keys an engine uses for instance bags (`engine/flow-2/...`)
-   * are not valid expression tokens, so they are present but unreachable.
-   */
-  view(aliases) {
-    const out = new Map(this.scopes);
-    for (const [token, key] of Object.entries(aliases ?? {})) {
-      const e = this.scopes.get(key);
-      if (!e) throw new Error(`alias '@${token}' names '${key}', which is not registered`);
-      out.set(token, e);
-    }
-    return out;
-  }
-  /** Every quality declaration's ladder, keyed scope token then name (the
-   *  scope's own normalisation). */
-  qualityLadders(view) {
-    const out = /* @__PURE__ */ new Map();
-    for (const [token, e] of view) {
-      for (const [n, d] of declsOf(e)) {
-        if (d.type !== "quality" || d.stages === void 0) continue;
-        let m = out.get(token);
-        if (!m) {
-          m = /* @__PURE__ */ new Map();
-          out.set(token, m);
-        }
-        m.set(n, d.stages);
-      }
-    }
-    return out;
-  }
-  /**
-   * Build the `ExpressionSchema` expr's validator consumes. Scopes with no
-   * declarations are **omitted** (opaque - references into them are not flagged);
-   * declared scopes contribute their property types for validation. Aliases
-   * apply as they do to `toEvalContext`, so a condition written against `@scene`
-   * validates against the instance bag the engine names.
-   */
-  toSchema(opts) {
-    const properties = /* @__PURE__ */ new Map();
-    for (const [token, e] of this.view(opts?.aliases)) {
-      const decls = declsOf(e);
-      if (decls.length === 0) continue;
-      const m = /* @__PURE__ */ new Map();
-      for (const [n, d] of decls) m.set(n, {
-        type: d.type,
-        enumValues: d.values,
-        ...d.stages !== void 0 ? { stages: d.stages } : {}
-      });
-      properties.set(token, m);
-    }
-    return { properties };
-  }
-  /** Serialize **owned** scopes (foreign scopes are the game's, and the game
-   *  saves them), as bare bags keyed by token, plus any values still parked, so
-   *  a save taken before every engine has re-registered loses nothing. The
-   *  registry knows nothing about game saves: a game embeds this in its own. */
-  save() {
-    const out = {};
-    for (const [token, e] of this.scopes) if (e.kind === "owned") out[token] = e.bag.save();
-    for (const [token, vals] of this.parked) out[token] = structuredClone(vals);
-    return out;
-  }
-  /**
-   * Restore from a `save` blob. An owned scope lays its section over its current
-   * values (the bag's `load` rule). A section for a key nobody has registered
-   * yet is PARKED and handed over when that key registers, so a game can load
-   * its registry before its engines have reopened their flows or decks. A
-   * section for a foreign scope is ignored: those values are the game's.
-   *
-   * A load replaces whatever was parked before it: it is a whole restore, and
-   * residue from an earlier load must not leak into this one.
-   *
-   * Changed in 0.7.0: sections for unregistered keys used to be dropped.
-   */
-  load(blob, opts) {
-    if (!opts?.keepParked) this.parked.clear();
-    for (const [token, vals] of Object.entries(blob)) {
-      const e = this.scopes.get(token);
-      if (e?.kind === "owned") e.bag.load(vals);
-      else if (!e) this.parked.set(token, structuredClone(vals));
-    }
-  }
-  /**
-   * `save()` wrapped with a version stamp.
-   *
-   * @deprecated Versioning belongs to the save that embeds the values; no
-   * engine ever called this. Embed `save()` in your own versioned save.
-   * Removed at the next breaking release.
-   */
-  saveFragment() {
-    return { version: SAVE_FRAGMENT_VERSION, scopes: this.save() };
-  }
-  /**
-   * Restore from a versioned fragment; an unsupported version throws.
-   *
-   * @deprecated See `saveFragment`. Removed at the next breaking release.
-   */
-  loadFragment(fragment) {
-    if (fragment.version !== SAVE_FRAGMENT_VERSION) {
-      throw new Error(`unsupported owned-state fragment version ${fragment.version} (supported: ${SAVE_FRAGMENT_VERSION})`);
-    }
-    this.load(fragment.scopes);
-  }
-  /**
-   * A token is taken once. There is no reserved-token list: a clash surfaces
-   * here, the moment a game combines its engines, which is the only moment
-   * anyone knows which engines are present. With owners recorded the error says
-   * whose token it already is.
-   */
-  assertFree(token, owner) {
-    const e = this.scopes.get(token);
-    if (!e) return;
-    const by = e.owner !== void 0 ? ` by ${e.owner}` : "";
-    const wants = owner !== void 0 ? ` (wanted by ${owner})` : "";
-    throw new Error(`scope '@${token}' is already registered${by}${wants}`);
-  }
-};
-function declsOf(e) {
-  if (e.kind === "foreign") return [...e.decls.entries()];
-  return e.bag.declarations().map((d) => [e.bag.normalise(d.name), d]);
-}
-function normOf(e) {
-  return e.kind === "foreign" ? e.norm : (n) => e.bag.normalise(n);
-}
-function defaultFor(d) {
-  if (d.default !== void 0) return d.default;
-  switch (d.type) {
-    case "boolean":
-      return false;
-    case "number":
-      return 0;
-    case "string":
-      return "";
-    case "enum":
-      return d.values?.[0] ?? "";
-    case "flags":
-      return [];
-    // 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;
-  }
-}
+// src/prng.ts
+import { makePrng, shuffleInPlace } from "@wildwinter/expr";
 
 // src/engine.ts
 var tagKey = (groupId, tagId) => `${groupId}${tagId}`;
@@ -975,7 +62,7 @@ function sectionsOf(p, keyOf, out) {
     for (const [id, values] of Object.entries(p[kind])) if (Object.keys(values).length > 0) out[keyOf(kind, id)] = values;
   }
 }
-var bagFromDecls = (decls, pathPrefix) => new PropertyBag(decls, { normalise: (n) => n, pathPrefix });
+var bagFromDecls = (decls, pathPrefix) => new StateBag(decls, { normalise: (n) => n, pathPrefix });
 function conditionPasses(v) {
   if (typeof v === "boolean") return v;
   if (typeof v === "number") return v !== 0;
@@ -1332,8 +419,8 @@ var Engine = class _Engine {
         reg.set("world", n, v, { host: true });
       } : void 0;
     } else {
-      internals.worldSet = (n, v, host2) => {
-        reg.set("world", n, v, host2 === true ? { host: true } : void 0);
+      internals.worldSet = (n, v, host) => {
+        reg.set("world", n, v, host === true ? { host: true } : void 0);
       };
     }
   }
@@ -2948,6 +2035,7 @@ var Flow = class {
 };
 
 // src/describe.ts
+import { effectiveGameId as effectiveGameId2, isHoleRef as isHoleRef2 } from "@storylet-studio/model";
 var summarise = (decls) => decls.map((d) => ({
   name: d.name,
   type: d.type,
@@ -2967,10 +2055,10 @@ var movableHoles = (hand, box) => {
   const filled = hand.template !== void 0 ? hand.chosen : hand.rule?.bindings;
   const out = [];
   for (const [groupId, value] of Object.entries(filled ?? {})) {
-    if (!isHoleRef(value)) continue;
+    if (!isHoleRef2(value)) continue;
     const group = box.tagGroups.find((g) => g.id === groupId);
     if (group === void 0) continue;
-    out.push({ group: effectiveGameId(group), from: value });
+    out.push({ group: effectiveGameId2(group), from: value });
   }
   return out;
 };
@@ -2988,7 +2076,7 @@ function describeBundle(bundle) {
   ];
   const totals = { boxes: 0, decks: 0, cards: 0, hands: 0, templates: 0, tagGroups: 0 };
   for (const box of bundle.boxes) {
-    const boxGameId = effectiveGameId(box);
+    const boxGameId = effectiveGameId2(box);
     const cards = box.decks.reduce((n, deck) => n + deck.cards.length, 0);
     boxes.push({
       gameId: boxGameId,
@@ -2997,8 +2085,8 @@ function describeBundle(bundle) {
       ...box.turn !== void 0 ? { turn: { seconds: box.turn.seconds } } : {},
       ...durableCardCount(box) > 0 ? { durableCards: durableCardCount(box) } : {},
       tagGroups: box.tagGroups.map((group) => ({
-        gameId: effectiveGameId(group),
-        tags: group.tags.map((tag) => effectiveGameId(tag))
+        gameId: effectiveGameId2(group),
+        tags: group.tags.map((tag) => effectiveGameId2(tag))
       })),
       counts: {
         decks: box.decks.length,
@@ -3018,11 +2106,11 @@ function describeBundle(bundle) {
       const template = hand.template !== void 0 ? box.handTemplates.find((t) => t.id === hand.template) : void 0;
       const movable = movableHoles(hand, box);
       hands.push({
-        gameId: effectiveGameId(hand),
+        gameId: effectiveGameId2(hand),
         ...hand.title !== void 0 ? { title: hand.title } : {},
         box: boxGameId,
         slots: handSlots(hand, box),
-        ...template !== void 0 ? { template: effectiveGameId(template) } : {},
+        ...template !== void 0 ? { template: effectiveGameId2(template) } : {},
         ...movable.length > 0 ? { movable } : {}
       });
     }
@@ -3037,11 +2125,11 @@ function describeBundle(bundle) {
       });
     };
     push("box", boxGameId, box.properties);
-    for (const deck of box.decks) push("deck", effectiveGameId(deck), deck.properties);
-    for (const hand of box.hands) push("hand", effectiveGameId(hand), handDecls(hand, box));
+    for (const deck of box.decks) push("deck", effectiveGameId2(deck), deck.properties);
+    for (const hand of box.hands) push("hand", effectiveGameId2(hand), handDecls(hand, box));
     for (const group of box.tagGroups) {
       for (const tag of group.tags) {
-        push("tag", effectiveGameId(tag), tag.properties ?? [], effectiveGameId(group));
+        push("tag", effectiveGameId2(tag), tag.properties ?? [], effectiveGameId2(group));
       }
     }
   }