@storylet-studio/runtime 0.2.0

package/dist/index.js

@@ -0,0 +1,1941 @@
+// ../../../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/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 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).
+  scopes: [
+    { token: "story", missing: "throw" },
+    { token: "world", missing: "throw" },
+    { token: "box", missing: "throw" },
+    { token: "deck", missing: "throw" },
+    { token: "hand", 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;
+}
+var PLACE_GROUP = "place";
+
+// ../../../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;
+  constructor(declarations = [], opts) {
+    this.norm = opts?.normalise ?? ((n) => n.toLowerCase());
+    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)];
+  }
+  /** 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. Returns the change. */
+  set(name, value, opts) {
+    const n = this.norm(name);
+    if (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));
+  }
+  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 });
+    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) {
+  return {
+    name: name ?? d.name.toLowerCase(),
+    type: d.type,
+    value,
+    default: d.default ?? defaultFor(d),
+    ...d.values !== void 0 ? { values: d.values } : {},
+    writable: writable ?? d.writable ?? true
+  };
+}
+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] ?? "";
+  }
+}
+
+// src/engine.ts
+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 });
+function conditionPasses(v) {
+  if (typeof v === "boolean") return v;
+  if (typeof v === "number") return v !== 0;
+  if (typeof v === "string") return v !== "";
+  return v.length > 0;
+}
+var SCOPE_DEFAULT_SHARED = { story: true, box: false, deck: false, hand: false, value: false };
+var isShared = (scope, d) => d.shared ?? SCOPE_DEFAULT_SHARED[scope];
+var sharedHalf = (scope, decls) => decls.filter((d) => isShared(scope, d));
+var flowHalf = (scope, decls) => decls.filter((d) => !isShared(scope, d));
+var handDeclsOf = (internals, hand) => {
+  if (hand.template !== void 0) {
+    return internals.templatesById.get(hand.template)?.properties ?? internals.bundle.boxes.flatMap((b) => b.handTemplates).find((t) => t.id === hand.template)?.properties ?? [];
+  }
+  return hand.properties ?? [];
+};
+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))])),
+    deck: new Map(b.boxes.flatMap((box) => box.decks.map(
+      (deck) => [deck.id, bagFromDecls(half("deck", deck.properties))]
+    ))),
+    // 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)))]
+    ))),
+    value: new Map(b.boxes.flatMap((box) => box.tagGroups.flatMap((group) => group.tags.map(
+      (tag) => [tag.id, bagFromDecls(half("value", tag.properties ?? []))]
+    ))))
+  };
+};
+var partitionValues = (p) => ({
+  story: p.story.values,
+  box: Object.fromEntries([...p.box].map(([id, bag]) => [id, bag.values])),
+  deck: Object.fromEntries([...p.deck].map(([id, bag]) => [id, bag.values])),
+  hand: Object.fromEntries([...p.hand].map(([id, bag]) => [id, bag.values])),
+  value: Object.fromEntries([...p.value].map(([id, bag]) => [id, bag.values]))
+});
+var loadPartition = (p, values) => {
+  p.story.load(values?.story ?? {});
+  for (const kind of ["box", "deck", "hand", "value"]) {
+    for (const [id, bag] of Object.entries(values?.[kind] ?? {})) {
+      p[kind].get(id)?.load(bag);
+    }
+  }
+};
+var Engine = class {
+  internals;
+  seed;
+  flowsById = /* @__PURE__ */ new Map();
+  engineTraceHandlers = /* @__PURE__ */ new Set();
+  /** The host's @world binding, if the engine was built with one: it
+   *  outlives reset/loadGame (the host's container is the host's). The
+   *  self-backed resolver is rebuilt instead. */
+  hostWorld;
+  constructor(bundle, opts = {}) {
+    this.seed = opts.seed ?? 0;
+    if (opts.world !== void 0) this.hostWorld = opts.world;
+    const internals = {
+      bundle,
+      ...opts.log ? { logCap: typeof opts.log === "object" ? opts.log.cap ?? 1e3 : 1e3 } : {},
+      cardsById: /* @__PURE__ */ new Map(),
+      cardsByGameId: /* @__PURE__ */ new Map(),
+      boxesByGameId: /* @__PURE__ */ new Map(),
+      boxesById: /* @__PURE__ */ new Map(),
+      handsById: /* @__PURE__ */ new Map(),
+      handsByGameId: /* @__PURE__ */ new Map(),
+      templatesById: /* @__PURE__ */ new Map(),
+      groupsById: /* @__PURE__ */ new Map(),
+      requiredGroups: /* @__PURE__ */ new Set(),
+      nodeCache: /* @__PURE__ */ new WeakMap(),
+      ladders: { world: /* @__PURE__ */ new Map(), story: /* @__PURE__ */ new Map(), box: /* @__PURE__ */ new Map(), deck: /* @__PURE__ */ new Map(), value: /* @__PURE__ */ new Map(), hand: /* @__PURE__ */ new Map() },
+      hasQualities: false,
+      hasShared: false,
+      flowDecls: { story: [], box: /* @__PURE__ */ new Map(), deck: /* @__PURE__ */ new Map(), hand: /* @__PURE__ */ new Map(), value: /* @__PURE__ */ new Map() },
+      shared: void 0,
+      worldResolver: void 0,
+      emitEngine: (flow, event, turn) => {
+        if (this.internals.logCap !== void 0) {
+          this.engineLog.push({ ...event, flow, seq: this.engineSeq++, ...turn !== void 0 ? { turn } : {} });
+          if (this.engineLog.length > this.internals.logCap) {
+            this.engineLog.splice(0, this.engineLog.length - this.internals.logCap);
+          }
+        }
+        for (const h of this.engineTraceHandlers) h(flow, event);
+      },
+      engineTracing: () => this.engineTraceHandlers.size > 0
+    };
+    this.internals = internals;
+    for (const box of bundle.boxes) {
+      internals.boxesById.set(box.id, box);
+      internals.boxesByGameId.set(effectiveGameId(box), box);
+      for (const group of box.tagGroups) {
+        internals.groupsById.set(group.id, { group, box });
+        if (group.required === true) internals.requiredGroups.add(group.id);
+      }
+      for (const deck of box.decks) {
+        if (deck.shared === true) internals.hasShared = true;
+        for (const card of deck.cards) {
+          const entry = { card, deck, box };
+          internals.cardsById.set(card.id, entry);
+          internals.cardsByGameId.set(effectiveGameId(card), entry);
+          if (card.shared === true) internals.hasShared = true;
+        }
+      }
+      for (const template of box.handTemplates) {
+        internals.templatesById.set(template.id, template);
+      }
+      for (const hand of box.hands) {
+        internals.handsById.set(hand.id, { hand, box });
+        internals.handsByGameId.set(effectiveGameId(hand), { hand, box });
+      }
+    }
+    this.initLadders();
+    internals.flowDecls = {
+      story: flowHalf("story", bundle.story.properties),
+      box: new Map(bundle.boxes.map((box) => [box.id, flowHalf("box", box.properties)])),
+      deck: new Map(bundle.boxes.flatMap((box) => box.decks.map(
+        (deck) => [deck.id, flowHalf("deck", deck.properties)]
+      ))),
+      hand: new Map(bundle.boxes.flatMap((box) => box.hands.map(
+        (hand) => [hand.id, flowHalf("hand", handDeclsOf(internals, hand))]
+      ))),
+      value: new Map(bundle.boxes.flatMap((box) => box.tagGroups.flatMap((group) => group.tags.map(
+        (tag) => [tag.id, flowHalf("value", tag.properties ?? [])]
+      ))))
+    };
+    this.initShared(this.hostWorld);
+  }
+  /** Build the shared stores and the @world seam. `hostWorld` sticks for the
+   *  engine's lifetime; reset/loadGame rebuild the shared bags around it. */
+  initShared(hostWorld) {
+    const internals = this.internals;
+    internals.shared = buildPartition(internals, sharedHalf);
+    if (hostWorld !== void 0) {
+      internals.worldResolver = hostWorld;
+    } else {
+      const bag = bagFromDecls(internals.bundle.world.properties);
+      internals.worldResolver = {
+        get: (n) => bag.get(n),
+        set: (n, v) => {
+          bag.set(n, v);
+        }
+      };
+    }
+  }
+  /** Quality ladders by scope for the eval channel (design/quality.md):
+   *  world/story keyed by name; box/deck/value keyed by owner id then name.
+   *  Built once - a bundle's declarations never change. Ladders are
+   *  declaration-level, so the sharing flag does not touch them. */
+  initLadders() {
+    const internals = this.internals;
+    const grab = (decls) => {
+      const m = /* @__PURE__ */ new Map();
+      for (const d of decls ?? []) if (d.type === "quality" && d.stages !== void 0) m.set(d.name, d.stages);
+      return m;
+    };
+    const b = internals.bundle;
+    internals.ladders.world = grab(b.world.properties);
+    internals.ladders.story = grab(b.story.properties);
+    for (const box of b.boxes) {
+      internals.ladders.box.set(box.id, grab(box.properties));
+      for (const deck of box.decks) internals.ladders.deck.set(deck.id, grab(deck.properties));
+      for (const group of box.tagGroups) {
+        for (const tag of group.tags) internals.ladders.value.set(tag.id, grab(tag.properties));
+      }
+      for (const hand of box.hands) internals.ladders.hand.set(hand.id, grab(handDeclsOf(internals, hand)));
+    }
+    const any = (m) => [...m.values()].some((x) => x.size > 0);
+    internals.hasQualities = internals.ladders.world.size > 0 || internals.ladders.story.size > 0 || any(internals.ladders.box) || any(internals.ladders.deck) || any(internals.ladders.value) || any(internals.ladders.hand);
+  }
+  // --- flow management (Patter's surface, name for name) ----------------------
+  /** Open (or REPLACE) the named flow. An existing id's flow is closed
+   *  first - re-opening a name is a reset of that name's whole per-flow
+   *  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 flow = new Flow(this, this.internals, id, opts.seed ?? this.seed);
+    this.flowsById.set(id, flow);
+    return flow;
+  }
+  getFlow(id) {
+    return this.flowsById.get(id);
+  }
+  /** Every live flow, open order. */
+  flows() {
+    return [...this.flowsById.values()];
+  }
+  /** Close the named flow: its handle goes INERT (every verb throws). A
+   *  dropped-but-held flow must not keep writing shared state (Patter's
+   *  stale-handle lesson). Unknown ids are a quiet no-op, like closing a
+   *  closed door. */
+  closeFlow(id) {
+    const flow = this.flowsById.get(id);
+    if (!flow) return;
+    this.flowsById.delete(id);
+    flow.markClosed();
+  }
+  /** @internal - Flow.close() routes here so both doors agree. */
+  dropFlow(id, flow) {
+    if (this.flowsById.get(id) === flow) this.flowsById.delete(id);
+  }
+  /** Close every flow and reseed the shared state to its defaults (the
+   *  self-backed @world included; a host-bound @world is the host's and is
+   *  not touched). */
+  reset() {
+    this.engineLog = [];
+    for (const flow of this.flowsById.values()) flow.markClosed();
+    this.flowsById.clear();
+    this.spent.clear();
+    this.initShared(this.hostWorld);
+  }
+  // --- shared scarcity (design/shared-scarcity.md) -----------------------------
+  /** Cards a shared `redraw: "never"` has taken out of the world, by card id.
+   *  The claim ledger is DERIVED from live boards and so needs no storage;
+   *  this one is durable, so it rides the save's shared half. */
+  spent = /* @__PURE__ */ new Set();
+  /** @internal */
+  isTaken(cardId) {
+    return this.spent.has(cardId);
+  }
+  /** @internal */
+  markTaken(cardId) {
+    this.spent.add(cardId);
+  }
+  // --- the run's log (design/shared-scarcity.md 8.2) ---------------------------
+  /** Every flow's events in one ordered stream, each tagged with its flow.
+   *  Opt in with the same `log` option the flow logs use; capped the same way.
+   *
+   *  This exists because a flow's own log cannot answer the question a run
+   *  raises: when a story action in ANOTHER flow moves shared state, your
+   *  flow's log says nothing and your value simply changes. Reading a run
+   *  needs one stream that says who did what, and merging the per-flow logs by
+   *  hand is a thing every host would otherwise have to write. */
+  engineLog = [];
+  engineSeq = 0;
+  log() {
+    return this.engineLog;
+  }
+  clearLog() {
+    this.engineLog = [];
+  }
+  /** @internal - shared claims across every LIVE flow, card id -> holders.
+   *  Derived, which is what makes closeFlow and the openFlow replace release
+   *  what a flow was holding: its board leaves the map with it. */
+  sharedClaims() {
+    const counts = /* @__PURE__ */ new Map();
+    for (const flow of this.flowsById.values()) {
+      for (const id of flow.heldCardIds()) counts.set(id, (counts.get(id) ?? 0) + 1);
+    }
+    return counts;
+  }
+  // --- engine-level state access ----------------------------------------------
+  /**
+   * Read shared state by path: "world.x", "story.gold" (when shared),
+   * "box.b_x.heat" (when shared). A ref that resolves PER-FLOW throws,
+   * naming the fix - silently answering with some flow's copy (or a junk
+   * default) was the bug Patter's engine.getProperty guard exists to stop.
+   */
+  getProperty(path) {
+    const found = this.resolveShared(path);
+    const value = found.kind === "world" ? this.internals.worldResolver.get(found.name) : found.bag.get(found.name);
+    if (value === void 0) throw new Error(`no property at "${path}"`);
+    return value;
+  }
+  setProperty(path, value) {
+    const found = this.resolveShared(path);
+    if (found.kind === "world") {
+      if (!this.internals.worldResolver.set) {
+        throw new Error(`@world is read-only here: the host bound no write`);
+      }
+      this.internals.worldResolver.set(found.name, value);
+      return;
+    }
+    found.bag.set(found.name, value, { silent: true, reason: "host setProperty" });
+  }
+  resolveShared(path) {
+    const parts = path.split(".");
+    const perFlow = () => {
+      throw new Error(`"${path}" is per-flow state - read it on a Flow, not the Engine`);
+    };
+    if (parts.length === 2 && parts[0] === "world") return { kind: "world", name: parts[1] };
+    if (parts.length === 2 && parts[0] === "story") {
+      const name = parts[1];
+      if (this.internals.shared.story.get(name) !== void 0) return { kind: "bag", bag: this.internals.shared.story, name };
+      if (this.internals.flowDecls.story.some((d) => d.name === name)) perFlow();
+      throw new Error(`no property at "${path}"`);
+    }
+    if (parts.length === 3 && (parts[0] === "box" || parts[0] === "deck" || parts[0] === "hand" || parts[0] === "value")) {
+      const kind = parts[0];
+      const [, id, name] = parts;
+      const bag = this.internals.shared[kind].get(id);
+      if (bag !== void 0 && bag.get(name) !== void 0) return { kind: "bag", bag, name };
+      if (this.internals.flowDecls[kind].get(id)?.some((d) => d.name === name)) perFlow();
+      if (bag === void 0 && !this.internals.flowDecls[kind].has(id)) throw new Error(`no ${kind} store "${id}"`);
+      throw new Error(`no property at "${path}"`);
+    }
+    throw new Error(`bad property path "${path}"`);
+  }
+  /** The shared surface as examiner rows: @world (read through the
+   *  resolver) then the shared partitions. Per-flow rows live on each Flow. */
+  listProperties() {
+    const out = [];
+    for (const d of this.internals.bundle.world.properties) {
+      const value = this.internals.worldResolver.get(d.name);
+      out.push({
+        path: `world.${d.name}`,
+        name: d.name,
+        type: d.type,
+        value: value ?? d.default,
+        default: d.default,
+        ...d.values !== void 0 ? { values: d.values } : {},
+        ...d.stages !== void 0 ? { stages: d.stages } : {}
+      });
+    }
+    const add = (prefix, bag) => {
+      for (const row of bag.rows()) out.push({ path: `${prefix}.${row.name}`, ...row });
+    };
+    add("story", this.internals.shared.story);
+    for (const [id, bag] of this.internals.shared.box) add(`box.${id}`, bag);
+    for (const [id, bag] of this.internals.shared.deck) add(`deck.${id}`, bag);
+    for (const [id, bag] of this.internals.shared.hand) add(`hand.${id}`, bag);
+    for (const [id, bag] of this.internals.shared.value) add(`value.${id}`, bag);
+    return out;
+  }
+  /** 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. */
+  listBags() {
+    const mounts = [{ prefix: "story", bag: this.internals.shared.story }];
+    for (const kind of ["box", "deck", "hand", "value"]) {
+      for (const [id, bag] of this.internals.shared[kind]) mounts.push({ prefix: `${kind}.${id}`, bag });
+    }
+    return mounts;
+  }
+  /** Every flow's trace, one stream, each event tagged with its flow id. */
+  subscribeTrace(handler) {
+    this.engineTraceHandlers.add(handler);
+    return () => this.engineTraceHandlers.delete(handler);
+  }
+  // --- persistence (schema 4) -------------------------------------------------
+  /** The whole engine, one envelope: the shared partitions once, then
+   *  every live flow keyed by its id. @world is NEVER here - the host
+   *  saves its container, each engine saves its own envelope. */
+  saveGame() {
+    return structuredClone({
+      schema: "storylets/save@1",
+      content: this.internals.bundle.content,
+      shared: { props: partitionValues(this.internals.shared), spent: [...this.spent].sort() },
+      flows: Object.fromEntries([...this.flowsById].map(([id, flow]) => [id, flow.snapshot()]))
+    });
+  }
+  /** Restore: shared state once, then every flow REBUILT from its blob.
+   *  Handles held from before the load are closed and inert (Patter's
+   *  rule); take fresh ones from getFlow()/flows(). */
+  loadGame(envelope) {
+    if (envelope.content.project !== this.internals.bundle.content.project) {
+      throw new Error(`save is for project "${envelope.content.project}", bundle is "${this.internals.bundle.content.project}"`);
+    }
+    const env = structuredClone(envelope);
+    this.reset();
+    loadPartition(this.internals.shared, env.shared.props);
+    for (const id of env.shared.spent ?? []) this.spent.add(id);
+    for (const [id, saved] of Object.entries(env.flows ?? {})) {
+      this.openFlow(id).restore(saved);
+    }
+  }
+};
+var Flow = class {
+  id;
+  engine;
+  internals;
+  closed = false;
+  prng;
+  /** Per-box turn counters, keyed by box id (schema 3.4) - per flow. */
+  turnCounts = /* @__PURE__ */ new Map();
+  cooldowns = {};
+  /** The board: hand contents (card ids, dealt order), keyed by hand id. */
+  boardContents = /* @__PURE__ */ new Map();
+  playLog = [];
+  // --- play-history indexes -------------------------------------------------
+  // The four play-history host functions used to SCAN playLog on every call,
+  // and they are called once per candidate card per ask, so dealing was
+  // O(candidates x playLog): a shipped game got measurably slower the longer
+  // somebody played it, which is the failure mode nobody meets in testing.
+  // Measured before the change, 2000 cards: a box with no history condition
+  // held flat at 0.3ms while `count_played` went 0.8ms -> 27.9ms as the log
+  // reached 4000 plays.
+  //
+  // These are a pure summary of `playLog`, maintained where it is appended and
+  // rebuilt where it is replaced, so they cannot drift from it. They are NOT
+  // saved: `playLog` is the record, this is a derivation, and rebuilding on
+  // load keeps the save format untouched.
+  //
+  // The tag keys are the played card's OWN (groupId, tagId) pairs, which is
+  // what makes the box-local rule survive: a group name resolves inside the
+  // ASKING box, so a card in another box carries different ids and cannot
+  // match, exactly as the per-record `inTag` check used to decide.
+  playCount = /* @__PURE__ */ new Map();
+  lastPlayOf = /* @__PURE__ */ new Map();
+  tagPlayCount = /* @__PURE__ */ new Map();
+  lastPlayInTag = /* @__PURE__ */ new Map();
+  /** The per-flow property partitions (the not-shared halves). */
+  stores;
+  traceHandlers = /* @__PURE__ */ new Set();
+  logEntries = [];
+  logSeq = 0;
+  /** Merged read view per scope, built once (bags are stable for the
+   *  flow's life): the flow's own bag first, the shared bag behind it.
+   *  Names are disjoint (shared XOR per-flow by declaration), so "first"
+   *  is routing, not shadowing. */
+  storyReader;
+  boxReaders = /* @__PURE__ */ new Map();
+  deckReaders = /* @__PURE__ */ new Map();
+  /** @internal - built by Engine.openFlow / Engine.loadGame only. */
+  constructor(engine, internals, id, seed) {
+    this.engine = engine;
+    this.internals = internals;
+    this.id = id;
+    this.prng = makePrng(seed);
+    this.stores = buildPartition(internals, flowHalf);
+    for (const box of internals.bundle.boxes) {
+      this.turnCounts.set(box.id, 0);
+      for (const hand of box.hands) this.boardContents.set(hand.id, []);
+    }
+    const pair = (own, shared) => ({
+      get: (n) => own?.get(n) ?? shared?.get(n)
+    });
+    this.storyReader = pair(this.stores.story, internals.shared.story);
+    for (const box of internals.bundle.boxes) {
+      this.boxReaders.set(box.id, pair(this.stores.box.get(box.id), internals.shared.box.get(box.id)));
+      for (const deck of box.decks) {
+        this.deckReaders.set(deck.id, pair(this.stores.deck.get(deck.id), internals.shared.deck.get(deck.id)));
+      }
+    }
+  }
+  // --- lifetime ----------------------------------------------------------------
+  get isClosed() {
+    return this.closed;
+  }
+  /** Close this flow: the handle goes inert, every verb throws. */
+  close() {
+    if (this.closed) return;
+    this.engine.dropFlow(this.id, this);
+    this.markClosed();
+  }
+  /** @internal */
+  markClosed() {
+    this.closed = true;
+  }
+  assertOpen() {
+    if (this.closed) throw new Error(`flow "${this.id}" is closed`);
+  }
+  /** A box's current turn (schema 3.4), on THIS flow's clock. */
+  turn(boxRef) {
+    this.assertOpen();
+    const box = this.internals.boxesByGameId.get(boxRef) ?? this.internals.boxesById.get(boxRef);
+    if (!box) throw new Error(`unknown box "${boxRef}"`);
+    return this.turnCounts.get(box.id) ?? 0;
+  }
+  /** Subscribe to this flow's deal/play trace (schema 5). Returns the
+   *  unsubscribe. With no subscribers anywhere the flow does no trace work. */
+  subscribeTrace(handler) {
+    this.traceHandlers.add(handler);
+    return () => this.traceHandlers.delete(handler);
+  }
+  get tracing() {
+    return this.traceHandlers.size > 0 || this.internals.logCap !== void 0 || this.internals.engineTracing();
+  }
+  emit(event, turn) {
+    if (this.internals.logCap !== void 0) {
+      this.logEntries.push({ ...event, seq: this.logSeq++, ...turn !== void 0 ? { turn } : {} });
+      if (this.logEntries.length > this.internals.logCap) this.logEntries.splice(0, this.logEntries.length - this.internals.logCap);
+    }
+    for (const handler of this.traceHandlers) handler(event);
+    this.internals.emitEngine(this.id, event, turn);
+  }
+  /** The retained flow log (opt-in via the Engine's `log`), oldest first,
+   *  capped. The introspection seam for hosts and tools; the durable play
+   *  history in a save stays `playLog` (schema 4) - the log is a
+   *  flow-lifetime utility and is NOT saved. */
+  log() {
+    return this.logEntries;
+  }
+  /** Empty the retained log; `seq` keeps counting, so ordering across a
+   *  clear stays meaningful. */
+  clearLog() {
+    this.logEntries = [];
+  }
+  // --- expression plumbing ----------------------------------------------------
+  node(expr) {
+    let node = this.internals.nodeCache.get(expr);
+    if (!node) {
+      node = deserialiseAst(expr.ast);
+      this.internals.nodeCache.set(expr, node);
+    }
+    return node;
+  }
+  /** Tag group names are box-scoped: two boxes may name a group the same way
+   *  (schema 1 - boxes namespace their groups), so a name is only ever
+   *  resolved inside the box being asked, never bundle-wide. Ids are
+   *  project-unique and accepted here too, still confined to the box. */
+  groupInBox(box, ref) {
+    return box.tagGroups.find((g) => effectiveGameId(g) === ref) ?? box.tagGroups.find((g) => g.id === ref);
+  }
+  /** Fold one play into the indexes. O(the card's tags), not O(the log). */
+  indexPlay(record) {
+    this.playCount.set(record.card, (this.playCount.get(record.card) ?? 0) + 1);
+    this.lastPlayOf.set(record.card, record);
+    const entry = this.internals.cardsByGameId.get(record.card);
+    if (!entry) return;
+    for (const [groupId, tagIds] of Object.entries(entry.card.tags ?? {})) {
+      for (const tagId of tagIds) {
+        const key = tagKey(groupId, tagId);
+        this.tagPlayCount.set(key, (this.tagPlayCount.get(key) ?? 0) + 1);
+        this.lastPlayInTag.set(key, record);
+      }
+    }
+  }
+  /** Rebuild the indexes from the log. Called wherever `playLog` is REPLACED
+   *  rather than appended to, which is `restore` alone. */
+  rebuildPlayIndex() {
+    this.playCount.clear();
+    this.lastPlayOf.clear();
+    this.tagPlayCount.clear();
+    this.lastPlayInTag.clear();
+    for (const record of this.playLog) this.indexPlay(record);
+  }
+  /** `box` is the box whose ask is being evaluated: the play-history
+   *  functions take a bare group name, so it resolves there (a card's tags
+   *  reference its own box's group, which keeps the counts box-local).
+   *  History is THIS flow's: countPlayed answers "have I done this". */
+  /** One host per box, built once.
+   *
+   *  The closures below read `this.playCount`, `this.turnCounts` and the rest
+   *  LIVE, so a cached host answers with current state - which is what makes
+   *  caching safe rather than a snapshot bug. Unreal did this from the start
+   *  (`hostsByBox_`, built at flow construction) and the other three rebuilt a
+   *  host, and its closures, on every `evalCtx` call: once per deck per ask,
+   *  and once per surviving card in the eviction pass. Structural divergence
+   *  in one port AND the allocation the audit flagged, so the other three
+   *  copied it (2026-08-29). Lazy rather than eager, so a bundle's unvisited
+   *  boxes cost nothing. */
+  hostsByBox = /* @__PURE__ */ new Map();
+  host(box) {
+    const cached = this.hostsByBox.get(box.id);
+    if (cached !== void 0) return cached;
+    const made = this.makeHost(box);
+    this.hostsByBox.set(box.id, made);
+    return made;
+  }
+  makeHost(box) {
+    const keyOf = (group, tag) => {
+      const found = this.groupInBox(box, group);
+      const t = found?.tags.find((v) => v.gameId === tag);
+      return found && t ? tagKey(found.id, t.id) : void 0;
+    };
+    const since = (record) => {
+      const entry = this.internals.cardsByGameId.get(record.card);
+      if (!entry) return NEVER_PLAYED;
+      return (this.turnCounts.get(entry.box.id) ?? 0) - record.turn;
+    };
+    return {
+      nextRandom: () => this.prng.next(),
+      countPlayed: (card) => this.playCount.get(card) ?? 0,
+      turnsSincePlayed: (card) => {
+        const last = this.lastPlayOf.get(card);
+        return last ? since(last) : NEVER_PLAYED;
+      },
+      countPlayedIn: (group, tag) => {
+        const key = keyOf(group, tag);
+        return key === void 0 ? 0 : this.tagPlayCount.get(key) ?? 0;
+      },
+      turnsSincePlayedIn: (group, tag) => {
+        const key = keyOf(group, tag);
+        const last = key === void 0 ? void 0 : this.lastPlayInTag.get(key);
+        return last ? since(last) : NEVER_PLAYED;
+      }
+    };
+  }
+  /** The evaluation environment (schema 3.1/6.2): @box/@deck resolve to the
+   *  card under evaluation; in hand-condition contexts @deck is an empty bag,
+   *  so any reference is an eval error (missing-policy throw). Every scope
+   *  is the flow's MERGED view - its own copies over the shared values,
+   *  names disjoint - and @world reads through the engine's resolver. */
+  evalCtx(box, deck, handEnv) {
+    return {
+      scopes: {
+        world: this.internals.worldResolver,
+        story: this.storyReader,
+        box: this.boxReaders.get(box.id) ?? {},
+        deck: deck ? this.deckReaders.get(deck.id) ?? {} : {},
+        hand: handEnv.bag
+      },
+      host: this.host(box),
+      // The quality channel, answering for THIS ask's box and deck. Only wired
+      // when a quality exists, so a bundle without one evaluates byte-
+      // identically to before the feature.
+      ...this.internals.hasQualities ? {
+        qualities: (scope, name) => scope === "world" ? this.internals.ladders.world.get(name) : scope === "story" ? this.internals.ladders.story.get(name) : scope === "box" ? this.internals.ladders.box.get(box.id)?.get(name) : scope === "deck" && deck ? this.internals.ladders.deck.get(deck.id)?.get(name) : scope === "hand" ? this.handLadder(handEnv, name) : void 0
+      } : {}
+    };
+  }
+  /** The ladder behind one composed @hand name, or undefined when the name is
+   *  not a quality (or came from criteria, which are tag NAMES, never state). */
+  handLadder(handEnv, name) {
+    const source = handEnv.sources.get(name);
+    if (!source) return void 0;
+    return source.kind === "value" ? this.internals.ladders.value.get(source.id)?.get(name) : source.kind === "hand" ? this.internals.ladders.hand.get(source.id)?.get(name) : void 0;
+  }
+  eval(expr, ctx) {
+    return evaluate(this.node(expr), ctx, storyletsDialect);
+  }
+  passes(expr, ctx, where) {
+    if (!expr) return true;
+    try {
+      return conditionPasses(this.eval(expr, ctx));
+    } catch (e) {
+      if (this.tracing) {
+        this.emit({ type: "diagnostic", where: where ?? "condition", message: e instanceof Error ? e.message : String(e) });
+      }
+      return false;
+    }
+  }
+  // --- resolving asks (schema 2.6 + 3.6) -----------------------------------------
+  tagByGameId(group, gameId) {
+    return group.tags.find((t) => t.gameId === gameId);
+  }
+  /** A deal's ask: the hand's template bindings + chosen tags, or its rule's
+   *  bindings, plus the implicit home binding (schema 2.4). */
+  askForHand(hand, box) {
+    const boundTags = /* @__PURE__ */ new Map();
+    const askNames = {};
+    let condition;
+    if (hand.template !== void 0) {
+      const template = this.internals.templatesById.get(hand.template);
+      if (!template) throw new Error(`hand "${effectiveGameId(hand)}": unknown template "${hand.template}"`);
+      for (const [groupId, tagId] of Object.entries(template.bindings ?? {})) {
+        boundTags.set(groupId, tagId);
+      }
+      for (const [groupId, tagId] of Object.entries(hand.chosen ?? {})) {
+        boundTags.set(groupId, tagId);
+        const found = this.internals.groupsById.get(groupId);
+        const tag = found?.group.tags.find((t) => t.id === tagId);
+        if (found && tag) askNames[effectiveGameId(found.group)] = effectiveGameId(tag);
+      }
+      condition = template.condition;
+    } else {
+      for (const [groupId, tagId] of Object.entries(hand.rule?.bindings ?? {})) {
+        boundTags.set(groupId, tagId);
+        const found = this.internals.groupsById.get(groupId);
+        const tag = found?.group.tags.find((t) => t.id === tagId);
+        if (found && tag) askNames[effectiveGameId(found.group)] = effectiveGameId(tag);
+      }
+      condition = hand.rule?.condition;
+    }
+    boundTags.set(PLACE_GROUP, hand.id);
+    this.bindStateGroups(box, boundTags, askNames);
+    return { box, hand, ...condition !== void 0 ? { condition } : {}, boundTags, askNames };
+  }
+  /** A peek's ask: raw criteria ({group gameId: tag gameId}), bindings only,
+   *  no condition slot (schema 3.1; the boundary, Reboot 4). */
+  askForPeek(box, criteria) {
+    const boundTags = /* @__PURE__ */ new Map();
+    const askNames = {};
+    for (const [groupRef, tagRef] of Object.entries(criteria)) {
+      if (groupRef === PLACE_GROUP) {
+        const hand = this.internals.handsByGameId.get(tagRef) ?? this.internals.handsById.get(tagRef);
+        if (!hand) throw new Error(`peek: unknown hand "${tagRef}" in home criteria`);
+        boundTags.set(PLACE_GROUP, hand.hand.id);
+        continue;
+      }
+      const found = this.groupInBox(box, groupRef);
+      if (!found) {
+        throw new Error(`peek: unknown tag group "${groupRef}" in box "${effectiveGameId(box)}"`);
+      }
+      const tag = this.tagByGameId(found, tagRef) ?? found.tags.find((t) => t.id === tagRef);
+      if (!tag) throw new Error(`peek: unknown tag "${tagRef}" in group "${effectiveGameId(found)}"`);
+      boundTags.set(found.id, tag.id);
+      askNames[effectiveGameId(found)] = effectiveGameId(tag);
+    }
+    this.bindStateGroups(box, boundTags, askNames);
+    return { box, boundTags, askNames };
+  }
+  /**
+   * Bind every `boundBy` group in the box from the property it names.
+   *
+   * The gap this closes: only a hand could bind a group, and `deal` takes no
+   * criteria, so an axis driven by state (an act, a chapter) had nowhere to
+   * gate. Runs AFTER the hand's own bindings and never overwrites one: an
+   * explicit binding is a deliberate act and beats a default.
+   *
+   * A value naming no tag in the group leaves the group UNBOUND rather than
+   * matching nothing. Unbound is a wildcard, so the ask still deals; a silent
+   * empty hand would look like content that does not exist, and the diagnostic
+   * is what says otherwise.
+   */
+  bindStateGroups(box, boundTags, askNames) {
+    for (const group of box.tagGroups) {
+      if (group.boundBy === void 0 || boundTags.has(group.id)) continue;
+      const ref = /^@(world|story)\.([a-z][a-z0-9_-]*)$/.exec(group.boundBy);
+      if (!ref) {
+        this.emit({ type: "diagnostic", where: `tag group ${effectiveGameId(group)}`, message: `boundBy "${group.boundBy}" is not a @world or @story property reference` });
+        continue;
+      }
+      let value;
+      try {
+        value = this.getProperty(`${ref[1]}.${ref[2]}`);
+      } catch {
+        this.emit({ type: "diagnostic", where: `tag group ${effectiveGameId(group)}`, message: `boundBy "${group.boundBy}" names a property that is not declared` });
+        continue;
+      }
+      const wanted = typeof value === "string" ? value : String(value);
+      const tag = group.tags.find((t) => effectiveGameId(t) === wanted);
+      if (!tag) {
+        this.emit({ type: "diagnostic", where: `tag group ${effectiveGameId(group)}`, message: `${group.boundBy} is "${wanted}", which is not one of its tags` });
+        continue;
+      }
+      boundTags.set(group.id, tag.id);
+      askNames[effectiveGameId(group)] = effectiveGameId(tag);
+    }
+  }
+  // --- @hand composition (schema 3.6) -------------------------------------------
+  /** A store's full value view for one owner: the shared half under the
+   *  flow's half. Names are disjoint, so the spread is routing, not
+   *  shadowing. */
+  valuesOf(kind, id) {
+    return {
+      ...this.internals.shared[kind].get(id)?.values ?? {},
+      ...this.stores[kind].get(id)?.values ?? {}
+    };
+  }
+  buildHandEnv(ask) {
+    const bag = {};
+    const sources = /* @__PURE__ */ new Map();
+    for (const [groupId, tagId] of ask.boundTags) {
+      if (groupId === PLACE_GROUP) continue;
+      for (const [name, value] of Object.entries(this.valuesOf("value", tagId))) {
+        bag[name] = value;
+        sources.set(name, { kind: "value", id: tagId });
+      }
+    }
+    if (ask.hand) {
+      for (const [name, value] of Object.entries(this.valuesOf("hand", ask.hand.id))) {
+        bag[name] = value;
+        sources.set(name, { kind: "hand", id: ask.hand.id });
+      }
+    }
+    for (const [name, value] of Object.entries(ask.askNames)) {
+      bag[name] = value;
+      sources.set(name, { kind: "criteria" });
+    }
+    return { bag, sources, boundTags: ask.boundTags };
+  }
+  // --- the ask (schema 3.1 + 3.2) ------------------------------------------------
+  /** The claims ledger, derived from THIS flow's board: card id -> holding
+   *  hands (schema 3.5). Claims are per flow - another flow holding the
+   *  card is another playthrough, not a rival hand. */
+  claims() {
+    const counts = /* @__PURE__ */ new Map();
+    for (const contents of this.boardContents.values()) {
+      for (const id of contents) counts.set(id, (counts.get(id) ?? 0) + 1);
+    }
+    return counts;
+  }
+  /** @internal - every card id on THIS flow's board, one entry per holding
+   *  hand. The engine sums these across live flows for the shared ledger. */
+  heldCardIds() {
+    return [...this.boardContents.values()].flat();
+  }
+  copiesOf(card) {
+    return card.copies ?? 1;
+  }
+  /** The claims step (schema 3.1 step 6) for one card, as a verdict or null
+   *  for "available". Two caps apply to a shared card and they are different
+   *  statements, so they get different verdicts: `copies` is your own board
+   *  filling up, `sharedCopies` is somebody else already holding it, and a
+   *  participant told "claimed" about a card sitting on another person's
+   *  table would read it as an engine fault (design/shared-scarcity 9.3.1).
+   *
+   *  `mine` counts this flow's holdings, `world` every live flow's. */
+  claimVerdict(card, shared, mine, world) {
+    const id = card.id;
+    if ((mine.get(id) ?? 0) >= this.copiesOf(card)) return "claimed";
+    if (shared && (world.get(id) ?? 0) >= sharedCap(card)) return "claimed-elsewhere";
+    return null;
+  }
+  /** Tag matching (schema 3.1 step 3): for every bound group the card lists
+   *  the bound tag or omits the group (wildcard); the home group inverts -
+   *  a homed card requires a matching home binding (schema 2.4). */
+  tagsMatch(card, boundTags) {
+    const home = card.tags?.[PLACE_GROUP];
+    if (home !== void 0 && home.length > 0) {
+      const bound = boundTags.get(PLACE_GROUP);
+      if (bound === void 0 || !home.includes(bound)) return false;
+    }
+    for (const [groupId, tagId] of boundTags) {
+      if (groupId === PLACE_GROUP) continue;
+      const tags = card.tags?.[groupId];
+      if (tags === void 0) {
+        if (this.internals.requiredGroups.has(groupId)) return false;
+        continue;
+      }
+      if (!tags.includes(tagId)) return false;
+    }
+    return true;
+  }
+  /** Run one ask: availability filter then ranking. `claimed` decides the
+   *  claims step (step 6) per card, returning the verdict that refused it or
+   *  null for available. `trace` (when a subscriber exists) collects the
+   *  per-card verdicts. */
+  runAsk(ask, claimed, trace) {
+    const { box } = ask;
+    const handEnv = this.buildHandEnv(ask);
+    const verdict = (id, v) => {
+      trace?.push({ id, verdict: v });
+    };
+    if (!this.passes(ask.condition, this.evalCtx(box, void 0, handEnv), `hand ${ask.hand ? effectiveGameId(ask.hand) : ""} condition`)) {
+      return { ordered: [], handEnv };
+    }
+    const gateOk = /* @__PURE__ */ new Map();
+    for (const deck of box.decks) {
+      gateOk.set(deck.id, this.passes(deck.condition, this.evalCtx(box, deck, handEnv), `deck ${deck.gameId} gate`));
+    }
+    const turn = this.turnCounts.get(box.id) ?? 0;
+    const scored = [];
+    for (const deck of box.decks) {
+      const deckCtx = this.evalCtx(box, deck, handEnv);
+      const deckShared = deck.shared ?? false;
+      for (const card of deck.cards) {
+        const shared = cardIsShared(card, deckShared);
+        if (!gateOk.get(deck.id)) {
+          verdict(card.id, "deck-gate");
+          continue;
+        }
+        if (shared && this.engine.isTaken(card.id)) {
+          verdict(card.id, "taken");
+          continue;
+        }
+        if ((this.cooldowns[card.id] ?? 0) > turn) {
+          verdict(card.id, "cooldown");
+          continue;
+        }
+        if (!this.tagsMatch(card, handEnv.boundTags)) {
+          verdict(card.id, "tags");
+          continue;
+        }
+        if (card.condition && !this.passes(
+          card.condition,
+          deckCtx,
+          this.tracing ? `card ${card.gameId} condition` : void 0
+        )) {
+          verdict(card.id, "condition");
+          continue;
+        }
+        const refused = claimed(card, shared);
+        if (refused) {
+          verdict(card.id, refused);
+          continue;
+        }
+        let priority;
+        if (typeof card.priority === "number") {
+          priority = card.priority;
+        } else {
+          try {
+            const v = this.eval(card.priority, deckCtx);
+            if (typeof v !== "number") {
+              verdict(card.id, "priority");
+              continue;
+            }
+            priority = v;
+          } catch (e) {
+            if (this.tracing) {
+              this.emit({ type: "diagnostic", where: `card ${card.gameId} priority`, message: e instanceof Error ? e.message : String(e) });
+            }
+            verdict(card.id, "priority");
+            continue;
+          }
+        }
+        let spec = 0;
+        if (box.ranking.specificity && card.condition) {
+          const node = this.node(card.condition);
+          spec = matchedSpecificity(node, (n) => {
+            try {
+              return conditionPasses(evaluate(n, deckCtx, storyletsDialect));
+            } catch {
+              return false;
+            }
+          });
+        }
+        scored.push({ entry: { card, deck, box }, priority, spec });
+      }
+    }
+    scored.sort((a, b) => b.priority - a.priority || b.spec - a.spec);
+    let i = 0;
+    while (i < scored.length) {
+      let j = i + 1;
+      while (j < scored.length && scored[j].priority === scored[i].priority && scored[j].spec === scored[i].spec) j++;
+      if (j - i > 1) {
+        const run = scored.slice(i, j);
+        shuffleInPlace(run, this.prng);
+        for (let k = 0; k < run.length; k++) scored[i + k] = run[k];
+      }
+      i = j;
+    }
+    for (const s of scored) {
+      trace?.push({ id: s.entry.card.id, verdict: "dealt", priority: s.priority, specificity: s.spec });
+    }
+    return { ordered: scored.map((s) => s.entry), handEnv };
+  }
+  /** Flip eligible-but-not-taken trace entries to "capped". */
+  capTrace(trace, taken) {
+    for (const entry of trace) {
+      if (entry.verdict === "dealt" && !taken.has(entry.id)) entry.verdict = "capped";
+    }
+  }
+  view(entry) {
+    const { card } = entry;
+    return {
+      id: card.id,
+      gameId: effectiveGameId(card),
+      ...card.title !== void 0 ? { title: card.title } : {},
+      ...card.purpose !== void 0 ? { purpose: card.purpose } : {},
+      ...card.fields !== void 0 ? { fields: card.fields } : {}
+    };
+  }
+  handCapacity(hand) {
+    if (hand.slots !== void 0) return hand.slots;
+    const declared = hand.template !== void 0 ? this.internals.templatesById.get(hand.template)?.slots : hand.rule?.slots;
+    return declared === void 0 || declared === "unbounded" ? Infinity : declared;
+  }
+  resolveHand(ref) {
+    const found = this.internals.handsByGameId.get(ref) ?? this.internals.handsById.get(ref);
+    if (!found) throw new Error(`unknown hand "${ref}"`);
+    return found;
+  }
+  // --- host surface (schema 5) ---------------------------------------------------
+  /** Look at the top of the stock through raw tag criteria (schema 3.1):
+   *  claims respected, nothing registered, nothing left behind but the
+   *  trace line. You can never play a card you only peeked. */
+  peek(boxRef, criteria = {}, n) {
+    this.assertOpen();
+    const box = this.internals.boxesByGameId.get(boxRef) ?? this.internals.boxesById.get(boxRef);
+    if (!box) throw new Error(`unknown box "${boxRef}"`);
+    const ask = this.askForPeek(box, criteria);
+    const claimCounts = this.claims();
+    const worldClaims = this.internals.hasShared ? this.engine.sharedClaims() : /* @__PURE__ */ new Map();
+    const trace = this.tracing ? [] : void 0;
+    const { ordered } = this.runAsk(ask, (card, shared) => this.claimVerdict(card, shared, claimCounts, worldClaims), trace);
+    const listed = n === void 0 ? ordered : ordered.slice(0, Math.max(n, 0));
+    if (trace) {
+      this.capTrace(trace, new Set(listed.map((e) => e.card.id)));
+      this.emit({ type: "peek", box: effectiveGameId(box), criteria, cards: trace }, this.turnCounts.get(box.id) ?? 0);
+    }
+    return { box: effectiveGameId(box), cards: listed.map((e) => this.view(e)) };
+  }
+  /** Refresh one hand (schema 3.5); returns its new shape. */
+  deal(handRef) {
+    this.assertOpen();
+    const { hand } = this.resolveHand(handRef);
+    return this.dealMany([handRef])[effectiveGameId(hand)] ?? [];
+  }
+  /** Re-deal several / all hands (schema 3.5): seeded hand-order shuffle
+   *  (fairness), evict, seed the ledger from survivors, fill in order.
+   *  Returns the dealt slice - the new contents of exactly the hands this
+   *  call dealt, keyed by hand gameId (board() stays the whole-board read). */
+  dealMany(handRefs) {
+    this.assertOpen();
+    const dealt = (handRefs ?? [...this.internals.handsById.keys()].sort()).map((ref) => this.resolveHand(ref));
+    shuffleInPlace(dealt, this.prng);
+    for (const { hand, box } of dealt) {
+      const ask = this.askForHand(hand, box);
+      const handEnv = this.buildHandEnv(ask);
+      const conditionOk = this.passes(ask.condition, this.evalCtx(box, void 0, handEnv));
+      const gateOk = /* @__PURE__ */ new Map();
+      for (const deck of box.decks) {
+        gateOk.set(deck.id, this.passes(deck.condition, this.evalCtx(box, deck, handEnv)));
+      }
+      const turn = this.turnCounts.get(box.id) ?? 0;
+      const evicted = [];
+      const evict = (cardId, reason) => {
+        evicted.push({ card: cardId, reason });
+        return false;
+      };
+      const survivors = (this.boardContents.get(hand.id) ?? []).filter((cardId) => {
+        if (!conditionOk) return evict(cardId, "hand-condition");
+        const entry = this.internals.cardsById.get(cardId);
+        if (!entry) return evict(cardId, "vanished");
+        if (!gateOk.get(entry.deck.id)) return evict(cardId, "deck-gate");
+        if ((this.cooldowns[cardId] ?? 0) > turn) return evict(cardId, "cooldown");
+        if (!this.tagsMatch(entry.card, handEnv.boundTags)) return evict(cardId, "tags");
+        if (!this.passes(entry.card.condition, this.evalCtx(box, entry.deck, handEnv), `card ${entry.card.gameId} condition`)) {
+          return evict(cardId, "condition");
+        }
+        return true;
+      });
+      this.boardContents.set(hand.id, survivors);
+      if (this.tracing) {
+        for (const e of evicted) this.emit({ type: "evict", hand: hand.id, card: e.card, reason: e.reason }, turn);
+      }
+    }
+    const claimCounts = this.claims();
+    const worldClaims = this.internals.hasShared ? this.engine.sharedClaims() : /* @__PURE__ */ new Map();
+    for (const { hand, box } of dealt) {
+      const contents = this.boardContents.get(hand.id) ?? [];
+      const free = this.handCapacity(hand) - contents.length;
+      if (free <= 0) continue;
+      const ask = this.askForHand(hand, box);
+      const own = new Set(contents);
+      const trace = this.tracing ? [] : void 0;
+      const { ordered } = this.runAsk(
+        ask,
+        (card, shared) => own.has(card.id) ? "claimed" : this.claimVerdict(card, shared, claimCounts, worldClaims),
+        trace
+      );
+      const added = ordered.slice(0, free).map((e) => e.card.id);
+      this.boardContents.set(hand.id, [...contents, ...added]);
+      for (const id of added) {
+        claimCounts.set(id, (claimCounts.get(id) ?? 0) + 1);
+        worldClaims.set(id, (worldClaims.get(id) ?? 0) + 1);
+      }
+      if (trace) {
+        this.capTrace(trace, new Set(added));
+        this.emit({ type: "deal", hand: effectiveGameId(hand), cards: trace }, this.turnCounts.get(box.id) ?? 0);
+      }
+    }
+    return Object.fromEntries(dealt.map(({ hand }) => [
+      effectiveGameId(hand),
+      (this.boardContents.get(hand.id) ?? []).map((id) => this.view(this.internals.cardsById.get(id)))
+    ]));
+  }
+  /** The board: current hand contents, in dealt order, keyed by hand gameId
+   *  (schema 5). Read it for what is out; peek the stock for what could
+   *  come.
+   *
+   *  `boxRef` (a box gameId or id) narrows the read to that box's hands, in
+   *  the same shape and the same order: "give me the barks hands" is a
+   *  common host query, and boxes are how a game separates its storylet
+   *  systems, so the grouping belongs here rather than in every host. An
+   *  unknown box throws, as it does on turn() and peek(). */
+  board(boxRef) {
+    this.assertOpen();
+    let keep;
+    if (boxRef !== void 0) {
+      const box = this.internals.boxesByGameId.get(boxRef) ?? this.internals.boxesById.get(boxRef);
+      if (!box) throw new Error(`unknown box "${boxRef}"`);
+      keep = box.id;
+    }
+    return Object.fromEntries([...this.boardContents.entries()].filter(([handId]) => keep === void 0 || this.internals.handsById.get(handId).box.id === keep).map(([handId, ids]) => [
+      effectiveGameId(this.internals.handsById.get(handId).hand),
+      ids.map((id) => this.view(this.internals.cardsById.get(id)))
+    ]));
+  }
+  /** Resolve a played/inspected card within a hand on the board. */
+  resolveDealt(cardId, handRef) {
+    const entry = this.internals.cardsById.get(cardId) ?? this.internals.cardsByGameId.get(cardId);
+    if (!entry) throw new Error(`unknown card "${cardId}"`);
+    const { hand, box } = this.resolveHand(handRef);
+    if (!(this.boardContents.get(hand.id) ?? []).includes(entry.card.id)) {
+      throw new Error(`card "${effectiveGameId(entry.card)}" is not dealt to hand "${effectiveGameId(hand)}"`);
+    }
+    return { entry, ask: this.askForHand(hand, box) };
+  }
+  /** Outcome availability, evaluated against CURRENT state on every ask
+   *  (schema 3.1/5) - never a deal-time snapshot. */
+  outcomes(cardId, from) {
+    this.assertOpen();
+    const { entry, ask } = this.resolveDealt(cardId, from);
+    const ctx = this.evalCtx(entry.box, entry.deck, this.buildHandEnv(ask));
+    return entry.card.outcomes.map((o) => ({
+      id: o.id,
+      gameId: effectiveGameId(o),
+      ...o.title !== void 0 ? { title: o.title } : {},
+      ...o.purpose !== void 0 ? { purpose: o.purpose } : {},
+      available: this.passes(o.condition, ctx)
+    }));
+  }
+  /** Apply an outcome (schema 3.7): the card must sit in a hand on the
+   *  board (you never play a card from inside the deck). Throws before any
+   *  mutation on a gated-shut outcome or a bad write target. */
+  play(cardId, outcomeGameId, from, opts = {}) {
+    this.assertOpen();
+    const { entry, ask } = this.resolveDealt(cardId, from);
+    const outcome = entry.card.outcomes.find((o) => effectiveGameId(o) === outcomeGameId);
+    if (!outcome) throw new Error(`card "${effectiveGameId(entry.card)}" has no outcome "${outcomeGameId}"`);
+    const handEnv = this.buildHandEnv(ask);
+    const ctx = this.evalCtx(entry.box, entry.deck, handEnv);
+    if (!this.passes(outcome.condition, ctx)) {
+      throw new Error(`outcome "${outcomeGameId}" on "${effectiveGameId(entry.card)}" is gated shut`);
+    }
+    const newTurn = (this.turnCounts.get(entry.box.id) ?? 0) + (opts.advanceTurns ?? this.internals.bundle.settings.playAdvancesTurns);
+    const writes = [];
+    for (const [target, expr] of Object.entries(outcome.changes)) {
+      writes.push({ target, value: this.eval(expr, ctx) });
+    }
+    for (const { target, value } of writes) {
+      const { path, prev } = this.applyWrite(target, value, entry, handEnv);
+      if (this.tracing) this.emit({ type: "write", target, path, value, ...prev !== void 0 ? { prev } : {} }, newTurn);
+    }
+    const record = { card: effectiveGameId(entry.card), outcome: effectiveGameId(outcome), turn: newTurn };
+    this.playLog.push(record);
+    this.indexPlay(record);
+    if (entry.card.redraw === "never") {
+      if (cardIsShared(entry.card, entry.deck.shared ?? false)) this.engine.markTaken(entry.card.id);
+      else this.cooldowns[entry.card.id] = Number.MAX_SAFE_INTEGER;
+    } else if (typeof entry.card.redraw === "number") {
+      this.cooldowns[entry.card.id] = newTurn + entry.card.redraw;
+    }
+    const handId = ask.hand.id;
+    this.boardContents.set(
+      handId,
+      (this.boardContents.get(handId) ?? []).filter((id) => id !== entry.card.id)
+    );
+    this.turnCounts.set(entry.box.id, newTurn);
+    if (this.tracing) this.emit({ type: "play", card: entry.card.id, outcome: effectiveGameId(outcome), turn: newTurn }, newTurn);
+  }
+  /** Land one change in whichever partition declares the name: the flow's
+   *  bag when the property is per-flow, the shared bag when it is shared -
+   *  the union/partition invariant made executable. */
+  landIn(kind, id, name, value, path) {
+    const own = kind === "story" ? this.stores.story : id !== void 0 ? this.stores[kind].get(id) : void 0;
+    const shared = kind === "story" ? this.internals.shared.story : id !== void 0 ? this.internals.shared[kind].get(id) : void 0;
+    const bag = own !== void 0 && own.get(name) !== void 0 ? own : shared !== void 0 && shared.get(name) !== void 0 ? shared : void 0;
+    if (bag === void 0) throw new Error(`no property at "${path}"`);
+    const change = bag.set(name, value);
+    return { path, ...change.prev !== void 0 ? { prev: change.prev } : {} };
+  }
+  /** Land one change; returns the resolved store path (for the trace) and
+   *  the value it replaced (for the log's "0 -> 1" reading). */
+  applyWrite(target, value, entry, handEnv) {
+    const match = /^@([a-z]+)\.([A-Za-z_][A-Za-z0-9_-]*)$/.exec(target);
+    if (!match) throw new Error(`bad change target "${target}"`);
+    const [, scope, name] = match;
+    switch (scope) {
+      case "world": {
+        const resolver = this.internals.worldResolver;
+        if (!resolver.set) throw new Error(`@world.${name} cannot be written: the host bound @world read-only`);
+        const prev = resolver.get(name);
+        resolver.set(name, value);
+        return { path: `world.${name}`, ...prev !== void 0 ? { prev } : {} };
+      }
+      case "story":
+        return this.landIn("story", void 0, name, value, `story.${name}`);
+      case "box":
+        return this.landIn("box", entry.box.id, name, value, `box.${entry.box.id}.${name}`);
+      case "deck":
+        return this.landIn("deck", entry.deck.id, name, value, `deck.${entry.deck.id}.${name}`);
+      case "hand": {
+        const source = handEnv.sources.get(name);
+        if (!source) throw new Error(`@hand.${name} is not composed in this ask`);
+        if (source.kind === "criteria") throw new Error(`@hand.${name} is a chosen tag / criteria name and cannot be written`);
+        return this.landIn(source.kind, source.id, name, value, `${source.kind}.${source.id}.${name}`);
+      }
+      default:
+        throw new Error(`bad change target scope "@${scope}"`);
+    }
+  }
+  /** Advance one box's clock (schema 3.4): a turn is one draw-from-stock
+   *  session for that box, on THIS flow's clock. */
+  advanceTurns(boxRef, n = 1) {
+    this.assertOpen();
+    const box = this.internals.boxesByGameId.get(boxRef) ?? this.internals.boxesById.get(boxRef);
+    if (!box) throw new Error(`unknown box "${boxRef}"`);
+    const next = (this.turnCounts.get(box.id) ?? 0) + n;
+    this.turnCounts.set(box.id, next);
+    if (this.tracing) this.emit({ type: "turns", box: effectiveGameId(box), turn: next }, next);
+  }
+  // --- state access (host surface + test tooling) ---------------------------------
+  /** Every box, bundle order: identity + this flow's clock (the enumeration
+   *  surface examiners key their turns sections on; parity member). */
+  listBoxes() {
+    this.assertOpen();
+    return this.internals.bundle.boxes.map((b) => ({
+      id: b.id,
+      gameId: effectiveGameId(b),
+      ...b.title !== void 0 ? { title: b.title } : {},
+      turn: this.turnCounts.get(b.id) ?? 0
+    }));
+  }
+  /** THIS flow's kernel bags with their store path prefixes (the state
+   *  logger's mount surface; parity member). The shared bags are the
+   *  Engine's listBags; the flows are rebuilt by loadGame, so consumers
+   *  re-enumerate after a load. */
+  listBags() {
+    this.assertOpen();
+    const mounts = [{ prefix: "story", bag: this.stores.story }];
+    for (const kind of ["box", "deck", "hand", "value"]) {
+      for (const [id, bag] of this.stores[kind]) mounts.push({ prefix: `${kind}.${id}`, bag });
+    }
+    return mounts;
+  }
+  /** The flow's FULL merged view as examiner rows (the property examiner /
+   *  editor surface, parity across all runtimes): @world read through the
+   *  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() {
+    this.assertOpen();
+    const out = [];
+    for (const d of this.internals.bundle.world.properties) {
+      const value = this.internals.worldResolver.get(d.name);
+      out.push({
+        path: `world.${d.name}`,
+        name: d.name,
+        type: d.type,
+        value: value ?? d.default,
+        default: d.default,
+        ...d.values !== void 0 ? { values: d.values } : {},
+        ...d.stages !== void 0 ? { stages: d.stages } : {}
+      });
+    }
+    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 });
+      }
+    };
+    add("story", this.internals.shared.story, this.stores.story);
+    for (const kind of ["box", "deck", "hand", "value"]) {
+      const ids = /* @__PURE__ */ new Set([...this.internals.shared[kind].keys(), ...this.stores[kind].keys()]);
+      for (const id of ids) add(`${kind}.${id}`, this.internals.shared[kind].get(id), this.stores[kind].get(id));
+    }
+    return out;
+  }
+  /** 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. */
+  getProperty(path) {
+    this.assertOpen();
+    const found = this.resolvePath(path);
+    const value = found.kind === "world" ? this.internals.worldResolver.get(found.name) : found.own?.get(found.name) ?? found.shared?.get(found.name);
+    if (value === void 0) throw new Error(`no property at "${path}"`);
+    return value;
+  }
+  setProperty(path, value) {
+    this.assertOpen();
+    const found = this.resolvePath(path);
+    if (found.kind === "world") {
+      if (!this.internals.worldResolver.set) throw new Error(`@world is read-only here: the host bound no write`);
+      this.internals.worldResolver.set(found.name, value);
+      return;
+    }
+    const bag = found.own !== void 0 && found.own.get(found.name) !== void 0 ? found.own : found.shared !== void 0 && found.shared.get(found.name) !== void 0 ? found.shared : void 0;
+    if (bag === void 0) throw new Error(`no property at "${path}"`);
+    bag.set(found.name, value, { silent: true, reason: "host setProperty" });
+  }
+  resolvePath(path) {
+    const parts = path.split(".");
+    if (parts.length === 2 && parts[0] === "world") return { kind: "world", name: parts[1] };
+    if (parts.length === 2 && parts[0] === "story") {
+      return { kind: "bag", own: this.stores.story, shared: this.internals.shared.story, name: parts[1] };
+    }
+    if (parts.length === 3 && (parts[0] === "box" || parts[0] === "deck" || parts[0] === "hand" || parts[0] === "value")) {
+      const kind = parts[0];
+      const own = this.stores[kind].get(parts[1]);
+      const shared = this.internals.shared[kind].get(parts[1]);
+      if (own === void 0 && shared === void 0) throw new Error(`no ${parts[0]} store "${parts[1]}"`);
+      return { kind: "bag", ...own !== void 0 ? { own } : {}, ...shared !== void 0 ? { shared } : {}, name: parts[2] };
+    }
+    throw new Error(`bad property path "${path}"`);
+  }
+  // --- persistence (schema 4) -------------------------------------------------
+  /** @internal - this flow's blob inside the engine's envelope. */
+  snapshot() {
+    return {
+      props: partitionValues(this.stores),
+      turns: Object.fromEntries(this.turnCounts),
+      prng: this.prng.state(),
+      cooldowns: this.cooldowns,
+      board: Object.fromEntries(this.boardContents),
+      playLog: this.playLog
+    };
+  }
+  /** @internal - restore a freshly opened flow from its blob (loadGame).
+   *  Orphaned keys (deleted entities) drop; new declarations keep defaults. */
+  restore(saved) {
+    loadPartition(this.stores, saved.props);
+    this.turnCounts = new Map(this.internals.bundle.boxes.map((b) => [b.id, 0]));
+    for (const [boxId, turn] of Object.entries(saved.turns ?? {})) {
+      if (this.turnCounts.has(boxId)) this.turnCounts.set(boxId, turn);
+    }
+    this.prng = makePrng(saved.prng);
+    this.cooldowns = saved.cooldowns ?? {};
+    this.playLog = saved.playLog ?? [];
+    this.rebuildPlayIndex();
+    this.boardContents = new Map(Object.entries(saved.board ?? {}).filter(([handId]) => this.internals.handsById.has(handId)).map(([handId, ids]) => [handId, ids.filter((id) => this.internals.cardsById.has(id))]));
+    for (const handId of this.internals.handsById.keys()) {
+      if (!this.boardContents.has(handId)) this.boardContents.set(handId, []);
+    }
+  }
+};
+
+// src/describe.ts
+var summarise = (decls) => decls.map((d) => ({
+  name: d.name,
+  type: d.type,
+  default: d.default,
+  ...d.values !== void 0 ? { values: d.values } : {},
+  ...d.purpose !== void 0 ? { purpose: d.purpose } : {}
+}));
+var handDecls = (hand, box) => {
+  if (hand.template !== void 0) {
+    return box.handTemplates.find((t) => t.id === hand.template)?.properties ?? [];
+  }
+  return hand.properties ?? [];
+};
+var handSlots = (hand, box) => {
+  if (hand.slots !== void 0) return hand.slots;
+  const declared = hand.template !== void 0 ? box.handTemplates.find((t) => t.id === hand.template)?.slots : hand.rule?.slots;
+  return declared === void 0 ? "unbounded" : declared;
+};
+function describeBundle(bundle) {
+  const boxes = [];
+  const hands = [];
+  const properties = [
+    { scope: "world", owner: "", properties: summarise(bundle.world.properties) },
+    { scope: "story", owner: "", properties: summarise(bundle.story.properties) }
+  ];
+  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 cards = box.decks.reduce((n, deck) => n + deck.cards.length, 0);
+    boxes.push({
+      gameId: boxGameId,
+      ...box.title !== void 0 ? { title: box.title } : {},
+      ranking: { specificity: box.ranking.specificity },
+      tagGroups: box.tagGroups.map((group) => ({
+        gameId: effectiveGameId(group),
+        tags: group.tags.map((tag) => effectiveGameId(tag))
+      })),
+      counts: {
+        decks: box.decks.length,
+        cards,
+        hands: box.hands.length,
+        templates: box.handTemplates.length,
+        tagGroups: box.tagGroups.length
+      }
+    });
+    totals.boxes += 1;
+    totals.decks += box.decks.length;
+    totals.cards += cards;
+    totals.hands += box.hands.length;
+    totals.templates += box.handTemplates.length;
+    totals.tagGroups += box.tagGroups.length;
+    for (const hand of box.hands) {
+      const template = hand.template !== void 0 ? box.handTemplates.find((t) => t.id === hand.template) : void 0;
+      hands.push({
+        gameId: effectiveGameId(hand),
+        ...hand.title !== void 0 ? { title: hand.title } : {},
+        box: boxGameId,
+        slots: handSlots(hand, box),
+        ...template !== void 0 ? { template: effectiveGameId(template) } : {}
+      });
+    }
+    const push = (scope, owner, decls, group) => {
+      if (decls.length === 0) return;
+      properties.push({
+        scope,
+        owner,
+        box: boxGameId,
+        ...group !== void 0 ? { group } : {},
+        properties: summarise(decls)
+      });
+    };
+    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 group of box.tagGroups) {
+      for (const tag of group.tags) {
+        push("tag", effectiveGameId(tag), tag.properties ?? [], effectiveGameId(group));
+      }
+    }
+  }
+  return {
+    identity: {
+      schema: bundle.schema,
+      project: bundle.content.project,
+      version: bundle.content.version,
+      hash: bundle.content.hash,
+      metadata: bundle.metadata
+    },
+    totals,
+    boxes,
+    hands,
+    properties,
+    maps: (bundle.maps ?? []).map((map) => ({
+      box: map.box,
+      group: map.group,
+      zones: map.zones.length,
+      backgrounds: map.backgrounds?.length ?? 0
+    }))
+  };
+}
+export {
+  Engine,
+  Flow,
+  describeBundle,
+  makePrng,
+  shuffleInPlace
+};
+//# sourceMappingURL=index.js.map