@patterkit/runtime 0.12.1 → 0.14.0

package/CHANGELOG.md

@@ -33,6 +33,54 @@ version number always means the same runtime behaviour. This package is versione
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-09-24
+
+### Added
+
+- **Other engines' scopes, with no setting.** A Patter line can name another engine's game-wide scope from the family's shared list (`@story.act` in a condition, an effect, or a `{@story.act}` slot) in any project. It is opaque to the compiler, recorded in the bundle (`externalScopes`), and never self-backed. Content that names one runs only where that engine is on the same registry: without it, `openFlow` and `loadGame` refuse before anything changes (`this content names @story, which no engine on this registry registered: give every engine the game's one registry`), and a write to a scope another engine has since removed fails naming the scope instead of landing in `@patter`.
+
+### Changed
+
+- **One registry per game.** Every property bag the engine holds now lives in a `ScopeRegistry`
+  (`@wildwinter/scoperegistry` 0.7.0): `@patter` under `patter`, and each flow's and scene's bag
+  under a key starting `patter/`. A new `registry` option takes the game's own registry, shared
+  with any other engine in the game; without one the engine makes its own and acts as its own game,
+  so a single-engine game needs no change.
+- **The save is version 3.** `saveGame()` holds what is not a property (cursors, PRNGs, visit
+  counts, selector cursors). An engine built without a registry also carries that registry's values
+  under `registry`, so one call is still the whole game; an engine given the game's registry leaves
+  them to the game, which saves the registry once. Version 2 saves still load, their values moving
+  into the registry.
+- **A self-backed `@world` is saved.** When the game binds no resolver, `@world` is a property the
+  engine's registry stores, so it rides in the save. A resolver the game binds is still external and
+  never saved. Given the game's registry, the engine self-backs nothing: `@world` is the game's to
+  register there.
+- **Every expression reads every registered scope**, so a condition can test another engine's
+  `@story.act` in a combined game. A token two engines both want fails as the second is built, naming
+  the first.
+- `hotSwap` hands every bag to the replacement engine on the same registry. The engine it replaces is
+  released and its flows are closed. If the restore fails, the fallback engine keeps the shared
+  properties and restarts each flow, where it used to start everything cold.
+
+### Deprecated
+
+- `Engine.save()` / `Engine.load()`, the shared `@patter` values alone. Save the registry instead.
+
+## [0.13.0] - 2026-09-05
+
+### Changed
+
+- **A `writable: false` host declaration is the STORY's promise, and only the story's: the game
+  writes it.** `Engine.setProperty` / `Flow.setProperty` are the game's surfaces, so they now write a
+  read-only `@world` property whether it is self-backed or bound to a resolver; an effect that writes
+  one is refused exactly as before, with the same sentence. Until now the runtime refused every
+  caller alike, so a game could not advance its own clock through the engine and a Patterplay
+  coverage driver on such a property killed the run - which is how both this project and the
+  Storylet Engine found it, on the same day, in different content
+  (from-storylets/host-writes-to-read-only-world). The rule now lives in the shared kernel
+  (`@wildwinter/scoperegistry` ^0.6.0, an explicit host authority on `set`), so both products mean
+  the same thing by the flag.
+
 ## [0.12.1] - 2026-09-04
 
 ### Changed

package/README.md

@@ -40,9 +40,11 @@ for (;;) {
 }
 ```
 
-`new Engine(bundle, options)` takes `{ rng?, seed?, locale?, world?, replayPromptOnChoose?, closedCaptions? }`:
+`new Engine(bundle, options)` takes `{ rng?, seed?, locale?, world?, registry?, replayPromptOnChoose?, closedCaptions? }`:
 - `world` is the host's resolver for `@world` properties (World Properties): `{ get(name), set?(name, value) }`.
-  Omit it and the runtime self-backs `@world` from the declared defaults.
+  Omit it and the runtime self-backs `@world` from the declared defaults, as a property it saves.
+- `registry` is the game's one `ScopeRegistry` (from `@wildwinter/scoperegistry`), holding every
+  engine's properties. Omit it and the engine makes its own. See *One registry per game* below.
 - `locale` plays a non-default language (embedded localisation; an IDs-only bundle ignores it).
 - A string the active locale is missing falls back to the default-locale source,
   flagged `<Untranslated: {id}> {source}` so a partial translation is impossible to miss.
@@ -90,7 +92,24 @@ The release zip's `demos/` folder holds two working references (in the repo:
 
 ## Save / load
 
-`engine.saveGame()` returns a JSON-serialisable snapshot of the whole game (shared
-state, visit counts, every live flow); `engine.loadGame(blob)` restores it.
-[@patterkit/play-helpers](../play-helpers) wraps these as `serializeState` /
-`deserializeState` with a tagged envelope.
+`engine.saveGame()` returns a JSON-serialisable snapshot of the whole game (visit counts,
+selector cursors, every live flow, and, for an engine built without a registry, every property
+value); `engine.loadGame(blob)` restores it. Saves from before property values moved into the
+registry (version 2) still load. [@patterkit/play-helpers](../play-helpers) wraps these as
+`serializeState` / `deserializeState` with a tagged envelope.
+
+## One registry per game
+
+A game has one `ScopeRegistry` holding every property from every engine, except values the game
+keeps itself and lends through a resolver, and saves it once. Pass it as `registry`:
+
+```ts
+import { ScopeRegistry } from "@wildwinter/scoperegistry";
+
+const registry = new ScopeRegistry().defineOwned("world", worldDeclarations, { owner: "Game" });
+const engine = new Engine(bundle, { registry });
+const save = { registry: registry.save(), patter: engine.saveGame() };   // saveGame() holds no values now
+```
+
+The engine registers `@patter` under `patter` and every per-flow and per-scene bag under a key
+starting `patter/`; `@world` is the game's to register. Loading works in either order.