@wildwinter/scoperegistry 0.1.0 → 0.3.0

package/README.md

@@ -27,6 +27,27 @@ another engine.
 settable per scope (a resolver with no `set`) and per property
 (`writable: false`), enforced by `set`.
 
+Since 0.2.0 this package is also the **state kernel** the Patter and
+Storylet Engine runtime families share (their "one properties implementer"):
+
+- **`PropertyBag`** is a first-class citizen: typed declarations + defaults,
+  the firing rule (engine writes notify `subscribe`rs; host writes pass
+  `{ silent: true, reason }` and reach only the always-on `onAudit` hook),
+  examiner `rows()`, one sanctioned `clone()` door, in-place `reseed`, and
+  bare-value `save()`/`load()`. Name normalisation is a policy: lowercase by
+  default, or pass `{ normalise }` (a case-significant product passes
+  identity).
+- Owned registry scopes are bags: `ownedBag(token)` exposes them, and
+  `mountOwned(token, bag)` attaches a bag another holder owns (the shared
+  state container for a mixed two-engine game).
+- **`listProperties()`** returns examiner rows across owned scopes and
+  declared foreign scopes, for the shared in-engine property panels.
+- **`saveFragment()`/`loadFragment()`** speak a versioned
+  `OwnedStateFragment` (`{ version, scopes }`), the one serialisation shape
+  both products' save envelopes embed when they adopt the kernel.
+  `save()`/`load()` keep the bare 0.1.x shape, so existing consumers' save
+  formats are untouched.
+
 ```ts
 import { ScopeRegistry } from "@wildwinter/scoperegistry";
 

package/dist/index.cjs

@@ -20,6 +20,106 @@ function readScopeRegistrySpec(source) {
   }
   return spec;
 }
+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
+  };
+}
+var SAVE_FRAGMENT_VERSION = 1;
 var ScopeRegistry = class {
   scopes = /* @__PURE__ */ new Map();
   /**
@@ -28,17 +128,24 @@ var ScopeRegistry = class {
    * type-checked (declarations) and serialized by `save`/`load`.
    */
   defineOwned(token, declarations) {
+    return this.mountOwned(token, new PropertyBag(declarations));
+  }
+  /**
+   * Attach an EXISTING bag as an owned scope - the shared-container move: a
+   * host (or the other product) holds the bag; this registry reads, writes
+   * and lists it like its own, but the holder saves it.
+   */
+  mountOwned(token, bag) {
     this.assertFree(token);
-    const bag = {};
-    const decls = /* @__PURE__ */ new Map();
-    for (const d of declarations) {
-      const name = d.name.toLowerCase();
-      decls.set(name, d);
-      bag[name] = d.default ?? defaultFor(d);
-    }
-    this.scopes.set(token, { kind: "owned", bag, decls });
+    this.scopes.set(token, { kind: "owned", bag });
     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
@@ -47,15 +154,7 @@ var ScopeRegistry = class {
    * registry stays valid.
    */
   reseedOwned(token, declarations) {
-    const e = this.scopes.get(token);
-    if (!e || e.kind !== "owned") throw new Error(`'@${token}' is not an owned scope`);
-    for (const k of Object.keys(e.bag)) delete e.bag[k];
-    e.decls.clear();
-    for (const d of declarations) {
-      const name = d.name.toLowerCase();
-      e.decls.set(name, d);
-      e.bag[name] = d.default ?? defaultFor(d);
-    }
+    this.ownedBag(token).reseed(declarations);
     return this;
   }
   /**
@@ -78,23 +177,49 @@ var ScopeRegistry = class {
   get(scope, name) {
     const e = this.scopes.get(scope);
     if (!e) return void 0;
-    const n = name.toLowerCase();
-    return e.kind === "owned" ? e.bag[n] : e.resolver.get(n);
+    return e.kind === "owned" ? e.bag.get(name) : e.resolver.get(name.toLowerCase());
   }
-  /** Write a property. Throws on an unknown or read-only scope/property. */
+  /** Write a property (an ENGINE write: the bag's subscribers fire; use
+   *  the bag directly for silent host writes). Throws on an unknown or
+   *  read-only scope/property. */
   set(scope, name, value) {
     const e = this.scopes.get(scope);
     if (!e) throw new Error(`unknown scope '@${scope}'`);
+    if (e.kind === "owned") {
+      try {
+        e.bag.set(name, value);
+      } catch {
+        throw new Error(`'@${scope}.${name}' is read-only`);
+      }
+      return;
+    }
     const n = name.toLowerCase();
-    if (!this.writable(e, n)) throw new Error(`'@${scope}.${name}' is read-only`);
-    if (e.kind === "owned") e.bag[n] = value;
-    else e.resolver.set(n, value);
+    if (!this.foreignWritable(e, n)) throw new Error(`'@${scope}.${name}' is read-only`);
+    e.resolver.set(n, value);
   }
-  writable(e, name) {
-    if (e.kind === "owned") return e.decls.get(name)?.writable ?? true;
+  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) {
+      if (e.kind === "owned") {
+        for (const row of e.bag.rows()) out.push({ scope: token, ...row });
+      } else {
+        for (const d of e.decls.values()) {
+          out.push({
+            scope: token,
+            ...rowFor(d, e.resolver.get(d.name.toLowerCase()), this.foreignWritable(e, d.name.toLowerCase()))
+          });
+        }
+      }
+    }
+    return out;
+  }
   /**
    * Build the `EvalContext` expr's `evaluate` consumes: owned scopes as static
    * bags, foreign scopes as their resolvers. `host` carries dialect-function
@@ -103,9 +228,31 @@ var ScopeRegistry = class {
   toEvalContext(host) {
     const scopes = {};
     for (const [token, e] of this.scopes) {
-      scopes[token] = e.kind === "owned" ? e.bag : e.resolver;
+      scopes[token] = e.kind === "owned" ? e.bag.values : e.resolver;
+    }
+    const qualities = this.qualityLadders();
+    return qualities.size === 0 ? { scopes, host } : {
+      scopes,
+      host,
+      qualities: (scope, name) => qualities.get(scope)?.get(name.toLowerCase())
+    };
+  }
+  /** Every quality declaration's ladder, keyed scope token then name. */
+  qualityLadders() {
+    const out = /* @__PURE__ */ new Map();
+    for (const [token, e] of this.scopes) {
+      const decls = e.kind === "owned" ? e.bag.declarations() : [...e.decls.values()];
+      for (const d of decls) {
+        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(d.name.toLowerCase(), d.stages);
+      }
     }
-    return { scopes, host };
+    return out;
   }
   /**
    * Build the `ExpressionSchema` expr's validator consumes. Scopes with no
@@ -115,25 +262,47 @@ var ScopeRegistry = class {
   toSchema() {
     const properties = /* @__PURE__ */ new Map();
     for (const [token, e] of this.scopes) {
-      if (e.decls.size === 0) continue;
+      const decls = e.kind === "owned" ? e.bag.declarations() : [...e.decls.values()];
+      if (decls.length === 0) continue;
       const m = /* @__PURE__ */ new Map();
-      for (const [name, d] of e.decls) m.set(name, { type: d.type, enumValues: d.values });
+      for (const d of decls) m.set(d.name.toLowerCase(), {
+        type: d.type,
+        enumValues: d.values,
+        ...d.stages !== void 0 ? { stages: d.stages } : {}
+      });
       properties.set(token, m);
     }
     return { properties };
   }
-  /** Serialize **owned** scopes only (foreign scopes are host-owned, host-saved). */
+  /** Serialize **owned** scopes only (foreign scopes are host-owned,
+   *  host-saved), as bare bags - the 0.1.x shape, kept stable so existing
+   *  consumers' save formats are untouched. A product embedding the
+   *  versioned cross-product shape uses `saveFragment`. */
   save() {
     const out = {};
-    for (const [token, e] of this.scopes) if (e.kind === "owned") out[token] = { ...e.bag };
+    for (const [token, e] of this.scopes) if (e.kind === "owned") out[token] = e.bag.save();
     return out;
   }
-  /** Restore owned-scope values from a `save` blob. Unknown/foreign scopes are ignored. */
+  /** Restore owned-scope values from a `save` blob. Unknown/foreign scopes
+   *  are ignored. */
   load(blob) {
     for (const [token, vals] of Object.entries(blob)) {
       const e = this.scopes.get(token);
-      if (e?.kind === "owned") Object.assign(e.bag, vals);
+      if (e?.kind === "owned") e.bag.load(vals);
+    }
+  }
+  /** The versioned owned-state fragment (the one serialisation shape both
+   *  product families' save envelopes embed when they adopt the kernel;
+   *  design/engine-runtimes.md 3.1). `save()` wrapped with a version stamp. */
+  saveFragment() {
+    return { version: SAVE_FRAGMENT_VERSION, scopes: this.save() };
+  }
+  /** Restore from a versioned fragment; an unsupported version throws. */
+  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);
   }
   assertFree(token) {
     if (this.scopes.has(token)) throw new Error(`scope '@${token}' is already registered`);
@@ -152,9 +321,14 @@ function defaultFor(d) {
       return d.values?.[0] ?? "";
     case "flags":
       return [];
+    // A quality starts at the first rung of its ladder.
+    case "quality":
+      return d.stages?.[0] ?? "";
   }
 }
 
+exports.PropertyBag = PropertyBag;
+exports.SAVE_FRAGMENT_VERSION = SAVE_FRAGMENT_VERSION;
 exports.SUPPORTED_SPEC_VERSIONS = SUPPORTED_SPEC_VERSIONS;
 exports.ScopeRegistry = ScopeRegistry;
 exports.readScopeRegistrySpec = readScopeRegistrySpec;

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["// ---------------------------------------------------------------------------\n// @wildwinter/scoperegistry - the scope registry / runtime state container that\n// sits on top of @wildwinter/expr.\n//\n// expr is a stateless calculator: given an AST, an EvalContext (the state), and\n// a Dialect, it computes. This package is the *state* layer: it owns the world\n// state as a set of named scopes - each either an **owned** scope (a property\n// bag this registry stores and saves) or a **foreign** scope (host- or\n// other-engine-resolved at runtime, never stored here) - and produces the\n// `EvalContext` (for evaluation) and `ExpressionSchema` (for validation) that\n// expr consumes. Plus the `scopeRegistrySpec` interop format for importing a\n// foreign owner's scope declarations.\n//\n// Design: design/scope-registry.md (in the patter repo). expr never depends on\n// this; this depends one-way on expr.\n// ---------------------------------------------------------------------------\n\nimport type {\n  EvalContext, ExpressionSchema, PropertyType, ScalarValue, ScopeResolver,\n} from \"@wildwinter/expr\";\n\nexport type { EvalContext, ExpressionSchema, PropertyType, ScalarValue, ScopeResolver } from \"@wildwinter/expr\";\n\n// ---------------------------------------------------------------------------\n// Declarations + the scopeRegistrySpec interop format\n// ---------------------------------------------------------------------------\n\n/**\n * A property declaration. `default` is used by an *owned* scope to seed its bag\n * (foreign scopes ignore it - the host owns the value). `writable: false` makes\n * a property read-only; default is read/write. (`type`/`values` feed validation.)\n */\nexport interface ScopeDeclaration {\n  name: string;\n  type: PropertyType;\n  values?: string[];        // for enum / flags\n  default?: ScalarValue;    // owned scopes: seed value\n  writable?: boolean;       // default true\n}\n\n/** One scope in a `scopeRegistrySpec`: a token + (optional) declarations. */\nexport interface ScopeSpec {\n  token: string;\n  /** Scope-level read/write default for its declarations (default true). */\n  writable?: boolean;\n  /** Property declarations; omit for an opaque scope (any name, unchecked). */\n  declarations?: ScopeDeclaration[];\n}\n\n/**\n * The interop format an owner (Storylet Studio, a host game) exports so another\n * engine can validate references into its scopes. Carried under the well-known\n * `scopeRegistrySpec` JSON key (inside a `.storyworld`, or a standalone file).\n */\nexport interface ScopeRegistrySpec {\n  version: number;\n  scopes: ScopeSpec[];\n}\n\n/** The spec versions this build understands. */\nexport const SUPPORTED_SPEC_VERSIONS = [1] as const;\n\n/**\n * Extract + validate a `scopeRegistrySpec` from any JSON value (a parsed\n * `.storyworld` bundle, or a vanilla `{ scopeRegistrySpec: ... }` manifest).\n * Returns null when the key is absent (so callers can probe arbitrary files);\n * throws on a malformed or unsupported-version spec.\n */\nexport function readScopeRegistrySpec(source: unknown): ScopeRegistrySpec | null {\n  if (!source || typeof source !== \"object\") return null;\n  const raw = (source as Record<string, unknown>).scopeRegistrySpec;\n  if (raw === undefined) return null;\n  if (typeof raw !== \"object\" || raw === null) throw new Error(\"scopeRegistrySpec must be an object\");\n  const spec = raw as Record<string, unknown>;\n  if (typeof spec.version !== \"number\") throw new Error(\"scopeRegistrySpec.version must be a number\");\n  if (!(SUPPORTED_SPEC_VERSIONS as readonly number[]).includes(spec.version)) {\n    throw new Error(`unsupported scopeRegistrySpec version ${spec.version} (supported: ${SUPPORTED_SPEC_VERSIONS.join(\", \")})`);\n  }\n  if (!Array.isArray(spec.scopes)) throw new Error(\"scopeRegistrySpec.scopes must be an array\");\n  for (const s of spec.scopes) {\n    if (!s || typeof s !== \"object\" || typeof (s as ScopeSpec).token !== \"string\") {\n      throw new Error(\"each scopeRegistrySpec scope needs a string token\");\n    }\n  }\n  return spec as unknown as ScopeRegistrySpec;\n}\n\n// ---------------------------------------------------------------------------\n// The registry / state container\n// ---------------------------------------------------------------------------\n\ninterface OwnedScope {\n  kind: \"owned\";\n  bag: Record<string, ScalarValue>;\n  decls: Map<string, ScopeDeclaration>;\n}\ninterface ForeignScope {\n  kind: \"foreign\";\n  resolver: ScopeResolver;\n  decls: Map<string, ScopeDeclaration>;\n  scopeWritable: boolean;\n}\ntype Entry = OwnedScope | ForeignScope;\n\nexport class ScopeRegistry {\n  private readonly scopes = new Map<string, Entry>();\n\n  /**\n   * Register a scope this registry **owns and stores**. Its bag is seeded from\n   * each declaration's `default` (or a type default). Owned scopes are\n   * type-checked (declarations) and serialized by `save`/`load`.\n   */\n  defineOwned(token: string, declarations: ScopeDeclaration[]): this {\n    this.assertFree(token);\n    const bag: Record<string, ScalarValue> = {};\n    const decls = new Map<string, ScopeDeclaration>();\n    for (const d of declarations) {\n      const name = d.name.toLowerCase();\n      decls.set(name, d);\n      bag[name] = d.default ?? defaultFor(d);\n    }\n    this.scopes.set(token, { kind: \"owned\", bag, decls });\n    return this;\n  }\n\n  /**\n   * Re-initialise an existing **owned** scope's bag from new declarations,\n   * clearing its current values. For scope-local state that resets on a context\n   * change (e.g. entering a new scene / site / deck) without disturbing other\n   * scopes. Mutates the bag in place, so an `EvalContext` already built from this\n   * registry stays valid.\n   */\n  reseedOwned(token: string, declarations: ScopeDeclaration[]): this {\n    const e = this.scopes.get(token);\n    if (!e || e.kind !== \"owned\") throw new Error(`'@${token}' is not an owned scope`);\n    for (const k of Object.keys(e.bag)) delete e.bag[k];\n    e.decls.clear();\n    for (const d of declarations) {\n      const name = d.name.toLowerCase();\n      e.decls.set(name, d);\n      e.bag[name] = d.default ?? defaultFor(d);\n    }\n    return this;\n  }\n\n  /**\n   * Register a **foreign** scope backed by a host `{ get, set? }` resolver. The\n   * values live in the host/other engine and are never stored or saved here.\n   * `declarations` (optional, e.g. imported from a `scopeRegistrySpec`) are used\n   * only for validation; omit them for an opaque scope.\n   */\n  defineForeign(\n    token: string,\n    resolver: ScopeResolver,\n    declarations: ScopeDeclaration[] = [],\n    scopeWritable = true,\n  ): this {\n    this.assertFree(token);\n    const decls = new Map<string, ScopeDeclaration>();\n    for (const d of declarations) decls.set(d.name.toLowerCase(), d);\n    this.scopes.set(token, { kind: \"foreign\", resolver, decls, scopeWritable });\n    return this;\n  }\n\n  has(token: string): boolean {\n    return this.scopes.has(token);\n  }\n\n  /** Read a property; undefined if the scope or property is not present. */\n  get(scope: string, name: string): ScalarValue | undefined {\n    const e = this.scopes.get(scope);\n    if (!e) return undefined;\n    const n = name.toLowerCase();\n    return e.kind === \"owned\" ? e.bag[n] : e.resolver.get(n);\n  }\n\n  /** Write a property. Throws on an unknown or read-only scope/property. */\n  set(scope: string, name: string, value: ScalarValue): void {\n    const e = this.scopes.get(scope);\n    if (!e) throw new Error(`unknown scope '@${scope}'`);\n    const n = name.toLowerCase();\n    if (!this.writable(e, n)) throw new Error(`'@${scope}.${name}' is read-only`);\n    if (e.kind === \"owned\") e.bag[n] = value;\n    else e.resolver.set!(n, value);\n  }\n\n  private writable(e: Entry, name: string): boolean {\n    if (e.kind === \"owned\") return e.decls.get(name)?.writable ?? true;\n    if (!e.resolver.set) return false;                 // no setter => read-only scope\n    return e.decls.get(name)?.writable ?? e.scopeWritable;\n  }\n\n  /**\n   * Build the `EvalContext` expr's `evaluate` consumes: owned scopes as static\n   * bags, foreign scopes as their resolvers. `host` carries dialect-function\n   * callbacks (PRNG, tag lookups) and is passed through untouched.\n   */\n  toEvalContext(host?: Record<string, unknown>): EvalContext {\n    const scopes: EvalContext[\"scopes\"] = {};\n    for (const [token, e] of this.scopes) {\n      scopes[token] = e.kind === \"owned\" ? e.bag : e.resolver;\n    }\n    return { scopes, host };\n  }\n\n  /**\n   * Build the `ExpressionSchema` expr's validator consumes. Scopes with no\n   * declarations are **omitted** (opaque - references into them are not flagged);\n   * declared scopes contribute their property types for validation.\n   */\n  toSchema(): ExpressionSchema {\n    const properties = new Map<string, Map<string, { type: PropertyType; enumValues?: string[] }>>();\n    for (const [token, e] of this.scopes) {\n      if (e.decls.size === 0) continue;\n      const m = new Map<string, { type: PropertyType; enumValues?: string[] }>();\n      for (const [name, d] of e.decls) m.set(name, { type: d.type, enumValues: d.values });\n      properties.set(token, m);\n    }\n    return { properties };\n  }\n\n  /** Serialize **owned** scopes only (foreign scopes are host-owned, host-saved). */\n  save(): Record<string, Record<string, ScalarValue>> {\n    const out: Record<string, Record<string, ScalarValue>> = {};\n    for (const [token, e] of this.scopes) if (e.kind === \"owned\") out[token] = { ...e.bag };\n    return out;\n  }\n\n  /** Restore owned-scope values from a `save` blob. Unknown/foreign scopes are ignored. */\n  load(blob: Record<string, Record<string, ScalarValue>>): void {\n    for (const [token, vals] of Object.entries(blob)) {\n      const e = this.scopes.get(token);\n      if (e?.kind === \"owned\") Object.assign(e.bag, vals);\n    }\n  }\n\n  private assertFree(token: string): void {\n    if (this.scopes.has(token)) throw new Error(`scope '@${token}' is already registered`);\n  }\n}\n\nfunction defaultFor(d: ScopeDeclaration): ScalarValue {\n  if (d.default !== undefined) return d.default;\n  switch (d.type) {\n    case \"boolean\": return false;\n    case \"number\": return 0;\n    case \"string\": return \"\";\n    case \"enum\": return d.values?.[0] ?? \"\";\n    case \"flags\": return [];\n  }\n}\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["// ---------------------------------------------------------------------------\n// @wildwinter/scoperegistry - the scope registry / runtime state container that\n// sits on top of @wildwinter/expr.\n//\n// expr is a stateless calculator: given an AST, an EvalContext (the state), and\n// a Dialect, it computes. This package is the *state* layer: it owns the world\n// state as a set of named scopes - each either an **owned** scope (a property\n// bag this registry stores and saves) or a **foreign** scope (host- or\n// other-engine-resolved at runtime, never stored here) - and produces the\n// `EvalContext` (for evaluation) and `ExpressionSchema` (for validation) that\n// expr consumes. Plus the `scopeRegistrySpec` interop format for importing a\n// foreign owner's scope declarations.\n//\n// Design: design/scope-registry.md (in the patter repo). expr never depends on\n// this; this depends one-way on expr.\n// ---------------------------------------------------------------------------\n\nimport type {\n  EvalContext, ExpressionSchema, PropertyType, ScalarValue, ScopeResolver,\n} from \"@wildwinter/expr\";\n\nexport type { EvalContext, ExpressionSchema, PropertyType, ScalarValue, ScopeResolver } from \"@wildwinter/expr\";\n\n// ---------------------------------------------------------------------------\n// Declarations + the scopeRegistrySpec interop format\n// ---------------------------------------------------------------------------\n\n/**\n * A property declaration. `default` is used by an *owned* scope to seed its bag\n * (foreign scopes ignore it - the host owns the value). `writable: false` makes\n * a property read-only; default is read/write. (`type`/`values` feed validation.)\n */\nexport interface ScopeDeclaration {\n  name: string;\n  type: PropertyType;\n  values?: string[];        // for enum / flags\n  /** A quality's ordered ladder of stage names (quality.md). */\n  stages?: string[];\n  default?: ScalarValue;    // owned scopes: seed value\n  writable?: boolean;       // default true\n}\n\n/** One scope in a `scopeRegistrySpec`: a token + (optional) declarations. */\nexport interface ScopeSpec {\n  token: string;\n  /** Scope-level read/write default for its declarations (default true). */\n  writable?: boolean;\n  /** Property declarations; omit for an opaque scope (any name, unchecked). */\n  declarations?: ScopeDeclaration[];\n}\n\n/**\n * The interop format an owner (Storylet Studio, a host game) exports so another\n * engine can validate references into its scopes. Carried under the well-known\n * `scopeRegistrySpec` JSON key (inside a `.storyworld`, or a standalone file).\n */\nexport interface ScopeRegistrySpec {\n  version: number;\n  scopes: ScopeSpec[];\n}\n\n/** The spec versions this build understands. */\nexport const SUPPORTED_SPEC_VERSIONS = [1] as const;\n\n/**\n * Extract + validate a `scopeRegistrySpec` from any JSON value (a parsed\n * `.storyworld` bundle, or a vanilla `{ scopeRegistrySpec: ... }` manifest).\n * Returns null when the key is absent (so callers can probe arbitrary files);\n * throws on a malformed or unsupported-version spec.\n */\nexport function readScopeRegistrySpec(source: unknown): ScopeRegistrySpec | null {\n  if (!source || typeof source !== \"object\") return null;\n  const raw = (source as Record<string, unknown>).scopeRegistrySpec;\n  if (raw === undefined) return null;\n  if (typeof raw !== \"object\" || raw === null) throw new Error(\"scopeRegistrySpec must be an object\");\n  const spec = raw as Record<string, unknown>;\n  if (typeof spec.version !== \"number\") throw new Error(\"scopeRegistrySpec.version must be a number\");\n  if (!(SUPPORTED_SPEC_VERSIONS as readonly number[]).includes(spec.version)) {\n    throw new Error(`unsupported scopeRegistrySpec version ${spec.version} (supported: ${SUPPORTED_SPEC_VERSIONS.join(\", \")})`);\n  }\n  if (!Array.isArray(spec.scopes)) throw new Error(\"scopeRegistrySpec.scopes must be an array\");\n  for (const s of spec.scopes) {\n    if (!s || typeof s !== \"object\" || typeof (s as ScopeSpec).token !== \"string\") {\n      throw new Error(\"each scopeRegistrySpec scope needs a string token\");\n    }\n  }\n  return spec as unknown as ScopeRegistrySpec;\n}\n\n// ---------------------------------------------------------------------------\n// PropertyBag - the state kernel's unit of state (added 0.2.0; design:\n// storylets-new/design/engine-runtimes.md 3.1). A typed, declared property\n// bag with defaults, the firing rule (engine writes notify subscribers;\n// host writes are silent but always auditable), examiner rows, one\n// sanctioned clone door, and bare-value save/load. Owned registry scopes\n// are bags; products may also hold bag families of their own (per-box,\n// per-scene) and mount the shared ones.\n// ---------------------------------------------------------------------------\n\n/** One property change. `silent` marks a host write (the firing rule: it\n *  reaches the audit hook but not subscribers); `reason` is the host's own\n *  note for its log. */\nexport interface BagChange {\n  name: string;\n  prev?: ScalarValue;\n  next: ScalarValue;\n  silent: boolean;\n  reason?: string;\n}\n\n/** One examiner row: what a property examiner/editor needs to render and\n *  edit a declared property. */\nexport interface PropertyRow {\n  name: string;\n  type: PropertyType;\n  value: ScalarValue | undefined;\n  default: ScalarValue;\n  values?: string[];\n  writable: boolean;\n}\n\nexport class PropertyBag {\n  /** The live values record (stable identity across reseed, so an\n   *  EvalContext built over it stays valid). Read-path for evaluation;\n   *  writes go through `set` so the firing rule applies. */\n  readonly values: Record<string, ScalarValue> = {};\n  private decls = new Map<string, ScopeDeclaration>();\n  private readonly subscribers = new Set<(change: BagChange) => void>();\n  private readonly auditors = new Set<(change: BagChange) => void>();\n  /** Name normalisation policy: lowercase by default (the registry's\n   *  long-standing contract); a product whose names are case-significant\n   *  passes identity. */\n  private readonly norm: (name: string) => string;\n\n  constructor(declarations: ScopeDeclaration[] = [], opts?: { normalise?: (name: string) => string }) {\n    this.norm = opts?.normalise ?? ((n) => n.toLowerCase());\n    this.seed(declarations);\n  }\n\n  private seed(declarations: ScopeDeclaration[]): void {\n    for (const d of declarations) {\n      const name = this.norm(d.name);\n      this.decls.set(name, d);\n      // Cloned so bags seeded from one declaration set never share a\n      // mutable default (flags arrays).\n      this.values[name] = structuredClone(d.default ?? defaultFor(d));\n    }\n  }\n\n  get(name: string): ScalarValue | undefined {\n    return this.values[this.norm(name)];\n  }\n\n  /** Write a property. Engine writes (the default) notify subscribers;\n   *  pass `silent: true` for a host write, which reaches only the audit\n   *  hook. Throws on a read-only property. Returns the change. */\n  set(name: string, value: ScalarValue, opts?: { silent?: boolean; reason?: string }): BagChange {\n    const n = this.norm(name);\n    if (this.decls.get(n)?.writable === false) throw new Error(`'${name}' is read-only`);\n    const change: BagChange = {\n      name: n,\n      prev: this.values[n],\n      next: value,\n      silent: opts?.silent ?? false,\n      reason: opts?.reason,\n    };\n    this.values[n] = value;\n    for (const audit of this.auditors) audit(change);\n    if (!change.silent) for (const fn of this.subscribers) fn(change);\n    return change;\n  }\n\n  /** Notified of engine (non-silent) writes. Returns the unsubscribe. */\n  subscribe(fn: (change: BagChange) => void): () => void {\n    this.subscribers.add(fn);\n    return () => this.subscribers.delete(fn);\n  }\n\n  /** Notified of EVERY write, silent or not. Returns the unsubscribe. */\n  onAudit(fn: (change: BagChange) => void): () => void {\n    this.auditors.add(fn);\n    return () => this.auditors.delete(fn);\n  }\n\n  /** Examiner rows: the declared surface only (stray values are storage,\n   *  not surface). */\n  rows(): PropertyRow[] {\n    return [...this.decls.entries()].map(([name, d]) => rowFor(d, this.get(name), undefined, name));\n  }\n\n  declarations(): ScopeDeclaration[] {\n    return [...this.decls.values()];\n  }\n\n  /** The one sanctioned copy door: values deep-copied, declarations\n   *  duplicated, the normalisation policy carried, subscriptions NOT\n   *  carried. */\n  clone(): PropertyBag {\n    const c = new PropertyBag([], { normalise: this.norm });\n    c.decls = new Map(this.decls);\n    Object.assign(c.values, structuredClone(this.values));\n    return c;\n  }\n\n  /** Clear and re-seed from new declarations, in place (the values record\n   *  keeps its identity, so contexts built over it stay valid). */\n  reseed(declarations: ScopeDeclaration[]): void {\n    for (const k of Object.keys(this.values)) delete this.values[k];\n    this.decls.clear();\n    this.seed(declarations);\n  }\n\n  /** Bare values, ready to embed in a product's save. */\n  save(): Record<string, ScalarValue> {\n    return structuredClone(this.values);\n  }\n\n  /** Lay saved values over the current ones (call after a fresh seed:\n   *  orphans land as strays, new declarations keep their defaults; the\n   *  product decides whether to prune). Does not fire events. */\n  load(values: Record<string, ScalarValue>): void {\n    for (const [k, v] of Object.entries(values)) this.values[this.norm(k)] = v;\n  }\n}\n\nfunction rowFor(d: ScopeDeclaration, value: ScalarValue | undefined, writable?: boolean, name?: string): PropertyRow {\n  return {\n    name: name ?? d.name.toLowerCase(),\n    type: d.type,\n    value,\n    default: d.default ?? defaultFor(d),\n    ...(d.values !== undefined ? { values: d.values } : {}),\n    writable: writable ?? d.writable ?? true,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// The registry / state container\n// ---------------------------------------------------------------------------\n\ninterface OwnedScope {\n  kind: \"owned\";\n  bag: PropertyBag;\n}\ninterface ForeignScope {\n  kind: \"foreign\";\n  resolver: ScopeResolver;\n  decls: Map<string, ScopeDeclaration>;\n  scopeWritable: boolean;\n}\ntype Entry = OwnedScope | ForeignScope;\n\n/** The versioned owned-state fragment both product save envelopes embed\n *  (design/engine-runtimes.md 3.1: one serialisation shape for bags). */\nexport interface OwnedStateFragment {\n  version: number;\n  scopes: Record<string, Record<string, ScalarValue>>;\n}\n\nexport const SAVE_FRAGMENT_VERSION = 1;\n\nexport class ScopeRegistry {\n  private readonly scopes = new Map<string, Entry>();\n\n  /**\n   * Register a scope this registry **owns and stores**. Its bag is seeded from\n   * each declaration's `default` (or a type default). Owned scopes are\n   * type-checked (declarations) and serialized by `save`/`load`.\n   */\n  defineOwned(token: string, declarations: ScopeDeclaration[]): this {\n    return this.mountOwned(token, new PropertyBag(declarations));\n  }\n\n  /**\n   * Attach an EXISTING bag as an owned scope - the shared-container move: a\n   * host (or the other product) holds the bag; this registry reads, writes\n   * and lists it like its own, but the holder saves it.\n   */\n  mountOwned(token: string, bag: PropertyBag): this {\n    this.assertFree(token);\n    this.scopes.set(token, { kind: \"owned\", bag });\n    return this;\n  }\n\n  /** An owned scope's bag (subscribe, audit, rows live there). */\n  ownedBag(token: string): PropertyBag {\n    const e = this.scopes.get(token);\n    if (!e || e.kind !== \"owned\") throw new Error(`'@${token}' is not an owned scope`);\n    return e.bag;\n  }\n\n  /**\n   * Re-initialise an existing **owned** scope's bag from new declarations,\n   * clearing its current values. For scope-local state that resets on a context\n   * change (e.g. entering a new scene / site / deck) without disturbing other\n   * scopes. Mutates the bag in place, so an `EvalContext` already built from this\n   * registry stays valid.\n   */\n  reseedOwned(token: string, declarations: ScopeDeclaration[]): this {\n    this.ownedBag(token).reseed(declarations);\n    return this;\n  }\n\n  /**\n   * Register a **foreign** scope backed by a host `{ get, set? }` resolver. The\n   * values live in the host/other engine and are never stored or saved here.\n   * `declarations` (optional, e.g. imported from a `scopeRegistrySpec`) are used\n   * only for validation; omit them for an opaque scope.\n   */\n  defineForeign(\n    token: string,\n    resolver: ScopeResolver,\n    declarations: ScopeDeclaration[] = [],\n    scopeWritable = true,\n  ): this {\n    this.assertFree(token);\n    const decls = new Map<string, ScopeDeclaration>();\n    for (const d of declarations) decls.set(d.name.toLowerCase(), d);\n    this.scopes.set(token, { kind: \"foreign\", resolver, decls, scopeWritable });\n    return this;\n  }\n\n  has(token: string): boolean {\n    return this.scopes.has(token);\n  }\n\n  /** Read a property; undefined if the scope or property is not present. */\n  get(scope: string, name: string): ScalarValue | undefined {\n    const e = this.scopes.get(scope);\n    if (!e) return undefined;\n    return e.kind === \"owned\" ? e.bag.get(name) : e.resolver.get(name.toLowerCase());\n  }\n\n  /** Write a property (an ENGINE write: the bag's subscribers fire; use\n   *  the bag directly for silent host writes). Throws on an unknown or\n   *  read-only scope/property. */\n  set(scope: string, name: string, value: ScalarValue): void {\n    const e = this.scopes.get(scope);\n    if (!e) throw new Error(`unknown scope '@${scope}'`);\n    if (e.kind === \"owned\") {\n      try {\n        e.bag.set(name, value);\n      } catch {\n        throw new Error(`'@${scope}.${name}' is read-only`);\n      }\n      return;\n    }\n    const n = name.toLowerCase();\n    if (!this.foreignWritable(e, n)) throw new Error(`'@${scope}.${name}' is read-only`);\n    e.resolver.set!(n, value);\n  }\n\n  private foreignWritable(e: ForeignScope, name: string): boolean {\n    if (!e.resolver.set) return false;                 // no setter => read-only scope\n    return e.decls.get(name)?.writable ?? e.scopeWritable;\n  }\n\n  /** Examiner rows across every scope with a declared surface: owned bags\n   *  first, then declared foreign scopes (values read through, writability\n   *  reflecting the resolver). Opaque foreign scopes are not listed. */\n  listProperties(): ({ scope: string } & PropertyRow)[] {\n    const out: ({ scope: string } & PropertyRow)[] = [];\n    for (const [token, e] of this.scopes) {\n      if (e.kind === \"owned\") {\n        for (const row of e.bag.rows()) out.push({ scope: token, ...row });\n      } else {\n        for (const d of e.decls.values()) {\n          out.push({\n            scope: token,\n            ...rowFor(d, e.resolver.get(d.name.toLowerCase()), this.foreignWritable(e, d.name.toLowerCase())),\n          });\n        }\n      }\n    }\n    return out;\n  }\n\n  /**\n   * Build the `EvalContext` expr's `evaluate` consumes: owned scopes as static\n   * bags, foreign scopes as their resolvers. `host` carries dialect-function\n   * callbacks (PRNG, tag lookups) and is passed through untouched.\n   */\n  toEvalContext(host?: Record<string, unknown>): EvalContext {\n    const scopes: EvalContext[\"scopes\"] = {};\n    for (const [token, e] of this.scopes) {\n      scopes[token] = e.kind === \"owned\" ? e.bag.values : e.resolver;\n    }\n    // The quality channel (quality.md): declared here once, so a host that\n    // registers a quality gets ordering comparisons and advance() with no\n    // further wiring. Only added when a quality exists, so contexts stay\n    // byte-identical for products that declare none.\n    const qualities = this.qualityLadders();\n    return qualities.size === 0 ? { scopes, host } : {\n      scopes, host,\n      qualities: (scope, name) => qualities.get(scope)?.get(name.toLowerCase()),\n    };\n  }\n\n  /** Every quality declaration's ladder, keyed scope token then name. */\n  private qualityLadders(): Map<string, Map<string, readonly string[]>> {\n    const out = new Map<string, Map<string, readonly string[]>>();\n    for (const [token, e] of this.scopes) {\n      const decls = e.kind === \"owned\" ? e.bag.declarations() : [...e.decls.values()];\n      for (const d of decls) {\n        if (d.type !== \"quality\" || d.stages === undefined) continue;\n        let m = out.get(token);\n        if (!m) { m = new Map(); out.set(token, m); }\n        m.set(d.name.toLowerCase(), d.stages);\n      }\n    }\n    return out;\n  }\n\n  /**\n   * Build the `ExpressionSchema` expr's validator consumes. Scopes with no\n   * declarations are **omitted** (opaque - references into them are not flagged);\n   * declared scopes contribute their property types for validation.\n   */\n  toSchema(): ExpressionSchema {\n    const properties = new Map<string, Map<string, { type: PropertyType; enumValues?: string[]; stages?: string[] }>>();\n    for (const [token, e] of this.scopes) {\n      const decls = e.kind === \"owned\" ? e.bag.declarations() : [...e.decls.values()];\n      if (decls.length === 0) continue;\n      const m = new Map<string, { type: PropertyType; enumValues?: string[]; stages?: string[] }>();\n      for (const d of decls) m.set(d.name.toLowerCase(), {\n        type: d.type, enumValues: d.values,\n        ...(d.stages !== undefined ? { stages: d.stages } : {}),\n      });\n      properties.set(token, m);\n    }\n    return { properties };\n  }\n\n  /** Serialize **owned** scopes only (foreign scopes are host-owned,\n   *  host-saved), as bare bags - the 0.1.x shape, kept stable so existing\n   *  consumers' save formats are untouched. A product embedding the\n   *  versioned cross-product shape uses `saveFragment`. */\n  save(): Record<string, Record<string, ScalarValue>> {\n    const out: Record<string, Record<string, ScalarValue>> = {};\n    for (const [token, e] of this.scopes) if (e.kind === \"owned\") out[token] = e.bag.save();\n    return out;\n  }\n\n  /** Restore owned-scope values from a `save` blob. Unknown/foreign scopes\n   *  are ignored. */\n  load(blob: Record<string, Record<string, ScalarValue>>): void {\n    for (const [token, vals] of Object.entries(blob)) {\n      const e = this.scopes.get(token);\n      if (e?.kind === \"owned\") e.bag.load(vals);\n    }\n  }\n\n  /** The versioned owned-state fragment (the one serialisation shape both\n   *  product families' save envelopes embed when they adopt the kernel;\n   *  design/engine-runtimes.md 3.1). `save()` wrapped with a version stamp. */\n  saveFragment(): OwnedStateFragment {\n    return { version: SAVE_FRAGMENT_VERSION, scopes: this.save() };\n  }\n\n  /** Restore from a versioned fragment; an unsupported version throws. */\n  loadFragment(fragment: OwnedStateFragment): void {\n    if (fragment.version !== SAVE_FRAGMENT_VERSION) {\n      throw new Error(`unsupported owned-state fragment version ${fragment.version} (supported: ${SAVE_FRAGMENT_VERSION})`);\n    }\n    this.load(fragment.scopes);\n  }\n\n  private assertFree(token: string): void {\n    if (this.scopes.has(token)) throw new Error(`scope '@${token}' is already registered`);\n  }\n}\n\nfunction defaultFor(d: ScopeDeclaration): ScalarValue {\n  if (d.default !== undefined) return d.default;\n  switch (d.type) {\n    case \"boolean\": return false;\n    case \"number\": return 0;\n    case \"string\": return \"\";\n    case \"enum\": return d.values?.[0] ?? \"\";\n    case \"flags\": return [];\n    // A quality starts at the first rung of its ladder.\n    case \"quality\": return d.stages?.[0] ?? \"\";\n  }\n}\n"]}

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { PropertyType, ScalarValue, ScopeResolver, EvalContext, ExpressionSchema } from '@wildwinter/expr';
+import { ScalarValue, PropertyType, ScopeResolver, EvalContext, ExpressionSchema } from '@wildwinter/expr';
 export { EvalContext, ExpressionSchema, PropertyType, ScalarValue, ScopeResolver } from '@wildwinter/expr';
 
 /**
@@ -10,6 +10,8 @@ interface ScopeDeclaration {
     name: string;
     type: PropertyType;
     values?: string[];
+    /** A quality's ordered ladder of stage names (quality.md). */
+    stages?: string[];
     default?: ScalarValue;
     writable?: boolean;
 }
@@ -39,6 +41,79 @@ declare const SUPPORTED_SPEC_VERSIONS: readonly [1];
  * throws on a malformed or unsupported-version spec.
  */
 declare function readScopeRegistrySpec(source: unknown): ScopeRegistrySpec | null;
+/** One property change. `silent` marks a host write (the firing rule: it
+ *  reaches the audit hook but not subscribers); `reason` is the host's own
+ *  note for its log. */
+interface BagChange {
+    name: string;
+    prev?: ScalarValue;
+    next: ScalarValue;
+    silent: boolean;
+    reason?: string;
+}
+/** One examiner row: what a property examiner/editor needs to render and
+ *  edit a declared property. */
+interface PropertyRow {
+    name: string;
+    type: PropertyType;
+    value: ScalarValue | undefined;
+    default: ScalarValue;
+    values?: string[];
+    writable: boolean;
+}
+declare 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. */
+    readonly values: Record<string, ScalarValue>;
+    private decls;
+    private readonly subscribers;
+    private readonly auditors;
+    /** Name normalisation policy: lowercase by default (the registry's
+     *  long-standing contract); a product whose names are case-significant
+     *  passes identity. */
+    private readonly norm;
+    constructor(declarations?: ScopeDeclaration[], opts?: {
+        normalise?: (name: string) => string;
+    });
+    private seed;
+    get(name: string): ScalarValue | undefined;
+    /** 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: string, value: ScalarValue, opts?: {
+        silent?: boolean;
+        reason?: string;
+    }): BagChange;
+    /** Notified of engine (non-silent) writes. Returns the unsubscribe. */
+    subscribe(fn: (change: BagChange) => void): () => void;
+    /** Notified of EVERY write, silent or not. Returns the unsubscribe. */
+    onAudit(fn: (change: BagChange) => void): () => void;
+    /** Examiner rows: the declared surface only (stray values are storage,
+     *  not surface). */
+    rows(): PropertyRow[];
+    declarations(): ScopeDeclaration[];
+    /** The one sanctioned copy door: values deep-copied, declarations
+     *  duplicated, the normalisation policy carried, subscriptions NOT
+     *  carried. */
+    clone(): PropertyBag;
+    /** Clear and re-seed from new declarations, in place (the values record
+     *  keeps its identity, so contexts built over it stay valid). */
+    reseed(declarations: ScopeDeclaration[]): void;
+    /** Bare values, ready to embed in a product's save. */
+    save(): Record<string, ScalarValue>;
+    /** 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: Record<string, ScalarValue>): void;
+}
+/** The versioned owned-state fragment both product save envelopes embed
+ *  (design/engine-runtimes.md 3.1: one serialisation shape for bags). */
+interface OwnedStateFragment {
+    version: number;
+    scopes: Record<string, Record<string, ScalarValue>>;
+}
+declare const SAVE_FRAGMENT_VERSION = 1;
 declare class ScopeRegistry {
     private readonly scopes;
     /**
@@ -47,6 +122,14 @@ declare class ScopeRegistry {
      * type-checked (declarations) and serialized by `save`/`load`.
      */
     defineOwned(token: string, declarations: ScopeDeclaration[]): this;
+    /**
+     * Attach an EXISTING bag as an owned scope - the shared-container move: a
+     * host (or the other product) holds the bag; this registry reads, writes
+     * and lists it like its own, but the holder saves it.
+     */
+    mountOwned(token: string, bag: PropertyBag): this;
+    /** An owned scope's bag (subscribe, audit, rows live there). */
+    ownedBag(token: string): PropertyBag;
     /**
      * Re-initialise an existing **owned** scope's bag from new declarations,
      * clearing its current values. For scope-local state that resets on a context
@@ -65,26 +148,46 @@ declare class ScopeRegistry {
     has(token: string): boolean;
     /** Read a property; undefined if the scope or property is not present. */
     get(scope: string, name: string): ScalarValue | undefined;
-    /** Write a property. Throws on an unknown or read-only scope/property. */
+    /** Write a property (an ENGINE write: the bag's subscribers fire; use
+     *  the bag directly for silent host writes). Throws on an unknown or
+     *  read-only scope/property. */
     set(scope: string, name: string, value: ScalarValue): void;
-    private writable;
+    private foreignWritable;
+    /** 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(): ({
+        scope: string;
+    } & PropertyRow)[];
     /**
      * 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(host?: Record<string, unknown>): EvalContext;
+    /** Every quality declaration's ladder, keyed scope token then name. */
+    private qualityLadders;
     /**
      * 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.
      */
     toSchema(): ExpressionSchema;
-    /** Serialize **owned** scopes only (foreign scopes are host-owned, host-saved). */
+    /** Serialize **owned** scopes only (foreign scopes are host-owned,
+     *  host-saved), as bare bags - the 0.1.x shape, kept stable so existing
+     *  consumers' save formats are untouched. A product embedding the
+     *  versioned cross-product shape uses `saveFragment`. */
     save(): Record<string, Record<string, ScalarValue>>;
-    /** Restore owned-scope values from a `save` blob. Unknown/foreign scopes are ignored. */
+    /** Restore owned-scope values from a `save` blob. Unknown/foreign scopes
+     *  are ignored. */
     load(blob: Record<string, Record<string, ScalarValue>>): void;
+    /** The versioned owned-state fragment (the one serialisation shape both
+     *  product families' save envelopes embed when they adopt the kernel;
+     *  design/engine-runtimes.md 3.1). `save()` wrapped with a version stamp. */
+    saveFragment(): OwnedStateFragment;
+    /** Restore from a versioned fragment; an unsupported version throws. */
+    loadFragment(fragment: OwnedStateFragment): void;
     private assertFree;
 }
 
-export { SUPPORTED_SPEC_VERSIONS, type ScopeDeclaration, ScopeRegistry, type ScopeRegistrySpec, type ScopeSpec, readScopeRegistrySpec };
+export { type BagChange, type OwnedStateFragment, PropertyBag, type PropertyRow, SAVE_FRAGMENT_VERSION, SUPPORTED_SPEC_VERSIONS, type ScopeDeclaration, ScopeRegistry, type ScopeRegistrySpec, type ScopeSpec, readScopeRegistrySpec };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { PropertyType, ScalarValue, ScopeResolver, EvalContext, ExpressionSchema } from '@wildwinter/expr';
+import { ScalarValue, PropertyType, ScopeResolver, EvalContext, ExpressionSchema } from '@wildwinter/expr';
 export { EvalContext, ExpressionSchema, PropertyType, ScalarValue, ScopeResolver } from '@wildwinter/expr';
 
 /**
@@ -10,6 +10,8 @@ interface ScopeDeclaration {
     name: string;
     type: PropertyType;
     values?: string[];
+    /** A quality's ordered ladder of stage names (quality.md). */
+    stages?: string[];
     default?: ScalarValue;
     writable?: boolean;
 }
@@ -39,6 +41,79 @@ declare const SUPPORTED_SPEC_VERSIONS: readonly [1];
  * throws on a malformed or unsupported-version spec.
  */
 declare function readScopeRegistrySpec(source: unknown): ScopeRegistrySpec | null;
+/** One property change. `silent` marks a host write (the firing rule: it
+ *  reaches the audit hook but not subscribers); `reason` is the host's own
+ *  note for its log. */
+interface BagChange {
+    name: string;
+    prev?: ScalarValue;
+    next: ScalarValue;
+    silent: boolean;
+    reason?: string;
+}
+/** One examiner row: what a property examiner/editor needs to render and
+ *  edit a declared property. */
+interface PropertyRow {
+    name: string;
+    type: PropertyType;
+    value: ScalarValue | undefined;
+    default: ScalarValue;
+    values?: string[];
+    writable: boolean;
+}
+declare 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. */
+    readonly values: Record<string, ScalarValue>;
+    private decls;
+    private readonly subscribers;
+    private readonly auditors;
+    /** Name normalisation policy: lowercase by default (the registry's
+     *  long-standing contract); a product whose names are case-significant
+     *  passes identity. */
+    private readonly norm;
+    constructor(declarations?: ScopeDeclaration[], opts?: {
+        normalise?: (name: string) => string;
+    });
+    private seed;
+    get(name: string): ScalarValue | undefined;
+    /** 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: string, value: ScalarValue, opts?: {
+        silent?: boolean;
+        reason?: string;
+    }): BagChange;
+    /** Notified of engine (non-silent) writes. Returns the unsubscribe. */
+    subscribe(fn: (change: BagChange) => void): () => void;
+    /** Notified of EVERY write, silent or not. Returns the unsubscribe. */
+    onAudit(fn: (change: BagChange) => void): () => void;
+    /** Examiner rows: the declared surface only (stray values are storage,
+     *  not surface). */
+    rows(): PropertyRow[];
+    declarations(): ScopeDeclaration[];
+    /** The one sanctioned copy door: values deep-copied, declarations
+     *  duplicated, the normalisation policy carried, subscriptions NOT
+     *  carried. */
+    clone(): PropertyBag;
+    /** Clear and re-seed from new declarations, in place (the values record
+     *  keeps its identity, so contexts built over it stay valid). */
+    reseed(declarations: ScopeDeclaration[]): void;
+    /** Bare values, ready to embed in a product's save. */
+    save(): Record<string, ScalarValue>;
+    /** 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: Record<string, ScalarValue>): void;
+}
+/** The versioned owned-state fragment both product save envelopes embed
+ *  (design/engine-runtimes.md 3.1: one serialisation shape for bags). */
+interface OwnedStateFragment {
+    version: number;
+    scopes: Record<string, Record<string, ScalarValue>>;
+}
+declare const SAVE_FRAGMENT_VERSION = 1;
 declare class ScopeRegistry {
     private readonly scopes;
     /**
@@ -47,6 +122,14 @@ declare class ScopeRegistry {
      * type-checked (declarations) and serialized by `save`/`load`.
      */
     defineOwned(token: string, declarations: ScopeDeclaration[]): this;
+    /**
+     * Attach an EXISTING bag as an owned scope - the shared-container move: a
+     * host (or the other product) holds the bag; this registry reads, writes
+     * and lists it like its own, but the holder saves it.
+     */
+    mountOwned(token: string, bag: PropertyBag): this;
+    /** An owned scope's bag (subscribe, audit, rows live there). */
+    ownedBag(token: string): PropertyBag;
     /**
      * Re-initialise an existing **owned** scope's bag from new declarations,
      * clearing its current values. For scope-local state that resets on a context
@@ -65,26 +148,46 @@ declare class ScopeRegistry {
     has(token: string): boolean;
     /** Read a property; undefined if the scope or property is not present. */
     get(scope: string, name: string): ScalarValue | undefined;
-    /** Write a property. Throws on an unknown or read-only scope/property. */
+    /** Write a property (an ENGINE write: the bag's subscribers fire; use
+     *  the bag directly for silent host writes). Throws on an unknown or
+     *  read-only scope/property. */
     set(scope: string, name: string, value: ScalarValue): void;
-    private writable;
+    private foreignWritable;
+    /** 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(): ({
+        scope: string;
+    } & PropertyRow)[];
     /**
      * 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(host?: Record<string, unknown>): EvalContext;
+    /** Every quality declaration's ladder, keyed scope token then name. */
+    private qualityLadders;
     /**
      * 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.
      */
     toSchema(): ExpressionSchema;
-    /** Serialize **owned** scopes only (foreign scopes are host-owned, host-saved). */
+    /** Serialize **owned** scopes only (foreign scopes are host-owned,
+     *  host-saved), as bare bags - the 0.1.x shape, kept stable so existing
+     *  consumers' save formats are untouched. A product embedding the
+     *  versioned cross-product shape uses `saveFragment`. */
     save(): Record<string, Record<string, ScalarValue>>;
-    /** Restore owned-scope values from a `save` blob. Unknown/foreign scopes are ignored. */
+    /** Restore owned-scope values from a `save` blob. Unknown/foreign scopes
+     *  are ignored. */
     load(blob: Record<string, Record<string, ScalarValue>>): void;
+    /** The versioned owned-state fragment (the one serialisation shape both
+     *  product families' save envelopes embed when they adopt the kernel;
+     *  design/engine-runtimes.md 3.1). `save()` wrapped with a version stamp. */
+    saveFragment(): OwnedStateFragment;
+    /** Restore from a versioned fragment; an unsupported version throws. */
+    loadFragment(fragment: OwnedStateFragment): void;
     private assertFree;
 }
 
-export { SUPPORTED_SPEC_VERSIONS, type ScopeDeclaration, ScopeRegistry, type ScopeRegistrySpec, type ScopeSpec, readScopeRegistrySpec };
+export { type BagChange, type OwnedStateFragment, PropertyBag, type PropertyRow, SAVE_FRAGMENT_VERSION, SUPPORTED_SPEC_VERSIONS, type ScopeDeclaration, ScopeRegistry, type ScopeRegistrySpec, type ScopeSpec, readScopeRegistrySpec };

package/dist/index.js

@@ -18,6 +18,106 @@ function readScopeRegistrySpec(source) {
   }
   return spec;
 }
+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
+  };
+}
+var SAVE_FRAGMENT_VERSION = 1;
 var ScopeRegistry = class {
   scopes = /* @__PURE__ */ new Map();
   /**
@@ -26,17 +126,24 @@ var ScopeRegistry = class {
    * type-checked (declarations) and serialized by `save`/`load`.
    */
   defineOwned(token, declarations) {
+    return this.mountOwned(token, new PropertyBag(declarations));
+  }
+  /**
+   * Attach an EXISTING bag as an owned scope - the shared-container move: a
+   * host (or the other product) holds the bag; this registry reads, writes
+   * and lists it like its own, but the holder saves it.
+   */
+  mountOwned(token, bag) {
     this.assertFree(token);
-    const bag = {};
-    const decls = /* @__PURE__ */ new Map();
-    for (const d of declarations) {
-      const name = d.name.toLowerCase();
-      decls.set(name, d);
-      bag[name] = d.default ?? defaultFor(d);
-    }
-    this.scopes.set(token, { kind: "owned", bag, decls });
+    this.scopes.set(token, { kind: "owned", bag });
     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
@@ -45,15 +152,7 @@ var ScopeRegistry = class {
    * registry stays valid.
    */
   reseedOwned(token, declarations) {
-    const e = this.scopes.get(token);
-    if (!e || e.kind !== "owned") throw new Error(`'@${token}' is not an owned scope`);
-    for (const k of Object.keys(e.bag)) delete e.bag[k];
-    e.decls.clear();
-    for (const d of declarations) {
-      const name = d.name.toLowerCase();
-      e.decls.set(name, d);
-      e.bag[name] = d.default ?? defaultFor(d);
-    }
+    this.ownedBag(token).reseed(declarations);
     return this;
   }
   /**
@@ -76,23 +175,49 @@ var ScopeRegistry = class {
   get(scope, name) {
     const e = this.scopes.get(scope);
     if (!e) return void 0;
-    const n = name.toLowerCase();
-    return e.kind === "owned" ? e.bag[n] : e.resolver.get(n);
+    return e.kind === "owned" ? e.bag.get(name) : e.resolver.get(name.toLowerCase());
   }
-  /** Write a property. Throws on an unknown or read-only scope/property. */
+  /** Write a property (an ENGINE write: the bag's subscribers fire; use
+   *  the bag directly for silent host writes). Throws on an unknown or
+   *  read-only scope/property. */
   set(scope, name, value) {
     const e = this.scopes.get(scope);
     if (!e) throw new Error(`unknown scope '@${scope}'`);
+    if (e.kind === "owned") {
+      try {
+        e.bag.set(name, value);
+      } catch {
+        throw new Error(`'@${scope}.${name}' is read-only`);
+      }
+      return;
+    }
     const n = name.toLowerCase();
-    if (!this.writable(e, n)) throw new Error(`'@${scope}.${name}' is read-only`);
-    if (e.kind === "owned") e.bag[n] = value;
-    else e.resolver.set(n, value);
+    if (!this.foreignWritable(e, n)) throw new Error(`'@${scope}.${name}' is read-only`);
+    e.resolver.set(n, value);
   }
-  writable(e, name) {
-    if (e.kind === "owned") return e.decls.get(name)?.writable ?? true;
+  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) {
+      if (e.kind === "owned") {
+        for (const row of e.bag.rows()) out.push({ scope: token, ...row });
+      } else {
+        for (const d of e.decls.values()) {
+          out.push({
+            scope: token,
+            ...rowFor(d, e.resolver.get(d.name.toLowerCase()), this.foreignWritable(e, d.name.toLowerCase()))
+          });
+        }
+      }
+    }
+    return out;
+  }
   /**
    * Build the `EvalContext` expr's `evaluate` consumes: owned scopes as static
    * bags, foreign scopes as their resolvers. `host` carries dialect-function
@@ -101,9 +226,31 @@ var ScopeRegistry = class {
   toEvalContext(host) {
     const scopes = {};
     for (const [token, e] of this.scopes) {
-      scopes[token] = e.kind === "owned" ? e.bag : e.resolver;
+      scopes[token] = e.kind === "owned" ? e.bag.values : e.resolver;
+    }
+    const qualities = this.qualityLadders();
+    return qualities.size === 0 ? { scopes, host } : {
+      scopes,
+      host,
+      qualities: (scope, name) => qualities.get(scope)?.get(name.toLowerCase())
+    };
+  }
+  /** Every quality declaration's ladder, keyed scope token then name. */
+  qualityLadders() {
+    const out = /* @__PURE__ */ new Map();
+    for (const [token, e] of this.scopes) {
+      const decls = e.kind === "owned" ? e.bag.declarations() : [...e.decls.values()];
+      for (const d of decls) {
+        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(d.name.toLowerCase(), d.stages);
+      }
     }
-    return { scopes, host };
+    return out;
   }
   /**
    * Build the `ExpressionSchema` expr's validator consumes. Scopes with no
@@ -113,25 +260,47 @@ var ScopeRegistry = class {
   toSchema() {
     const properties = /* @__PURE__ */ new Map();
     for (const [token, e] of this.scopes) {
-      if (e.decls.size === 0) continue;
+      const decls = e.kind === "owned" ? e.bag.declarations() : [...e.decls.values()];
+      if (decls.length === 0) continue;
       const m = /* @__PURE__ */ new Map();
-      for (const [name, d] of e.decls) m.set(name, { type: d.type, enumValues: d.values });
+      for (const d of decls) m.set(d.name.toLowerCase(), {
+        type: d.type,
+        enumValues: d.values,
+        ...d.stages !== void 0 ? { stages: d.stages } : {}
+      });
       properties.set(token, m);
     }
     return { properties };
   }
-  /** Serialize **owned** scopes only (foreign scopes are host-owned, host-saved). */
+  /** Serialize **owned** scopes only (foreign scopes are host-owned,
+   *  host-saved), as bare bags - the 0.1.x shape, kept stable so existing
+   *  consumers' save formats are untouched. A product embedding the
+   *  versioned cross-product shape uses `saveFragment`. */
   save() {
     const out = {};
-    for (const [token, e] of this.scopes) if (e.kind === "owned") out[token] = { ...e.bag };
+    for (const [token, e] of this.scopes) if (e.kind === "owned") out[token] = e.bag.save();
     return out;
   }
-  /** Restore owned-scope values from a `save` blob. Unknown/foreign scopes are ignored. */
+  /** Restore owned-scope values from a `save` blob. Unknown/foreign scopes
+   *  are ignored. */
   load(blob) {
     for (const [token, vals] of Object.entries(blob)) {
       const e = this.scopes.get(token);
-      if (e?.kind === "owned") Object.assign(e.bag, vals);
+      if (e?.kind === "owned") e.bag.load(vals);
+    }
+  }
+  /** The versioned owned-state fragment (the one serialisation shape both
+   *  product families' save envelopes embed when they adopt the kernel;
+   *  design/engine-runtimes.md 3.1). `save()` wrapped with a version stamp. */
+  saveFragment() {
+    return { version: SAVE_FRAGMENT_VERSION, scopes: this.save() };
+  }
+  /** Restore from a versioned fragment; an unsupported version throws. */
+  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);
   }
   assertFree(token) {
     if (this.scopes.has(token)) throw new Error(`scope '@${token}' is already registered`);
@@ -150,9 +319,12 @@ function defaultFor(d) {
       return d.values?.[0] ?? "";
     case "flags":
       return [];
+    // A quality starts at the first rung of its ladder.
+    case "quality":
+      return d.stages?.[0] ?? "";
   }
 }
 
-export { SUPPORTED_SPEC_VERSIONS, ScopeRegistry, readScopeRegistrySpec };
+export { PropertyBag, SAVE_FRAGMENT_VERSION, SUPPORTED_SPEC_VERSIONS, ScopeRegistry, readScopeRegistrySpec };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["// ---------------------------------------------------------------------------\n// @wildwinter/scoperegistry - the scope registry / runtime state container that\n// sits on top of @wildwinter/expr.\n//\n// expr is a stateless calculator: given an AST, an EvalContext (the state), and\n// a Dialect, it computes. This package is the *state* layer: it owns the world\n// state as a set of named scopes - each either an **owned** scope (a property\n// bag this registry stores and saves) or a **foreign** scope (host- or\n// other-engine-resolved at runtime, never stored here) - and produces the\n// `EvalContext` (for evaluation) and `ExpressionSchema` (for validation) that\n// expr consumes. Plus the `scopeRegistrySpec` interop format for importing a\n// foreign owner's scope declarations.\n//\n// Design: design/scope-registry.md (in the patter repo). expr never depends on\n// this; this depends one-way on expr.\n// ---------------------------------------------------------------------------\n\nimport type {\n  EvalContext, ExpressionSchema, PropertyType, ScalarValue, ScopeResolver,\n} from \"@wildwinter/expr\";\n\nexport type { EvalContext, ExpressionSchema, PropertyType, ScalarValue, ScopeResolver } from \"@wildwinter/expr\";\n\n// ---------------------------------------------------------------------------\n// Declarations + the scopeRegistrySpec interop format\n// ---------------------------------------------------------------------------\n\n/**\n * A property declaration. `default` is used by an *owned* scope to seed its bag\n * (foreign scopes ignore it - the host owns the value). `writable: false` makes\n * a property read-only; default is read/write. (`type`/`values` feed validation.)\n */\nexport interface ScopeDeclaration {\n  name: string;\n  type: PropertyType;\n  values?: string[];        // for enum / flags\n  default?: ScalarValue;    // owned scopes: seed value\n  writable?: boolean;       // default true\n}\n\n/** One scope in a `scopeRegistrySpec`: a token + (optional) declarations. */\nexport interface ScopeSpec {\n  token: string;\n  /** Scope-level read/write default for its declarations (default true). */\n  writable?: boolean;\n  /** Property declarations; omit for an opaque scope (any name, unchecked). */\n  declarations?: ScopeDeclaration[];\n}\n\n/**\n * The interop format an owner (Storylet Studio, a host game) exports so another\n * engine can validate references into its scopes. Carried under the well-known\n * `scopeRegistrySpec` JSON key (inside a `.storyworld`, or a standalone file).\n */\nexport interface ScopeRegistrySpec {\n  version: number;\n  scopes: ScopeSpec[];\n}\n\n/** The spec versions this build understands. */\nexport const SUPPORTED_SPEC_VERSIONS = [1] as const;\n\n/**\n * Extract + validate a `scopeRegistrySpec` from any JSON value (a parsed\n * `.storyworld` bundle, or a vanilla `{ scopeRegistrySpec: ... }` manifest).\n * Returns null when the key is absent (so callers can probe arbitrary files);\n * throws on a malformed or unsupported-version spec.\n */\nexport function readScopeRegistrySpec(source: unknown): ScopeRegistrySpec | null {\n  if (!source || typeof source !== \"object\") return null;\n  const raw = (source as Record<string, unknown>).scopeRegistrySpec;\n  if (raw === undefined) return null;\n  if (typeof raw !== \"object\" || raw === null) throw new Error(\"scopeRegistrySpec must be an object\");\n  const spec = raw as Record<string, unknown>;\n  if (typeof spec.version !== \"number\") throw new Error(\"scopeRegistrySpec.version must be a number\");\n  if (!(SUPPORTED_SPEC_VERSIONS as readonly number[]).includes(spec.version)) {\n    throw new Error(`unsupported scopeRegistrySpec version ${spec.version} (supported: ${SUPPORTED_SPEC_VERSIONS.join(\", \")})`);\n  }\n  if (!Array.isArray(spec.scopes)) throw new Error(\"scopeRegistrySpec.scopes must be an array\");\n  for (const s of spec.scopes) {\n    if (!s || typeof s !== \"object\" || typeof (s as ScopeSpec).token !== \"string\") {\n      throw new Error(\"each scopeRegistrySpec scope needs a string token\");\n    }\n  }\n  return spec as unknown as ScopeRegistrySpec;\n}\n\n// ---------------------------------------------------------------------------\n// The registry / state container\n// ---------------------------------------------------------------------------\n\ninterface OwnedScope {\n  kind: \"owned\";\n  bag: Record<string, ScalarValue>;\n  decls: Map<string, ScopeDeclaration>;\n}\ninterface ForeignScope {\n  kind: \"foreign\";\n  resolver: ScopeResolver;\n  decls: Map<string, ScopeDeclaration>;\n  scopeWritable: boolean;\n}\ntype Entry = OwnedScope | ForeignScope;\n\nexport class ScopeRegistry {\n  private readonly scopes = new Map<string, Entry>();\n\n  /**\n   * Register a scope this registry **owns and stores**. Its bag is seeded from\n   * each declaration's `default` (or a type default). Owned scopes are\n   * type-checked (declarations) and serialized by `save`/`load`.\n   */\n  defineOwned(token: string, declarations: ScopeDeclaration[]): this {\n    this.assertFree(token);\n    const bag: Record<string, ScalarValue> = {};\n    const decls = new Map<string, ScopeDeclaration>();\n    for (const d of declarations) {\n      const name = d.name.toLowerCase();\n      decls.set(name, d);\n      bag[name] = d.default ?? defaultFor(d);\n    }\n    this.scopes.set(token, { kind: \"owned\", bag, decls });\n    return this;\n  }\n\n  /**\n   * Re-initialise an existing **owned** scope's bag from new declarations,\n   * clearing its current values. For scope-local state that resets on a context\n   * change (e.g. entering a new scene / site / deck) without disturbing other\n   * scopes. Mutates the bag in place, so an `EvalContext` already built from this\n   * registry stays valid.\n   */\n  reseedOwned(token: string, declarations: ScopeDeclaration[]): this {\n    const e = this.scopes.get(token);\n    if (!e || e.kind !== \"owned\") throw new Error(`'@${token}' is not an owned scope`);\n    for (const k of Object.keys(e.bag)) delete e.bag[k];\n    e.decls.clear();\n    for (const d of declarations) {\n      const name = d.name.toLowerCase();\n      e.decls.set(name, d);\n      e.bag[name] = d.default ?? defaultFor(d);\n    }\n    return this;\n  }\n\n  /**\n   * Register a **foreign** scope backed by a host `{ get, set? }` resolver. The\n   * values live in the host/other engine and are never stored or saved here.\n   * `declarations` (optional, e.g. imported from a `scopeRegistrySpec`) are used\n   * only for validation; omit them for an opaque scope.\n   */\n  defineForeign(\n    token: string,\n    resolver: ScopeResolver,\n    declarations: ScopeDeclaration[] = [],\n    scopeWritable = true,\n  ): this {\n    this.assertFree(token);\n    const decls = new Map<string, ScopeDeclaration>();\n    for (const d of declarations) decls.set(d.name.toLowerCase(), d);\n    this.scopes.set(token, { kind: \"foreign\", resolver, decls, scopeWritable });\n    return this;\n  }\n\n  has(token: string): boolean {\n    return this.scopes.has(token);\n  }\n\n  /** Read a property; undefined if the scope or property is not present. */\n  get(scope: string, name: string): ScalarValue | undefined {\n    const e = this.scopes.get(scope);\n    if (!e) return undefined;\n    const n = name.toLowerCase();\n    return e.kind === \"owned\" ? e.bag[n] : e.resolver.get(n);\n  }\n\n  /** Write a property. Throws on an unknown or read-only scope/property. */\n  set(scope: string, name: string, value: ScalarValue): void {\n    const e = this.scopes.get(scope);\n    if (!e) throw new Error(`unknown scope '@${scope}'`);\n    const n = name.toLowerCase();\n    if (!this.writable(e, n)) throw new Error(`'@${scope}.${name}' is read-only`);\n    if (e.kind === \"owned\") e.bag[n] = value;\n    else e.resolver.set!(n, value);\n  }\n\n  private writable(e: Entry, name: string): boolean {\n    if (e.kind === \"owned\") return e.decls.get(name)?.writable ?? true;\n    if (!e.resolver.set) return false;                 // no setter => read-only scope\n    return e.decls.get(name)?.writable ?? e.scopeWritable;\n  }\n\n  /**\n   * Build the `EvalContext` expr's `evaluate` consumes: owned scopes as static\n   * bags, foreign scopes as their resolvers. `host` carries dialect-function\n   * callbacks (PRNG, tag lookups) and is passed through untouched.\n   */\n  toEvalContext(host?: Record<string, unknown>): EvalContext {\n    const scopes: EvalContext[\"scopes\"] = {};\n    for (const [token, e] of this.scopes) {\n      scopes[token] = e.kind === \"owned\" ? e.bag : e.resolver;\n    }\n    return { scopes, host };\n  }\n\n  /**\n   * Build the `ExpressionSchema` expr's validator consumes. Scopes with no\n   * declarations are **omitted** (opaque - references into them are not flagged);\n   * declared scopes contribute their property types for validation.\n   */\n  toSchema(): ExpressionSchema {\n    const properties = new Map<string, Map<string, { type: PropertyType; enumValues?: string[] }>>();\n    for (const [token, e] of this.scopes) {\n      if (e.decls.size === 0) continue;\n      const m = new Map<string, { type: PropertyType; enumValues?: string[] }>();\n      for (const [name, d] of e.decls) m.set(name, { type: d.type, enumValues: d.values });\n      properties.set(token, m);\n    }\n    return { properties };\n  }\n\n  /** Serialize **owned** scopes only (foreign scopes are host-owned, host-saved). */\n  save(): Record<string, Record<string, ScalarValue>> {\n    const out: Record<string, Record<string, ScalarValue>> = {};\n    for (const [token, e] of this.scopes) if (e.kind === \"owned\") out[token] = { ...e.bag };\n    return out;\n  }\n\n  /** Restore owned-scope values from a `save` blob. Unknown/foreign scopes are ignored. */\n  load(blob: Record<string, Record<string, ScalarValue>>): void {\n    for (const [token, vals] of Object.entries(blob)) {\n      const e = this.scopes.get(token);\n      if (e?.kind === \"owned\") Object.assign(e.bag, vals);\n    }\n  }\n\n  private assertFree(token: string): void {\n    if (this.scopes.has(token)) throw new Error(`scope '@${token}' is already registered`);\n  }\n}\n\nfunction defaultFor(d: ScopeDeclaration): ScalarValue {\n  if (d.default !== undefined) return d.default;\n  switch (d.type) {\n    case \"boolean\": return false;\n    case \"number\": return 0;\n    case \"string\": return \"\";\n    case \"enum\": return d.values?.[0] ?? \"\";\n    case \"flags\": return [];\n  }\n}\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";AA8DO,IAAM,uBAAA,GAA0B,CAAC,CAAC;AAQlC,SAAS,sBAAsB,MAAA,EAA2C;AAC/E,EAAA,IAAI,CAAC,MAAA,IAAU,OAAO,MAAA,KAAW,UAAU,OAAO,IAAA;AAClD,EAAA,MAAM,MAAO,MAAA,CAAmC,iBAAA;AAChD,EAAA,IAAI,GAAA,KAAQ,QAAW,OAAO,IAAA;AAC9B,EAAA,IAAI,OAAO,QAAQ,QAAA,IAAY,GAAA,KAAQ,MAAM,MAAM,IAAI,MAAM,qCAAqC,CAAA;AAClG,EAAA,MAAM,IAAA,GAAO,GAAA;AACb,EAAA,IAAI,OAAO,IAAA,CAAK,OAAA,KAAY,UAAU,MAAM,IAAI,MAAM,4CAA4C,CAAA;AAClG,EAAA,IAAI,CAAE,uBAAA,CAA8C,QAAA,CAAS,IAAA,CAAK,OAAO,CAAA,EAAG;AAC1E,IAAA,MAAM,IAAI,KAAA,CAAM,CAAA,sCAAA,EAAyC,IAAA,CAAK,OAAO,gBAAgB,uBAAA,CAAwB,IAAA,CAAK,IAAI,CAAC,CAAA,CAAA,CAAG,CAAA;AAAA,EAC5H;AACA,EAAA,IAAI,CAAC,MAAM,OAAA,CAAQ,IAAA,CAAK,MAAM,CAAA,EAAG,MAAM,IAAI,KAAA,CAAM,2CAA2C,CAAA;AAC5F,EAAA,KAAA,MAAW,CAAA,IAAK,KAAK,MAAA,EAAQ;AAC3B,IAAA,IAAI,CAAC,KAAK,OAAO,CAAA,KAAM,YAAY,OAAQ,CAAA,CAAgB,UAAU,QAAA,EAAU;AAC7E,MAAA,MAAM,IAAI,MAAM,mDAAmD,CAAA;AAAA,IACrE;AAAA,EACF;AACA,EAAA,OAAO,IAAA;AACT;AAkCO,IAAM,WAAA,GAAN,MAAM,YAAA,CAAY;AAAA;AAAA;AAAA;AAAA,EAId,SAAsC,EAAC;AAAA,EACxC,KAAA,uBAAY,GAAA,EAA8B;AAAA,EACjC,WAAA,uBAAkB,GAAA,EAAiC;AAAA,EACnD,QAAA,uBAAe,GAAA,EAAiC;AAAA;AAAA;AAAA;AAAA,EAIhD,IAAA;AAAA,EAEjB,WAAA,CAAY,YAAA,GAAmC,EAAC,EAAG,IAAA,EAAiD;AAClG,IAAA,IAAA,CAAK,OAAO,IAAA,EAAM,SAAA,KAAc,CAAC,CAAA,KAAM,EAAE,WAAA,EAAY,CAAA;AACrD,IAAA,IAAA,CAAK,KAAK,YAAY,CAAA;AAAA,EACxB;AAAA,EAEQ,KAAK,YAAA,EAAwC;AACnD,IAAA,KAAA,MAAW,KAAK,YAAA,EAAc;AAC5B,MAAA,MAAM,IAAA,GAAO,IAAA,CAAK,IAAA,CAAK,CAAA,CAAE,IAAI,CAAA;AAC7B,MAAA,IAAA,CAAK,KAAA,CAAM,GAAA,CAAI,IAAA,EAAM,CAAC,CAAA;AAGtB,MAAA,IAAA,CAAK,MAAA,CAAO,IAAI,CAAA,GAAI,eAAA,CAAgB,EAAE,OAAA,IAAW,UAAA,CAAW,CAAC,CAAC,CAAA;AAAA,IAChE;AAAA,EACF;AAAA,EAEA,IAAI,IAAA,EAAuC;AACzC,IAAA,OAAO,IAAA,CAAK,MAAA,CAAO,IAAA,CAAK,IAAA,CAAK,IAAI,CAAC,CAAA;AAAA,EACpC;AAAA;AAAA;AAAA;AAAA,EAKA,GAAA,CAAI,IAAA,EAAc,KAAA,EAAoB,IAAA,EAAyD;AAC7F,IAAA,MAAM,CAAA,GAAI,IAAA,CAAK,IAAA,CAAK,IAAI,CAAA;AACxB,IAAA,IAAI,IAAA,CAAK,KAAA,CAAM,GAAA,CAAI,CAAC,CAAA,EAAG,QAAA,KAAa,KAAA,EAAO,MAAM,IAAI,KAAA,CAAM,CAAA,CAAA,EAAI,IAAI,CAAA,cAAA,CAAgB,CAAA;AACnF,IAAA,MAAM,MAAA,GAAoB;AAAA,MACxB,IAAA,EAAM,CAAA;AAAA,MACN,IAAA,EAAM,IAAA,CAAK,MAAA,CAAO,CAAC,CAAA;AAAA,MACnB,IAAA,EAAM,KAAA;AAAA,MACN,MAAA,EAAQ,MAAM,MAAA,IAAU,KAAA;AAAA,MACxB,QAAQ,IAAA,EAAM;AAAA,KAChB;AACA,IAAA,IAAA,CAAK,MAAA,CAAO,CAAC,CAAA,GAAI,KAAA;AACjB,IAAA,KAAA,MAAW,KAAA,IAAS,IAAA,CAAK,QAAA,EAAU,KAAA,CAAM,MAAM,CAAA;AAC/C,IAAA,IAAI,CAAC,OAAO,MAAA,EAAQ,KAAA,MAAW,MAAM,IAAA,CAAK,WAAA,KAAgB,MAAM,CAAA;AAChE,IAAA,OAAO,MAAA;AAAA,EACT;AAAA;AAAA,EAGA,UAAU,EAAA,EAA6C;AACrD,IAAA,IAAA,CAAK,WAAA,CAAY,IAAI,EAAE,CAAA;AACvB,IAAA,OAAO,MAAM,IAAA,CAAK,WAAA,CAAY,MAAA,CAAO,EAAE,CAAA;AAAA,EACzC;AAAA;AAAA,EAGA,QAAQ,EAAA,EAA6C;AACnD,IAAA,IAAA,CAAK,QAAA,CAAS,IAAI,EAAE,CAAA;AACpB,IAAA,OAAO,MAAM,IAAA,CAAK,QAAA,CAAS,MAAA,CAAO,EAAE,CAAA;AAAA,EACtC;AAAA;AAAA;AAAA,EAIA,IAAA,GAAsB;AACpB,IAAA,OAAO,CAAC,GAAG,IAAA,CAAK,KAAA,CAAM,SAAS,CAAA,CAAE,IAAI,CAAC,CAAC,MAAM,CAAC,CAAA,KAAM,OAAO,CAAA,EAAG,IAAA,CAAK,IAAI,IAAI,CAAA,EAAG,MAAA,EAAW,IAAI,CAAC,CAAA;AAAA,EAChG;AAAA,EAEA,YAAA,GAAmC;AACjC,IAAA,OAAO,CAAC,GAAG,IAAA,CAAK,KAAA,CAAM,QAAQ,CAAA;AAAA,EAChC;AAAA;AAAA;AAAA;AAAA,EAKA,KAAA,GAAqB;AACnB,IAAA,MAAM,CAAA,GAAI,IAAI,YAAA,CAAY,IAAI,EAAE,SAAA,EAAW,IAAA,CAAK,IAAA,EAAM,CAAA;AACtD,IAAA,CAAA,CAAE,KAAA,GAAQ,IAAI,GAAA,CAAI,IAAA,CAAK,KAAK,CAAA;AAC5B,IAAA,MAAA,CAAO,OAAO,CAAA,CAAE,MAAA,EAAQ,eAAA,CAAgB,IAAA,CAAK,MAAM,CAAC,CAAA;AACpD,IAAA,OAAO,CAAA;AAAA,EACT;AAAA;AAAA;AAAA,EAIA,OAAO,YAAA,EAAwC;AAC7C,IAAA,KAAA,MAAW,CAAA,IAAK,OAAO,IAAA,CAAK,IAAA,CAAK,MAAM,CAAA,EAAG,OAAO,IAAA,CAAK,MAAA,CAAO,CAAC,CAAA;AAC9D,IAAA,IAAA,CAAK,MAAM,KAAA,EAAM;AACjB,IAAA,IAAA,CAAK,KAAK,YAAY,CAAA;AAAA,EACxB;AAAA;AAAA,EAGA,IAAA,GAAoC;AAClC,IAAA,OAAO,eAAA,CAAgB,KAAK,MAAM,CAAA;AAAA,EACpC;AAAA;AAAA;AAAA;AAAA,EAKA,KAAK,MAAA,EAA2C;AAC9C,IAAA,KAAA,MAAW,CAAC,CAAA,EAAG,CAAC,CAAA,IAAK,OAAO,OAAA,CAAQ,MAAM,CAAA,EAAG,IAAA,CAAK,MAAA,CAAO,IAAA,CAAK,IAAA,CAAK,CAAC,CAAC,CAAA,GAAI,CAAA;AAAA,EAC3E;AACF;AAEA,SAAS,MAAA,CAAO,CAAA,EAAqB,KAAA,EAAgC,QAAA,EAAoB,IAAA,EAA4B;AACnH,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,IAAA,IAAQ,CAAA,CAAE,IAAA,CAAK,WAAA,EAAY;AAAA,IACjC,MAAM,CAAA,CAAE,IAAA;AAAA,IACR,KAAA;AAAA,IACA,OAAA,EAAS,CAAA,CAAE,OAAA,IAAW,UAAA,CAAW,CAAC,CAAA;AAAA,IAClC,GAAI,EAAE,MAAA,KAAW,MAAA,GAAY,EAAE,MAAA,EAAQ,CAAA,CAAE,MAAA,EAAO,GAAI,EAAC;AAAA,IACrD,QAAA,EAAU,QAAA,IAAY,CAAA,CAAE,QAAA,IAAY;AAAA,GACtC;AACF;AAyBO,IAAM,qBAAA,GAAwB;AAE9B,IAAM,gBAAN,MAAoB;AAAA,EACR,MAAA,uBAAa,GAAA,EAAmB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOjD,WAAA,CAAY,OAAe,YAAA,EAAwC;AACjE,IAAA,OAAO,KAAK,UAAA,CAAW,KAAA,EAAO,IAAI,WAAA,CAAY,YAAY,CAAC,CAAA;AAAA,EAC7D;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,UAAA,CAAW,OAAe,GAAA,EAAwB;AAChD,IAAA,IAAA,CAAK,WAAW,KAAK,CAAA;AACrB,IAAA,IAAA,CAAK,OAAO,GAAA,CAAI,KAAA,EAAO,EAAE,IAAA,EAAM,OAAA,EAAS,KAAK,CAAA;AAC7C,IAAA,OAAO,IAAA;AAAA,EACT;AAAA;AAAA,EAGA,SAAS,KAAA,EAA4B;AACnC,IAAA,MAAM,CAAA,GAAI,IAAA,CAAK,MAAA,CAAO,GAAA,CAAI,KAAK,CAAA;AAC/B,IAAA,IAAI,CAAC,CAAA,IAAK,CAAA,CAAE,IAAA,KAAS,OAAA,QAAe,IAAI,KAAA,CAAM,CAAA,EAAA,EAAK,KAAK,CAAA,uBAAA,CAAyB,CAAA;AACjF,IAAA,OAAO,CAAA,CAAE,GAAA;AAAA,EACX;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,WAAA,CAAY,OAAe,YAAA,EAAwC;AACjE,IAAA,IAAA,CAAK,QAAA,CAAS,KAAK,CAAA,CAAE,MAAA,CAAO,YAAY,CAAA;AACxC,IAAA,OAAO,IAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,cACE,KAAA,EACA,QAAA,EACA,eAAmC,EAAC,EACpC,gBAAgB,IAAA,EACV;AACN,IAAA,IAAA,CAAK,WAAW,KAAK,CAAA;AACrB,IAAA,MAAM,KAAA,uBAAY,GAAA,EAA8B;AAChD,IAAA,KAAA,MAAW,CAAA,IAAK,cAAc,KAAA,CAAM,GAAA,CAAI,EAAE,IAAA,CAAK,WAAA,IAAe,CAAC,CAAA;AAC/D,IAAA,IAAA,CAAK,MAAA,CAAO,IAAI,KAAA,EAAO,EAAE,MAAM,SAAA,EAAW,QAAA,EAAU,KAAA,EAAO,aAAA,EAAe,CAAA;AAC1E,IAAA,OAAO,IAAA;AAAA,EACT;AAAA,EAEA,IAAI,KAAA,EAAwB;AAC1B,IAAA,OAAO,IAAA,CAAK,MAAA,CAAO,GAAA,CAAI,KAAK,CAAA;AAAA,EAC9B;AAAA;AAAA,EAGA,GAAA,CAAI,OAAe,IAAA,EAAuC;AACxD,IAAA,MAAM,CAAA,GAAI,IAAA,CAAK,MAAA,CAAO,GAAA,CAAI,KAAK,CAAA;AAC/B,IAAA,IAAI,CAAC,GAAG,OAAO,MAAA;AACf,IAAA,OAAO,CAAA,CAAE,IAAA,KAAS,OAAA,GAAU,CAAA,CAAE,GAAA,CAAI,GAAA,CAAI,IAAI,CAAA,GAAI,CAAA,CAAE,QAAA,CAAS,GAAA,CAAI,IAAA,CAAK,aAAa,CAAA;AAAA,EACjF;AAAA;AAAA;AAAA;AAAA,EAKA,GAAA,CAAI,KAAA,EAAe,IAAA,EAAc,KAAA,EAA0B;AACzD,IAAA,MAAM,CAAA,GAAI,IAAA,CAAK,MAAA,CAAO,GAAA,CAAI,KAAK,CAAA;AAC/B,IAAA,IAAI,CAAC,CAAA,EAAG,MAAM,IAAI,KAAA,CAAM,CAAA,gBAAA,EAAmB,KAAK,CAAA,CAAA,CAAG,CAAA;AACnD,IAAA,IAAI,CAAA,CAAE,SAAS,OAAA,EAAS;AACtB,MAAA,IAAI;AACF,QAAA,CAAA,CAAE,GAAA,CAAI,GAAA,CAAI,IAAA,EAAM,KAAK,CAAA;AAAA,MACvB,CAAA,CAAA,MAAQ;AACN,QAAA,MAAM,IAAI,KAAA,CAAM,CAAA,EAAA,EAAK,KAAK,CAAA,CAAA,EAAI,IAAI,CAAA,cAAA,CAAgB,CAAA;AAAA,MACpD;AACA,MAAA;AAAA,IACF;AACA,IAAA,MAAM,CAAA,GAAI,KAAK,WAAA,EAAY;AAC3B,IAAA,IAAI,CAAC,IAAA,CAAK,eAAA,CAAgB,CAAA,EAAG,CAAC,CAAA,EAAG,MAAM,IAAI,KAAA,CAAM,CAAA,EAAA,EAAK,KAAK,CAAA,CAAA,EAAI,IAAI,CAAA,cAAA,CAAgB,CAAA;AACnF,IAAA,CAAA,CAAE,QAAA,CAAS,GAAA,CAAK,CAAA,EAAG,KAAK,CAAA;AAAA,EAC1B;AAAA,EAEQ,eAAA,CAAgB,GAAiB,IAAA,EAAuB;AAC9D,IAAA,IAAI,CAAC,CAAA,CAAE,QAAA,CAAS,GAAA,EAAK,OAAO,KAAA;AAC5B,IAAA,OAAO,EAAE,KAAA,CAAM,GAAA,CAAI,IAAI,CAAA,EAAG,YAAY,CAAA,CAAE,aAAA;AAAA,EAC1C;AAAA;AAAA;AAAA;AAAA,EAKA,cAAA,GAAsD;AACpD,IAAA,MAAM,MAA2C,EAAC;AAClD,IAAA,KAAA,MAAW,CAAC,KAAA,EAAO,CAAC,CAAA,IAAK,KAAK,MAAA,EAAQ;AACpC,MAAA,IAAI,CAAA,CAAE,SAAS,OAAA,EAAS;AACtB,QAAA,KAAA,MAAW,GAAA,IAAO,CAAA,CAAE,GAAA,CAAI,IAAA,EAAK,EAAG,GAAA,CAAI,IAAA,CAAK,EAAE,KAAA,EAAO,KAAA,EAAO,GAAG,GAAA,EAAK,CAAA;AAAA,MACnE,CAAA,MAAO;AACL,QAAA,KAAA,MAAW,CAAA,IAAK,CAAA,CAAE,KAAA,CAAM,MAAA,EAAO,EAAG;AAChC,UAAA,GAAA,CAAI,IAAA,CAAK;AAAA,YACP,KAAA,EAAO,KAAA;AAAA,YACP,GAAG,MAAA,CAAO,CAAA,EAAG,EAAE,QAAA,CAAS,GAAA,CAAI,EAAE,IAAA,CAAK,WAAA,EAAa,CAAA,EAAG,KAAK,eAAA,CAAgB,CAAA,EAAG,EAAE,IAAA,CAAK,WAAA,EAAa,CAAC;AAAA,WACjG,CAAA;AAAA,QACH;AAAA,MACF;AAAA,IACF;AACA,IAAA,OAAO,GAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,cAAc,IAAA,EAA6C;AACzD,IAAA,MAAM,SAAgC,EAAC;AACvC,IAAA,KAAA,MAAW,CAAC,KAAA,EAAO,CAAC,CAAA,IAAK,KAAK,MAAA,EAAQ;AACpC,MAAA,MAAA,CAAO,KAAK,IAAI,CAAA,CAAE,IAAA,KAAS,UAAU,CAAA,CAAE,GAAA,CAAI,SAAS,CAAA,CAAE,QAAA;AAAA,IACxD;AAKA,IAAA,MAAM,SAAA,GAAY,KAAK,cAAA,EAAe;AACtC,IAAA,OAAO,UAAU,IAAA,KAAS,CAAA,GAAI,EAAE,MAAA,EAAQ,MAAK,GAAI;AAAA,MAC/C,MAAA;AAAA,MAAQ,IAAA;AAAA,MACR,SAAA,EAAW,CAAC,KAAA,EAAO,IAAA,KAAS,SAAA,CAAU,GAAA,CAAI,KAAK,CAAA,EAAG,GAAA,CAAI,IAAA,CAAK,WAAA,EAAa;AAAA,KAC1E;AAAA,EACF;AAAA;AAAA,EAGQ,cAAA,GAA8D;AACpE,IAAA,MAAM,GAAA,uBAAU,GAAA,EAA4C;AAC5D,IAAA,KAAA,MAAW,CAAC,KAAA,EAAO,CAAC,CAAA,IAAK,KAAK,MAAA,EAAQ;AACpC,MAAA,MAAM,KAAA,GAAQ,CAAA,CAAE,IAAA,KAAS,OAAA,GAAU,CAAA,CAAE,GAAA,CAAI,YAAA,EAAa,GAAI,CAAC,GAAG,CAAA,CAAE,KAAA,CAAM,QAAQ,CAAA;AAC9E,MAAA,KAAA,MAAW,KAAK,KAAA,EAAO;AACrB,QAAA,IAAI,CAAA,CAAE,IAAA,KAAS,SAAA,IAAa,CAAA,CAAE,WAAW,MAAA,EAAW;AACpD,QAAA,IAAI,CAAA,GAAI,GAAA,CAAI,GAAA,CAAI,KAAK,CAAA;AACrB,QAAA,IAAI,CAAC,CAAA,EAAG;AAAE,UAAA,CAAA,uBAAQ,GAAA,EAAI;AAAG,UAAA,GAAA,CAAI,GAAA,CAAI,OAAO,CAAC,CAAA;AAAA,QAAG;AAC5C,QAAA,CAAA,CAAE,IAAI,CAAA,CAAE,IAAA,CAAK,WAAA,EAAY,EAAG,EAAE,MAAM,CAAA;AAAA,MACtC;AAAA,IACF;AACA,IAAA,OAAO,GAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,QAAA,GAA6B;AAC3B,IAAA,MAAM,UAAA,uBAAiB,GAAA,EAA2F;AAClH,IAAA,KAAA,MAAW,CAAC,KAAA,EAAO,CAAC,CAAA,IAAK,KAAK,MAAA,EAAQ;AACpC,MAAA,MAAM,KAAA,GAAQ,CAAA,CAAE,IAAA,KAAS,OAAA,GAAU,CAAA,CAAE,GAAA,CAAI,YAAA,EAAa,GAAI,CAAC,GAAG,CAAA,CAAE,KAAA,CAAM,QAAQ,CAAA;AAC9E,MAAA,IAAI,KAAA,CAAM,WAAW,CAAA,EAAG;AACxB,MAAA,MAAM,CAAA,uBAAQ,GAAA,EAA8E;AAC5F,MAAA,KAAA,MAAW,KAAK,KAAA,EAAO,CAAA,CAAE,IAAI,CAAA,CAAE,IAAA,CAAK,aAAY,EAAG;AAAA,QACjD,MAAM,CAAA,CAAE,IAAA;AAAA,QAAM,YAAY,CAAA,CAAE,MAAA;AAAA,QAC5B,GAAI,EAAE,MAAA,KAAW,MAAA,GAAY,EAAE,MAAA,EAAQ,CAAA,CAAE,MAAA,EAAO,GAAI;AAAC,OACtD,CAAA;AACD,MAAA,UAAA,CAAW,GAAA,CAAI,OAAO,CAAC,CAAA;AAAA,IACzB;AACA,IAAA,OAAO,EAAE,UAAA,EAAW;AAAA,EACtB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,IAAA,GAAoD;AAClD,IAAA,MAAM,MAAmD,EAAC;AAC1D,IAAA,KAAA,MAAW,CAAC,KAAA,EAAO,CAAC,CAAA,IAAK,KAAK,MAAA,EAAQ,IAAI,CAAA,CAAE,IAAA,KAAS,SAAS,GAAA,CAAI,KAAK,CAAA,GAAI,CAAA,CAAE,IAAI,IAAA,EAAK;AACtF,IAAA,OAAO,GAAA;AAAA,EACT;AAAA;AAAA;AAAA,EAIA,KAAK,IAAA,EAAyD;AAC5D,IAAA,KAAA,MAAW,CAAC,KAAA,EAAO,IAAI,KAAK,MAAA,CAAO,OAAA,CAAQ,IAAI,CAAA,EAAG;AAChD,MAAA,MAAM,CAAA,GAAI,IAAA,CAAK,MAAA,CAAO,GAAA,CAAI,KAAK,CAAA;AAC/B,MAAA,IAAI,GAAG,IAAA,KAAS,OAAA,EAAS,CAAA,CAAE,GAAA,CAAI,KAAK,IAAI,CAAA;AAAA,IAC1C;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,YAAA,GAAmC;AACjC,IAAA,OAAO,EAAE,OAAA,EAAS,qBAAA,EAAuB,MAAA,EAAQ,IAAA,CAAK,MAAK,EAAE;AAAA,EAC/D;AAAA;AAAA,EAGA,aAAa,QAAA,EAAoC;AAC/C,IAAA,IAAI,QAAA,CAAS,YAAY,qBAAA,EAAuB;AAC9C,MAAA,MAAM,IAAI,KAAA,CAAM,CAAA,yCAAA,EAA4C,SAAS,OAAO,CAAA,aAAA,EAAgB,qBAAqB,CAAA,CAAA,CAAG,CAAA;AAAA,IACtH;AACA,IAAA,IAAA,CAAK,IAAA,CAAK,SAAS,MAAM,CAAA;AAAA,EAC3B;AAAA,EAEQ,WAAW,KAAA,EAAqB;AACtC,IAAA,IAAI,IAAA,CAAK,MAAA,CAAO,GAAA,CAAI,KAAK,CAAA,QAAS,IAAI,KAAA,CAAM,CAAA,QAAA,EAAW,KAAK,CAAA,uBAAA,CAAyB,CAAA;AAAA,EACvF;AACF;AAEA,SAAS,WAAW,CAAA,EAAkC;AACpD,EAAA,IAAI,CAAA,CAAE,OAAA,KAAY,MAAA,EAAW,OAAO,CAAA,CAAE,OAAA;AACtC,EAAA,QAAQ,EAAE,IAAA;AAAM,IACd,KAAK,SAAA;AAAW,MAAA,OAAO,KAAA;AAAA,IACvB,KAAK,QAAA;AAAU,MAAA,OAAO,CAAA;AAAA,IACtB,KAAK,QAAA;AAAU,MAAA,OAAO,EAAA;AAAA,IACtB,KAAK,MAAA;AAAQ,MAAA,OAAO,CAAA,CAAE,MAAA,GAAS,CAAC,CAAA,IAAK,EAAA;AAAA,IACrC,KAAK,OAAA;AAAS,MAAA,OAAO,EAAC;AAAA;AAAA,IAEtB,KAAK,SAAA;AAAW,MAAA,OAAO,CAAA,CAAE,MAAA,GAAS,CAAC,CAAA,IAAK,EAAA;AAAA;AAE5C","file":"index.js","sourcesContent":["// ---------------------------------------------------------------------------\n// @wildwinter/scoperegistry - the scope registry / runtime state container that\n// sits on top of @wildwinter/expr.\n//\n// expr is a stateless calculator: given an AST, an EvalContext (the state), and\n// a Dialect, it computes. This package is the *state* layer: it owns the world\n// state as a set of named scopes - each either an **owned** scope (a property\n// bag this registry stores and saves) or a **foreign** scope (host- or\n// other-engine-resolved at runtime, never stored here) - and produces the\n// `EvalContext` (for evaluation) and `ExpressionSchema` (for validation) that\n// expr consumes. Plus the `scopeRegistrySpec` interop format for importing a\n// foreign owner's scope declarations.\n//\n// Design: design/scope-registry.md (in the patter repo). expr never depends on\n// this; this depends one-way on expr.\n// ---------------------------------------------------------------------------\n\nimport type {\n  EvalContext, ExpressionSchema, PropertyType, ScalarValue, ScopeResolver,\n} from \"@wildwinter/expr\";\n\nexport type { EvalContext, ExpressionSchema, PropertyType, ScalarValue, ScopeResolver } from \"@wildwinter/expr\";\n\n// ---------------------------------------------------------------------------\n// Declarations + the scopeRegistrySpec interop format\n// ---------------------------------------------------------------------------\n\n/**\n * A property declaration. `default` is used by an *owned* scope to seed its bag\n * (foreign scopes ignore it - the host owns the value). `writable: false` makes\n * a property read-only; default is read/write. (`type`/`values` feed validation.)\n */\nexport interface ScopeDeclaration {\n  name: string;\n  type: PropertyType;\n  values?: string[];        // for enum / flags\n  /** A quality's ordered ladder of stage names (quality.md). */\n  stages?: string[];\n  default?: ScalarValue;    // owned scopes: seed value\n  writable?: boolean;       // default true\n}\n\n/** One scope in a `scopeRegistrySpec`: a token + (optional) declarations. */\nexport interface ScopeSpec {\n  token: string;\n  /** Scope-level read/write default for its declarations (default true). */\n  writable?: boolean;\n  /** Property declarations; omit for an opaque scope (any name, unchecked). */\n  declarations?: ScopeDeclaration[];\n}\n\n/**\n * The interop format an owner (Storylet Studio, a host game) exports so another\n * engine can validate references into its scopes. Carried under the well-known\n * `scopeRegistrySpec` JSON key (inside a `.storyworld`, or a standalone file).\n */\nexport interface ScopeRegistrySpec {\n  version: number;\n  scopes: ScopeSpec[];\n}\n\n/** The spec versions this build understands. */\nexport const SUPPORTED_SPEC_VERSIONS = [1] as const;\n\n/**\n * Extract + validate a `scopeRegistrySpec` from any JSON value (a parsed\n * `.storyworld` bundle, or a vanilla `{ scopeRegistrySpec: ... }` manifest).\n * Returns null when the key is absent (so callers can probe arbitrary files);\n * throws on a malformed or unsupported-version spec.\n */\nexport function readScopeRegistrySpec(source: unknown): ScopeRegistrySpec | null {\n  if (!source || typeof source !== \"object\") return null;\n  const raw = (source as Record<string, unknown>).scopeRegistrySpec;\n  if (raw === undefined) return null;\n  if (typeof raw !== \"object\" || raw === null) throw new Error(\"scopeRegistrySpec must be an object\");\n  const spec = raw as Record<string, unknown>;\n  if (typeof spec.version !== \"number\") throw new Error(\"scopeRegistrySpec.version must be a number\");\n  if (!(SUPPORTED_SPEC_VERSIONS as readonly number[]).includes(spec.version)) {\n    throw new Error(`unsupported scopeRegistrySpec version ${spec.version} (supported: ${SUPPORTED_SPEC_VERSIONS.join(\", \")})`);\n  }\n  if (!Array.isArray(spec.scopes)) throw new Error(\"scopeRegistrySpec.scopes must be an array\");\n  for (const s of spec.scopes) {\n    if (!s || typeof s !== \"object\" || typeof (s as ScopeSpec).token !== \"string\") {\n      throw new Error(\"each scopeRegistrySpec scope needs a string token\");\n    }\n  }\n  return spec as unknown as ScopeRegistrySpec;\n}\n\n// ---------------------------------------------------------------------------\n// PropertyBag - the state kernel's unit of state (added 0.2.0; design:\n// storylets-new/design/engine-runtimes.md 3.1). A typed, declared property\n// bag with defaults, the firing rule (engine writes notify subscribers;\n// host writes are silent but always auditable), examiner rows, one\n// sanctioned clone door, and bare-value save/load. Owned registry scopes\n// are bags; products may also hold bag families of their own (per-box,\n// per-scene) and mount the shared ones.\n// ---------------------------------------------------------------------------\n\n/** One property change. `silent` marks a host write (the firing rule: it\n *  reaches the audit hook but not subscribers); `reason` is the host's own\n *  note for its log. */\nexport interface BagChange {\n  name: string;\n  prev?: ScalarValue;\n  next: ScalarValue;\n  silent: boolean;\n  reason?: string;\n}\n\n/** One examiner row: what a property examiner/editor needs to render and\n *  edit a declared property. */\nexport interface PropertyRow {\n  name: string;\n  type: PropertyType;\n  value: ScalarValue | undefined;\n  default: ScalarValue;\n  values?: string[];\n  writable: boolean;\n}\n\nexport class PropertyBag {\n  /** The live values record (stable identity across reseed, so an\n   *  EvalContext built over it stays valid). Read-path for evaluation;\n   *  writes go through `set` so the firing rule applies. */\n  readonly values: Record<string, ScalarValue> = {};\n  private decls = new Map<string, ScopeDeclaration>();\n  private readonly subscribers = new Set<(change: BagChange) => void>();\n  private readonly auditors = new Set<(change: BagChange) => void>();\n  /** Name normalisation policy: lowercase by default (the registry's\n   *  long-standing contract); a product whose names are case-significant\n   *  passes identity. */\n  private readonly norm: (name: string) => string;\n\n  constructor(declarations: ScopeDeclaration[] = [], opts?: { normalise?: (name: string) => string }) {\n    this.norm = opts?.normalise ?? ((n) => n.toLowerCase());\n    this.seed(declarations);\n  }\n\n  private seed(declarations: ScopeDeclaration[]): void {\n    for (const d of declarations) {\n      const name = this.norm(d.name);\n      this.decls.set(name, d);\n      // Cloned so bags seeded from one declaration set never share a\n      // mutable default (flags arrays).\n      this.values[name] = structuredClone(d.default ?? defaultFor(d));\n    }\n  }\n\n  get(name: string): ScalarValue | undefined {\n    return this.values[this.norm(name)];\n  }\n\n  /** Write a property. Engine writes (the default) notify subscribers;\n   *  pass `silent: true` for a host write, which reaches only the audit\n   *  hook. Throws on a read-only property. Returns the change. */\n  set(name: string, value: ScalarValue, opts?: { silent?: boolean; reason?: string }): BagChange {\n    const n = this.norm(name);\n    if (this.decls.get(n)?.writable === false) throw new Error(`'${name}' is read-only`);\n    const change: BagChange = {\n      name: n,\n      prev: this.values[n],\n      next: value,\n      silent: opts?.silent ?? false,\n      reason: opts?.reason,\n    };\n    this.values[n] = value;\n    for (const audit of this.auditors) audit(change);\n    if (!change.silent) for (const fn of this.subscribers) fn(change);\n    return change;\n  }\n\n  /** Notified of engine (non-silent) writes. Returns the unsubscribe. */\n  subscribe(fn: (change: BagChange) => void): () => void {\n    this.subscribers.add(fn);\n    return () => this.subscribers.delete(fn);\n  }\n\n  /** Notified of EVERY write, silent or not. Returns the unsubscribe. */\n  onAudit(fn: (change: BagChange) => void): () => void {\n    this.auditors.add(fn);\n    return () => this.auditors.delete(fn);\n  }\n\n  /** Examiner rows: the declared surface only (stray values are storage,\n   *  not surface). */\n  rows(): PropertyRow[] {\n    return [...this.decls.entries()].map(([name, d]) => rowFor(d, this.get(name), undefined, name));\n  }\n\n  declarations(): ScopeDeclaration[] {\n    return [...this.decls.values()];\n  }\n\n  /** The one sanctioned copy door: values deep-copied, declarations\n   *  duplicated, the normalisation policy carried, subscriptions NOT\n   *  carried. */\n  clone(): PropertyBag {\n    const c = new PropertyBag([], { normalise: this.norm });\n    c.decls = new Map(this.decls);\n    Object.assign(c.values, structuredClone(this.values));\n    return c;\n  }\n\n  /** Clear and re-seed from new declarations, in place (the values record\n   *  keeps its identity, so contexts built over it stay valid). */\n  reseed(declarations: ScopeDeclaration[]): void {\n    for (const k of Object.keys(this.values)) delete this.values[k];\n    this.decls.clear();\n    this.seed(declarations);\n  }\n\n  /** Bare values, ready to embed in a product's save. */\n  save(): Record<string, ScalarValue> {\n    return structuredClone(this.values);\n  }\n\n  /** Lay saved values over the current ones (call after a fresh seed:\n   *  orphans land as strays, new declarations keep their defaults; the\n   *  product decides whether to prune). Does not fire events. */\n  load(values: Record<string, ScalarValue>): void {\n    for (const [k, v] of Object.entries(values)) this.values[this.norm(k)] = v;\n  }\n}\n\nfunction rowFor(d: ScopeDeclaration, value: ScalarValue | undefined, writable?: boolean, name?: string): PropertyRow {\n  return {\n    name: name ?? d.name.toLowerCase(),\n    type: d.type,\n    value,\n    default: d.default ?? defaultFor(d),\n    ...(d.values !== undefined ? { values: d.values } : {}),\n    writable: writable ?? d.writable ?? true,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// The registry / state container\n// ---------------------------------------------------------------------------\n\ninterface OwnedScope {\n  kind: \"owned\";\n  bag: PropertyBag;\n}\ninterface ForeignScope {\n  kind: \"foreign\";\n  resolver: ScopeResolver;\n  decls: Map<string, ScopeDeclaration>;\n  scopeWritable: boolean;\n}\ntype Entry = OwnedScope | ForeignScope;\n\n/** The versioned owned-state fragment both product save envelopes embed\n *  (design/engine-runtimes.md 3.1: one serialisation shape for bags). */\nexport interface OwnedStateFragment {\n  version: number;\n  scopes: Record<string, Record<string, ScalarValue>>;\n}\n\nexport const SAVE_FRAGMENT_VERSION = 1;\n\nexport class ScopeRegistry {\n  private readonly scopes = new Map<string, Entry>();\n\n  /**\n   * Register a scope this registry **owns and stores**. Its bag is seeded from\n   * each declaration's `default` (or a type default). Owned scopes are\n   * type-checked (declarations) and serialized by `save`/`load`.\n   */\n  defineOwned(token: string, declarations: ScopeDeclaration[]): this {\n    return this.mountOwned(token, new PropertyBag(declarations));\n  }\n\n  /**\n   * Attach an EXISTING bag as an owned scope - the shared-container move: a\n   * host (or the other product) holds the bag; this registry reads, writes\n   * and lists it like its own, but the holder saves it.\n   */\n  mountOwned(token: string, bag: PropertyBag): this {\n    this.assertFree(token);\n    this.scopes.set(token, { kind: \"owned\", bag });\n    return this;\n  }\n\n  /** An owned scope's bag (subscribe, audit, rows live there). */\n  ownedBag(token: string): PropertyBag {\n    const e = this.scopes.get(token);\n    if (!e || e.kind !== \"owned\") throw new Error(`'@${token}' is not an owned scope`);\n    return e.bag;\n  }\n\n  /**\n   * Re-initialise an existing **owned** scope's bag from new declarations,\n   * clearing its current values. For scope-local state that resets on a context\n   * change (e.g. entering a new scene / site / deck) without disturbing other\n   * scopes. Mutates the bag in place, so an `EvalContext` already built from this\n   * registry stays valid.\n   */\n  reseedOwned(token: string, declarations: ScopeDeclaration[]): this {\n    this.ownedBag(token).reseed(declarations);\n    return this;\n  }\n\n  /**\n   * Register a **foreign** scope backed by a host `{ get, set? }` resolver. The\n   * values live in the host/other engine and are never stored or saved here.\n   * `declarations` (optional, e.g. imported from a `scopeRegistrySpec`) are used\n   * only for validation; omit them for an opaque scope.\n   */\n  defineForeign(\n    token: string,\n    resolver: ScopeResolver,\n    declarations: ScopeDeclaration[] = [],\n    scopeWritable = true,\n  ): this {\n    this.assertFree(token);\n    const decls = new Map<string, ScopeDeclaration>();\n    for (const d of declarations) decls.set(d.name.toLowerCase(), d);\n    this.scopes.set(token, { kind: \"foreign\", resolver, decls, scopeWritable });\n    return this;\n  }\n\n  has(token: string): boolean {\n    return this.scopes.has(token);\n  }\n\n  /** Read a property; undefined if the scope or property is not present. */\n  get(scope: string, name: string): ScalarValue | undefined {\n    const e = this.scopes.get(scope);\n    if (!e) return undefined;\n    return e.kind === \"owned\" ? e.bag.get(name) : e.resolver.get(name.toLowerCase());\n  }\n\n  /** Write a property (an ENGINE write: the bag's subscribers fire; use\n   *  the bag directly for silent host writes). Throws on an unknown or\n   *  read-only scope/property. */\n  set(scope: string, name: string, value: ScalarValue): void {\n    const e = this.scopes.get(scope);\n    if (!e) throw new Error(`unknown scope '@${scope}'`);\n    if (e.kind === \"owned\") {\n      try {\n        e.bag.set(name, value);\n      } catch {\n        throw new Error(`'@${scope}.${name}' is read-only`);\n      }\n      return;\n    }\n    const n = name.toLowerCase();\n    if (!this.foreignWritable(e, n)) throw new Error(`'@${scope}.${name}' is read-only`);\n    e.resolver.set!(n, value);\n  }\n\n  private foreignWritable(e: ForeignScope, name: string): boolean {\n    if (!e.resolver.set) return false;                 // no setter => read-only scope\n    return e.decls.get(name)?.writable ?? e.scopeWritable;\n  }\n\n  /** Examiner rows across every scope with a declared surface: owned bags\n   *  first, then declared foreign scopes (values read through, writability\n   *  reflecting the resolver). Opaque foreign scopes are not listed. */\n  listProperties(): ({ scope: string } & PropertyRow)[] {\n    const out: ({ scope: string } & PropertyRow)[] = [];\n    for (const [token, e] of this.scopes) {\n      if (e.kind === \"owned\") {\n        for (const row of e.bag.rows()) out.push({ scope: token, ...row });\n      } else {\n        for (const d of e.decls.values()) {\n          out.push({\n            scope: token,\n            ...rowFor(d, e.resolver.get(d.name.toLowerCase()), this.foreignWritable(e, d.name.toLowerCase())),\n          });\n        }\n      }\n    }\n    return out;\n  }\n\n  /**\n   * Build the `EvalContext` expr's `evaluate` consumes: owned scopes as static\n   * bags, foreign scopes as their resolvers. `host` carries dialect-function\n   * callbacks (PRNG, tag lookups) and is passed through untouched.\n   */\n  toEvalContext(host?: Record<string, unknown>): EvalContext {\n    const scopes: EvalContext[\"scopes\"] = {};\n    for (const [token, e] of this.scopes) {\n      scopes[token] = e.kind === \"owned\" ? e.bag.values : e.resolver;\n    }\n    // The quality channel (quality.md): declared here once, so a host that\n    // registers a quality gets ordering comparisons and advance() with no\n    // further wiring. Only added when a quality exists, so contexts stay\n    // byte-identical for products that declare none.\n    const qualities = this.qualityLadders();\n    return qualities.size === 0 ? { scopes, host } : {\n      scopes, host,\n      qualities: (scope, name) => qualities.get(scope)?.get(name.toLowerCase()),\n    };\n  }\n\n  /** Every quality declaration's ladder, keyed scope token then name. */\n  private qualityLadders(): Map<string, Map<string, readonly string[]>> {\n    const out = new Map<string, Map<string, readonly string[]>>();\n    for (const [token, e] of this.scopes) {\n      const decls = e.kind === \"owned\" ? e.bag.declarations() : [...e.decls.values()];\n      for (const d of decls) {\n        if (d.type !== \"quality\" || d.stages === undefined) continue;\n        let m = out.get(token);\n        if (!m) { m = new Map(); out.set(token, m); }\n        m.set(d.name.toLowerCase(), d.stages);\n      }\n    }\n    return out;\n  }\n\n  /**\n   * Build the `ExpressionSchema` expr's validator consumes. Scopes with no\n   * declarations are **omitted** (opaque - references into them are not flagged);\n   * declared scopes contribute their property types for validation.\n   */\n  toSchema(): ExpressionSchema {\n    const properties = new Map<string, Map<string, { type: PropertyType; enumValues?: string[]; stages?: string[] }>>();\n    for (const [token, e] of this.scopes) {\n      const decls = e.kind === \"owned\" ? e.bag.declarations() : [...e.decls.values()];\n      if (decls.length === 0) continue;\n      const m = new Map<string, { type: PropertyType; enumValues?: string[]; stages?: string[] }>();\n      for (const d of decls) m.set(d.name.toLowerCase(), {\n        type: d.type, enumValues: d.values,\n        ...(d.stages !== undefined ? { stages: d.stages } : {}),\n      });\n      properties.set(token, m);\n    }\n    return { properties };\n  }\n\n  /** Serialize **owned** scopes only (foreign scopes are host-owned,\n   *  host-saved), as bare bags - the 0.1.x shape, kept stable so existing\n   *  consumers' save formats are untouched. A product embedding the\n   *  versioned cross-product shape uses `saveFragment`. */\n  save(): Record<string, Record<string, ScalarValue>> {\n    const out: Record<string, Record<string, ScalarValue>> = {};\n    for (const [token, e] of this.scopes) if (e.kind === \"owned\") out[token] = e.bag.save();\n    return out;\n  }\n\n  /** Restore owned-scope values from a `save` blob. Unknown/foreign scopes\n   *  are ignored. */\n  load(blob: Record<string, Record<string, ScalarValue>>): void {\n    for (const [token, vals] of Object.entries(blob)) {\n      const e = this.scopes.get(token);\n      if (e?.kind === \"owned\") e.bag.load(vals);\n    }\n  }\n\n  /** The versioned owned-state fragment (the one serialisation shape both\n   *  product families' save envelopes embed when they adopt the kernel;\n   *  design/engine-runtimes.md 3.1). `save()` wrapped with a version stamp. */\n  saveFragment(): OwnedStateFragment {\n    return { version: SAVE_FRAGMENT_VERSION, scopes: this.save() };\n  }\n\n  /** Restore from a versioned fragment; an unsupported version throws. */\n  loadFragment(fragment: OwnedStateFragment): void {\n    if (fragment.version !== SAVE_FRAGMENT_VERSION) {\n      throw new Error(`unsupported owned-state fragment version ${fragment.version} (supported: ${SAVE_FRAGMENT_VERSION})`);\n    }\n    this.load(fragment.scopes);\n  }\n\n  private assertFree(token: string): void {\n    if (this.scopes.has(token)) throw new Error(`scope '@${token}' is already registered`);\n  }\n}\n\nfunction defaultFor(d: ScopeDeclaration): ScalarValue {\n  if (d.default !== undefined) return d.default;\n  switch (d.type) {\n    case \"boolean\": return false;\n    case \"number\": return 0;\n    case \"string\": return \"\";\n    case \"enum\": return d.values?.[0] ?? \"\";\n    case \"flags\": return [];\n    // A quality starts at the first rung of its ladder.\n    case \"quality\": return d.stages?.[0] ?? \"\";\n  }\n}\n"]}

package/package.json

@@ -1,12 +1,22 @@
 {
   "name": "@wildwinter/scoperegistry",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Scope registry / runtime state container for @wildwinter/expr: owned property scopes + foreign (host-resolved) scopes, save/load, and the scopeRegistrySpec interop format. Produces the EvalContext and ExpressionSchema that expr consumes.",
   "type": "module",
   "license": "MIT",
   "author": "Ian Thomas",
-  "repository": { "type": "git", "url": "git+https://github.com/wildwinter/expr.git", "directory": "packages/scoperegistry" },
-  "keywords": ["expression", "scope", "registry", "state", "wildwinter"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wildwinter/expr.git",
+    "directory": "packages/scoperegistry"
+  },
+  "keywords": [
+    "expression",
+    "scope",
+    "registry",
+    "state",
+    "wildwinter"
+  ],
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -17,7 +27,11 @@
       "require": "./dist/index.cjs"
     }
   },
-  "files": ["dist", "README.md", "LICENSE"],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "sideEffects": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -31,6 +45,6 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
-    "@wildwinter/expr": "^0.3.0"
+    "@wildwinter/expr": "^0.4.0"
   }
 }