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

package/dungeons/vertical/travel/travel.sql

@@ -0,0 +1,236 @@
+-- ============================================================
+-- travel.js — v1.6 human-inspection queries (DuckDB)
+--
+-- Every query is keyed to a story id in travel.js's `stories` export;
+-- the machine-checked verdicts come from:
+--   node scripts/verify-stories.mjs dungeons/vertical/travel/travel.js --data-prefix verify-travel
+-- Generate first:
+--   node scripts/verify-runner.mjs dungeons/vertical/travel/travel.js verify-travel
+-- Run this file:
+--   duckdb -c ".read dungeons/vertical/travel/travel.sql"
+-- ============================================================
+
+-- ── identity-resolution prelude ─────────────────────────────
+-- avgDevicePerUser: 2 + account created is both isAuthEvent and
+-- isFirstEvent, so born users auth on their first event; the device-pool
+-- resolve is belt-and-braces for any device-only edge.
+CREATE OR REPLACE VIEW users AS
+SELECT * FROM read_json_auto('data/verify-travel-USERS*.json', sample_size=-1, union_by_name=true);
+
+CREATE OR REPLACE VIEW device_map AS
+-- profiles store the device pool under the legacy "anonymousIds" key
+SELECT unnest("anonymousIds") AS device_id, distinct_id FROM users;
+
+CREATE OR REPLACE VIEW ev AS
+-- ::VARCHAR casts — user_id sniffs as UUID, device_id as VARCHAR; DuckDB
+-- refuses to coalesce mixed types
+SELECT coalesce(m.distinct_id::VARCHAR, e.user_id::VARCHAR, e.device_id::VARCHAR) AS uid,
+       e.time::TIMESTAMP AS t,
+       e.*
+FROM read_json_auto('data/verify-travel-EVENTS*.json', sample_size=-1, union_by_name=true) e
+LEFT JOIN device_map m ON e.device_id = m.device_id;
+
+-- Per-user counts. Bookings are only ever DELETED post-generation (H8
+-- all-or-nothing per user, H10 post-day-60, future-time guard), so
+-- booking-count cohorts are ONE-SIDED: output >= threshold implies
+-- hook-time >= threshold. hotel viewed / searches / sessions / reviews /
+-- upgrades are never deleted — exact hook-time recovery.
+CREATE OR REPLACE VIEW per_user AS
+SELECT uid,
+  count(*) FILTER (WHERE event = 'hotel viewed') AS hv,
+  count(*) FILTER (WHERE event = 'booking completed') AS bookings,
+  count(*) FILTER (WHERE event = 'destination searched') AS searches,
+  count(*) FILTER (WHERE event = 'app session') AS sessions,
+  count(*) FILTER (WHERE event = 'room upgrade selected') AS upgrades,
+  count(*) FILTER (WHERE event = 'review submitted') AS reviews
+FROM ev GROUP BY 1;
+
+CREATE OR REPLACE VIEW first_ev AS
+SELECT uid, min(t) AS f FROM ev GROUP BY 1;
+
+-- Calendar landmarks (dataset 2026-01-01 → 2026-05-01 23:59:59 UTC):
+--   advance-stamped region:      t <  '2026-04-08 23:59:59'  (H2, >21d before end + margin)
+--   organic middle band:         t in ['2026-04-11 23:59:59', '2026-04-27 23:59:59']
+--   last_minute-stamped region:  t >= '2026-04-29 00:59:59'  (<3d before end + margin)
+--   H10 fatigue cutoff (day 60): t >= '2026-03-02 00:00:00'
+
+
+-- ── H1-weekend-rate-surge ───────────────────────────────────
+-- Fri/Sat/Sun 'booking completed' nightly_rate ×1.3 (floored). 'hotel
+-- viewed' carries the same nightly_rate pool untouched — the placebo arm.
+-- dayofweek(): Sunday = 0 (matches JS getUTCDay).
+SELECT event,
+  CASE WHEN dayofweek(t) IN (0, 5, 6) THEN 'wkn' ELSE 'wkd' END AS bucket,
+  count(*) AS n, round(avg(nightly_rate), 1) AS avg_rate
+FROM ev WHERE event IN ('booking completed', 'hotel viewed') AND nightly_rate IS NOT NULL
+GROUP BY 1, 2 ORDER BY 1, 2;
+-- read: booking wkn/wkd ≈ 1.3; hotel viewed ≈ 1.0
+
+
+-- ── H2-booking-window ───────────────────────────────────────
+-- H2 stamps by calendar distance to dataset end: advance (>21d, rate ×0.8),
+-- last_minute (<3d, rate ×1.4). The 3-21d middle band keeps ORGANIC labels
+-- (2/5 advance, 2/5 standard, 1/5 last_minute) and untouched rates — a
+-- label breakdown DILUTES both treated labels; read by calendar REGION
+-- with the middle band as baseline instead.
+SELECT CASE WHEN t < TIMESTAMP '2026-04-08 23:59:59' THEN 'adv'
+            WHEN t >= TIMESTAMP '2026-04-29 00:59:59' THEN 'lm'
+            WHEN t >= TIMESTAMP '2026-04-11 23:59:59' AND t <= TIMESTAMP '2026-04-27 23:59:59' THEN 'mid' END AS region,
+  count(*) AS n, round(avg(nightly_rate), 1) AS avg_rate,
+  round(count(*) FILTER (WHERE booking_window = 'advance')::DOUBLE / count(*), 4) AS adv_share,
+  round(count(*) FILTER (WHERE booking_window = 'last_minute')::DOUBLE / count(*), 4) AS lm_share
+FROM ev WHERE event = 'booking completed'
+GROUP BY 1 ORDER BY 1;
+-- read: adv/mid avg_rate ≈ 0.80 (weekend-mix corrected); lm/mid ≈ 1.36;
+--       stamped regions label-pure (adv_share / lm_share = 1.0), middle
+--       band keeps organic adv_share ≈ 0.4
+
+
+-- ── H3-loyalty-boost ────────────────────────────────────────
+-- >=5 bookings at hook time → loyalty_points ×(2.5 + U[0,1]) floored,
+-- E[mult] = 3.0. Output >=5 IMPLIES treatment (deletions-only); control
+-- 1-4 bookings AND hv <= 10 (H10 never drops their bookings).
+SELECT CASE WHEN p.bookings >= 5 THEN 'big'
+            WHEN p.bookings BETWEEN 1 AND 4 AND p.hv <= 10 THEN 'small' END AS arm,
+  count(DISTINCT p.uid) AS users, round(avg(e.loyalty_points), 2) AS avg_lp
+FROM per_user p JOIN ev e ON e.uid = p.uid AND e.event = 'booking completed'
+WHERE p.bookings >= 5 OR (p.bookings BETWEEN 1 AND 4 AND p.hv <= 10)
+GROUP BY 1 ORDER BY 1;
+-- read: big/small avg_lp ≈ 3.0
+
+
+-- ── H4-cancel-by-window ─────────────────────────────────────
+-- Each 'booking cancelled' is stamped with the booking_window of the
+-- user's nearest PRECEDING booking, then 60% of last_minute-stamped
+-- cancels are dropped. Replicate the matching with an ASOF JOIN; restrict
+-- to matched bookings in the organic middle band (labels iid 0.4/0.4/0.2)
+-- for hv <= 10 users (their output booking set = hook-time set).
+WITH bk AS (SELECT uid, t, booking_window FROM ev WHERE event = 'booking completed'),
+cn AS (
+  SELECT e.uid, e.t, e.booking_window AS stamped
+  FROM ev e JOIN per_user p ON p.uid = e.uid AND p.hv <= 10
+  WHERE e.event = 'booking cancelled'
+),
+m AS (
+  SELECT cn.uid, cn.stamped, bk.booking_window AS matched, bk.t AS bt
+  FROM cn ASOF JOIN bk ON cn.uid = bk.uid AND cn.t >= bk.t
+)
+SELECT matched AS label, count(*) AS n,
+  round(count(*) FILTER (WHERE stamped = matched)::DOUBLE / count(*), 4) AS agree
+FROM m
+WHERE bt >= TIMESTAMP '2026-04-11 23:59:59' AND bt <= TIMESTAMP '2026-04-27 23:59:59'
+GROUP BY 1 ORDER BY 1;
+-- read: keep = (lm_n / std_n) / 0.5 ≈ 0.4 (the 40% keep rate);
+--       adv_n / std_n ≈ 1.0 (placebo); agree ≈ 1.0 (ASOF replicates hook)
+
+
+-- ── H5-luxury-upsell ────────────────────────────────────────
+-- luxury_seeker with an upgrade template: 50% cloned 'room upgrade
+-- selected' per booking → +0.5 upgrades-per-booking ADDITIVE. Both arms
+-- restricted to template owners and PRE-day-60 counts (H10's post-day-60
+-- booking drop would shrink over-viewers' denominators).
+SELECT u.customer_segment AS seg, count(DISTINCT pr.uid) AS users,
+  round(sum(pr.upgrades_pre)::DOUBLE / sum(pr.bookings_pre), 4) AS upgrades_per_booking
+FROM (
+  SELECT uid,
+    count(*) FILTER (WHERE event = 'booking completed' AND t < TIMESTAMP '2026-03-02') AS bookings_pre,
+    count(*) FILTER (WHERE event = 'room upgrade selected' AND t < TIMESTAMP '2026-03-02') AS upgrades_pre
+  FROM ev GROUP BY 1
+) pr
+JOIN per_user p ON p.uid = pr.uid AND p.upgrades >= 1
+JOIN users u ON u.distinct_id::VARCHAR = pr.uid
+WHERE u.customer_segment IN ('luxury_seeker', 'budget_hunter') AND pr.bookings_pre >= 1
+GROUP BY 1 ORDER BY 1;
+-- read: lux − budget ≈ +0.5 (plus small positive organic funnel-gap confound)
+
+-- doc-level Insights view: upgrades per user across ALL users
+SELECT u.customer_segment AS seg, count(*) AS users,
+  round(avg(coalesce(p.upgrades, 0)), 3) AS avg_upgrades
+FROM users u LEFT JOIN per_user p ON p.uid = u.distinct_id::VARCHAR
+WHERE u.customer_segment IN ('luxury_seeker', 'budget_hunter')
+GROUP BY 1 ORDER BY 1;
+-- read: lux/budget ≈ 12x — the +0.5 additive clone term dominates the thin
+--       organic upsell base (~0.08 upb); the knob-clean read is the
+--       upgrades-per-booking DIFFERENCE above
+
+
+-- ── H6-review-quality ───────────────────────────────────────
+-- Per-user avg stay_rating >= 4 → review_length ×1.5; <= 2 → ×0.5.
+-- Reviews are never deleted/cloned → output avg EXACTLY reproduces the
+-- hook-time classification (arm = the treatment variable itself).
+WITH rv AS (SELECT uid, avg(stay_rating) AS avg_r FROM ev WHERE event = 'review submitted' GROUP BY 1)
+SELECT CASE WHEN rv.avg_r >= 4 THEN 'high' WHEN rv.avg_r <= 2 THEN 'low' ELSE 'mid' END AS arm,
+  count(DISTINCT rv.uid) AS users, round(avg(e.review_length), 1) AS avg_len
+FROM rv JOIN ev e ON e.uid = rv.uid AND e.event = 'review submitted'
+GROUP BY 1 ORDER BY 1;
+-- read: high/mid ≈ 1.5; low/mid ≈ 0.5
+
+
+-- ── H7-business-profile ─────────────────────────────────────
+-- user hook overwrites per segment: business gets company_name (never
+-- 'none') + travel_frequency 'weekly'; luxury avg_budget U-int[250,500];
+-- budget U-int[50,120]; everyone else keeps company_name 'none'.
+SELECT customer_segment AS seg, count(*) AS users,
+  round(avg((travel_frequency = 'weekly')::INT), 4) AS weekly_share,
+  round(avg((company_name IS NOT NULL AND company_name <> 'none')::INT), 4) AS company_share,
+  min(avg_budget_per_night) AS min_budget, max(avg_budget_per_night) AS max_budget
+FROM users GROUP BY 1 ORDER BY 1;
+-- read: biz weekly_share = company_share = 1.0; others company_share = 0;
+--       lux budget within [250, 500]; budget_hunter within [50, 120]
+
+
+-- ── H8-casual-booking-drop ──────────────────────────────────
+-- leisure_family/budget_hunter: 25% per-user chance ALL bookings spliced
+-- out. Among users with >= 10 searches (exact activity floor), treated
+-- zero-booking share inflates by ~0.25 plus the organic conversion gap.
+SELECT CASE WHEN u.customer_segment IN ('leisure_family', 'budget_hunter') THEN 'treated' ELSE 'control' END AS arm,
+  count(*) AS users, round(avg((p.bookings = 0)::INT), 4) AS zero_booking_share
+FROM per_user p JOIN users u ON u.distinct_id::VARCHAR = p.uid
+WHERE p.searches >= 10
+GROUP BY 1 ORDER BY 1;
+-- read: treated − control ≈ +0.22-0.30; control ≈ <= 0.12
+
+
+-- ── H9-booking-ttc ──────────────────────────────────────────
+-- funnel-post scales Search to Book gaps: business ×0.74, budget/leisure
+-- ×1.25, luxury untouched (v1.6 scopes the hook to Search to Book only).
+-- CAUTION: cross-event TTC SQL here is the documented greedy-single-pass
+-- limitation — it pairs searches/bookings across funnel instances and
+-- buries the signal. The story asserts TTC through the Mixpanel-aligned
+-- emulator (timeToConvert, 60h window = 48h generative × 1.25 max
+-- stretch); trust the story verdict, not ad-hoc pair SQL.
+SELECT u.customer_segment AS seg, count(*) AS booking_events
+FROM ev e JOIN users u ON u.distinct_id::VARCHAR = e.uid
+WHERE e.event = 'booking completed' GROUP BY 1 ORDER BY 1;
+
+
+-- ── H10-hotel-view-magic ────────────────────────────────────
+-- Sweet spot 5-10 hotel views → nightly_rate ×1.3 on all bookings; 11+
+-- views → 35% of bookings dropped on/after day 60 (2026-03-02). Value
+-- read restricted to the ADVANCE region where H2's ×0.8 is constant on
+-- both arms and cancels.
+SELECT CASE WHEN p.hv BETWEEN 5 AND 10 THEN 'sweet' WHEN p.hv < 5 THEN 'low' END AS arm,
+  count(DISTINCT p.uid) AS users, round(avg(e.nightly_rate), 1) AS avg_rate
+FROM per_user p JOIN ev e ON e.uid = p.uid AND e.event = 'booking completed'
+WHERE (p.hv <= 10) AND e.t < TIMESTAMP '2026-04-08 23:59:59'
+GROUP BY 1 ORDER BY 1;
+-- read: sweet/low avg_rate ≈ 1.3
+
+-- volume read: hotel-view count is intrinsically coupled to activity, so
+-- NO cross-arm level comparison works. The day-60 calendar edge makes it
+-- a difference-in-differences: each arm's own after/before
+-- bookings-per-session ratio cancels its activity composition; worldEvents
+-- (summer sale ×2, hurricane ×0.2) are arm-invariant and cancel cross-arm.
+-- Users born before day 45 only, so both arms have real before-exposure.
+SELECT CASE WHEN p.hv BETWEEN 5 AND 10 THEN 'sweet' WHEN p.hv >= 11 THEN 'over' END AS arm,
+  CASE WHEN e.t >= TIMESTAMP '2026-03-02' THEN 'after' ELSE 'before' END AS period,
+  count(DISTINCT p.uid) AS users,
+  count(*) FILTER (WHERE e.event = 'booking completed') AS bookings,
+  count(*) FILTER (WHERE e.event = 'app session') AS sessions
+FROM per_user p
+JOIN first_ev fe ON fe.uid = p.uid AND fe.f < TIMESTAMP '2026-02-15'
+JOIN ev e ON e.uid = p.uid
+WHERE p.hv >= 5
+GROUP BY 1, 2 ORDER BY 1, 2;
+-- read: DiD = (over after/before bookings-per-session) ÷ (sweet after/before)
+--       ≈ 0.65 (the keep rate)

package/dungeons/vertical/travel/travel.verify.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * travel.verify.mjs — thin wrapper around the story runner.
+ *
+ * All verification logic lives in the `stories` export of ./travel.js;
+ * this script just streams the shards and delegates. It is equivalent to:
+ *
+ *   node scripts/verify-stories.mjs dungeons/vertical/travel/travel.js --data-prefix verify-travel
+ *
+ * Generate first:
+ *   node scripts/verify-runner.mjs dungeons/vertical/travel/travel.js verify-travel
+ * Run:
+ *   node dungeons/vertical/travel/travel.verify.mjs [prefix]   # default verify-travel
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { buildIdentityMap, evaluateStories, VERDICT_RANK } from '@ak--47/dungeon-master/verify';
+import config, { stories } from './travel.js';
+
+const PREFIX = process.argv[2] || 'verify-travel';
+const prefixPath = path.join('data', PREFIX);
+
+async function loadShards(suffix) {
+	// streaming load: full-fidelity EVENTS shards exceed the readFileSync cap
+	const dir = path.dirname(prefixPath), base = path.basename(prefixPath);
+	const out = [];
+	if (!fs.existsSync(dir)) return out;
+	for (const f of fs.readdirSync(dir).filter(f => f.startsWith(`${base}-${suffix}`) && f.endsWith('.json')).sort()) {
+		const rl = readline.createInterface({ input: fs.createReadStream(path.join(dir, f)), crlfDelay: Infinity });
+		for await (const line of rl) {
+			if (line.trim()) out.push(JSON.parse(line));
+		}
+	}
+	return out;
+}
+
+const events = await loadShards('EVENTS');
+const profiles = await loadShards('USERS');
+if (!events.length) {
+	console.error(`no shards at ${prefixPath}-EVENTS*.json — run: node scripts/verify-runner.mjs dungeons/vertical/travel/travel.js ${PREFIX}`);
+	process.exit(1);
+}
+console.log(`travel — events=${events.length} users=${profiles.length} (${prefixPath})`);
+
+const execFileP = promisify(execFile);
+const runSql = async (sql) => {
+	const { stdout } = await execFileP('duckdb', ['-json', '-c', sql.replaceAll('{{PREFIX}}', prefixPath)], { maxBuffer: 64 * 1024 * 1024 });
+	return stdout.trim() ? JSON.parse(stdout) : [];
+};
+
+// funnels passed raw (unvalidated) — the H8/H9 emulator stories carry their
+// own explicit conversion windows (72h Onboarding; 48h Search to Book
+// generative window × the 1.25 budget/leisure stretch = 60h, covering the
+// stretched support), so no funnel-default threading is needed
+const results = await evaluateStories(stories, events, {
+	profiles,
+	funnels: config.funnels,
+	identityMap: buildIdentityMap(profiles),
+	runSql,
+});
+
+let worst = 'NAILED';
+for (const r of results) {
+	console.log(`${r.verdict.padEnd(7)} ${r.id}`);
+	for (const a of r.assertions) console.log(`        ${a.verdict.padEnd(7)} ${a.detail}`);
+	if (VERDICT_RANK[r.verdict] < VERDICT_RANK[worst]) worst = r.verdict;
+}
+console.log(`\nworst verdict: ${worst}`);
+process.exit(VERDICT_RANK[worst] >= VERDICT_RANK.STRONG ? 0 : 1);

package/index.js

@@ -27,7 +27,7 @@ import { makeMirror } from './lib/generators/mirror.js';
 import { makeGroupProfile, makeProfile } from './lib/generators/profiles.js';
 
 // Utilities
-import { initChance, initUserChance, resetUserChance, setDatasetNow, setDatasetBegin, deleteFile } from './lib/utils/utils.js';
+import { initChance, initUserChance, resetUserChance, resetValueCaches, setDatasetNow, setDatasetBegin, deleteFile } from './lib/utils/utils.js';
 import { runWithDataset } from './lib/utils/dataset-context.js';
 
 // External dependencies
@@ -68,7 +68,7 @@ dayjs.extend(utc);
  *
  * @example
  * // multiple dungeons
- * const results = await DUNGEON_MASTER(['./dungeons/vertical/gaming.js', './dungeons/vertical/media.js']);
+ * const results = await DUNGEON_MASTER(['./dungeons/vertical/gaming/gaming.js', './dungeons/vertical/media/media.js']);
  *
  * @example
  * // raw JS text
@@ -130,6 +130,10 @@ async function runDungeon(config) {
 		// Initialize seeded RNG BEFORE validation — config-validator captures a
 		// chance reference for default userProps (spiritAnimal). If we init after,
 		// run 1 binds an unseeded instance while run 2 binds a stale one → non-deterministic.
+		// v1.6.1: clear per-run winner/weighted-array caches unconditionally —
+		// a prior in-process run must never leak its winners into this one.
+		// (initChance also clears them, but only fires when a seed is set.)
+		resetValueCaches();
 		if (config.seed) {
 			initChance(config.seed);
 		}
@@ -568,7 +572,7 @@ function extractFileInfo(storage) {
 /**
  * Count profiles that would be pushed to Mixpanel (anonymous non-converters carry
  * `_drop: true` and are skipped by mixpanel-sender). v1.5.1.
- * @param {any} profilesContainer
+ * @param {Iterable<{ _drop?: boolean }> | null | undefined} profilesContainer
  * @returns {number}
  */
 function countProfilesPushed(profilesContainer) {

package/lib/core/config-validator.js

@@ -378,7 +378,10 @@ function normalizeExperiments(funnels, datasetEndUnix) {
 		const startDays = Number.isFinite(raw.startDaysBeforeEnd) && raw.startDaysBeforeEnd > 0
 			? raw.startDaysBeforeEnd : 0;
 		const startUnix = startDays > 0 ? datasetEndUnix - startDays * 86400 : null;
-		f._experiment = { name, variants, startUnix };
+		// Sticky bucketing defaults true — the per-user hash was the only pre-1.6
+		// behavior, so existing dungeons stay byte-identical.
+		const sticky = raw.sticky === undefined ? true : !!raw.sticky;
+		f._experiment = { name, variants, startUnix, sticky };
 	}
 }
 
@@ -568,7 +571,25 @@ export function validateDungeonConfig(config) {
 	// only avgEventsPerUserPerDay would never trigger auto-batch.
 	if (numEvents >= 2_000_000 && config.batchSize === undefined) {
 		batchSize = 1_000_000;
-		if (verbose) console.warn(`⚠️  Auto-enabling batch mode: numEvents (${numEvents.toLocaleString()}) >= 2M. Using batchSize of ${batchSize.toLocaleString()}.`);
+		// Width-aware shrink: wide event schemas (many props/event) cost far more
+		// live memory per buffered event, so a 1M-event batch can exceed the default
+		// ~4GB heap and OOM mid-generation (batch mode is supposed to PREVENT that).
+		// Estimate a volume-weighted props/event and cap the batch so its peak buffer
+		// stays ~1.4GB. Narrow schemas keep the full 1M batch (no behavior change).
+		const evs = Array.isArray(config.events) ? config.events : [];
+		const superN = config.superProps ? Object.keys(config.superProps).length : 0;
+		let wSum = 0, wpSum = 0;
+		for (const e of evs) {
+			const w = (e && typeof e.weight === "number" && e.weight > 0) ? e.weight : 1;
+			const pN = (e && e.properties && typeof e.properties === "object") ? Object.keys(e.properties).length : 0;
+			wSum += w; wpSum += w * pN;
+		}
+		const avgOwnProps = wSum > 0 ? wpSum / wSum : 0;
+		const avgPropsPerEvent = avgOwnProps + superN + 10; // + core/identity/location/device estimate
+		const estBytesPerEvent = Math.max(400, Math.round(avgPropsPerEvent * 150));
+		const memSafeBatch = Math.max(100_000, Math.floor(1_400_000_000 / estBytesPerEvent));
+		if (avgPropsPerEvent > 18 && memSafeBatch < batchSize) batchSize = memSafeBatch;
+		if (verbose) console.warn(`⚠️  Auto-enabling batch mode: numEvents (${numEvents.toLocaleString()}) >= 2M (~${Math.round(avgPropsPerEvent)} props/event). Using batchSize of ${batchSize.toLocaleString()}.`);
 	}
 
 	// Resolve soup presets (intra-week / intra-day shape — must happen after numDays is computed)
@@ -1067,6 +1088,12 @@ function transformSCDPropsWithoutCredentials(config) {
 
 // ── Advanced Feature Validation Functions ──
 
+// P2.5 (v1.6): churnRate / activeWindow / soupOverride are declared Persona
+// surface but unimplemented — nothing in lib/ reads them after validation.
+// Deprecated no-ops; warn once per process when a dungeon sets any of them.
+const DEAD_PERSONA_FIELDS = ['churnRate', 'activeWindow', 'soupOverride'];
+let warnedDeadPersonaFields = false;
+
 /**
  * Validates persona configurations
  * @param {import('../../types').Persona[]} personas
@@ -1074,14 +1101,22 @@ function transformSCDPropsWithoutCredentials(config) {
  */
 function validatePersonas(personas) {
 	if (!Array.isArray(personas) || personas.length === 0) return null;
+	const deadFieldsSet = new Set();
 	for (const p of personas) {
 		if (!p.name) throw new Error('Each persona must have a name');
 		if (typeof p.weight !== 'number' || p.weight <= 0) throw new Error(`Persona "${p.name}" must have a positive weight`);
+		for (const field of DEAD_PERSONA_FIELDS) {
+			if (p[field] !== undefined) deadFieldsSet.add(field);
+		}
 		if (p.eventMultiplier === undefined) p.eventMultiplier = 1.0;
 		if (p.conversionModifier === undefined) p.conversionModifier = 1.0;
 		if (p.churnRate === undefined) p.churnRate = 0;
 		if (p.properties === undefined) p.properties = {};
 	}
+	if (deadFieldsSet.size > 0 && !warnedDeadPersonaFields) {
+		warnedDeadPersonaFields = true;
+		console.warn(`[dungeon-master] Persona field(s) ${[...deadFieldsSet].join(', ')} are deprecated and unimplemented — they have no effect on generation. This warning fires once per process.`);
+	}
 	return personas;
 }
 

package/lib/core/context.js

@@ -109,10 +109,12 @@ function createProgressReporter(config) {
 		}
 
 		try {
-			const result = /** @type {any} */ (callback(update));
+			// onProgress is declared `=> void`, but async callbacks returning a
+			// promise are supported — duck-type the thenable at runtime.
+			const result = /** @type {Promise<unknown> | undefined} */ (/** @type {unknown} */ (callback(update)));
 			totalUpdates++;
 			if (result && typeof result.then === 'function') {
-				result.then(undefined, (/** @type {any} */ err) => {
+				result.then(undefined, (/** @type {Error} */ err) => {
 					errorCount++;
 					if (verbose) console.warn(`[dungeon-master] onProgress async error (${errorCount}/3): ${err?.message || err}`);
 					if (errorCount >= 3) disabled = true;

package/lib/core/dungeon-loader.js

@@ -11,8 +11,11 @@ import Chance from 'chance';
 
 /**
  * Detect what kind of input was passed and normalize it
- * @param {any} input - The raw input to DUNGEON_MASTER
- * @returns {{ type: 'object' | 'file' | 'files' | 'text', value: any }}
+ * @param {unknown} input - The raw input to DUNGEON_MASTER
+ * @returns {{ type: 'object', value: import('../../types').Dungeon }
+ *         | { type: 'file', value: string }
+ *         | { type: 'files', value: string[] }
+ *         | { type: 'text', value: string }}
  */
 export function detectInputType(input) {
 	if (input === null || input === undefined) {
@@ -29,12 +32,12 @@ export function detectInputType(input) {
 				throw new Error(`dungeon-master: array items must be file path strings. got ${typeof item}.`);
 			}
 		}
-		return { type: 'files', value: input };
+		return { type: 'files', value: /** @type {string[]} */ (input) };
 	}
 
 	// Plain config object
 	if (typeof input === 'object') {
-		return { type: 'object', value: input };
+		return { type: 'object', value: /** @type {import('../../types').Dungeon} */ (input) };
 	}
 
 	// String: file path or raw JS text
@@ -128,7 +131,7 @@ export function parseJSONDungeon(json) {
 	const hooksString = json.hooks || null;
 
 	// Reconstruct the config from the JSON schema
-	const config = reviveJSONConfig(schema);
+	const config = /** @type {Record<string, unknown>} */ (reviveJSONConfig(schema));
 
 	// Attach hook if present
 	if (hooksString && typeof hooksString === 'string') {
@@ -136,14 +139,14 @@ export function parseJSONDungeon(json) {
 	}
 
 	validateDungeonShape(config);
-	return config;
+	return /** @type {import('../../types').Dungeon} */ (config);
 }
 
 /**
  * Revive JSON config by converting function-call objects back to functions
  * JSON dungeons store functions as { functionName: "...", body: "...", args: [...] }
- * @param {any} value
- * @returns {any}
+ * @param {unknown} value
+ * @returns {unknown}
  */
 function reviveJSONConfig(value) {
 	if (value === null || value === undefined) return value;
@@ -152,8 +155,8 @@ function reviveJSONConfig(value) {
 	if (typeof value !== 'object') return value;
 
 	// Function-call objects → actual functions
-	if (value.functionName) {
-		return reviveFunctionObject(value);
+	if ('functionName' in value && value.functionName) {
+		return reviveFunctionObject(/** @type {{ functionName: string, body?: string, args?: unknown[] }} */ (value));
 	}
 
 	// Arrays
@@ -162,6 +165,7 @@ function reviveJSONConfig(value) {
 	}
 
 	// Objects
+	/** @type {Record<string, unknown>} */
 	const result = {};
 	for (const [key, val] of Object.entries(value)) {
 		result[key] = reviveJSONConfig(val);
@@ -178,8 +182,8 @@ function reviveJSONConfig(value) {
  * mostChosenIndex, etc.) that don't exist at revival time. These will fail to eval
  * and fall back to null, which is handled gracefully by the config validator.
  *
- * @param {{ functionName: string, body?: string, args?: any[] }} obj
- * @returns {Function|any[]|null}
+ * @param {{ functionName: string, body?: string, args?: unknown[] }} obj
+ * @returns {Function|unknown[]|null}
  */
 function reviveFunctionObject(obj) {
 	const { functionName, body, args = [] } = obj;
@@ -257,13 +261,14 @@ export async function loadFromText(code) {
 /**
  * Validate that a config object has the minimum shape of a dungeon
  * This is a pre-flight check before passing to the full config validator
- * @param {any} config
+ * @param {unknown} input
  * @throws {Error} if the config is clearly not a valid dungeon
  */
-export function validateDungeonShape(config) {
-	if (!config || typeof config !== 'object' || Array.isArray(config)) {
+export function validateDungeonShape(input) {
+	if (!input || typeof input !== 'object' || Array.isArray(input)) {
 		throw new Error('dungeon-master: config must be a plain object.');
 	}
+	const config = /** @type {Record<string, unknown>} */ (input);
 
 	// Must have at least one recognizable dungeon property
 	const dungeonKeys = [

package/lib/core/dungeon-to-json.js

@@ -16,6 +16,10 @@
  * is sampled at serialization time (when its closure is still live) and the inferred
  * output type is recorded as `dataType` (e.g. "number", "string", "boolean", "number[]").
  * So a field that loses its `weighNumRange(1,10)` generator still records `dataType: "number"`.
+ *
+ * A dungeon's `stories` NAMED export (v1.6 story layer) is NOT carried into the JSON —
+ * only the default-export config is serialized. The .js file remains the source of
+ * record for stories; verify-stories.mjs reads them from the module directly.
  */
 
 import { detectInputType, loadFromFile, loadFromText } from './dungeon-loader.js';
@@ -75,18 +79,31 @@ function serializeConfig(config, includeCredentials) {
 	}
 
 	return {
-		schema: convertToJSON(cleanConfig),
+		// cleanConfig is an object, so convertToJSON returns the map arm of JSONReady.
+		schema: /** @type {Record<string, unknown>} */ (convertToJSON(cleanConfig)),
 		hooks,
 		timestamp: new Date().toISOString(),
 		version: '4.0'
 	};
 }
 
+/**
+ * A JSON-serializable value: what `convertToJSON` produces. Functions become
+ * `SerializedFunction` markers; everything else is plain JSON.
+ * (Recursion goes through the named array/map aliases — TS rejects a JSDoc
+ * type alias that references itself directly in its own union.)
+ * @typedef {null | boolean | number | string
+ *         | import('../../types').SerializedFunction
+ *         | JSONReadyArray | JSONReadyMap} JSONReady
+ * @typedef {JSONReady[]} JSONReadyArray
+ * @typedef {{ [key: string]: JSONReady }} JSONReadyMap
+ */
+
 /**
  * Convert a JavaScript value to a JSON-serializable form, turning functions into
  * `{ functionName, body | args }` objects that `reviveJSONConfig` can revive.
- * @param {any} value
- * @returns {any}
+ * @param {unknown} value
+ * @returns {JSONReady}
  */
 export function convertToJSON(value) {
 	// Null/undefined
@@ -111,6 +128,7 @@ export function convertToJSON(value) {
 
 	// Objects
 	if (typeof value === 'object') {
+		/** @type {{ [key: string]: JSONReady }} */
 		const result = {};
 		for (const [key, val] of Object.entries(value)) {
 			result[key] = convertToJSON(val);
@@ -202,7 +220,7 @@ function inferDataType(func) {
 /**
  * Map a sampled value to a type label: "number" | "string" | "boolean" | "date" |
  * "object" | "<elementType>[]" | "array". Returns undefined for null/undefined/functions.
- * @param {any} value
+ * @param {unknown} value
  * @returns {string | undefined}
  */
 function classifyValue(value) {

package/lib/core/storage.js

@@ -245,9 +245,9 @@ export async function createHookArray(arr = [], opts) {
 		}
 	}
 
-	// Enhance the array with our methods
-	/** @type {HookedArray} */
-	const enrichedArray = /** @type {any} */ (arr);
+	// Enhance the array with our methods (plain array → HookedArray, methods
+	// attached just below — hence the through-unknown assertion)
+	const enrichedArray = /** @type {HookedArray} */ (/** @type {unknown} */ (arr));
 	enrichedArray.hookPush = transformThenPush;
 	enrichedArray.flush = flush;
 	enrichedArray.getWriteDir = getWriteDir;