@ak--47/dungeon-master 1.7.0 → 1.8.0

package/scripts/verify-stories.mjs

@@ -34,15 +34,18 @@ import readline from 'readline';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { pathToFileURL } from 'url';
+import { parse as parseCsv } from 'csv-parse';
+import generate from '../index.js';
 import { extractComments } from '../lib/core/extract-comments.js';
 import { validateDungeonConfig } from '../lib/core/config-validator.js';
 import {
 	buildIdentityMap,
-	verifyDungeon,
 	VERDICT_RANK,
 	validateStories,
-	storiesToChecks,
+	validateSchema,
 	evaluateStories,
+	auditWarehouseRows,
+	computeWarehouseSourceRows,
 } from '../lib/verify/index.js';
 
 const USAGE = `Usage: node scripts/verify-stories.mjs <dungeon-path> [--data-prefix <prefix>] [--in-memory] [--json]
@@ -89,13 +92,16 @@ if (!fs.existsSync(abs)) die(`verify-stories: dungeon not found at ${abs}`);
 
 const mod = await import(pathToFileURL(abs).href);
 const config = mod.default;
-const stories = mod.stories;
+const stories = Array.isArray(mod.stories) ? mod.stories : [];
 if (!config || typeof config !== 'object') die(`verify-stories: ${dungeonPath} has no default-exported config object`);
-if (!Array.isArray(stories) || !stories.length) {
+const hasWarehouseMetrics = Array.isArray(config.warehouseMetrics) && config.warehouseMetrics.length > 0;
+if (!stories.length && !hasWarehouseMetrics) {
 	die(`verify-stories: ${dungeonPath} has no \`stories\` named export — add one (see lib/templates/story-spec.schema.json) or use scripts/verify-runner.mjs for ad-hoc checks.`);
 }
-const sv = validateStories(stories);
-if (!sv.valid) die(`verify-stories: invalid stories:\n  ${sv.errors.join('\n  ')}`);
+if (stories.length) {
+	const sv = validateStories(stories);
+	if (!sv.valid) die(`verify-stories: invalid stories:\n  ${sv.errors.join('\n  ')}`);
+}
 
 // ── coverage discipline ─────────────────────────────────────────────────────
 // Every numbered hook in the HOOK STORIES comment block needs >=1 story. One
@@ -129,28 +135,30 @@ const coverage = {
 
 let storyResults;   // Array<{ id, hook, archetype, verdict, assertions }>
 let schemaPass = true;
+let warehouseAudits = [];
 
 if (inMemory) {
-	const checks = storiesToChecks(stories); // warns + skips duckdb assertions
-	if (!checks.length) die('verify-stories: every assertion is duckdb (disk-mode-only) — nothing to run in-memory. Drop --in-memory.');
-	// token: '' prevents any Mixpanel send; in-memory verification never writes.
-	const report = await verifyDungeon({ ...config, token: '', writeToDisk: false }, checks);
-	schemaPass = !!report.schemaReport?.pass;
-	const byStory = new Map(stories.map(s => [s.id, { id: s.id, hook: s.hook, archetype: s.archetype, verdict: null, assertions: [] }]));
-	for (const r of report.results) {
-		const m = /^(.+)\[(\d+)\]$/.exec(r.name);
-		const st = m && byStory.get(m[1]);
-		if (!st) continue;
-		const verdict = (/^([A-Z]+) — /.exec(r.detail || '') || [])[1] || (r.pass ? 'STRONG' : 'NONE');
-		st.assertions.push({ name: r.name, verdict, observed: null, detail: r.detail || '' });
-	}
-	for (const st of byStory.values()) {
-		// duckdb-only stories have zero in-memory assertions: informational SKIPPED.
-		st.verdict = st.assertions.length
-			? st.assertions.reduce((w, a) => VERDICT_RANK[a.verdict] < VERDICT_RANK[w] ? a.verdict : w, 'NAILED')
-			: 'SKIPPED';
-	}
-	storyResults = [...byStory.values()];
+	const result = await generate({ ...config, token: '', writeToDisk: false });
+	const events = Array.isArray(result.eventData) ? result.eventData : Array.from(result.eventData || []);
+	const profiles = Array.isArray(result.userProfilesData) ? result.userProfilesData : Array.from(result.userProfilesData || []);
+	const validated = result.validatedConfig || validateDungeonConfig({ ...config, token: '' });
+	schemaPass = !!validateSchema(events, validated)?.pass;
+	const warehouseSpecs = Object.fromEntries((validated.warehouseMetrics || []).map((spec) => [spec.name, spec]));
+	const warehouseRows = result.warehouseMetricData || {};
+	storyResults = stories.length
+		? await evaluateStories(stories, events, {
+			profiles,
+			funnels: Array.isArray(validated.funnels) ? validated.funnels : [],
+			identityMap: buildIdentityMap(profiles),
+			warehouseRows,
+			warehouseSpecs,
+			datasetStart: validated.datasetStart,
+			datasetEnd: validated.datasetEnd,
+			skipDiskOnlyDuckdb: true,
+			onWarning: (message) => console.error(message),
+		})
+		: [];
+	warehouseAudits = buildWarehouseAudits(warehouseSpecs, warehouseRows, validated, events);
 } else {
 	const prefix = dataPrefix || `verify-${path.basename(abs).replace(/\.(js|mjs)$/, '')}`;
 	const prefixPath = prefix.includes('/') ? prefix : path.join('data', prefix);
@@ -180,6 +188,12 @@ if (inMemory) {
 	// enrich the object you hand it.
 	const validated = validateDungeonConfig({ ...config, token: '' });
 	const identityMap = buildIdentityMap(profiles);
+	schemaPass = !!validateSchema(events, validated)?.pass;
+	const warehouseSpecs = Object.fromEntries((validated.warehouseMetrics || []).map((spec) => [spec.name, spec]));
+	const warehouseManifest = loadWarehouseManifest(prefixPath);
+	const warehouseRows = Object.fromEntries(await Promise.all(
+		Object.values(warehouseSpecs).map(async (spec) => [spec.name, await loadWarehouseRows(prefixPath, spec, warehouseManifest)])
+	));
 
 	const execFileP = promisify(execFile);
 	const runSql = async (sql) => {
@@ -195,19 +209,27 @@ if (inMemory) {
 		return trimmed ? JSON.parse(trimmed) : [];
 	};
 
-	storyResults = await evaluateStories(stories, events, {
-		profiles,
-		funnels: Array.isArray(validated.funnels) ? validated.funnels : [],
-		identityMap,
-		runSql,
-	});
+	storyResults = stories.length
+		? await evaluateStories(stories, events, {
+			profiles,
+			funnels: Array.isArray(validated.funnels) ? validated.funnels : [],
+			identityMap,
+			runSql,
+			warehouseRows,
+			warehouseSpecs,
+			datasetStart: validated.datasetStart,
+			datasetEnd: validated.datasetEnd,
+		})
+		: [];
+	warehouseAudits = buildWarehouseAudits(warehouseSpecs, warehouseRows, validated, events, warehouseManifest);
 }
 
 // ── report ──────────────────────────────────────────────────────────────────
 
 const counted = storyResults.filter(s => s.verdict !== 'SKIPPED');
 const failing = counted.filter(s => VERDICT_RANK[s.verdict] < VERDICT_RANK.STRONG);
-const pass = failing.length === 0 && missing.length === 0 && schemaPass;
+const failingAudits = warehouseAudits.filter((audit) => !audit.pass);
+const pass = failing.length === 0 && failingAudits.length === 0 && missing.length === 0 && schemaPass;
 
 if (asJson) {
 	console.log(JSON.stringify({
@@ -215,26 +237,36 @@ if (asJson) {
 		mode: inMemory ? 'in-memory' : 'disk',
 		coverage,
 		stories: storyResults,
+		warehouseAudits,
 		schemaPass,
 		pass,
 	}, null, 2));
 } else {
-	const wId = Math.max(5, ...storyResults.map(s => s.id.length));
-	const wHook = Math.max(4, ...storyResults.map(s => String(s.hook).length));
-	const wArch = Math.max(9, ...storyResults.map(s => s.archetype.length));
-	console.log('');
-	console.log(`${'STORY'.padEnd(wId)}  ${'HOOK'.padEnd(wHook)}  ${'ARCHETYPE'.padEnd(wArch)}  VERDICT`);
-	for (const s of storyResults) {
-		console.log(`${s.id.padEnd(wId)}  ${String(s.hook).padEnd(wHook)}  ${s.archetype.padEnd(wArch)}  ${s.verdict}`);
-		for (const a of s.assertions) {
-			console.log(`  ${a.name.padEnd(wId)}  ${a.verdict} — ${a.detail.replace(/^[A-Z]+ — /, '')}`);
+	if (storyResults.length) {
+		const wId = Math.max(5, ...storyResults.map(s => s.id.length));
+		const wHook = Math.max(4, ...storyResults.map(s => String(s.hook).length));
+		const wArch = Math.max(9, ...storyResults.map(s => s.archetype.length));
+		console.log('');
+		console.log(`${'STORY'.padEnd(wId)}  ${'HOOK'.padEnd(wHook)}  ${'ARCHETYPE'.padEnd(wArch)}  VERDICT`);
+		for (const s of storyResults) {
+			console.log(`${s.id.padEnd(wId)}  ${String(s.hook).padEnd(wHook)}  ${s.archetype.padEnd(wArch)}  ${s.verdict}`);
+			for (const a of s.assertions) {
+				console.log(`  ${a.name.padEnd(wId)}  ${a.verdict} — ${a.detail.replace(/^[A-Z]+ — /, '')}`);
+			}
 		}
+		console.log('');
 	}
-	console.log('');
 	const tally = {};
 	for (const s of counted) tally[s.verdict] = (tally[s.verdict] || 0) + 1;
 	const skipped = storyResults.length - counted.length;
-	console.log(`${counted.length} stories: ${Object.entries(tally).map(([v, n]) => `${n} ${v}`).join(', ') || 'none'}${skipped ? ` (${skipped} skipped — duckdb-only, disk mode required)` : ''}`);
+	console.log(`${counted.length} stories: ${Object.entries(tally).map(([v, n]) => `${n} ${v}`).join(', ') || 'none'}${skipped ? ` (${skipped} skipped — disk mode required)` : ''}`);
+	if (warehouseAudits.length) {
+		console.log('warehouse audit:');
+		for (const audit of warehouseAudits) {
+			const summary = `stats corr=${formatNumber(audit.stats.corr)} buckets=${audit.stats.buckets} gaps=${audit.stats.gaps} empty=${audit.stats.emptyNumericCells}`;
+			console.log(`  ${audit.table}: ${audit.pass ? 'PASS' : 'FAIL'} — ${audit.failures.length ? audit.failures.join('; ') : summary}`);
+		}
+	}
 	if (coverage.note) console.log(`coverage: ${coverage.note}`);
 	else if (missing.length) console.log(`coverage: FAIL — hooks with no story: ${missing.map(n => `H${n}`).join(', ')} (declared H${coverage.declared.join(', H')})`);
 	else console.log(`coverage: ${coverage.declared.length} hooks declared in HOOK STORIES, all covered`);
@@ -243,3 +275,77 @@ if (asJson) {
 }
 
 process.exit(pass ? 0 : 1);
+
+function buildWarehouseAudits(warehouseSpecs, warehouseRows, validated, events = [], warehouseManifest = null) {
+	return Object.values(warehouseSpecs || {}).map((spec) => {
+		const rows = warehouseRows?.[spec.name] || [];
+		const sourceRows = events.length ? computeWarehouseSourceRows(events, spec) : [];
+		const manifestColumns = warehouseManifest?.tables?.find((table) => table.table === spec.name)?.columns || [];
+		return {
+			table: spec.name,
+			...auditWarehouseRows(rows, spec, {
+				datasetStart: validated.datasetStart,
+				datasetEnd: validated.datasetEnd,
+				sourceRows,
+				manifestColumns,
+			}),
+		};
+	});
+}
+
+function loadWarehouseManifest(prefixPath) {
+	const manifestPath = `${prefixPath}-WAREHOUSE-MANIFEST.json`;
+	if (!fs.existsSync(manifestPath)) return null;
+	return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+}
+
+async function loadWarehouseRows(prefixPath, spec, manifest) {
+	const manifestEntry = manifest?.tables?.find((table) => table.table === spec.name) || null;
+	const fileBase = manifestEntry?.file || `${path.basename(prefixPath)}-WAREHOUSE-${spec.name}`;
+	const format = manifestEntry?.format || spec.format || 'csv';
+	const filePath = path.join(path.dirname(prefixPath), `${fileBase}.${format}`);
+	if (!fs.existsSync(filePath)) return [];
+	if (format === 'json') return loadNdjson(filePath);
+	return loadCsv(filePath, manifestEntry?.columns || []);
+}
+
+async function loadNdjson(filePath) {
+	const out = [];
+	const rl = readline.createInterface({ input: fs.createReadStream(filePath), crlfDelay: Infinity });
+	for await (const line of rl) {
+		if (line.trim()) out.push(JSON.parse(line));
+	}
+	return out;
+}
+
+async function loadCsv(filePath, columns) {
+	const out = [];
+	const parser = fs.createReadStream(filePath).pipe(parseCsv({
+		bom: true,
+		columns: true,
+		skip_empty_lines: true,
+	}));
+	for await (const record of parser) {
+		const row = {};
+		for (const [header, rawValue] of Object.entries(record)) {
+			const type = columns.find((column) => column.name === header)?.bqType;
+			row[header] = coerceWarehouseCell(rawValue ?? '', type);
+		}
+		out.push(row);
+	}
+	return out;
+}
+
+function coerceWarehouseCell(value, bqType) {
+	if (bqType === 'FLOAT64') {
+		if (value === '') return '';
+		const numeric = Number(value);
+		return Number.isFinite(numeric) ? numeric : value;
+	}
+	if (bqType === 'BOOL') return value === 'true';
+	return value;
+}
+
+function formatNumber(value) {
+	return Number.isFinite(value) ? value.toFixed(3) : String(value);
+}

package/types.d.ts

@@ -453,6 +453,18 @@ export interface Dungeon {
     groupProps?: Record<string, Record<string, ValueValid>>;
     /** Lookup table definitions for dimension tables. */
     lookupTables?: LookupTableSchema[];
+    /**
+     * v1.8.0 — identity-less metric snapshots. One record per cadence tick per
+     * dimension cross-product row, carrying NO `user_id` and NO `device_id`.
+     *
+     * Use for infrastructure and finance telemetry: daily CDN egress per region,
+     * weekly billing rollups per plan tier, hourly queue depth per cluster.
+     * `$ad_spend` (`hasAdSpend: true`) is the same idea hard-coded; this is the
+     * general form and it does not use a Mixpanel reserved event name.
+     */
+    standaloneEvents?: StandaloneEventConfig[];
+    /** v1.8.0 — warehouse-backed metric source tables derived from the run's own event stream. */
+    warehouseMetrics?: WarehouseMetricConfig[];
     /** TimeSoup configuration: shapes intra-week and intra-day rhythm (peaks, deviation, DOW/HOD weights). Pair with `macro` for big-picture trend control. */
     soup?: soup;
     /** 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. */
@@ -703,7 +715,7 @@ export interface ResolvedMacro {
  * - "everything"  — array of ALL events for one user (return array to replace; meta.profile available)
  *
  * Storage-only hooks (fire during hookPush, not in generators):
- * - "ad-spend", "group", "mirror", "lookup"
+ * - "ad-spend", "group", "mirror", "lookup", "standalone", "warehouse"
  */
 export type hookTypes =
     | "event"
@@ -716,6 +728,8 @@ export type hookTypes =
     | "funnel-pre"
     | "funnel-post"
     | "ad-spend"
+    | "standalone"
+    | "warehouse"
     | "churn"
     | "group-event"
     | "everything"
@@ -732,7 +746,9 @@ export type hookTypes =
  * - "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.
+ * - storage-only ("ad-spend", "group", "mirror", "lookup", "standalone"): return an object or array of records; undefined drops the record.
+ * - "warehouse": return value is IGNORED; mutate the row in place.
+ * - "standalone" runs before the user loop; "warehouse" runs after it. Neither receives person metadata or enters "everything".
  *
  * @param record - The data being processed (event, profile, array of events, funnel config, etc.).
  * @param type - Which hook type is firing — see `hookTypes`.
@@ -908,6 +924,10 @@ export interface hookArrayOptions<T> {
     concurrency?: number;
     /** Generation context (config, runtime, defaults). */
     context?: Context;
+    /** Warehouse metric name for warehouse containers. */
+    metricName?: string;
+    /** Fixed CSV column order for warehouse metric tables. */
+    fixedColumns?: string[];
 }
 
 /**
@@ -929,6 +949,10 @@ export interface HookedArray<T> extends Array<T> {
     getWritePath: () => string;
     /** Returns all file paths written by this container during the current run. */
     getWrittenFiles: () => string[];
+    /** Storage hook type this array is configured for. */
+    type?: hookTypes | string;
+    /** Output serialization format for this array. */
+    format?: string;
     /** SCD prop name this array carries (only set on SCD HookedArrays). */
     scdKey?: string;
     /** Entity type for SCDs ("user" or a group key). */
@@ -937,6 +961,10 @@ export interface HookedArray<T> extends Array<T> {
     groupKey?: string;
     /** Lookup table key this array carries (only set on lookup table HookedArrays). */
     lookupKey?: string;
+    /** Warehouse metric name this array carries (only set on warehouse HookedArrays). */
+    metricName?: string;
+    /** Fixed CSV column order for warehouse metric tables. */
+    fixedColumns?: string[];
 }
 
 export type AllData =
@@ -954,8 +982,11 @@ export interface Storage {
     mirrorEventData?: HookedArray<EventSchema>;
     userProfilesData?: HookedArray<UserProfile>;
     adSpendData?: HookedArray<EventSchema>;
+    standaloneEventData?: HookedArray<EventSchema>;
     groupProfilesData?: HookedArray<GroupProfileSchema>[];
     lookupTableData?: HookedArray<LookupTableSchema>[];
+    warehouseMetricData?: HookedArray<Record<string, any>>[];
+    warehouseManifestFile?: string;
     scdTableData?: HookedArray<SCDSchema>[];
     groupEventData?: HookedArray<EventSchema>;
 }
@@ -1023,6 +1054,14 @@ export interface Context {
     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;
+    /** Runtime accumulator for post-loop warehouse metric materialization. */
+    warehouseAccumulator?: {
+        warnings?: string[];
+        ingest: (events: EventSchema[]) => void;
+        getCell: (metricName: string, seriesKey: string, bucketStartSec: number) => any;
+    };
+    /** Manifest describing materialized warehouse tables for downstream tooling. */
+    warehouseManifest?: WarehouseManifest;
     /** Alias of `FIXED_BEGIN` — surfaced on hook `meta.datasetStart`. */
     DATASET_START_SECONDS: number;
     /** Alias of `FIXED_NOW` — surfaced on hook `meta.datasetEnd`. */
@@ -1596,6 +1635,12 @@ export type Result = {
     scdTableData: SCDSchema[][];
     /** Ad-spend events (only populated when `hasAdSpend: true`). */
     adSpendData: EventSchema[];
+    /** Identity-less metric snapshots (only populated when `standaloneEvents` is set). v1.8.0. */
+    standaloneEventData: EventSchema[];
+    /** Materialized warehouse metric tables keyed by metric name. */
+    warehouseMetricData: Record<string, Record<string, any>[]>;
+    /** Warehouse table manifest surfaced whenever `warehouseMetrics` is configured. */
+    warehouseManifest?: WarehouseManifest;
     /** Group profiles — one inner array per group key. */
     groupProfilesData: GroupProfileSchema[][];
     /** Lookup tables — one inner array per table. */
@@ -2007,9 +2052,10 @@ export interface StoryAssertion {
     /**
      * Byte-compatible with `emulateBreakdown` / `verifyDungeon` args — or the
      * `{ type: 'duckdb', sql }` escape hatch (disk mode only; `{{PREFIX}}` in
-     * the SQL is substituted with the run's data prefix path).
+     * the SQL is substituted with the run's data prefix path), or warehouse
+     * verification rows via `{ type: 'warehouse' | 'warehouse-stats', table }`.
      */
-    breakdown: Record<string, unknown> & { type: string; sql?: string };
+    breakdown: Record<string, unknown> & { type: string; sql?: string; table?: string };
     select?: StorySelect;
     expect?: StoryExpect;
     /**
@@ -2325,13 +2371,266 @@ export interface WritePaths {
     eventFiles: string[];
     userFiles: string[];
     adSpendFiles: string[];
+    standaloneFiles: string[];
     scdFiles: string[];
     mirrorFiles: string[];
     groupFiles: string[];
     lookupFiles: string[];
+    warehouseFiles: string[];
     folder: string;
 }
 
+// ============= Standalone (identity-less) Events — v1.8.0 =============
+
+/**
+ * An identity-less metric snapshot stream.
+ *
+ * The engine emits one record per cadence tick per dimension cross-product row.
+ * Records carry `event`, `time`, `insert_id`, `distinct_id`, every dimension as
+ * a flat property, and every resolved entry in `properties`. They never carry
+ * `user_id` or `device_id`, because they describe a system, not a person.
+ *
+ * @example
+ * standaloneEvents: [{
+ *   event: 'cdn_egress',
+ *   cadence: 'day',
+ *   dimensions: { region: ['us-east', 'us-west', 'eu', 'apac'] },
+ *   distinctIdFrom: 'region',
+ *   properties: {
+ *     gb_out:   (ctx) => 400 + ctx.tickIndex * 3,
+ *     cost_usd: (ctx) => (400 + ctx.tickIndex * 3) * 0.085,
+ *     p95_ms:   [120, 140, 160],
+ *   },
+ * }]
+ */
+export interface StandaloneEventConfig {
+    /** Event name as it lands in Mixpanel. Must be unique across `standaloneEvents`. */
+    event: string;
+    /**
+     * How often a snapshot fires. Ticks start at the dataset start and step by
+     * the cadence; the last tick is the final one at or before the dataset end.
+     * Default: `'day'`.
+     */
+    cadence?: 'hour' | 'day' | 'week';
+    /**
+     * Dimension values to cross-product. Each key becomes a flat property on the
+     * record. `{ region: ['us','eu'], tier: ['a','b'] }` emits 4 records per tick.
+     * Omit for a single record per tick.
+     */
+    dimensions?: Record<string, any[]>;
+    /**
+     * Which dimension supplies the synthetic `distinct_id`. Must name a declared
+     * dimension. When omitted, `distinct_id` is the event name. The id exists so
+     * Mixpanel accepts the record; it never maps to a person.
+     */
+    distinctIdFrom?: string;
+    /**
+     * Snapshot metrics. Same `ValueValid` forms as event properties, and value
+     * functions receive a `StandaloneValueContext` so a metric can shape a trend
+     * across the window.
+     */
+    properties?: Record<string, ValueValid>;
+}
+
+/** @internal Normalized `StandaloneEventConfig` produced by the validator. */
+export interface ResolvedStandaloneEventConfig {
+    event: string;
+    cadence: 'hour' | 'day' | 'week';
+    dimensions: Record<string, any[]>;
+    distinctIdFrom: string | null;
+    properties: Record<string, ValueValid>;
+}
+
+/**
+ * Context handed to every standalone property value function.
+ * Shares `time` and `config` with `ValueContext`, so a function written for a
+ * normal event property still works unchanged.
+ */
+export interface StandaloneValueContext {
+    /** Tick timestamp in unix MILLISECONDS. */
+    time: number;
+    /** The full validated dungeon config. */
+    config: Dungeon;
+    /** This row's dimension values, e.g. `{ region: 'us-east' }`. */
+    dimensions: Record<string, any>;
+    /** Zero-based index of this tick within the window. Use it to shape a trend. */
+    tickIndex: number;
+    /** Total number of ticks in the window. `tickIndex / (tickCount - 1)` is window progress. */
+    tickCount: number;
+    /** The cadence this stream fires on. */
+    cadence: 'hour' | 'day' | 'week';
+    /** The partially built record (`event`, `time`, `insert_id`, `distinct_id`, dimensions). */
+    event: Record<string, any>;
+}
+
+/**
+ * Meta passed to the `"standalone"` hook.
+ *
+ * Storage-only: return the record or an array of records to retain them.
+ * Returning undefined drops the record. Warehouse hooks instead ignore returns.
+ */
+export interface HookMetaStandalone extends HookMetaTimeAnchors {
+    /** The resolved config for the stream this record belongs to. */
+    spec: ResolvedStandaloneEventConfig;
+    /** The full validated dungeon config. */
+    config: Dungeon;
+}
+
+export interface WarehouseMetricSource {
+    /** Source event names whose bucketed measure contributes positively to the series. */
+    event: string | string[];
+    /** Source event names whose bucketed measure is subtracted from the series. */
+    minus?: string | string[];
+    /** Per-bucket measure. Default: `'count'`. */
+    measure?: 'count' | 'sum' | 'avg' | 'dau' | 'users';
+    /** Required when `measure` is `'sum'` or `'avg'`. */
+    property?: string;
+    /** Optional row filter over flat event records. */
+    where?: ((event: Record<string, any>) => boolean) | null;
+    /** Optional dimension columns copied from source event or super prop keys. */
+    groupBy?: string | string[];
+}
+
+export interface WarehouseMetricConfig {
+    /**
+     * @example
+     * warehouseMetrics: [{
+     *   name: 'daily_active_subscriptions',
+     *   type: 'point-in-time',
+     *   source: {
+     *     event: 'subscription_started',
+     *     minus: 'subscription_cancelled',
+     *     measure: 'count',
+     *   },
+     *   baseline: 40,
+     *   timeColumn: 'date',
+     *   valueColumn: 'active_subscriptions',
+     * }]
+     */
+    /** Unique metric/table name. Must match `/^[a-z][a-z0-9_]{0,63}$/`. */
+    name: string;
+    /** Metric family: additive sums per bucket vs point-in-time carried levels. Default: `'additive'`. */
+    type?: 'additive' | 'point-in-time';
+    /** Bucket grain. Default: `'day'`. */
+    grain?: 'day' | 'week' | 'month';
+    /** Point-in-time only: emit only the first bucket and changed values. Default: `false`. */
+    sparse?: boolean;
+    /** Declarative source spec describing how to derive the table from generated events. */
+    source: WarehouseMetricSource;
+    /** Output time column name. Default: `'date'`. */
+    timeColumn?: string;
+    /** Output value column name. Default: `'value'`. */
+    valueColumn?: string;
+    /** Point-in-time starting level at the dataset window start. Default: `0`. */
+    baseline?: number;
+    /** Multiplier applied after bucket aggregation. Default: `1`. */
+    scale?: number;
+    /** Seeded jitter fraction clamped to `[0, 0.5]`. Default: `0`. */
+    noise?: number;
+    /** Grain periods of backfill before the dataset window. Default: `0`. */
+    history?: number;
+    /** Extra declared output columns, preserved in declaration order. */
+    columns?: Record<string, ValueValid | ((ctx: WarehouseValueContext) => ValueValid)>;
+    /** Output file format. Defaults to the dungeon format, else `'csv'`. */
+    format?: 'csv' | 'json';
+}
+
+/** @internal Normalized `WarehouseMetricConfig` produced by the validator. */
+export interface ResolvedWarehouseMetricConfig {
+    name: string;
+    type: 'additive' | 'point-in-time';
+    grain: 'day' | 'week' | 'month';
+    sparse: boolean;
+    source: {
+        event: string[];
+        minus: string[];
+        measure: 'count' | 'sum' | 'avg' | 'dau' | 'users';
+        property: string | null;
+        where: ((event: Record<string, any>) => boolean) | null;
+        groupBy: string[];
+    };
+    timeColumn: string;
+    valueColumn: string;
+    baseline: number;
+    scale: number;
+    noise: number;
+    history: number;
+    columns: Record<string, ValueValid | ((ctx: WarehouseValueContext) => ValueValid)>;
+    format: 'csv' | 'json';
+}
+
+export interface WarehouseValueContext {
+    /** Final bucket value after scale and noise. */
+    value: number;
+    /** Partially built row so later columns can depend on earlier ones. */
+    row: Record<string, any>;
+    /** Bucket start in unix milliseconds. */
+    time: number;
+    /** Zero-based chronological bucket index within this series, including backfill buckets and sparse gaps when present. */
+    bucketIndex: number;
+    /** Total chronological buckets in this series, including history buckets even when sparse rows are skipped. */
+    bucketCount: number;
+    /** Bucket grain for this metric. */
+    grain: 'day' | 'week' | 'month';
+    /** True when this row was synthesized before the dataset window by `history`. */
+    isBackfill: boolean;
+    /** Stable joined dimension key for this series. Empty string when undimensioned. */
+    seriesKey: string;
+    /** The resolved metric spec for this table. */
+    spec: ResolvedWarehouseMetricConfig;
+    /** The full validated dungeon config. */
+    config: Dungeon;
+}
+
+export interface HookMetaWarehouse extends HookMetaTimeAnchors {
+    /** The resolved config for the metric this row belongs to. */
+    spec: ResolvedWarehouseMetricConfig;
+    /** The full validated dungeon config. */
+    config: Dungeon;
+    /** Metric/table name. */
+    metricName: string;
+    /** Zero-based chronological bucket index within this series, including history buckets and sparse gaps. */
+    bucketIndex: number;
+    /** Total chronological buckets in this series, including history buckets even when sparse rows are skipped. */
+    bucketCount: number;
+    /** Bucket grain for the metric. */
+    grain: 'day' | 'week' | 'month';
+    /** Stable joined dimension key for this series. Empty string when undimensioned. */
+    seriesKey: string;
+    /** True when the row belongs to the `history` backfill before the dataset window. */
+    isBackfill: boolean;
+    /** Raw bucket contributions before scale/noise and before point-in-time carry-forward. */
+    raw: {
+        plus: { count: number; sum: number; users: number };
+        minus: { count: number; sum: number; users: number };
+    };
+}
+
+export interface WarehouseManifestColumn {
+    name: string;
+    bqType: 'DATE' | 'FLOAT64' | 'BOOL' | 'STRING';
+}
+
+export interface WarehouseManifestTable {
+    table: string;
+    file: string;
+    format: 'csv' | 'json';
+    grain: 'day' | 'week' | 'month';
+    type: 'additive' | 'point-in-time';
+    timeColumn: string;
+    valueColumn: string;
+    dimensionColumns: string[];
+    columns: WarehouseManifestColumn[];
+    recommendedAggregation: 'sum' | 'last value';
+    sql: string;
+    refreshHint: string;
+}
+
+export interface WarehouseManifest {
+    configName: string;
+    tables: WarehouseManifestTable[];
+}
+
 /**
  * Configuration for TimeSoup time distribution function
  */