@storylet-studio/runtime 0.7.0 → 0.8.1

package/dist/index.cjs

@@ -287,6 +287,12 @@ function walk(node, want, evalTruthy, countingCalls) {
   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 ?? {};
@@ -306,16 +312,17 @@ var flagsArg = (fn, args, h) => {
   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).
+  // 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: [
-    { token: "story", missing: "throw" },
-    { token: "world", missing: "throw" },
-    { token: "box", missing: "throw" },
-    { token: "deck", missing: "throw" },
-    { token: "hand", missing: "throw" }
+    ...OWN_SCOPES.map((token) => ({ token, missing: "throw" })),
+    ...EXTERNAL_SCOPES.map((token) => ({ token, missing: "throw" }))
   ],
   defaultScope: "story",
   functions: {
@@ -480,6 +487,8 @@ 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";
 
 // ../../../expr/packages/scoperegistry/src/index.ts
 var PropertyBag = class _PropertyBag {
@@ -512,6 +521,13 @@ var PropertyBag = class _PropertyBag {
   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
@@ -595,6 +611,328 @@ function rowFor(d, value, writable, name, pathPrefix = "") {
     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) {
@@ -625,6 +963,48 @@ function defaultFor(d) {
 var tagKey = (groupId, tagId) => `${groupId}${tagId}`;
 var cardIsShared = (card, deckShared) => card.shared ?? deckShared;
 var sharedCap = (card) => card.sharedCopies ?? card.copies ?? 1;
+var OWNER = "Storylet Engine";
+var identity = (n) => n;
+var esc = (id) => id.replace(/%/g, "%25").replace(/\//g, "%2F");
+var unesc = (id) => id.replace(/%2F/g, "/").replace(/%25/g, "%");
+var sharedKey = (kind, id) => `storylets/${kind}/${esc(id)}`;
+var flowPrefix = (flowId) => `storylets/flow/${esc(flowId)}/`;
+var flowKey = (flowId, kind, id) => kind === "story" ? `${flowPrefix(flowId)}story` : `${flowPrefix(flowId)}${kind}/${esc(id)}`;
+var emptyPartitionValues = () => ({ story: {}, box: {}, deck: {}, hand: {}, value: {} });
+function partitionsFromSections(sections, flowIds) {
+  const shared = emptyPartitionValues();
+  const flows = /* @__PURE__ */ new Map();
+  const rest = {};
+  const flowOf = (escaped) => {
+    const id = unesc(escaped);
+    if (!flowIds.has(id)) return void 0;
+    let p = flows.get(id);
+    if (!p) {
+      p = emptyPartitionValues();
+      flows.set(id, p);
+    }
+    return p;
+  };
+  for (const [key, values] of Object.entries(sections)) {
+    let m;
+    if (key === "story") shared.story = values;
+    else if (m = /^storylets\/(box|deck|hand|value)\/([^/]+)$/.exec(key)) shared[m[1]][unesc(m[2])] = values;
+    else if (m = /^storylets\/flow\/([^/]+)\/story$/.exec(key)) {
+      const p = flowOf(m[1]);
+      if (p) p.story = values;
+    } else if (m = /^storylets\/flow\/([^/]+)\/(box|deck|hand|value)\/([^/]+)$/.exec(key)) {
+      const p = flowOf(m[1]);
+      if (p) p[m[2]][unesc(m[3])] = values;
+    } else if (!key.startsWith("storylets/")) rest[key] = values;
+  }
+  return { shared, flows, rest };
+}
+function sectionsOf(p, keyOf, out) {
+  if (Object.keys(p.story).length > 0) out[keyOf("story")] = p.story;
+  for (const kind of ["box", "deck", "hand", "value"]) {
+    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 });
 function conditionPasses(v) {
   if (typeof v === "boolean") return v;
@@ -809,7 +1189,7 @@ function finishReport(bundle, saved, flows, draft) {
     retypedProperties
   };
 }
-var Engine = class {
+var Engine = class _Engine {
   internals;
   seed;
   onReplacedFlow;
@@ -819,7 +1199,13 @@ var Engine = class {
    *  outlives reset/loadGame (the host's container is the host's). The
    *  self-backed resolver is rebuilt instead. */
   hostWorld;
+  /** The options this engine was built with: hotSwap builds its replacement from them. */
+  creationOptions;
+  /** How to register each shared scope again, in registration order: a failed
+   *  hotSwap puts this engine back exactly as it was. */
+  sharedMounts = [];
   constructor(bundle, opts = {}) {
+    this.creationOptions = opts;
     this.seed = opts.seed ?? 0;
     this.onReplacedFlow = opts.onReplacedFlow;
     if (opts.world !== void 0) this.hostWorld = opts.world;
@@ -843,6 +1229,10 @@ var Engine = class {
       flowDecls: { story: [], box: /* @__PURE__ */ new Map(), deck: /* @__PURE__ */ new Map(), hand: /* @__PURE__ */ new Map(), value: /* @__PURE__ */ new Map() },
       sharedDecls: { story: [], box: /* @__PURE__ */ new Map(), deck: /* @__PURE__ */ new Map(), hand: /* @__PURE__ */ new Map(), value: /* @__PURE__ */ new Map() },
       shared: void 0,
+      registry: opts.registry ?? new ScopeRegistry(),
+      ownsRegistry: opts.registry === void 0,
+      selfWorld: false,
+      registryView: () => view(),
       worldResolver: void 0,
       worldReadOnly: /* @__PURE__ */ new Set(),
       emitEngine: (flow, event, turn) => {
@@ -857,6 +1247,19 @@ var Engine = class {
       engineTracing: () => this.engineTraceHandlers.size > 0
     };
     this.internals = internals;
+    let viewRevision = -1;
+    let viewCache = { scopes: {}, qualities: void 0 };
+    const view = () => {
+      const reg = internals.registry;
+      if (reg.revision !== viewRevision) {
+        const ctx = reg.toEvalContext();
+        const scopes = {};
+        for (const [k, v] of Object.entries(ctx.scopes)) if (!k.includes("/")) scopes[k] = v;
+        viewCache = { scopes, qualities: ctx.qualities };
+        viewRevision = reg.revision;
+      }
+      return viewCache;
+    };
     indexValueOwners(internals.owners.value, bundle);
     for (const box of bundle.boxes) {
       internals.boxesById.set(box.id, box);
@@ -903,34 +1306,79 @@ var Engine = class {
     internals.sharedDecls = declSet(sharedHalf);
     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. */
+  /** Build the shared stores, register them and @world, and set up the @world
+   *  seam. Once, for the engine's life: reset and loads reseed the bags in
+   *  place, so the registry never sees them come and go. */
   initShared(hostWorld) {
     const internals = this.internals;
+    const reg = internals.registry;
+    const worldDecls = internals.bundle.world.properties;
     internals.shared = buildPartition(internals, sharedHalf);
     internals.worldReadOnly = new Set(internals.bundle.world.properties.filter((d) => d.writable === false).map((d) => d.name));
+    const registered = [];
+    const mount = (key, register) => {
+      register();
+      registered.push(key);
+      this.sharedMounts.push({ key, mount: register });
+    };
+    try {
+      const story = internals.shared.story;
+      mount("story", () => {
+        reg.mountOwned("story", story, { owner: OWNER });
+      });
+      for (const kind of OWNED_SCOPES) {
+        for (const [id, bag] of internals.shared[kind]) {
+          if (bag.declarations().length === 0) continue;
+          mount(sharedKey(kind, id), () => {
+            reg.mountOwned(sharedKey(kind, id), bag, { owner: OWNER });
+          });
+        }
+      }
+      if (hostWorld !== void 0) {
+        mount("world", () => {
+          reg.defineForeign("world", hostWorld, worldDecls, { normalise: identity, owner: OWNER });
+        });
+      } else if (internals.ownsRegistry && !reg.has("world")) {
+        reg.defineOwned("world", worldDecls, { normalise: identity, pathPrefix: "world.", owner: OWNER });
+        const worldBag = reg.ownedBag("world");
+        registered.push("world");
+        this.sharedMounts.push({ key: "world", mount: () => {
+          reg.mountOwned("world", worldBag, { owner: OWNER });
+        } });
+        internals.selfWorld = true;
+      }
+    } catch (e) {
+      for (const k of registered) reg.remove(k, { keep: true });
+      throw e;
+    }
+    internals.worldResolver = {
+      get: (n) => reg.get("world", n),
+      set: (n, v) => {
+        reg.set("world", n, v);
+      }
+    };
     if (hostWorld !== void 0) {
-      internals.worldResolver = hostWorld;
-      const set = hostWorld.set;
-      internals.worldSet = set !== void 0 ? (n, v) => {
-        set(n, v);
+      internals.worldSet = hostWorld.set !== void 0 ? (n, v) => {
+        reg.set("world", n, v, { host: true });
       } : void 0;
     } else {
-      const bag = bagFromDecls(internals.bundle.world.properties, "world.");
-      internals.worldResolver = {
-        // The engine writes through worldSet below, not through this; the `set`
-        // is the resolver's SHAPE, so @world still reads as writable to anything
-        // inspecting the seam, and it is the story's door: no host flag on it.
-        get: (n) => bag.get(n),
-        set: (n, v) => {
-          bag.set(n, v);
-        }
-      };
       internals.worldSet = (n, v, host2) => {
-        bag.set(n, v, host2 === true ? { host: true } : void 0);
+        reg.set("world", n, v, host2 === true ? { host: true } : void 0);
       };
     }
   }
+  /** Every shared bag back to its declared defaults, in place (the registry
+   *  keeps them registered), the self-backed @world included. */
+  reseedShared() {
+    const { shared, sharedDecls, registry } = this.internals;
+    shared.story.reseed(sharedDecls.story);
+    for (const kind of OWNED_SCOPES) {
+      for (const [id, bag] of shared[kind]) bag.reseed(sharedDecls[kind].get(id) ?? []);
+    }
+    if (this.internals.selfWorld) {
+      registry.reseedOwned("world", this.internals.bundle.world.properties);
+    }
+  }
   /** 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
@@ -962,6 +1410,13 @@ var Engine = class {
    *  state; shared state is untouched. There is no default flow: "main" is
    *  a caller convention, not an engine rule. */
   openFlow(id, opts = {}) {
+    return this.open(id, opts, false);
+  }
+  /** openFlow, and loadGame's rebuild. `claim` says the new flow's bags take
+   *  the values the registry holds for them (a load); a fresh open is a reset
+   *  of that name, so anything waiting for it is discarded first. */
+  open(id, opts, claim) {
+    this.assertExternalScopes();
     const otherClaims = opts.restore !== void 0 ? this.sharedClaimsExcept(id) : void 0;
     const existing = this.flowsById.get(id);
     if (existing) {
@@ -969,6 +1424,7 @@ var Engine = class {
       if (dealt > 0) this.onReplacedFlow?.(id, dealt);
       existing.markClosed();
     }
+    if (!claim) this.internals.registry.discardParked(flowPrefix(id));
     const flow = new Flow(this, this.internals, id, opts.seed ?? this.seed);
     this.flowsById.set(id, flow);
     if (opts.restore !== void 0) {
@@ -1005,11 +1461,22 @@ var Engine = class {
    *  self-backed @world included; a host-bound @world is the host's and is
    *  not touched). */
   reset() {
+    this.dropRun(false);
+    this.reseedShared();
+    this.internals.registry.discardParked("storylets/");
+  }
+  /** End the run: clear the log, close every flow, forget spent cards. Each
+   *  flow's bags leave the registry; `keepFlows` names the flows whose values
+   *  are kept there for the flow that replaces them (a load into the game's
+   *  registry). */
+  dropRun(keepFlows) {
     this.engineLog = [];
-    for (const flow of this.flowsById.values()) flow.markClosed();
+    for (const [id, flow] of this.flowsById) {
+      flow.releaseBags(keepFlows !== false && keepFlows.has(id));
+      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.
@@ -1071,7 +1538,7 @@ var Engine = class {
    */
   getProperty(path) {
     const found = this.resolveShared(path);
-    const value = found.kind === "world" ? this.internals.worldResolver.get(found.name) : found.bag.get(found.name);
+    const value = found.kind === "world" ? this.internals.worldResolver.get(found.name) : found.kind === "scope" ? this.internals.registry.get(found.token, found.name) : found.bag.get(found.name);
     if (value === void 0) throw new Error(`no property at "${path}"`);
     return value;
   }
@@ -1084,6 +1551,10 @@ var Engine = class {
       this.internals.worldSet(found.name, value, true);
       return;
     }
+    if (found.kind === "scope") {
+      this.internals.registry.set(found.token, found.name, value, { host: true });
+      return;
+    }
     found.bag.set(found.name, value, { silent: true, reason: "host setProperty", host: true });
   }
   resolveShared(path) {
@@ -1092,6 +1563,9 @@ var Engine = class {
       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" && this.internals.registry.has(parts[0])) {
+      return { kind: "scope", token: parts[0], 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 };
@@ -1119,6 +1593,18 @@ var Engine = class {
   diagnose(message) {
     this.internals.emitEngine("", { type: "diagnostic", where: "property address", message });
   }
+  /** Content that names another engine's scope (`@patter.visits`) runs only
+   *  where that engine is on this registry: without it every read would answer
+   *  false and every write fail, so the flow is refused as it opens, before
+   *  anything changes. By then a game has built all of its engines, whatever
+   *  order it built them in. The same message on every runtime. */
+  assertExternalScopes() {
+    for (const token of this.internals.bundle.externalScopes ?? []) {
+      if (!this.internals.registry.has(token)) {
+        throw new Error(`this content names @${token}, which no engine on this registry registered: give every engine the game's one registry`);
+      }
+    }
+  }
   /** The shared surface as examiner rows: @world (read through the
    *  resolver) then the shared partitions. Per-flow rows live on each Flow. */
   listProperties() {
@@ -1170,15 +1656,77 @@ var Engine = class {
     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. */
+  /**
+   * Live bundle refresh: rebuild on an edited bundle with the whole run carried
+   * over, and return the replacement with the report its load produced.
+   *
+   * Standalone, that is a save and a load into a new engine, and this one is left
+   * untouched (discard it). With the game's registry the two cannot both hold the
+   * same keys, so this engine is spent afterwards (its flows closed, the
+   * replacement holding everything on the same registry): it carries its
+   * own values into the snapshot, steps out of the registry, and the replacement
+   * loads them the way a standalone save loads: so the report covers the
+   * properties the edit dropped, defaulted, or retyped, and a dropped property
+   * is dropped rather than kept. Values the game loaded that were still waiting
+   * for a flow of this engine carry across as they were, and nothing belonging
+   * to any other engine is touched. A save for another project is refused before
+   * anything moves; if the rebuild fails for any other reason, this engine takes
+   * its registrations back and is left exactly as it was.
+   */
+  hotSwap(bundle, opts = {}) {
+    if (bundle.content.project !== this.internals.bundle.content.project) {
+      throw new Error(`save is for project "${this.internals.bundle.content.project}", bundle is "${bundle.content.project}"`);
+    }
+    const options = { ...this.creationOptions, ...opts };
+    const snapshot = this.saveGame();
+    const reg = this.internals.registry;
+    if (this.internals.ownsRegistry) {
+      const next2 = new _Engine(bundle, { ...options, registry: void 0 });
+      return { engine: next2, report: next2.loadGame(snapshot) };
+    }
+    const mine = {};
+    for (const [key, values] of Object.entries(reg.save())) {
+      if (key === "story" || key.startsWith("storylets/")) mine[key] = values;
+    }
+    const registeredKeys = /* @__PURE__ */ new Set([
+      ...this.sharedMounts.map((m) => m.key),
+      ...[...this.flowsById.values()].flatMap((f) => f.registeredKeys())
+    ]);
+    const waiting = Object.fromEntries(Object.entries(mine).filter(([key]) => !registeredKeys.has(key)));
+    for (const { key } of this.sharedMounts) if (reg.has(key)) reg.remove(key);
+    for (const flow of this.flowsById.values()) flow.releaseBags(false);
+    let next;
+    try {
+      next = new _Engine(bundle, { ...options, registry: reg });
+      const report = next.loadGame({ ...snapshot, registry: mine });
+      const stillWaiting = Object.fromEntries(Object.entries(waiting).filter(([key]) => !reg.has(key)));
+      if (Object.keys(stillWaiting).length > 0) reg.load(stillWaiting, { keepParked: true });
+      this.dropRun(false);
+      return { engine: next, report };
+    } catch (e) {
+      next?.dropRun(false);
+      for (const { key } of next?.sharedMounts ?? []) if (reg.has(key)) reg.remove(key);
+      reg.discardParked("storylets/");
+      for (const { mount } of this.sharedMounts) mount();
+      for (const flow of this.flowsById.values()) flow.mountBags();
+      this.reseedShared();
+      reg.load(mine, { keepParked: true });
+      throw e;
+    }
+  }
+  /** The whole engine's NON-property state, one envelope: the spent cards
+   *  once, then every live flow (board, clocks, cooldowns, PRNG, play log)
+   *  keyed by its id. The property values are the registry's: a standalone
+   *  engine (one that made its own registry) carries them here under
+   *  `registry`, self-backed @world included; a game that passed a registry
+   *  saves it once itself, beside each engine's envelope. */
   saveGame() {
     return structuredClone({
-      schema: "storylets/save@1",
+      schema: SAVE_SCHEMA,
       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()]))
+      ...this.internals.ownsRegistry ? { registry: this.internals.registry.save() } : {},
+      shared: { spent: [...this.spent].sort() },
+      flows: Object.fromEntries([...this.flowsById].map(([id, flow]) => [id, flow.snapshot(false)]))
     });
   }
   /** ONE flow's blob, to park a visit that is walking away: the same shape
@@ -1190,7 +1738,7 @@ var Engine = class {
   saveFlow(id) {
     const flow = this.flowsById.get(id);
     if (!flow) throw new Error(`unknown flow "${id}"`);
-    return structuredClone(flow.snapshot());
+    return structuredClone(flow.snapshot(true));
   }
   /** What `loadGame(envelope)` would do that is not a plain restore, without
    *  doing any of it (design/engine-server.md 4.9). Pure: nothing on this
@@ -1213,16 +1761,31 @@ var Engine = class {
    *  Handles held from before the load are closed and inert (Patter's
    *  rule); take fresh ones from getFlow()/flows().
    *
+   *  Property values come from the registry. An envelope that carries them
+   *  (a standalone engine's, or a version 1 envelope) has them walked, cleaned,
+   *  and moved into the registry here, over fresh defaults. Otherwise the game
+   *  loads its registry itself, before or after this call: each flow's bags
+   *  are handed back to the registry with their values, and the restored
+   *  flows claim them. The report then covers only what this envelope holds;
+   *  the registry's own load rule applies to the values.
+   *
    *  Returns the report `previewLoad` would have given for this envelope: the
    *  drift tolerance that makes a load forgiving is what hides its cost, so
    *  the cost comes back with the load whether or not anybody looked first. */
   loadGame(envelope) {
     this.assertSameProject(envelope);
+    this.assertExternalScopes();
     const plan = this.planLoad(structuredClone(envelope));
-    this.reset();
-    loadPartition(this.internals.shared, plan.shared);
+    const reg = this.internals.registry;
+    if (plan.sections !== void 0) {
+      this.reset();
+      if (this.internals.ownsRegistry) reg.load(plan.sections);
+      else reg.load(plan.sections, { keepParked: true });
+    } else {
+      this.dropRun(new Set(plan.flows.map(([id]) => id)));
+    }
     for (const id of plan.spent) this.spent.add(id);
-    for (const [id, clean] of plan.flows) this.openFlow(id).restore(clean);
+    for (const [id, clean] of plan.flows) this.open(id, {}, true).restore(clean);
     return plan.report;
   }
   assertSameProject(envelope) {
@@ -1234,26 +1797,43 @@ var Engine = class {
    *  half writes. Nothing here touches the engine, which is what lets
    *  previewLoad and loadGame share it. */
   planLoad(envelope) {
+    const schema = envelope.schema;
+    if (schema !== SAVE_SCHEMA && schema !== SAVE_SCHEMA_V1) throw new Error(`unsupported save schema: ${String(schema)}`);
     const draft = emptyDraft();
-    const shared = walkPartition(
-      this.internals,
-      this.internals.sharedDecls,
-      envelope.shared?.props,
-      void 0,
-      draft
-    );
+    const flowIds = new Set(Object.keys(envelope.flows ?? {}));
+    let moved;
+    if (envelope.schema === SAVE_SCHEMA_V1) {
+      moved = {
+        shared: envelope.shared?.props ?? emptyPartitionValues(),
+        flows: new Map(Object.entries(envelope.flows ?? {}).map(([id, f]) => [id, f.props ?? emptyPartitionValues()])),
+        rest: {}
+      };
+    } else if (envelope.registry !== void 0) {
+      moved = partitionsFromSections(envelope.registry, flowIds);
+    }
+    const shared = moved !== void 0 ? walkPartition(this.internals, this.internals.sharedDecls, moved.shared, void 0, draft) : void 0;
     const spent = [];
     for (const cardId of envelope.shared?.spent ?? []) {
       if (this.internals.cardsById.has(cardId)) spent.push(cardId);
       else draft.droppedSpent.push(cardId);
     }
     const flows = [];
+    const sections = moved !== void 0 ? { ...moved.rest } : void 0;
+    if (sections !== void 0 && shared !== void 0) {
+      sectionsOf(shared, (kind, id) => kind === "story" ? "story" : sharedKey(kind, id), sections);
+    }
     for (const [id, saved] of Object.entries(envelope.flows ?? {})) {
-      flows.push([id, this.planFlowRestore(id, saved, void 0, draft)]);
+      const withProps = moved !== void 0 ? { ...saved, props: moved.flows.get(id) ?? emptyPartitionValues() } : { ...saved };
+      const clean = this.planFlowRestore(id, withProps, void 0, draft);
+      if (sections !== void 0 && clean.props !== void 0) {
+        sectionsOf(clean.props, (kind, owner) => flowKey(id, kind, owner), sections);
+        delete clean.props;
+      }
+      flows.push([id, clean]);
     }
     return {
       report: finishReport(this.internals.bundle.content, envelope.content, flows.map(([id]) => id), draft),
-      shared,
+      ...sections !== void 0 ? { sections } : {},
       spent,
       flows
     };
@@ -1264,7 +1844,7 @@ var Engine = class {
    *  there is nobody else to compete with. */
   planFlowRestore(id, saved, otherClaims, draft) {
     const internals = this.internals;
-    const props = walkPartition(internals, internals.flowDecls, saved.props, id, draft);
+    const props = saved.props !== void 0 ? walkPartition(internals, internals.flowDecls, saved.props, id, draft) : void 0;
     const cooldowns = {};
     for (const [cardId, turn] of Object.entries(saved.cooldowns ?? {})) {
       if (internals.cardsById.has(cardId)) cooldowns[cardId] = turn;
@@ -1305,7 +1885,7 @@ var Engine = class {
       board[handId] = kept;
     }
     return {
-      props,
+      ...props !== void 0 ? { props } : {},
       turns: saved.turns ?? {},
       prng: saved.prng,
       cooldowns,
@@ -1348,8 +1928,12 @@ var Flow = class {
   lastPlayOf = /* @__PURE__ */ new Map();
   tagPlayCount = /* @__PURE__ */ new Map();
   lastPlayInTag = /* @__PURE__ */ new Map();
-  /** The per-flow property partitions (the not-shared halves). */
+  /** The per-flow property partitions (the not-shared halves), each bag
+   *  that declares something registered under this flow's keys. */
   stores;
+  registered = [];
+  /** This flow's bags that declare something, under their registry keys. */
+  bagKeys = [];
   traceHandlers = /* @__PURE__ */ new Set();
   logEntries = [];
   logSeq = 0;
@@ -1367,6 +1951,13 @@ var Flow = class {
     this.id = id;
     this.prng = makePrng(seed);
     this.stores = buildPartition(internals, flowHalf);
+    const put = (key, bag) => {
+      if (bag.declarations().length === 0) return;
+      this.bagKeys.push([key, bag]);
+    };
+    put(flowKey(id, "story"), this.stores.story);
+    for (const kind of OWNED_SCOPES) for (const [owner, bag] of this.stores[kind]) put(flowKey(id, kind, owner), bag);
+    this.mountBags();
     for (const box of internals.bundle.boxes) {
       this.turnCounts.set(box.id, 0);
       for (const hand of box.hands) this.boardContents.set(hand.id, []);
@@ -1394,8 +1985,28 @@ var Flow = class {
   }
   /** @internal */
   markClosed() {
+    this.releaseBags(false);
     this.closed = true;
   }
+  /** @internal - take this flow's bags out of the registry; with `keep`, their
+   *  values wait there for the flow that replaces this one (a load into the
+   *  game's registry). Idempotent. */
+  releaseBags(keep) {
+    for (const key of this.registered) this.internals.registry.remove(key, { keep });
+    this.registered.length = 0;
+  }
+  /** @internal - the registry keys this flow holds right now. */
+  registeredKeys() {
+    return [...this.registered];
+  }
+  /** @internal - register this flow's bags (again): at construction, and when a
+   *  failed hotSwap hands them back. Each claims what the registry holds for it. */
+  mountBags() {
+    for (const [key, bag] of this.bagKeys) {
+      this.internals.registry.mountOwned(key, bag, { owner: OWNER });
+      this.registered.push(key);
+    }
+  }
   assertOpen() {
     if (this.closed) throw new Error(`flow "${this.id}" is closed`);
   }
@@ -1532,8 +2143,12 @@ var Flow = class {
    *  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) {
+    const others = this.internals.registryView();
     return {
       scopes: {
+        // Every other engine's game-wide scope first (every engine reads every
+        // scope); this engine's own tokens are its merged views, over the top.
+        ...others.scopes,
         world: this.internals.worldResolver,
         story: this.storyReader,
         box: this.boxReaders.get(box.id) ?? {},
@@ -1544,8 +2159,8 @@ var Flow = class {
       // 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
+      ...this.internals.hasQualities || others.qualities !== void 0 ? {
+        qualities: (scope, name) => scope === "world" ? this.internals.ladders.world.get(name) ?? others.qualities?.(scope, 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) : others.qualities?.(scope, name)
       } : {}
     };
   }
@@ -2184,8 +2799,17 @@ var Flow = class {
         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, `${this.address(source.kind, source.id)}.${name}`);
       }
-      default:
+      default: {
+        if (this.internals.registry.has(scope)) {
+          const prev = this.internals.registry.get(scope, name);
+          this.internals.registry.set(scope, name, value);
+          return { path: `${scope}.${name}`, ...prev !== void 0 ? { prev } : {} };
+        }
+        if (this.internals.bundle.externalScopes?.includes(scope)) {
+          throw new Error(`@${scope}.${name} cannot be written: no engine on this registry registered @${scope}`);
+        }
         throw new Error(`bad change target scope "@${scope}"`);
+      }
     }
   }
   /** Advance one box's clock (schema 3.4): a turn is one draw-from-stock
@@ -2278,7 +2902,7 @@ var Flow = class {
   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);
+    const value = found.kind === "world" ? this.internals.worldResolver.get(found.name) : found.kind === "scope" ? this.internals.registry.get(found.token, 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;
   }
@@ -2290,6 +2914,10 @@ var Flow = class {
       this.internals.worldSet(found.name, value, true);
       return;
     }
+    if (found.kind === "scope") {
+      this.internals.registry.set(found.token, found.name, value, { host: true });
+      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", host: true });
@@ -2297,6 +2925,9 @@ var Flow = class {
   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" && this.internals.registry.has(parts[0])) {
+      return { kind: "scope", token: parts[0], 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] };
     }
@@ -2315,10 +2946,11 @@ var Flow = class {
     throw new Error(`bad property path "${path}"`);
   }
   // --- persistence (schema 4) -------------------------------------------------
-  /** @internal - this flow's blob inside the engine's envelope. */
-  snapshot() {
+  /** @internal - this flow's blob: inside the engine's envelope without its
+   *  properties (the registry has them), or parked whole by saveFlow. */
+  snapshot(withProps) {
     return {
-      props: partitionValues(this.stores),
+      ...withProps ? { props: partitionValues(this.stores) } : {},
       turns: Object.fromEntries(this.turnCounts),
       prng: this.prng.state(),
       cooldowns: this.cooldowns,
@@ -2329,7 +2961,7 @@ var Flow = class {
   /** @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);
+    if (saved.props !== void 0) 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);