@ak--47/dungeon-master 1.5.4 → 1.6.0

package/docs/guides/1.5.3-upgrade-guide.md

@@ -0,0 +1,117 @@
+# 1.5.3 Upgrade Guide
+
+**TL;DR: No breaking changes — two new exports.** `dungeonToJSON` serializes a dungeon to the JSON/UI wrapper format (the inverse of `parseJSONDungeon`), and `extractComments` pulls the `OVERVIEW` / `HOOK STORIES` doc blocks out of a dungeon's source. Nothing else changed. Existing dungeons and code run unmodified.
+
+## What Changed
+
+### 1. `dungeonToJSON(input, options?)` — dungeon → JSON
+
+**What**: A new named export that converts a dungeon into the `{ schema, hooks, timestamp, version }` JSON/UI wrapper format — the inverse of `parseJSONDungeon`. It accepts the same input flavors as the default export.
+
+```js
+import DUNGEON_MASTER, { dungeonToJSON, parseJSONDungeon } from "@ak--47/dungeon-master";
+
+// From a config object
+const json = await dungeonToJSON(config);
+
+// From a file path (.js / .mjs / .json)
+const json = await dungeonToJSON("./dungeons/vertical/ecommerce.js");
+
+// From raw source text
+const json = await dungeonToJSON("export default { numUsers: 100, events: [...] }");
+
+// From an array of paths → array of results
+const all = await dungeonToJSON(["./a.js", "./b.js"]);
+
+// Round-trips back into a runnable config
+const config = parseJSONDungeon(await dungeonToJSON("./dungeons/vertical/ecommerce.js"));
+```
+
+The output shape:
+
+```js
+{
+    schema,            // config with functions serialized to { functionName, body | args }, hook excluded
+    hooks,             // the hook function stringified, or null
+    timestamp,         // ISO string
+    version: "4.0"     // UI schema format version
+}
+```
+
+**Why**: The package could already ingest JSON dungeons (`parseJSONDungeon`, `loadFromFile`, `loadFromText`) but had no exported way to go the other direction. That logic lived only inside `scripts/dungeon-to-json.mjs` as an un-importable CLI internal.
+
+**Action needed**: None — it's a new export. Two things to know if you use it:
+
+- **Credentials are stripped by default.** `token`, `serviceAccount`, `serviceSecret`, `projectId`, and `secret` are removed from the output so tokens never leak into JSON. Pass `{ includeCredentials: true }` to keep them.
+- **It's best effort, but type-preserving.** Arrow functions and bound `chance.*` methods round-trip cleanly. Detected utility calls (`weighArray`, `weighNumRange`, `pickAWinner`, …) are serialized by name **without their arguments** and revive to `null` — the config validator handles that gracefully, but the revived dungeon won't reproduce those exact property generators. To keep the field's **type** visible even when the generator is lost, every function is sampled at serialization time and its output type is recorded as `dataType`:
+
+  ```js
+  // a property like `amount: weighNumRange(5, 500)` serializes to:
+  { functionName: "weighNumRange", args: [], dataType: "number" }
+  // an arrow `tag: () => chance.pickone([...])` keeps its body AND records:
+  { functionName: "arrow", body: "() => chance.pickone([...])", dataType: "string" }
+  ```
+
+  `dataType` is one of `"number" | "string" | "boolean" | "date" | "object" | "<elementType>[]" | "array"`, omitted only when sampling the function threw. For lossless persistence, keep the `.js` source as the source of truth.
+
+The JSON-representation shapes are formally typed — `DungeonJSON`, `DungeonComments`, and `SerializedFunction` are exported from `types.d.ts`.
+
+`dungeonToJSON` is always async (file/text/array input must be awaited) — `await` it even for object input.
+
+### 2. `extractComments(input)` — read a dungeon's doc blocks
+
+**What**: A new named export that pulls the human-readable comment blocks out of a dungeon's **source**. Dungeons authored by the `create-dungeon` / `write-hooks` skills use a canonical section convention:
+
+```js
+// ── OVERVIEW ──
+/*
+ * NAME:       Acme
+ * APP:        ...
+ */
+
+// ── HOOK STORIES ──
+/*
+ * 1. POWER USERS BUY 3X MORE (everything)
+ * ...
+ */
+```
+
+`extractComments` returns those blocks as cleaned prose:
+
+```js
+import { extractComments } from "@ak--47/dungeon-master";
+
+const { overview, hookStories, sections } = extractComments("./dungeons/vertical/ecommerce.js");
+// overview    → cleaned text of the OVERVIEW block (or null)
+// hookStories → cleaned text of the HOOK STORIES block (or null)
+// sections    → { OVERVIEW: "...", "HOOK STORIES": "...", ... } — every `// ── LABEL ──`
+//               header immediately followed by a block comment, keyed by exact label
+```
+
+It accepts a file path, a raw source string, or an array of paths (→ array of results). The comment scaffolding (`// ──`, `/* */`, leading ` * `) is stripped to readable text.
+
+**Why**: Tools (UIs, LLM pipelines, doc generators) need to read a dungeon's intent without parsing it by hand. There was no programmatic accessor.
+
+**Action needed**: None — it's a new export. Two things to know:
+
+- **It operates on source, never the imported module.** Passing a config object throws — importing a dungeon discards its comments, so there's nothing to extract from a live config. Pass a file path or the raw source string.
+- **It's best effort.** It relies on the canonical `// ── LABEL ──` header + block-comment convention. Hand-written dungeons that deviate (different separator characters, no block comment after the header) may return `null` for `overview`/`hookStories` or omit sections.
+
+### 3. `scripts/dungeon-to-json.mjs` is now a thin wrapper
+
+**What**: The CLI script's inline `convertToJSON` / `convertFunctionToObject` logic moved into `lib/core/dungeon-to-json.js`. The script now calls the exported `dungeonToJSON` (with `includeCredentials: true` to preserve its legacy full-config output for UI round-trips).
+
+**Action needed**: None. The CLI behaves identically:
+
+```bash
+node scripts/dungeon-to-json.mjs ./dungeons/vertical/ecommerce.js
+node scripts/json-to-dungeon.mjs ./dungeons/vertical/ecommerce.json
+```
+
+## Migration Checklist
+
+Nothing required. This release is additive.
+
+- [ ] (Optional) Replace any hand-rolled dungeon→JSON code with `dungeonToJSON`.
+- [ ] (Optional) Use `extractComments` to surface OVERVIEW / HOOK STORIES docs in tooling.
+- [ ] If you serialize dungeons that carry credentials, decide whether you need `{ includeCredentials: true }` (default strips them).

package/docs/guides/1.6.0-upgrade-guide.md

@@ -0,0 +1,204 @@
+# 1.6.0 Upgrade Guide
+
+**TL;DR: No breaking config API changes.** Every 1.5.x dungeon config runs
+unmodified — the only new config field is `ExperimentConfig.sticky`, whose
+default preserves existing behavior byte-for-byte. 1.6.0 is primarily a
+**verifier-alignment release**: the `/verify` emulator gained five new
+analysis types and was re-derived against Mixpanel's ARB C++ line-by-line,
+so verify-side **numbers can shift** (they are now more correct). Three
+generation-side fixes change output at the same seed, each gated on a
+feature you'd know you're using (experiments with shuffle orders,
+time-mutating hooks, `isChurnEvent`). Shipped vertical dungeons moved to a
+one-folder-per-vertical layout.
+
+## What Changed
+
+### 1. Story layer (new, additive)
+
+**What**: Dungeons can now export `stories` alongside the default config —
+one machine-checkable story per hook (`DungeonStory` in types.d.ts, JSON
+schema at `lib/templates/story-spec.schema.json`). The new
+`scripts/verify-stories.mjs` runner evaluates them mechanically into
+five-tier verdicts (NAILED / STRONG / WEAK / NONE / INVERSE) with
+hook-coverage discipline, population floors, disk + in-memory modes, and
+`--json` output.
+
+**Why**: "Did the engineered pattern actually appear in the data?" used to
+be an LLM judgment call. Stories make it a mechanical check.
+
+**Action needed**: None. Dungeons without a `stories` export behave exactly
+as before. All 22 shipped verticals now carry stories — use them as
+reference implementations.
+
+### 2. Emulator expansion (new, additive)
+
+**What**: `emulateBreakdown` gains five types — `eventBreakdown` (Insights
+totals broken down by property, with Mixpanel's exact segment coercion),
+`uniques` (per-interval dedup, rolling XAU, cumulative), `lifecycle`
+(new / retained / resurrected / dormant), `topPaths` (Flows), and
+`distinctCount`. Retention is completed: `compounded`, `birthCanRetain`,
+`carryForward` / `carryBack` / `consecutiveForward`, `calendarStart`,
+`cohortWindow`, `segmentOn: 'return'`, week/month buckets. New standalone
+primitives: `sessionize()`, `filterFirstTimeEver()`, `evaluateFormula()`,
+`extractFlows` / `aggregateFlows`, `frequencyHistogram`, null-aware
+avg/sum `{ flatten: true }`.
+
+**Action needed**: None — all additive. If you previously verified these
+report types in DuckDB or a live project, the emulator now covers them.
+
+### 3. Verify-side behavior changes (numbers can shift)
+
+These make the emulator agree with Mixpanel's ARB implementation. If you
+pinned expected values against 1.5.x emulator output, re-baseline.
+
+- **Retention option keys are strict.** Unknown keys in a `retention`
+  config now **throw** instead of being silently ignored (a typo'd option
+  used to run with defaults and produce plausible-but-wrong numbers).
+  `carry_forward: true` survives as a deprecated alias for
+  `unbounded: 'carryForward'`.
+- **Funnel exclusions no longer fire before step 0.** An exclusion event
+  before the first step no longer condemns the attempt (ARB semantics);
+  it only matters inside the 2-second grace rule at step 0.
+- **Non-sequential funnel orders verify with full ARB semantics.**
+  `first-fixed` / `last-fixed` / `first-and-last-fixed` / `outside-in` /
+  `random` used to verify via loose set-membership; they now enforce
+  conversion windows, the 2-second rule, exclusions, and anchor ordering.
+  Users that passed the loose check but violate a window no longer
+  convert — funnel counts can drop.
+- **`sessionMetrics` defaults to query-time derived sessions.** New
+  `source: 'derived' | 'stamped'` option, default `'derived'`: sessions
+  are re-derived from raw timestamps via `sessionize()` — what Mixpanel
+  actually computes — instead of reading the generator's pre-stamped
+  `session_id`. Pass `source: 'stamped'` to restore the 1.5 reading; the
+  per-row `stampedDivergence` count audits the gap.
+
+### 4. Generation output changes at the same seed (feature-gated)
+
+- **`$experiment_started` is pinned to funnel-pass start.** Pre-existing
+  bug since 1.4.0: for experiment funnels with a shuffle `order`
+  (`last-fixed`, `random`, ...), the exposure event was shuffled into the
+  funnel body, compressing exposure→conversion TTC and undercounting
+  variant lift. It now stays at execution index 0. Output (event order +
+  RNG stream) changes for experiment funnels with shuffle orders;
+  `sequential` experiment funnels are unaffected.
+- **Session IDs are re-derived after the `everything` hook.** Hooks that
+  mutate event times (TTC scaling, injected bursts) used to leave stale
+  `session_id` values that disagreed with query-time derivation. A second
+  relabel pass now runs on the final event set. Only affects dungeons
+  whose hooks move timestamps; identity fields are never touched.
+- **Churn is a hard activity boundary.** Users who hit an `isChurnEvent`
+  (and don't roll a return) no longer carry events dated after the churn
+  event — their stream truncates at it. Only affects `isChurnEvent`
+  dungeons.
+
+### 5. Hook helpers and patterns
+
+- **Bin-based patterns bin by distinct days by default.**
+  `applyFrequencyByFrequency`, `applyFunnelFrequencyBreakdown`, and
+  `applyAggregateByBin` gain `binBy: 'events' | 'distinctDays'` (default
+  `'distinctDays'`) — matching how Mixpanel frequency reports bucket
+  users. Pass `binBy: 'events'` to restore the pre-1.6 axis.
+- **`applyAttributedBySource` rewritten** to overwrite engine-stamped
+  touches (`{ weights, property, model: 'firstTouch'|'lastTouch'|'both' }`)
+  instead of stamping fresh values that land outside the touchpoint cap's
+  lookback and never move the report.
+- **`applyTTCBySegment` deprecated** (still works, warns once). Use
+  `applyTTCBySegmentV2` (`everything` hook) — the funnel-post variant only
+  reaches the Mixpanel report for `isFirstFunnel` runs, because TTC
+  measures the first occurrence of each step per user.
+- **New atoms**: `hashCohort`, `applyLifecycleWave`, `applyPathBias`,
+  `applySessionShape`, `binByDistinctPeriods`, `findFirstSequence`,
+  `scaleFunnelTTC`.
+
+### 6. Experiments: `sticky` knob
+
+**What**: `ExperimentConfig.sticky`, default `true`. Sticky bucketing —
+the deterministic per-user hash that has always been the variant
+assignment — is now explicit and opt-out-able. `sticky: false` re-rolls
+the variant on every funnel pass via the seeded RNG.
+
+```js
+experiment: {
+  name: 'Checkout Redesign',
+  sticky: false,   // multi-pass users can land in different variants
+  variants: [{ name: 'Control' }, { name: 'Treatment', conversionMultiplier: 1.25 }],
+}
+```
+
+**Action needed**: None. The default is the pre-1.6 behavior.
+
+### 7. Vertical dungeon layout
+
+**What**: `dungeons/vertical/` restructured from flat files to one folder
+per vertical: `dungeons/vertical/<name>/<name>.js` plus siblings
+`<name>.verify.mjs` (verification script) and `<name>.sql` (DuckDB
+inspection queries). Two new showcase dungeons: `streaming` (lifecycle)
+and `support-desk` (flows + sessions). All verticals import engine
+helpers via package subpaths (`@ak--47/dungeon-master/utils`,
+`/hook-helpers`) — no relative `../../lib/` imports remain.
+
+**Action needed**: Anything globbing `dungeons/vertical/*.js` inside
+`node_modules` must switch to `dungeons/vertical/*/*.js` (the nested glob
+matches only the dungeon — verify scripts are `.mjs`, SQL is `.sql`).
+
+### 8. Deprecations
+
+- `applyTTCBySegment` → `applyTTCBySegmentV2` (see §5).
+- `Persona.churnRate`, `Persona.activeWindow`, `Persona.soupOverride` —
+  declared but never implemented; the validator now warns once per
+  process if a dungeon sets them.
+- `carry_forward: true` retention option → `unbounded: 'carryForward'`.
+
+## For DM4 specifically
+
+Checklist derived from dm4's current usage surface (as of dm4 @ dm 1.5.4):
+
+1. **`server/services/template-loader.js` — REQUIRED.** The
+   `dungeons/vertical/*.js` quickload glob finds nothing in 1.6.0; switch
+   to `dungeons/vertical/*/*.js`. The relative-import rewriting
+   (`../../lib/utils/utils.js` → package paths) is now a no-op — shipped
+   verticals already import `@ak--47/dungeon-master/utils` and
+   `/hook-helpers` directly. Vertical count is 22 (was 20): `streaming`
+   and `support-desk` are new.
+2. **`verifier-canonical.js` sessionMetrics — numbers shift.** The
+   `{ type: 'sessionMetrics' }` call now derives sessions from timestamps
+   (§3). Recommended: keep the new default (it's what Mixpanel computes)
+   and re-baseline expected avg/median/p90; `source: 'stamped'` restores
+   1.5 readings if needed.
+3. **`verifier-canonical.js` evaluateFunnel — counts can drop** for
+   non-`sequential` `funnelOrder` values and for configs passing
+   `exclusionSteps` (§3). Sequential funnels with no exclusions are
+   unchanged.
+4. **`ALLOWED_DUNGEON_OPTION_KEYS` — no changes required.** 1.6.0 adds no
+   new top-level `Dungeon` config keys. The only new config field is
+   funnel-level `experiment.sticky` — add it wherever dm4 validates
+   `ExperimentConfig` shapes.
+5. **Error-string regexes — re-run `error-messages` tests.** The SCD
+   credentials message is unchanged verbatim. New throw surfaces exist in
+   the verify layer (strict retention keys, funnel option conflicts) —
+   only relevant if dm4 starts calling those APIs with unknown options.
+6. **Unchanged, no action**: `onProgress` payload contract (1.5.4 shape),
+   `dungeonToJSON` / `extractComments` (the `stories` named export is
+   deliberately NOT carried into JSON — the `.js` file stays the story
+   source of record), `validateSchema` report shape,
+   `buildIdentityMap` / `resolveUserId`, `_drop: true` profile semantics,
+   HOOKS.md §4 recipe numbering (4.29–4.31 appended, existing numbers
+   stable), `types.d.ts` / `HOOKS.md` package-file paths, validator
+   clamps (safe-range table identical to 1.5.1), two-arg
+   `DUNGEON_MASTER(config, overrides)` overload.
+7. **Optional adoption**: the story layer (§1) is a better fit for dm4's
+   hook-plan/verify pipeline than free-form checks — generated dungeons
+   can emit a `stories` export and dm4 can shell out to
+   `scripts/verify-stories.mjs --json` for mechanical verdicts instead of
+   LLM-graded verification.
+
+## Verifying the upgrade
+
+```bash
+npm install @ak--47/dungeon-master@1.6.0
+npx vitest run   # your suite; re-baseline any pinned emulator numbers per §3
+```
+
+For dungeons using experiments with shuffle orders, time-mutating hooks,
+or `isChurnEvent`: regenerate any golden fixtures — same seed now produces
+corrected (different) output per §4.

package/dungeons/technical/stories-verify.js

@@ -0,0 +1,152 @@
+// ── IMPORTS ──
+import { hashCohort, cloneEvent, dropEventsWhere } from '../../lib/hook-helpers/index.js';
+/** @typedef {import("../../types").Dungeon} Config */
+
+// ── OVERVIEW ──
+/*
+ * NAME:       stories-verify
+ * PURPOSE:    P3.3 fixture — exercises the story runner (scripts/verify-stories.mjs)
+ *             in both disk and in-memory modes. Small scale, fixed seed, and
+ *             DETERMINISTIC hooks (index parity, hash cohorts — no RNG) so the
+ *             story verdicts are stable run-to-run.
+ * SCALE:      200 users, ~12K events, 14 days
+ * EVENTS (2): browse, purchase
+ * FUNNELS (0): none
+ *
+ * Verified by: node scripts/verify-stories.mjs dungeons/technical/stories-verify.js
+ */
+
+// ── HOOK STORIES ──
+/*
+ * One `everything` hook, plan pinned per user via hashCohort (the engine stamps
+ * the `plan` superProp randomly per event; the hook overwrites it per-user):
+ *
+ * H1: pro-plan browse amplification — every pro browse event is cloned
+ *     BROWSE_CLONES more times, so pro browse volume is exactly
+ *     (BROWSE_CLONES + 1)x its base. Aggregate pro/free count ratio also
+ *     absorbs the hash-split cohort-size noise (Binomial(200, 0.5): the
+ *     pro/free user ratio sits within ~[0.8, 1.25] at 3σ), so the a-priori
+ *     floor is (BROWSE_CLONES + 1) * 0.8 rounded down to 2.0 — derived from
+ *     the knobs, not tuned to observations.
+ * H2: free-plan purchase suppression — every 2nd free purchase is dropped
+ *     (index parity, deterministic). Free purchase volume halves (keep =
+ *     ceil(n/2) per user, so slightly over half survives at small n), putting
+ *     the pro/free purchase ratio a bit under 2.0 — floor 1.5.
+ */
+
+// ── KNOBS (stories compute their thresholds from these) ──
+const PRO_PCT = 50;        // hashCohort split: ~half the users are plan=pro
+const BROWSE_CLONES = 2;   // pro browse volume = (BROWSE_CLONES + 1) x base
+
+// ── CONFIG ──
+/** @type {Config} */
+const config = {
+	name: 'stories-verify',
+	seed: 'p33-stories-verify',
+	numUsers: 200,
+	numDays: 14,
+	avgEventsPerUserPerDay: 4,
+	percentUsersBornInDataset: 0,
+	format: 'json',
+	concurrency: 1,
+	writeToDisk: false,
+	verbose: false,
+	superProps: { plan: ['free', 'pro'] },
+	events: [
+		{ event: 'browse', weight: 8, properties: { surface: ['home', 'category', 'search'] } },
+		{ event: 'purchase', weight: 2, properties: { amount: [10, 20, 30, 40, 50] } },
+	],
+	hook: function (record, type, _meta) {
+		if (type !== 'everything' || !Array.isArray(record) || !record.length) return record;
+		const uid = record[0].user_id || record[0].distinct_id;
+		if (!uid) return record;
+		const isPro = hashCohort(uid, PRO_PCT);
+		const plan = isPro ? 'pro' : 'free';
+		for (const ev of record) ev.plan = plan;
+		if (isPro) {
+			// H1: clone each pro browse BROWSE_CLONES times (same timestamp —
+			// auto-sort after `everything` keeps the stream ordered).
+			const clones = [];
+			for (const ev of record) {
+				if (ev.event !== 'browse') continue;
+				for (let i = 0; i < BROWSE_CLONES; i++) clones.push(cloneEvent(ev));
+			}
+			record.push(...clones);
+		} else {
+			// H2: drop every 2nd free purchase (parity — deterministic, no RNG).
+			let n = 0;
+			dropEventsWhere(record, (e) => e.event === 'purchase' && (n++ % 2 === 1));
+		}
+		return record;
+	},
+};
+
+// ── STORIES ──
+/** @type {import("../../types").DungeonStory[]} */
+export const stories = [
+	{
+		id: 'H1-pro-browse-3x',
+		hook: 'H1',
+		archetype: 'cohort-count-scale',
+		narrative: `pro-plan users generate ${BROWSE_CLONES + 1}x browse volume (each pro browse cloned ${BROWSE_CLONES} more times)`,
+		assertions: [
+			{
+				breakdown: { type: 'eventBreakdown', event: 'browse', breakdownProperty: 'plan' },
+				select: {
+					pro: { where: { value: 'pro' } },
+					free: { where: { value: 'free' } },
+				},
+				// target from the knob; floor = target * 0.8 hash-split bound (see HOOK STORIES)
+				expect: { metric: 'pro.count / free.count', op: '>=', target: BROWSE_CLONES + 1, floor: 2.0 },
+			},
+			{
+				// single-ref sanity: the pro cohort is roughly half of 200 users
+				breakdown: { type: 'eventBreakdown', event: 'browse', breakdownProperty: 'plan' },
+				select: { pro: { where: { value: 'pro' } } },
+				expect: { metric: 'pro.total_users', op: 'between', target: [60, 140] },
+			},
+		],
+	},
+	{
+		id: 'H2-free-purchase-drop',
+		hook: 'H2',
+		archetype: 'composition-drift',
+		narrative: 'every 2nd free purchase dropped — pro/free purchase count ratio approaches 2x (ceil-keep parity leaves it slightly under)',
+		assertions: [
+			{
+				breakdown: { type: 'eventBreakdown', event: 'purchase', breakdownProperty: 'plan' },
+				select: {
+					pro: { where: { value: 'pro' } },
+					free: { where: { value: 'free' } },
+				},
+				expect: { metric: 'pro.count / free.count', op: '>=', target: 2.0, floor: 1.5 },
+			},
+		],
+	},
+	{
+		id: 'H2-duckdb-crosscheck',
+		hook: 'H2',
+		archetype: 'bespoke',
+		narrative: 'raw-shard SQL cross-check of the purchase suppression (duckdb escape hatch; disk mode only — skipped in-memory)',
+		assertions: [
+			{
+				breakdown: {
+					type: 'duckdb',
+					sql: "SELECT plan, count(*) AS n FROM read_json_auto('{{PREFIX}}-EVENTS*.json') WHERE event = 'purchase' GROUP BY plan",
+				},
+				assert: (rows) => {
+					const by = Object.fromEntries((rows || []).map(r => [r.plan, Number(r.n)]));
+					const ratio = by.pro / by.free;
+					const pass = Number.isFinite(ratio) && ratio >= 1.5;
+					return {
+						pass,
+						verdict: pass ? (ratio >= 1.8 ? 'NAILED' : 'STRONG') : 'NONE',
+						detail: `pro=${by.pro} free=${by.free} ratio=${Number.isFinite(ratio) ? ratio.toFixed(2) : 'n/a'}`,
+					};
+				},
+			},
+		],
+	},
+];
+
+export default config;

package/dungeons/vertical/README.md

@@ -0,0 +1,154 @@
+# Vertical Dungeons — Proof of Story-in-Data
+
+One folder per vertical dungeon (v1.6 layout). Each
+`dungeons/vertical/<name>/` holds three sibling files:
+
+- **`<name>.js`** — the dungeon, exporting `stories` alongside the default
+  config. Stories are the machine-checkable contract for every numbered
+  hook; evaluate them with
+  `node scripts/verify-stories.mjs dungeons/vertical/<name>/<name>.js`.
+- **`<name>.verify.mjs`** — Node script using `@ak--47/dungeon-master/verify`
+  primitives (`emulateBreakdown`, `evaluateFunnel`, `buildIdentityMap`,
+  `resolveUserId`). Emulator-backed where Mixpanel-equivalent semantics
+  matter; per-user JS aggregation where bespoke. Each `check()` call asserts
+  one engineered hook produces measurable signal in the generated data.
+- **`<name>.sql`** — DuckDB queries for human-eyeball inspection of the
+  same hooks. Run after generation to inspect raw outputs the way an
+  analyst would in Mixpanel.
+
+These files are the **proof** that the engineered story patterns documented
+in each dungeon's top-level comment block actually appear in the generated
+data — at full fidelity, not at smoke-test scale.
+
+## Coverage
+
+All 22 vertical dungeons. Every documented hook has a story-backed
+verification check — no documented hook is unverified. (Aggregate hook
+counts are rebuilt at each release; see the per-dungeon stories exports
+for the authoritative contract.)
+
+Score column regenerated 2026-07-04 from the fix-round sweep: every
+dungeon regenerated at full fidelity (its shipped `numUsers`) under the
+post-review verifier and scored by `scripts/verify-stories.mjs` — the
+score is the worst story verdict the runner printed, not an editorial
+judgment. 15 NAILED / 7 STRONG, 22/22 at STRONG or better. This is
+lower than the 2026-07-03 headline (20/2) **by design**: the fix-round
+band policy below re-derived NAILED bands from hook knobs, and verdicts
+that previously leaned on measurement-anchored bands now grade STRONG
+honestly. No hook regressed — the data is unchanged; the grading got
+stricter.
+
+| # | Dungeon | Score | Hooks | Iter |
+|---|---------|-------|-------|------|
+| 1 | fitness | NAILED | 10/10 | 2 |
+| 2 | dating | NAILED | 10/10 | 2 |
+| 3 | community | NAILED | 10/10 | 3 |
+| 4 | travel | NAILED | 10/10 | 2 |
+| 5 | logistics | NAILED | 10/10 | 3 |
+| 6 | education | STRONG | 10/10 | 3 |
+| 7 | real-estate | NAILED | 10/10 | 2 |
+| 8 | insurance-application | STRONG | 10/10 | 3 |
+| 9 | food-delivery | STRONG | 10/10 | 2 |
+| 10 | devtools | NAILED | 10/10 | 1 |
+| 11 | healthcare | NAILED | 10/10 | 2 |
+| 12 | fintech | NAILED | 10/10 | 2 |
+| 13 | ai-platform | NAILED | 10/10 | 3 |
+| 14 | marketplace | NAILED | 10/10 | 2 |
+| 15 | media | NAILED | 10/10 | 2 |
+| 16 | ecommerce | NAILED | 10/10 | 3 |
+| 17 | sass | STRONG | 11/11 | 2 |
+| 18 | gaming | STRONG | 13/13 | 2 |
+| 19 | social | STRONG | 10/10 | 2 |
+| 20 | crypto | NAILED | 11/11 | 2 |
+| 21 | streaming | NAILED | 4/4 | 2 |
+| 22 | support-desk | STRONG | 3/3 | 1 |
+
+**Score legend.** Grading is mechanical (the runner reports where the
+measured value landed), but the bands themselves are author-declared —
+band *selection* is an editorial act, and the score is only as honest
+as the band derivation. The fix-round band policy (2026-07-04):
+- A NAILED band must be derived from the hook's knob (knob ±10%),
+  never from a measurement of the dungeon's own output — a band
+  centered on a measurement passes by construction.
+- Where the realized magnitude is confounded (selection effects,
+  mixtures, budget attenuation), the assertion uses a knob-derived
+  floor or ceiling instead, which grades STRONG by design. STRONG is
+  not a blemish: it is the honest verdict for a real effect whose
+  exact magnitude is not knob-derivable.
+- **NAILED** — every assertion in every story landed inside its
+  knob-derived NAILED band at full fidelity.
+- **STRONG** — every assertion passed, but at least one landed in the
+  STRONG band outside the NAILED band (or is a floor/ceiling check).
+  Each such case documents why in its story's derivation notes.
+
+## Running
+
+```bash
+# 1. Generate fresh data (full fidelity — uses dungeon's shipped numUsers)
+node scripts/verify-runner.mjs dungeons/vertical/${NAME}/${NAME}.js verify-${NAME}
+
+# 2. Evaluate the dungeon's stories (five-tier verdict table)
+node scripts/verify-stories.mjs dungeons/vertical/${NAME}/${NAME}.js --data-prefix verify-${NAME}
+
+# 3. Run the .mjs verifier (CI gate)
+node --max-old-space-size=4096 dungeons/vertical/${NAME}/${NAME}.verify.mjs
+
+# 4. (Optional) Run the SQL for human inspection
+duckdb -c ".read dungeons/vertical/${NAME}/${NAME}.sql"
+
+# 5. Cleanup
+rm -f data/verify-${NAME}-*
+```
+
+## Verify-script anatomy
+
+Every `<name>.verify.mjs` follows the same template (see
+[HOOKS.md §9.9](../../HOOKS.md#99-per-dungeon-verify-script-template)):
+
+1. Stream-load shards (`readline.createInterface`) — handles dungeons up to
+   ~1M events without `readFileSync`'s 512MB cap.
+2. Build identity map (`buildIdentityMap(profiles)`) and per-user event
+   bucket (`resolveUserId`).
+3. One `check(name, pass, detail)` per documented hook.
+4. Exit non-zero if any check fails.
+
+## Reading the SQL
+
+SQL files are human-readable Mixpanel inspection queries. They name each
+hook the same way as the `.verify.mjs` file and the dungeon's docstring.
+Numbering is consistent across all three artifacts:
+
+- Dungeon comment: `* 1. WHALE WALLETS (everything)`
+- `<name>.verify.mjs`: `check('H1 whale 5x+ trade amount', ...)`
+- `<name>.sql`: `-- Hook 1: WHALE WALLETS — top 2% drive most volume`
+
+## Known limitations (historical — list now empty)
+
+Several engineered hooks intentionally use `funnel-post` to compress
+time-to-convert within a single funnel-instance. The verifier's
+`evaluateFunnel` is a greedy single-pass over the user's full event
+history — it picks the first matching event for each step regardless of
+which funnel-instance the hook touched. Through v1.5 this forced some
+dungeons to check TTC hooks for population presence only. As of v1.6
+every affected dungeon (ai-platform, dating, community, travel,
+logistics, education, real-estate, devtools, marketplace, crypto) has
+graduated: their TTC stories assert the TTC delta itself through
+`emulateBreakdown`'s `timeToConvert` at conversion windows covering the
+stretched support (see each story narrative for the censoring
+analysis). Three graduation lessons generalize: pick the conversion
+window where each cohort's TTC distribution is unimodal (media — at
+multi-day windows the median sits on a bimodal mode boundary and flips
+on sampling noise); restrict funnel-post scaling to the target
+funnel when another funnel shares a step prefix (marketplace — scaling
+everything let the greedy evaluator assemble chains across unscaled
+instances, collapsing the read); and anchor the scaled funnel on a
+unique first step (crypto — `wallet connected` is `isFirstEvent` +
+`isAuthEvent`, so it occurs exactly once per user and the greedy
+evaluator has no earlier instance to latch onto, making the read
+stable across 1h–24h windows).
+
+See
+[`research/1.5.0-vertical-eval.md`](../../research/1.5.0-vertical-eval.md)
+for the aggregate evaluation methodology and pattern catalog, and
+[HOOKS.md §9](../../HOOKS.md#9-verification-patterns-from-the-v150-vertical-eval)
+for the verification recipe encyclopedia.