@storylet-studio/model 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -23,7 +23,10 @@ __export(index_exports, {
   BOX_SCHEMA: () => BOX_SCHEMA,
   BUNDLE_EXTENSION: () => BUNDLE_EXTENSION,
   BUNDLE_SCHEMA: () => BUNDLE_SCHEMA,
+  CONTRACTS_DIR: () => CONTRACTS_DIR,
+  CONTRACT_SCHEMA: () => CONTRACT_SCHEMA,
   DECK_SCHEMA: () => DECK_SCHEMA,
+  DEFAULT_PLAY_RUNG: () => DEFAULT_PLAY_RUNG,
   FURNITURE_COLOURS: () => FURNITURE_COLOURS,
   HANDS_SCHEMA: () => HANDS_SCHEMA,
   NOTES_SCHEMA: () => NOTES_SCHEMA,
@@ -37,12 +40,15 @@ __export(index_exports, {
   SPATIAL: () => SPATIAL,
   TAGS_SCHEMA: () => TAGS_SCHEMA,
   VIEW_SCHEMA: () => VIEW_SCHEMA,
+  ambiguousValueAddressMessage: () => ambiguousValueAddressMessage,
   backgroundsOf: () => backgroundsOf,
   bindHand: () => bindHand,
   bundleAssetPath: () => bundleAssetPath,
   byDisplayOrder: () => byDisplayOrder,
   centroid: () => centroid,
   commentsOf: () => commentsOf,
+  contractPropertyPath: () => contractPropertyPath,
+  contractPropertyType: () => contractPropertyType,
   droppedRect: () => droppedRect,
   effectiveGameId: () => effectiveGameId,
   framesOf: () => framesOf,
@@ -52,6 +58,7 @@ __export(index_exports, {
   handBinding: () => handBinding,
   inferDeclFromWrite: () => inferDeclFromWrite,
   isCaseOnlyPropertyName: () => import_expr.isCaseOnlyPropertyName,
+  isHoleRef: () => isHoleRef,
   isSpatial: () => isSpatial,
   isValidGameId: () => isValidGameId,
   isValidPropertyName: () => import_expr.isValidPropertyName,
@@ -59,6 +66,7 @@ __export(index_exports, {
   markOf: () => markOf,
   marksOn: () => marksOn,
   openThreadCounts: () => openThreadCounts,
+  parseHoleRef: () => parseHoleRef,
   pointInPolygon: () => pointInPolygon,
   polygonBounds: () => polygonBounds,
   polygonOf: () => polygonOf,
@@ -67,7 +75,9 @@ __export(index_exports, {
   spatialOf: () => spatialOf,
   stacked: () => stacked,
   threadsFor: () => threadsFor,
+  turnSpan: () => turnSpan,
   unbindHand: () => unbindHand,
+  valueAddresses: () => valueAddresses,
   withBackgrounds: () => withBackgrounds,
   withPolygon: () => withPolygon,
   withSpatialGroup: () => withSpatialGroup,
@@ -467,6 +477,41 @@ function effectiveGameId(entity) {
   const fromTitle = entity.title ? gameIdify(entity.title) : "";
   return fromTitle || entity.id;
 }
+function valueAddresses(bundle) {
+  const tags = [];
+  for (const box of bundle.boxes) {
+    const boxGameId = effectiveGameId(box);
+    for (const group of box.tagGroups) {
+      for (const tag of group.tags) {
+        const gameId = effectiveGameId(tag);
+        tags.push({ id: tag.id, gameId, qualified: `${boxGameId}/${gameId}` });
+      }
+    }
+  }
+  const forms = /* @__PURE__ */ new Map();
+  for (const tag of tags) {
+    const list = forms.get(tag.gameId) ?? [];
+    if (!list.includes(tag.qualified)) list.push(tag.qualified);
+    forms.set(tag.gameId, list);
+  }
+  const print = /* @__PURE__ */ new Map();
+  const accept = /* @__PURE__ */ new Map();
+  const repeated = /* @__PURE__ */ new Map();
+  for (const tag of tags) {
+    const candidates = forms.get(tag.gameId) ?? [tag.qualified];
+    const ambiguous = candidates.length > 1;
+    print.set(tag.id, ambiguous ? tag.qualified : tag.gameId);
+    if (!accept.has(tag.qualified)) accept.set(tag.qualified, tag.id);
+    if (!ambiguous && !accept.has(tag.gameId)) accept.set(tag.gameId, tag.id);
+    if (ambiguous) repeated.set(tag.gameId, candidates);
+  }
+  return { print, accept, repeated };
+}
+function ambiguousValueAddressMessage(segment, name, candidates) {
+  const forms = candidates.map((q) => `"value.${q}.${name}"`);
+  const list = forms.length <= 1 ? forms[0] ?? "" : `${forms.slice(0, -1).join(", ")} or ${forms[forms.length - 1]}`;
+  return `"value.${segment}.${name}" names a tag in ${candidates.length} boxes; write ${list}`;
+}
 function freeGameId(base, taken) {
   let gameId = base;
   for (let n = 2; taken.has(gameId); n++) gameId = `${base}-${n}`;
@@ -480,8 +525,32 @@ function freeTitle(base, taken) {
   for (let n = 2; taken.has(gameIdify(title)); n++) title = `${base} ${n}`;
   return title;
 }
+function turnSpan(turns, seconds, long = false) {
+  const total = Math.max(0, Math.round(turns * seconds));
+  const say = (n, short, one, many) => long ? `${n} ${n === 1 ? one : many}` : `${n} ${short}`;
+  if (total < 60) return long ? say(total, "s", "second", "seconds") : `${total}s`;
+  if (total < 3600) {
+    const minutes = total % 60 === 0 ? total / 60 : Math.round(total / 6) / 10;
+    return say(minutes, "min", "minute", "minutes");
+  }
+  let hours = Math.floor(total / 3600);
+  let rest = Math.round(total % 3600 / 60);
+  if (rest === 60) {
+    hours += 1;
+    rest = 0;
+  }
+  const said = say(hours, "hr", "hour", "hours");
+  return rest === 0 ? said : `${said} ${say(rest, "min", "minute", "minutes")}`;
+}
 var PLACE_GROUP = "place";
+var HOLE_REF = /^@(hand|world|story)\.([a-z][a-z0-9_-]*)$/;
+var isHoleRef = (value) => value.startsWith("@");
+var parseHoleRef = (value) => {
+  const m = HOLE_REF.exec(value);
+  return m === null ? void 0 : { scope: m[1], name: m[2] };
+};
 var BUNDLE_SCHEMA = "storylets/bundle@0";
+var DEFAULT_PLAY_RUNG = "solo";
 var SAVE_SCHEMA = "storylets/save@1";
 var SAVEFILE_SCHEMA = "storylets/savefile@1";
 var PROJECT_FOLDER_EXTENSION = ".storylets";
@@ -504,8 +573,16 @@ var SHARD_EXTENSIONS = {
    *  id-keyed (design/annotation.md). Documentation NOTES used to share this
    *  file and were retired: `purpose` already says why a thing exists, and
    *  Patterpad's typed routing has no destination here. */
-  notes: ".storyletnotes"
+  notes: ".storyletnotes",
+  /** An installation contract: what a VENUE depends on, one file per
+   *  installation in `contracts/` at the project root
+   *  (design/engine-server.md 4.11). Its own shard, and its own folder, for the
+   *  walkthrough's reason (Reboot 7.5, S4): a different owner, a different
+   *  change rate, and a merge that must never collide with the author's edits,
+   *  since the server always wins its own file. */
+  contract: ".storyletcontract"
 };
+var CONTRACTS_DIR = "contracts";
 var PROJECT_SCHEMA = "storylets/project@0";
 var BOX_SCHEMA = "storylets/box@0";
 var TAGS_SCHEMA = "storylets/tags@0";
@@ -513,13 +590,19 @@ var HANDS_SCHEMA = "storylets/hands@0";
 var DECK_SCHEMA = "storylets/deck@0";
 var VIEW_SCHEMA = "storylets/view@0";
 var NOTES_SCHEMA = "storylets/notes@0";
+var CONTRACT_SCHEMA = "storylets/contract@0";
+var contractPropertyPath = (p) => typeof p === "string" ? p : p.path;
+var contractPropertyType = (p) => typeof p === "string" ? void 0 : p.type;
 var FURNITURE_COLOURS = ["paper", "amber", "sage", "sky", "rose", "slate"];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BOX_SCHEMA,
   BUNDLE_EXTENSION,
   BUNDLE_SCHEMA,
+  CONTRACTS_DIR,
+  CONTRACT_SCHEMA,
   DECK_SCHEMA,
+  DEFAULT_PLAY_RUNG,
   FURNITURE_COLOURS,
   HANDS_SCHEMA,
   NOTES_SCHEMA,
@@ -533,12 +616,15 @@ var FURNITURE_COLOURS = ["paper", "amber", "sage", "sky", "rose", "slate"];
   SPATIAL,
   TAGS_SCHEMA,
   VIEW_SCHEMA,
+  ambiguousValueAddressMessage,
   backgroundsOf,
   bindHand,
   bundleAssetPath,
   byDisplayOrder,
   centroid,
   commentsOf,
+  contractPropertyPath,
+  contractPropertyType,
   droppedRect,
   effectiveGameId,
   framesOf,
@@ -548,6 +634,7 @@ var FURNITURE_COLOURS = ["paper", "amber", "sage", "sky", "rose", "slate"];
   handBinding,
   inferDeclFromWrite,
   isCaseOnlyPropertyName,
+  isHoleRef,
   isSpatial,
   isValidGameId,
   isValidPropertyName,
@@ -555,6 +642,7 @@ var FURNITURE_COLOURS = ["paper", "amber", "sage", "sky", "rose", "slate"];
   markOf,
   marksOn,
   openThreadCounts,
+  parseHoleRef,
   pointInPolygon,
   polygonBounds,
   polygonOf,
@@ -563,7 +651,9 @@ var FURNITURE_COLOURS = ["paper", "amber", "sage", "sky", "rose", "slate"];
   spatialOf,
   stacked,
   threadsFor,
+  turnSpan,
   unbindHand,
+  valueAddresses,
   withBackgrounds,
   withPolygon,
   withSpatialGroup,

package/dist/index.d.cts

@@ -409,6 +409,25 @@ interface PropertyDecl {
      * the game's own state, always engine-level, never per-flow.
      */
     shared?: boolean;
+    /**
+     * The durability axis (design/engine-server.md 4.2), valid wherever `shared`
+     * is valid and orthogonal to it: `shared` says whose value this is WITHIN a
+     * run, `durable` says whether the value survives the run at all. A durable
+     * shared property is the installation's memory ("trolls defeated since we
+     * opened"); a durable per-flow one is the player's pocket (visits,
+     * allegiance, what they earned).
+     *
+     * INERT TO THE RUNTIME. The engine partitions by `shared` alone and never
+     * reads this. Durability is what the SERVER does at a run boundary: it reads
+     * the declarations, lifts the durable values out of the partitions before the
+     * world restarts, and writes them back into the fresh engine afterwards,
+     * entirely through `getProperty` / `setProperty`.
+     *
+     * On a `@world` declaration the flag is a validation error, for the reason
+     * `shared` is: @world is the game's own state, and how long the game keeps it
+     * is the game's business.
+     */
+    durable?: boolean;
     purpose?: string;
 }
 /** A card-template field (box-defined). Data for the host; the engine never
@@ -433,6 +452,32 @@ declare function effectiveGameId(entity: {
     title?: string;
     id: string;
 }): string;
+/** The three answers a value address needs, all derived from the bundle. */
+interface ValueAddresses {
+    /** Tag internal id -> the owner segment an address PRINTS for it. */
+    print: Map<string, string>;
+    /** Every owner segment a value address ACCEPTS -> the tag's internal id.
+     *  Holds the qualified form for every tag and the short form only for a
+     *  gameId no other tag shares. */
+    accept: Map<string, string>;
+    /** A tag gameId more than one box uses -> its qualified forms, in bundle
+     *  order. Empty for the overwhelming majority of projects, and what a
+     *  refusal lists. */
+    repeated: Map<string, string[]>;
+}
+/** The owner segment of every tag in the bundle, both ways round. */
+declare function valueAddresses(bundle: {
+    boxes: readonly {
+        id: string;
+        gameId?: string;
+        title?: string;
+        tagGroups: readonly TagGroup[];
+    }[];
+}): ValueAddresses;
+/** What an ambiguous short-form value address is told: the candidates, in
+ *  full, because "that names two tags" without them leaves a host reading a
+ *  bundle it did not write to find out which boxes. */
+declare function ambiguousValueAddressMessage(segment: string, name: string, candidates: readonly string[]): string;
 /**
  * The first free gameId of the form `base`, `base-2`, `base-3`, ... not already
  * in `taken`.
@@ -473,6 +518,17 @@ declare function byDisplayOrder<T extends {
     order?: number;
 }>(items: readonly T[]): T[];
 declare function freeTitle(base: string, taken: ReadonlySet<string>): string;
+/**
+ * A count of a TIMED box's turns, said as time (design/engine-server.md 4.8):
+ * `turnSpan(30, 60)` is "30 min", and `turnSpan(30, 60, true)` is "30 minutes".
+ *
+ * One definition, because the conversion appears wherever a designer might
+ * otherwise have to do it in their head: the card editor's Redraw field, the
+ * box page, the Board's advance buttons, and the coverage report's turn
+ * budget. Two of those want the unit spelled out and two want it short, which
+ * is the whole of `long`.
+ */
+declare function turnSpan(turns: number, seconds: number, long?: boolean): string;
 interface Outcome<E> {
     id: string;
     gameId?: string;
@@ -528,6 +584,21 @@ interface Card<E> {
      *  common case writes one number and "five in the world, one to a customer"
      *  is `copies: 1, sharedCopies: 5`. */
     sharedCopies?: number;
+    /** Does this card's `redraw: "never"` spend survive the run
+     *  (design/engine-server.md 4.2)? Absent takes the deck's flag, set here it
+     *  overrides the deck, exactly as `shared` does. `shared` decides who a
+     *  spend counts for WITHIN a run; this decides whether it outlives one.
+     *
+     *  Only `"never"` crosses the run boundary, for the reason only `"never"`
+     *  crosses the flow boundary (shared-scarcity 9.3.2): a finite cooldown is
+     *  an absolute turn of a box clock, and the clock resets with the run. On
+     *  any other redraw the flag is a compile warning.
+     *
+     *  INERT TO THE RUNTIME, like the declaration flag: the server lifts the
+     *  durable spends at run end (per-flow ones from the flow's `never`
+     *  cooldowns, shared ones from the engine's spent set) and puts them back
+     *  through `openFlow(id, { restore })` and `markTaken`. */
+    durable?: boolean;
     /** Card-template data: field name -> value, validated at publish. */
     fields?: Record<string, ScalarValue>;
     outcomes: Outcome<E>[];
@@ -543,6 +614,11 @@ interface Deck<E> {
      *  in it is shared unless the card says otherwise. The container is where
      *  Patter puts its own shared-memory flag, and the deck is our container. */
     shared?: boolean;
+    /** Every `redraw: "never"` card in this pile is spent for good, past the end
+     *  of the run, unless the card says otherwise (design/engine-server.md 4.2).
+     *  The container carries the flag for the reason `shared` is carried here:
+     *  a pile is what an author reaches for when a rule is true of all of it. */
+    durable?: boolean;
     properties: PropertyDecl[];
     cards: Card<E>[];
 }
@@ -638,6 +714,30 @@ interface TagGroup {
  *  half of that answer. `home` was a metaphor an author had to learn, and it
  *  leaked into hand-edited shards and the docs. */
 declare const PLACE_GROUP = "place";
+/** The scopes a movable hole may be filled from (design/engine-server.md 4.6):
+ *  the two `boundBy` already allows, plus `@hand` - the asking hand's OWN
+ *  declared property, resolved before tag composition so a movable hole can
+ *  never depend on the tags it is choosing. */
+type HoleRefScope = "hand" | "story" | "world";
+/** A parsed hole reference: `@hand.zone` -> `{ scope: "hand", name: "zone" }`. */
+interface HoleRef {
+    scope: HoleRefScope;
+    name: string;
+}
+/**
+ * Is this `chosen` / binding value MEANT as a property reference rather than a
+ * tag id?
+ *
+ * The test is the leading `@` alone, deliberately: a value that starts with
+ * one and does not parse is a mistyped reference, which the compiler should
+ * name as such, not a tag id that happens to look odd. Tag ids never begin
+ * with `@`.
+ */
+declare const isHoleRef: (value: string) => boolean;
+/** Parse a hole reference, or undefined when it is not one. The on-disk form
+ *  stays a plain string, so the canonical serialiser and the shard merge need
+ *  no change at all: a hole is still one group name against one value. */
+declare const parseHoleRef: (value: string) => HoleRef | undefined;
 /** A declared kind of hand (schema 2.6): live-inherited, author-side only,
  *  never called from game code. One condition governs every instance. */
 interface HandTemplate<E> {
@@ -649,9 +749,12 @@ interface HandTemplate<E> {
      *  position). Merges as a per-item value, so id-sorted storage stays
      *  merge-clean (Reboot 7.4). */
     order?: number;
-    /** Fixed tag bindings: tag group id -> tag id. */
+    /** Fixed tag bindings: tag group id -> tag id. Literal tags only: what a
+     *  template FIXES is the same for every instance, and a hole that moves is
+     *  the instance's own business (`Hand.chosen`, 4.6). */
     bindings?: Record<string, string>;
-    /** The holes: tag group ids each instance fills (one tag each). */
+    /** The holes: tag group ids each instance fills (one tag each, or one
+     *  property reference: 4.6). */
     chooses?: string[];
     /** Shared availability condition, ANDed in (schema 3.1); evaluated per
      *  instance against that instance's composed @hand. */
@@ -663,6 +766,15 @@ interface HandTemplate<E> {
 }
 /** A standalone hand's inline rule (schema 2.6): owned by the hand. */
 interface HandRule<E> {
+    /**
+     * Tag group id -> tag id, or a PROPERTY REFERENCE (`"@hand.zone"`,
+     * `"@story.where"`, `"@world.place"`) the runtime resolves at ask time
+     * (design/engine-server.md 4.6, the hand that moves). Still a plain string
+     * on disk, so the canonical serialiser and the merge are untouched; what
+     * widened is the meaning, and `parseHoleRef` is where it is read.
+     *
+     * `place` is never fillable this way: it is the hand's own name, not an axis.
+     */
     bindings?: Record<string, string>;
     condition?: E;
     slots: number | "unbounded";
@@ -679,7 +791,17 @@ interface Hand<E> {
     purpose?: string;
     /** Hand template id (not gameId). */
     template?: string;
-    /** Template instances: tag group id -> tag id, one per `chooses` hole. */
+    /**
+     * Template instances: tag group id -> tag id, one per `chooses` hole.
+     *
+     * A value may instead be a PROPERTY REFERENCE (`"@hand.zone"`,
+     * `"@story.where"`, `"@world.place"`), which makes the hole MOVABLE: the
+     * runtime resolves the reference at ask time and binds the hole to the tag
+     * the value names, so moving the Elder to the forest is `setProperty` and
+     * nothing else (design/engine-server.md 4.6). Still a plain string on disk,
+     * so the canonical serialiser and the shard merge need no change; read it
+     * with `parseHoleRef`.
+     */
     chosen?: Record<string, string>;
     /** Standalone hands: the inline rule. */
     rule?: HandRule<E>;
@@ -704,6 +826,25 @@ interface Box<E> {
     ranking: {
         specificity: boolean;
     };
+    /**
+     * A TIMED box: its clock counts real time, one turn every `seconds` of the
+     * run (design/engine-server.md 4.8). Absent is the ordinary box, whose turn
+     * is a play.
+     *
+     * Two things follow, and only two. In the ENGINE, a play in this box
+     * defaults to advancing nothing: `settings.playAdvancesTurns` does not
+     * apply, so a designer cannot declare the convention and then forget to
+     * switch play-advance off. Everywhere else it is what the tools SAY: the
+     * host ticks the box (the runtime has no clock and gains none here), and a
+     * card's `redraw: N` reads as N x `seconds`, which the editors, the bundle
+     * inspectors and the coverage report spell out rather than leaving a
+     * designer to know that 30 meant minutes.
+     *
+     * The number itself is inert to the runtime, which never reads it.
+     */
+    turn?: {
+        seconds: number;
+    };
     /** The card template: what every card in this box carries. */
     fields: FieldDecl[];
     properties: PropertyDecl[];
@@ -723,6 +864,30 @@ interface BundleContent {
 interface BundleSettings {
     playAdvancesTurns: number;
 }
+/**
+ * The play ladder (design/engine-server.md 4.10): how much of itself
+ * Storyletter shows this project, in one setting with three rungs rather than
+ * a set of toggles, because the features nest.
+ *
+ *   solo   one player, one flow: no sharing, no durability, no venue features
+ *   shared several players over one world: sharing appears
+ *   venue  a production: nothing is hidden
+ *
+ * EDITOR-SIDE ONLY. It stays in the project shard beside `coverage` and
+ * `export` and is never compiled: a solo project plays on the same Engine as a
+ * venue one. Hidden is hidden rather than disabled, so going DOWN a rung is
+ * refused when the project already contains what the rung would hide, and a
+ * hand-edited shard above its rung is a compile warning.
+ */
+type PlayRung = "solo" | "shared" | "venue";
+/** The default rung: a project shard that says nothing is a solo game. */
+declare const DEFAULT_PLAY_RUNG: PlayRung;
+/** The project shard's settings block: what the bundle carries, plus the
+ *  authoring-side play rung that it does not. */
+interface ProjectSettings extends BundleSettings {
+    /** The play ladder rung (see `PlayRung`). Absent = "solo". */
+    play?: PlayRung;
+}
 /**
  * A map that a bundle was asked to carry: one spatial tag group's geometry,
  * flattened for a host to draw (design/graphical-views.md 2, "The map MAY ship").
@@ -737,9 +902,16 @@ interface BundleSettings {
  * names it passes to `peek`. There is nothing here to strip either, which is why
  * `metadata: "stripped"` needs no special case: no titles, no purposes.
  *
- * Sites are deliberately NOT here. A site is where an author parked a hand while
- * working, held in the view sidecar precisely because it is not content, and a
- * host that wants to place a hand already has its zone from the compiled binding.
+ * SITES ARE HERE, which reverses a ruling. Until 2026-09-05 this comment said
+ * they were deliberately not: a site was where an author parked a hand while
+ * working, held in the view sidecar precisely because it was not content, and a
+ * host that wanted to place a hand had its zone from the compiled binding. That
+ * held for a game, where a hand's zone is its only real-world meaning. It does
+ * not hold for a physical experience (design/engine-server.md 4.3), where the
+ * position IS content: it is where the kiosk stands, and a producer's map is
+ * simply wrong without it. The alternative was a second file beside the bundle,
+ * which would cost a format the inspectors do not read and would put the view
+ * sidecar in the shipping path by the back door.
  */
 interface BundleMap {
     /** The owning box, by gameId (tag groups are box-scoped). */
@@ -755,6 +927,16 @@ interface BundleMap {
     /** Background pictures, back to front, as bundle-relative paths. Hidden ones
      *  do not ship: what an author put away is not something to spring on a host. */
     backgrounds?: BundleBackground[];
+    /** Where the placed hands stand on this map, by hand gameId, sorted by that
+     *  gameId so the bytes do not depend on authoring order. A hand nobody has
+     *  placed has no entry, and a map with no placed hand has no key at all. The
+     *  zone a site sits in is NOT repeated here: the hand's own binding is what
+     *  the runtime deals from, and a second copy could only go on to disagree. */
+    sites?: {
+        hand: string;
+        x: number;
+        y: number;
+    }[];
 }
 /** One shipped picture. `locked` and `hidden` are authoring state and do not
  *  travel; the draw order is the array order. */
@@ -844,6 +1026,75 @@ interface SaveEnvelope {
     shared: SharedSave;
     flows: Record<string, FlowSave>;
 }
+/** One card that a restore refused to put back on the board.
+ *
+ *  `vanished` and `hand-vanished` are the edit's doing (the card, or the hand
+ *  it sat in, is no longer in the bundle). `claimed-elsewhere` is only ever a
+ *  single-flow restore into a LIVE engine: the card is shared, and the other
+ *  open flows already hold every copy the world has. */
+interface LoadEviction {
+    flow: string;
+    hand: string;
+    card: string;
+    reason: "vanished" | "hand-vanished" | "claimed-elsewhere";
+}
+/** One property the restore could not put back as it was. `flow` names the
+ *  flow whose half it belongs to; absent, it is the shared half.
+ *
+ *  `path` is the engine's property address, spelled exactly as
+ *  `Flow.listProperties()` / `Engine.listProperties()` print it and exactly as
+ *  `getProperty` and `setProperty` accept it: `story.<name>` for the story
+ *  scope, `<scope>.<ownerGameId>.<name>` for the box, deck, hand and tag
+ *  scopes. No `@`, which belongs to the expression language and not to an
+ *  address.
+ *
+ *  The owner segment is its GAMEID (design/engine-server.md 4.4), the name it
+ *  is called by everywhere else, so an operator reading a hot-swap report can
+ *  paste the address straight into `setProperty`. An owner the build no longer
+ *  has keeps the id the save carried: there is no gameId left to give it,
+ *  which is the rule the eviction list above has always used. */
+interface LoadProperty {
+    flow?: string;
+    path: string;
+}
+/** What a load or a flow restore would do that is not a plain restore
+ *  (design/engine-server.md 4.9). Arrays are sorted, so two runtimes given the
+ *  same save and bundle produce the same bytes; `flows` alone keeps the
+ *  envelope's own order, because a caller re-takes its handles in it. */
+interface LoadReport {
+    /** No drift and nothing dropped, defaulted or retyped: the save goes back
+     *  exactly as it was. `flows` is not a divergence and does not count. */
+    exact: boolean;
+    project: string;
+    /** Drift when the two differ; reported, never refused. */
+    version: {
+        saved: string;
+        bundle: string;
+    };
+    /** Drift when the two differ; reported, never refused. */
+    hash: {
+        saved: string;
+        bundle: string;
+    };
+    /** The flows this restores, in the order it restores them. */
+    flows: string[];
+    evicted: LoadEviction[];
+    /** Cooldowns held for cards the bundle no longer has. */
+    droppedCooldowns: {
+        flow: string;
+        card: string;
+    }[];
+    /** Shared `redraw: "never"` entries for cards the bundle no longer has. */
+    droppedSpent: string[];
+    /** In the save, not declared any more. */
+    droppedProperties: LoadProperty[];
+    /** Declared, not in the save: it takes the declaration's default. */
+    defaultedProperties: LoadProperty[];
+    /** In the save, still declared, but the saved value no longer fits the
+     *  declaration (its type changed, or an enum value / quality stage was
+     *  edited away). It takes the declaration's default. */
+    retypedProperties: LoadProperty[];
+}
 /** The .storyletsave FILE: the HOST's file, not the engine's - the engine's
  *  envelope plus, when the host keeps one, its @world container. This is
  *  "host saves its container once, each engine saves its own envelope"
@@ -888,7 +1139,18 @@ declare const SHARD_EXTENSIONS: {
      *  file and were retired: `purpose` already says why a thing exists, and
      *  Patterpad's typed routing has no destination here. */
     readonly notes: ".storyletnotes";
+    /** An installation contract: what a VENUE depends on, one file per
+     *  installation in `contracts/` at the project root
+     *  (design/engine-server.md 4.11). Its own shard, and its own folder, for the
+     *  walkthrough's reason (Reboot 7.5, S4): a different owner, a different
+     *  change rate, and a merge that must never collide with the author's edits,
+     *  since the server always wins its own file. */
+    readonly contract: ".storyletcontract";
 };
+/** Where the installation contracts live, relative to the project root. The
+ *  directory is the registry, as it is for a box's decks: a contract exists
+ *  because its file exists. */
+declare const CONTRACTS_DIR = "contracts";
 declare const PROJECT_SCHEMA = "storylets/project@0";
 declare const BOX_SCHEMA = "storylets/box@0";
 declare const TAGS_SCHEMA = "storylets/tags@0";
@@ -898,6 +1160,68 @@ declare const VIEW_SCHEMA = "storylets/view@0";
 /** The comment sidecar's schema. Still called "notes" on disk: the file already
  *  held both, and renaming it would break every project for no gain. */
 declare const NOTES_SCHEMA = "storylets/notes@0";
+declare const CONTRACT_SCHEMA = "storylets/contract@0";
+/**
+ * What one installation depends on, written by the venue's server and read by
+ * `validate` (design/engine-server.md 4.11).
+ *
+ * NOT THE AUTHOR'S FILE. A venue is provisioned against names - the hands its
+ * stations deal, the boxes its scheduler ticks, the properties its clocks drive,
+ * the fields its crew read - and the server writes them out so the tools that
+ * already gate a build can refuse a rename before it reaches the venue. A
+ * project playing at two venues has two of these. The author never edits one,
+ * and today, with no server built, a project either receives one or has none.
+ *
+ * NEVER COMPILED. It is project-side config like `coverage` and `export`: the
+ * server does not need its own contract handed back, it needs the bundle to
+ * still honour it.
+ *
+ * BY GAMEID throughout, because a gameId is the name that crosses the project's
+ * border and an internal id is authoring identity.
+ */
+interface ContractShard {
+    schema: typeof CONTRACT_SCHEMA;
+    /** The installation this contract speaks for. One file per installation, and
+     *  two files naming the same one is an error. */
+    installation: string;
+    /** Who wrote it, for a human reading the file ("Storylet Server 0.1.0"). */
+    by?: string;
+    /** The server's revision when it wrote this. */
+    revision?: number;
+    /** Hands a station is bound to, by gameId: they may not be renamed or
+     *  removed. */
+    hands?: string[];
+    /** Timed boxes the venue's scheduler ticks, by box gameId, with the turn unit
+     *  in SECONDS it was provisioned against. A box whose unit changed means every
+     *  rest on its cards changed meaning. */
+    boxes?: Record<string, {
+        turn: number;
+    }>;
+    /** Property paths the venue reads or drives, in the engine's own address
+     *  grammar with no `@` ("world.time_wall", "story.visits"), which is how
+     *  `listProperties()` prints them. */
+    properties?: ContractProperty[];
+    /** Card-template field names the crew and the bridges read. */
+    fields?: string[];
+}
+/**
+ * One contracted property.
+ *
+ * A bare path is the common form and the one the spec's example writes. The
+ * object form adds the TYPE the venue was provisioned against, which is the only
+ * way `validate` can catch the break that costs a producer most: a property that
+ * still exists under the same name and now holds something else. A server that
+ * knows the type should write the object form; a hand-written contract may say
+ * only the path and get the existence check alone.
+ */
+type ContractProperty = string | {
+    path: string;
+    type?: PropertyType;
+};
+/** The path a contracted property names, whichever form it was written in. */
+declare const contractPropertyPath: (p: ContractProperty) => string;
+/** The type a contracted property was provisioned against, when it says. */
+declare const contractPropertyType: (p: ContractProperty) => PropertyType | undefined;
 /** A point in a canvas's own coordinates. */
 interface ViewPoint {
     x: number;
@@ -1017,7 +1341,7 @@ interface ProjectShard {
         name: string;
         version: string;
     };
-    settings: BundleSettings;
+    settings: ProjectSettings;
     /** Coverage drivers + argument domains (authoring/testing config; stays
      *  out of the compiled bundle). */
     coverage?: CoverageConfig;
@@ -1087,6 +1411,10 @@ interface BoxShard {
         ranking: {
             specificity: boolean;
         };
+        /** Declares a timed box (see `Box.turn`); compiled through unchanged. */
+        turn?: {
+            seconds: number;
+        };
         fields: FieldDecl[];
         properties: PropertyDecl[];
     };
@@ -1112,6 +1440,8 @@ interface DeckShard {
         condition?: string;
         /** Scarce across flows: see Deck.shared. */
         shared?: boolean;
+        /** Its `redraw: "never"` cards are spent past the run: see Deck.durable. */
+        durable?: boolean;
         /** Authored display order within the box (sparse; see BoxShard). */
         order?: number;
         properties: PropertyDecl[];
@@ -1119,4 +1449,4 @@ interface DeckShard {
     cards: Card<string>[];
 }
 
-export { BOX_SCHEMA, BUNDLE_EXTENSION, BUNDLE_SCHEMA, type Box, type BoxMap, type BoxShard, type Bundle, type BundleBackground, type BundleContent, type BundleMap, type BundleSettings, type CanvasFurniture, type Card, type Comment, type CommentMark, type CommentMessage, type CoverageConfig, type CoverageDriver, DECK_SCHEMA, type Deck, type DeckCanvas, type DeckShard, FURNITURE_COLOURS, type FieldDecl, type FlowSave, type Frame, type FurnitureColour, HANDS_SCHEMA, type Hand, type HandBinding, type HandRule, type HandTemplate, type HandsShard, NOTES_SCHEMA, type NotesShard, type Outcome, PLACE_GROUP, PROJECT_FOLDER_EXTENSION, PROJECT_SCHEMA, type PlayRecord, type Polygon, type ProjectShard, type PropertyBag, type PropertyDecl, type PropertyType, type PropsPartition, type Rect, type RedrawPolicy, SAVEFILE_SCHEMA, SAVE_SCHEMA, SHARD_EXTENSIONS, SPATIAL, type SaveEnvelope, type SaveFile, type SharedSave, type SpatialBackground, type SpatialGroup, type StackMove, type Stacked, TAGS_SCHEMA, type Tag, type TagGroup, type TagsShard, VIEW_SCHEMA, type ViewPoint, type ViewShard, backgroundsOf, bindHand, bundleAssetPath, byDisplayOrder, centroid, commentsOf, droppedRect, effectiveGameId, framesOf, freeGameId, freeTitle, gameIdify, handBinding, inferDeclFromWrite, isSpatial, isValidGameId, labelPoint, markOf, marksOn, openThreadCounts, pointInPolygon, polygonBounds, polygonOf, restack, spatialOf, stacked, threadsFor, unbindHand, withBackgrounds, withPolygon, withSpatialGroup, withZ, zOf, zoneAt, zonesAt };
+export { BOX_SCHEMA, BUNDLE_EXTENSION, BUNDLE_SCHEMA, type Box, type BoxMap, type BoxShard, type Bundle, type BundleBackground, type BundleContent, type BundleMap, type BundleSettings, CONTRACTS_DIR, CONTRACT_SCHEMA, type CanvasFurniture, type Card, type Comment, type CommentMark, type CommentMessage, type ContractProperty, type ContractShard, type CoverageConfig, type CoverageDriver, DECK_SCHEMA, DEFAULT_PLAY_RUNG, type Deck, type DeckCanvas, type DeckShard, FURNITURE_COLOURS, type FieldDecl, type FlowSave, type Frame, type FurnitureColour, HANDS_SCHEMA, type Hand, type HandBinding, type HandRule, type HandTemplate, type HandsShard, type HoleRef, type HoleRefScope, type LoadEviction, type LoadProperty, type LoadReport, NOTES_SCHEMA, type NotesShard, type Outcome, PLACE_GROUP, PROJECT_FOLDER_EXTENSION, PROJECT_SCHEMA, type PlayRecord, type PlayRung, type Polygon, type ProjectSettings, type ProjectShard, type PropertyBag, type PropertyDecl, type PropertyType, type PropsPartition, type Rect, type RedrawPolicy, SAVEFILE_SCHEMA, SAVE_SCHEMA, SHARD_EXTENSIONS, SPATIAL, type SaveEnvelope, type SaveFile, type SharedSave, type SpatialBackground, type SpatialGroup, type StackMove, type Stacked, TAGS_SCHEMA, type Tag, type TagGroup, type TagsShard, VIEW_SCHEMA, type ValueAddresses, type ViewPoint, type ViewShard, ambiguousValueAddressMessage, backgroundsOf, bindHand, bundleAssetPath, byDisplayOrder, centroid, commentsOf, contractPropertyPath, contractPropertyType, droppedRect, effectiveGameId, framesOf, freeGameId, freeTitle, gameIdify, handBinding, inferDeclFromWrite, isHoleRef, isSpatial, isValidGameId, labelPoint, markOf, marksOn, openThreadCounts, parseHoleRef, pointInPolygon, polygonBounds, polygonOf, restack, spatialOf, stacked, threadsFor, turnSpan, unbindHand, valueAddresses, withBackgrounds, withPolygon, withSpatialGroup, withZ, zOf, zoneAt, zonesAt };

package/dist/index.d.ts

@@ -409,6 +409,25 @@ interface PropertyDecl {
      * the game's own state, always engine-level, never per-flow.
      */
     shared?: boolean;
+    /**
+     * The durability axis (design/engine-server.md 4.2), valid wherever `shared`
+     * is valid and orthogonal to it: `shared` says whose value this is WITHIN a
+     * run, `durable` says whether the value survives the run at all. A durable
+     * shared property is the installation's memory ("trolls defeated since we
+     * opened"); a durable per-flow one is the player's pocket (visits,
+     * allegiance, what they earned).
+     *
+     * INERT TO THE RUNTIME. The engine partitions by `shared` alone and never
+     * reads this. Durability is what the SERVER does at a run boundary: it reads
+     * the declarations, lifts the durable values out of the partitions before the
+     * world restarts, and writes them back into the fresh engine afterwards,
+     * entirely through `getProperty` / `setProperty`.
+     *
+     * On a `@world` declaration the flag is a validation error, for the reason
+     * `shared` is: @world is the game's own state, and how long the game keeps it
+     * is the game's business.
+     */
+    durable?: boolean;
     purpose?: string;
 }
 /** A card-template field (box-defined). Data for the host; the engine never
@@ -433,6 +452,32 @@ declare function effectiveGameId(entity: {
     title?: string;
     id: string;
 }): string;
+/** The three answers a value address needs, all derived from the bundle. */
+interface ValueAddresses {
+    /** Tag internal id -> the owner segment an address PRINTS for it. */
+    print: Map<string, string>;
+    /** Every owner segment a value address ACCEPTS -> the tag's internal id.
+     *  Holds the qualified form for every tag and the short form only for a
+     *  gameId no other tag shares. */
+    accept: Map<string, string>;
+    /** A tag gameId more than one box uses -> its qualified forms, in bundle
+     *  order. Empty for the overwhelming majority of projects, and what a
+     *  refusal lists. */
+    repeated: Map<string, string[]>;
+}
+/** The owner segment of every tag in the bundle, both ways round. */
+declare function valueAddresses(bundle: {
+    boxes: readonly {
+        id: string;
+        gameId?: string;
+        title?: string;
+        tagGroups: readonly TagGroup[];
+    }[];
+}): ValueAddresses;
+/** What an ambiguous short-form value address is told: the candidates, in
+ *  full, because "that names two tags" without them leaves a host reading a
+ *  bundle it did not write to find out which boxes. */
+declare function ambiguousValueAddressMessage(segment: string, name: string, candidates: readonly string[]): string;
 /**
  * The first free gameId of the form `base`, `base-2`, `base-3`, ... not already
  * in `taken`.
@@ -473,6 +518,17 @@ declare function byDisplayOrder<T extends {
     order?: number;
 }>(items: readonly T[]): T[];
 declare function freeTitle(base: string, taken: ReadonlySet<string>): string;
+/**
+ * A count of a TIMED box's turns, said as time (design/engine-server.md 4.8):
+ * `turnSpan(30, 60)` is "30 min", and `turnSpan(30, 60, true)` is "30 minutes".
+ *
+ * One definition, because the conversion appears wherever a designer might
+ * otherwise have to do it in their head: the card editor's Redraw field, the
+ * box page, the Board's advance buttons, and the coverage report's turn
+ * budget. Two of those want the unit spelled out and two want it short, which
+ * is the whole of `long`.
+ */
+declare function turnSpan(turns: number, seconds: number, long?: boolean): string;
 interface Outcome<E> {
     id: string;
     gameId?: string;
@@ -528,6 +584,21 @@ interface Card<E> {
      *  common case writes one number and "five in the world, one to a customer"
      *  is `copies: 1, sharedCopies: 5`. */
     sharedCopies?: number;
+    /** Does this card's `redraw: "never"` spend survive the run
+     *  (design/engine-server.md 4.2)? Absent takes the deck's flag, set here it
+     *  overrides the deck, exactly as `shared` does. `shared` decides who a
+     *  spend counts for WITHIN a run; this decides whether it outlives one.
+     *
+     *  Only `"never"` crosses the run boundary, for the reason only `"never"`
+     *  crosses the flow boundary (shared-scarcity 9.3.2): a finite cooldown is
+     *  an absolute turn of a box clock, and the clock resets with the run. On
+     *  any other redraw the flag is a compile warning.
+     *
+     *  INERT TO THE RUNTIME, like the declaration flag: the server lifts the
+     *  durable spends at run end (per-flow ones from the flow's `never`
+     *  cooldowns, shared ones from the engine's spent set) and puts them back
+     *  through `openFlow(id, { restore })` and `markTaken`. */
+    durable?: boolean;
     /** Card-template data: field name -> value, validated at publish. */
     fields?: Record<string, ScalarValue>;
     outcomes: Outcome<E>[];
@@ -543,6 +614,11 @@ interface Deck<E> {
      *  in it is shared unless the card says otherwise. The container is where
      *  Patter puts its own shared-memory flag, and the deck is our container. */
     shared?: boolean;
+    /** Every `redraw: "never"` card in this pile is spent for good, past the end
+     *  of the run, unless the card says otherwise (design/engine-server.md 4.2).
+     *  The container carries the flag for the reason `shared` is carried here:
+     *  a pile is what an author reaches for when a rule is true of all of it. */
+    durable?: boolean;
     properties: PropertyDecl[];
     cards: Card<E>[];
 }
@@ -638,6 +714,30 @@ interface TagGroup {
  *  half of that answer. `home` was a metaphor an author had to learn, and it
  *  leaked into hand-edited shards and the docs. */
 declare const PLACE_GROUP = "place";
+/** The scopes a movable hole may be filled from (design/engine-server.md 4.6):
+ *  the two `boundBy` already allows, plus `@hand` - the asking hand's OWN
+ *  declared property, resolved before tag composition so a movable hole can
+ *  never depend on the tags it is choosing. */
+type HoleRefScope = "hand" | "story" | "world";
+/** A parsed hole reference: `@hand.zone` -> `{ scope: "hand", name: "zone" }`. */
+interface HoleRef {
+    scope: HoleRefScope;
+    name: string;
+}
+/**
+ * Is this `chosen` / binding value MEANT as a property reference rather than a
+ * tag id?
+ *
+ * The test is the leading `@` alone, deliberately: a value that starts with
+ * one and does not parse is a mistyped reference, which the compiler should
+ * name as such, not a tag id that happens to look odd. Tag ids never begin
+ * with `@`.
+ */
+declare const isHoleRef: (value: string) => boolean;
+/** Parse a hole reference, or undefined when it is not one. The on-disk form
+ *  stays a plain string, so the canonical serialiser and the shard merge need
+ *  no change at all: a hole is still one group name against one value. */
+declare const parseHoleRef: (value: string) => HoleRef | undefined;
 /** A declared kind of hand (schema 2.6): live-inherited, author-side only,
  *  never called from game code. One condition governs every instance. */
 interface HandTemplate<E> {
@@ -649,9 +749,12 @@ interface HandTemplate<E> {
      *  position). Merges as a per-item value, so id-sorted storage stays
      *  merge-clean (Reboot 7.4). */
     order?: number;
-    /** Fixed tag bindings: tag group id -> tag id. */
+    /** Fixed tag bindings: tag group id -> tag id. Literal tags only: what a
+     *  template FIXES is the same for every instance, and a hole that moves is
+     *  the instance's own business (`Hand.chosen`, 4.6). */
     bindings?: Record<string, string>;
-    /** The holes: tag group ids each instance fills (one tag each). */
+    /** The holes: tag group ids each instance fills (one tag each, or one
+     *  property reference: 4.6). */
     chooses?: string[];
     /** Shared availability condition, ANDed in (schema 3.1); evaluated per
      *  instance against that instance's composed @hand. */
@@ -663,6 +766,15 @@ interface HandTemplate<E> {
 }
 /** A standalone hand's inline rule (schema 2.6): owned by the hand. */
 interface HandRule<E> {
+    /**
+     * Tag group id -> tag id, or a PROPERTY REFERENCE (`"@hand.zone"`,
+     * `"@story.where"`, `"@world.place"`) the runtime resolves at ask time
+     * (design/engine-server.md 4.6, the hand that moves). Still a plain string
+     * on disk, so the canonical serialiser and the merge are untouched; what
+     * widened is the meaning, and `parseHoleRef` is where it is read.
+     *
+     * `place` is never fillable this way: it is the hand's own name, not an axis.
+     */
     bindings?: Record<string, string>;
     condition?: E;
     slots: number | "unbounded";
@@ -679,7 +791,17 @@ interface Hand<E> {
     purpose?: string;
     /** Hand template id (not gameId). */
     template?: string;
-    /** Template instances: tag group id -> tag id, one per `chooses` hole. */
+    /**
+     * Template instances: tag group id -> tag id, one per `chooses` hole.
+     *
+     * A value may instead be a PROPERTY REFERENCE (`"@hand.zone"`,
+     * `"@story.where"`, `"@world.place"`), which makes the hole MOVABLE: the
+     * runtime resolves the reference at ask time and binds the hole to the tag
+     * the value names, so moving the Elder to the forest is `setProperty` and
+     * nothing else (design/engine-server.md 4.6). Still a plain string on disk,
+     * so the canonical serialiser and the shard merge need no change; read it
+     * with `parseHoleRef`.
+     */
     chosen?: Record<string, string>;
     /** Standalone hands: the inline rule. */
     rule?: HandRule<E>;
@@ -704,6 +826,25 @@ interface Box<E> {
     ranking: {
         specificity: boolean;
     };
+    /**
+     * A TIMED box: its clock counts real time, one turn every `seconds` of the
+     * run (design/engine-server.md 4.8). Absent is the ordinary box, whose turn
+     * is a play.
+     *
+     * Two things follow, and only two. In the ENGINE, a play in this box
+     * defaults to advancing nothing: `settings.playAdvancesTurns` does not
+     * apply, so a designer cannot declare the convention and then forget to
+     * switch play-advance off. Everywhere else it is what the tools SAY: the
+     * host ticks the box (the runtime has no clock and gains none here), and a
+     * card's `redraw: N` reads as N x `seconds`, which the editors, the bundle
+     * inspectors and the coverage report spell out rather than leaving a
+     * designer to know that 30 meant minutes.
+     *
+     * The number itself is inert to the runtime, which never reads it.
+     */
+    turn?: {
+        seconds: number;
+    };
     /** The card template: what every card in this box carries. */
     fields: FieldDecl[];
     properties: PropertyDecl[];
@@ -723,6 +864,30 @@ interface BundleContent {
 interface BundleSettings {
     playAdvancesTurns: number;
 }
+/**
+ * The play ladder (design/engine-server.md 4.10): how much of itself
+ * Storyletter shows this project, in one setting with three rungs rather than
+ * a set of toggles, because the features nest.
+ *
+ *   solo   one player, one flow: no sharing, no durability, no venue features
+ *   shared several players over one world: sharing appears
+ *   venue  a production: nothing is hidden
+ *
+ * EDITOR-SIDE ONLY. It stays in the project shard beside `coverage` and
+ * `export` and is never compiled: a solo project plays on the same Engine as a
+ * venue one. Hidden is hidden rather than disabled, so going DOWN a rung is
+ * refused when the project already contains what the rung would hide, and a
+ * hand-edited shard above its rung is a compile warning.
+ */
+type PlayRung = "solo" | "shared" | "venue";
+/** The default rung: a project shard that says nothing is a solo game. */
+declare const DEFAULT_PLAY_RUNG: PlayRung;
+/** The project shard's settings block: what the bundle carries, plus the
+ *  authoring-side play rung that it does not. */
+interface ProjectSettings extends BundleSettings {
+    /** The play ladder rung (see `PlayRung`). Absent = "solo". */
+    play?: PlayRung;
+}
 /**
  * A map that a bundle was asked to carry: one spatial tag group's geometry,
  * flattened for a host to draw (design/graphical-views.md 2, "The map MAY ship").
@@ -737,9 +902,16 @@ interface BundleSettings {
  * names it passes to `peek`. There is nothing here to strip either, which is why
  * `metadata: "stripped"` needs no special case: no titles, no purposes.
  *
- * Sites are deliberately NOT here. A site is where an author parked a hand while
- * working, held in the view sidecar precisely because it is not content, and a
- * host that wants to place a hand already has its zone from the compiled binding.
+ * SITES ARE HERE, which reverses a ruling. Until 2026-09-05 this comment said
+ * they were deliberately not: a site was where an author parked a hand while
+ * working, held in the view sidecar precisely because it was not content, and a
+ * host that wanted to place a hand had its zone from the compiled binding. That
+ * held for a game, where a hand's zone is its only real-world meaning. It does
+ * not hold for a physical experience (design/engine-server.md 4.3), where the
+ * position IS content: it is where the kiosk stands, and a producer's map is
+ * simply wrong without it. The alternative was a second file beside the bundle,
+ * which would cost a format the inspectors do not read and would put the view
+ * sidecar in the shipping path by the back door.
  */
 interface BundleMap {
     /** The owning box, by gameId (tag groups are box-scoped). */
@@ -755,6 +927,16 @@ interface BundleMap {
     /** Background pictures, back to front, as bundle-relative paths. Hidden ones
      *  do not ship: what an author put away is not something to spring on a host. */
     backgrounds?: BundleBackground[];
+    /** Where the placed hands stand on this map, by hand gameId, sorted by that
+     *  gameId so the bytes do not depend on authoring order. A hand nobody has
+     *  placed has no entry, and a map with no placed hand has no key at all. The
+     *  zone a site sits in is NOT repeated here: the hand's own binding is what
+     *  the runtime deals from, and a second copy could only go on to disagree. */
+    sites?: {
+        hand: string;
+        x: number;
+        y: number;
+    }[];
 }
 /** One shipped picture. `locked` and `hidden` are authoring state and do not
  *  travel; the draw order is the array order. */
@@ -844,6 +1026,75 @@ interface SaveEnvelope {
     shared: SharedSave;
     flows: Record<string, FlowSave>;
 }
+/** One card that a restore refused to put back on the board.
+ *
+ *  `vanished` and `hand-vanished` are the edit's doing (the card, or the hand
+ *  it sat in, is no longer in the bundle). `claimed-elsewhere` is only ever a
+ *  single-flow restore into a LIVE engine: the card is shared, and the other
+ *  open flows already hold every copy the world has. */
+interface LoadEviction {
+    flow: string;
+    hand: string;
+    card: string;
+    reason: "vanished" | "hand-vanished" | "claimed-elsewhere";
+}
+/** One property the restore could not put back as it was. `flow` names the
+ *  flow whose half it belongs to; absent, it is the shared half.
+ *
+ *  `path` is the engine's property address, spelled exactly as
+ *  `Flow.listProperties()` / `Engine.listProperties()` print it and exactly as
+ *  `getProperty` and `setProperty` accept it: `story.<name>` for the story
+ *  scope, `<scope>.<ownerGameId>.<name>` for the box, deck, hand and tag
+ *  scopes. No `@`, which belongs to the expression language and not to an
+ *  address.
+ *
+ *  The owner segment is its GAMEID (design/engine-server.md 4.4), the name it
+ *  is called by everywhere else, so an operator reading a hot-swap report can
+ *  paste the address straight into `setProperty`. An owner the build no longer
+ *  has keeps the id the save carried: there is no gameId left to give it,
+ *  which is the rule the eviction list above has always used. */
+interface LoadProperty {
+    flow?: string;
+    path: string;
+}
+/** What a load or a flow restore would do that is not a plain restore
+ *  (design/engine-server.md 4.9). Arrays are sorted, so two runtimes given the
+ *  same save and bundle produce the same bytes; `flows` alone keeps the
+ *  envelope's own order, because a caller re-takes its handles in it. */
+interface LoadReport {
+    /** No drift and nothing dropped, defaulted or retyped: the save goes back
+     *  exactly as it was. `flows` is not a divergence and does not count. */
+    exact: boolean;
+    project: string;
+    /** Drift when the two differ; reported, never refused. */
+    version: {
+        saved: string;
+        bundle: string;
+    };
+    /** Drift when the two differ; reported, never refused. */
+    hash: {
+        saved: string;
+        bundle: string;
+    };
+    /** The flows this restores, in the order it restores them. */
+    flows: string[];
+    evicted: LoadEviction[];
+    /** Cooldowns held for cards the bundle no longer has. */
+    droppedCooldowns: {
+        flow: string;
+        card: string;
+    }[];
+    /** Shared `redraw: "never"` entries for cards the bundle no longer has. */
+    droppedSpent: string[];
+    /** In the save, not declared any more. */
+    droppedProperties: LoadProperty[];
+    /** Declared, not in the save: it takes the declaration's default. */
+    defaultedProperties: LoadProperty[];
+    /** In the save, still declared, but the saved value no longer fits the
+     *  declaration (its type changed, or an enum value / quality stage was
+     *  edited away). It takes the declaration's default. */
+    retypedProperties: LoadProperty[];
+}
 /** The .storyletsave FILE: the HOST's file, not the engine's - the engine's
  *  envelope plus, when the host keeps one, its @world container. This is
  *  "host saves its container once, each engine saves its own envelope"
@@ -888,7 +1139,18 @@ declare const SHARD_EXTENSIONS: {
      *  file and were retired: `purpose` already says why a thing exists, and
      *  Patterpad's typed routing has no destination here. */
     readonly notes: ".storyletnotes";
+    /** An installation contract: what a VENUE depends on, one file per
+     *  installation in `contracts/` at the project root
+     *  (design/engine-server.md 4.11). Its own shard, and its own folder, for the
+     *  walkthrough's reason (Reboot 7.5, S4): a different owner, a different
+     *  change rate, and a merge that must never collide with the author's edits,
+     *  since the server always wins its own file. */
+    readonly contract: ".storyletcontract";
 };
+/** Where the installation contracts live, relative to the project root. The
+ *  directory is the registry, as it is for a box's decks: a contract exists
+ *  because its file exists. */
+declare const CONTRACTS_DIR = "contracts";
 declare const PROJECT_SCHEMA = "storylets/project@0";
 declare const BOX_SCHEMA = "storylets/box@0";
 declare const TAGS_SCHEMA = "storylets/tags@0";
@@ -898,6 +1160,68 @@ declare const VIEW_SCHEMA = "storylets/view@0";
 /** The comment sidecar's schema. Still called "notes" on disk: the file already
  *  held both, and renaming it would break every project for no gain. */
 declare const NOTES_SCHEMA = "storylets/notes@0";
+declare const CONTRACT_SCHEMA = "storylets/contract@0";
+/**
+ * What one installation depends on, written by the venue's server and read by
+ * `validate` (design/engine-server.md 4.11).
+ *
+ * NOT THE AUTHOR'S FILE. A venue is provisioned against names - the hands its
+ * stations deal, the boxes its scheduler ticks, the properties its clocks drive,
+ * the fields its crew read - and the server writes them out so the tools that
+ * already gate a build can refuse a rename before it reaches the venue. A
+ * project playing at two venues has two of these. The author never edits one,
+ * and today, with no server built, a project either receives one or has none.
+ *
+ * NEVER COMPILED. It is project-side config like `coverage` and `export`: the
+ * server does not need its own contract handed back, it needs the bundle to
+ * still honour it.
+ *
+ * BY GAMEID throughout, because a gameId is the name that crosses the project's
+ * border and an internal id is authoring identity.
+ */
+interface ContractShard {
+    schema: typeof CONTRACT_SCHEMA;
+    /** The installation this contract speaks for. One file per installation, and
+     *  two files naming the same one is an error. */
+    installation: string;
+    /** Who wrote it, for a human reading the file ("Storylet Server 0.1.0"). */
+    by?: string;
+    /** The server's revision when it wrote this. */
+    revision?: number;
+    /** Hands a station is bound to, by gameId: they may not be renamed or
+     *  removed. */
+    hands?: string[];
+    /** Timed boxes the venue's scheduler ticks, by box gameId, with the turn unit
+     *  in SECONDS it was provisioned against. A box whose unit changed means every
+     *  rest on its cards changed meaning. */
+    boxes?: Record<string, {
+        turn: number;
+    }>;
+    /** Property paths the venue reads or drives, in the engine's own address
+     *  grammar with no `@` ("world.time_wall", "story.visits"), which is how
+     *  `listProperties()` prints them. */
+    properties?: ContractProperty[];
+    /** Card-template field names the crew and the bridges read. */
+    fields?: string[];
+}
+/**
+ * One contracted property.
+ *
+ * A bare path is the common form and the one the spec's example writes. The
+ * object form adds the TYPE the venue was provisioned against, which is the only
+ * way `validate` can catch the break that costs a producer most: a property that
+ * still exists under the same name and now holds something else. A server that
+ * knows the type should write the object form; a hand-written contract may say
+ * only the path and get the existence check alone.
+ */
+type ContractProperty = string | {
+    path: string;
+    type?: PropertyType;
+};
+/** The path a contracted property names, whichever form it was written in. */
+declare const contractPropertyPath: (p: ContractProperty) => string;
+/** The type a contracted property was provisioned against, when it says. */
+declare const contractPropertyType: (p: ContractProperty) => PropertyType | undefined;
 /** A point in a canvas's own coordinates. */
 interface ViewPoint {
     x: number;
@@ -1017,7 +1341,7 @@ interface ProjectShard {
         name: string;
         version: string;
     };
-    settings: BundleSettings;
+    settings: ProjectSettings;
     /** Coverage drivers + argument domains (authoring/testing config; stays
      *  out of the compiled bundle). */
     coverage?: CoverageConfig;
@@ -1087,6 +1411,10 @@ interface BoxShard {
         ranking: {
             specificity: boolean;
         };
+        /** Declares a timed box (see `Box.turn`); compiled through unchanged. */
+        turn?: {
+            seconds: number;
+        };
         fields: FieldDecl[];
         properties: PropertyDecl[];
     };
@@ -1112,6 +1440,8 @@ interface DeckShard {
         condition?: string;
         /** Scarce across flows: see Deck.shared. */
         shared?: boolean;
+        /** Its `redraw: "never"` cards are spent past the run: see Deck.durable. */
+        durable?: boolean;
         /** Authored display order within the box (sparse; see BoxShard). */
         order?: number;
         properties: PropertyDecl[];
@@ -1119,4 +1449,4 @@ interface DeckShard {
     cards: Card<string>[];
 }
 
-export { BOX_SCHEMA, BUNDLE_EXTENSION, BUNDLE_SCHEMA, type Box, type BoxMap, type BoxShard, type Bundle, type BundleBackground, type BundleContent, type BundleMap, type BundleSettings, type CanvasFurniture, type Card, type Comment, type CommentMark, type CommentMessage, type CoverageConfig, type CoverageDriver, DECK_SCHEMA, type Deck, type DeckCanvas, type DeckShard, FURNITURE_COLOURS, type FieldDecl, type FlowSave, type Frame, type FurnitureColour, HANDS_SCHEMA, type Hand, type HandBinding, type HandRule, type HandTemplate, type HandsShard, NOTES_SCHEMA, type NotesShard, type Outcome, PLACE_GROUP, PROJECT_FOLDER_EXTENSION, PROJECT_SCHEMA, type PlayRecord, type Polygon, type ProjectShard, type PropertyBag, type PropertyDecl, type PropertyType, type PropsPartition, type Rect, type RedrawPolicy, SAVEFILE_SCHEMA, SAVE_SCHEMA, SHARD_EXTENSIONS, SPATIAL, type SaveEnvelope, type SaveFile, type SharedSave, type SpatialBackground, type SpatialGroup, type StackMove, type Stacked, TAGS_SCHEMA, type Tag, type TagGroup, type TagsShard, VIEW_SCHEMA, type ViewPoint, type ViewShard, backgroundsOf, bindHand, bundleAssetPath, byDisplayOrder, centroid, commentsOf, droppedRect, effectiveGameId, framesOf, freeGameId, freeTitle, gameIdify, handBinding, inferDeclFromWrite, isSpatial, isValidGameId, labelPoint, markOf, marksOn, openThreadCounts, pointInPolygon, polygonBounds, polygonOf, restack, spatialOf, stacked, threadsFor, unbindHand, withBackgrounds, withPolygon, withSpatialGroup, withZ, zOf, zoneAt, zonesAt };
+export { BOX_SCHEMA, BUNDLE_EXTENSION, BUNDLE_SCHEMA, type Box, type BoxMap, type BoxShard, type Bundle, type BundleBackground, type BundleContent, type BundleMap, type BundleSettings, CONTRACTS_DIR, CONTRACT_SCHEMA, type CanvasFurniture, type Card, type Comment, type CommentMark, type CommentMessage, type ContractProperty, type ContractShard, type CoverageConfig, type CoverageDriver, DECK_SCHEMA, DEFAULT_PLAY_RUNG, type Deck, type DeckCanvas, type DeckShard, FURNITURE_COLOURS, type FieldDecl, type FlowSave, type Frame, type FurnitureColour, HANDS_SCHEMA, type Hand, type HandBinding, type HandRule, type HandTemplate, type HandsShard, type HoleRef, type HoleRefScope, type LoadEviction, type LoadProperty, type LoadReport, NOTES_SCHEMA, type NotesShard, type Outcome, PLACE_GROUP, PROJECT_FOLDER_EXTENSION, PROJECT_SCHEMA, type PlayRecord, type PlayRung, type Polygon, type ProjectSettings, type ProjectShard, type PropertyBag, type PropertyDecl, type PropertyType, type PropsPartition, type Rect, type RedrawPolicy, SAVEFILE_SCHEMA, SAVE_SCHEMA, SHARD_EXTENSIONS, SPATIAL, type SaveEnvelope, type SaveFile, type SharedSave, type SpatialBackground, type SpatialGroup, type StackMove, type Stacked, TAGS_SCHEMA, type Tag, type TagGroup, type TagsShard, VIEW_SCHEMA, type ValueAddresses, type ViewPoint, type ViewShard, ambiguousValueAddressMessage, backgroundsOf, bindHand, bundleAssetPath, byDisplayOrder, centroid, commentsOf, contractPropertyPath, contractPropertyType, droppedRect, effectiveGameId, framesOf, freeGameId, freeTitle, gameIdify, handBinding, inferDeclFromWrite, isHoleRef, isSpatial, isValidGameId, labelPoint, markOf, marksOn, openThreadCounts, parseHoleRef, pointInPolygon, polygonBounds, polygonOf, restack, spatialOf, stacked, threadsFor, turnSpan, unbindHand, valueAddresses, withBackgrounds, withPolygon, withSpatialGroup, withZ, zOf, zoneAt, zonesAt };

package/dist/index.js

@@ -394,6 +394,41 @@ function effectiveGameId(entity) {
   const fromTitle = entity.title ? gameIdify(entity.title) : "";
   return fromTitle || entity.id;
 }
+function valueAddresses(bundle) {
+  const tags = [];
+  for (const box of bundle.boxes) {
+    const boxGameId = effectiveGameId(box);
+    for (const group of box.tagGroups) {
+      for (const tag of group.tags) {
+        const gameId = effectiveGameId(tag);
+        tags.push({ id: tag.id, gameId, qualified: `${boxGameId}/${gameId}` });
+      }
+    }
+  }
+  const forms = /* @__PURE__ */ new Map();
+  for (const tag of tags) {
+    const list = forms.get(tag.gameId) ?? [];
+    if (!list.includes(tag.qualified)) list.push(tag.qualified);
+    forms.set(tag.gameId, list);
+  }
+  const print = /* @__PURE__ */ new Map();
+  const accept = /* @__PURE__ */ new Map();
+  const repeated = /* @__PURE__ */ new Map();
+  for (const tag of tags) {
+    const candidates = forms.get(tag.gameId) ?? [tag.qualified];
+    const ambiguous = candidates.length > 1;
+    print.set(tag.id, ambiguous ? tag.qualified : tag.gameId);
+    if (!accept.has(tag.qualified)) accept.set(tag.qualified, tag.id);
+    if (!ambiguous && !accept.has(tag.gameId)) accept.set(tag.gameId, tag.id);
+    if (ambiguous) repeated.set(tag.gameId, candidates);
+  }
+  return { print, accept, repeated };
+}
+function ambiguousValueAddressMessage(segment, name, candidates) {
+  const forms = candidates.map((q) => `"value.${q}.${name}"`);
+  const list = forms.length <= 1 ? forms[0] ?? "" : `${forms.slice(0, -1).join(", ")} or ${forms[forms.length - 1]}`;
+  return `"value.${segment}.${name}" names a tag in ${candidates.length} boxes; write ${list}`;
+}
 function freeGameId(base, taken) {
   let gameId = base;
   for (let n = 2; taken.has(gameId); n++) gameId = `${base}-${n}`;
@@ -407,8 +442,32 @@ function freeTitle(base, taken) {
   for (let n = 2; taken.has(gameIdify(title)); n++) title = `${base} ${n}`;
   return title;
 }
+function turnSpan(turns, seconds, long = false) {
+  const total = Math.max(0, Math.round(turns * seconds));
+  const say = (n, short, one, many) => long ? `${n} ${n === 1 ? one : many}` : `${n} ${short}`;
+  if (total < 60) return long ? say(total, "s", "second", "seconds") : `${total}s`;
+  if (total < 3600) {
+    const minutes = total % 60 === 0 ? total / 60 : Math.round(total / 6) / 10;
+    return say(minutes, "min", "minute", "minutes");
+  }
+  let hours = Math.floor(total / 3600);
+  let rest = Math.round(total % 3600 / 60);
+  if (rest === 60) {
+    hours += 1;
+    rest = 0;
+  }
+  const said = say(hours, "hr", "hour", "hours");
+  return rest === 0 ? said : `${said} ${say(rest, "min", "minute", "minutes")}`;
+}
 var PLACE_GROUP = "place";
+var HOLE_REF = /^@(hand|world|story)\.([a-z][a-z0-9_-]*)$/;
+var isHoleRef = (value) => value.startsWith("@");
+var parseHoleRef = (value) => {
+  const m = HOLE_REF.exec(value);
+  return m === null ? void 0 : { scope: m[1], name: m[2] };
+};
 var BUNDLE_SCHEMA = "storylets/bundle@0";
+var DEFAULT_PLAY_RUNG = "solo";
 var SAVE_SCHEMA = "storylets/save@1";
 var SAVEFILE_SCHEMA = "storylets/savefile@1";
 var PROJECT_FOLDER_EXTENSION = ".storylets";
@@ -431,8 +490,16 @@ var SHARD_EXTENSIONS = {
    *  id-keyed (design/annotation.md). Documentation NOTES used to share this
    *  file and were retired: `purpose` already says why a thing exists, and
    *  Patterpad's typed routing has no destination here. */
-  notes: ".storyletnotes"
+  notes: ".storyletnotes",
+  /** An installation contract: what a VENUE depends on, one file per
+   *  installation in `contracts/` at the project root
+   *  (design/engine-server.md 4.11). Its own shard, and its own folder, for the
+   *  walkthrough's reason (Reboot 7.5, S4): a different owner, a different
+   *  change rate, and a merge that must never collide with the author's edits,
+   *  since the server always wins its own file. */
+  contract: ".storyletcontract"
 };
+var CONTRACTS_DIR = "contracts";
 var PROJECT_SCHEMA = "storylets/project@0";
 var BOX_SCHEMA = "storylets/box@0";
 var TAGS_SCHEMA = "storylets/tags@0";
@@ -440,12 +507,18 @@ var HANDS_SCHEMA = "storylets/hands@0";
 var DECK_SCHEMA = "storylets/deck@0";
 var VIEW_SCHEMA = "storylets/view@0";
 var NOTES_SCHEMA = "storylets/notes@0";
+var CONTRACT_SCHEMA = "storylets/contract@0";
+var contractPropertyPath = (p) => typeof p === "string" ? p : p.path;
+var contractPropertyType = (p) => typeof p === "string" ? void 0 : p.type;
 var FURNITURE_COLOURS = ["paper", "amber", "sage", "sky", "rose", "slate"];
 export {
   BOX_SCHEMA,
   BUNDLE_EXTENSION,
   BUNDLE_SCHEMA,
+  CONTRACTS_DIR,
+  CONTRACT_SCHEMA,
   DECK_SCHEMA,
+  DEFAULT_PLAY_RUNG,
   FURNITURE_COLOURS,
   HANDS_SCHEMA,
   NOTES_SCHEMA,
@@ -459,12 +532,15 @@ export {
   SPATIAL,
   TAGS_SCHEMA,
   VIEW_SCHEMA,
+  ambiguousValueAddressMessage,
   backgroundsOf,
   bindHand,
   bundleAssetPath,
   byDisplayOrder,
   centroid,
   commentsOf,
+  contractPropertyPath,
+  contractPropertyType,
   droppedRect,
   effectiveGameId,
   framesOf,
@@ -474,6 +550,7 @@ export {
   handBinding,
   inferDeclFromWrite,
   isCaseOnlyPropertyName,
+  isHoleRef,
   isSpatial,
   isValidGameId,
   isValidPropertyName,
@@ -481,6 +558,7 @@ export {
   markOf,
   marksOn,
   openThreadCounts,
+  parseHoleRef,
   pointInPolygon,
   polygonBounds,
   polygonOf,
@@ -489,7 +567,9 @@ export {
   spatialOf,
   stacked,
   threadsFor,
+  turnSpan,
   unbindHand,
+  valueAddresses,
   withBackgrounds,
   withPolygon,
   withSpatialGroup,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storylet-studio/model",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Storylets data-model types: source shards (project / box / tags / hands / deck), the compiled bundle, the save envelope. The shape source-of-truth.",
   "type": "module",
   "license": "MIT",