Add declarative quest battery (ADR 0007)

- New src/state/Quests.js module: registerQuests, questStatus, questWhatsNext, questWhatsNextNode, questProgress, resolveQuestAccessor, clearQuests
- Virtual quest namespace in condition evaluator (quest.<id>.<accessor>)
- Export quest API from mod.js and mod.d.ts
- Document quest/step terminology in CONTEXT.md
- New ADR 0007-declarative-quest-battery.md

Author: gandazgul

CONTEXT.md

@@ -40,6 +40,9 @@ Extract and formalize domain terminology from the codebase.
 | **WeatherLayer** | Overlays procedural rain/snow (Graphics lines) and/or falling leaves (sprites) | `this.weather` on AdventureScene |
 | **NightLayer** | Evening/night lighting overlay: tint, lit windows, moon | Per-scene optional |
 | **CritterHelper** | Static utility for spawning decorative ambient critters (butterfly, bird, ground) | Uses `summer-atlas` by default |
+| **Quest** | A composite tree of Steps the game registers at boot; the engine derives `done`/`whatsNext` by evaluating each node's `doneWhen` **Condition** over the Store. No stored status, no player-facing log | Registered via `quests` registry; evaluator peer of `PropEngine` |
+| **Step** | A node in a Quest — a Quest nested in a Quest. Leaf carries a `doneWhen`; composite carries ordered `steps` (hand-authored or generated from a runtime target list). `whatsNext` = DFS to first incomplete leaf | One node type, no `flag`/`collection` taxonomy |
+| **Quest path namespace** | Virtual `quest.<id>.<accessor>` keys the Condition evaluator resolves at eval time (not stored). `<accessor>` ∈ `{ status, whatsNext, progress }` or a `<step_name>` that descends. `status` ∈ `not_started`→`seen`→`started`→`done` (derived cascade); `progress` = count of done leaves. Same namespace for `when` and imperative reads | Step names can't shadow `status`/`whatsNext`/`progress` (boot guard) |
 | **DialogueBubble** | A cloud-bubble Container with optional icons + text, auto-destroying | Supports `thought` and `speech` variants |
 | **ContentRegistry** | Engine registry mapping inventory item IDs to atlas/frame/scale specs | `content.registerItems()` / `content.getItem()` |
 | **CharacterRegistry** | Engine registry mapping character IDs to render configs (sprite, animations, outfits) | `characters.register()` / `characters.resolve()` / `characters.render()` |

docs/adr/0007-declarative-quest-battery.md

@@ -0,0 +1,114 @@
+# 0007 — Declarative Quest battery
+
+Status: **accepted** Date: 2026-06-04
+
+## Decision
+
+The Engine provides a **Quest battery** — a generic, game-agnostic system for declaring task structures and querying
+their progress — as a peer to the Prop framework (ADR 0002) and the declarative NPC cast (ADR 0004). It has four parts:
+
+1. **A single recursive node type.** A Quest is a composite tree. Each node is one shape:
+   - **leaf** — `{ id, doneWhen: Condition }`
+   - **composite** — `{ id, steps: Node[] }`
+   - **collection** — `{ id, collect: { items, in, selfCombineInto? } }` — generates one leaf per item (each `doneWhen`
+     = `has(in, item)`); `items` may be a function so the set can be rolled at runtime.
+
+   A node is **done** when, if it has steps, all steps are done; otherwise its `doneWhen` passes. A Step _is_ a Quest —
+   there is no separate "sub-quest" type and no `flag`/`collection` taxonomy at the type level. Any node may carry an
+   **optional `icon`** (a hint for the Thought-Bubble nudge or a future quest log), shown when present and hidden when
+   absent — so the unit→icon mapping lives on the node, not in a separate Game table.
+
+2. **A `quests` registry** the Game populates at boot (`quests.register(def)`), exactly like `content`, `castRegistry`,
+   and `wearables`. Definitions are plain declarative data; the Engine never hardcodes a quest.
+
+3. **A derived evaluator.** `status` and `whatsNext` are **computed on read** from the Store via the **Condition** DSL —
+   never stored. `status` resolves by a priority cascade:
+
+   ```
+   done         if all leaves done
+   started      else if startWhen passes   (default: any leaf done)
+   seen         else if seenWhen passes     (optional; typically an intro-seen fact)
+   not_started  otherwise
+   ```
+
+   `whatsNext` is a depth-first walk to the first incomplete leaf (the concrete unit still outstanding: a toy id, an
+   ingredient id), or `null` once done. `progress` is the count of done leaves in the subtree (a scalar; `total` is
+   known from the definition, so percent is derivable).
+
+4. **A virtual path namespace** in the Condition evaluator. State is read as `quest.<id>.<accessor>`, where `<accessor>`
+   is one of three reserved keys (`status`, `whatsNext`, `progress`) or a `<step_name>` that descends into that child
+   and reopens the same accessors. The **same namespace serves both `when` blocks and imperative reads** — there is no
+   second API for querying quests. The evaluator recognizes the `quest.` prefix and routes to the Quest resolver instead
+   of the flat Store. A `when` therefore reads quest state with plain, serializable `eq`:
+
+   ```js
+   when: { "quest.backpack.status": { eq: "started" } }
+   when: { "quest.backpack.fill.pencil_case.whatsNext": { eq: "ruler" } }
+   ```
+
+   Step ids may not shadow the reserved accessors `status` / `whatsNext` / `progress`; registration throws if they do.
+
+The Game owns only the **catalog** of definitions (including each node's optional `icon`). The Engine owns the node
+type, registry, evaluator, and namespace.
+
+## Context
+
+State across an adventure game is a sprawl of booleans, and the same composite predicate gets hand-re-derived wherever
+it is needed. In the reference game, the two kitchen-doorway hotspots each inlined a character-for-character copy of the
+`isBreakfastInProgress` predicate in raw DSL keys; the "what is the next thing to do" question was answered by ~6
+bespoke cascades (`getMissingToys`, `getPancakeIngredientsMissing`, `getOutOfBoundsBlockers`,
+`getNextBackpackQuestStepIcon`, `getBreakfastReminderIcons`, `getEndGameBlocker`); and a pile of intro-seen flags
+(`summerIntroSeen`, `mamaBackpackIntroSeen`, …) tracked lifecycle by hand. Changing one rule meant editing every copy in
+lockstep; missing one shipped a regression.
+
+A survey of how the genre handles this confirmed the failure mode rather than offering an escape:
+
+- **Adventure Game Studio** uses one global `int` per quest (`0`/`1`/`-1`), advanced by hand — the same boolean sprawl
+  with a sanctioned name.
+- **Bethesda (Skyrim/Fallout)** uses stored stage integers (`SetStage`) plus objective flags, advanced by quest scripts.
+  Powerful, but the canonical source of "permanently broken quest" bugs — a script path that forgets to advance a stage.
+  This is precisely our regression class at AAA scale, and the argument against any _stored_ status.
+- **Unity** best practice is ScriptableObject-based quests: author as data at edit time, evaluate at runtime. The one
+  durable approach, and structurally identical to this battery.
+- **Phaser** offers only the registry/DataManager — a key-value store (our `Store`); no quest concept.
+
+The Engine already had every ingredient: a pure, serializable **Condition** DSL (ADR 0002) shared by props, cast, and
+wearables; the declarative-registry idiom; and a reactive `Store`. A Quest's "is it done" check is structurally
+identical to a Prop's `when`. So this battery formalizes a pattern the Engine was already shaped for, rather than
+introducing a foreign mechanism.
+
+## Consequences
+
+- **Status cannot desync.** Because `status`/`whatsNext` are derived from existing facts on every read, there is no
+  stored quest field to fall out of agreement with the world — structurally avoiding the Bethesda/AGS failure mode.
+- **One `whatsNext`, not six cascades.** Every "what's the next step" question becomes a single DFS over a declared
+  tree. Drilling (which quest → which step → which item) falls out of the recursion.
+- **`when` blocks reference quests, not raw keys.** Props, exits, cast reactions, and gates read `quest.<id>.<accessor>`
+  instead of re-spelling composite conditions. One definition, many readers.
+- **The Condition evaluator gains a virtual-namespace seam.** It must route prefixed keys to a resolver. This is general
+  (future namespaces can reuse it) but it is now load-bearing for props/cast/wearables, which makes the seam **hard to
+  reverse** — backing it out means re-inlining conditions across every consumer.
+- **Facts must be monotonic.** Lifecycle stages derived from transient signals (e.g. "an item is on-screen now") will
+  flicker/regress. Transients must be latched into a stored monotonic fact that the Quest reads. The derived-status
+  guarantee holds only over a monotonic fact substrate.
+- **Reserved accessors constrain step names.** `status` and `whatsNext` are reserved; a boot guard enforces it.
+- **Another engine surface to maintain,** and the Engine is now committed to the Quest concept fairly permanently.
+
+## Considered alternatives
+
+- **Stored status machine (AGS int / Bethesda stage).** Rejected: reintroduces the desync/regression class that
+  motivated the work; adds an (N+1)th field that must agree with N others.
+- **Materialized derived Store keys** (recompute status into reserved keys so plain `eq` works). Rejected: a cache that
+  exists only to be read by conditions, and still "stored" in spirit; the virtual namespace gets the same `eq`
+  ergonomics with nothing materialized.
+- **A dedicated `quest` Condition op.** Rejected: hard-couples the Engine's most shared primitive (the Condition DSL) to
+  one concept; the virtual path namespace needs no new op.
+- **Game-only quests (no Engine battery).** Rejected: the evaluator is pure tree-traversal + Condition eval with zero
+  game knowledge — the textbook definition of an Engine battery under ADR 0005 — and every title in this genre needs it.
+  Keeping it game-side would trap reusable code and duplicate the Engine's existing evaluation path.
+- **Flat step list with a closed `flag`/`collection` taxonomy.** Rejected: real data nests three levels
+  (`backpack → fill → pencil_case → parts`) and target sets are sometimes runtime-rolled; a uniform recursive node with
+  generated children covers all of it with one `whatsNext` traversal.
+- **Distributed, entity-owned state** (each object tracks itself; no central quest). Rejected for the "what's next / is
+  this flow done" question specifically: it needs an ordered view _across_ entities, which a uniform Quest tree provides
+  and scattered self-state does not.

mod.d.ts

@@ -4106,6 +4106,131 @@ export type RunState = {
 	collections: Record<string, Set<string>>;
 	items: Record<string, string>;
 };
+/**
+ * Register quest definitions (merges with any already registered). Throws if a
+ * step id shadows a reserved accessor.
+ * @param {Record<string, QuestNode>} entries
+ */
+export function registerQuests(entries: Record<string, QuestNode>): Record<string, QuestNode>;
+/**
+ * Resolve a `quest.<id>.<...>.<accessor>` path against the registry. Each
+ * non-reserved segment descends into the child node with that id; a reserved
+ * segment (which must be terminal) yields the derived value. A path that ends
+ * on a node defaults to its `status`.
+ * @param {string} path
+ * @returns {string | number | null | undefined}
+ */
+export function resolveQuestAccessor(path: string): string | number | null | undefined;
+/** @param {string} id @returns {"not_started"|"seen"|"started"|"done"|undefined} */
+export function questStatus(id: string): "not_started" | "seen" | "started" | "done" | undefined;
+/** @param {string} id @returns {string | null | undefined} first outstanding unit id. */
+export function questWhatsNext(id: string): string | null | undefined;
+/** @param {string} id @returns {QuestNode | null | undefined} the outstanding leaf node (carries its optional `icon`). */
+export function questWhatsNextNode(id: string): QuestNode | null | undefined;
+/** @param {string} id @returns {{ done: number, total: number } | undefined} */
+export function questProgress(id: string): {
+	done: number;
+	total: number;
+} | undefined;
+/** Reset the registry (tests). */
+export function clearQuests(): void;
+/**
+ * Engine — declarative Quest battery (ADR 0007).
+ *
+ * A Quest is a composite tree of nodes; a Step *is* a Quest nested in a Quest.
+ * Status (`not_started`→`seen`→`started`→`done`), `whatsNext` and `progress`
+ * are DERIVED on read by evaluating each node's Condition against the Store —
+ * nothing is stored, so quest state cannot desync from the world.
+ *
+ * The Game registers a catalog at boot ({@link registerQuests}); the Engine
+ * never hardcodes a quest. State is read through the `quest.<id>.<accessor>`
+ * virtual namespace the Condition evaluator resolves (see conditions.js), so a
+ * `when` reads quest state with the same DSL — and the same names — that
+ * imperative code uses.
+ *
+ * Node shapes (one type, no taxonomy):
+ *   - leaf:       `{ id, doneWhen: Condition, icon? }`
+ *   - composite:  `{ id, steps: Node[], icon? }`
+ *   - collection: `{ id, collect: { items, in, selfCombineInto? }, icon? }`
+ *       `items` is a list of ids (or nested nodes), or a `() => list` for
+ *       runtime-rolled sets; each generated leaf is done when its id is in the
+ *       `in` collection (or already moved into `selfCombineInto`).
+ * A root may also carry `seenWhen` / `startWhen` Conditions (see {@link statusOf}).
+ *
+ * @typedef {Record<string, any>} Condition
+ * @typedef {{
+ *   id?: string,
+ *   doneWhen?: Condition,
+ *   steps?: QuestNode[],
+ *   collect?: { items: Array<string | QuestNode> | (() => Array<string | QuestNode>), in: string, selfCombineInto?: string },
+ *   seenWhen?: Condition,
+ *   startWhen?: Condition,
+ *   icon?: any,
+ *   _collect?: { in: string, selfCombineInto?: string },
+ * }} QuestNode
+ */
+/** Accessor names that may not be used as step ids (they'd shadow the namespace). */
+export const RESERVED_ACCESSORS: readonly [
+	"status",
+	"whatsNext",
+	"progress"
+];
+/**
+ * The live quest registry — a plain id → QuestNode map the Game populates at
+ * boot. Read by reference, so late registration before the first read is fine.
+ * @type {Record<string, QuestNode>}
+ */
+export const questRegistry: Record<string, QuestNode>;
+export namespace quests {
+	export { registerQuests as registerQuests };
+	export { questStatus as questStatus };
+	export { questWhatsNext as questWhatsNext };
+	export { questWhatsNextNode as questWhatsNextNode };
+	export { questProgress as questProgress };
+	export { resolveQuestAccessor as resolveQuestAccessor };
+	export { questRegistry as questRegistry };
+}
+type Condition$1 = Record<string, any>;
+/**
+ * Engine — declarative Quest battery (ADR 0007).
+ *
+ * A Quest is a composite tree of nodes; a Step *is* a Quest nested in a Quest.
+ * Status (`not_started`→`seen`→`started`→`done`), `whatsNext` and `progress`
+ * are DERIVED on read by evaluating each node's Condition against the Store —
+ * nothing is stored, so quest state cannot desync from the world.
+ *
+ * The Game registers a catalog at boot ({@link registerQuests}); the Engine
+ * never hardcodes a quest. State is read through the `quest.<id>.<accessor>`
+ * virtual namespace the Condition evaluator resolves (see conditions.js), so a
+ * `when` reads quest state with the same DSL — and the same names — that
+ * imperative code uses.
+ *
+ * Node shapes (one type, no taxonomy):
+ *   - leaf:       `{ id, doneWhen: Condition, icon? }`
+ *   - composite:  `{ id, steps: Node[], icon? }`
+ *   - collection: `{ id, collect: { items, in, selfCombineInto? }, icon? }`
+ *       `items` is a list of ids (or nested nodes), or a `() => list` for
+ *       runtime-rolled sets; each generated leaf is done when its id is in the
+ *       `in` collection (or already moved into `selfCombineInto`).
+ * A root may also carry `seenWhen` / `startWhen` Conditions (see {@link statusOf}).
+ */
+export type QuestNode = {
+	id?: string;
+	doneWhen?: Condition$1;
+	steps?: QuestNode[];
+	collect?: {
+		items: Array<string | QuestNode> | (() => Array<string | QuestNode>);
+		in: string;
+		selfCombineInto?: string;
+	};
+	seenWhen?: Condition$1;
+	startWhen?: Condition$1;
+	icon?: any;
+	_collect?: {
+		in: string;
+		selfCombineInto?: string;
+	};
+};
 /**
  * Fade the camera out, then start `targetKey`.
  *

mod.js

@@ -21,6 +21,18 @@ export { NightLayer } from "./src/environment/NightLayer.js";
 export { exitApproaches, PropEngine } from "./src/interaction/PropEngine.js";
 export { SceneEditor } from "./src/ui/SceneEditor.js";
 export { Store, store } from "./src/state/Store.js";
+export {
+    clearQuests,
+    questProgress,
+    questRegistry,
+    quests,
+    questStatus,
+    questWhatsNext,
+    questWhatsNextNode,
+    registerQuests,
+    RESERVED_ACCESSORS,
+    resolveQuestAccessor,
+} from "./src/state/Quests.js";
 export { SubsceneStack } from "./src/scene/SubsceneStack.js";
 export { showSuccessMessage } from "./src/cutscene/SuccessMessage.js";
 export { DialogueBubble } from "./src/cutscene/DialogueBubble.js";

src/core/conditions.js

@@ -1,4 +1,5 @@
 import { store } from "../state/Store.js";
+import { resolveQuestAccessor } from "../state/Quests.js";
 
 /**
  * Declarative condition evaluator for the prop framework (see
@@ -77,6 +78,16 @@ function evaluateLeaf(key, constraint, ctx) {
         return ctx.draggedId === constraint;
     }
 
+    // Virtual quest namespace: `quest.<id>.<accessor>` resolved by the Quest
+    // battery (ADR 0007). Same scalar sugar as a value key.
+    if (key.startsWith("quest.")) {
+        const actual = resolveQuestAccessor(key);
+        if (constraint !== null && typeof constraint === "object") {
+            return evaluateOps(actual, constraint);
+        }
+        return actual === constraint; // bare value = eq
+    }
+
     if (store.isCollection(key)) {
         return evaluateCollection(key, constraint, ctx);
     }