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

package/HOOKS.md

@@ -1,9 +1,9 @@
 # HOOKS.md -- Hook Encyclopedia
 
-Hook reference and recipe catalog for dungeon-master. Every recipe is calibrated
-against Mixpanel's actual counting semantics (greedy single-pass funnels,
-distinct-period frequency, null-aware aggregation, capped attribution) — see
-[Section 2](#2-how-mixpanel-counts-things) before adapting any pattern.
+Hook reference and recipe catalog for dungeon-master. Recipes have different
+counting and evidence requirements. Read [Section 2](#2-how-mixpanel-counts-things)
+before adapting a pattern, then verify the exact report on the emitted dataset.
+The [1.8.2 guide](docs/guides/1.8.2-upgrade-guide.md) records live-tested scope and limits.
 
 ---
 
@@ -172,20 +172,28 @@ verification emulator (`@ak--47/dungeon-master/verify`) now matches these
 rules; old recipes that ignored them will look correct on the dataset but
 fail when verified or queried in Mixpanel.
 
-### 2.1 Frequency reports count DISTINCT PERIODS, not total events
+### 2.1 Frequency depends on the selected report
 
-Mixpanel's frequency distribution / cohort-by-event-count reports count
-**distinct time periods** (default: days) on which the user fired the
-event. Two purchases on the same day = frequency **1**, not 2.
+Three measurements require different checks:
+
+- **Raw per-user event count:** two purchases on one day count as two. Insights
+  per-user count histograms and frequency breakdowns using total event count use
+  this axis. `applyFrequencyByFrequency` scales this target count.
+- **Distinct calendar-day activity:** those purchases count as one active day.
+  `countDistinctPeriods` defaults to UTC calendar buckets (`ui-bucket`), and
+  `binBy: 'distinctDays'` uses the same rule. This default is retained for
+  compatibility; it is not a universal Mixpanel frequency-report rule.
+- **Rolling Frequency/Addiction:** an event counts when it is at least one
+  selected unit after the last counted event. Histories reset per report interval.
+  Two events around midnight can occupy two calendar days but one rolling period.
 
 Two related rules exist (v1.6 names them for what they are; the old
 `'calendar'` / `'rolling'` names remain as silent aliases, unknown names
 now throw):
 
 - **`algorithm: 'ui-bucket'`** (default in our verifier):
-  `COUNT(DISTINCT date_trunc(unit, time))` in UTC. Matches what the Mixpanel
-  UI shows and what [`injectOnNewDays`](lib/hook-helpers/inject.js) uses
-  internally.
+  `COUNT(DISTINCT date_trunc(unit, time))` in UTC. This is also what
+  [`injectOnNewDays`](lib/hook-helpers/inject.js) uses internally.
 - **`algorithm: 'mixpanel-rolling'`**: the C++
   `addiction_query.cpp` rule `qtz_time >= last_counted + seconds_for_unit`
   (`addiction_query_update_history`, `addiction_query.cpp:363-374`) — what
@@ -193,8 +201,8 @@ now throw):
   boundaries (events at 23:59 + 00:01 next day = 1 rolling period, 2
   calendar periods).
 
-Use the default (`ui-bucket`) for hooks. Use `'mixpanel-rolling'` only
-when verifying behavior that explicitly depends on the C++ implementation.
+Choose the algorithm from the requested report. Do not replace a raw-count
+histogram with active-day counts, or use calendar days to claim rolling parity.
 
 **The actual Frequency report shape** is `frequencyHistogram(events,
 { event, unit, intervalDays, profiles })` (v1.6): per report interval, a
@@ -205,19 +213,19 @@ zero bucket (`addiction_query.cpp:546-573`). Array length is
 `ceil(interval / unit)` (`unit.c:108-113`). Use it when a dungeon targets
 the Frequency report itself rather than a frequency-derived cohort.
 
-**Implication for hooks:** `scaleEventCount(record, "Buy", 3)` clones 3x as
-many Buy events at sub-second offsets — they all land on the same calendar
-day, so the user moves **zero bins** in Mixpanel's frequency report. Use
+**Implication for hooks:** `scaleEventCount(record, "Buy", 3)` targets 3x as
+many Buy events at one-second offsets. This changes raw-count histogram bins.
+It generally does not add active days or rolling periods. Use
 [`injectOnNewDays`](lib/hook-helpers/inject.js) when the goal is to move
-users between frequency bins. Both `injectOnNewDays` and the default
+users between calendar-day activity bins. Both `injectOnNewDays` and the default
 `countDistinctPeriods` algorithm use calendar-bucket math, so they agree
 at boundaries.
 
 One second is also below Mixpanel's 30-minute session gap, so the default
 spread cannot create a new session either. The full list of metrics a default
-`scaleEventCount` call **cannot** move: active days per user, DAU, stickiness
-(DAU÷MAU), sessions per user, frequency bins, and retention. It moves event
-volume, and nothing else.
+`scaleEventCount` call does not reliably move: active days per user, DAU,
+stickiness (DAU/MAU), sessions per user, rolling frequency, and retention.
+At dataset edges, clones can be clipped. Verify surviving counts separately.
 
 As of v1.6.4 you can pass `{ spreadDays: N }` to scatter the clones across the
 next N days instead:
@@ -363,7 +371,7 @@ sampling.
 
 ### 2.5 Active-day distribution is config-first
 
-Mixpanel frequency reports count distinct days (§2.1). The v1.5 engine
+Distinct-day activity is a separate measurement from raw counts (§2.1). The engine
 exposes `Dungeon.avgActiveDaysPerUser` as the canonical primitive for this
 shape. Set it at the config level and the engine concentrates each user's
 events onto a sampled subset of days drawn from `normal(mean=N, sd=N/3)`,
@@ -537,12 +545,22 @@ 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
-enabled, after the state machine reaches the final step the engine resets to
-step 0 and continues scanning. `result.completions` reports the total. In
-`countMode: 'totals'` the engine returns one `FunnelResult` per completion
-(simultaneous histories — one user, many funnel completions). Without
-reentry the funnel runs once per user.
+Reference: `history.cpp` (`history_is_mutable`) and `funnel_query.cpp`
+(shared first/last step handling). With `reentry: true`, completion absorbs
+events through the inclusive 2-second grace period. The next event beyond
+grace starts the next scan. Conversion-window expiry can restart earlier.
+`graceperiod: false` disables the completion wait.
+
+When an event records the ordered last step and also matches the ordered
+first step, it closes one attempt and anchors the next immediately. Both
+selectors must match. Any-order edges do not use this exception.
+`woRepeat` still restarts only at window expiry.
+
+`result.completions` reports repeat completions in uniques mode. In
+`countMode: 'totals'`, the engine returns one `FunnelResult` per attempt,
+including partial attempts. **Compatibility unchanged:** `reentry` defaults
+to `false`, even for totals. Totals alone does not enable analytics general
+counting's repeat-history behavior.
 
 ### 2.9 HPC (Hold Property Constant) — parallel sub-funnels
 
@@ -555,13 +573,24 @@ directly, or (v1.6) pass `holdPropertyConstant: '<prop>'` to the
 `funnelFrequency` emulator — it routes through the HPC engine and reports
 per-held-value sub-funnel counts.
 
+Session windows derive ordinals from the full user stream before HPC
+partitioning. Events with another held value can bridge a session but cannot
+fill steps in the current bucket. This applies to explicit session windows
+and `countMode: 'sessions'`. The local session defaults remain a 30-minute
+timeout, 24-hour maximum, and UTC day boundaries.
+
 ### 2.10 Funnel segment modes (FIRST_TOUCH / LAST_TOUCH / STEP)
 
 Reference: `options.hpp` `funnel_segment_mode`; `history.cpp`
 `property_set_buffer`. The engine snapshots the matched event's properties
-at every funnel step. Segmentation chooses which step's properties to use:
-FIRST_TOUCH (step 0), LAST_TOUCH (last reached), or STEP N (specific index).
-Enable with `evaluateFunnel({ trackStepProperties: true })`, then pick with
+at every reached position. FIRST_TOUCH and LAST_TOUCH merge those snapshots
+in recorded path order, including partial and any-order paths. The first
+or last defined non-null value wins, respectively. Undefined never replaces
+a defined value; null never replaces a defined non-null value. If only null
+and undefined are present, null wins. Snapshots remain unchanged.
+
+STEP N selects one reached position without merging fallback values.
+Enable with `evaluateFunnel(events, steps, { trackStepProperties: true })`, then pick with
 `resolveFunnelSegment(result, 'first' | 'last' | { step: N })`.
 
 ### 2.11 Engine-validation guarantees (v1.5+)
@@ -855,15 +884,12 @@ Reference: `flows_query.cpp:988-994` (next-anchor-only), `flows.cpp:680-717`
 
 ### New principles from the emulator alignment
 
-21. **Distinct-day vs total-event binning.** Frequency-distribution reports in
-    Mixpanel count distinct days (Section 2.1). For any hook whose verification
-    target is a frequency report, use [`binByDistinctPeriods`](lib/verify/counting.js)
-    instead of `binUsersByEventCount`. For hooks targeting raw event counts
-    (Insights `total events`, `events per user`), `binUsersByEventCount` is
-    still correct.
+21. **Match the bin to the report.** Use `binUsersByEventCount` for raw event
+  counts and `binByDistinctPeriods` for calendar-day activity. Use rolling
+  counting for the Frequency/Addiction report. Section 2.1 distinguishes them.
 
-22. **`scaleEventCount` does not move users between frequency bins.** Cloning
-    Buy events at sub-second offsets places them on the same calendar day and
+22. **`scaleEventCount` changes raw-count bins.** Cloning
+  Buy events at one-second offsets usually places them on the same calendar day and
     inside the same 30-minute session window, so distinct days, sessions, DAU,
     stickiness, and retention are all unchanged. It moves event volume only. To
     shift any of the others, pass `{ spreadDays: N }` (v1.6.4) or use
@@ -877,11 +903,10 @@ Reference: `flows_query.cpp:988-994` (next-anchor-only), `flows.cpp:680-717`
     after the prior step's timestamp (with margin > 2 seconds for the grace
     window).
 
-24. **Attribution stamping is capped at 10 touchpoints.** When biasing
-    `firstTouch` attribution by stamping touchpoint events, ≤10 touches per
-    user enter the candidate pool. Stamping 50 weighted Touch events per
-    user gives the same answer as stamping 10. Aim for sparse, distinct
-    touches with deterministic weight ratios.
+24. **Separate stamping caps from attribution reads.** The generator defaults
+  to ten stamped touches per user. Mixpanel first/last reads are uncapped
+  within their conversion-bounded lookback. Distinct touch timestamps avoid
+  ambiguous attribution when different values tie at the first or last time.
 
 25. **Null-aware aggregation removes the need to "fill" defaults.** Don't
     coalesce missing numeric properties to 0 to keep AVG sane — Mixpanel
@@ -1720,6 +1745,13 @@ touch with a seeded weighted pick (models: `firstTouch`, `lastTouch`,
 `both`). It never stamps unstamped events, so total touch count is
 unchanged.
 
+The helper selects lifetime endpoints. A report reads eligible touches before
+each conversion and inside its lookback. The lifetime-last touch can occur after
+the conversion; the lifetime-first can expire. Neither endpoint is a general
+conversion-aware guarantee. Pass a deliberately eligible stream to the existing
+helper or implement that selection in the hook, then verify the requested report.
+Conflicting sources at an equal timestamp have no stable cross-ingestion order.
+
 ---
 
 #### 4.27 Active-Day Cohort Engineering (v1.5)
@@ -1843,8 +1875,9 @@ event set rather than one value moment.
 **Hook:** `everything`
 **Mixpanel report:** Flows — top paths after the anchor event show the engineered branch (Section 2.17)
 
-**In Mixpanel:** ~30% of users who view an item proceed straight down
-`add to cart → begin checkout`, making it the dominant Sankey branch.
+**In Mixpanel:** Bias the first branch toward `add to cart → begin checkout`.
+The helper selects ~30% of users for append-only injection. Existing traffic
+can interrupt the branch; the final branch share is not guaranteed to be 30%.
 
 ```js
 import { applyPathBias } from "@ak--47/dungeon-master/hook-helpers";
@@ -1889,6 +1922,8 @@ if (type === "everything") {
     sessionsPerWeek: 3,
     eventsPerSession: 5,
     sessionMinutes: 25,
+    datasetStart: meta.datasetStart,
+    datasetEnd: meta.datasetEnd,
   });
 }
 ```
@@ -1897,12 +1932,35 @@ if (type === "everything") {
 event set (after the `everything` hook), so wholesale timestamp rewrites no
 longer leave stale session labels. The atom keeps intra-session gaps well
 under the 30-min timeout (spacing capped at 20min + bounded jitter), keeps
-inter-session gaps well over it, and never crosses UTC midnight inside one
+inter-session gaps over it when explicit bounds are supplied, and never crosses UTC midnight inside one
 engineered session (the day-boundary split would cut it). Retiming only — no
 events are added or dropped, so total counts and event mixes are untouched.
 Session count follows `min(sessionsPerWeek × weeks, ceil(N /
 eventsPerSession))`: scarce users get fewer sessions, not fabricated events.
 
+`datasetStart` and `datasetEnd` are additive, optional arguments. Existing
+calls with neither bound keep the original full-UTC-day placement between
+the user's first and last active days. A two-event stream at 12:00/12:20 can
+still request two sessions with `eventsPerSession: 1` and `sessionMinutes: 5`.
+Legacy overfull requests also keep their old behavior: they do not throw,
+but their clusters can merge under the 30-minute timeout.
+
+The bounds accept ISO strings, unix seconds, or unix milliseconds. Hook
+metadata uses unix seconds and can be passed directly, as in the example.
+Either bound enables constrained placement; an omitted side uses the start
+of the first active UTC day or the end of the last active UTC day. The helper
+cannot infer `datasetEnd` from the last event. Pass known bounds when the
+dataset ends partway through an active day, including an inclusive midnight
+endpoint, to prevent later engine clipping.
+
+With explicit bounds, partial days compress clusters, including zero-duration
+clusters at midnight. If the requested sessions cannot fit inside a week's
+available day slices, the helper throws `RangeError` before changing any
+events. Invalid bounds also throw. It never silently reduces the target or
+drops records. Widen the allowed window or reduce the session target. Exact
+session separation assumes UTC and the default 30-minute timeout, without
+a maximum session duration.
+
 ---
 
 ## 5. Phase 3 Atom Reference
@@ -1933,7 +1991,7 @@ Import from `@ak--47/dungeon-master/hook-helpers`:
 | `splitByAuth` | identity | `(events, authTime) -> { preAuth, postAuth, stitch }` | Partition by auth boundary |
 | **`applyLifecycleWave`** | shape | `(events, uid, { dormantFromDay, dormantDays, resurrectBurst?, valueMomentEvent, dropAll? }) -> events[]` | Clean dormancy gap + resurrection burst; sweeps the ENTIRE window by timestamp (v1.6, recipe 4.29). Returns a NEW array |
 | **`applyPathBias`** | shape | `(events, uid, { anchor, path, share, gapSeconds? }) -> events[]` | Inject a Flows path after the user's first anchor for ~`share` (fraction) of users; skips users missing any step template (v1.6, recipe 4.30) |
-| **`applySessionShape`** | shape | `(events, uid, { sessionsPerWeek, eventsPerSession, sessionMinutes }) -> events[]` | Retime the stream into deterministic session clusters — intra-gaps ≪ 30min, inter-gaps ≫ 30min, never crosses UTC midnight (v1.6, recipe 4.31) |
+| **`applySessionShape`** | shape | `(events, uid, { sessionsPerWeek, eventsPerSession, sessionMinutes, datasetStart?, datasetEnd? }) -> events[]` | Preserve records; default legacy full-UTC-day placement. Optional bounds constrain placement and throw atomically on insufficient capacity (recipe 4.31) |
 
 **Inject atoms + v1.5:** the engine auto-sorts events by time after the
 `everything` hook (`autoSortAfterEverything: true` default — see Principle

package/README.md

@@ -18,6 +18,10 @@ i built this because i needed it. and after using it across hundreds of customer
 npm install @ak--47/dungeon-master
 ```
 
+1.8.2 adds live counting verification and fixes identity, session-funnel,
+attribution, and experiment-filter defects. See the
+[upgrade guide](docs/guides/1.8.2-upgrade-guide.md) for compatibility and tested limits.
+
 ## quick start
 
 ```javascript
@@ -957,7 +961,7 @@ styles: `support`, `review`, `search`, `feedback`, `chat`, `email`, `forum`, `co
 ## scripts
 
 ```bash
-npm test                      # full vitest test suite
+npm test                      # default unit/integration/e2e suite; prunes data/tmp
 npm run typecheck             # typescript check
 npm run dungeon:run           # run a dungeon file locally
 npm run dungeon:to-json       # convert JS dungeon to JSON (for UI import)
@@ -978,6 +982,8 @@ node scripts/verify-runner.mjs <path> [prefix]   # generate at full fidelity for
 
 ## tests
 
+1.8.1 compatibility and output changes: [upgrade guide](docs/guides/1.8.1-upgrade-guide.md).
+
 vitest tests live under `tests/` in three tiers:
 
 | dir | scope | wall time |
@@ -999,6 +1005,40 @@ npx vitest tests/unit                                       # watch mode
 
 `tests/e2e/engine-shape-full-sweep.test.js` skips itself unless `RUN_FULL_SWEEP=1` is set (it wraps the long-running 194-combo engine sweep).
 
+### editor and offline alignment tests
+
+VS Code discovers unit, integration, E2E, and alignment tests through one serial
+`vitest.editor.config.js`. The workspace disables Go test
+discovery and ignores the overlapping diagnostic Vitest configs. After changing
+these settings, run **Developer: Reload Window** if stale providers or test runs
+remain in the Testing panel. Editor runs omit the pruning setup, but they are not
+OS-sandboxed.
+
+Use **Tasks: Run Test Task** for `test: regression (offline, macOS)`, or choose
+the named alignment and sweep tasks from **Tasks: Run Task**. These test tasks
+never invoke the prune or dungeon-run tasks. Existing dungeon-run cleanup is
+unchanged and remains separate from testing.
+
+The `test: engine matrix`, `test: engine short sweep`, and `test: engine full sweep`
+tasks expose the direct-run engine checks. They are opt-in and use OS network denial.
+The full engine wrapper is visible under E2E but skipped until `RUN_FULL_SWEEP=1`.
+Direct-run `.mjs` scripts are not Vitest tests, so they do not get a separate
+`engine` folder in the Testing tree. The legacy engine sweeps do not use the
+alignment runner's ten-minute deadline. E2E tests may write files or perform
+network operations when run directly in the editor; editor execution is not an
+offline guarantee.
+
+```sh
+node tests/alignment/run.mjs                               # offline alignment gate
+node tests/alignment/run.mjs --sweep --timeout-ms=600000    # opt-in bounded sweep
+```
+
+Alignment is a separate test family, excluded from `npm test` but visible in the editor.
+Its runner enforces OS network denial on macOS, fails closed elsewhere, and kills
+workers at the ten-minute deadline. Tests and reports live in the source checkout;
+they are not included in the npm package. The default `npm test` and direct root
+Vitest commands still prune `data` and `tmp` through their global setup.
+
 ### engine tests (direct-run, NOT vitest)
 
 `tests/engine/` houses direct-run regression tests at scale. these are NOT vitest-compatible — invoke with `node` directly. used to catch engine regressions across a wide variety of dungeon configurations and for ad-hoc chart inspection. outputs land in `./tmp/` (gitignored).

package/docs/guides/1.8.1-upgrade-guide.md

@@ -0,0 +1,153 @@
+# 1.8.1 Upgrade Guide
+
+1.8.1 repairs funnel counting, lifecycle timing, and emitted identity. Existing
+configurations and call forms remain supported. No property renames or required
+configuration changes are introduced. `applySessionShape` adds optional dataset
+bounds; its existing unbounded calls retain their behavior.
+
+Generated timestamps, identities, and report counts can change from 1.8.0 because
+the previous output contained defects. Recheck saved story expectations rather
+than expecting byte-identical output across versions.
+
+## Update the dependency
+
+After 1.8.1 is published:
+
+```sh
+npm install @ak--47/dungeon-master@1.8.1
+```
+
+No additional runtime dependency is required. The package still requires Node.js
+20.20.0 or newer. This guide does not indicate that npm publication has occurred.
+
+## Funnel counts can change
+
+- An ordered funnel whose first and last steps match now finalizes its conversion
+  correctly. With reentry enabled, the closing event can also start the next
+  attempt. Without reentry, it still completes and does not create another attempt.
+- Ordinary completed histories consume events through the inclusive two-second
+  completion grace period. Those events do not become a second attempt. The
+  existing `graceperiod: false` option disables that wait.
+- Hold-property-constant session windows use session boundaries from the full
+  stream before property filtering. Unrelated activity can keep a session open.
+- First/last-touch segmentation merges properties across reached steps. A missing
+  property on the preferred step can fall back to another reached step. Explicit
+  step selection remains separate.
+
+`countMode: 'totals'` still defaults to `reentry: false`. Specify `reentry: true`
+when repeated histories are intended. This compatibility default differs from
+Mixpanel general totals. Do not change existing report options implicitly when
+comparing old and new results.
+
+## Lifecycle and identity output is corrected
+
+Retention entry follows adjusted creation, retries precede the final onboarding
+attempt, and usage follows onboarding completion. The engine reconciles its own
+identity fields against surviving auth events after filtering. Engine-created
+data-quality duplicates and world-event clones preserve identity provenance.
+
+Explicit hook identity overrides and the synthetic experiment identity exception
+remain supported. A later valid event carrying both IDs can provide identity
+mapping evidence; this is not restricted to the first funnel.
+
+Short windows retain partial output instead of introducing a required exception.
+Inspect the existing `result.warnings` collection for:
+
+| warning key | meaning |
+| --- | --- |
+| `lifecycle.firstFunnelClipped` | Configured timing cannot fit before dataset end; future steps are omitted without compressing TTC. |
+| `lifecycle.emptyPreAuthAttempt` | Auth is the first step, so a failed pre-auth attempt emits no rows. |
+| `lifecycle.strictAttemptBudget` | The strict event budget cannot retain every surviving attempt entry. |
+
+Configured suppression and hook filtering remain authoritative. The engine does
+not recreate intentionally removed events to satisfy an attempt count.
+
+## Bound session reshaping when the dataset end matters
+
+Calls without bounds retain legacy full-UTC-day placement. They cannot infer the
+dataset end from the last observed event and may still move events beyond it.
+Pass known bounds to prevent that clipping:
+
+```js
+import { applySessionShape } from '@ak--47/dungeon-master/hook-helpers';
+
+const hook = (records, type, meta) => {
+  if (type === 'everything') {
+    applySessionShape(records, meta.profile.distinct_id, {
+      sessionsPerWeek: 3,
+      eventsPerSession: 5,
+      sessionMinutes: 10,
+      datasetStart: meta.datasetStart,
+      datasetEnd: meta.datasetEnd,
+    });
+  }
+  return records;
+};
+```
+
+Bounds accept ISO strings, Unix seconds, or Unix milliseconds. Either explicit
+bound enables constrained placement; an omitted side uses the original UTC day
+edge. Invalid bounds or insufficient per-week session capacity throw `RangeError`
+before records are mutated. Two same-day sessions separated by more than thirty
+minutes cannot fit in a twenty-minute interval. Adjust the requested cadence or
+available window rather than swallowing that error.
+
+The helper retimes the same records. It does not add or drop events. Unbounded
+legacy requests remain nonthrowing, including overfull layouts where derived
+sessions can merge.
+
+## Path injection remains append-only
+
+`applyPathBias` selects the earliest chronological anchor and leaves original
+traffic intact. `share: 1` selects all eligible users for injection. Competing
+events can still interrupt the immediate branch, so it does not promise a 100%
+Flows branch share. Recheck the observed branch, not only the injected count.
+
+## Revalidate the story, not just the schema
+
+Run a pinned, seeded representative dungeon with ordinary standalone traffic and
+competing funnels. Compare counts using explicit report settings. For deterministic
+same-version comparisons, use `concurrency: 1` and strip only `insert_id`.
+
+The new alignment checks establish selected source-derived Mixpanel contracts.
+They do not execute Mixpanel's engine. Timezone/DST variants, list-valued HPC,
+project-specific session exclusions, all parameter combinations, and arbitrary
+hooks are not covered by a universal parity claim.
+
+The recorded sweep produced 17.08 million events across 594 dungeons within ten
+minutes. Its largest single dungeon had 281,751 events. Of 297 cells, 125 met their
+evidence criteria and 172 had insufficient eligible populations. Increasing total
+events is not a substitute for enough eligible users or converters.
+
+## Repository test workflows
+
+These commands require a repository checkout with development dependencies.
+The npm package ships this guide, but does not ship the test suites.
+
+```sh
+node tests/alignment/run.mjs
+node tests/alignment/run.mjs --sweep --timeout-ms=600000
+```
+
+Both commands use macOS OS-level network denial and a hard maximum of ten minutes.
+They fail closed on unsupported platforms. The editor's Testing panel is a separate
+workflow: one serial editor config discovers unit, integration, E2E, and alignment
+tests without global pruning. Direct-run engine scripts have opt-in tasks; their
+full-sweep E2E wrapper is visible but skipped by default. Editor runs do not provide
+an OS network sandbox. Use the named offline test tasks when network denial is
+required, especially for E2E tests that can perform external operations.
+
+`npm test` retains the default unit/integration/E2E suite and excludes alignment.
+Its global setup prunes local `data` and `tmp`; preserve artifacts before using it.
+The explicit `prune` task and default dungeon-run task retain their existing cleanup
+behavior. None of the new offline test tasks depend on them.
+
+## Before publishing
+
+Confirm package version and changelog are 1.8.1. Inspect `npm pack --dry-run --json`
+and rerun the relevant release checks. Publishing to npm is a separate operator
+action; neither test execution nor a Git commit publishes the package.
+
+See the [changelog](../../CHANGELOG.md), [hook reference](../../HOOKS.md), and
+[1.8.0 guide](1.8.0-upgrade-guide.md) for the unchanged standalone and warehouse
+metric APIs.

package/docs/guides/1.8.2-upgrade-guide.md

@@ -0,0 +1,110 @@
+# 1.8.2 upgrade guide
+
+1.8.2 fixes verifier counting and experiment-filter defects found while importing
+synthetic datasets and querying them in Mixpanel. Public exports, signatures,
+options, and defaults remain unchanged. No new runtime dependency is required.
+
+After publication:
+
+```sh
+npm install @ak--47/dungeon-master@1.8.2
+```
+
+This guide describes a release candidate. A branch, PR, or passing test does not
+publish a package.
+
+## identity requires emitted evidence
+
+Automatic verification links a device only when an emitted event contains both
+`device_id` and `user_id`. A profile device pool alone cannot create a link.
+Ordinary event names work; linking is not restricted to an auth-named event.
+
+`buildIdentityMap(profiles)` remains unchanged for explicit caller overrides.
+Pass that map only when it represents trusted identity knowledge. Automatic
+mapping preserves an explicit authenticated user on a conflicting device event.
+Original-merge projects, B2B identity rules, external mapping history, and all
+ingestion validation policies are not fully emulated.
+
+Historical anonymous events may join their user after the import receipt returns.
+The live verification run observed that delay and later verified the same fixture
+without sending it again. Check event totals and identity readiness before accepting
+a funnel comparison. No sender ordering change or fixed sleep claims to solve this.
+
+## report wrappers use the supported counting code
+
+Held-property funnels now support session counting through `funnelFrequency`.
+Matching dungeon defaults no longer inject a millisecond conversion window into
+an implicit one-session report. List-valued held properties expand into per-value
+histories while preserving full-stream session boundaries.
+
+Scalar-only held-property keys retain their existing behavior. Mixed list/scalar
+keys use the source-derived string representation. Explicit list-only mode,
+extreme value formatting, and engine cardinality caps remain outside this API.
+
+Totals still defaults to `reentry: false`. Set `reentry: true` when comparing
+repeated histories with Mixpanel general totals. Session tests use UTC and the
+default thirty-minute inactivity timeout. Project exclusions and non-UTC/DST
+variants require separate proof.
+
+## passing stories need enough independent users
+
+`minCohort` no longer sums overlapping period populations or treats arbitrary rows
+as independent users. It uses a conservative lower bound and applies to custom
+callbacks too. Missing denominator evidence caps an otherwise passing result at
+`WEAK`, with an explanation. Assertions without `minCohort` retain their behavior.
+
+This can expose previously optimistic story verdicts. Inspect the selected users,
+entrants, converters, or mature retention cohorts. Do not lower the threshold just
+to restore a green verdict.
+
+## exposure events retain global filters
+
+Synthetic `$experiment_started` events now include declared `superProps`, including
+context-aware values. Experiment name and variant fields remain authoritative.
+Run-isolated experiment queries therefore retain the exposure and outcome rows.
+This can change seeded output when global property generation consumes randomness.
+Same-version deterministic runs still exclude only fresh `insert_id` values.
+
+Funnel-frequency keep/drop decisions now use stable event fields instead of random
+insertion IDs. Their outcome can change from 1.8.1 but is reproducible on rerun.
+
+## frequency and attribution have distinct contracts
+
+Raw event-count histograms, calendar-day activity, and rolling Frequency/Addiction
+reports are separate measurements. `applyFrequencyByFrequency` scales raw target
+event counts. Its existing `binBy: 'distinctDays'` default only selects the cohort
+axis; it does not make clones add new active days. Use explicit report settings.
+
+`attributedBy` now ignores null or absent touch values, retains touchless conversions
+as `unknown`, and preserves earlier touches across conversion time buckets.
+The public default still selects the first conversion per user; `perConversion:
+'all'` evaluates every conversion. The API has no finite-lookback argument.
+
+`applyAttributedBySource` retains lifetime endpoint selection. Verify that the
+selected endpoint is inside each intended conversion's lookback. Distinct touch
+timestamps are required for reproducible conflicting source order. Same-time
+ties and backend transition compression can differ from raw event-array order.
+
+## verified scope and remaining work
+
+The repository's `tests/alignment/live/REPORT.md` records source revision, run IDs,
+queries, counts, practical effects, neutral controls, and historical failures.
+The local analytics checkout supplied counting contracts; live Mixpanel queries
+tested their behavior on imported data. The C++ engine was not built locally.
+
+Evidence covers selected generated conversion, TTC, retention, volume, weights,
+incidents, raw-count frequency, numeric aggregates, attribution, sessions, and
+Flows. It does not establish every configuration cross-product, literal retention
+probability calibration, arbitrary hook behavior, warehouse deployment, or every
+project setting. Capacity and ambiguous-order limits remain explicit.
+
+Repository gates preserve data and deny network access:
+
+```sh
+node tests/alignment/run.mjs
+node tests/alignment/run.mjs --sweep --timeout-ms=600000
+```
+
+Live scripts are opt-in and require project-specific authorization and credentials.
+They are excluded from the npm package. Do not use the default pruning test setup
+while retained live datasets are still needed.

package/lib/generators/events.js

@@ -17,6 +17,8 @@ import { dataLogger as logger } from "../utils/logger.js";
 // Keys that must never be nulled by data quality gremlins
 const NULL_EXEMPT_KEYS = new Set(['event', 'time', 'insert_id', 'user_id', 'device_id', 'distinct_id', '_drop', '_anomaly', '_persona']);
 
+export const engineIdentity = Symbol('engineIdentity');
+
 
 /**
  * Creates a Mixpanel event with a flat shape
@@ -293,6 +295,9 @@ export async function makeEvent(
 
 	eventTemplate.insert_id = randomUUID();
 
+    const originalIdentity = { user_id: eventTemplate.user_id, device_id: eventTemplate.device_id };
+    Object.defineProperty(eventTemplate, engineIdentity, { value: originalIdentity, configurable: true });
+
     // Call hook if configured (hooks override everything — they are the final authority)
     const { hook } = config;
     if (hook) {
@@ -305,6 +310,7 @@ export async function makeEvent(
         });
         // If hook returns a modified event, use it; otherwise use original
         if (hookedEvent && typeof hookedEvent === 'object') {
+            Object.defineProperty(hookedEvent, engineIdentity, { value: originalIdentity, configurable: true });
             return hookedEvent;
         }
     }