@storylet-studio/runtime 0.8.2 → 0.9.1

package/dist/index.js

@@ -3,12 +3,16 @@ import { deserialiseAst, evaluate } from "@wildwinter/expr";
 import { matchedSpecificity } from "@wildwinter/expr-specificity";
 import { storyletsDialect, NEVER_PLAYED } from "@storylet-studio/dialect";
 import {
+  BUNDLE_SCHEMAS,
   PLACE_GROUP,
+  allTagGroups,
   ambiguousValueAddressMessage,
   effectiveGameId,
+  groupsOfBox,
   isHoleRef,
   parseHoleRef,
-  valueAddresses
+  valueAddresses,
+  zoneQualifiedValueAddressMessage
 } from "@storylet-studio/model";
 import { SAVE_SCHEMA, SAVE_SCHEMA_V1 } from "@storylet-studio/model";
 import { PropertyBag as StateBag, ScopeRegistry } from "@wildwinter/scoperegistry";
@@ -17,7 +21,7 @@ import { PropertyBag as StateBag, ScopeRegistry } from "@wildwinter/scoperegistr
 import { makePrng, shuffleInPlace } from "@wildwinter/expr";
 
 // src/engine.ts
-var tagKey = (groupId, tagId) => `${groupId}${tagId}`;
+var tagKey = (boxId, groupId, tagId) => `${boxId}${groupId}${tagId}`;
 var cardIsShared = (card, deckShared) => card.shared ?? deckShared;
 var sharedCap = (card) => card.sharedCopies ?? card.copies ?? 1;
 var OWNER = "Storylet Engine";
@@ -74,11 +78,12 @@ var isShared = (scope, d) => d.shared ?? SCOPE_DEFAULT_SHARED[scope];
 var sharedHalf = (scope, decls) => decls.filter((d) => isShared(scope, d));
 var flowHalf = (scope, decls) => decls.filter((d) => !isShared(scope, d));
 var OWNED_SCOPES = ["box", "deck", "hand", "value"];
+var emptyOwnerIndex = () => ({ gameId: /* @__PURE__ */ new Map(), id: /* @__PURE__ */ new Map(), repeated: /* @__PURE__ */ new Map(), zoneQualified: /* @__PURE__ */ new Map() });
 var emptyOwnerIndexes = () => ({
-  box: { gameId: /* @__PURE__ */ new Map(), id: /* @__PURE__ */ new Map(), repeated: /* @__PURE__ */ new Map() },
-  deck: { gameId: /* @__PURE__ */ new Map(), id: /* @__PURE__ */ new Map(), repeated: /* @__PURE__ */ new Map() },
-  hand: { gameId: /* @__PURE__ */ new Map(), id: /* @__PURE__ */ new Map(), repeated: /* @__PURE__ */ new Map() },
-  value: { gameId: /* @__PURE__ */ new Map(), id: /* @__PURE__ */ new Map(), repeated: /* @__PURE__ */ new Map() }
+  box: emptyOwnerIndex(),
+  deck: emptyOwnerIndex(),
+  hand: emptyOwnerIndex(),
+  value: emptyOwnerIndex()
 });
 var indexOwner = (index, entity) => {
   const gameId = effectiveGameId(entity);
@@ -90,6 +95,7 @@ var indexValueOwners = (index, bundle) => {
   for (const [id, segment] of addresses.print) index.gameId.set(id, segment);
   for (const [segment, id] of addresses.accept) index.id.set(segment, id);
   for (const [gameId, candidates] of addresses.repeated) index.repeated.set(gameId, candidates);
+  for (const [segment, zone] of addresses.zoneQualified) index.zoneQualified.set(segment, zone);
 };
 var handDeclsOf = (internals, hand) => {
   if (hand.template !== void 0) {
@@ -101,6 +107,8 @@ var addressOf = (internals, kind, id) => `${kind}.${internals.owners[kind].gameI
 var resolveOwner = (internals, kind, segment) => {
   const candidates = internals.owners[kind].repeated.get(segment);
   if (candidates !== void 0) return { ambiguous: candidates };
+  const zone = internals.owners[kind].zoneQualified.get(segment);
+  if (zone !== void 0) return { zone };
   const byGameId = internals.owners[kind].id.get(segment);
   if (byGameId !== void 0) return { id: byGameId, legacy: false };
   if (internals.owners[kind].gameId.has(segment)) return { id: segment, legacy: true };
@@ -110,6 +118,7 @@ var ownerOrThrow = (internals, kind, segment, name) => {
   const owner = resolveOwner(internals, kind, segment);
   if (owner === void 0) throw new Error(`no ${kind} store "${segment}"`);
   if ("ambiguous" in owner) throw new Error(ambiguousValueAddressMessage(segment, name, owner.ambiguous));
+  if ("zone" in owner) throw new Error(zoneQualifiedValueAddressMessage(segment, owner.zone, name));
   return owner;
 };
 var legacyAddressMessage = (internals, kind, segment, name) => `"${kind}.${segment}.${name}" names the ${kind} by its internal id; write "${addressOf(internals, kind, segment)}.${name}". The internal-id form is refused after the next release.`;
@@ -127,9 +136,12 @@ var buildPartition = (internals, half) => {
     hand: new Map(b.boxes.flatMap((box) => box.hands.map(
       (hand) => [hand.id, bagFromDecls(half("hand", handDeclsOf(internals, hand)), at("hand", hand.id))]
     ))),
-    value: new Map(b.boxes.flatMap((box) => box.tagGroups.flatMap((group) => group.tags.map(
+    // Every box's tags, then the project map's zones ONCE (design/project-
+    // map-contract.md 3.3): a zone is one bag per partition, whichever boxes'
+    // hands are dealt to it.
+    value: new Map(allTagGroups(b).flatMap((group) => group.tags.map(
       (tag) => [tag.id, bagFromDecls(half("value", tag.properties ?? []), at("value", tag.id))]
-    ))))
+    )))
   };
 };
 var partitionValues = (p) => ({
@@ -246,6 +258,68 @@ function finishReport(bundle, saved, flows, draft) {
     retypedProperties
   };
 }
+var refuseUnreadableBundle = (bundle) => {
+  const schema = bundle.schema;
+  if (typeof schema !== "string" || !BUNDLE_SCHEMAS.includes(schema)) {
+    throw new Error(`unsupported bundle schema: ${String(schema)} (this runtime reads ${BUNDLE_SCHEMAS.join(" and ")})`);
+  }
+  const problems = [];
+  const map = bundle.map?.group;
+  const mapName = map !== void 0 ? effectiveGameId(map) : void 0;
+  if (map !== void 0 && mapName === PLACE_GROUP) {
+    problems.push(`the project map's tag group is called "${PLACE_GROUP}", which is reserved for a box's own hands`);
+  }
+  const boxTags = /* @__PURE__ */ new Map();
+  for (const box of bundle.boxes) {
+    for (const group of box.tagGroups) {
+      for (const tag of group.tags) {
+        const gameId = effectiveGameId(tag);
+        if (!boxTags.has(gameId)) boxTags.set(gameId, { box: effectiveGameId(box), group: effectiveGameId(group) });
+      }
+    }
+  }
+  for (const tag of map?.tags ?? []) {
+    const zone = effectiveGameId(tag);
+    const clash = boxTags.get(zone);
+    if (clash !== void 0) {
+      problems.push(`the project map's zone "${zone}" has the name of tag "${zone}" in box "${clash.box}", group "${clash.group}", so "value.${zone}.<name>" would name two things`);
+    }
+  }
+  for (const box of bundle.boxes) {
+    const boxName = effectiveGameId(box);
+    if (box.usesMap === true) {
+      if (map === void 0) {
+        problems.push(`box "${boxName}" uses the project map, but the bundle has no map`);
+        continue;
+      }
+      const twin = box.tagGroups.find((g) => effectiveGameId(g) === mapName);
+      if (twin !== void 0) {
+        problems.push(`box "${boxName}" uses the project map and declares its own tag group "${mapName}", the map's name`);
+      }
+      continue;
+    }
+    if (map === void 0) continue;
+    const names = (where) => {
+      problems.push(`box "${boxName}" is not on the project map, but ${where} names the map's tag group "${mapName}"`);
+    };
+    for (const deck of box.decks) {
+      for (const card of deck.cards) {
+        if (card.tags?.[map.id] !== void 0) names(`card "${effectiveGameId(card)}"`);
+      }
+    }
+    for (const template of box.handTemplates) {
+      if (template.bindings?.[map.id] !== void 0 || template.chooses?.includes(map.id) === true) {
+        names(`hand template "${effectiveGameId(template)}"`);
+      }
+    }
+    for (const hand of box.hands) {
+      if (hand.chosen?.[map.id] !== void 0 || hand.rule?.bindings?.[map.id] !== void 0) {
+        names(`hand "${effectiveGameId(hand)}"`);
+      }
+    }
+  }
+  if (problems.length > 0) throw new Error(`bundle refused: ${problems.join("; ")}`);
+};
 var Engine = class _Engine {
   internals;
   seed;
@@ -262,6 +336,7 @@ var Engine = class _Engine {
    *  hotSwap puts this engine back exactly as it was. */
   sharedMounts = [];
   constructor(bundle, opts = {}) {
+    refuseUnreadableBundle(bundle);
     this.creationOptions = opts;
     this.seed = opts.seed ?? 0;
     this.onReplacedFlow = opts.onReplacedFlow;
@@ -345,6 +420,10 @@ var Engine = class _Engine {
         indexOwner(internals.owners.hand, hand);
       }
     }
+    if (bundle.map !== void 0) {
+      internals.groupsById.set(bundle.map.group.id, { group: bundle.map.group });
+      if (bundle.map.group.required === true) internals.requiredGroups.add(bundle.map.group.id);
+    }
     this.initLadders();
     const declSet = (half) => ({
       story: half("story", bundle.story.properties),
@@ -355,9 +434,9 @@ var Engine = class _Engine {
       hand: new Map(bundle.boxes.flatMap((box) => box.hands.map(
         (hand) => [hand.id, half("hand", handDeclsOf(internals, hand))]
       ))),
-      value: new Map(bundle.boxes.flatMap((box) => box.tagGroups.flatMap((group) => group.tags.map(
+      value: new Map(allTagGroups(bundle).flatMap((group) => group.tags.map(
         (tag) => [tag.id, half("value", tag.properties ?? [])]
-      ))))
+      )))
     });
     internals.flowDecls = declSet(flowHalf);
     internals.sharedDecls = declSet(sharedHalf);
@@ -458,6 +537,7 @@ var Engine = class _Engine {
       }
       for (const hand of box.hands) internals.ladders.hand.set(hand.id, grab(handDeclsOf(internals, hand)));
     }
+    for (const tag of b.map?.group.tags ?? []) internals.ladders.value.set(tag.id, grab(tag.properties));
     const any = (m) => [...m.values()].some((x) => x.size > 0);
     internals.hasQualities = internals.ladders.world.size > 0 || internals.ladders.story.size > 0 || any(internals.ladders.box) || any(internals.ladders.deck) || any(internals.ladders.value) || any(internals.ladders.hand);
   }
@@ -781,11 +861,35 @@ var Engine = class _Engine {
     return structuredClone({
       schema: SAVE_SCHEMA,
       content: this.internals.bundle.content,
-      ...this.internals.ownsRegistry ? { registry: this.internals.registry.save() } : {},
+      ...this.internals.ownsRegistry ? { registry: this.registrySection() } : {},
       shared: { spent: [...this.spent].sort() },
       flows: Object.fromEntries([...this.flowsById].map(([id, flow]) => [id, flow.snapshot(false)]))
     });
   }
+  /** The registry's values in CANONICAL order, the order a load rebuilds them
+   *  in: the engine-wide keys as the constructor registered them, then each
+   *  flow's keys in `flows()` order (each flow's own registration order), then
+   *  anything else the registry holds (values still waiting for a key), as the
+   *  registry lists it. The registry itself lists keys in registration order,
+   *  and a flow replaced in place (`open()` above keeps its slot in
+   *  `flowsById`) re-registers its keys at the END, so `openFlow("a");
+   *  openFlow("b"); openFlow("a")` saved b's keys before a's while a load
+   *  rebuilt a's first: the same run, different `.storyletsave` bytes, and a
+   *  save loaded and saved again no longer equal to itself. It is the
+   *  2026-08-29 rule carried into the section save@2 moved the per-flow values
+   *  to (2026-10-01). Order does not matter on READ (`partitionsFromSections`
+   *  sorts by key shape), so a save written in the old order loads as before. */
+  registrySection() {
+    const all = this.internals.registry.save();
+    const out = {};
+    const take = (key) => {
+      if (Object.prototype.hasOwnProperty.call(all, key) && !Object.prototype.hasOwnProperty.call(out, key)) out[key] = all[key];
+    };
+    for (const { key } of this.sharedMounts) take(key);
+    for (const flow of this.flowsById.values()) for (const key of flow.registeredKeys()) take(key);
+    for (const key of Object.keys(all)) take(key);
+    return out;
+  }
   /** ONE flow's blob, to park a visit that is walking away: the same shape
    *  the envelope carries per flow, and the same shape `openFlow`'s `restore`
    *  option takes back (design/engine-server.md 4.1). Saving the whole
@@ -1115,9 +1219,16 @@ var Flow = class {
   /** Tag group names are box-scoped: two boxes may name a group the same way
    *  (schema 1 - boxes namespace their groups), so a name is only ever
    *  resolved inside the box being asked, never bundle-wide. Ids are
-   *  project-unique and accepted here too, still confined to the box. */
+   *  project-unique and accepted here too, still confined to the box.
+   *
+   *  A box on the project map sees ONE namespace: its own groups, then the
+   *  map's group (design/project-map-contract.md 3.1). A box that has not
+   *  opted in does not see the map's name at all, so a peek naming it there
+   *  is the ordinary unknown-group refusal. Own groups first is stated for
+   *  determinism only: a bundle that loads never has the two share a name. */
   groupInBox(box, ref) {
-    return box.tagGroups.find((g) => effectiveGameId(g) === ref) ?? box.tagGroups.find((g) => g.id === ref);
+    const groups = groupsOfBox(this.internals.bundle, box);
+    return groups.find((g) => effectiveGameId(g) === ref) ?? groups.find((g) => g.id === ref);
   }
   /** Fold one play into the indexes. O(the card's tags), not O(the log). */
   indexPlay(record) {
@@ -1127,7 +1238,7 @@ var Flow = class {
     if (!entry) return;
     for (const [groupId, tagIds] of Object.entries(entry.card.tags ?? {})) {
       for (const tagId of tagIds) {
-        const key = tagKey(groupId, tagId);
+        const key = tagKey(entry.box.id, groupId, tagId);
         this.tagPlayCount.set(key, (this.tagPlayCount.get(key) ?? 0) + 1);
         this.lastPlayInTag.set(key, record);
       }
@@ -1143,8 +1254,10 @@ var Flow = class {
     for (const record of this.playLog) this.indexPlay(record);
   }
   /** `box` is the box whose ask is being evaluated: the play-history
-   *  functions take a bare group name, so it resolves there (a card's tags
-   *  reference its own box's group, which keeps the counts box-local).
+   *  functions take a bare group name, so it resolves there, and they count
+   *  only that box's own plays (the box is in the index key). That was
+   *  automatic while every group was a box's; a project-map zone is shared,
+   *  and its history is still not (design/project-map-contract.md 3.7, D7).
    *  History is THIS flow's: countPlayed answers "have I done this". */
   /** One host per box, built once.
    *
@@ -1169,7 +1282,7 @@ var Flow = class {
     const keyOf = (group, tag) => {
       const found = this.groupInBox(box, group);
       const t = found?.tags.find((v) => v.gameId === tag);
-      return found && t ? tagKey(found.id, t.id) : void 0;
+      return found && t ? tagKey(box.id, found.id, t.id) : void 0;
     };
     const since = (record) => {
       const entry = this.internals.cardsByGameId.get(record.card);
@@ -1376,7 +1489,7 @@ var Flow = class {
    * is what says otherwise.
    */
   bindStateGroups(box, boundTags, askNames) {
-    for (const group of box.tagGroups) {
+    for (const group of groupsOfBox(this.internals.bundle, box)) {
       if (group.boundBy === void 0 || boundTags.has(group.id)) continue;
       const ref = /^@(world|story)\.([a-z][a-z0-9_-]*)$/.exec(group.boundBy);
       if (!ref) {
@@ -2035,7 +2148,7 @@ var Flow = class {
 };
 
 // src/describe.ts
-import { effectiveGameId as effectiveGameId2, isHoleRef as isHoleRef2 } from "@storylet-studio/model";
+import { effectiveGameId as effectiveGameId2, groupsOfBox as groupsOfBox2, isHoleRef as isHoleRef2 } from "@storylet-studio/model";
 var summarise = (decls) => decls.map((d) => ({
   name: d.name,
   type: d.type,
@@ -2051,12 +2164,12 @@ var handDecls = (hand, box) => {
   }
   return hand.properties ?? [];
 };
-var movableHoles = (hand, box) => {
+var movableHoles = (bundle, hand, box) => {
   const filled = hand.template !== void 0 ? hand.chosen : hand.rule?.bindings;
   const out = [];
   for (const [groupId, value] of Object.entries(filled ?? {})) {
     if (!isHoleRef2(value)) continue;
-    const group = box.tagGroups.find((g) => g.id === groupId);
+    const group = groupsOfBox2(bundle, box).find((g) => g.id === groupId);
     if (group === void 0) continue;
     out.push({ group: effectiveGameId2(group), from: value });
   }
@@ -2081,6 +2194,7 @@ function describeBundle(bundle) {
     boxes.push({
       gameId: boxGameId,
       ...box.title !== void 0 ? { title: box.title } : {},
+      ...box.usesMap === true ? { usesMap: true } : {},
       ranking: { specificity: box.ranking.specificity },
       ...box.turn !== void 0 ? { turn: { seconds: box.turn.seconds } } : {},
       ...durableCardCount(box) > 0 ? { durableCards: durableCardCount(box) } : {},
@@ -2104,7 +2218,7 @@ function describeBundle(bundle) {
     totals.tagGroups += box.tagGroups.length;
     for (const hand of box.hands) {
       const template = hand.template !== void 0 ? box.handTemplates.find((t) => t.id === hand.template) : void 0;
-      const movable = movableHoles(hand, box);
+      const movable = movableHoles(bundle, hand, box);
       hands.push({
         gameId: effectiveGameId2(hand),
         ...hand.title !== void 0 ? { title: hand.title } : {},
@@ -2133,6 +2247,15 @@ function describeBundle(bundle) {
       }
     }
   }
+  const map = bundle.map;
+  if (map !== void 0) {
+    const group = effectiveGameId2(map.group);
+    for (const tag of map.group.tags) {
+      const decls = tag.properties ?? [];
+      if (decls.length > 0) properties.push({ scope: "tag", owner: effectiveGameId2(tag), group, properties: summarise(decls) });
+    }
+    totals.tagGroups += 1;
+  }
   return {
     identity: {
       schema: bundle.schema,
@@ -2145,13 +2268,16 @@ function describeBundle(bundle) {
     boxes,
     hands,
     properties,
-    maps: (bundle.maps ?? []).map((map) => ({
-      box: map.box,
-      group: map.group,
-      zones: map.zones.length,
-      backgrounds: map.backgrounds?.length ?? 0,
-      sites: map.sites?.length ?? 0
-    }))
+    ...map !== void 0 ? {
+      map: {
+        group: effectiveGameId2(map.group),
+        tags: map.group.tags.map((tag) => effectiveGameId2(tag)),
+        boxes: bundle.boxes.filter((box) => box.usesMap === true).map((box) => effectiveGameId2(box)),
+        zones: map.geometry?.zones.length ?? 0,
+        backgrounds: map.geometry?.backgrounds?.length ?? 0,
+        sites: Object.fromEntries(Object.entries(map.geometry?.sites ?? {}).map(([box, sites]) => [box, sites.length]))
+      }
+    } : {}
   };
 }
 export {