@wireai/activation 0.14.3 → 0.16.0

package/CHANGELOG.md

@@ -3,6 +3,786 @@
 All notable changes to `@wireai/activation` (formerly `wireai-onboarding`).
 Historical entries below the rename keep the old package name on purpose.
 
+## [0.16.0] - 2026-08-20
+
+> **MINOR, and here is the precedent it rests on:** an OPTIONAL member added to a public type is what
+> made 0.14.0 and 0.15.0 minors, and this release adds `WireDoctorJoinTarget` to the
+> `@wireai/activation/analytics` barrel plus `WireDoctorOptions.join`. Everything under 0.15.1 below
+> ships inside this release.
+>
+> The heading is worded as a blocker, not as `[Unreleased]`, on purpose: this file has twice carried
+> an `[Unreleased]` title long after the work shipped (see the 2026-08-09 corrections below). A
+> heading that names what it is waiting for cannot go quietly stale.
+
+### Added
+
+- **`wireDoctor` gained a fifth check, `join_key`** — the one failure the other four are structurally
+  blind to. `target`, `reachability`, `storage` and `round_trip` all answer *does an event leave and
+  get accepted?*. None of them answers *can it be joined?*. `user_context.device_key` is the only
+  thing that stitches an onboarding session to everything the app reports later, so an integration
+  without one writes every event, passes all four checks, and still reports a permanent **zero** in
+  the `activated` funnel. Two real consumers shipped exactly that, and the 0.15.1 notes recorded the
+  gap as future work.
+
+  The check mirrors `WireOnboarding`'s own auto-join conditions, in its order: a host-supplied
+  `device_key` wins outright; `autoJoinKey: false` with no host key is an unlinked funnel; no
+  `storage` means the kit declines to inject (an unpersisted key differs every launch, which
+  corrupts session counting rather than just leaving it empty); a failed `storage` check means the
+  same; otherwise it reads the persisted auto key, and a first run with proven-writable storage
+  passes because the kit will mint and persist on first mount.
+
+- **`WireDoctorJoinTarget`**, exported from `@wireai/activation/analytics`, and
+  `WireDoctorOptions.join`. Pass the same `appId` / `userContext` / `autoJoinKey` you pass
+  `<WireOnboarding>` — anything reconstructed would diagnose a different integration than the one
+  that ships.
+
+- **`isUsableIdentityValue`**, a pure predicate extracted from `resolveIdentity`, which is now its
+  only other caller. ⚠️ **Module-level only — deliberately NOT added to any barrel**, so it is not
+  part of the published surface even though its sibling `resolveIdentity` is: nothing outside the
+  kit needs it yet, and this repo does not grow public API speculatively. See **Guarded** for why
+  the doctor could not simply call `resolveIdentity`.
+
+### Changed — read this before upgrading
+
+- **Omitting `join` FAILS the report** rather than skipping the check. An existing caller that passes
+  only `{ target, storage }` will see `report.ok` go from `true` to `false`, with a `join_key` check
+  whose detail begins `NOT EVALUATED` and names exactly what to pass.
+
+  This is deliberate, and it is the module's own established doctrine rather than a new invention:
+  `dev_only` already returns `ok: false` for the same reason, because — in that check's own words —
+  *"a green report that never ran is the exact failure mode this whole feature exists to remove."* A
+  report that never looked at the join has not earned a green either. `wireDoctor` is dev-only and
+  gated on `__DEV__`, so no release build and no end user is affected.
+
+### Guarded
+
+- **The check is strictly READ-ONLY: one `getItem`, plus pure predicates.** It would have been
+  shorter to call `hydrateDeviceIdentity` and read `.durable` off the result, and that would have
+  been a bug: it MINTS, registers on the process-wide registry, and persists. Two things forbid it —
+  this module's own contract (*"mints no `globalThis` slot"*, *"never a side effect on the host"*),
+  and the 0.15.1 defect where a propless READER wrote into the census it read, so the host's real
+  `appId` registering afterwards made the census read two and the reader answered `undefined` for
+  the rest of the process. A diagnostic that causes the defect class it diagnoses is worse than no
+  diagnostic. Same reasoning for the host-key branch calling `isUsableIdentityValue` and not
+  `resolveIdentity`: the latter WRITES the provenance registry for a `host`-sourced value.
+
+  This is held by a test, not by this paragraph: *"join_key: READ-ONLY — it mints nothing and writes
+  no identity registry"* asserts both `Symbol.for` slots are still absent after a full run, and it
+  was mutation-checked by swapping the predicate for `resolveIdentity({ source: "host" })` and
+  watching it go red.
+
+### Docs
+
+- `README.md`, `AGENTS.md`, `INTEGRATION_PROMPT.md` and `llms.txt` each stated the absence this
+  change removes — *"exactly four checks"*, *"does not check the join key"* — in four separate
+  places. All four are corrected: a flag falsifies every doc that named its absence, and grepping
+  for the new identifier finds none of them. The historical entries below are left as written; they
+  describe what those releases shipped.
+
+### Tests
+
+912 → **923**, 0 fail (`mcp` unmoved at 128). All eleven new tests were mutation-checked: the
+unevaluated-join verdict, the appId-namespaced read, the shared identity predicate, the
+storage-failed branch and the read-only guard were each reverted in turn, each took a test red, and
+each was restored. The doc-compile gate was positive-controlled against the new README example.
+
+## [0.15.1] - 2026-08-19 — ⚠️ NEVER PUBLISHED; its contents ship in 0.16.0 above
+
+> This version was merged, gated and audited, but npm never served it: the pre-publish audit kept
+> finding defects while it sat unpublished, and by the time it was clean the surface had gained an
+> export, which forced a MINOR. **Do not look for 0.15.1 on the registry — it does not exist.**
+> Everything in this section is in 0.16.0.
+
+**PATCH — and a PATCH that carries RUNTIME behaviour change, not only docs.** It began as a
+docs-and-gates pass and grew, in the same unpublished version, into the audit wave below: five
+silent runtime failures, then four kill switches that could not stop a first impression, then the
+review gate's ambient device key. **221 non-comment lines under `src/` differ from 0.15.0**
+(diffed against the 0.15.0 tree over `src/`, with comment and blank lines excluded) — so read the
+`### Fixed` sections as shipped behaviour, and re-test accordingly.
+
+It is a PATCH because **the public surface did not move**: the built type surface is
+declaration-for-declaration identical to 0.15.0 (1049 normalised lines on both sides, diffed across
+every emitted `.d.ts` with the content-hashed chunk names normalised away; the instrument was
+positive-controlled by deleting a member and watching it report). Nothing was added, removed or
+renamed on any barrel, so a consumer re-pinning 0.15.0 → 0.15.1 compiles unchanged.
+
+> ⚠️ **This header used to read *"Docs, JSDoc comments, tests and package scripts only — every
+> changed line under `src/` is inside a comment."*** That was true when it was written for the docs
+> pass and became false the moment the first runtime fix landed in the same version. It is corrected
+> here rather than quietly deleted, because it is the same defect class the rest of this release
+> exists to fix — a claim that outlived the code it described — and it was sitting in the release's
+> own front matter, which is the last thing a reader sees before trusting everything below it.
+
+### Pre-publish audit (2026-08-20) — added to this version before it shipped
+
+An adversarial find-and-fix loop was run against the **tarball**, not the repo, before the
+irreversible `npm publish`. Six rounds, six lenses; it exited after two consecutive rounds found
+nothing new and every confirmed finding had an executable gate.
+
+#### Fixed — the findings that audit DEFERRED, taken in the same window
+
+The audit deliberately deferred five findings: each was real but had no path to user-visible harm
+before the publish, and every edit made against an about-to-be-immutable version carries its own
+risk. The version stayed unpublished long enough to spend that window, so it was spent. **No public
+export was added, renamed or removed** — the built `.d.ts` export lists are byte-identical to the
+ones the audit signed off, and the version stays 0.16.0.
+
+- **A gate's app-open counter stalled forever on a screen that never unmounts.** `bumpSessionCount`
+  follows real app-opens correctly and always has — but the review and questionnaire gates reached it
+  only from a `useState` initializer, which runs once per component INSTANCE. On a home feed that
+  stays mounted that is once per JS PROCESS, and iOS suspends apps rather than killing them: a user
+  who opens the app daily produces a fresh `app.session_started` each time (the SERVER's
+  `min_sessions` advances), while `wire_review_<id>_sessions` on the device sat at its launch value
+  and the LOCAL `minSessions` rule became unsatisfiable for the life of the app. Silent, and in the
+  safe direction — a prompt that never shows — which is why it survived a fix that was recorded as
+  complete. Both gates now subscribe to the session registry and re-ask the counter when a genuinely
+  new open is registered. A notification naming an open already counted is a no-op by construction,
+  so the cold-start ordering the existing pin exists for is untouched. Asserted at the mounted hook,
+  not at the helper: a green unit test over a helper is not evidence about its caller.
+
+- **`useAnalytics` handed the host a DISPOSED instance after a StrictMode remount (dev builds only).**
+  React's StrictMode runs a mount effect setup → cleanup → setup with **no render in between**. The
+  cleanup disposes the instance and clears the ref while the component is still mounted, and no
+  render comes to rebuild it — so the object the host is holding is disposed, and
+  `EventQueue.enqueue` returns early when disposed. Every `track()` on it was a silent no-op: no
+  error, no warning, `size()` stayed 0, until the host happened to re-render. The hook now returns a
+  stable facade that delegates to the live instance at CALL time, and the mount effect's setup
+  rebuilds what its own cleanup disposed. Production `<StrictMode>` is a passthrough, so no shipped
+  app lost an event — but dev is where a developer verifies that their analytics work at all.
+
+  The render harness gained a `strict` option so the next hook gets this coverage for free. ⚠️ It is
+  in the harness rather than at each call site because the double-invoke only fires when
+  `<StrictMode>` is the OUTERMOST element of the tree; nested one level down it silently does
+  nothing and the test passes over the defect it was written for.
+
+- **Five awaited `fetch` calls carried no ceiling.** The review and questionnaire transports (submit
+  and decision, both modules) and `reportClientEventsOutcome` all awaited a bare `fetch`, unlike the
+  event queue and `wireDoctor`, which each carried their own. A server that accepts a connection and
+  then says nothing parked those callers for the PLATFORM default (~60s on iOS) — holding the gates'
+  post latch closed, which is exactly the window their unmount recovery net cannot re-post inside,
+  and leaving a host's `await wire.track()` pending. All five now go through one shared deadline
+  helper carrying the two mechanisms the feature fetch learned the hard way: an abort that tears the
+  socket down, and a race that guarantees the promise settles even on a runtime that ignores
+  `signal` once the body has started. The BODY read is inside the deadline, because a ceiling
+  cleared when the headers land is not a ceiling.
+
+- **The kit's one `any` is gone.** `WireFeaturesProvider` reached its two global context slots
+  through `globalThis as any`, which made both contexts infer as `any` — so every Provider value in
+  that file, and every read of them, was type-unchecked. The slots are typed now; a wrong-shaped
+  Provider value is a compile error, which it was not before.
+
+#### Guarded — a latent context split that has no bite today
+
+`components/Illustration.tsx` and `icons/IconRegistry.tsx` hold their registries in a plain
+`createContext` rather than the shared global slot the theme and feature contexts use. Measured:
+there is no bite today — both modules are reached only from the root barrel, so exactly one bundle
+holds one context object. But that is a property of the current import graph, not of the code: the
+day a subpath surface renders an icon or an illustration, the module is inlined into that bundle too,
+the provider writes one context, the consumer reads another, and the registry silently serves empty.
+Changing a live context's load-time identity is a riskier edit than the latent defect right before an
+immutable publish, so this ships as a **ratchet only**: a test that fails the moment either module
+reaches a subpath bundle, naming the fix (park it in the shared slot) rather than allow-listing it.
+
+#### Fixed — the consumer could not complete step 0
+
+- **No shipped doc said where to get an `apiKey`.** All four said "the getwireai console" with no
+  URL, and offered `register_<app>.py` as the alternative. That script is in **no** `files` entry,
+  lives only in a private repo, and its only instances are named after this vendor's own apps, so a
+  customer could never run it. Step 0 of a first integration was unexecutable. `README.md`,
+  `AGENTS.md`, `INTEGRATION_PROMPT.md` and `llms.txt` now carry the real path, measured live on
+  2026-08-20: sign up at <https://getwireai.com/signup>, which creates the account, the first app
+  and its key together and lands the reader inside the console already signed in; then read the key
+  and the server URL off that app's **Integrate** tab. `/console/register` is for the SECOND app
+  onwards, and `/login` is for coming back later, not for finishing signup.
+
+  A second pass the same day corrected three details of that path that the first one got wrong,
+  because a wrong recipe is a different defect from a missing one, not a smaller one. Signup asks
+  for an app name and an email and takes the password on the confirmation screen (the docs said
+  email and password up front); it already mints the first app and its key, so a reader following
+  the old step 3 registered a redundant second app; and the **Integrate** tab renders exactly ONE
+  copy field, the API key. The server URL is the `serverUrl` line of the init snippet beside it,
+  so "both as copy fields" was not what the page shows. Per-environment keys are real and are
+  revoked in that tab's **Keys and environments** section, which is what the docs now name
+  instead of a standalone Keys surface.
+
+  A third pass corrected the docs' account of that same section, and of the key itself. **The
+  console has no add-key control**: self-serve issuance is gated off behind a flag that has been
+  `false` in every commit of the component's history (the empty state literally reads "Contact
+  support to provision one"), so "add and revoke them here" and "the console issues one key per
+  environment" were both capabilities we do not have. The label vocabulary is real, revoking is
+  real, issuing is not; the docs now say exactly that and point at Support. The wording had been
+  taken from a STALE COMMENT in the console repo describing the control as available -- a reminder
+  that another repo's prose is not that repo's behaviour, and only the component is.
+
+  **And a security note in this package contradicted its own instructions.** A callout added in
+  the first pass told the reader to keep the `apiKey` server-side and never commit it, three lines
+  above the step that puts it in `EXPO_PUBLIC_WIREAI_API_KEY`, which Metro inlines into the shipped
+  bundle at build time; the agent brief has always said the opposite and correctly ("a tenant key,
+  safe in the bundle"). The tenant key is DESIGNED to ship inside the mobile binary. What it cannot
+  do, since a backend ruling on 2026-08-01, is authenticate a console session, which is the
+  privilege boundary that was actually closed. The callout now says that, and keeps the one piece
+  of advice that survives: read it from an env var rather than a committed literal. Two more claims were corrected on review, both of
+  them the same class as the ones they were correcting: the key is readable back on EVERY visit
+  (the tab renders it from the app record, and the product's own signup copy promises exactly
+  that), so nothing "shows its key once"; and the `/login` step is not part of signup at all,
+  because the session cookie comes back on the set-password response and the reader is already
+  inside the console.
+
+- **`package.json` published three dead links.** `homepage`, `repository` and `bugs` all pointed at
+  `github.com/chohra-med/wireai-onboarding`, which answers **404** to anyone not signed in. npm
+  renders exactly those fields as the Homepage / Repository / Issues links. `bugs` is why this was
+  treated as CRITICAL rather than cosmetic: it told customers to report problems at an address they
+  cannot open, so a report is never rejected, it is simply never filed, and nobody finds out.
+  `homepage` is now the product site, `bugs` is the console's support form, and `repository` is
+  removed rather than pointing a closed-source package at a 404.
+
+  ⛔ **npm metadata is immutable per published version, so 0.15.0's three links are permanent.**
+  They are serving right now: `npm view @wireai/activation@0.15.0 homepage bugs repository` still
+  returns all three `wireai-onboarding` URLs, and `latest` is still 0.15.0. Nothing here repairs
+  the version a customer installs today. The fix reaches anyone only on the NEXT publish, which
+  is 0.15.1, and that is the whole reason it was worth catching before the irreversible step
+  rather than after it.
+
+  `bugs` also carries an **email**,
+  because the support form sits behind the console login wall: a paying customer gets there, but
+  someone still evaluating the package has no account, and their report would go the same silent
+  way as before. npm renders the address beside the URL, so both readers have a route.
+
+- **A pinned tarball version in an install line, for the second release running.** The README said
+  `npm install ./wireai-activation-0.15.0.tgz` while publishing 0.15.1, so the documented command
+  fails with ENOENT; the Distribution section three screens down already had it right as `x.y.z`.
+  This same class was fixed earlier in this very release and was not gated then, which is exactly
+  why it came back one version later: a doc fix that does not become an executable check is half a
+  fix. The neighbouring `git+ssh` line pointed at a repo path that does not exist, and is now a
+  placeholder.
+
+- **The "Backend coupling" section reads as an instruction but is a VENDOR operation** (it ends in a
+  deploy against a private backend). It now says so, and points at the console's Support section.
+
+#### Added — the gates, so none of the above can recur
+
+`test/canary/keyAcquisition.test.tsx`, eight assertions, every one mutation-checked by reverting
+the fix and watching that one assertion go red:
+
+1. every shipped doc names the signup URL;
+2. no shipped doc offers `register_…` in a sentence that also mentions a key;
+3. every console path printed is one this package DOCUMENTS, checked against an allowlist. It
+   started as a shape check and could not fail: `new URL()` cannot reject a string the capture
+   regex has already anchored to `https://getwireai.com`, and the capture stopped at the `<` of
+   `<app-id>`, so the templated Integrate URL was only ever seen as far as `/console/`. A
+   one-character typo in the address a first integration depends on passed all six;
+4. every consumer-facing link (`homepage`, `bugs.url`, and `repository.url` if it ever returns)
+   is on an ALLOWLIST of origins measured public. This started life as a ban list naming the repo
+   path the dead links used, and a ban list tests the wrong predicate: measured with the API,
+   `wireai-onboarding` and `wireai-activation` are ONE repo behind a redirect, and both 404 for
+   the public for a single reason, which is that a public package was pointing at a PRIVATE repo.
+   Spelling was never the fault, so a ban list would have waved through a `repository` field
+   naming the repo correctly (verified: it did, 6/6 green) and is blind to any private repo added
+   later. An allowlist fails on all of them and asks for a measurement;
+5. `homepage` and `bugs.url` are PRESENT and on the product host. That is all it ever did, and
+   it used to be NAMED "…and `bugs` is reachable by a customer", which the code did not check and
+   which is not true: `/console/support` answers 307 to `/login?next=…`, so a stranger reaches a
+   login wall. Renamed to its behaviour, because an assertion whose name claims more than its body
+   is worse than no assertion: it is read as coverage;
+6. `bugs` carries a LOGIN-FREE contact route, and not an unmonitored `noreply` one. This is where
+   the reachability claim honestly lives. An email needs no account, so it is decidable offline;
+   whether a login-walled URL lets a stranger in is not. An address nobody reads would satisfy the
+   field and move the silent failure one layer down instead of closing it;
+7. the two allowlists above are PINNED by content and length, so widening one is a failing test
+   rather than a one-line config edit. An allowlist that can be widened in the same diff that
+   needs the widening is decorative, and this repo has already lost that round once (a permitted-
+   `await` allowlist was defeated by adding a bare `"await"` entry, green through two reviews).
+   Verified both ways: adding `https://github.com` to the origins lets a `repository` field
+   pointing at the private repo pass assertion 4, and adding the typo'd path lets the typo pass
+   assertion 3 -- and this assertion catches both;
+8. no shipped doc pins a concrete tarball version in an install command.
+
+⛔ These canaries are OFFLINE by design, and the file header now says why a reachability probe
+would not help: `/console/support` returns a FINAL 200 after one redirect, on the login page, so a
+"follow redirects, expect 200" check scores the login wall as a pass. Reachability is a release-time
+preflight that inspects the final URL, not a unit test.
+
+#### Fixed — three runtime defects the pre-publish audit found LAST (2026-08-20)
+
+- **CRITICAL — the questionnaire's recovery net was INERT while its POST was in flight, so a
+  finished run was silently destroyed AND its permanent once-gate already spent.** This is the exact
+  defect 0.15.1 fixed in `reviews/ReviewGate.tsx` earlier in this same version, left uncorrected on
+  the second copy — the `correct-the-whole-set-not-n-minus-one` class. `postedRef` is taken
+  OPTIMISTICALLY and released only in the transport's `.then`, while `finish` auto-closes the modal
+  1500ms after posting. On any network slower than that the gate unmounted mid-flight, the net's only
+  branch (`if (undelivered && !postedRef.current)`) found the latch CLOSED and no-opped, and the POST
+  later resolved `"unsent"` with nothing mounted to notice. The host's `onResolved` → `markResolved`
+  has already written the permanent `wire_questionnaire_<id>_<ver>_seen` key, so that user is never
+  asked again. The `ReviewGate` shape is ported verbatim: `recoverOnSettleRef` / `recoveredRef` /
+  `postOnceRef`, an in-flight branch in `postOnce`'s `.then`, and an in-flight branch in the unmount
+  net; recovery stays bounded to ONE extra post. The questionnaire's deliberate difference is kept —
+  it has NO abandonment payload to rescue, because a half-typed draft is not an answer.
+  (`src/questionnaire/QuestionnaireGate.tsx`.)
+
+- **HIGH — a MINTED session id defeated the cold-start guard, so one launch counted as TWO
+  app-opens.** `ensureCurrentSessionId()` mints a fallback id AND writes the shared session slot (it
+  must: the server drops an event with no `session_id` behind a 200), and it is reached from
+  `analyticsFacade.resolveSessionId`, `wireActivation.track` and `reviews/transport.reportAppEvent` —
+  any of which a host can hit before `useLifecycleEvents` mounts. So `currentOpenId` pinned the launch
+  with `observed = <the minted id>` instead of `undefined`, its cold-start adopt branch never fired,
+  and the REAL `app.session_started` that followed read as a genuinely new open. The fail-closed
+  `minSessions: 2` default — the guard added after the 2026-07-16 one-star incident — became
+  satisfiable inside a user's FIRST session. It failed in the UNSAFE direction. A fallback id is not
+  evidence the app was opened: the mint is now recorded in its own cross-bundle slot and
+  `currentOpenId` treats a pin taken over one exactly like a pin taken over nothing, so the first
+  REAL registration adopts the open rather than starting a second. The existing cold-start rule is
+  unchanged. (`src/analytics/currentSession.ts`, `src/reviews/runtime.ts`.)
+
+- **MEDIUM — `fetchWireFeatures` had no ceiling on the BODY read, so both gates could hold dark
+  forever.** The abort timer was cleared in a `finally` around the `fetch` alone, so it died the
+  moment the headers landed and `await res.json()` ran uncapped. A 200 whose body then stalls left
+  the call pending forever, `settled` never flipped, and `useReviewGate` / `useQuestionnaireGate`
+  never became ready — inverting the module's own stated contract, *"fail-open, never fail-dark… it
+  can never dark a tenant's activation"*. One deadline now covers the headers AND the body, with two
+  mechanisms because they fail differently: the abort tears the socket down, and the race guarantees
+  the promise settles even on a runtime that ignores `signal` mid-body. Honest scope: on native RN
+  `fetch` is the XHR polyfill and the body is already buffered, so this was effectively unreachable
+  there; on RN-Web / Expo web, which the kit explicitly supports, it is real.
+  (`src/features/fetchWireFeatures.ts`.)
+
+Every one of the three carries a new test that was MUTATION-CHECKED (revert the fix → that test goes
+red → restore, tree byte-identical), and the two whose assertion is "a number did NOT move" carry an
+instrument check proving the harness can see the move it is asserting the absence of.
+
+#### Checked and clean (no change needed)
+
+The tarball leaks no internal path (`.memory`, `ai_rules`, `CLAUDE.md`, specs, tests: **0**), ships
+no credential-shaped literal and no commit SHA in the release notes; **43/43** `exports` targets and
+**19/19** type entrypoints exist in the tarball; the README's install line resolves in a clean
+consumer with no peer errors; **all 7 subpaths** and **all 28 documented named imports** resolve
+against the *installed* package; and the README's `metro` snippets execute correctly in both their
+documented call forms. Each of those instruments was positive-controlled before its result was
+believed.
+
+Tests: **912 → 920**, 0 fail; `mcp` **128**, 0 fail; typecheck and a clean build both green.
+
+⚠️ **The console claims in these docs are NOT gated, and cannot be from here.** They are assertions
+about another repository's rendered UI; this package's canaries are offline and in-tree. Three
+rounds of review found a false console claim each time, so the standing rule is that every sentence
+about the console names the `file:line` in the console repo that proves it, and the durable fix is a
+release-time preflight that reads that repo. Filed, not built here.
+
+### The docs-and-gates pass this version started as
+
+0.15.0 shipped `<WireOnboarding config={{ ...config, storage }} />` in two published docs and in the
+`userContext` JSDoc that seeded them. `storage` is a PROP of `<WireOnboarding>`, not a field of
+`WireOnboardingConfig`, so an agent that copied that line shipped an integration that does not
+compile — and, if it worked around the error by dropping the prop, one with a permanently empty
+`activated` funnel and no error anywhere. The root cause was not the typo. It was that NOTHING in
+this repo has ever compiled doc-borne code: `src/docsContract.test.ts` reads the `import` line of an
+example and nothing below it, and everything else polices the docs as prose. `docsContract.test.ts`
+had already written the verdict in its own header — *"prose review has already failed to catch it
+twice. Only an executable check holds."*
+
+### Added
+
+- **`test/canary/docExamples.test.tsx` — the doc examples are now COMPILED.** It resolves the doc
+  list off the real publish surface (never a filename list), extracts every fenced ` ```ts ` /
+  ` ```tsx ` block, writes each to its own file, and runs `tsc --noEmit` with
+  `@wireai/activation*` mapped to the BUILT `dist/*.d.ts` — the types a customer installs, not
+  `src/`. 29 blocks compile today. Free identifiers are supplied in three tiers: the handful the
+  kit itself types (`config`, `storage`, `target`, the id strings), then every name the built
+  bundles export bound to its real shipped type, then everything still unresolved declared `any` as
+  a host-owned value — the last tier discovered mechanically from a compile pass, not from a list
+  that would rot. A fence that is genuinely a fragment opts out with
+  `<!-- doc-check: skip - reason -->`, and a skip with no reason fails the suite.
+- **Three policy assertions a compiler cannot make.** Every documented `npm install` line must name
+  every NON-OPTIONAL peer, read from `peerDependencies` + `peerDependenciesMeta` at test time.
+  Every PRIMARY `<WireOnboarding>` example (one that shows `config` and BOTH exits) must carry
+  `fallbackFlow` and a join key, because both props are optional in the type and only a policy can
+  see their absence. And no doc may tell a reader to run something the tarball does not ship.
+- **Five anti-false-clean floors,** one per scanner: the doc list, the fence count, the parsed
+  export surface, the install-line count and the primary-example count. Measured, then asserted, so
+  a rotted regex fails instead of passing over nothing.
+
+### Fixed
+
+- **`storage` was documented as a config field.** Corrected in `AGENTS.md` (the join-key example and
+  the lifecycle paragraph), `llms.txt`, `INTEGRATION_PROMPT.md`, and — the origin the copies came
+  from — the `userContext` JSDoc in `src/types.ts`. `README.md` was already right.
+- **`useLifecycleEvents(config, …)` did not compile as documented.** Its first argument is a
+  `LifecycleConfig`; `wireConfigFromEnv` returns `WireOnboardingConfig | null`. The three agent docs
+  now print the literal form `useLifecycleEvents({ serverUrl, apiKey, appId, storage }, …)` that
+  `README.md` already used, and say why.
+- **`fetchReviewDecision` → `useReviewGate` dropped the `?? undefined`** in `AGENTS.md`. The fetch
+  resolves `ReviewDecisionResponse | null`; the hook option is `decision?: ReviewDecision`.
+- **Install lines left out required peers.** `zod` and `react-native-safe-area-context` are
+  non-optional and were missing from every install line in `README.md`, `AGENTS.md`, `llms.txt` and
+  `INTEGRATION_PROMPT.md`.
+- **The two primary README examples taught an integration the review bar rejects** — no
+  `fallbackFlow` (so a backend error dead-ends instead of degrading) and no join key (so the
+  `activated` funnel reads zero, silently). Both now carry them.
+- **Every doc led with a "fastest path" that does not exist.** The `wire-rn-integration` skill is
+  not in the tarball and is not in this repo either. Replaced with `INTEGRATION_PROMPT.md`, which
+  ships in the package.
+- **Six more examples that did not compile:** a `useRef<string>()` with no argument (React 19
+  removed that overload), an untyped `useMemo` whose widened `gesture: string` cannot be a
+  `CoachmarkStep`, a `<WireOnboarding>` missing its required `config`, and the review-gate snippets
+  that reused the names `config` and `storage` for the GATE's config and its SYNCHRONOUS store.
+
+### Changed
+
+- **`prepublishOnly` runs the whole suite, not just the canaries.** It was
+  `npm run build && npm run test:canary`, which excludes `src/**/*.test.ts` — so
+  `src/docsContract.test.ts`, the one doc gate that already existed, never ran at publish time. It
+  is now `npm run build && npm test`, the same suite CI and a developer run.
+
+### The doc gate had a silent-skip loophole (second pass, same day)
+
+> A separate pass over the gate the section above added. It kept a hole of exactly the shape the
+> gate exists to close, and four live doc defects were sitting inside it.
+
+- **A BARE ` ``` ` fence was skipped SILENTLY.** The extractor matched only ` ```ts ` / ` ```tsx `;
+  anything else was dropped with no marker, no reason and no failure. That is the inverse of the
+  `doc-check: skip` directive, whose reason is MANDATORY. The consequence was measurable:
+  `INTEGRATION_PROMPT.md` had zero tagged fences, so the gate compiled **nothing** from the file
+  every other doc calls the fastest path, and `llms.txt` prints no fence at all. Every fence in a
+  shipped doc now needs an explicit DISPOSITION: `ts`/`tsx`, a known code/data lane, or the skip
+  directive with a reason. A bare fence fails by construction, so no heuristic ever has to guess
+  whether to fail. (For the record, because the miscount is easy to repeat: counting untagged
+  ` ``` ` LINES reports 42 for `README.md`, but 41 of those are the CLOSING fences of tagged
+  blocks. Across all five docs exactly TWO blocks were opened by a bare fence, an env file and an
+  English prompt, and neither was TypeScript.)
+- **A language tag can no longer hide a TypeScript example.** A ` ```bash ` or ` ```json ` fence is
+  now content-checked for line-anchored TS/TSX shapes, and a ` ```js ` fence may be CommonJS (the
+  metro config) but not ESM or JSX. An unknown tag fails loud rather than passing quietly. The
+  shape detector has a positive control that runs as a test: it must fire on a real TSX example and
+  stay silent on a shell transcript, an env file, and prose that quotes code in backticks.
+- **Inline `code spans` in prose are now compiled too, as far as they honestly can be.** A span is
+  lifted into the compiler when it is a complete call or self-closing JSX element, headed by a name
+  the kit exports, carrying an object literal (which is what separates a call a reader TRANSCRIBES
+  from signature notation like `track(name, meta?)`). 34 spans compile today, which is the only
+  coverage `llms.txt` and `INTEGRATION_PROMPT.md` have ever had. Stated plainly: this is PARTIAL.
+  Signature notation is not code and is not checked, and a bare identifier in prose cannot be told
+  apart from a host-owned name, so prose identifiers are not existence-checked.
+- **A whole-screen scaffold is now held to the review bar.** The `PRIMARY` selector keys off
+  `config` + BOTH exits, and `README.md`'s "3-line minimal usage" slipped through it for the whole
+  0.15.0 cycle by simply not printing `onSkip`: a complete, exported, copy-me screen with no
+  `fallbackFlow` and no join key, exempt BY CONSTRUCTION. A fenced example that imports from the
+  kit, declares a component and mounts `<WireOnboarding>` is now held to the same bar whatever
+  props it prints.
+
+### Fixed by the tightened gate
+
+- **`INTEGRATION_PROMPT.md:66` taught `useReviewGate({ config, decision })`, which does not
+  compile** on either argument: `Type 'ReviewDecisionResponse | null' is not assignable to type
+  'ReviewDecision | undefined'`, and `Property 'id' is missing in type 'WireOnboardingConfig' but
+  required in type 'ReviewConfig'`. `AGENTS.md` already called the `?? undefined` "not optional"
+  and `README.md` already showed it correctly; the prompt was the copy nobody compiled.
+- **Two docs handed `wireConfigFromEnv(...)` straight to the required `config` prop.** It returns
+  `WireOnboardingConfig | null`. `INTEGRATION_PROMPT.md` and `llms.txt` now mint it, gate on the
+  null, and render the gated value.
+- **The README "minimal usage" example had no `fallbackFlow`, no `storage` and no `userContext`.**
+  It now carries them, and says why: those are the two omissions that fail silently.
+- **`isOnboardingEnabled` was documented with only its `remote` option** in `AGENTS.md` and
+  `llms.txt`; it also takes `config` (`WireConfigOverrides`).
+- **The `AGENTS.md` "Types:" line omitted `WireOnboardingStorage` and `LifecycleConfig`,** both
+  exported and both needed to type the props that same file documents.
+
+### Documented (three silent failures the agent docs never named)
+
+- **The review/questionnaire gates need SYNCHRONOUS storage.** `useReviewGate` counts app opens
+  through a `CoachmarkStorage` (`getItem` returns `string | null`, not a Promise), which is a
+  DIFFERENT shape from the AsyncStorage-style adapter `<WireOnboarding storage>` takes. The kit's
+  own source says the outcome: "No storage pins the counter at 1 forever, so the fail-closed
+  minSessions rule can never be met and the gate silently never fires." An async adapter reaches
+  the same dead end: the kit probes it, sees the thenable, and substitutes a fail-closed store.
+  `README.md` documented this; `AGENTS.md`, `llms.txt` and `INTEGRATION_PROMPT.md` did not mention
+  `storage` at all, while `AGENTS.md` opens by claiming "everything you need is here". Now in all
+  three.
+- **How to actually WIRE `<ReviewGate>`.** It has no `gate` prop. `AGENTS.md` gains a compiling
+  example (gated by the harness above) showing the controller's `visible` / `markShown` /
+  `markResolved`, and spells out that omitting `onShown`/`onResolved` compiles, shows the prompt,
+  and re-prompts the same user on every open, because those two are what persist the cooldown and
+  the once-per-version seen gate. They previously appeared only in `README.md`.
+- **`sessionCount` is a HOST obligation.** `AGENTS.md`, `llms.txt` and `INTEGRATION_PROMPT.md`
+  printed `{ deviceKey, sessionCount, userId }` without saying the host must own a persisted,
+  per-open counter. A hardcoded `1` compiles and pins every user at `returning: false` forever.
+- **`wireDoctor` cannot see the #1 documented silent failure, and the docs implied it could.** Its
+  four checks are `target`, `reachability`, `storage`, `round_trip`. None checks the join key, the
+  lifecycle mount, or `min_sessions`, so an integration with a permanently-zero `activated` funnel
+  passes every check green. `INTEGRATION_PROMPT.md` said "Every check must come back `ok`" and
+  stopped there. All three agent docs now state what a green report does NOT mean. **No runtime
+  change**: `src/analytics/wireDoctor.ts` is untouched. A `join_key` check is recommended as future
+  work, not implemented here.
+
+### Still blocking (not invented)
+
+- **No doc can tell a reader where to GET an api key or a `serverUrl`.** Every one says "the
+  getwireai console" with no URL, and no `register_<app>.py` ships in the tarball. Deliberately
+  left alone rather than filled with a guessed URL. It needs an owner decision.
+
+### Fixed — five silent runtime failures (audit wave, branch `fix/0.15.1-runtime-silent-failures`)
+
+*A separate set of changes inside the same version. Every one of these compiles, runs, looks fine
+and reports nothing — the product's entire failure history in one shape. Each carries a test that
+was watched go RED with the fix reverted and GREEN with it restored.*
+
+- **A hung storage adapter killed the whole app-open funnel.** Both lifecycle hooks
+  (`useLifecycleEvents`, `useSessionStart`) awaited `hydrateDeviceIdentity`, which awaits a BARE
+  `storage.getItem` with no ceiling anywhere in the chain, and every fire lives inside that `.then`.
+  An adapter that neither resolves nor rejects (a locked keychain, a wedged bridge) therefore meant
+  `app.session_started` and `app.first_open` never fired — for the whole process, on every launch,
+  with nothing thrown and nothing logged. Those are the events the server counts `min_sessions`
+  from, so the counter stayed 0 and every review / questionnaire trigger that reads it became
+  permanently unsatisfiable. The kit had already solved this five times (`WireOnboarding.tsx`'s
+  `AUTO_JOIN_HYDRATION_TIMEOUT_MS`, `persistedSession`, `lifecycle`, `eventQueue`, `features/cache`);
+  only these two hooks had no cap. Both now race the read against the SAME exported ceiling
+  (`withTimeout` + `READ_TIMEOUT_MS` from `session/persistedSession`) and fire DEGRADED on a
+  timeout — with no auto device key, exactly the branch a rejecting adapter already took. The false
+  JSDoc on `hydrateAutoDeviceKey` / `hydrateDeviceIdentity` that claimed a *"hung"* adapter resolves
+  to the in-memory id is corrected: it never did, and now says so and names the ceilings its callers
+  apply. (`app.first_open` is still not EMITTED under a hung adapter — `reportFirstOpen` declines on
+  its own timed-out flag read, a standing 0.14.0 ruling — but it is now REACHED instead of stranded.)
+- **`reportFirstOpen` spent the once-EVER flag when nothing was sent.** With `storage` + `appId` but
+  no `sink` and no `serverUrl`, `emitFirstOpen` routes through `buildEventsRequest`, which returns
+  `null` — a silent no-op — and the persisted `wireai:first_open:<appId>` flag was written anyway.
+  That marks the install as having reported its first open while ZERO events exist, and the flag
+  survives app kills, so `app.first_open` was dead for that install forever. Reachable on the
+  documented wiring: `serverUrl` is optional on `LifecycleConfig` and the hook's effect is
+  mount-only, so a late-resolving URL lands exactly here. It now bails on
+  `!sink && !target?.serverUrl` before either guard, mirroring `reportSessionStart`.
+- **An EMPTY `steps` array burned the coachmark once-gate.** `useCoachmarkTour` armed without
+  looking at `steps`, then the drive effect hit `activeIndex >= steps.length` → `finish()` →
+  `markSeenGate(...)`: the user saw nothing and the tour was dead on that install for good, even
+  after the catalog was fixed. Reachable on the documented AI path — `selectTourSteps` returns `[]`
+  whenever the server sends ids a SHIPPED catalog does not know — and on any host whose steps
+  arrive async. The tour no longer arms on an empty list (keyed on `steps.length`, a VALUE, so an
+  inline array cannot restart the arm timer every render), and a list that goes empty mid-tour takes
+  the kill switch's `exit(false)`, which writes no gate.
+- **The review abandonment net was inert while the post was in flight.** `postedRef` is taken
+  optimistically and released only in `submitReview`'s `.then`, while the gate auto-closes 1500ms
+  after posting. On any network slower than that, unmount ran with the latch still closed: the
+  recovery branch needs `!postedRef.current` and the abandonment branch returns on it, so BOTH
+  no-opped and a detractor's 1-4 stars plus mandatory text was dropped silently — and the once-gate
+  means they are never asked again. The unmount now hands the recovery to the promise when it finds
+  a post still in flight, and the `.then` re-posts once if nothing reached the server. Bounded to
+  exactly ONE extra post (the net's existing in-process ceiling), carrying the impression's
+  `idempotency_key` and its unit, so a row that did land is upserted rather than duplicated.
+- **The review kill switch could not stop the FIRST impression.** `useWireFeatures` seeds the all-on
+  defaults and swaps only when `GET /v1/features` resolves, so `useReviewGate` read
+  `review.enabled === true` on the first render of every mount — and with no `timeoutFallbackMs`
+  the local wait is skipped too. A tenant with `review.enabled: false` still got a visible gate, a
+  `review_prompt_shown` and, if tapped in that window, a POSTed row; the code comment saying such a
+  tenant "must never see the gate" was falsified by its own async default. The gate now holds its
+  first impression until the feature answer is SETTLED. Fail-open is untouched, and the distinction
+  is the whole fix: `fetchWireFeatures` swallows a timeout / 401 / 5xx into the defaults and that
+  resolution IS an answer, so an unreachable control plane still allows the gate — only an
+  unanswered question holds it, and a surface with no `featuresConfig` has nothing to wait for.
+- **Internal, no public surface change:** `useWireFeaturesState` / `useResolvedFeaturesState` (flags
+  + `settled`) back the two existing flags-only hooks, and `WireFeaturesProvider` publishes the
+  settled flag on a SECOND `Symbol.for` context (`wireai.features.settled.context`, defaulting to
+  `true` so a missing or older provider can never suppress a gate). Neither is exported from the
+  root barrel — this stays a PATCH.
+- **15 new tests** (878 → 893 after rebasing onto #100's +9; mcp unchanged at 128), each
+  mutation-checked:
+  `test/canary/lifecycleHungStorage.test.tsx`, `test/canary/coachmarkEmptyTour.test.tsx`,
+  `test/canary/reviewKillSwitchRace.test.tsx`, three slow-network cases added to
+  `test/canary/reviewSubmissionDurability.test.tsx` (the existing fast-path ordering is untouched —
+  it is what hid the defect), and one no-transport case in `src/session-analytics/lifecycle.test.ts`.
+
+### Fixed — the n−1 twin: the QUESTIONNAIRE kill switch had the identical first-render defect
+
+- **`useQuestionnaireGate` read `.questionnaire.enabled` off the optimistic all-on seed**, exactly
+  as `useReviewGate` did before the fix above. A tenant with `questionnaire.enabled: false` could
+  therefore still get a visible gate on the first render of every mount, a
+  `questionnaire_prompt_shown`, and — if the user answered inside that window — a POSTed response
+  row on `/v1/questionnaires/{id}/responses`. It was filed as a deliberate follow-up when the review
+  gate was fixed (`.memory/60-decisions.md`, 2026-08-19) rather than bundled, so a falsification
+  failure there could not be ambiguous between two surfaces.
+- **The fix reuses the seam that fix introduced — no second mechanism.** The gate now reads
+  `useResolvedFeaturesState` and holds its first impression until `settled`, and `settled` flips on
+  EVERY resolution of `fetchWireFeatures` including the fail-open one. An unreachable control plane
+  (timeout / 401 / 5xx / malformed body) resolves to the all-on defaults, and that resolution IS the
+  answer, so it still ALLOWS the questionnaire; only an unanswered question holds it. A host with no
+  `featuresConfig` has nothing to wait for and is byte-identical to before.
+- **No public surface change.** `useResolvedFeaturesState` stays internal, nothing is exported,
+  renamed or removed from any barrel — this remains a PATCH.
+- **5 new tests** (893 → 898; mcp unchanged at 128), all in
+  `test/canary/questionnaireKillSwitchRace.test.tsx`, mutation-checked in BOTH directions: removing
+  the settled seam turns 4 of them red, and breaking fail-open (settling only on a non-default
+  answer) turns the other 3 red. Every fail-open test asserts the HOLD before the RELEASE — a
+  release-only assertion passes on an unfixed gate and would certify the defect.
+
+### Fixed — the n−2 and n−3 twins: the COACHMARKS and SHOWCASE kill switches, where the same seam does NOT port
+
+- **The same first-render defect, on the last two surfaces that had it.** `CoachmarkProvider` read
+  `.coachmarks.enabled`, and `FeatureShowcase` read `.showcase.enabled`, off the optimistic all-on
+  seed. A tenant who switched either module OFF still got the first tour, and the whole full-screen
+  intro, on every cold start — and the showcase could take the once-gate with it: tapping through
+  those slides calls `finish`, which writes `wire_showcase_<id>_seen`, so the showcase then never
+  replayed even after the tenant re-enabled it. Silent, permanent, once per install.
+- **⛔ The seam the review + questionnaire gates use does NOT port to either surface, and forcing it
+  would have shipped a worse defect than the one being fixed.** Both sites were left alone in the
+  earlier pass for that reason, correctly. Each needed its own shape:
+- **Coachmarks — TRI-STATE, because the kill switch is TERMINAL.** `useCoachmarkTour` SUBSCRIBES to
+  the coachmarks flag and `exit()`s a tour in flight when it flips false. Holding the surface by
+  writing that flag false during the fetch would therefore have ended the tour of every ENABLED
+  tenant on every cold start. So "is the verdict an ANSWER?" is now a SECOND fact on the same
+  runtime record (`setCoachmarksResolved` / `areCoachmarksResolved`, written by `CoachmarkProvider`
+  from the resolved features' `settled`, waking the same listener set). An unanswered verdict blocks
+  ONLY the ARM of a NEW tour — no timer starts, no overlay shows, no once-gate is consumed, so an ON
+  answer plays the tour in full — and never touches a tour already running. The field is OPTIONAL on
+  the runtime type and reads `true` when absent, exactly like `listeners`, so a record left by an
+  inlined copy from an older kit version is upgraded in place rather than read as "unanswered".
+- **Showcase — a BOUNDED, SCOPED hold, because the disabled path calls `onDone`.** A naive hold on
+  `!settled` is a blank full screen for as long as the features fetch takes (its own ceiling is
+  4000ms), on every launch. Two bounds fix that. SCOPE: an already-seen gate or an absent pager
+  skips whatever the tenant answers, so those launches — every launch after the first — never wait
+  at all. TIME: the hold expires at `READ_TIMEOUT_MS` (1500ms, the repo's one exported read ceiling,
+  reused rather than a third number invented here) and falls through to the previous optimistic
+  behaviour, so the worst case is what shipped before, reached later.
+- **Fail-open is unchanged on both.** `settled` flips on EVERY resolution of `fetchWireFeatures`
+  including the fail-open one, so a timeout / 401 / 5xx / malformed body still arms the tour and
+  still plays the showcase. Only a question nobody has answered YET holds either surface, and a host
+  with no `featuresConfig` has nothing to wait for and is byte-identical to before.
+- **No public surface change.** `useResolvedFeaturesState`, `setCoachmarksResolved` and
+  `areCoachmarksResolved` are all internal — `src/coachmarks/index.ts`, every other barrel and
+  `package.json` are byte-identical to the previous commit. This remains a PATCH.
+- **11 new tests** (898 → 909; mcp unchanged at 128): 5 in
+  `test/canary/coachmarkKillSwitchRace.test.tsx`, 6 in
+  `test/canary/showcaseKillSwitchRace.test.tsx`. Both files were mutation-checked — reverting each
+  fix turns its first test red — and each carries the controls that stop the fix from being a mute:
+  an explicit ON must still fire, a FAILED fetch must still fire, and a host with no `featuresConfig`
+  must be unchanged. The coachmark file additionally pins THE LINE THE FIX MUST NOT CROSS: an
+  unanswered verdict may not tear down a tour in flight. The showcase file pins both bounds of its
+  hold, including that an already-seen showcase is never held at all.
+
+### Fixed — the review gate's ambient device key could go SILENTLY DEAD for the whole process
+
+- **`ambientAutoDeviceKey` minted its fallback id INTO the tenant census it then counts.** The
+  function answers "which single id space does this process have?" by reading `registry.keys`, and
+  refuses (`undefined`) when it reads two, because a propless caller cannot say which of two tenants
+  a device belongs to. When it read ZERO it minted through `resolveAutoDeviceKey()`, which
+  REGISTERED that fallback under `"default"` — so the fallback became an entry in the very census
+  the next call is judged by. The review gate lives on the home feed, so a cold start can reach it
+  before any Wire surface has initialised: the gate asked first, left a `"default"` entry behind,
+  and the moment the host's real `appId` registered the census read TWO. Every later call returned
+  `undefined`, the injected `meta.device_key` stopped happening, and the server then has no unit to
+  scope the impression's `idempotency_key` to — so it discards the key and inserts a plain row,
+  which means each recovery re-post writes a SECOND review row (a double-counted `count`, a
+  corrupted `avg`). Ordering-dependent, silent, and permanent for the process.
+- **The fix holds the fallback OUTSIDE the census** (a new `ambient` field on the existing
+  `@wireai/activation:autoDeviceKeys` registry, not a new global slot), so it yields instead of
+  competing: a real id space appearing later simply wins, which is the answer the function's own
+  docstring already argued for. A process that never registers one keeps its fallback, so the
+  reviews-only host is byte-identical to before.
+- **The docstring was amended rather than left standing.** Its three-state reasoning was sound at
+  any ONE instant and wrong across two, because the empty-state branch wrote into the map the next
+  instant is read from; the comment now says so.
+- **Deliberately NOT changed: the impression's unit is still pinned even when it is NON-DURABLE.**
+  Porting the kit's cross-launch-join rule ("read `durable`, refuse a `false`") to this field was
+  considered and REJECTED, with the reasoning recorded in `src/reviews/idempotency.ts` and
+  `.memory/60-decisions.md`. Refusing a non-durable unit removes the unit, which makes the server
+  discard the key and write the second row — trading an under-counted join for a corrupted rating.
+  Measured, not argued: applying that rule turns 7 existing tests red, including
+  `THE INERTNESS PROBE`, both `CONTRACT SIM`s and `ASYNC ORDERING`, every one of which exists to
+  pin that a home-feed post carries a unit.
+- **What this release does NOT close, stated plainly.** A review row can still be stamped with a
+  device key no analytics event carries, in two sequences: an impression opened before any surface
+  has registered a real `appId` (it pins the ambient fallback), and one opened while a hydration is
+  in flight (it pins the synchronous mint, and the persisted id replaces it a moment later). What
+  the fix above removes is the PERMANENT case — the reader answering `undefined` for the rest of the
+  process — so the residue is bounded to impressions opened before the id space settles, and the
+  gate is once-per-user. Refusing the unit does not repair that join; it removes the join AND the
+  server's ability to dedupe. Closing it properly means giving the gate a settled identity to pin
+  (`appId` / `storage` props on `ReviewGate`), which is a public-API change and not a PATCH.
+- **No public surface change.** `ambientAutoDeviceKey` is internal (it is not in `src/index.ts`);
+  no barrel and no `package.json` field moved — this remains a PATCH.
+- **Also added: the guard for the coachmark ruling in the section above, which had none.** That
+  section argues at length that an UNANSWERED verdict must publish the kill switch as ON, because
+  the flag is terminal for a tour in flight — and flipping that `true` to `false` left all five of
+  its tests green. The one that names the shape ("an UNANSWERED verdict never tears down a tour in
+  flight") reaches it by calling `setCoachmarksResolved(false)` on the runtime singleton and never
+  mounts a `CoachmarkProvider`, so the line encoding the ruling was executed by no test. The new
+  case arms a tour, then mounts the REAL provider with `/v1/features` deliberately unanswered, and
+  asserts the tour survives; it is the only test in the file the naive repair turns red. No source
+  change — `src/coachmarks/CoachmarkProvider.tsx` is byte-identical.
+- **3 new tests** (909 → 912; mcp unchanged at 128), each mutation-checked by reverting the code it
+  guards and watching it fail:
+  `src/reviews/idempotency.test.ts` ("ambientAutoDeviceKey SURVIVES a late registration") and
+  `test/canary/idempotencyKey.test.tsx` ("REGISTRATION ORDER"), the latter driving the real
+  `ReviewGate` and asserting on the CAPTURED POST BODY, never on a return value; plus
+  `test/canary/coachmarkKillSwitchRace.test.tsx` ("THE SAME LINE, THROUGH THE REAL PROVIDER").
+
+## [0.15.0] - 2026-08-19
+
+**MINOR, not patch, and only because of new API. Two exported surfaces each GAINED an optional
+member; nothing was lost or renamed.** `ReviewSubmission` gains an OPTIONAL `idempotency_key` and
+`buildReviewSubmission` gains an OPTIONAL `idempotencyKey` input. Both are additive and optional, so
+every existing call site compiles unchanged and sends a byte-identical body unless it opts in. A
+gained public member is still a MINOR under this changelog's own precedent: 0.14.0 was bumped MINOR
+for exactly this shape, an optional field added to an exported interface. Every behaviour change
+below is a bug fix.
+
+### Added
+
+- **The review gate can now reach the server's idempotent upsert path, so a recovery post merges
+  into the row it may already have written instead of adding a second one.** `POST /v1/reviews`
+  accepts an optional client-minted `idempotency_key` and derives the row id from it; the kit now
+  mints one per gate IMPRESSION and holds it across every post of that impression. This is a
+  CAPABILITY, not a guarantee, and the condition is load-bearing: the server honours the key only
+  when the post also carries a unit it can scope it to, and ignores it outright otherwise.
+- **Every review post now carries that unit.** The server resolves it as `meta.device_key`, else
+  `session_id`. The gate lives on the home feed, where a user legitimately has no onboarding
+  session, and the kit never put a `device_key` into a review `meta` — so the key alone would have
+  been discarded on the default wiring. The gate now fills in the kit's own per-install auto id,
+  and only when the host supplied none: **any non-empty string you pass in `meta.device_key` wins
+  verbatim.** The kit counts a value as host-supplied only when it is a string with at least one
+  non-whitespace character, so a non-string or an all-whitespace one is not a usable unit and is
+  replaced. **Overriding `meta` cannot remove the unit**: the injection tests the MERGED bucket, so
+  stripping `device_key` there only gets the auto id back. Exactly one post carries no unit at all,
+  the one where the kit cannot name an id honestly: two tenants registered in one process, which
+  leaves the per-install id space ambiguous and the auto id `undefined`. That post reaches the
+  server with no unit, the server ignores the idempotency key, and that path keeps the previous
+  behaviour.
+- The injected id is the SAME per-install id the analytics surfaces use, adopted from the process
+  registry rather than minted fresh, so the gate never opens a second id space for one install.
+
+### Unchanged on purpose
+
+- **The `rejected` verdict is still not retried.** Re-posting after a non-2xx is now safe wherever
+  the key is honoured, but it would also turn a genuine 4xx refusal into a retry needing its own
+  budget. That is a separate recovery decision and is deliberately not bundled here.
+- Questionnaire submissions are untouched. The server has no idempotency path for them, so every
+  statement in `src/questionnaire/` about there being no key on the wire remains true.
+
+### Fixed
+
+- **An ASYNC gate-storage adapter now fails CLOSED instead of misfiring the gates.** The sync gate
+  storage (`CoachmarkStorage`) silently accepted an async adapter — AsyncStorage handed straight to
+  `CoachmarkProvider` or a gate's `storage` prop. Its `getItem` returns a Promise, which is never
+  `=== "1"` and parses to `NaN`, so every seen-gate read "unseen" forever: coachmark tours and
+  showcases replayed on every open, and a review gate configured with `minSessions` 0/1 could
+  RE-FIRE its native prompt each open (the 2026-07-16 one-star incident class). A thenable probe on
+  first read (`validateGateStorage`, WeakSet-cached so each adapter pays for exactly one probe) now
+  substitutes a closed adapter: every gate reads "seen", nothing shows, nothing fires, and a
+  once-per-process dev warning names the fix (pass a sync adapter, e.g. a 3-line MMKV wrapper).
+  Never-fire is the only direction a once-per-user gate may err in. A rejecting probe promise is
+  detached, so a broken native store cannot surface as an unhandled rejection.
+  - Canary: `test/canary/asyncGateStorage.test.tsx` (6 tests, proven red with the probe neutered —
+    including the sync CONTROL that stays green) + the new
+    `@wireai/activation:asyncGateStorageWarned` latch registered in `globalSlotDiscipline`.
+
+### Docs
+
+- **The "a `device_key` you passed is never overridden" line is now qualified everywhere it ships**,
+  on the ONBOARDING join-key path as it already was on the reviews path. The bar is the same on both
+  and it is `resolveIdentity` / `hasDeviceKey`: a string with at least one non-whitespace character.
+  `userContext` also accepts numbers and booleans, so a non-string or an all-whitespace `device_key`
+  was never a usable join key — it reads as absent and the auto key is merged over it, which the
+  unqualified sentence denied. Corrected in `AGENTS.md`, `README.md` (both the props table and the
+  join-key rules), and the shipped JSDoc in `src/types.ts` + `src/WireOnboarding.tsx`. No behaviour
+  change: the predicate is unchanged, only the sentence describing it.
+- `README.md`'s tarball install line named `@wireai/activation-0.1.3.tgz`, a file `npm pack` has
+  never produced under any version (it emits `wireai-activation-<version>.tgz`, scope flattened), so
+  an agent following it hit `ENOENT`. Fixed there and in the two Distribution mentions.
+
 ## [0.14.3] - 2026-08-18
 
 **PATCH: no public surface gained, lost or renamed a member.** `SpotlightOverlay`, `GestureHint`