@ak--47/dungeon-master 1.2.3 → 1.3.1

package/scripts/verify-runner.mjs

@@ -1,42 +1,90 @@
 /**
- * Verify Runner — runs a dungeon at constrained params for hook verification.
+ * Verify Runner — runs a dungeon for hook verification.
  *
- * Usage: node scripts/verify-runner.mjs <dungeon-path> [run-name]
+ * Default mode: FULL FIDELITY — runs the dungeon with its own configured
+ *   numUsers / avgEventsPerUserPerDay / numDays. This is the only way to
+ *   verify the trends a benchmark consumer will actually see.
  *
- * Example: node scripts/verify-runner.mjs dungeons/streaming.js verify-streaming
+ * --small mode: ~1K users with avgEventsPerUserPerDay scaled proportionally
+ *   so total events stay near 100K. Use only for fast smoke checks; do NOT
+ *   ship verification verdicts based on --small runs.
+ *
+ * Usage:
+ *   node scripts/verify-runner.mjs <dungeon-path> [run-name] [--small]
+ *
+ * Examples:
+ *   node scripts/verify-runner.mjs dungeons/vertical/gaming.js verify-gaming
+ *   node scripts/verify-runner.mjs dungeons/vertical/gaming.js verify-gaming --small
  */
 import generate from '../index.js';
 import path from 'path';
 
-const dungeonPath = process.argv[2];
+const args = process.argv.slice(2);
+const flags = new Set(args.filter(a => a.startsWith('--')));
+const positional = args.filter(a => !a.startsWith('--'));
+
+const dungeonPath = positional[0];
 if (!dungeonPath) {
-	console.error('Usage: node scripts/verify-runner.mjs <dungeon-path> [run-name]');
+	console.error('Usage: node scripts/verify-runner.mjs <dungeon-path> [run-name] [--small]');
 	process.exit(1);
 }
 
-const runName = process.argv[3] || 'verify-hooks';
+const runName = positional[1] || 'verify-hooks';
+const isSmall = flags.has('--small');
 const absolutePath = path.isAbsolute(dungeonPath)
-  ? dungeonPath
-  : path.resolve(process.cwd(), dungeonPath);
+	? dungeonPath
+	: path.resolve(process.cwd(), dungeonPath);
 
 const { default: config } = await import(absolutePath);
 
-const results = await generate({
-  ...config,
-  token: "",
-  numUsers: 1000,
-  numEvents: 100_000,
-  format: "json",
-  gzip: false,
-  writeToDisk: true,
-  name: runName,
-  concurrency: 1,
-  verbose: false,
-});
+let override;
+
+if (isSmall) {
+	// SMALL mode: 1K users, scaled per-day rate so total events ≈ 100K.
+	// Preserves the dungeon's per-user-per-day shape while shrinking the dataset.
+	// Use only for quick smoke checks — verdicts must come from full fidelity.
+	const numUsers = 1000;
+	const numDays = config.numDays || 100;
+	const targetTotal = 100_000;
+	const scaledRate = targetTotal / (numUsers * numDays);
+	override = {
+		...config,
+		token: '',
+		numUsers,
+		numDays,
+		avgEventsPerUserPerDay: scaledRate,
+		numEvents: undefined,
+		format: 'json',
+		gzip: false,
+		writeToDisk: true,
+		name: runName,
+		concurrency: 1,
+		verbose: false,
+	};
+} else {
+	// FULL FIDELITY: use the dungeon's own scale settings as-shipped.
+	// Full-scale runs can take minutes for 50K-user dungeons; that's expected.
+	override = {
+		...config,
+		token: '',
+		format: 'json',
+		gzip: false,
+		writeToDisk: true,
+		name: runName,
+		concurrency: config.concurrency || 1,
+		verbose: false,
+	};
+}
+
+const t0 = Date.now();
+const results = await generate(override);
+const wallMs = Date.now() - t0;
 
 console.log(JSON.stringify({
-  eventCount: results.eventCount,
-  userCount: results.userCount,
-  files: results.files,
-  duration: results.time?.human || results.time?.delta + 'ms'
+	mode: isSmall ? 'small' : 'full',
+	eventCount: results.eventCount,
+	userCount: results.userCount,
+	files: results.files,
+	duration: results.time?.human || `${wallMs}ms`,
+	wallMs,
 }));

package/types.d.ts

@@ -1,10 +1,14 @@
 /**
- * most of the time, the value of a property is a primitive
+ * Primitive scalar types that property values resolve to. Property values may
+ * also be plain object literals (nested records) — `Record<string, any>` is the
+ * narrowest TS can express here without making `Primitives` self-recursive
+ * (which it can't be, because `ValueValid` is built on top of it).
  */
 type Primitives = string | number | boolean | Date | Record<string, any>;
 
 /**
- * a "validValue" can be a primitive, an array of primitives, or a function that returns a primitive
+ * A "validValue" can be a primitive, an array of valid values, or a thunk that
+ * returns one. Configs use this everywhere properties are user-defined.
  */
 export type ValueValid = Primitives | ValueValid[] | (() => ValueValid);
 
@@ -17,16 +21,29 @@ export interface Dungeon {
     token?: string;
     /** RNG seed for reproducible output. Same seed + concurrency=1 = identical data. */
     seed?: string;
-    /** Number of days the dataset spans (from "now" looking backward). Default: 30 */
+    /** Number of days the dataset spans. Used as fallback when datasetStart/datasetEnd are NOT both set — window becomes (today_start - numDays, today_start). Default: 30. When datasetStart/datasetEnd ARE both set, numDays is recomputed from the window and any user-supplied value is ignored (with a warning). */
     numDays?: number;
-    /** Explicit start of dataset window (unix seconds). Alternative to numDays. */
+    /**
+     * Explicit start of the dataset window. Pin BOTH `datasetStart` and `datasetEnd` for
+     * bit-exact deterministic runs. Accepts ISO string ("2026-01-01T00:00:00Z"), unix
+     * seconds (1735689600), unix milliseconds (1735689600000), or anything `dayjs()`
+     * can parse. Setting only one of datasetStart/datasetEnd throws.
+     */
+    datasetStart?: string | number;
+    /**
+     * Explicit end of the dataset window. See `datasetStart` — both must be set together.
+     */
+    datasetEnd?: string | number;
+    /** @deprecated Legacy alias internally aliased to datasetStart on validated config. Prefer `datasetStart`. */
     epochStart?: number;
-    /** Explicit end of dataset window (unix seconds). Defaults to FIXED_NOW. */
+    /** @deprecated Legacy alias internally aliased to datasetEnd on validated config. Prefer `datasetEnd`. */
     epochEnd?: number;
-    /** Target total number of events to generate across all users. */
+    /** Target total number of events to generate across all users. Fallback when avgEventsPerUserPerDay is not set; otherwise derived from rate × numUsers × numDays. */
     numEvents?: number;
     /** Number of unique users to generate. */
     numUsers?: number;
+    /** Average events per user per active day. The canonical event-volume primitive — born-late users get this rate × their remaining window, so per-day density stays constant. If both this and numEvents are set, this wins. */
+    avgEventsPerUserPerDay?: number;
     /** Output format for files written to disk. */
     format?: "csv" | "json" | "parquet" | string;
     /** Mixpanel data residency region. */
@@ -106,9 +123,11 @@ export interface Dungeon {
     groupEvents?: GroupEventConfig[];
     /** Lookup table definitions for dimension tables. */
     lookupTables?: LookupTableSchema[];
-    /** TimeSoup configuration: controls the temporal distribution of events (peaks, deviation, mean). */
+    /** TimeSoup configuration: shapes intra-week and intra-day rhythm (peaks, deviation, DOW/HOD weights). Pair with `macro` for big-picture trend control. */
     soup?: soup;
-    /** Hook function called on every data point. The primary mechanism for engineering deliberate trends and patterns. */
+    /** Macro trend shape across the full dataset window: birth distribution + per-user event allocation. Default: "flat". Use "growth"/"viral"/"steady"/"decline" or a custom object. */
+    macro?: macro;
+    /** Hook function called on every data point. The primary mechanism for engineering deliberate trends and patterns. The `any` is intentional — `record` and `meta` shapes vary by hook type; narrow inside the function (see `HookMeta*` types). */
     hook?: Hook<any>;
 
     // ── Advanced Features ──
@@ -135,10 +154,14 @@ export interface Dungeon {
     [key: string]: any;
 
     // ── Distribution Controls ──
-    /** Percentage of users whose account creation falls within the dataset window (vs. pre-existing). Default: 15 */
+    // These three knobs are normally set by the `macro` preset (default "flat").
+    // Setting them on the dungeon config directly overrides the preset's value.
+    /** Percentage of users whose account creation falls within the dataset window (vs. pre-existing). Default (from macro: "flat"): 15 */
     percentUsersBornInDataset?: number;
-    /** Bias toward recent birth dates for users born in dataset (0 = uniform, 1 = heavily recent). Default: 0.3 */
+    /** Bias for birth dates of users born in dataset. -1..1; negative = early skew, positive = recent skew, 0 = uniform. Default (from macro: "flat"): 0 */
     bornRecentBias?: number;
+    /** How pre-existing users' first event time is placed. "pinned" stacks them all at FIXED_BEGIN; "uniform" spreads across [FIXED_BEGIN-30d, FIXED_BEGIN]. Default (from macro: "flat"): "uniform" */
+    preExistingSpread?: "pinned" | "uniform";
 }
 
 export type SCDProp = {
@@ -183,6 +206,43 @@ export type SoupConfig = {
  */
 type soup = SoupPreset | SoupConfig;
 
+/**
+ * Macro preset names for big-picture trend shape across the dataset window.
+ * Macro is orthogonal to soup: macro shapes the whole-window trend (births,
+ * growth, decline); soup shapes the intra-week and intra-day rhythm.
+ */
+export type MacroPreset = "flat" | "steady" | "growth" | "viral" | "decline";
+
+/**
+ * Macro configuration object — fine-grained big-picture trend control.
+ */
+export type MacroConfig = {
+    /** Use a named macro preset as the base, then override individual fields. */
+    preset?: MacroPreset;
+    /** Bias for birth dates. -1..1; negative = early skew, positive = recent skew, 0 = uniform. */
+    bornRecentBias?: number;
+    /** Percentage of users born in dataset window (0..100). */
+    percentUsersBornInDataset?: number;
+    /** "pinned" = pre-existing users stack at FIXED_BEGIN; "uniform" = spread across [FIXED_BEGIN-30d, FIXED_BEGIN]. */
+    preExistingSpread?: "pinned" | "uniform";
+};
+
+/** Big-picture trend shape: preset string, config object, or preset+overrides. */
+type macro = MacroPreset | MacroConfig;
+
+/** Public alias for the `soup` config union (preset string or config object). */
+export type Soup = soup;
+
+/** Public alias for the `macro` config union (preset string or config object). */
+export type Macro = macro;
+
+/** Resolved macro values after preset + override resolution. Used internally. */
+export interface ResolvedMacro {
+    bornRecentBias: number;
+    percentUsersBornInDataset: number;
+    preExistingSpread: "pinned" | "uniform";
+}
+
 /**
  * Hook types and when they fire (in order per user):
  * - "user"        — user profile object (mutate in-place, return ignored)
@@ -213,31 +273,141 @@ export type hookTypes =
 
 /**
  * A hook function that receives every piece of data as it flows through the pipeline.
- * @param record - The data being processed (event, profile, array of events, etc.)
- * @param type - Which hook type is firing
- * @param meta - Contextual metadata (varies by type; "everything" includes meta.profile and meta.scd)
+ *
+ * The runtime signature is intentionally permissive (`any`) because `record` and `meta`
+ * vary by `type`. Use the `HookMeta*` interfaces below as convenience types when narrowing
+ * inside your hook (e.g. `if (type === "event") { const m = meta as HookMetaEvent; ... }`).
+ *
+ * Return-value semantics:
+ * - "event": return value REPLACES the event (must be the event object).
+ * - "everything": return an array to REPLACE the user's event list (filter/inject/dedupe).
+ * - "user", "scd-pre", "funnel-pre", "funnel-post": return value is IGNORED — mutate in place.
+ * - storage-only ("ad-spend", "group", "mirror", "lookup"): return value is IGNORED.
+ *
+ * @param record - The data being processed (event, profile, array of events, funnel config, etc.).
+ * @param type - Which hook type is firing — see `hookTypes`.
+ * @param meta - Contextual metadata. Shape depends on `type` — see `HookMeta*` interfaces.
  */
 export type Hook<T> = (record: any, type: hookTypes, meta: any) => T;
 
+/**
+ * Time-window anchors present on every hook's `meta`. Use these to derive relative
+ * dates inside hooks (e.g. `dayjs.unix(meta.datasetStart).add(45, 'days')`). NEVER
+ * read wall-clock `dayjs()` inside a hook — it makes hooks non-deterministic.
+ */
+export interface HookMetaTimeAnchors {
+    /** Start of the dataset window (unix seconds). Same value the engine uses to bound event generation. */
+    datasetStart: number;
+    /** End of the dataset window (unix seconds). Same value the engine uses to bound event generation. */
+    datasetEnd: number;
+}
+
+/** Meta passed to the "event" hook. */
+export interface HookMetaEvent extends HookMetaTimeAnchors {
+    /** The user this event belongs to (only `distinct_id` is guaranteed). */
+    user: { distinct_id: string };
+    /** The fully-resolved dungeon config. */
+    config: Dungeon;
+}
+
+/** Meta passed to the "user" hook (fires when a user profile is created). */
+export interface HookMetaUser extends HookMetaTimeAnchors {
+    /** The user object being constructed (mutate in place). */
+    user: UserProfile;
+    /** The fully-resolved dungeon config. */
+    config: Dungeon;
+    /** True if the user's account creation falls inside the dataset window. */
+    userIsBornInDataset: boolean;
+}
+
+/** Meta passed to the "scd-pre" hook (fires per SCD prop, before insertion). */
+export interface HookMetaScdPre extends HookMetaTimeAnchors {
+    /** The user profile that owns these SCD entries. */
+    profile: UserProfile;
+    /** The SCD prop key being generated (e.g. "plan", "tier"). */
+    type: string;
+    /** The full SCD entry list for this prop (mutate in place). */
+    scd: SCDSchema[];
+    /** The fully-resolved dungeon config. */
+    config: Dungeon;
+    /** All SCD prop arrays generated so far for this user, keyed by prop name. */
+    allSCDs: Record<string, SCDSchema[]>;
+}
+
+/** Meta passed to the "funnel-pre" hook (mutate funnel before generating events). */
+export interface HookMetaFunnelPre extends HookMetaTimeAnchors {
+    user: { distinct_id: string };
+    profile: UserProfile;
+    scd: Record<string, SCDSchema[]>;
+    funnel: Funnel;
+    config: Dungeon;
+    /** Unix seconds — earliest possible event time for this funnel's first step. */
+    firstEventTime: number;
+}
+
+/** Meta passed to the "funnel-post" hook (mutate generated funnel events in place). */
+export interface HookMetaFunnelPost extends HookMetaTimeAnchors {
+    user: { distinct_id: string };
+    profile: UserProfile;
+    scd: Record<string, SCDSchema[]>;
+    funnel: Funnel;
+    config: Dungeon;
+}
+
+/** Meta passed to the "everything" hook — most powerful hook (sees all events for one user). */
+export interface HookMetaEverything extends HookMetaTimeAnchors {
+    /** The user's profile, including merged persona/region/attribution properties. */
+    profile: UserProfile;
+    /** All SCD entries for this user, keyed by prop name. */
+    scd: Record<string, SCDSchema[]>;
+    /** The fully-resolved dungeon config. */
+    config: Dungeon;
+    /** True if the user's account creation falls inside the dataset window. */
+    userIsBornInDataset: boolean;
+}
+
 export interface hookArrayOptions<T> {
+    /** Transform/validate function applied to every record on push. */
     hook?: Hook<T>;
+    /** What this array stores — controls hook-firing semantics in the storage layer. */
     type?: hookTypes;
+    /** Output filename (no extension; format adds it). Used by storage's batch writer. */
     filename?: string;
+    /** Output filepath used when writing batches to disk. */
+    filepath?: string;
+    /** Output serialization format. */
     format?: "csv" | "json" | "parquet" | string;
+    /** Max parallel disk writes. */
     concurrency?: number;
+    /** Generation context (config, runtime, defaults). */
     context?: Context;
-    [key: string]: any;
 }
 
 /**
- * an enriched array is an array that has a hookPush method that can be used to transform-then-push items into the array
+ * an enriched array is an array that has a hookPush method that can be used to transform-then-push items into the array.
+ *
+ * Storage callers also tag the array with a key identifying what it stores
+ * (e.g. SCD prop name, group key, lookup table key). The fields are optional
+ * because not every HookedArray needs them; mixpanel-sender / user-loop read
+ * them when present to route uploads correctly.
  */
 export interface HookedArray<T> extends Array<T> {
-    hookPush: (item: T | T[], ...meta: any[]) => Promise<any>;
+    /** Transform-then-push. Resolves once the item (and any auto-flushed batch) is persisted. */
+    hookPush: (item: T | T[], ...meta: unknown[]) => Promise<void>;
+    /** Force-flush any pending batch to disk. */
     flush: () => Promise<void>;
+    /** Absolute path of the directory batches will be written to. */
     getWriteDir: () => string;
+    /** Absolute path (with extension) of the next batch file. */
     getWritePath: () => string;
-    [key: string]: any;
+    /** SCD prop name this array carries (only set on SCD HookedArrays). */
+    scdKey?: string;
+    /** Entity type for SCDs ("user" or a group key). */
+    entityType?: string;
+    /** Group key this array carries (only set on group profile HookedArrays). */
+    groupKey?: string;
+    /** Lookup table key this array carries (only set on lookup table HookedArrays). */
+    lookupKey?: string;
 }
 
 export type AllData =
@@ -245,8 +415,7 @@ export type AllData =
     | HookedArray<UserProfile>
     | HookedArray<GroupProfileSchema>
     | HookedArray<LookupTableSchema>
-    | HookedArray<SCDSchema>
-    | any[];
+    | HookedArray<SCDSchema>;
 
 /**
  * the storage object is a key-value store that holds arrays of data
@@ -277,16 +446,33 @@ export interface RuntimeState {
 /**
  * Default data factories for generating realistic test data
  */
+/**
+ * Default data factories — pre-resolved at context creation time so user-loop
+ * doesn't re-evaluate weighted picker arrays on every iteration.
+ */
 export interface Defaults {
-    locationsUsers: () => any[];
-    locationsEvents: () => any[];
-    iOSDevices: () => any[];
-    androidDevices: () => any[];
-    desktopDevices: () => any[];
-    browsers: () => any[];
-    campaigns: () => any[];
-    devicePools: { android: any[]; ios: any[]; desktop: any[] };
-    allDevices: any[];
+    /** Location pools applied to user profiles (city, region, country, lat/lng). */
+    locationsUsers: () => Record<string, ValueValid>[];
+    /** Location pools applied to events. */
+    locationsEvents: () => Record<string, ValueValid>[];
+    /** iOS device pool (model, os version, etc.). */
+    iOSDevices: () => Record<string, ValueValid>[];
+    /** Android device pool. */
+    androidDevices: () => Record<string, ValueValid>[];
+    /** Desktop device pool (browser, screen resolution, etc.). */
+    desktopDevices: () => Record<string, ValueValid>[];
+    /** Browser/UA pool. */
+    browsers: () => Record<string, ValueValid>[];
+    /** UTM campaign pool used when `hasCampaigns: true`. */
+    campaigns: () => Record<string, ValueValid>[];
+    /** Pre-built per-platform device arrays selected once at context creation. */
+    devicePools: {
+        android: Record<string, ValueValid>[];
+        ios: Record<string, ValueValid>[];
+        desktop: Record<string, ValueValid>[];
+    };
+    /** Flat union of every device in `devicePools` — used when no platform filter applies. */
+    allDevices: Record<string, ValueValid>[];
 }
 
 /**
@@ -297,12 +483,17 @@ export interface Context {
     config: Dungeon;
     storage: Storage | null;
     defaults: Defaults;
-    campaigns: any[];
+    /** Pre-built UTM campaign pool (used when `hasCampaigns: true`). */
+    campaigns: Record<string, ValueValid>[];
     runtime: RuntimeState;
+    /** End of the resolved dataset window (unix seconds). Equal to the user-supplied `datasetEnd`, or fallback `today_start`. */
     FIXED_NOW: number;
+    /** Start of the resolved dataset window (unix seconds). Equal to the user-supplied `datasetStart`, or fallback `today_start - numDays`. */
     FIXED_BEGIN?: number;
-    TIME_SHIFT_SECONDS: number;
-    MAX_TIME: number;
+    /** Alias of `FIXED_BEGIN` — surfaced on hook `meta.datasetStart`. */
+    DATASET_START_SECONDS: number;
+    /** Alias of `FIXED_NOW` — surfaced on hook `meta.datasetEnd`. */
+    DATASET_END_SECONDS: number;
 
     // State update methods
     incrementOperations(): void;
@@ -319,10 +510,6 @@ export interface Context {
     incrementUserCount(): void;
     incrementEventCount(): void;
     isBatchMode(): boolean;
-
-    // Time helper methods
-    getTimeShift(): number;
-    getDaysShift(): number;
 }
 
 /**
@@ -494,7 +681,8 @@ export interface LookupTableSchema {
 
 export interface LookupTableData {
     key: string;
-    data: any[];
+    /** Generated rows for this lookup table. Each row is a flat record keyed by attribute name. */
+    data: Record<string, ValueValid>[];
 }
 
 export interface SCDSchema {
@@ -506,7 +694,8 @@ export interface SCDSchema {
 
 export interface GroupProfileSchema {
     key: string;
-    data: any[];
+    /** Generated group profile rows. Each row is a flat record keyed by group property name. */
+    data: Record<string, ValueValid>[];
 }
 
 /**
@@ -523,15 +712,25 @@ type ImportResult = import("mixpanel-import").ImportResults;
  * the end result of the data generation
  */
 export type Result = {
+    /** Generated events. */
     eventData: EventSchema[];
+    /** Mirror datasets (transformed copies of `eventData`). */
     mirrorEventData: EventSchema[];
-    userProfilesData: any[];
-    scdTableData: any[][];
+    /** User profiles. */
+    userProfilesData: UserProfile[];
+    /** SCD entries — one inner array per SCD prop. */
+    scdTableData: SCDSchema[][];
+    /** Ad-spend events (only populated when `hasAdSpend: true`). */
     adSpendData: EventSchema[];
+    /** Group profiles — one inner array per group key. */
     groupProfilesData: GroupProfileSchema[][];
+    /** Lookup tables — one inner array per table. */
     lookupTableData: LookupTableData[][];
+    /** Mixpanel import results (only populated when a token was provided). */
     importResults?: ImportResults;
+    /** Absolute paths of all files written to disk. */
     files?: string[];
+    /** Timing information. */
     time?: {
         start: number;
         end: number;
@@ -589,7 +788,7 @@ export interface WorldEvent {
     /** Conversion rate modifier during this event. */
     conversionModifier?: number;
     /** Properties injected into affected events. */
-    injectProps?: Record<string, any>;
+    injectProps?: Record<string, ValueValid>;
     /** Which events are affected ("*" for all, or array of event names). */
     affectsEvents?: string[] | "*";
     /** Aftermath period after the event ends. */
@@ -752,7 +951,7 @@ export interface GeoRegion {
     /** UTC timezone offset for this region (e.g., -5 for EST). */
     timezoneOffset: number;
     /** Properties injected for users in this region. */
-    properties?: Record<string, any>;
+    properties?: Record<string, ValueValid>;
 }
 
 /**
@@ -792,9 +991,9 @@ export interface FeatureConfig {
     /** Property name to inject on events. */
     property: string;
     /** Possible values for the property. First value is the "before" default if defaultBefore not set. */
-    values: any[];
+    values: ValueValid[];
     /** Default value before the feature launches. If not set, property doesn't exist before launch. */
-    defaultBefore?: any;
+    defaultBefore?: ValueValid;
     /** Which events are affected ("*" for all, or array of event names). */
     affectsEvents?: string[] | "*";
     /** Conversion rate lift for users who adopted the feature. */
@@ -802,7 +1001,7 @@ export interface FeatureConfig {
     /** Resolved logistic curve params (set by config-validator). */
     _resolvedCurve?: { k: number; midpoint: number };
     /** Pre-computed adopted values (set by config-validator). */
-    _adoptedValues?: any[];
+    _adoptedValues?: ValueValid[];
 }
 
 /**
@@ -830,7 +1029,7 @@ export interface AnomalyConfig {
     /** For burst/coordinated: number of events to inject. */
     count?: number;
     /** Properties injected on anomalous events. */
-    properties?: Record<string, any>;
+    properties?: Record<string, ValueValid>;
     /** Resolved absolute start time in unix seconds (set by config-validator). */
     _startUnix?: number;
     /** Resolved absolute end time in unix seconds (set by config-validator). */
@@ -869,8 +1068,8 @@ export declare function loadFromFile(filePath: string): Promise<Dungeon>;
 export declare function loadFromText(code: string): Promise<Dungeon>;
 /** Parse a JSON dungeon (UI schema format) into a runnable config */
 export declare function parseJSONDungeon(json: object): Dungeon;
-/** Validate that an object has the minimum shape of a dungeon config */
-export declare function validateDungeonShape(config: any): void;
+/** Validate that an object has the minimum shape of a dungeon config. Throws on shape violations. */
+export declare function validateDungeonShape(config: unknown): void;
 
 // ============= Text Generator Types =============
 
@@ -1049,7 +1248,7 @@ export interface TextMetadata {
     /** Keywords that were injected */
     injectedKeywords?: string[];
     /** User persona information */
-    persona?: Record<string, any>;
+    persona?: Record<string, ValueValid>;
     /** Flesch reading ease score */
     readabilityScore?: number;
     /** Text style used */
@@ -1170,13 +1369,14 @@ export interface TimeSoupOptions {
 }
 
 /**
- * Test context configuration for unit/integration tests
+ * Test context configuration for unit/integration tests. Looser than `Context`
+ * by design — tests routinely attach ad-hoc fixtures, so the index signature stays.
  */
 export interface TestContext {
     config: Dungeon;
     storage: Storage | null;
     defaults: Defaults;
-    campaigns: any[];
+    campaigns: Record<string, ValueValid>[];
     runtime: RuntimeState;
-    [key: string]: any;
+    [key: string]: unknown;
 }