@ak--47/dungeon-master 1.6.2 → 1.6.3

package/.claude/skills/create-project/provision.mjs

@@ -315,9 +315,22 @@ function printSummary() {
 		// Defensive: the API's `added`/`skipped` entries may be objects, strings, or
 		// null. Never let summary formatting throw — it would swallow real warnings.
 		const fmt = (g) => (g == null ? null : typeof g === 'string' ? g : (g.property_name || g.name || null));
-		const added = (groupKeyResult?.added || []).map(fmt).filter(Boolean).join(', ') || '(none)';
-		const skipped = (groupKeyResult?.skipped || []).map(fmt).filter(Boolean).join(', ') || '(none)';
-		console.log(`group keys:     added [${added}]  skipped [${skipped}]`);
+		const added = (groupKeyResult?.added || []).map(fmt).filter(Boolean);
+		const skipped = (groupKeyResult?.skipped || []).map(fmt).filter(Boolean);
+		// `added`/`skipped` are not always populated (a create that lands via a
+		// different code path can return both empty), which made a perfectly good
+		// provision print "added [(none)] skipped [(none)]" and read as a failure.
+		// `all_group_keys` is the authoritative post-state, so report against that
+		// and only fall back to the deltas when it's absent.
+		const all = (groupKeyResult?.all_group_keys || []).map(fmt).filter(Boolean);
+		if (all.length) {
+			const present = groupKeys.map((g) => g.property_name).filter((p) => all.includes(p));
+			const missing = groupKeys.map((g) => g.property_name).filter((p) => !all.includes(p));
+			console.log(`group keys:     in project [${present.join(', ') || '(none)'}]${missing.length ? `  MISSING [${missing.join(', ')}]` : ''}`);
+			if (missing.length) warnings.push(`group keys missing after addGroupKey: ${missing.join(', ')}`);
+		} else {
+			console.log(`group keys:     added [${added.join(', ') || '(none)'}]  skipped [${skipped.join(', ') || '(none)'}]`);
+		}
 	}
 	console.log(`business ctx:   ${content.length} chars uploaded (source: ${ctxSource})`);
 	console.log(`credentials:    ${wroteBack ? 'written back into dungeon ✓' : 'NOT written (see warnings)'}`);

package/.claude/skills/headless-build/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: headless-build
+description: Use after a dungeon's data is loaded into a real Mixpanel project — builds the full demoable environment with mixpanel-headless (dashboards, charts, Lexicon, cohorts, custom properties, behaviors/metrics/formulas, annotations) targeted at that dungeon's engineered stories, then verifies the stories still read live. Final step after create-dungeon / write-hooks / verify-dungeon / create-project.
+argument-hint: [dungeon path, e.g. dungeons/user/nyc-dcp/nyc-dcp.js]
+model: claude-opus-4-6
+effort: max
+---
+
+# Headless Build — turn a loaded project into a demo
+
+Last step of the pipeline:
+
+```
+/create-dungeon → /write-hooks → /verify-dungeon → /create-project → /headless-build
+```
+
+The project already has data. This skill builds everything a human sees: themed
+dashboards whose narrative is computed from the live data, an annotated Lexicon,
+saved cohorts and custom properties, saved behaviors/metrics/formulas, and
+annotations that explain the engineered moments. Then it re-measures the hook
+stories **against the live project** and fails if they no longer read.
+
+That last step is the point. Local story verification passes on the generated
+array in memory; it never sees what survived ingest. A build can render five
+perfect dashboards on top of a story that silently collapsed on the way in.
+
+## Scope
+
+In scope: dashboards + charts, Lexicon enrichment, cohorts, custom properties,
+behaviors/metrics/formulas, annotations, and live story verification.
+
+Out of scope: changing the dungeon, regenerating or re-sending data. If the data
+is wrong, fix the dungeon and re-run `/create-project` — do not paper over it
+with dashboard copy.
+
+## Prerequisites
+
+- The dungeon's `creds.json` / `credentials` block exists (`/create-project` ran).
+- Data is actually loaded — `00_auth_check.py` fails loudly if not.
+- `uv` available. `mixpanel_headless` is on PyPI, so it needs no local checkout:
+  `uv run --with mixpanel_headless python <script>`.
+
+## Step 0 — ask who creates the entities
+
+**Ask the user before building.** The answer changes who owns every asset:
+
+| Mode | Effect |
+|---|---|
+| **bearer** (recommended) | Entities are created by a real user via OAuth token (`BEARER_TOKEN` in the repo `.env`). They appear in that person's Mixpanel UI with owner access. |
+| **service** | Entities are created by the dungeon's service account. A human then sees **"Your access: None"**, and custom properties have no share endpoint — so it cannot be fixed from the UI at all. Only correct when no OAuth token exists. |
+
+Default to **bearer** whenever a token is available. To use it with
+`mixpanel_headless`, set `MP_OAUTH_TOKEN` and **unset `MP_USERNAME` / `MP_SECRET`** —
+the SDK prefers the service account whenever the full SA env set is present.
+Power-tools calls must use the same principal (`Authorization: Bearer …`), or
+entities created through that path land back under the service account.
+
+## Reference implementation
+
+`dungeons/user/nyc-dcp/build/` is the worked example — read it before writing a
+new one. (It is gitignored with the rest of `dungeons/user/`, so it lives only in
+the working copy.) Peloton's equivalent is
+`/Users/ak/code/mixpanel-headless/ak/customer_peloton/`.
+
+## Layout
+
+Create the build inside the dungeon's own folder:
+
+```
+dungeons/user/<name>/build/
+├── .env                    # MP_USERNAME / MP_SECRET / MP_PROJECT_ID / MP_REGION
+├── _common.py              # window detection, ws factory + retry, helpers, knobs, cohorts
+├── build_all.py            # one-shot orchestrator, --only / --internal / --from-date
+├── scripts/
+│   ├── 00_auth_check.py         # also prints WHO is authenticated
+│   ├── 01_reset_entities.py     # opt-in: delete this build's own entities
+│   ├── 02_custom_props.py
+│   ├── 03_cohorts.py
+│   ├── 04_lexicon.py
+│   ├── 05_dash_start_here.py    # built LAST — links the other boards by id
+│   ├── 06..09_dash_<story>.py   # one board per engineered story
+│   ├── 10_annotations.py
+│   ├── 11_behaviors_metrics.py  # via power-tools; headless lacks these
+│   └── 99_verify.py
+└── results/                # entities.json registry, window.json, verification_*.json
+```
+
+## Steps
+
+### 1. Read the dungeon
+
+Pull out, from the dungeon file itself: the `stories` export, the HOOK STORIES
+doc block, the knob constants, the event/property schema, and the VALUE MOMENT.
+**Mirror the knob constants into `_common.py`** so dashboard copy quotes the
+designed value while the charts show the measured one. Never let narrative text
+hardcode a number no longer tied to a knob.
+
+### 2. Probe the project before designing
+
+Capabilities differ per project. Run a throwaway probe and design around what
+actually works. Verified on both NYC DCP and Peloton:
+
+- Insights `group_by` / `where` / saved-cohort filters: **work**.
+- Funnels `group_by`: **silently does not segment** — returns rows identical to
+  ungrouped. Use one funnel per segment with a `where` filter instead.
+- Day-granularity queries reject ranges **over 366 days**.
+- Valid `displayOptions.chartType`: `bar`, `column`, `frequency-curve`,
+  `funnel-steps`, `funnel-top-paths`, `insights-metric`, `line`, `pie`,
+  `retention-curve`, `table`. There is no `stacked-area` — the API rejects it.
+
+### 3. Auto-detect the data window
+
+Never hardcode dates. A regenerated dungeon lands on new ones and every chart
+silently clips. Probe wide at `unit="month"`, then resolve exact days inside the
+non-empty months (day charts cap at 366 days). Cache to `results/window.json`.
+
+### 4. Build entities, then boards
+
+Order matters: custom properties and cohorts first (boards break down by them),
+Lexicon, behaviors/metrics/formulas, annotations, then dashboards, with the
+"Start Here" board last so it can link the others by id.
+
+Keep a `results/entities.json` registry of every created id — the Start Here
+board and the verifier both read it.
+
+### 5. Write boards that argue, not just render
+
+The difference between a dashboard and a demo:
+
+- **Query first, then narrate.** Compute the numbers live, then interpolate them
+  into text cards. Never write a number by hand.
+- **One board per story**, plus a Start Here tour board.
+- **Normalize rates.** Raw totals carry population and activity; the claim is
+  almost always about intensity. Say which denominator you used and why.
+- **Name the confound.** If a chart could be read two ways, put the alternative
+  in the text card and say what rules it out.
+- **End each board with a "So what"** — the decision the board supports.
+- Text card HTML must be single-line (`" ".join(html.split())`) — TipTap mangles
+  newlines.
+
+**Board titles carry no app prefix.** The project is already the app; a
+`"<App> — "` prefix on every board is noise that eats the readable part of the
+name in the sidebar. Title them `Borough Equity & Access`, not
+`NYC DCP — Borough Equity & Access`.
+
+**Always label the legend.** By default a series reads
+`Data Export [Total Events]` — it names the event and the math, not the thing
+being measured. Mixpanel exposes this as **Rename** on a query block; on the
+wire it is `params.sections.show[i].name` plus `userNamed: true` (the flag is
+what stops the UI regenerating the label). Every insights report should pass a
+plain-English label: `Users`, `Exports`, `Comments Filed`.
+
+**Merge KPI cards into ONE multi-metric report.** Four big-number cards do not
+need four saved reports. Each report is another entity to create and another
+query to run, and the rate limit is the binding constraint on a full build.
+Concatenate the `sections.show` arrays of several single-metric queries into one
+params dict and keep `chart_type="insights-metric"` — Mixpanel still renders big
+numbers, one per metric. Only safe when the inputs share a time range and
+report-level filter, since `sections.filter` applies to the whole report; per-metric
+filters have to move into `show[i].behavior.filters`.
+
+**Share everything, and warm the cohorts.** Two separate failure modes:
+
+- *Unshared* — an entity is visible only to its creator. Call
+  `/crud/shareDash` (`view_only: false`) and `/crud/shareCohort`
+  (`can_edit: true`) for everything you create. There is no share endpoint for
+  custom properties, behaviors, or metrics — which is exactly why bearer auth
+  matters: get the owner right at creation, because you cannot fix it after.
+- *Unwarmed* — cohort membership computes **lazily**. A freshly created cohort
+  reports `count: 0` until something queries it, and a cohort showing 0 members
+  reads as broken in a demo. Run one cheap query per cohort after creating it.
+  Verify counts, not just existence.
+
+### 6. Verify against the live project
+
+`99_verify.py` does two checks:
+
+- **structure** — every registered entity still exists.
+- **stories** — re-measure each hook effect live and compare to the knob.
+
+Report MATCH / DIRECTIONAL / MISS per story and exit non-zero on any MISS.
+Use a wider tolerance than the dungeon's own ±10% bar (~25%): Mixpanel's cohort
+membership is computed over the whole window, not the dungeon's internal binning,
+so depth-band style cohorts will not line up exactly.
+
+### 7. Report
+
+Give the user the board URLs
+(`https://mixpanel.com/project/<pid>/view/<wsid>/app/boards/<id>`), the entity
+counts, and the story verdict table.
+
+## Gotchas that cost real time
+
+**Saved cohort ids, never inline definitions.** `Filter.in_cohort(CohortDefinition(...))`
+is accepted and applied, but every definition collapses to the same membership —
+three different cohorts return byte-identical numbers instead of erroring. Create
+cohorts first, then filter by id: `Filter.in_cohort(<saved_id>, "<name>")`.
+
+**`create_cohort` via headless 500s** on some projects; `CreateCohortParams.definition`
+also wants `.to_dict()`, not the builder object. Use `/crud/createCohort` — see the
+`powertools` skill for the payload shape and its limits (behavioral counts yes;
+profile-property and behavior-nested property filters no).
+
+**Rate limits will kill a full build midway.** A build fires several hundred
+queries; the cap trips after the first couple of boards and the rest fail,
+leaving a half-built project that still looks fine until you count the boards.
+The client must therefore:
+
+- **Issue one request at a time**, with a small fixed gap. Parallelism does not
+  help and actively hurts — the cap is request-rate based, so concurrency only
+  reaches the limit sooner and then every worker sits in backoff together.
+- **Back off hard and genuinely exponentially** on 429: start ~30s, double, cap
+  ~15 minutes, ~7 attempts. The cap is per-hour, so short retries just burn
+  attempts without letting the window refill. Retry transient 502s the same way.
+- **Be resumable.** Keep the entity registry on disk and reuse by name, so a
+  killed build picks up where it stopped instead of duplicating.
+
+On Mixpanel-internal projects `--internal` additionally sends the rate-limit
+bypass headers. It is a no-op elsewhere and does *not* remove the need for
+backoff — it supplements it.
+
+**Fewer entities is a rate-limit strategy, not just tidiness.** Merging four KPI
+cards into one multi-metric report removes three creates and three queries from
+every build. Prefer one report with N metrics wherever the chart allows it.
+
+**`ws._api_client` is lazy** — None immediately after construction. Force it via
+`ws._get_api_client()` before patching request headers.
+
+**Idempotency.** Dashboards: delete-by-title then recreate. Everything else:
+look up by name and reuse. Re-running must never duplicate.
+
+## Commands
+
+```bash
+cd dungeons/user/<name>/build
+set -a && . ./.env && set +a
+
+uv run --with mixpanel_headless python build_all.py --auth bearer        # recommended
+uv run --with mixpanel_headless python build_all.py --auth service       # SA-owned assets
+uv run --with mixpanel_headless python build_all.py --internal           # + rate-limit bypass
+uv run --with mixpanel_headless python build_all.py --only reset --apply # wipe this build's entities
+uv run --with mixpanel_headless python build_all.py --only dashboards verify
+uv run --with mixpanel_headless python build_all.py --skip-lexicon
+uv run --with mixpanel_headless python build_all.py --from-date 2026-04-18 --to-date 2026-08-17
+uv run --with mixpanel_headless python scripts/99_verify.py              # verify only
+```
+
+Phases: `auth`, `reset` (opt-in only), `customprops`, `cohorts`, `lexicon`,
+`entities`, `annotations`, `dashboards`, `verify`.
+
+`reset` is never part of the default order — it deletes entities, and only ever
+the ones this build created, matched by name. Use it when assets were created
+under the wrong principal and must be recreated (there is no way to re-own an
+existing custom property).

package/.claude/skills/powertools/SKILL.md

@@ -45,7 +45,27 @@ node .claude/skills/powertools/snapshot-project.mjs <project_id> --bearer <token
 
 GET the path for full docs. Full list: GET `/` and GET `/macro`.
 
-**crud** — `/crud/createProject`, `/crud/deleteProject`, `/crud/getProjects`, `/crud/mintServiceAccount`, `/crud/addGroupKey`, `/crud/setBusinessContext` (all used by the create-project skill's `provision.mjs`).
+**crud** — 187 endpoints. GET `/crud` for the full list.
+
+*Project lifecycle* (used by create-project's `provision.mjs`): `/crud/createProject`, `/crud/deleteProject` (**irreversible** — deletes the project and all its data; needs `org_id`), `/crud/getProjects`, `/crud/mintServiceAccount`, `/crud/deleteServiceAccount`, `/crud/addGroupKey`, `/crud/deleteGroupKey`, `/crud/setBusinessContext`.
+
+*Analysis entities* (used by the `headless-build` skill for what `mixpanel_headless` does not expose): `/crud/createCohort` + `getCohorts`/`getCohort`/`updateCohort`/`deleteCohort`, `/crud/createBehavior` + `getBehaviors`/`deleteBehavior`, `/crud/createMetric` + `getMetrics`/`deleteMetric`, `/crud/createFormula` + `getFormulas`/`deleteFormula`, `/crud/createDash`/`updateDash`/`pinDash`/`duplicateDash`, `/crud/makeInsightsReport`/`makeFunnelsReport`/`makeFlowsReport`/`makeRetentionReport`, `/crud/createCustomProp`, `/crud/createCustomEvent`, `/crud/createAnnotation`, `/crud/createLookupTable`.
+
+### Entity-CRUD response shapes (verified 2026-08-17 — these bite)
+
+Three different shapes across one API family. Assuming a flat list or a flat `results.id` silently yields `None`/empty rather than erroring:
+
+- **create** returns `{"status":"ok","results":{"<id>":{...}}}` — `results` is keyed BY id, so `results["id"]` is None. Take `next(iter(results.values()))["id"]`.
+- **list** (`getBehaviors`/`getMetrics`/`getFormulas`) returns numerically-keyed entries at the **top level** — `{"0":{...},"1":{...},"duration_ms":…}` — with nothing under `results`. Iterate `raw.values()` and keep dicts that carry a `name`+`id`.
+- `getMetrics` and `getFormulas` return the **same combined set** (metrics and formulas share one store), so dedupe by name if you call both.
+
+### Cohort payload limits (verified on project 4054934)
+
+`/crud/createCohort` accepts the native UI shape: `groups[]` of `cohort_group` (each `{type, event:{resourceType:"cohort",value:"$all_users"}, filters[]}`) plus `determiner: "all"|"any"`. What works and what does not:
+
+- ✅ behavioral counts — `customProperty.behavior` + `filterOperator: "is at least"|"is at most"`; multiple filters in one group give a RANGE; multiple groups give AND (`all`) / OR (`any`).
+- ❌ profile-property filters, and property filters nested inside a `behavior` — both fail with `Failed to resolve cohort references`. Express those as report `where` filters instead.
+- New cohorts report `count: 0` at creation; membership computes asynchronously.
 
 **query** — `/query/getTopEvents` (per-event counts, limit≤100 default), `/query/getEventNames`, `/query/getPropertyValues`, `/query/getTopProperties`, `/query/getSegmentation`, `/query/getFunnel`, `/query/listFunnels`, `/query/listCohorts`, `/query/runJQL`. Rate limits: 5 concurrent / 60 per hour; 1h response cache.
 

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 All notable changes to `@ak--47/dungeon-master`.
 
+## 1.6.3 — 2026-08-17
+
+### Fixed
+
+- **Cloned events no longer get deduplicated away by Mixpanel on ingest.** All
+  eight clone-producing helpers now give each clone a fresh `insert_id`:
+  `cloneEvent`, `scaleEventCount`, `injectAfterEvent`, `injectBetween`,
+  `injectBurst`, `injectOnNewDays`, `applyLifecycleWave`, and `applyPathBias`.
+  Four of them (`cloneEvent` and the three `injectAfterEvent`/`injectBetween`/
+  `injectBurst`) copied the template's id verbatim, so clones arrived as
+  byte-identical twins and Mixpanel deduped them server-side. The others deleted
+  the id, which is no safer: `mixpanel-import` runs with `fixData: true` and
+  synthesizes a missing id by content-hashing the record, so identical clones
+  collide into one anyway. Measured on an 8K-user dungeon: 608,081 events
+  generated, 598,555 landed. The loss fell entirely on the two events the hooks
+  clone, and an engineered 4x comment surge read as **1.17x** in the project while
+  local story verification still reported 4.14x — verification never inspects
+  `insert_id`. After the fix, all 608,081 ids are distinct and in-project counts
+  match sent counts exactly. Affects any dungeon whose hooks clone or inject
+  events. New shared helpers `stampFreshInsertId` / `cloneWithFreshId` in
+  `lib/hook-helpers/_internal.js`; every clone site honors an explicit
+  `insert_id` override uniformly. Swept by `tests/unit/clone-insert-id.test.js`,
+  which covers every clone site rather than the one that happened to break.
+- **The engine now guarantees unique `insert_id` across each user's final event
+  stream.** Fixing the clone helpers was not sufficient: hooks are documented to
+  inject events by spreading an existing one, and a spread copies `insert_id`
+  too — so any hand-rolled clone reintroduced the bug. Several shipped dungeons
+  (including `dungeons/technical/simple.js` and most of `dungeons/vertical/`) do
+  exactly that, and measured 160 duplicate ids in a 3,254-event sample. The user
+  loop now re-stamps any duplicate or missing `insert_id` after the `everything`
+  hook, alongside the existing auto-sort and future-time guards. A legitimate
+  stream never carries two events with the same id, so any collision at that
+  point is a clone. Pinned by `tests/integration/insert-id-uniqueness.test.js`.
+  CLAUDE.md's hook rule now points at `cloneEvent` while documenting that a bare
+  spread remains safe.
+- **`mixpanel-import` 3.5.1 → 3.6.1**, which fixes an undercount in the reported
+  user-profile success total (3.5.1 reported 196 profiles sent for a batch of
+  6,049 that had in fact all landed).
+- **`create-project` no longer reports a successful group-key add as a failure.**
+  The summary read `added [(none)] skipped [(none)]` even when the key was created
+  and ready, because the response's `added`/`skipped` arrays are not always
+  populated. It now reports against `all_group_keys`, the authoritative post-state,
+  and warns when a declared key is genuinely absent.
+
+### Added
+
+- **`/headless-build` skill** — final step of the pipeline (after `/create-project`).
+  Builds a demoable Mixpanel environment with `mixpanel_headless`: dashboards whose
+  narrative text is computed live from the project, Lexicon enrichment, saved
+  cohorts, custom properties, behaviors/metrics/formulas, and annotations — then
+  re-measures every hook story against the live project and fails on a miss.
+- **`powertools` skill: entity-CRUD index.** Documents the three inconsistent
+  response shapes across the create/list endpoints, the `createCohort` payload
+  contract, and which cohort filter types the API accepts.
+
 ## 1.6.2 — 2026-07-30
 
 ### Fixed

package/lib/hook-helpers/_internal.js

@@ -1,3 +1,48 @@
+import { randomUUID } from 'node:crypto';
+
+/**
+ * Give a cloned event its own `insert_id`.
+ *
+ * Clones MUST NOT inherit their template's id, and stripping the id is not
+ * enough either: mixpanel-import runs with `fixData: true`, which synthesizes a
+ * missing id by content-hashing the record — so two clones that differ only in
+ * ways the hash ignores collapse into one on ingest. Mixpanel then dedupes them
+ * server-side and the engineered volume silently disappears from the project
+ * while local verification (which never looks at `insert_id`) still passes.
+ *
+ * `insert_id` is already assigned via `randomUUID()` in the event generator
+ * (`lib/generators/events.js`), so it sits outside the seeded
+ * byte-identical-output guarantee; using it here keeps clone ids consistent with
+ * engine-generated ones.
+ *
+ * @template {{insert_id?: string}} T
+ * @param {T} clone
+ * @returns {T} the same object, with a fresh `insert_id`
+ */
+export function stampFreshInsertId(clone) {
+	clone.insert_id = randomUUID();
+	return clone;
+}
+
+/**
+ * Spread a template into a new event, merge `overrides`, and give it a fresh
+ * `insert_id` — unless the caller pinned one explicitly.
+ *
+ * Every clone site should go through this so the override contract is uniform:
+ * a caller that passes `insert_id` in `overrides` keeps it, and everyone else
+ * gets a unique id rather than a duplicate of the template's.
+ *
+ * @template {Record<string, any>} T
+ * @param {T} template - Event to clone from.
+ * @param {Record<string, any>} [overrides] - Fields to merge on top.
+ * @returns {T} the new event
+ */
+export function cloneWithFreshId(template, overrides = {}) {
+	const clone = /** @type {T} */ ({ ...template, ...overrides });
+	if (!(overrides && 'insert_id' in overrides)) stampFreshInsertId(clone);
+	return clone;
+}
+
 export function toMs(t) {
 	if (typeof t === 'number') return t > 1e12 ? t : t > 1e9 ? t * 1000 : t;
 	return Date.parse(t);

package/lib/hook-helpers/inject.js

@@ -10,7 +10,7 @@
  */
 
 import { getChance } from '../utils/utils.js';
-import { toMs, writeTime } from './_internal.js';
+import { toMs, writeTime, stampFreshInsertId, cloneWithFreshId } from './_internal.js';
 
 /**
  * Splice a cloned event into `events` immediately after `sourceEvent`. Time is
@@ -29,7 +29,7 @@ export function injectAfterEvent(events, sourceEvent, templateEvent, gapMs, over
 	if (!events || !sourceEvent || !templateEvent) return null;
 	const baseT = toMs(sourceEvent.time);
 	if (!Number.isFinite(baseT)) return null;
-	const newEv = { ...templateEvent, ...overrides };
+	const newEv = cloneWithFreshId(templateEvent, overrides);
 	writeTime(newEv, baseT + gapMs);
 	const idx = events.indexOf(sourceEvent);
 	if (idx >= 0) events.splice(idx + 1, 0, newEv);
@@ -60,7 +60,7 @@ export function injectBetween(events, eventA, eventB, templateEvent, overrides =
 	const aT = toMs(a.time);
 	const bT = toMs(b.time);
 	if (!Number.isFinite(aT) || !Number.isFinite(bT)) return null;
-	const newEv = { ...templateEvent, ...overrides };
+	const newEv = cloneWithFreshId(templateEvent, overrides);
 	writeTime(newEv, (aT + bT) / 2);
 	const bIdxOrig = events.indexOf(b);
 	if (bIdxOrig >= 0) events.splice(bIdxOrig, 0, newEv);
@@ -89,7 +89,7 @@ export function injectBurst(events, templateEvent, count, anchorTime, spreadMs,
 	const created = [];
 	for (let i = 0; i < count; i++) {
 		const offset = chance.floating({ min: -spreadMs, max: spreadMs });
-		const newEv = { ...templateEvent, ...overrides };
+		const newEv = cloneWithFreshId(templateEvent, overrides);
 		writeTime(newEv, anchorMs + offset);
 		events.push(newEv);
 		created.push(newEv);
@@ -119,7 +119,8 @@ const DAY_MS = 86400000;
  *   5. Find a template event of `eventName`; if none exist for this user,
  *      return unchanged (we honor schema-first: don't fabricate events).
  *   6. Clone the template onto each picked day at a random hour within the
- *      day. `insert_id` is stripped (Mixpanel re-deduplicates on import).
+ *      day. Each clone gets a FRESH `insert_id` (inheriting or omitting it lets
+ *      Mixpanel dedupe the clones away on ingest).
  *   7. Append clones to the array. Caller's downstream sort handles ordering.
  *
  * @param {Object[]} events - Full user event array (from `everything` hook).
@@ -183,9 +184,8 @@ export function injectOnNewDays(events, eventName, targetDays, options = {}) {
 		const lo = Math.max(dayStart, minMs);
 		const hi = Math.min(dayEnd, maxMs);
 		const newMs = lo >= hi ? lo : chance.integer({ min: lo, max: hi });
-		const clone = { ...template, ...overrides };
+		const clone = cloneWithFreshId(template, overrides);
 		writeTime(clone, newMs);
-		delete clone.insert_id;
 		events.push(clone);
 	}
 

package/lib/hook-helpers/mutate.js

@@ -8,7 +8,7 @@
  * `Math.random()` — so dungeon runs stay reproducible.
  */
 
-import { toMs } from './_internal.js';
+import { toMs, stampFreshInsertId, cloneWithFreshId } from './_internal.js';
 
 import { getChance } from '../utils/utils.js';
 
@@ -25,7 +25,9 @@ import { getChance } from '../utils/utils.js';
  */
 export function cloneEvent(template, overrides = {}) {
 	if (!template) throw new Error('cloneEvent: template is required');
-	return /** @type {T} */ ({ ...template, ...overrides });
+	// A clone that keeps its template's insert_id is deduped away by Mixpanel on
+	// ingest. Callers may still pin one explicitly via overrides.
+	return /** @type {T} */ (cloneWithFreshId(template, overrides));
 }
 
 /**
@@ -57,8 +59,9 @@ export function dropEventsWhere(events, predicate) {
  *   integer = -dropped.
  * - factor === 1 or no matches: no-op, returns 0.
  *
- * Note: the `insert_id` of cloned events is removed so a downstream pass can
- * regenerate it (otherwise Mixpanel will dedupe on import).
+ * Note: cloned events get a FRESH `insert_id` — they must not inherit the
+ * source's, and leaving it blank is not safe either (the importer content-hashes
+ * missing ids, so identical clones collide and Mixpanel dedupes them away).
  *
  * @param {Array<{event:string,time:string|number,insert_id?:string}>} events
  * @param {string} eventName
@@ -78,8 +81,7 @@ export function scaleEventCount(events, eventName, factor) {
 			const newTime = Number.isFinite(baseMs)
 				? new Date(baseMs + (i + 1) * 1000).toISOString()
 				: src.time;
-			const clone = { ...src, time: newTime };
-			delete clone.insert_id;
+			const clone = stampFreshInsertId({ ...src, time: newTime });
 			events.push(clone);
 			added++;
 		}

package/lib/hook-helpers/shape.js

@@ -6,13 +6,13 @@
  * (HOOKS.md §2.16), a biased Flows path branch (§2.17), and a deterministic
  * session cadence (§2.13). All three are `everything`-hook-only — they need
  * the whole stream — and obey the schema-first rules: clones only (spread
- * from the user's own events, `insert_id` stripped), no fabricated events,
+ * from the user's own events, each given a fresh `insert_id`), no fabricated events,
  * seeded `chance` for all randomness. Timestamp rewrites are safe because
  * the engine re-derives `session_id` on the final event set (v1.6 P2.1).
  */
 
 import { getChance } from '../utils/utils.js';
-import { toMs, writeTime } from './_internal.js';
+import { toMs, writeTime, stampFreshInsertId } from './_internal.js';
 import { hashFloat } from './cohort.js';
 
 const DAY_MS = 86400000;
@@ -100,7 +100,7 @@ export function applyLifecycleWave(events, uid, opts) {
 	for (let i = 0; i < resurrectBurst; i++) {
 		const clone = { ...template };
 		writeTime(clone, t);
-		delete clone.insert_id;
+		stampFreshInsertId(clone);
 		if (!clone.user_id && uid) clone.user_id = uid;
 		kept.push(clone);
 		t += chance.integer({ min: MIN_MS, max: 10 * MIN_MS });
@@ -168,7 +168,7 @@ export function applyPathBias(events, uid, opts) {
 		t += chance.integer({ min: lo, max: hi }) * 1000;
 		const clone = { ...tpl };
 		writeTime(clone, t);
-		delete clone.insert_id;
+		stampFreshInsertId(clone);
 		if (!clone.user_id && uid) clone.user_id = uid;
 		events.push(clone);
 	}

package/lib/hook-patterns/frequency-by-frequency.js

@@ -16,8 +16,8 @@
  * - Operates on the user's full event stream — call from the `everything` hook.
  * - Does NOT add new properties; uses existing event names defined in the dungeon
  *   schema.
- * - Cloned events have their `insert_id` stripped (mutate.scaleEventCount handles
- *   that), so the engine's batch writer can re-stamp them downstream.
+ * - Cloned events get a fresh `insert_id` (mutate.scaleEventCount handles that),
+ *   so Mixpanel does not dedupe them away on ingest.
  */
 
 import { binUsersByEventCount } from '../hook-helpers/cohort.js';

package/lib/orchestrators/user-loop.js

@@ -750,6 +750,33 @@ export async function userLoop(context) {
 				});
 			}
 
+			// v1.6.3: guarantee unique `insert_id` across the user's final stream.
+			//
+			// Hooks clone events by spreading an existing one — the documented way
+			// to inject — and a spread copies `insert_id` along with everything
+			// else. Mixpanel deduplicates on `insert_id` at ingest, so those clones
+			// are accepted, reported as successful, and then silently dropped: the
+			// engineered volume never appears in the project. Nothing downstream
+			// catches it, because local verification never inspects `insert_id`.
+			//
+			// The hook-helper clone atoms stamp fresh ids themselves, but hooks are
+			// free to hand-roll a spread (and many shipped dungeons do), so the
+			// only reliable place to enforce this is here, over the finished set.
+			// A legitimate stream never contains two events with the same id, so
+			// any collision at this point is a clone that needs its own id.
+			// `> 0`, not `> 1`: a lone event cannot collide, but it can still be
+			// missing an id if a hook replaced it with a constructed object.
+			if (usersEvents.length > 0) {
+				const seenInsertIds = new Set();
+				for (const ev of usersEvents) {
+					if (!ev) continue;
+					if (!ev.insert_id || seenInsertIds.has(ev.insert_id)) {
+						ev.insert_id = randomUUID();
+					}
+					seenInsertIds.add(ev.insert_id);
+				}
+			}
+
 			// Defensive guard: drop any events whose timestamp landed past the
 			// configured dataset end. Hooks that duplicate events with time offsets
 			// (weekend surges, viral spreads) can leak a few past the boundary.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ak--47/dungeon-master",
-	"version": "1.6.2",
+	"version": "1.6.3",
 	"description": "generate fancy datasets",
 	"type": "module",
 	"main": "index.js",
@@ -87,7 +87,7 @@
 		"dotenv": "^16.4.5",
 		"hyparquet-writer": "^0.6.1",
 		"mixpanel": "^0.18.0",
-		"mixpanel-import": "^3.5.1",
+		"mixpanel-import": "^3.6.1",
 		"p-limit": "^3.1.0",
 		"pino": "^9.0.0",
 		"pino-pretty": "^11.0.0",