@ak--47/dungeon-master 1.6.5 → 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,337 @@
 
 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
+the five round-two items (`dm-engine-round-two.md`) and the three round-one items
+that table missed (P0-3, P1-5, P1-6). Every behavior change below carries the
+number that proved the gap and the number after the fix, both from real
+generation passes (400 users × 60 days unless stated; scripts in the session
+scratchpad, assertions pinned in `tests/integration/v170-engine-requests.test.js`).
+
+**Output compatibility.** Same seed, same config, `concurrency: 1`, pinned window:
+1.7.0 and 1.6.5 produce byte-identical **events** (modulo `insert_id`) on every
+technical fixture that does not set `hasLocation` — `simplest`, `datagen-v15-verify`,
+`experiments`, `group-analytics`, `mirror-strategies`, `ad-spend`, `anonymous-users`
+(the funnel-step time pin below still runs TimeSoup, so the RNG stream is
+unchanged). Profiles and groups are identical where the fixture is deterministic
+(`datagen-v15-verify`, `ad-spend`, `anonymous-users`); `simplest`, `experiments`,
+`group-analytics` and `scd` build some profile/group props from their own unseeded
+`new Chance()` and were never run-to-run stable. Three changes alter output on
+purpose, each gated on a feature you would know you are using — see **Behavior
+changes** (B1–B3). The 10-test engine-shape canary passes; `smoke-test-all` runs
+22/22 shipped dungeons clean. The full 194-combo strict-bar sweep
+(`RUN_FULL_SWEEP=1`, 2026-09-04, window pinned to Wednesday 2026-09-02) passes
+191/194. The 3 failures are one config three times — `growth/365d/r1.2` with
+born `-`/`30`/`100`, which the growth cap resolves to the same 30 — failing the
+last-day bar at ratio 0.66 vs 0.70. Running the same `long` tier on 1.6.5 (`main`)
+produces the identical 3 failures with identical numbers, so this is a
+pre-existing, calendar-window-dependent marginal dip on one 365-day config, not a
+1.7.0 regression. Tracked as a follow-up; not a release blocker.
+
+**For DM4: tripwires that now flip.** `tests/integration/v5-engine.test.js` pins
+several of the old behaviors; when these assertions fail on 1.7.0 that is the fix
+landing, and the workaround it guards can go:
+- the spike hook for The Moment (`volumeMultiplier` amplifies — P0-3)
+- the flat-only born-share restriction (`macro: { bornRecentBias, percentUsersBornInDataset }` with no `preset` is uncapped — R2-1)
+- the 19-country `SINGLE_COUNTRY_NAMES` enum in `tests/v5-render.test.js` (`singleCountry: 'US'` works; a miss throws — R2-2)
+- the `importResults.users.success` overwrite (the receipt reconciles — R2-5)
+- the repeated-value weighting idiom (`{ __weights }` — P2-1)
+- the "fewer than two non-funnel events" refusal on Persona Difference — its premise was wrong; see P1-5 below
+
+### Tier 1 — silent lies fixed
+
+- **R2-1 `MacroConfig` object overrides.** Measured before: `macro: { preset: 'flat',
+  percentUsersBornInDataset: 50 }` → 10.3% born; `macro: { percentUsersBornInDataset: 50 }`
+  (no preset) → 10.0%; only the top-level key with no `macro` at all gave 52.3%.
+  Cause: the born% cap keyed the preset-less object to `flat` (12) and the warning was
+  `verbose`-gated. Now: a NAMED preset (string or `{ preset }`) is a shape contract and
+  still clamps — 12.3% after, with the clamp in `result.warnings`
+  (`{ key: 'percentUsersBornInDataset', requested: 50, applied: 12 }`); an object
+  WITHOUT `preset` is a custom macro and is honored as written — 55.0% after for
+  `{ percentUsersBornInDataset: 50 }`, 48.8% for `{ bornRecentBias: 0.3, percentUsersBornInDataset: 50 }`.
+  Canonical spelling: `macro: { preset, ...overrides }`; the top-level keys are a legacy
+  alias that wins over the object. Documented in README, `MacroConfig` JSDoc, CLAUDE.md.
+- **R2-2 `singleCountry`.** Accepts the ISO code or the full name, case-insensitive
+  (`resolveSingleCountry`, also hoisted from `switches`). A value matching no country
+  THROWS with the list of valid values. Measured before: `'US'` and `'Narnia'` both
+  silently deleted every geo property from events and profiles; after: `'US'` → 100%
+  `country_code: US` on events and profiles.
+- **R2-3 `strictEventCount` is exact.** Before: stopped on the GENERATED count (drops
+  included) and never topped up — 4,987 of 5,000 with ~4x headroom (DM4 measured 4,705
+  on its config). Now: the bailout reads the STORED count; a per-user budget controller
+  scales the remaining users' budgets by (events still needed ÷ expected remaining
+  delivery at the realized yield), clamped to [0.25, 4], aiming slightly high; the
+  final user's stream is trimmed with a seeded uniform sample so the count never
+  exceeds the target. Measured: 5,000 of 5,000; 30,000 of 30,000; test pins 3,000 of
+  3,000. When capacity cannot reach the target (e.g. a churn event ends every user
+  early) the run stops short and `result.warnings` carries
+  `{ key: 'numEvents', requested, applied }`. User creation still stops once the target
+  is met (legacy). Only under the flag — the default path is untouched.
+- **R2-5 profile receipt.** `importResults.users` now carries `generated` (profiles the
+  engine pushed to storage, bots included) and `dropped_anonymous` (`_drop`-flagged
+  anonymous non-converters never sent to `/engage`) alongside mixpanel-import's
+  `success` / `failed`, so `generated - dropped_anonymous - failed === success` is
+  checkable. Counters tick at push time, so they hold in batch mode. The sender logs
+  a line when the receipt does not reconcile. DM4's "100 generated, 45 reported" is
+  now decidable from the result object.
+
+### Tier 2 — the deferred 1.7.0 feature set
+
+- **P0-1 `funnels[].conditions`: operators, validation, docs, tests.** Operator maps
+  `eq`, `neq`, `in`, `nin`, `gt`, `gte`, `lt`, `lte` (AND within a key, AND across keys;
+  no `or`); the scalar shorthand is unchanged. Matching moved to
+  `lib/utils/conditions.js` (re-exported from user-loop). The validator THROWS on
+  shapes that silently never matched — function values, bare arrays (points at
+  `{ in: [...] }`), unknown operators, `in`/`nin` without an array — and warns into
+  `result.warnings` when a condition key is declared nowhere the profile is built from.
+  Users who satisfy none of the author's funnels (the engine catch-all excluded) are
+  counted and reported once per run (`key: 'funnels.conditions'`). Measured: iOS 80.2%
+  vs Android 39.8% purchased-per-viewed on the duplicate-funnel idiom; `{ gte: 10 }` 89.7%
+  vs `{ lt: 10 }` 20.0%. README "segmented funnels", typed `FunnelConditions`, 30 unit
+  cases + integration coverage of the filter branch that had none.
+- **P0-2 experiment variant on the profile.** Every exposed user carries
+  `"Experiment: <name>": "<variant>"`, stamped lazily at first exposure (so
+  `startDaysBeforeEnd` is respected and never-exposed users carry nothing), before the
+  `everything` hook. `experiment.stampProfile` (default `true`) opts out; `sticky: false`
+  implies off. Not stamped on step events (would be undeclared columns). Measured: 0
+  mismatches against `Variant name` on 13,005 exposure events.
+- **P1-1 `(ctx) => value`.** `choose(value, ctx)` passes
+  `{ profile?, event?, time?, config }` to every property function. Zero-arity functions
+  are untouched; a function that declares a parameter is context-aware and skips the
+  source-string cache (which would otherwise freeze its first result). Bound natives
+  (`chance.animal.bind(chance)`) are still called with no argument. Funnel steps after
+  the first now know their final time before properties resolve (`fixedTimeMs`, fed by
+  a synchronous side channel from step 0) — TimeSoup still runs so the RNG stream is
+  unchanged; context-aware step properties defer from `buildFunnelEvents` into
+  `makeEvent`. `json-evaluator` emits `(ctx) => body` for expression bodies and passes
+  whole-function bodies through unwrapped. Measured: 203 of 203 `pro` users got
+  `revenue: 100` from `(ctx) => ctx.profile.plan === 'pro' ? 100 : 0`; 0 events without
+  profile context.
+- **P1-2 `stickyEventProps` + stable location (B2).** `stickyEventProps: ['plan_tier']`
+  copies the profile value onto every event after `superProps`, before the `event`
+  hook; keys declared only in `superProps` resolve once per user. Schema-first: undeclared
+  keys throw; `lib/verify/schema-validator.js` treats sticky keys as legal on every event.
+  Measured: 67,355 of 67,355 events matched the profile. **B2:** with `hasLocation: true`
+  a user's events now share the user's location — `featureCtx.userLocation` was computed
+  and never read; measured 0.8% of events matched their profile city before, 100% after.
+- **P1-3 `personas[].ttcModifier`.** Multiplies `timeToConvert` after the experiment
+  `ttcMultiplier`, before `funnel-pre`. Measured median TTC 0.50h vs 1.96h for 0.25 vs 1.
+  **B3:** `churnRate`, `activeWindow`, `soupOverride` removed from the `Persona` type
+  (never implemented); the validator still accepts and warns on them, and no longer
+  defaults `churnRate`.
+- **P1-4 `campaignPerUser`.** One campaign template per user at birth; UTMs stamped on
+  the profile and reused on every touchpoint. Profile UTM keys already present (persona
+  `properties`, `user` hook) win over the draw, so a persona can own a channel. Measured:
+  0 of 399 users with more than one `utm_source` (400 of 400 before). Ad spend derived
+  from acquisitions is deferred to 1.8.0.
+- **P2-1 `{ __weights }` + `autoPowerLaw`.** `{ __weights: { free: 60, pro: 30,
+  enterprise: 10 } }` draws exactly those shares (measured 239/123/38 over 400 users);
+  `autoPowerLaw: false` turns the implicit 45/25/15 draw off for the run (module flag set
+  per run, reset with the value caches). Both round-trip through `dungeon-to-json`.
+- **P2-2 `result.warnings[]`.** Always present. Validator clamps (`percentUsersBornInDataset`,
+  `bornRecentBias`, compound bias, `avgEventsPerUserPerDay`, `avgActiveDaysPerUser`,
+  `numDays < 14`, `engagementDecay` + active days, auto-set `conversionWindowDays`) plus
+  runtime aggregates via `context.addWarning` (one entry per key with `count`). Console
+  output stays `verbose`-gated. `EngineWarning` type.
+- **P2-4 `conversionRate` saturation.** Every engine clamp of a modified rate above 100
+  — experiment variant, persona, world event, or whatever a `funnel-pre` hook left behind
+  — is reported once per funnel and source
+  (`funnels[Buy].conversionRate:persona "whale" conversionModifier`, requested 195,
+  applied 100). The engine cannot see a hook's own `Math.min(95, rate * 3)`; HOOKS.md
+  says so.
+
+### Tier 3 — open items outside the deferred table
+
+- **P0-3 `worldEvents[].volumeMultiplier > 1` amplifies.** New per-user pass
+  `amplifyWorldEvents` clones affected in-window events — `floor(m − 1)` copies plus one
+  with probability `frac(m)` — each with a fresh `insert_id` and a timestamp spread
+  uniformly across the window (never past the dataset end), after the churn cut and
+  before decay and hooks. Measured 3x on a 4-day window: **1.08x before, 3.06x after**,
+  all `insert_id`s unique, clones on every window day; 1.5x lands in [1.3, 1.7].
+  `aftermath.volumeMultiplier` follows the same rule. Validation rejects negative or
+  non-finite multipliers.
+- **P1-5 `eventMultiplier` and funnels — the premise was wrong.** The multiplier scales
+  the whole per-user budget, which drives funnel passes too: measured **3.19x / 2.96x**
+  for an asked 3x with every event a funnel step. DM4's 0.96x came from its fixture's
+  `isChurnEvent` (`Churned`, weight 1, `returnLikelihood: 0.15`): a churn event in the
+  standalone pool ends every user after roughly the same number of events regardless of
+  budget — measured **1.04x with the churn event, 2.90x without**, same config. The
+  engine now reports it (`key: 'personas.eventMultiplier'`) when more than half the
+  users churn while a persona multiplier is in play; `eventMultiplier` and `isChurnEvent`
+  docs state the cap. DM4 should replace its "fewer than two non-funnel events" check
+  with a churn-event check.
+- **P1-6 day-1 retention floor — documented (option 2).** `retentionCurve` picks session
+  days; retention counts events; birth-day funnels spill into day 1 regardless of the
+  day plan, so day 1 sits near 0.85 (DM4 measured 0.885 for an asked 0.15; days 7 and 30
+  follow the curve). Stated in the `retentionCurve` JSDoc, README config table, and
+  HOOKS.md §2.7. Verify from day 7 on.
+
+### Behavior changes (not purely additive)
+
+- **B1** — `conditions` values that are functions or bare arrays now THROW at validation.
+  Any dungeon relying on them was already producing an empty funnel.
+- **B2** — `hasLocation: true` now yields one stable location per user on events instead
+  of a fresh random city per event. Event geo distributions change; `scd.js` (the one
+  technical fixture with `hasLocation`) is the reference.
+- **B3** — `churnRate`, `activeWindow`, `soupOverride` are gone from the `Persona` type.
+  Runtime still accepts them with the existing once-per-process warning.
+- World-event windows on funnel steps after the first now test the step's FINAL time
+  (previously the pre-offset TimeSoup time). Only dungeons combining `worldEvents` with
+  multi-step funnels see different `_drop` / `injectProps` decisions; the fix is what the
+  docs always described.
+
+### Not built (by request)
+
+Session replay, per-funnel `soup`, `or` conditions, anything in `stories` / `verify` /
+`emulateBreakdown`, and ad spend derived from acquisitions (P1-4 item 3, 1.8.0). R2-4
+(the verticals as DM4 templates) is deferred to its own sprint per AK: each vertical
+should demonstrate a different declarative trend type so the template gallery doubles
+as a catalog demo; the R2-4 audit stands as that sprint's punch list.
+
 ## 1.6.5 — 2026-09-02
 
 ### Changed

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,130 @@ 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
+SEES did change in five places:
+
+1. `event` hook on funnel steps after the first: `record.time` is now the step's
+   FINAL time. Before 1.7.0 it was the pre-offset TimeSoup time, overwritten after
+   the hook returned — a hook that derived a property from `record.time` on step 2+
+   was reading the wrong timestamp.
+2. `everything` hook: the array already contains world-event clones
+   (`volumeMultiplier > 1`), `stickyEventProps` values on every event, and one
+   stable location per user under `hasLocation`. `meta.profile` carries
+   `"Experiment: <name>"` for exposed users (stamped before `everything`, after `user`).
+3. `funnel-pre`: `record.timeToConvert` already includes the persona `ttcModifier`
+   (like `conversionModifier` today). The hook stays the final authority. A rate the
+   hook leaves above 100 is clamped downstream exactly as before and now shows up in
+   `result.warnings`.
+4. `user` hook: under `campaignPerUser` the profile already carries the drawn
+   `utm_*` keys; a hook that overwrites them wins, and the touchpoint pass reads the
+   final values. `stickyEventProps` values are read from the profile AFTER the hook.
+5. Hooks may not add properties (rule 1) — `stickyEventProps`, the experiment
+   profile key, and world-event clones are engine-stamped and declared, so the
+   schema validator accepts them. Prefer these declarative knobs over a hook when
+   they express the story (README "segmented funnels", "sticky event properties",
+   "campaigns per user").
 
 ---
 
@@ -399,6 +524,17 @@ All items on the v1.5.0 "documented gaps" list closed in 1.6.0. Unrecognized
 retention option keys now THROW — kills the silent-ignore class of bug where a
 typo'd `compounded: true` was dropped without effect.
 
+**`retentionCurve` cannot move day 1 (v1.7.0 doc).** `buildActiveDayPlan`
+picks which UTC days a user gets a SESSION; retention counts EVENTS. A funnel
+opened on the birth day spills its later steps across the following
+`timeToConvert` hours regardless of the day plan, so day 1 sits on a floor
+near 0.85 for funnel-driven dungeons no matter what `day1` asks for. Measured
+(2,000 users, 60 days): `{ day1: 0.15, day7: 0.06, day30: 0.02 }` delivered
+day 1 = 0.885, day 7 = 0.151, day 30 = 0.060 — the curve governs from day 7
+on and over-delivers by a consistent ~2.5x there. Verify retention stories from
+day 7 onward. To lower day 1, shorten `timeToConvert` on the funnels users
+enter on birth, or drop next-day spill in an `everything` hook.
+
 ### 2.8 Funnel reentry: state machine resets after completion
 
 Reference: `history.cpp` (`last_step_starts_next_funnel`). With reentry
@@ -813,6 +949,19 @@ if (type === "funnel-pre") {
 Greedy funnel engine (Section 2.2) applies after — keep `conversionRate`
 adjustments modest (1.2x is comfortable; 3x can saturate at the 95% cap).
 
+**Saturation is reported, but only the engine's own clamp (v1.7.0, P2-4).** When a
+persona `conversionModifier`, an experiment variant, a world event, or the value a
+`funnel-pre` hook leaves behind pushes `conversionRate` above 100, the engine
+clamps to 100 and adds one aggregated entry per funnel and source to
+`result.warnings` (`funnels[Checkout].conversionRate:persona "whale"
+conversionModifier`, `requested: 195`, `applied: 100`). It cannot see a hook's own
+cap: `record.conversionRate = Math.min(95, rate * 3)` on a base of 65 yields 95 — a
+1.46x lift, not 3x — and the engine never learns the intended 195. To get a true
+multiple, read the base rate and solve for it, or lower the base rate so the multiple
+fits under the cap. For "one segment converts differently on one funnel" prefer the
+declarative `funnels[].conditions` (README "segmented funnels") over a `funnel-pre`
+hook — it needs no cap arithmetic.
+
 ---
 
 #### 4.2 Feature Launch Inflection