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

package/.claude/skills/write-hooks/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: write-hooks
 description: Use when an existing dungeon needs engineered story trends or "magic number" patterns — writes the `hook` function using atom helpers and high-level patterns. Adds no new event flags; never mutates the schema.
-argument-hint: [path/to/dungeon.js] [free-text story / trend description]
+argument-hint: '[path/to/dungeon.js] [free-text story / trend description]'
 model: claude-opus-4-6
 effort: max
 ---
@@ -68,7 +68,7 @@ property values that differ by cohort, injected bursts, lifecycle waves.
 Hooks fire in this order per user (see `CLAUDE.md` for the canonical reference):
 
 1. `"user"` — profile created. Mutate in place; return ignored.
-2. `"scd-pre"` — SCD entries created. Mutate in place OR return new array.
+2. `"scd-pre"` — SCD entries created. Mutate in place; return ignored.
 3. For each funnel: `"funnel-pre"` → `"event"` (per step) → `"funnel-post"`.
 
 **`funnel-pre` is now reliable for temporal patterns.** Usage funnels advance a
@@ -76,7 +76,7 @@ cursor after each run, so successive `meta.firstEventTime` values spread across
 the user's active window. Persona and world-event modifiers apply BEFORE the
 hook — the hook has final authority on `conversionRate`, `timeToConvert`, and
 `props`.
-4. `"event"` — for non-funnel standalone events. Return value REPLACES the event.
+4. `"event"` — for non-funnel user events from `events[]`. Return value REPLACES the event.
 5. `"everything"` — array of ALL the user's events. Return array to replace.
 
 **Most engineered trends belong in `everything`.** It sees the full user stream,
@@ -86,6 +86,36 @@ and you can mutate freely.
 Storage-only hooks (`ad-spend`, `group`, `mirror`, `lookup`) fire later in the
 pipeline and don't see the same `meta` shape.
 
+### Cadence streams and warehouse rows (v1.8.0)
+
+These hooks sit outside the per-user sequence and never enter `everything`.
+Neither has person metadata (`meta.profile`, auth state, sessions, or SCDs).
+
+- `standaloneEvents`: `type === 'standalone'` fires on storage push before the
+  user loop. Read `meta.spec` and `meta.config` to identify the stream. Return
+  the record object or an array of records. Returning `undefined` drops it.
+  Mutating without returning is therefore insufficient. Preserve required keys
+  and use fresh `insert_id` values for clones. Its synthetic `distinct_id` is a
+  series identifier, never a person or a retention cohort.
+- `warehouseMetrics`: `type === 'warehouse'` fires after user generation, once
+  per materialized row. Mutate the row in place; its return value is ignored.
+  Keep the time column and group keys stable. Modify only the value column and
+  declared extra columns. Meta includes `spec`, `config`, `metricName`,
+  `bucketIndex`, `bucketCount`, `grain`, `seriesKey`, `isBackfill`, and `raw`.
+  `raw` describes plus/minus source aggregates before scaling, noise, and carry.
+
+Do not add either schema here. Send missing `standaloneEvents` properties or
+warehouse `columns` back to `/create-dungeon`. Warehouse sources consume user
+`events[]` only, including both plus and minus legs; they cannot consume cadence
+streams. Standalone value functions use tick context, warehouse column functions
+use bucket context; neither supplies a user profile.
+
+Verify standalone stories with disk-backed `duckdb` assertions against
+`{{PREFIX}}-STANDALONE*.json`. The user-event emulator and `--in-memory` CLI mode
+do not evaluate this stream. Warehouse stories can use `warehouse` assertions
+or `warehouse-stats` assertions; automatic warehouse audits also run without
+stories. Hand off to `/verify-dungeon` with an explicit artifact prefix.
+
 ## Hook meta — identity context
 
 Inside `funnel-pre` and `funnel-post`:

package/CHANGELOG.md

@@ -2,6 +2,148 @@
 
 All notable changes to `@ak--47/dungeon-master`.
 
+## 1.8.0 — 2026-09-10
+
+### Added — `standaloneEvents`: identity-less metric snapshots
+
+A new top-level config key that generates records describing a **system, not a
+person**. They carry no `user_id` and no `device_id`. Before 1.8.0 the only
+identity-less stream the engine could produce was `$ad_spend` via `hasAdSpend`,
+which is hard-coded to one shape, one cadence, and a Mixpanel reserved event
+name. `standaloneEvents` is the general form.
+
+```js
+standaloneEvents: [{
+  event: 'cdn_egress',
+  cadence: 'day',                                       // 'hour' | 'day' | 'week', default 'day'
+  dimensions: { region: ['us-east', 'us-west', 'eu'] }, // cross-producted
+  distinctIdFrom: 'region',                             // synthetic id, never a person
+  properties: {
+    gb_out:   (ctx) => 400 + ctx.tickIndex * 3,
+    cost_usd: (ctx) => (400 + ctx.tickIndex * 3) * 0.085,
+    p95_ms:   [120, 140, 160],
+  },
+}]
+```
+
+- One record per cadence tick per dimension cross-product row.
+- Ticks start at the dataset start and step by the cadence. The last tick is the
+  final one at or before the dataset end, so nothing lands in the future.
+- Each record carries `event`, `time`, `insert_id`, `distinct_id`, every
+  dimension as a flat property, and every resolved entry in `properties`.
+- `distinct_id` is the value of the dimension named by `distinctIdFrom`, else the
+  event name. It exists so Mixpanel accepts the record; it never maps to a person.
+- Property value functions receive a `StandaloneValueContext`:
+  `{ time, config, dimensions, tickIndex, tickCount, cadence, event }`.
+  `tickIndex / (tickCount - 1)` is window progress — use it to shape a trend.
+- New hook type `standalone` (storage-only). Return the record or an array of
+  records; returning nothing drops the record. `meta.spec` carries the resolved
+  stream config. The `warehouse` hook instead mutates its row and ignores returns.
+- Lands in `result.standaloneEventData`, writes to a `-STANDALONE` file shard,
+  and imports to Mixpanel as its own event stream.
+- Validation **throws** on a malformed entry rather than skipping it. A silent
+  skip would drop a whole data stream without the author noticing.
+
+New types: `StandaloneEventConfig`, `ResolvedStandaloneEventConfig`,
+`StandaloneValueContext`, `HookMetaStandalone`. `WritePaths` gains
+`standaloneFiles`; `Result` gains `standaloneEventData`; `hookTypes` gains
+`"standalone"`.
+
+**Output compatibility.** Additive only. A config without `standaloneEvents` is
+byte-identical to 1.7.0 — the generation pass is gated on the key being present,
+so the seeded RNG stream is untouched. `config.standaloneEvents` normalizes to
+`[]` when absent. Event determinism comparisons exclude the fresh `insert_id`.
+
+New tests: `tests/unit/standalone-events.test.js` (25),
+`tests/integration/standalone-events.test.js` (15).
+
+### Added — `warehouseMetrics`: manifest-driven warehouse source tables
+
+A new top-level config key that materializes warehouse-ready tables from the
+run's own events after generation completes. This is the local source-table side
+of a warehouse metric demo: bookings rollups, active subscription levels, ARR
+snapshots, and other time-series tables that should read like a real warehouse.
+
+```js
+warehouseMetrics: [{
+  name: 'daily_new_bookings',
+  source: { event: 'new_booking', measure: 'sum', property: 'booking_value' },
+  valueColumn: 'bookings',
+}]
+```
+
+- Supports additive and point-in-time metrics.
+- Grain: `day`, `week`, `month`.
+- Supports subtractive `minus` legs, `groupBy` on up to two declared keys,
+  optional `history` backfill, sparse point-in-time emission, seeded `noise`,
+  `scale`, and derived `columns`.
+- Lands in `result.warehouseMetricData` keyed by metric name and emits
+  `result.warehouseManifest` with table schemas, SQL, and recommended
+  aggregation.
+- Writes `<name>-WAREHOUSE-<table>.csv|json` plus
+  `<name>-WAREHOUSE-MANIFEST.json` when `writeToDisk` is enabled.
+- Never imports through `token`. Warehouse deploy is a separate flow.
+- New hook type `warehouse` fires once per materialized row with
+  `metricName`, `bucketIndex`, `bucketCount`, `grain`, `seriesKey`,
+  `isBackfill`, and `raw` bucket stats.
+- Warehouse verification adds `warehouse` / `warehouse-stats` story breakdowns
+  plus automatic audits over declared columns, gaps, monotonic time, empty numeric
+  cells, and sparse first-bucket coverage. Source correlation is available to story
+  assertions; it is not an automatic pass/fail gate.
+- Sparse point-in-time comparison carries emitted levels across missing buckets,
+  excludes history from correlation, and compares the first live delta to the scaled
+  baseline. Warehouse generation preserves the user event stream, including with noise.
+- Disk verification parses quoted multiline CSV records with `csv-parse` and keeps
+  disk and in-memory audit results consistent.
+
+### Added — `/warehouse-metrics`: BigQuery load + warehouse metric save flow
+
+The shipped skill at `.claude/skills/warehouse-metrics/` loads the generated
+warehouse tables into BigQuery, connects that dataset to Mixpanel with the
+existing powertools macro, previews each metric SQL, and saves new metrics when
+the CRUD endpoints are available.
+
+- Uses the emitted warehouse manifest as the contract.
+- Maps manifest `recommendedAggregation: 'last value'` to the API's
+  `aggregation: 'last_value'`.
+- If `GET /crud/getWarehouseMetrics` returns 404, the script still completes the
+  BigQuery load and source setup, then writes `warehouse/GAPS.md` for manual
+  metric creation.
+- Preview fails fast on the raw substring block (`CREATE`, `UPDATE`, etc.), so
+  identifiers like `created_at` and `updated_at` are a real deploy-time trap.
+- The canonical skill name is `/warehouse-metrics`. Bundled commands and handoffs
+  use `.claude/skills/warehouse-metrics/`.
+- Uses the shipped Powertools warehouse CRUD and IAM setup macro. Runtime IAM is
+  configured; permission failures still stop deployment with the original error.
+- Dry-run works before project provisioning, using placeholders without credentials.
+  Live table replacement requires explicit operator consent; the script does not prompt.
+
+### Changed — skill workflow and provisioning context
+
+- All nine bundled skills have parsed string argument hints and matching folder names.
+  Release tests check frontmatter and warehouse handoffs.
+- Authoring, hooks, and verification distinguish person events, identity-less cadence
+  events, and identity-free warehouse rows. Synthetic IDs never count as people.
+- Verification preserves the explicit run prefix and local uncompressed warehouse
+  artifacts for deployment. Soup analysis remains scoped to user-event timestamps.
+- Project business context includes separate cadence and warehouse summaries without
+  evaluating property functions or including credentials.
+- Headless builds preserve warehouse history and use query preview for fresh results;
+  warehouse refresh only invalidates the saved metric cache.
+
+### Added - `/release-check`
+
+The new `/release-check` skill audits tests, determinism, documentation, package
+contents, and release handoffs. `.agents/skills` and `.github/skills` link to the
+canonical `.claude/skills` directory for shared agent discovery. Publishing remains
+an explicitly authorized operator action.
+
+### Changed — `streamCSV` preserves falsy cells
+
+CSV serialization now writes `0` and `false` as literal cell values instead of
+empty strings. If downstream warehouse SQL or fixtures were treating blank cells
+as zero or false, update them to read the actual value.
+
 ## 1.7.0 — 2026-09-03
 
 The engine round for DM4 v5. Executes the 1.6.4 "Deferred to 1.7.0" table plus

package/HOOKS.md

@@ -21,10 +21,12 @@ hook: function (record, type, meta) { ... return record; }
 | `event` | `events.js:176` | Single event (flat props) | **Used** (replaces event) | `user: { distinct_id }`, `config`, `datasetStart`, `datasetEnd` |
 | `funnel-post` | `funnels.js:153` | Array of funnel events | Ignored (mutate in-place) | `user`, `profile`, `scd`, `funnel`, `config`, `experiment` |
 | `everything` | `user-loop.js:280` | Array of ALL user events | **Used** if array returned | `profile`, `scd`, `config`, `datasetStart`, `datasetEnd`, `userIsBornInDataset`, `authTime`, `isPreAuth`, `persona` |
-| `ad-spend` | `storage.js` | Ad spend event | Ignored | -- |
-| `group` | `storage.js` | Group profile | Ignored | -- |
-| `mirror` | `storage.js` | Mirror data point | Ignored | -- |
-| `lookup` | `storage.js` | Lookup table entry | Ignored | -- |
+| `ad-spend` | `storage.js` | Ad spend event | Object or array used | -- |
+| `group` | `storage.js` | Group profile | Object or array used | -- |
+| `mirror` | `storage.js` | Mirror data point | Object or array used | -- |
+| `lookup` | `storage.js` | Lookup table entry | Object or array used | -- |
+| `standalone` | `storage.js`, before user loop | Identity-less cadence event | Object or array used; `undefined` drops | `spec`, `config`, `datasetStart`, `datasetEnd` |
+| `warehouse` | `storage.js` | One materialized warehouse row | Ignored | `spec`, `config`, `metricName`, `bucketIndex`, `bucketCount`, `grain`, `seriesKey`, `isBackfill`, `raw`, `datasetStart`, `datasetEnd` |
 
 **Per-user execution order:** `user` -> `scd-pre` -> `funnel-pre` -> `event` -> `funnel-post` -> `everything`
 
@@ -36,7 +38,105 @@ double-fire mutations.
 **Return rules:**
 - `event`: return the (possibly replaced) event object.
 - `everything`: return the (possibly modified) array. Filtered array removes events.
-- All other types: mutate `record` in-place. Return value is ignored.
+- `ad-spend`, `group`, `mirror`, `lookup`, `standalone`: return the record or an
+  array of records. Returning `undefined` drops the record.
+- `user`, `scd-pre`, `funnel-pre`, `funnel-post`, `warehouse`: mutate `record`
+  in place. Return value is ignored.
+
+`standaloneEvents` runs before the user loop; `warehouseMetrics` materializes
+after it. Neither hook receives person metadata or enters `everything`.
+Standalone synthetic `distinct_id` values identify series, never people. Use
+disk-backed `duckdb` assertions on `{{PREFIX}}-STANDALONE*.json` for cadence
+stories. Warehouse stories support `warehouse` and `warehouse-stats`
+assertions, with automatic table audits even when no stories are exported.
+
+### 1.1 Warehouse rows (`type === 'warehouse'`)
+
+`warehouse` fires once per materialized row, after the user loop and before the
+rows are written to disk. the row already matches the manifest contract:
+
+- `timeColumn`
+- every `source.groupBy` key, in order
+- `valueColumn`
+- every declared key in `columns`
+
+declare every key up front. warehouse containers are created with a fixed column
+list, and the manifest is built from that same list. an undeclared key is not
+part of the output contract even if it exists briefly in memory.
+
+`meta.seriesKey` is the joined group tuple in `source.groupBy` order, separated
+by `|`. examples:
+
+- no `groupBy` → `''`
+- `groupBy: ['region']` and `row.region === 'us'` → `'us'`
+- `groupBy: ['region', 'plan_tier']` and `row.region === 'us'`, `row.plan_tier === 'enterprise'` → `'us|enterprise'`
+
+`meta.bucketIndex` and `meta.bucketCount` are chronological and include history
+buckets even when `sparse: true` skips repeated rows. `meta.isBackfill` is true
+for the synthetic buckets created by `history`. `meta.raw` is the bucketed
+source truth before `scale`, `noise`, and point-in-time carry-forward.
+
+Treat the time axis as immutable. `row[spec.timeColumn]` drives ordering,
+manifest SQL, and warehouse verification. mutate the value column or declared
+extra columns instead.
+
+Recipe: scale a point-in-time level for an in-window story slice
+
+```js
+warehouseMetrics: [{
+  name: 'daily_active_subscriptions',
+  type: 'point-in-time',
+  source: { event: 'subscription_started', minus: 'subscription_cancelled', groupBy: 'region' },
+  baseline: 40,
+  timeColumn: 'date',
+  valueColumn: 'active_subscriptions',
+  columns: { lifted: false },
+}],
+
+hook: (row, type, meta) => {
+  if (type !== 'warehouse') return row;
+  if (meta.metricName !== 'daily_active_subscriptions') return row;
+  if (meta.isBackfill) return row;
+
+  const liveIndex = meta.bucketIndex - meta.spec.history;
+  if (meta.seriesKey === 'us' && liveIndex >= 7 && liveIndex < 14) {
+    row.active_subscriptions = Math.round(row.active_subscriptions * 1.2);
+    row.lifted = true;
+  }
+  return row;
+}
+```
+
+Recipe: apply an incident dip to one series only
+
+```js
+warehouseMetrics: [{
+  name: 'daily_new_bookings',
+  source: {
+    event: 'new_booking',
+    measure: 'sum',
+    property: 'booking_value',
+    groupBy: ['region', 'plan_tier'],
+  },
+  timeColumn: 'date',
+  valueColumn: 'bookings',
+  columns: { incident: false },
+}],
+
+hook: (row, type, meta) => {
+  if (type !== 'warehouse') return row;
+  if (meta.metricName !== 'daily_new_bookings') return row;
+  if (meta.isBackfill) return row;
+  if (meta.seriesKey !== 'us|enterprise') return row;
+
+  const liveIndex = meta.bucketIndex - meta.spec.history;
+  if (liveIndex >= 14 && liveIndex <= 16) {
+    row.bookings = Math.round(row.bookings * 0.35);
+    row.incident = true;
+  }
+  return row;
+}
+```
 
 **What 1.7.0 changed for hooks.** No hook signature, `meta` field, or firing
 order changed, and the hook-helper atoms and patterns are untouched. What a hook

package/README.md

@@ -91,6 +91,11 @@ const result = await DUNGEON_MASTER({
 console.log(result.importResults);
 ```
 
+`token` imports event-shaped streams only: events, users, groups, ad spend, and
+`standaloneEvents`. `warehouseMetrics` does **not** import through this path.
+warehouse tables are materialized locally and need a separate warehouse deploy
+step after the run.
+
 ## dungeons
 
 a dungeon is a javascript file that exports a configuration object. it defines your entire data model: events, funnels, user properties, group analytics, SCDs, and a hook function that engineers discoverable patterns into the data.
@@ -537,6 +542,8 @@ dungeon-master generates multiple data types that mirror a real analytics implem
 | SCDs | `scdProps` | slowly changing dimensions (subscription tier over time) |
 | lookup tables | `lookupTables` | dimension tables (product catalog, region mapping) |
 | ad spend | `hasAdSpend` | daily ad spend with impressions, clicks, cost metrics |
+| standalone events | `standaloneEvents` | identity-less metric snapshots on a cadence (infrastructure, finance, ops) |
+| warehouse metrics | `warehouseMetrics` | warehouse source tables derived from generated events, with a manifest for downstream deploy |
 | mirror datasets | `mirrorProps` | transformed copies of event data (A/B versions) |
 | organic text | `createTextGenerator` | reviews, support tickets, search queries, chat messages |
 
@@ -606,6 +613,222 @@ variant assignment is **sticky by default**: a deterministic hash of `user_id` +
 
 **the variant lands on the user profile (1.7.0).** every exposed user carries `"Experiment: <name>": "<variant>"` (e.g. `"Experiment: Checkout Redesign": "New Checkout"`), so the funnel breaks down by variant in Mixpanel with a user-property breakdown — no cohort built from the exposure event. stamped when the user is first exposed (respects `startDaysBeforeEnd`); never-exposed users carry nothing; the `user` hook fires before exposure and does not see it, the `everything` hook does. `stampProfile: false` turns it off; `sticky: false` implies off. measured: 0 mismatches between the profile value and the `Variant name` on 13,005 exposure events.
 
+## standalone events (identity-less metric snapshots)
+
+`standaloneEvents` generates records that describe a **system, not a person**. they carry
+no `user_id` and no `device_id`. use them for infrastructure, finance, and ops telemetry:
+daily CDN egress per region, weekly billing rollups per plan tier, hourly queue depth per
+cluster. `hasAdSpend` is the same idea hard-coded to `$ad_spend`; this is the general form
+and it does not use a Mixpanel reserved event name.
+
+```javascript
+standaloneEvents: [
+  {
+    event: 'cdn_egress',
+    cadence: 'day',                                       // 'hour' | 'day' | 'week' (default 'day')
+    dimensions: { region: ['us-east', 'us-west', 'eu'] }, // cross-producted
+    distinctIdFrom: 'region',                             // synthetic id, never a person
+    properties: {
+      gb_out:   (ctx) => 400 + ctx.tickIndex * 3,         // shape a trend across the window
+      cost_usd: (ctx) => (400 + ctx.tickIndex * 3) * 0.085,
+      p95_ms:   [120, 140, 160],                          // same ValueValid forms as event props
+    },
+  },
+  {
+    event: 'billing_rollup',
+    cadence: 'week',
+    dimensions: { tier: ['free', 'pro', 'max'] },
+    properties: { mrr_usd: (ctx) => ..., churn_usd: (ctx) => ... },
+  },
+]
+```
+
+the engine emits **one record per cadence tick per dimension cross-product row**. the
+example above produces 3 records per day (`cdn_egress`) plus 3 records per week
+(`billing_rollup`). ticks start at the dataset start and step by the cadence; the last tick
+is the final one at or before the dataset end, so nothing lands in the future.
+
+each record carries `event`, `time`, `insert_id`, `distinct_id`, every dimension as a flat
+property, and every resolved entry in `properties`.
+
+| field | behavior |
+|---|---|
+| `event` | required, unique across `standaloneEvents` |
+| `cadence` | `'hour'`, `'day'`, or `'week'`. default `'day'` |
+| `dimensions` | object of non-empty arrays, cross-producted. omit for one record per tick |
+| `distinctIdFrom` | must name a declared dimension. omitted → `distinct_id` is the event name |
+| `properties` | keys may not collide with a dimension or with `event`/`time`/`insert_id`/`distinct_id`/`user_id`/`device_id` |
+
+property value functions receive a `StandaloneValueContext`: `{ time, config, dimensions,
+tickIndex, tickCount, cadence, event }`. `tickIndex / (tickCount - 1)` is window progress —
+use it to shape growth, a dip, or a spike, guarding `tickCount <= 1` before division.
+
+the stream lands in `result.standaloneEventData`, writes to its own `-STANDALONE` file
+shard, and imports to Mixpanel as its own event stream. hooks fire with type
+`"standalone"`; `meta.spec` carries the resolved config so a hook can tell streams apart.
+the hook runs before the user loop. return the record object or an array of records;
+returning `undefined` drops the record. it has no person metadata and never enters
+`everything`. warehouse hooks have a different contract: mutate the row in place;
+their return values are ignored.
+
+```javascript
+hook: (record, type, meta) => {
+  if (type === 'standalone' && meta.spec.event === 'cdn_egress' && record.region === 'us-east') {
+    record.p95_ms *= 40;
+  }
+  return record;
+}
+```
+
+validation throws rather than skipping. a malformed entry would silently drop a whole data
+stream, and you would not notice until the charts were wrong.
+
+## warehouse metrics (local source tables)
+
+`warehouseMetrics` materializes warehouse-ready tables from the run's own event
+stream after user generation completes. use it when you need a bookings table, a
+subscription level snapshot, or an ARR table that reads like a real warehouse
+source. these rows land in `result.warehouseMetricData`, write to
+`<name>-WAREHOUSE-<table>.csv|json`, and emit one manifest at
+`<name>-WAREHOUSE-MANIFEST.json`.
+
+they are **not** imported by `token`. that is deliberate. the live path is:
+
+1. run the dungeon
+2. review `/warehouse-metrics` in dry-run mode
+3. obtain explicit operator consent for live execution
+4. load the tables to bigquery and save the metrics there
+
+live deploy uses `bq load --replace`, so it overwrites the destination warehouse
+tables. the shipped script does not prompt on its own, so the operator or agent
+must obtain explicit consent before running it in live mode. if the
+warehouse CRUD docs route returns 404, the deploy still loads tables and connects
+the source, then writes `warehouse/GAPS.md` for manual metric creation.
+
+the manifest carries `recommendedAggregation: 'sum' | 'last value'`. the
+Mixpanel warehouse metric API spells that second value as `last_value`; the
+deploy flow maps it for you.
+
+there is one real preview trap: `previewWarehouseMetric` rejects raw SQL
+containing `DROP`, `DELETE`, `TRUNCATE`, `ALTER`, `CREATE`, `INSERT`, or
+`UPDATE` as plain substrings. `created_at` trips `CREATE`; `updated_at` trips
+`UPDATE`. aliasing only helps if the blocked text disappears from the query
+entirely.
+
+### canonical shapes
+
+additive daily bookings:
+
+```javascript
+warehouseMetrics: [{
+  name: 'daily_new_bookings',
+  source: {
+    event: 'new_booking',
+    measure: 'sum',
+    property: 'booking_value',
+  },
+  timeColumn: 'date',
+  valueColumn: 'bookings',
+}]
+```
+
+point-in-time daily active subscriptions:
+
+```javascript
+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',
+}]
+```
+
+sparse monthly ARR with backfill:
+
+```javascript
+warehouseMetrics: [{
+  name: 'monthly_arr_snapshot',
+  type: 'point-in-time',
+  grain: 'month',
+  sparse: true,
+  history: 18,
+  source: {
+    event: 'subscription_started',
+    minus: 'subscription_cancelled',
+    measure: 'sum',
+    property: 'monthly_value',
+  },
+  baseline: 24000,
+  scale: 12,
+  timeColumn: 'month',
+  valueColumn: 'arr_usd',
+}]
+```
+
+the shipped technical fixture uses a 60-day live window plus 18 monthly backfill
+buckets. sample row counts are illustrative only. `grain`, `history`, `sparse`,
+and `groupBy` all change how many rows a table emits.
+
+### config surface
+
+| key | default | range / contract |
+|---|---|---|
+| `name` | required | unique table / metric name, `/^[a-z][a-z0-9_]{0,63}$/` |
+| `type` | `'additive'` | `'additive'` or `'point-in-time'` |
+| `grain` | `'day'` | `'day'`, `'week'`, `'month'` |
+| `sparse` | `false` | boolean, valid only with `type: 'point-in-time'` |
+| `source.event` | required | string or string[] of declared source events |
+| `source.minus` | `[]` | string or string[] of declared subtractive events |
+| `source.measure` | `'count'` | `'count'`, `'sum'`, `'avg'`, `'dau'`, `'users'`; point-in-time forbids `'avg'` and `'dau'` |
+| `source.property` | `null` | required for `'sum'` and `'avg'`; must be declared on every source event or in `superProps` |
+| `source.where` | `null` | optional function over flat event rows |
+| `source.groupBy` | `[]` | up to 2 keys, each declared on every source event or in `superProps`; observed cardinality above 50 warns |
+| `timeColumn` | `'date'` | valid JS identifier; becomes the ordered time axis in rows and manifest |
+| `valueColumn` | `'value'` | valid JS identifier |
+| `baseline` | `0` | number `>= 0`; used only for point-in-time metrics, ignored on additive |
+| `scale` | `1` | finite number `> 0`, applied after bucket aggregation |
+| `noise` | `0` | finite number, clamped to `[0, 0.5]` with a warning |
+| `history` | `0` | integer `>= 0`; warns above roughly 3 years at each grain (`1095` day, `156` week, `36` month) |
+| `columns` | `{}` | extra declared output columns; keys must be valid identifiers and cannot collide with time/value/groupBy columns |
+| `format` | dungeon `format`, else `'csv'` | `'csv'` or `'json'` |
+
+materialized tables are deterministic at the same seed and do not perturb the
+event stream. the warehouse pass runs after the user loop, so seeded noise and
+derived columns never change generated events.
+
+### result and manifest
+
+```javascript
+const result = await DUNGEON_MASTER(config);
+
+result.warehouseMetricData.daily_new_bookings
+result.warehouseManifest.tables
+result.files
+```
+
+each manifest table includes:
+
+| field | meaning |
+|---|---|
+| `table` | warehouse table name |
+| `file` | file prefix without extension |
+| `format` | `'csv'` or `'json'` |
+| `grain` | bucket grain |
+| `type` | additive vs point-in-time |
+| `timeColumn` | date axis column |
+| `valueColumn` | numeric value column |
+| `dimensionColumns` | copied `groupBy` keys |
+| `columns` | ordered BigQuery schema (`DATE`, `FLOAT64`, `BOOL`, `STRING`) |
+| `recommendedAggregation` | `'sum'` or `'last value'` |
+| `sql` | `SELECT * FROM \`{{DATASET}}.<table>\` ORDER BY <timeColumn>` |
+| `refreshHint` | currently `'hourly'` |
+
 ## user generation
 
 users are generated with configurable birth distributions, normally controlled via the `macro` preset (see "time shape" above). these three knobs can also be set directly on the dungeon config — they override the preset's values.
@@ -697,8 +920,11 @@ result.userProfilesData  // user profiles
 result.scdTableData      // SCD mutations
 result.groupProfilesData // group profiles
 result.adSpendData       // ad spend data
+result.standaloneEventData // identity-less event snapshots
 result.lookupTableData   // lookup table entries
 result.mirrorEventData   // mirror dataset
+result.warehouseMetricData // warehouse tables keyed by metric name
+result.warehouseManifest // warehouse table manifest
 
 result.eventCount        // total event count
 result.userCount         // total user count
@@ -899,6 +1125,8 @@ see [types.d.ts](types.d.ts) for the complete `Dungeon` interface. here are the
 | `hasLocation` | boolean | false | include geo properties |
 | `hasCampaigns` | boolean | false | include UTM properties |
 | `hasAdSpend` | boolean | false | generate ad spend data |
+| `standaloneEvents` | array | `[]` | identity-less cadence streams that import as events |
+| `warehouseMetrics` | array | `[]` | local warehouse source tables + manifest, derived from generated events |
 | `hasAnonIds` | boolean | false | generate anonymous IDs |
 | `hasSessionIds` | boolean | false | generate session IDs |
 | `alsoInferFunnels` | boolean | false | auto-generate funnels from events |