@wildo-ai/saas-frontend-lib 1.1.4 → 1.1.5

package/dist/esm/core/guidance/GuidanceContext.js

@@ -11,7 +11,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * - Real-time sync via EventBus
  */
 import { createContext, useContext, useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { GuidanceFlowScope, GuidanceRenderMode, GUIDANCE_SCOPE_TO_RESOURCE, OnboardingTriggerType, OnboardingStatus, isTerminalOnboardingStatus, ProgressionScope, PROGRESSION_SCOPE_TO_RESOURCE, LifecycleStage, LifecycleScope, LIFECYCLE_SCOPE_TO_RESOURCE, GuidanceStateUtils, hasReachedStage as hasReachedStageUtil, MilestoneRewardType, CelebrationDisplayMode, CoreResourceOperation, ResourceOperationVariantType, ResourcesConfig_OperationPathUtils, } from '@wildo-ai/saas-models';
+import { CoreResourceType, GuidanceFlowScope, GuidanceRenderMode, GUIDANCE_SCOPE_TO_RESOURCE, OnboardingTriggerType, OnboardingStatus, isTerminalOnboardingStatus, ProgressionScope, PROGRESSION_SCOPE_TO_RESOURCE, LifecycleStage, LifecycleScope, LIFECYCLE_SCOPE_TO_RESOURCE, GuidanceStateUtils, hasReachedStage as hasReachedStageUtil, MilestoneRewardType, resolveCelebrationDisplayMode, CoreResourceOperation, GUIDANCE_SCOPE_TO_LIFECYCLE_SCOPE, GUIDANCE_SCOPE_TO_PROGRESSION_SCOPE, OnboardingElementType, ResourceOperationVariantType, ResourcesConfig_OperationPathUtils, } from '@wildo-ai/saas-models';
 import { compileResourceGuidance } from './guidance-resource-compiler.shared.utils.js';
 import { ApplicationContext } from '../../core/runtime/ApplicationContext.shared.js';
 import { useEventBus } from '../../core/events/useEventBus.js';
@@ -65,7 +65,9 @@ export const GUIDANCE_FALLBACK = {
     activeFlows: EMPTY_ACTIVE_FLOWS,
     flowStates: EMPTY_FLOW_STATES,
     activateFlow: () => { },
-    completeElement: () => { },
+    recordFlowPresented: () => { },
+    reportFlowNotPresentable: () => { },
+    completeElement: async () => { },
     completeFlow: () => { },
     dismissFlow: () => { },
     skipFlow: () => { },
@@ -87,48 +89,136 @@ function findApiCallOperation(registry, resourceType, operationId) {
         && (o.variantType === ResourceOperationVariantType.API_CALL
             || o.variantType === ResourceOperationVariantType.API_CALL_WITH_CALLBACK)) ?? null;
 }
+/**
+ * What a guidance-state read established — three outcomes that must never be collapsed.
+ *
+ * ## Why this vocabulary exists
+ *
+ * This read used to answer `GuidanceState | null`, which gave "the row is empty" and "I could
+ * not find out" the SAME value, `{ flows: {} }`. That is indistinguishable from a brand-new
+ * user, and it is load-bearing because {@link persistGuidanceState} writes the WHOLE document:
+ * so one transient network failure produced an in-memory empty state, the user's next dismissal
+ * built `nextScopeState` from it, and the write replaced their real onboarding history with a
+ * one-entry document. Silent, permanent data loss from a recoverable error.
+ *
+ * - `LOADED`     — the server answered; `state` is what it holds (possibly legitimately empty).
+ * - `ABSENT`     — the server answered NOT FOUND; no row exists yet, so one may be created.
+ *                  This is a POSITIVE answer and is why it is not folded into `UNAVAILABLE`.
+ * - `UNAVAILABLE`— the read failed for any other reason. Nothing is known about the stored
+ *                  document, so the scope must stay out of `scopedStates` and every write for
+ *                  it must be refused until a later read succeeds.
+ */
+var ScopedStateReadOutcome;
+(function (ScopedStateReadOutcome) {
+    ScopedStateReadOutcome["LOADED"] = "loaded";
+    ScopedStateReadOutcome["ABSENT"] = "absent";
+    ScopedStateReadOutcome["UNAVAILABLE"] = "unavailable";
+})(ScopedStateReadOutcome || (ScopedStateReadOutcome = {}));
+/** Resource + operation pairs already reported, so a missing door is named once per session. */
+const reportedMissingGuidanceOperations = new Set();
+/**
+ * Name a guidance door the resource registry does not expose.
+ *
+ * Every one of these three doors — READ, CREATE, UPDATE — answers `UNAVAILABLE` when its operation
+ * is absent, and `UNAVAILABLE` correctly suppresses writes for the scope. What was missing is the
+ * DISTINCTION an operator needs: a transient backend failure and a consumer registry that trims an
+ * operation produce the identical, permanent symptom — guidance that appears to work and records
+ * nothing — and only the second one is repaired by editing configuration rather than by waiting.
+ *
+ * Not reachable with the core resource configuration, where all three are `API_CALL` defaults. It
+ * is reachable by any consumer that narrows the operation set, and there the message is the only
+ * thing standing between the symptom and a day of debugging.
+ */
+function reportMissingGuidanceOperation(resourceType, operation) {
+    const key = `${resourceType}:${operation}`;
+    if (reportedMissingGuidanceOperations.has(key))
+        return;
+    reportedMissingGuidanceOperations.add(key);
+    LoggerFrontendService.getLogger().warn(`GuidanceContext: no default non-bulk API_CALL ${operation} operation is registered for `
+        + `"${resourceType}". Guidance for this scope cannot be persisted and every change will be `
+        + `local to the session. Register the operation, or stop declaring persistable flows for it.`);
+}
+/**
+ * The server's document with this session's own flows laid over it.
+ *
+ * ## Why a merge, and why this direction
+ *
+ * Two paths read a scope's stored document while the session may already hold local changes for it:
+ * initialization, and the recovery that follows a suppressed write. Both face the same collision and
+ * must resolve it the same way, which is why this is one function rather than two spreads.
+ *
+ * The SESSION wins per flow, because a local entry is a change the user just made and the server has
+ * not seen — `updateFlowState` commits locally before it decides whether to persist, precisely so the
+ * surface keeps behaving while a write is refused. The SERVER supplies every flow the session has not
+ * touched, which is the history a whole-document write would otherwise overwrite.
+ *
+ * ## The residual, stated rather than implied
+ *
+ * The merge is per FLOW, not per field within a flow. For the one flow a suppressed write touched,
+ * the local entry was built from `{ NOT_STARTED, elements: {}, triggerCount: 0 }` — `updateFlowState`
+ * has no stored copy to start from, that being the whole problem — so the server's `elements` and
+ * `triggerCount` for THAT flow are replaced rather than combined. The user's action wins, which is
+ * the right answer for the status it carries; what is lost is per-element progress on a flow the user
+ * has just dismissed or completed. Merging field-by-field would need a delta this path does not have.
+ */
+function mergeScopedStateOverLocal(serverState, localState) {
+    if (!localState)
+        return serverState;
+    return { ...serverState, flows: { ...serverState.flows, ...localState.flows } };
+}
 async function fetchGuidanceState(scope, doOperation, registry) {
     const resourceType = GUIDANCE_SCOPE_TO_RESOURCE[scope];
     const operation = findApiCallOperation(registry, resourceType, CoreResourceOperation.READ);
-    if (!operation)
-        return { flows: {} };
+    // No READ operation registered for this scope: the application cannot persist guidance here
+    // at all. UNAVAILABLE rather than an empty state, so nothing is ever written back either.
+    if (!operation) {
+        reportMissingGuidanceOperation(resourceType, CoreResourceOperation.READ);
+        return { outcome: ScopedStateReadOutcome.UNAVAILABLE };
+    }
     const operationPath = ResourcesConfig_OperationPathUtils.buildOperationPathKeyFromOperation(operation);
     try {
         const result = await doOperation(operationPath, { contextualParameters: {} }, { silent: true });
-        return result ?? { flows: {} };
+        return { outcome: ScopedStateReadOutcome.LOADED, state: result ?? { flows: {} } };
     }
     catch (err) {
         if (errorManagement.isNotFoundError(err))
-            return null;
-        return { flows: {} };
+            return { outcome: ScopedStateReadOutcome.ABSENT };
+        return { outcome: ScopedStateReadOutcome.UNAVAILABLE };
     }
 }
 async function createGuidanceState(scope, doOperation, registry) {
     const resourceType = GUIDANCE_SCOPE_TO_RESOURCE[scope];
     const operation = findApiCallOperation(registry, resourceType, CoreResourceOperation.CREATE);
-    if (!operation)
-        return { flows: {} };
+    // Same reasoning as the READ door: no CREATE operation means this scope is not persistable,
+    // which is not the same fact as "its document is empty".
+    if (!operation) {
+        reportMissingGuidanceOperation(resourceType, CoreResourceOperation.CREATE);
+        return { outcome: ScopedStateReadOutcome.UNAVAILABLE };
+    }
     const operationPath = ResourcesConfig_OperationPathUtils.buildOperationPathKeyFromOperation(operation);
     try {
         const result = await doOperation(operationPath, {
             contextualParameters: {},
             requestData: { flows: {} },
         }, { silent: true });
-        return result ?? { flows: {} };
+        return { outcome: ScopedStateReadOutcome.LOADED, state: result ?? { flows: {} } };
     }
     catch {
-        // M14: Another tab may have created it — retry read
-        const existingState = await fetchGuidanceState(scope, doOperation, registry);
-        if (existingState)
-            return existingState;
-        return { flows: {} };
+        // M14: Another tab may have created it — retry read. Whatever that read establishes is the
+        // answer, INCLUDING `UNAVAILABLE`: a failed create followed by a failed read tells us nothing
+        // about the stored document, and inventing an empty one here is the data-loss path this
+        // whole vocabulary exists to close.
+        return fetchGuidanceState(scope, doOperation, registry);
     }
 }
 async function persistGuidanceState(scope, state, doOperation, registry) {
     const resourceType = GUIDANCE_SCOPE_TO_RESOURCE[scope];
     const operation = findApiCallOperation(registry, resourceType, CoreResourceOperation.UPDATE);
-    if (!operation)
+    // The write door, and the quietest of the three: this one returned with no trace at all.
+    if (!operation) {
+        reportMissingGuidanceOperation(resourceType, CoreResourceOperation.UPDATE);
         return;
+    }
     const operationPath = ResourcesConfig_OperationPathUtils.buildOperationPathKeyFromOperation(operation);
     try {
         await doOperation(operationPath, { contextualParameters: {}, requestData: state });
@@ -137,20 +227,116 @@ async function persistGuidanceState(scope, state, doOperation, registry) {
         /* Best-effort persistence — ScopedResourceRegistryProvider injects scope params */
     }
 }
+// ─── Bound Survey Answers ───────────────────────────────────────
+/** Why a bound survey's answers could not be written. Carried to the renderer so it can say so. */
+export var SurveyBindingWriteOutcome;
+(function (SurveyBindingWriteOutcome) {
+    /** Every bound answer was written to the target resource. */
+    SurveyBindingWriteOutcome["WRITTEN"] = "written";
+    /** The survey binds nothing — there was no write to make, which is not a failure. */
+    SurveyBindingWriteOutcome["NOT_BOUND"] = "not_bound";
+    /** The target resource registers no default non-bulk API_CALL UPDATE this consumer can reach. */
+    SurveyBindingWriteOutcome["NO_OPERATION"] = "no_operation";
+    /** The write was attempted and refused. */
+    SurveyBindingWriteOutcome["REFUSED"] = "refused";
+})(SurveyBindingWriteOutcome || (SurveyBindingWriteOutcome = {}));
+/**
+ * Write a bound survey's answers to the resource it names (#1372).
+ *
+ * ## Why this runs BEFORE the element is recorded complete
+ *
+ * A survey that reports success while its answers went nowhere is the defect this capability was
+ * built to remove, one layer up: the person answered, the element went green, and the row stayed
+ * empty. So the write is the gate. `completeElement` awaits this and records nothing unless it
+ * answers `WRITTEN` or `NOT_BOUND`.
+ *
+ * ## The row is never addressed by id
+ *
+ * `ScopedResourceRegistryProvider` injects the scope parameters, exactly as it does for the
+ * guidance-state write beside this one. So the target is whichever row belongs to the current
+ * subject, and a binding cannot reach another subject's data by construction rather than by a check.
+ *
+ * ## Only answers with a declared field travel
+ *
+ * A question without `bindToField` stays telemetry on the guidance-state row. That keeps an
+ * unbound survey exactly as it was, and means a bound survey does not silently widen into sending
+ * every answer it happens to hold.
+ *
+ * v1 UPDATEs and does not create a missing row; a target with no row answers `REFUSED`, loudly,
+ * rather than appearing to succeed.
+ */
+async function writeBoundSurveyAnswers(element, answers, doOperation, registry) {
+    if (element.type !== OnboardingElementType.SURVEY)
+        return SurveyBindingWriteOutcome.NOT_BOUND;
+    const survey = element;
+    const resourceType = survey.bindTo?.resourceType;
+    if (!resourceType)
+        return SurveyBindingWriteOutcome.NOT_BOUND;
+    const requestData = {};
+    for (const question of survey.questions ?? []) {
+        if (!question.bindToField)
+            continue;
+        const answer = answers?.[question.id];
+        // An unanswered optional question writes nothing rather than nulling the field: the person
+        // declined to say, which is not the same as asking for the stored value to be cleared.
+        if (answer === undefined)
+            continue;
+        requestData[question.bindToField] = answer;
+    }
+    if (Object.keys(requestData).length === 0)
+        return SurveyBindingWriteOutcome.NOT_BOUND;
+    const operation = findApiCallOperation(registry, resourceType, CoreResourceOperation.UPDATE);
+    if (!operation) {
+        LoggerFrontendService.getLogger().warn(`GuidanceContext: survey "${element.ref}" binds to "${resourceType}", which registers no default `
+            + 'non-bulk API_CALL UPDATE operation. Its answers cannot be written, so the survey will not complete. '
+            + 'Register the operation, or remove the binding.', { elementRef: element.ref, resourceType });
+        return SurveyBindingWriteOutcome.NO_OPERATION;
+    }
+    const operationPath = ResourcesConfig_OperationPathUtils.buildOperationPathKeyFromOperation(operation);
+    try {
+        await doOperation(operationPath, { contextualParameters: {}, requestData });
+        return SurveyBindingWriteOutcome.WRITTEN;
+    }
+    catch (err) {
+        // NOT swallowed, unlike the guidance-state write beside it. That one is best-effort because
+        // losing it costs a re-shown banner; this one carries what the person typed.
+        LoggerFrontendService.getLogger().warn(`GuidanceContext: writing survey "${element.ref}" answers to "${resourceType}" was refused. `
+            + 'The survey has not been completed, so the person can retry.', { elementRef: element.ref, resourceType, fields: Object.keys(requestData), error: String(err) });
+        return SurveyBindingWriteOutcome.REFUSED;
+    }
+}
 async function fetchProgressionState(scope, doOperation, registry) {
     const resourceType = PROGRESSION_SCOPE_TO_RESOURCE[scope];
     const operation = findApiCallOperation(registry, resourceType, CoreResourceOperation.READ);
+    // No READ operation registered for this scope — this consumer cannot reach progression at all,
+    // which is not the same fact as "this user has achieved nothing" (#1069).
     if (!operation)
-        return null;
+        return { outcome: ScopedStateReadOutcome.UNAVAILABLE };
     const operationPath = ResourcesConfig_OperationPathUtils.buildOperationPathKeyFromOperation(operation);
     try {
         const result = await doOperation(operationPath, { contextualParameters: {} }, { silent: true });
-        return result ?? { milestonesAchieved: {}, operationCounts: {}, totalPoints: 0, valueMomentsAchieved: {}, categoriesProgress: {} };
+        return {
+            outcome: ScopedStateReadOutcome.LOADED,
+            state: result ?? { milestonesAchieved: {}, operationCounts: {}, totalPoints: 0, valueMomentsAchieved: {}, categoriesProgress: {} },
+        };
     }
     catch (err) {
         if (errorManagement.isNotFoundError(err))
-            return null;
-        return { milestonesAchieved: {}, operationCounts: {}, totalPoints: 0, valueMomentsAchieved: {}, categoriesProgress: {} };
+            return { outcome: ScopedStateReadOutcome.ABSENT };
+        /**
+         * The twin of the guidance read defect, and it was left behind when that one was fixed.
+         *
+         * A failed read used to answer a ZEROED progression state — `totalPoints: 0`, no milestones, no
+         * value moments — which is indistinguishable from a user who has genuinely achieved nothing. The
+         * milestone tracker then rendered a confident "0 points" and an empty achievement list on a
+         * transient network failure, telling the user their progress was gone.
+         *
+         * Unlike guidance this is NOT data loss: progression UPDATE is `INTERNAL_CALL`, so
+         * `findApiCallOperation` can never resolve a write and the frontend never persists this
+         * document. The damage is confined to what the user is shown — which is still a lie, and still
+         * the same collapse of "I could not find out" into "there is nothing".
+         */
+        return { outcome: ScopedStateReadOutcome.UNAVAILABLE };
     }
 }
 async function fetchMilestoneDefinitions(analyticsEnabled) {
@@ -169,24 +355,71 @@ const EMPTY_SCOPED_LIFECYCLE = {
     [LifecycleScope.USER]: null,
     [LifecycleScope.ORGANIZATION]: null,
 };
+/**
+ * The THIRD lane of the same distinction, and the one that was left behind twice.
+ *
+ * `ScopedStateReadResult`'s own docblock above says it is shared "so the next scoped-state reader
+ * inherits the distinction instead of re-deriving it" — and this reader is that next one. It
+ * collapsed a missing READ operation, a 404, a network failure and a 500 into a single `null`, and
+ * its caller turned that `null` into `createInitialLifecycleState()`: `currentStage: SIGNED_UP`,
+ * `stagesVisited: [SIGNED_UP]`, no criteria met.
+ *
+ * That is not a degraded answer, it is a confident wrong one. A user who reached ENGAGED months ago
+ * and whose lifecycle read hits one transient 502 was shown the onboarding activation checklist at
+ * 0 of N on their own home screen, and `hasReachedStage` answered false for every stage they had
+ * actually passed, for the whole session — with no re-read to recover it.
+ *
+ * ABSENT is the one case where the initial state is TRUTHFUL: no row means the subject really is at
+ * SIGNED_UP. UNAVAILABLE means nothing is known, so the scope stays out of `lifecycleScopedStates`
+ * and `currentStage` stays `null` — which `AppLayout_Home` already reads as "show the generic
+ * welcome" rather than as a stage.
+ */
 async function fetchLifecycleState(scope, doOperation, registry) {
     const resourceType = LIFECYCLE_SCOPE_TO_RESOURCE[scope];
     const operation = findApiCallOperation(registry, resourceType, CoreResourceOperation.READ);
+    // No READ operation registered: nothing can be known about this scope's stage, ever.
     if (!operation)
-        return null;
+        return { outcome: ScopedStateReadOutcome.UNAVAILABLE };
     const operationPath = ResourcesConfig_OperationPathUtils.buildOperationPathKeyFromOperation(operation);
     try {
         const result = await doOperation(operationPath, { contextualParameters: {} }, { silent: true });
-        return result ?? null;
+        // A 200 with no body is a row that does not exist yet — the same reading as a 404 below.
+        if (!result)
+            return { outcome: ScopedStateReadOutcome.ABSENT };
+        return { outcome: ScopedStateReadOutcome.LOADED, state: result };
     }
-    catch {
-        return null;
+    catch (err) {
+        if (errorManagement.isNotFoundError(err))
+            return { outcome: ScopedStateReadOutcome.ABSENT };
+        return { outcome: ScopedStateReadOutcome.UNAVAILABLE };
     }
 }
 // ─── Audience Evaluator ─────────────────────────────────────────
 // ─── Coexistence Enforcer ───────────────────────────────────────
-function enforceCoexistence(eligible) {
-    const sorted = [...eligible].sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
+/**
+ * A flow that renders NOTHING must not hold the single OVERLAY slot.
+ *
+ * This admits at most one OVERLAY flow, chosen by priority, with no visibility input — while the
+ * renderer skips a flow whose elements all resolve to nothing (a tooltip whose target never
+ * mounted, a tour with no steps, a checklist with no container). Such a flow therefore never
+ * reaches IN_PROGRESS, never reaches a terminal status, and stays in the active set for the
+ * session, so a higher-priority invisible flow permanently suppressed a lower-priority one that
+ * WOULD have rendered — and nothing logged it, because the renderer's missing-label warning is
+ * skipped by the same early return.
+ *
+ * `unpresentable` is reported by the renderer, which is the only party that knows. It DEPRIORITISES
+ * rather than excludes: a target that has not mounted yet is the ordinary case on first paint, and
+ * dropping the flow outright would lose it the moment its element appears. So an invisible flow
+ * still takes the slot when nothing else wants it, and yields the moment something else can use it.
+ */
+function enforceCoexistence(eligible, unpresentableFlowRefs = new Set()) {
+    const sorted = [...eligible].sort((a, b) => {
+        const aUnpresentable = unpresentableFlowRefs.has(a.ref) ? 1 : 0;
+        const bUnpresentable = unpresentableFlowRefs.has(b.ref) ? 1 : 0;
+        if (aUnpresentable !== bUnpresentable)
+            return aUnpresentable - bUnpresentable;
+        return (a.priority ?? 100) - (b.priority ?? 100);
+    });
     const result = [];
     let hasOverlay = false;
     let hasChecklist = false;
@@ -229,15 +462,25 @@ export const GuidanceContextProvider = ({ children }) => {
     // handles are listed directly in an init effect's dependency array, every such
     // identity change re-runs the effect MID-FETCH: the previous run's cleanup sets
     // `cancelled = true` (so its `if (cancelled) return` guard drops the in-flight
-    // commit), while the re-run immediately hits the `initRef` re-entry guard —
-    // which is only reset by the M9 scope-change effect, NOT by a handle-identity
-    // change — so no replacement fetch ever starts. The net effect is that the
-    // fetched guidance/progression state is silently never committed to state:
+    // commit), while the re-run immediately hits the `initRef` re-entry guard — so
+    // no replacement fetch ever starts. The net effect is that the fetched
+    // guidance/progression state is silently never committed to state:
     // `flowStates` stays empty, onboarding/guidance re-appear on every load, and
     // the next user action full-replaces the persisted document. Reading the
     // registry through this render-synced ref lets each init effect depend ONLY on
     // its genuine fetch inputs (the applicable scope set + the auth gate) while
     // still using the latest handle at call time.
+    //
+    // THE GATE ITSELF NOW RELEASES. This said the guard "is only reset by the M9
+    // scope-change effect, NOT by a handle-identity change" — sound as the contrast
+    // it was drawing (a SCOPE change resets; a handle-identity change does not), and
+    // already one short read literally, since the logout/user-switch reset cleared it
+    // too. Either way it is why the ref above was the whole remedy. Each init effect's
+    // own cleanup now clears its re-entry ref when the run did not COMMIT, so the
+    // cancel-then-blocked sequence cannot survive any re-run — which is what
+    // StrictMode's deliberate remount needed, and which makes this ref an optimisation
+    // (fewer wasted fetches) rather than the only thing standing between a boot and an
+    // empty `flowStates`.
     const resourceRegistryRef = useRef(resourceRegistry);
     resourceRegistryRef.current = resourceRegistry;
     const logger = useMemo(() => LoggerFrontendService.getLogger(), []);
@@ -333,6 +576,65 @@ export const GuidanceContextProvider = ({ children }) => {
     // ─── State ──────────────────────────────────────────────────
     const [scopedStates, setScopedStates] = useState({});
     const scopedStatesRef = useRef({});
+    /**
+     * Scopes whose stored guidance document this session has actually ESTABLISHED — read, or created
+     * after a positive 404.
+     *
+     * Tracked SEPARATELY from `scopedStates`, and the reason is the trap that makes this whole area
+     * hard. Presence in `scopedStates` looks like the same question and is not: `updateFlowState`
+     * COMMITS locally before it decides whether to persist, so the first suppressed interaction puts
+     * the scope into the map and every interaction after it reads as "loaded". A predicate over the
+     * map therefore suppresses exactly one write and then writes a one-entry document over the
+     * server's real history — the defect, one interaction later.
+     *
+     * It also supersedes an earlier `unreadableScopesRef`, which recorded only the scopes whose read
+     * FAILED. That set is empty during initialization and empty again for the whole re-read window
+     * after a scope or identity change, which is precisely when a websocket-driven update arrives
+     * carrying a scope straight off the wire. Recording what HAS been established, rather than what is
+     * known to have failed, answers the loading window and the failure with one fact.
+     */
+    /**
+     * False once the provider unmounts, so an in-flight recovery cannot commit into a dead session.
+     *
+     * RAISED in the effect body as well as lowered in its cleanup, and the raise is the load-bearing
+     * half. React StrictMode mounts, tears down and re-mounts effects on the SAME fiber, and a `useRef`
+     * object survives that — so a cleanup-only effect leaves this `false` for the provider's entire
+     * life after the first double-invoke. Every application scaffolded by this framework renders under
+     * `<React.StrictMode>` in development, so the guard would have refused every recovery in exactly
+     * the environment the recovery exists for, silently. This file already reasons about the same
+     * double-invoke for `initRef`.
+     */
+    const isMountedRef = useRef(true);
+    useEffect(() => {
+        isMountedRef.current = true;
+        return () => { isMountedRef.current = false; };
+    }, []);
+    const loadedScopesRef = useRef(new Set());
+    /**
+     * Whether the initialization read is in flight.
+     *
+     * `initRef` says initialization has STARTED and is never lowered until a reset, so it cannot tell
+     * "still reading" from "finished". The recovery path needs that distinction: a write suppressed
+     * during the loading window is the normal case, and firing a second read for a scope the init
+     * pass is already fetching would double every boot-time request for no gain.
+     */
+    const initInFlightRef = useRef(false);
+    /** Identifies the CURRENT initialization run — see where it is set for why a token is needed. */
+    const initRunTokenRef = useRef(null);
+    /**
+     * Which SCOPE SET / IDENTITY the current reads belong to.
+     *
+     * `isMountedRef` is not enough for anything that awaits: a tenant switch and a user switch do NOT
+     * unmount this provider, they run the two reset effects below. Those clear `loadedScopesRef` and
+     * `recoveringScopesRef`, but they cannot cancel a promise already in flight or invalidate what it
+     * resolves to — so a read issued for tenant A could land after the switch, mark the scope
+     * writable, and commit A's document as B's. The next interaction then persists it through the
+     * scoped registry, which injects B's parameters: A's guidance written into B's row.
+     *
+     * `initialize()` already carries `initRunTokenRef` for exactly this reason. This is the same
+     * discipline for every OTHER awaiting path, bumped wherever those refs are cleared.
+     */
+    const scopeGenerationRef = useRef(0);
     const [activeFlowRefs, setActiveFlowRefs] = useState(new Set());
     const [isLoading, setIsLoading] = useState(true);
     const initRef = useRef(false);
@@ -412,6 +714,16 @@ export const GuidanceContextProvider = ({ children }) => {
             progressionInitRef.current = false;
             lifecycleInitRef.current = false;
             pendingFeatureActivationRefsRef.current.clear();
+            // What a scope's read established belongs to the scope set that was in play. Carrying the
+            // suppression REPORT across would silence the warning for a newly applicable scope on the
+            // strength of a different one's failure, and carrying the in-flight marker across would
+            // block its first recovery attempt.
+            loadedScopesRef.current.clear();
+            initInFlightRef.current = false;
+            reportedSuppressedScopesRef.current.clear();
+            recoveringScopesRef.current.clear();
+            // Any read still in flight belongs to the previous scope set and must not land.
+            scopeGenerationRef.current += 1;
             prevScopesRef.current = applicableScopes;
             if (isAuthenticated && hasPersistableFlows) {
                 setIsLoading(true);
@@ -474,6 +786,14 @@ export const GuidanceContextProvider = ({ children }) => {
         progressionInitRef.current = false;
         lifecycleInitRef.current = false;
         pendingFeatureActivationRefsRef.current.clear();
+        // Same reasoning as the scope-change reset: an identity change starts over, and one user's
+        // failed read must not silence the next user's warning or block their first recovery read.
+        loadedScopesRef.current.clear();
+        initInFlightRef.current = false;
+        reportedSuppressedScopesRef.current.clear();
+        recoveringScopesRef.current.clear();
+        // Same reason as the scope-change reset: one identity's in-flight read must not land on the next.
+        scopeGenerationRef.current += 1;
         commitScopedStates({});
         setActiveFlowRefs(new Set());
         setProgressionScopedStates({ ...EMPTY_SCOPED_PROGRESSION });
@@ -508,6 +828,27 @@ export const GuidanceContextProvider = ({ children }) => {
         const userFeatures = featuresCtx?.resolvedFeatures?.features ?? [];
         const featureLimits = featuresCtx?.resolvedFeatures?.limits ?? {};
         const currentUsage = featuresCtx?.resolvedFeatures?.currentUsage ?? {};
+        /*
+         * Progression and lifecycle PER GUIDANCE SCOPE (#1373), so a flow asks about its own: a USER
+         * flow about the user's milestones and stage, an ORGANIZATION flow about the organization's.
+         *
+         * A scope whose document has not been read is OMITTED rather than given an empty entry, and the
+         * evaluator treats an absent scope as "nothing achieved, no stage". That direction is
+         * deliberate: a gated flow must stay hidden while nothing is known, not appear for the window
+         * before the documents land — which is exactly when a new subject is looking at the screen.
+         */
+        const scopedState = {};
+        for (const guidanceScope of [GuidanceFlowScope.USER, GuidanceFlowScope.ORGANIZATION]) {
+            const progression = progressionScopedStates[GUIDANCE_SCOPE_TO_PROGRESSION_SCOPE[guidanceScope]];
+            const lifecycle = lifecycleScopedStates[GUIDANCE_SCOPE_TO_LIFECYCLE_SCOPE[guidanceScope]];
+            if (!progression && !lifecycle)
+                continue;
+            scopedState[guidanceScope] = {
+                achievedMilestoneRefs: new Set(Object.keys(progression?.milestonesAchieved ?? {})),
+                currentLifecycleStage: lifecycle?.currentStage,
+                stagesReached: new Set(lifecycle?.stagesVisited ?? []),
+            };
+        }
         return {
             userRoles,
             userFeatures,
@@ -515,9 +856,16 @@ export const GuidanceContextProvider = ({ children }) => {
             currentUsage,
             completedFlowRefs: completedRefs,
             userCreatedAt: userOrgs.user?.createdAt ? new Date(userOrgs.user.createdAt) : undefined,
+            scopedState,
+            // Reads the SAME merged `flowStates` the completion set above is built from, so a criterion
+            // about an answer and a criterion about a completion can never disagree about which document
+            // they are looking at.
+            recordedSurveyAnswer: (flowRef, elementRef, questionId) => flowStates[flowRef]?.elements?.[elementRef]?.surveyAnswers?.[questionId],
         };
     }, [
         flowStates,
+        progressionScopedStates,
+        lifecycleScopedStates,
         userOrgs.permissions,
         appScope?.currentOrganizationId,
         userOrgs.user?.createdAt,
@@ -531,34 +879,116 @@ export const GuidanceContextProvider = ({ children }) => {
         if (initRef.current || !hasPersistableFlows || !isAuthenticated)
             return;
         initRef.current = true;
+        /**
+         * A token for THIS run, so a stale run's `finally` cannot lower a newer run's flag.
+         *
+         * On a scope or identity change the sequence is: cleanup lowers the flag, the new effect raises
+         * it, and only then does the OLD promise settle — whose `finally` would lower the flag the new
+         * run had just raised, re-enabling exactly the duplicate boot-time read it exists to prevent.
+         */
+        const runToken = Symbol('guidance-init');
+        initRunTokenRef.current = runToken;
+        initInFlightRef.current = true;
         let cancelled = false;
+        /**
+         * Whether this run got as far as COMMITTING. The cleanup releases the re-entry gate when it did
+         * not — see the cleanup for the sequence that made this necessary.
+         */
+        let committed = false;
         const initialize = async () => {
             // Read the latest registry handle at call time (see resourceRegistryRef).
             const registry = resourceRegistryRef.current;
             logDebug('Initializing guidance state', { scopes: applicableScopes, flowCount: persistenceRegistry.size });
             const stateResults = await Promise.allSettled(applicableScopes.map(async (scope) => {
-                let state = await fetchGuidanceState(scope, registry.doOperation, registry.registry);
-                if (state === null) {
+                let read = await fetchGuidanceState(scope, registry.doOperation, registry.registry);
+                if (read.outcome === ScopedStateReadOutcome.ABSENT) {
                     logDebug(`Auto-creating guidance state for scope ${scope}`);
-                    state = await createGuidanceState(scope, registry.doOperation, registry.registry);
+                    read = await createGuidanceState(scope, registry.doOperation, registry.registry);
                 }
-                return { scope, state };
+                return { scope, read };
             }));
             if (cancelled)
                 return;
             const newStates = {};
             for (const result of stateResults) {
-                if (result.status === 'fulfilled' && result.value.state) {
-                    newStates[result.value.scope] = result.value.state;
+                if (result.status !== 'fulfilled')
+                    continue;
+                const { scope, read } = result.value;
+                // A scope whose state could not be read is deliberately LEFT OUT of `scopedStates`
+                // rather than seeded with an empty document. `updateFlowState` refuses to persist a
+                // scope that is absent here, so an unreadable backend degrades to "guidance does not
+                // record anything this session" instead of overwriting what the server holds.
+                if (read.outcome !== ScopedStateReadOutcome.LOADED) {
+                    logDebug(`Guidance state unavailable for scope ${scope} — writes suppressed for this scope`);
+                    continue;
                 }
+                loadedScopesRef.current.add(scope);
+                newStates[scope] = read.state;
             }
-            // M7: Functional updater — merge with any concurrent WS updates
-            updateScopedStates(prev => ({ ...prev, ...newStates }));
+            /**
+             * Functional updater, merging PER FLOW — see {@link mergeScopedStateOverLocal}.
+             *
+             * The comment here said "merge with any concurrent WS updates" over a scope-level spread
+             * (`{ ...prev, ...newStates }`), which replaces a scope's whole document rather than merging
+             * it. Anything committed locally during the loading window — a dismissal the user made while
+             * this read was in flight, which `updateFlowState` deliberately commits and refuses to persist
+             * — was therefore dropped the moment the read landed. The claim named the behaviour the code
+             * did not have.
+             */
+            updateScopedStates(prev => {
+                const merged = { ...prev };
+                for (const [scope, state] of Object.entries(newStates)) {
+                    merged[scope] = mergeScopedStateOverLocal(state, prev[scope]);
+                }
+                return merged;
+            });
+            committed = true;
             setIsLoading(false);
             logDebug('Guidance state loaded', { scopeCount: Object.keys(newStates).length });
         };
-        initialize();
-        return () => { cancelled = true; };
+        // `finally`, so an initialization that THROWS does not leave the flag raised — which would
+        // disable the recovery path for the rest of the session, exactly when it is needed most.
+        /*
+         * A REJECTED initialization must not leave the lane latched.
+         *
+         * `committed` is only consulted by the CLEANUP, which runs on a dependency change or an
+         * unmount — neither of which happens because a promise rejected. So a throw left the re-entry
+         * ref raised and `isLoading` true for the rest of the session, and every consumer gated on
+         * that loading flag stayed inert: no flow could activate, and the tracker returned null
+         * forever. Two of the three lanes did not even attach a handler, so the rejection was also
+         * unhandled.
+         *
+         * The body's own try/catch covers the READS; what reaches here is everything outside them —
+         * a registry handle that is not what was assumed, a throw from a setState subscriber.
+         */
+        initialize().catch((error) => {
+            LoggerFrontendService.getLogger().warn('GuidanceContext: guidance initialization failed', { error });
+            initRef.current = false;
+            setIsLoading(false);
+        }).finally(() => {
+            if (initRunTokenRef.current === runToken)
+                initInFlightRef.current = false;
+        });
+        return () => {
+            cancelled = true;
+            /**
+             * RELEASE the re-entry gate when this run never committed, so a re-mount actually re-fetches.
+             *
+             * The comment on `resourceRegistryRef` above describes this exact sequence — cleanup sets
+             * `cancelled`, the re-run hits the `initRef` gate, "no replacement fetch ever starts… the
+             * fetched guidance state is silently never committed" — and closes it for ONE cause,
+             * dependency-identity churn, by keeping service handles out of the dependency array. React
+             * StrictMode is a SECOND cause of the same sequence, it is deliberate rather than accidental,
+             * and it happens on EVERY development mount: the skeleton template wraps every generated
+             * application in `<React.StrictMode>`, so `isLoading` never settled and no guidance flow ever
+             * triggered in dev. Releasing the gate here closes both causes at the gate itself, which makes
+             * the dependency hygiene above an optimisation rather than the only thing holding this up.
+             */
+            if (!committed)
+                initRef.current = false;
+            if (initRunTokenRef.current === runToken)
+                initInFlightRef.current = false;
+        };
         // Deps are the genuine fetch inputs ONLY: the applicable scope set + the
         // auth gate + the persistable-flows gate. Service handles (resourceRegistry)
         // are read via ref so their boot-time identity churn cannot cancel the
@@ -579,38 +1009,86 @@ export const GuidanceContextProvider = ({ children }) => {
             return;
         progressionInitRef.current = true;
         let cancelled = false;
+        // Released by the cleanup when this run never commits — see the guidance init effect above.
+        let committed = false;
         const initializeProgression = async () => {
             // Read the latest registry handle at call time (see resourceRegistryRef).
             const registry = resourceRegistryRef.current;
             logDebug('Initializing progression state', { scopes: progressionApplicableScopes });
             const [stateResults, definitions] = await Promise.all([
                 Promise.allSettled(progressionApplicableScopes.map(async (scope) => {
-                    const state = await fetchProgressionState(scope, registry.doOperation, registry.registry);
-                    return { scope, state };
+                    const read = await fetchProgressionState(scope, registry.doOperation, registry.registry);
+                    return { scope, read };
                 })),
-                fetchMilestoneDefinitions(analyticsEnabled),
+                // Reachability, not only configuration (#1069, the #268 rule): milestone definitions are served
+                // beside the progression store, which a consumer that excludes the resource does not serve.
+                fetchMilestoneDefinitions(analyticsEnabled && registry.hasResource(CoreResourceType.USER_PROGRESSION_STATE)),
             ]);
             if (cancelled)
                 return;
             const newStates = { ...EMPTY_SCOPED_PROGRESSION };
             for (const result of stateResults) {
-                if (result.status === 'fulfilled' && result.value.state) {
-                    newStates[result.value.scope] = result.value.state;
+                if (result.status !== 'fulfilled')
+                    continue;
+                const { scope, read } = result.value;
+                /**
+                 * A scope whose progression could not be READ is left `null`, not seeded with zeroes.
+                 *
+                 * `null` is what the tracker already treats as "no progression to show", so it renders
+                 * nothing — which is honest. A zeroed state renders "0 points" and an empty achievement
+                 * list, telling a user with a transient network failure that their progress is gone.
+                 *
+                 * ABSENT is folded in here too: unlike guidance there is no create-on-absent path, because
+                 * the row is seeded server-side by `onParentCreate` and the frontend cannot write this
+                 * document at all (progression UPDATE is `INTERNAL_CALL`).
+                 */
+                if (read.outcome !== ScopedStateReadOutcome.LOADED) {
+                    logDebug(`Progression state unavailable for scope ${scope} — showing nothing rather than zeroes`);
+                    continue;
                 }
+                newStates[scope] = read.state;
             }
-            // M7: Functional updater — merge with concurrent WS updates
+            /*
+             * A functional updater, and a SCOPE-LEVEL spread — which REPLACES each scope's document
+             * rather than merging within it. This comment used to say "merge with concurrent WS
+             * updates"; it was deleted from the guidance lane as false and survived here, over code
+             * that does the same thing. A WS event that landed during the loading window is overwritten
+             * by the document read before it, so the delta is lost until reload.
+             */
             setProgressionScopedStates(prev => ({ ...prev, ...newStates }));
             if (definitions.length > 0) {
                 setMilestoneDefinitions(definitions);
             }
+            committed = true;
             setProgressionIsLoading(false);
             logDebug('Progression state loaded', {
                 scopeCount: Object.values(newStates).filter(Boolean).length,
                 milestoneDefinitionCount: definitions.length,
             });
         };
-        initializeProgression();
-        return () => { cancelled = true; };
+        /*
+         * A REJECTED initialization must not leave the lane latched.
+         *
+         * `committed` is only consulted by the CLEANUP, which runs on a dependency change or an
+         * unmount — neither of which happens because a promise rejected. So a throw left the re-entry
+         * ref raised and `isLoading` true for the rest of the session, and every consumer gated on
+         * that loading flag stayed inert: no flow could activate, and the tracker returned null
+         * forever. Two of the three lanes did not even attach a handler, so the rejection was also
+         * unhandled.
+         *
+         * The body's own try/catch covers the READS; what reaches here is everything outside them —
+         * a registry handle that is not what was assumed, a throw from a setState subscriber.
+         */
+        initializeProgression().catch((error) => {
+            LoggerFrontendService.getLogger().warn('GuidanceContext: progression initialization failed', { error });
+            progressionInitRef.current = false;
+            setProgressionIsLoading(false);
+        });
+        return () => {
+            cancelled = true;
+            if (!committed)
+                progressionInitRef.current = false;
+        };
         // Genuine fetch inputs ONLY (scope set + analytics gate + auth gate).
         // resourceRegistry read via ref; appContext dropped (only its derived
         // `analyticsEnabled` boolean is used, and it is already a dep).
@@ -632,30 +1110,69 @@ export const GuidanceContextProvider = ({ children }) => {
         }
         lifecycleInitRef.current = true;
         let cancelled = false;
+        // Released by the cleanup when this run never commits — see the guidance init effect above.
+        let committed = false;
         const initializeLifecycle = async () => {
             // Read the latest registry handle at call time (see resourceRegistryRef).
             const registry = resourceRegistryRef.current;
             setLifecycleIsLoading(true);
             logDebug('Initializing lifecycle state', { scopes: lifecycleApplicableScopes });
             const stateResults = await Promise.allSettled(lifecycleApplicableScopes.map(async (scope) => {
-                const state = await fetchLifecycleState(scope, registry.doOperation, registry.registry);
-                return { scope, state: state ?? GuidanceStateUtils.createInitialLifecycleState() };
+                const read = await fetchLifecycleState(scope, registry.doOperation, registry.registry);
+                return { scope, read };
             }));
             if (cancelled)
                 return;
             const newStates = { ...EMPTY_SCOPED_LIFECYCLE };
             for (const result of stateResults) {
-                if (result.status === 'fulfilled' && result.value.state) {
-                    newStates[result.value.scope] = result.value.state;
-                }
+                if (result.status !== 'fulfilled')
+                    continue;
+                const { scope, read } = result.value;
+                /*
+                 * ABSENT is the only outcome that may materialize a default: no stored row means the
+                 * subject genuinely is at the first stage. UNAVAILABLE leaves the scope unset, so
+                 * `currentStage` stays null and nothing downstream states a stage nobody read.
+                 */
+                if (read.outcome === ScopedStateReadOutcome.LOADED)
+                    newStates[scope] = read.state;
+                else if (read.outcome === ScopedStateReadOutcome.ABSENT)
+                    newStates[scope] = GuidanceStateUtils.createInitialLifecycleState();
             }
-            // M7: Functional updater — merge with concurrent WS updates
+            /*
+             * A functional updater, and a SCOPE-LEVEL spread — which REPLACES each scope's document
+             * rather than merging within it. This comment used to say "merge with concurrent WS
+             * updates"; it was deleted from the guidance lane as false and survived here, over code
+             * that does the same thing. A WS event that landed during the loading window is overwritten
+             * by the document read before it, so the delta is lost until reload.
+             */
             setLifecycleScopedStates(prev => ({ ...prev, ...newStates }));
+            committed = true;
             setLifecycleIsLoading(false);
             logDebug('Lifecycle state loaded', { scopeCount: Object.values(newStates).filter(Boolean).length });
         };
-        initializeLifecycle();
-        return () => { cancelled = true; };
+        /*
+         * A REJECTED initialization must not leave the lane latched.
+         *
+         * `committed` is only consulted by the CLEANUP, which runs on a dependency change or an
+         * unmount — neither of which happens because a promise rejected. So a throw left the re-entry
+         * ref raised and `isLoading` true for the rest of the session, and every consumer gated on
+         * that loading flag stayed inert: no flow could activate, and the tracker returned null
+         * forever. Two of the three lanes did not even attach a handler, so the rejection was also
+         * unhandled.
+         *
+         * The body's own try/catch covers the READS; what reaches here is everything outside them —
+         * a registry handle that is not what was assumed, a throw from a setState subscriber.
+         */
+        initializeLifecycle().catch((error) => {
+            LoggerFrontendService.getLogger().warn('GuidanceContext: lifecycle initialization failed', { error });
+            lifecycleInitRef.current = false;
+            setLifecycleIsLoading(false);
+        });
+        return () => {
+            cancelled = true;
+            if (!committed)
+                lifecycleInitRef.current = false;
+        };
         // Genuine fetch inputs ONLY (scope set + lifecycle gate + auth gate).
         // resourceRegistry read via ref so boot-time identity churn cannot cancel
         // the in-flight fetch before it commits.
@@ -672,9 +1189,143 @@ export const GuidanceContextProvider = ({ children }) => {
     // H5: Compute the persisted state synchronously from the latest committed ref.
     // React may defer functional state updaters, so deriving persistence payloads
     // from inside `setState(...)` can skip writes entirely at runtime.
+    /**
+     * Scopes whose suppression has already been reported, so the warning below fires once per scope
+     * rather than once per interaction.
+     */
+    const reportedSuppressedScopesRef = useRef(new Set());
+    /** Scopes with a recovery read in flight, so concurrent interactions do not stack requests. */
+    const recoveringScopesRef = useRef(new Set());
+    /**
+     * Try again to establish a scope whose document this session never read.
+     *
+     * ## Why a retry exists at all
+     *
+     * Without one, a single transient failure at boot disabled guidance persistence for the rest of
+     * the session: `initRef` is only reset by a scope change or an identity change, so nothing re-read
+     * the scope, and every dismissal appeared to work while none of them stuck. The user's only remedy
+     * was to switch organization or sign out.
+     *
+     * ## Why it is demand-driven rather than timed
+     *
+     * It runs from the one place that proves the state is WANTED — a suppressed write — so there are
+     * no timers, no backoff policy to tune, and no requests on a surface nobody is using. The attempt
+     * rate is the interaction rate, and it is bounded by an in-flight guard rather than a counter,
+     * because "the user keeps trying" is exactly when trying again is correct.
+     *
+     * The write that triggered it is NOT replayed here. It does not need to be: the local commit has
+     * already happened, `persistGuidanceState` writes the WHOLE document, and the next interaction on
+     * a now-readable scope carries it.
+     */
+    /** Progression scopes whose recovery read is in flight, so an event storm asks once. */
+    const recoveringProgressionScopesRef = useRef(new Set());
+    /**
+     * Re-read a progression scope whose boot read failed, when an event for it arrives.
+     *
+     * The two progression websocket handlers DROP an event for a scope that reads `null`, and the
+     * comment there justified it with "initialization is still running and will land the
+     * authoritative document, which already contains this achievement". That is true of one of the
+     * two states `null` encodes and false of the other: a scope whose read FAILED is left `null`,
+     * `committed` is set regardless, and the init ref is never released — so for that scope
+     * initialization is permanently over, and every later event is dropped with nothing to land it.
+     * Progression has no `create-on-absent` path either, so unlike guidance there was no second door.
+     *
+     * The event that would have been dropped now asks for the document instead. Generation-guarded
+     * like the guidance recovery: a tenant switch does not unmount, so a read issued for the previous
+     * scope set must not land on the next one.
+     */
+    const recoverProgressionScope = useCallback(async (scope) => {
+        if (recoveringProgressionScopesRef.current.has(scope))
+            return;
+        recoveringProgressionScopesRef.current.add(scope);
+        const generation = scopeGenerationRef.current;
+        try {
+            const registry = resourceRegistryRef.current;
+            const read = await fetchProgressionState(scope, registry.doOperation, registry.registry);
+            if (read.outcome !== ScopedStateReadOutcome.LOADED)
+                return;
+            if (!isMountedRef.current)
+                return;
+            if (scopeGenerationRef.current !== generation)
+                return;
+            setProgressionScopedStates(prev => ({ ...prev, [scope]: read.state }));
+            logDebug(`Progression state for scope ${scope} recovered after a failed read`);
+        }
+        finally {
+            recoveringProgressionScopesRef.current.delete(scope);
+        }
+    }, [logDebug]);
+    const recoverScopedState = useCallback(async (scope) => {
+        if (loadedScopesRef.current.has(scope))
+            return;
+        // Initialization is already fetching this scope; its answer is the one to wait for.
+        if (initInFlightRef.current)
+            return;
+        if (recoveringScopesRef.current.has(scope))
+            return;
+        recoveringScopesRef.current.add(scope);
+        const generation = scopeGenerationRef.current;
+        try {
+            const registry = resourceRegistryRef.current;
+            let read = await fetchGuidanceState(scope, registry.doOperation, registry.registry);
+            if (read.outcome === ScopedStateReadOutcome.ABSENT) {
+                read = await createGuidanceState(scope, registry.doOperation, registry.registry);
+            }
+            if (read.outcome !== ScopedStateReadOutcome.LOADED)
+                return;
+            /**
+             * The provider may have unmounted while this read was in flight — `initialize()` one function
+             * above carries the same discipline through its own `cancelled` flag. Landing here would mark
+             * a scope established and commit a document into a session that has ended, which is the shape
+             * this whole area exists to refuse.
+             */
+            if (!isMountedRef.current)
+                return;
+            /*
+             * And the tenant/identity this read was issued FOR must still be the one in play. A switch
+             * does not unmount, so `isMountedRef` alone would let the previous tenant's document land as
+             * the current one's — and `mergeScopedStateOverLocal` makes the session win per flow, so a
+             * later correct read cannot undo it.
+             */
+            if (scopeGenerationRef.current !== generation)
+                return;
+            loadedScopesRef.current.add(scope);
+            LoggerFrontendService.getLogger().info(`GuidanceContext: guidance state for scope "${scope}" recovered — persistence resumes for this scope.`);
+            reportedSuppressedScopesRef.current.delete(scope);
+            /**
+             * MERGE the server's document under the session's, never discard either.
+             *
+             * The only caller is the suppressed branch of `updateFlowState`, and that branch COMMITS
+             * LOCALLY before it calls this — so by the time the read lands, this scope is always present
+             * in `scopedStates`. A `prev[scope] === undefined ? … : prev` guard is therefore always false
+             * in practice, and it threw the freshly-read server document away while
+             * `loadedScopesRef.add(scope)` above had already made the scope writable. The next interaction
+             * then wrote the session's one-entry document over the server's real history — the exact data
+             * loss this whole mechanism exists to close, arriving through its own repair path, with no
+             * concurrency needed: failed boot read, dismiss A, dismiss B.
+             *
+             * The resolution lives in {@link mergeScopedStateOverLocal}, which `initialize()` also uses —
+             * the two paths face the same collision and now genuinely resolve it the same way. They did
+             * not, and this said they did: `initialize()` was a scope-level spread that replaced the local
+             * document wholesale, which is the opposite direction and dropped anything committed during
+             * the loading window.
+             */
+            updateScopedStates(prev => ({ ...prev, [scope]: mergeScopedStateOverLocal(read.state, prev[scope]) }));
+        }
+        finally {
+            recoveringScopesRef.current.delete(scope);
+        }
+    }, [updateScopedStates]);
     const updateFlowState = useCallback((flowRef, updater, options) => {
         const currentScopedStates = scopedStatesRef.current;
         const scope = options?.scopeOverride ?? resolveFlowStateScope(flowRef, currentScopedStates);
+        /**
+         * Whether this scope's stored document was ever successfully READ (or created) this session.
+         *
+         * Read from {@link loadedScopesRef}, NOT from `scopedStates` — see that ref's own docblock for
+         * why the two are different questions and why the map cannot answer this one.
+         */
+        const scopeWasRead = loadedScopesRef.current.has(scope);
         const scopeState = currentScopedStates[scope] ?? { flows: {} };
         const currentFlowState = scopeState.flows[flowRef] ?? {
             status: OnboardingStatus.NOT_STARTED,
@@ -690,8 +1341,32 @@ export const GuidanceContextProvider = ({ children }) => {
             ...currentScopedStates,
             [scope]: nextScopeState,
         });
+        // `persistGuidanceState` writes the WHOLE document. Doing that for a scope whose stored
+        // document we never managed to READ would replace the server's real history with whatever
+        // this session happens to hold — which, having started from `{ flows: {} }` above, is one
+        // entry. The local commit above is kept so the surface still behaves for this session, and a
+        // later update on a scope that has since loaded carries the skipped change with it, because
+        // the whole document is what gets written; only THIS write leaves.
+        if (!scopeWasRead) {
+            /**
+             * WARN, not `logDebug`.
+             *
+             * This file disables its own debug channel (`setDebugTypeLogging('GuidanceContext', false)`),
+             * so the only record of a silently non-persisting session was written to a stream nobody
+             * turns on. Suppression is the thing an operator most needs to see: every dismissal appears
+             * to work and none of them sticks, and every request involved answers 200.
+             */
+            if (!reportedSuppressedScopesRef.current.has(scope)) {
+                reportedSuppressedScopesRef.current.add(scope);
+                LoggerFrontendService.getLogger().warn(`GuidanceContext: guidance persistence is SUPPRESSED for scope "${scope}" — its stored document `
+                    + `was never read this session, so writing would replace the server's history with this session's `
+                    + `single entry. Changes apply locally and are retried on the next interaction.`);
+            }
+            void recoverScopedState(scope);
+            return;
+        }
         void persistGuidanceState(scope, nextScopeState, resourceRegistry.doOperation, resourceRegistry.registry);
-    }, [commitScopedStates, resolveFlowStateScope, resourceRegistry]);
+    }, [commitScopedStates, resolveFlowStateScope, resourceRegistry, recoverScopedState]);
     // ─── Trigger Engine ─────────────────────────────────────────
     const tryActivateFlow = useCallback((flowRef) => {
         const flow = flowRegistry.get(flowRef);
@@ -710,15 +1385,76 @@ export const GuidanceContextProvider = ({ children }) => {
             return;
         if (state?.status === OnboardingStatus.IN_PROGRESS && activeFlowRefs.has(flowRef))
             return;
-        if (!evaluateGuidanceAudience(flow.audience, audienceContext))
+        if (!evaluateGuidanceAudience(flow.audience, audienceContext, flow.scope ?? GuidanceFlowScope.USER))
             return;
         logDebug(`Activating flow: ${flowRef}`);
+        /*
+         * ACTIVATION IS IN-MEMORY ONLY. It used to write IN_PROGRESS and increment
+         * `triggerCount` here, i.e. at the moment a trigger FIRED — before anything
+         * could know whether the flow's copy existed. A flow whose labels had not been
+         * generated yet then rendered an empty card and had already spent its
+         * once-per-user occasion: a FIRST_VISIT flow never fires again once
+         * `triggerCount > 0`, and nothing in the console, network tab or DOM said why
+         * (#539). The persisted transition, and the ACTIVATED event, now happen in
+         * `recordFlowPresented`, which the renderer calls once every required label of
+         * every element resolves.
+         */
         setActiveFlowRefs(prev => {
             const next = new Set(prev);
             next.add(flowRef);
             return next;
         });
-        // H3-1 + H3-2: Set IN_PROGRESS and increment triggerCount
+    }, [flowRegistry, flowStates, activeFlowRefs, audienceContext, flowScopeMap, applicableScopes, logDebug, featuresAreLoading]);
+    /*
+     * Flow refs whose CURRENT activation has already been recorded as presented.
+     * A ref, not state: the renderer calls in an effect that re-runs on every flow
+     * state change, and the guard must not itself cause a render. Pruned whenever a
+     * flow leaves the active set, so a later re-activation is a new occasion.
+     */
+    const presentedActivationRefsRef = useRef(new Set());
+    useEffect(() => {
+        for (const flowRef of presentedActivationRefsRef.current) {
+            if (!activeFlowRefs.has(flowRef))
+                presentedActivationRefsRef.current.delete(flowRef);
+        }
+        // Same pruning for the unpresentable set, so a later activation is judged afresh.
+        let unpresentableChanged = false;
+        for (const flowRef of unpresentableFlowRefsRef.current) {
+            if (!activeFlowRefs.has(flowRef)) {
+                unpresentableFlowRefsRef.current.delete(flowRef);
+                unpresentableChanged = true;
+            }
+        }
+        if (unpresentableChanged)
+            setUnpresentableFlowRefs(new Set(unpresentableFlowRefsRef.current));
+    }, [activeFlowRefs]);
+    /**
+     * Flows the renderer resolved to ZERO presented elements. Reported by the only party that can
+     * know, and pruned when the flow leaves the active set so a later activation starts clean.
+     */
+    const unpresentableFlowRefsRef = useRef(new Set());
+    const [unpresentableFlowRefs, setUnpresentableFlowRefs] = useState(new Set());
+    const reportFlowNotPresentable = useCallback((flowRef, notPresentable) => {
+        const held = unpresentableFlowRefsRef.current.has(flowRef);
+        if (held === notPresentable)
+            return;
+        if (notPresentable)
+            unpresentableFlowRefsRef.current.add(flowRef);
+        else
+            unpresentableFlowRefsRef.current.delete(flowRef);
+        setUnpresentableFlowRefs(new Set(unpresentableFlowRefsRef.current));
+    }, []);
+    const recordFlowPresented = useCallback((flowRef) => {
+        if (!activeFlowRefs.has(flowRef))
+            return;
+        if (presentedActivationRefsRef.current.has(flowRef))
+            return;
+        const flow = flowRegistry.get(flowRef);
+        if (!flow)
+            return;
+        presentedActivationRefsRef.current.add(flowRef);
+        // H3-1 + H3-2: Set IN_PROGRESS and increment triggerCount — once per activation
+        // that a person was actually shown.
         updateFlowState(flowRef, prev => ({
             ...prev,
             status: OnboardingStatus.IN_PROGRESS,
@@ -729,9 +1465,9 @@ export const GuidanceContextProvider = ({ children }) => {
             flowRef,
             renderMode: flow.renderMode,
             triggerSource: 'frontend',
-            scope,
+            scope: flowScopeMap[flowRef] ?? GuidanceFlowScope.USER,
         });
-    }, [flowRegistry, flowStates, activeFlowRefs, audienceContext, flowScopeMap, applicableScopes, emit, logDebug, updateFlowState, featuresAreLoading]);
+    }, [activeFlowRefs, flowRegistry, flowScopeMap, updateFlowState, emit]);
     // FIRST_VISIT trigger: run after each relevant state load boundary.
     useEffect(() => {
         if (guidanceIsLoading || featuresAreLoading || flowDefinitions.length === 0)
@@ -784,6 +1520,8 @@ export const GuidanceContextProvider = ({ children }) => {
             }
         });
     }, [guidanceIsLoading, routeFlowsCompiled, on, tryActivateFlow]);
+    /** Flow refs already reported as carrying an unqualified EVENT name, so the warning fires once. */
+    const warnedUnqualifiedEventFlowRefsRef = useRef(new Set());
     // EVENT trigger: subscribe to resource success events
     useEffect(() => {
         if (guidanceIsLoading || flowDefinitions.length === 0)
@@ -791,10 +1529,48 @@ export const GuidanceContextProvider = ({ children }) => {
         const eventFlows = flowDefinitions.filter(f => f.trigger.type === OnboardingTriggerType.EVENT && f.trigger.eventName);
         if (eventFlows.length === 0)
             return;
+        /**
+         * An UNQUALIFIED `eventName` can never match, and this is the only place that can say so.
+         *
+         * `OnboardingTriggerSchema.eventName` is a bare `z.string().optional()` — nothing checks the
+         * `<resourceType>:<operationIdentifier>` shape at authoring time — and the unqualified matching
+         * arm was removed from the loop below because it fired a flow on every resource's operation. The
+         * removal is right, and it silently moved a mis-authored flow from "fires everywhere" to "never
+         * fires, ever": both are wrong, and the second one produces no evidence at all.
+         *
+         * Warned once per flow ref per subscription, at the moment the subscription is built, so an
+         * author sees it on the first load of a surface carrying the flow rather than having to wait for
+         * an event that will never arrive.
+         */
+        for (const flow of eventFlows) {
+            const eventName = flow.trigger.eventName;
+            if (eventName.includes(':'))
+                continue;
+            if (warnedUnqualifiedEventFlowRefsRef.current.has(flow.ref))
+                continue;
+            warnedUnqualifiedEventFlowRefsRef.current.add(flow.ref);
+            LoggerFrontendService.getLogger().warn(`GuidanceContext: guidance flow "${flow.ref}" declares an EVENT trigger with the unqualified `
+                + `eventName "${eventName}". Event names are matched as "<resourceType>:<operationIdentifier>", `
+                + `so this flow can never fire. Qualify it with the resource it belongs to.`);
+        }
         return on(FrontendEvents.NOTIFY_RESOURCE_SUCCESS, (payload) => {
+            /**
+             * The event name is QUALIFIED by resource, and only the qualified form matches.
+             *
+             * There was a second arm here — `flow.trigger.eventName === payload.operationIdentifier` — an
+             * unqualified fallback on the bare operation. A flow authored with `eventName: 'CREATE'`
+             * therefore fired on EVERY resource's create: a todo-list onboarding banner triggered by
+             * creating an invoice. Nothing in the authoring surface suggested the name was global, and
+             * nothing reported the cross-resource activation.
+             *
+             * Removed rather than narrowed: the qualified form is what the authoring guidance documents
+             * (`${resourceType}:${operationIdentifier}`) and what Wonder Todos' own flow composes from the
+             * two enums, so the fallback served no declared shape — it only made a mis-authored name fire
+             * on the wrong resources instead of visibly not firing.
+             */
             const eventName = `${payload.resourceType}:${payload.operationIdentifier}`;
             for (const flow of eventFlows) {
-                if (flow.trigger.eventName === eventName || flow.trigger.eventName === payload.operationIdentifier) {
+                if (flow.trigger.eventName === eventName) {
                     tryActivateFlow(flow.ref);
                 }
             }
@@ -830,7 +1606,7 @@ export const GuidanceContextProvider = ({ children }) => {
     // ─── Active Flows (with coexistence enforcement) ────────────
     const activeFlows = useMemo(() => {
         const eligible = flowDefinitions.filter(f => activeFlowRefs.has(f.ref));
-        return enforceCoexistence(eligible);
+        return enforceCoexistence(eligible, unpresentableFlowRefs);
     }, [flowDefinitions, activeFlowRefs]);
     // ─── Public API ─────────────────────────────────────────────
     // H3-9: Guard activateFlow against pre-init — no-op while loading
@@ -839,7 +1615,59 @@ export const GuidanceContextProvider = ({ children }) => {
             return;
         tryActivateFlow(ref);
     }, [tryActivateFlow, guidanceIsLoading]);
-    const completeElement = useCallback((flowRef, elementRef, data) => {
+    /**
+     * The EFFECTS of a flow reaching COMPLETED, separated from the state write that causes it.
+     *
+     * They are separate because the write has two callers that must each make exactly ONE state
+     * update: `completeFlow` (the flow is completed on its own) and `completeElement` (the flow is
+     * completed BY its last element, in the same update that records that element).
+     *
+     * Why one update rather than two: `updateFlowState` fires a fire-and-forget PUT of the WHOLE
+     * document per call, so two calls in one tick race, and the loser is whichever response the
+     * server happens to write last. Measured live 2026-09-22 (#1481): completing the last element and
+     * then completing the flow issued two PUTs, the element-only one landed second, and the stored row
+     * read `status: "in-progress"` beside an element that said `"completed"` — the flow re-activated on
+     * the next trigger and asked its survey again.
+     */
+    const announceFlowCompleted = useCallback((flowRef) => {
+        setActiveFlowRefs(prev => {
+            const next = new Set(prev);
+            next.delete(flowRef);
+            return next;
+        });
+        // Flow-only event: onboarding views (no renderMode) persist silently.
+        const entry = persistenceRegistry.get(flowRef);
+        const scope = resolveFlowStateScope(flowRef);
+        if (entry?.renderMode) {
+            emit(FrontendEvents.GUIDANCE_FLOW_COMPLETED, {
+                flowRef,
+                renderMode: entry.renderMode,
+                triggerSource: 'frontend',
+                scope,
+            });
+        }
+        logDebug(`Flow completed: ${flowRef}`);
+    }, [persistenceRegistry, resolveFlowStateScope, emit, logDebug]);
+    const completeFlow = useCallback((flowRef) => {
+        // H3-6: Guard — unknown flow OR onboarding view no-op
+        if (!persistenceRegistry.has(flowRef))
+            return;
+        // H3-7: State transition validation — block only from a terminal state.
+        // A flow shown by a direct renderer (standalone OnboardingView) may still be
+        // NOT_STARTED/undefined when the user completes it (it is never routed through
+        // the trigger engine), so allow any non-terminal status to reach COMPLETED —
+        // mirrors dismiss/skip and keeps the four lifecycle guards aligned.
+        const currentState = flowStates[flowRef];
+        if (isTerminalOnboardingStatus(currentState?.status))
+            return;
+        updateFlowState(flowRef, (prev) => ({
+            ...prev,
+            status: OnboardingStatus.COMPLETED,
+            completedAt: new Date(),
+        }));
+        announceFlowCompleted(flowRef);
+    }, [updateFlowState, persistenceRegistry, flowStates, announceFlowCompleted]);
+    const completeElement = useCallback(async (flowRef, elementRef, data) => {
         // H3-6: Guard — unknown flow OR onboarding view no-op
         if (!persistenceRegistry.has(flowRef))
             return;
@@ -857,9 +1685,53 @@ export const GuidanceContextProvider = ({ children }) => {
             }
             validatedSurveyAnswers = sanitized;
         }
+        /*
+         * A bound survey writes its answers BEFORE anything is recorded (#1372).
+         *
+         * Ordering is the whole guarantee: if the target refuses, nothing is marked complete, so the
+         * person keeps the form they filled in and can retry. Recording first and writing after would
+         * reproduce the defect this binding exists to remove — a green element over an empty row.
+         *
+         * Every other element type, and every unbound survey, answers NOT_BOUND without a round trip,
+         * so this costs them nothing.
+         */
+        const completingElement = persistenceRegistry.get(flowRef)?.elements.find(e => e.ref === elementRef);
+        if (completingElement && !data?.declineResourceBinding) {
+            // Latest registry handle at call time, like the init effects (see resourceRegistryRef).
+            const resourceRegistryHandle = resourceRegistryRef.current;
+            const writeOutcome = await writeBoundSurveyAnswers(completingElement, validatedSurveyAnswers, resourceRegistryHandle.doOperation, resourceRegistryHandle.registry);
+            if (writeOutcome === SurveyBindingWriteOutcome.REFUSED
+                || writeOutcome === SurveyBindingWriteOutcome.NO_OPERATION) {
+                // The renderer surfaces this; the write helper has already said why in the log.
+                throw new Error(`guidance_survey_binding_write_failed:${writeOutcome}`);
+            }
+        }
+        const entry = persistenceRegistry.get(flowRef);
+        /*
+         * A flow whose every DECLARED element is finished is itself finished, and that transition is
+         * written in the SAME update that records the element — never in a second one.
+         *
+         * `completeFlow` had exactly ONE caller, `OnboardingView` (the standalone onboarding-view
+         * surface), so a flow rendered through the TRIGGER ENGINE never reached a terminal status. It
+         * stayed `IN_PROGRESS` for ever, stayed in the active set, and `GuidanceRenderer` re-rendered
+         * every element the flow declares on the next trigger, whatever their recorded state.
+         *
+         * Measured live 2026-09-22 on Wonder Todos (#1481): the bound display-name survey was ANSWERED
+         * (its answer written to `userProfiles.displayName`), then SKIPPED, then asked a THIRD time on
+         * the next `todos:update` — with an empty field, and answering again overwrote the profile.
+         *
+         * The declared set comes from the REGISTRY, never from the recorded state map, so the flow is
+         * complete only when nothing it declares is outstanding. The element being recorded right now
+         * counts as finished: `prev` cannot contain it yet.
+         */
+        const flowIsNowComplete = entry !== undefined && entry.elements.every(el => el.ref === elementRef
+            || flowStates[flowRef]?.elements?.[el.ref]?.status === OnboardingStatus.COMPLETED);
         updateFlowState(flowRef, (prev) => ({
             ...prev,
-            status: prev.status === OnboardingStatus.NOT_STARTED ? OnboardingStatus.IN_PROGRESS : prev.status,
+            status: flowIsNowComplete
+                ? OnboardingStatus.COMPLETED
+                : (prev.status === OnboardingStatus.NOT_STARTED ? OnboardingStatus.IN_PROGRESS : prev.status),
+            ...(flowIsNowComplete ? { completedAt: new Date() } : {}),
             elements: {
                 ...prev.elements,
                 [elementRef]: {
@@ -871,7 +1743,6 @@ export const GuidanceContextProvider = ({ children }) => {
             },
         }));
         // GUIDANCE_* events are flow-only: skip for onboarding views (no renderMode).
-        const entry = persistenceRegistry.get(flowRef);
         if (entry?.renderMode) {
             const element = entry.elements.find(e => e.ref === elementRef);
             if (element) {
@@ -883,42 +1754,10 @@ export const GuidanceContextProvider = ({ children }) => {
             }
         }
         logDebug(`Element completed: ${flowRef}/${elementRef}`);
-    }, [updateFlowState, persistenceRegistry, emit, logDebug]);
-    const completeFlow = useCallback((flowRef) => {
-        // H3-6: Guard — unknown flow OR onboarding view no-op
-        if (!persistenceRegistry.has(flowRef))
-            return;
-        // H3-7: State transition validation — block only from a terminal state.
-        // A flow shown by a direct renderer (standalone OnboardingView) may still be
-        // NOT_STARTED/undefined when the user completes it (it is never routed through
-        // the trigger engine), so allow any non-terminal status to reach COMPLETED —
-        // mirrors dismiss/skip and keeps the four lifecycle guards aligned.
-        const currentState = flowStates[flowRef];
-        if (isTerminalOnboardingStatus(currentState?.status))
-            return;
-        updateFlowState(flowRef, (prev) => ({
-            ...prev,
-            status: OnboardingStatus.COMPLETED,
-            completedAt: new Date(),
-        }));
-        setActiveFlowRefs(prev => {
-            const next = new Set(prev);
-            next.delete(flowRef);
-            return next;
-        });
-        // Flow-only event: onboarding views (no renderMode) persist silently.
-        const entry = persistenceRegistry.get(flowRef);
-        const scope = resolveFlowStateScope(flowRef);
-        if (entry?.renderMode) {
-            emit(FrontendEvents.GUIDANCE_FLOW_COMPLETED, {
-                flowRef,
-                renderMode: entry.renderMode,
-                triggerSource: 'frontend',
-                scope,
-            });
-        }
-        logDebug(`Flow completed: ${flowRef}`);
-    }, [updateFlowState, persistenceRegistry, flowStates, resolveFlowStateScope, emit, logDebug]);
+        // The state write above already carried the terminal status; only the effects remain.
+        if (flowIsNowComplete)
+            announceFlowCompleted(flowRef);
+    }, [updateFlowState, persistenceRegistry, emit, logDebug, announceFlowCompleted, flowStates]);
     const dismissFlow = useCallback((flowRef) => {
         // H3-6: Guard — unknown flow OR onboarding view no-op
         if (!persistenceRegistry.has(flowRef))
@@ -990,17 +1829,30 @@ export const GuidanceContextProvider = ({ children }) => {
         const unsubActivated = on(FrontendEvents.GUIDANCE_FLOW_ACTIVATED, (payload) => {
             if (payload.triggerSource === 'backend') {
                 logDebug(`Backend activated flow: ${payload.flowRef}`);
+                /*
+                 * IN-MEMORY ONLY, exactly like `activateFlow`.
+                 *
+                 * This wrote IN_PROGRESS and incremented `triggerCount` here — the precise thing #539
+                 * removed from the frontend trigger lane, left in place one handler over. Two consequences,
+                 * both reachable:
+                 *
+                 *  - DOUBLE COUNTING. `GuidanceRenderer` is mounted unconditionally and sees the flow in
+                 *    `activeFlows`, so it calls `recordFlowPresented`, whose guard passes (active, not yet
+                 *    presented) and increments a SECOND time, emitting a second ACTIVATED event with
+                 *    `triggerSource: 'frontend'`.
+                 *  - the #539 defect itself. Spending the occasion at ACTIVATION time is what let a flow
+                 *    whose labels had not been generated render raw keys and still be recorded as shown —
+                 *    a FIRST_VISIT flow never fires again once `triggerCount > 0`, and nothing said why.
+                 *
+                 * The persisted transition and the event belong to `recordFlowPresented`, which runs once
+                 * every required label of every element resolves. Where the flow came from does not change
+                 * when it was SEEN.
+                 */
                 setActiveFlowRefs(prev => {
                     const next = new Set(prev);
                     next.add(payload.flowRef);
                     return next;
                 });
-                updateFlowState(payload.flowRef, (prev) => ({
-                    ...prev,
-                    status: OnboardingStatus.IN_PROGRESS,
-                    startedAt: prev.startedAt ?? new Date(),
-                    triggerCount: (prev.triggerCount ?? 0) + 1,
-                }), { scopeOverride: payload.scope });
             }
         });
         const unsubCompleted = on(FrontendEvents.GUIDANCE_FLOW_COMPLETED, (payload) => {
@@ -1045,7 +1897,33 @@ export const GuidanceContextProvider = ({ children }) => {
             logDebug(`Milestone achieved: ${payload.milestoneRef} (scope: ${payload.scope})`);
             const scope = payload.scope;
             setProgressionScopedStates(prev => {
-                const current = prev[scope] ?? { milestonesAchieved: {}, operationCounts: {}, totalPoints: 0, categoriesProgress: {} };
+                const current = prev[scope];
+                /**
+                 * `null` means the scope's progression has not been read — the fetch failed, or it is
+                 * still in flight, which is exactly when a websocket event arrives. This event carries a
+                 * DELTA (one milestone, a category increment); applying it to a fabricated zeroed base
+                 * would publish a state that is wrong in every field the event does not mention, and
+                 * `null` is the one value the consumers treat as "not known" rather than "known to be
+                 * zero".
+                 *
+                 * Dropping the DELTA is right; leaving it at that was not. This said "initialization is
+                 * still running and will land the authoritative document", which is true of one of the two
+                 * states `null` encodes and false of the other. A scope whose read FAILED is also `null`,
+                 * `committed` is set regardless, and the init ref is never released — so for that scope
+                 * nothing is still running, and every later event was dropped with nothing to land it. Nor
+                 * is the in-flight case airtight: `Promise.allSettled` holds the commit until the SLOWEST
+                 * scope answers, so a document read before this event can land after it.
+                 *
+                 * So the event now ASKS for the document instead of only being discarded. The celebration
+                 * is emitted outside this updater and is unaffected either way.
+                 */
+                if (!current) {
+                    logDebug(`Milestone event for unread progression scope ${scope} — dropped rather than seeded`);
+                    // The celebration is emitted OUTSIDE this updater, so it is unaffected; what is lost is
+                    // the delta, which a re-read replaces with the authoritative document.
+                    void recoverProgressionScope(scope);
+                    return prev;
+                }
                 return {
                     ...prev,
                     [scope]: {
@@ -1081,12 +1959,10 @@ export const GuidanceContextProvider = ({ children }) => {
             }
             // C3: Trigger celebration overlay for celebration-type rewards
             if (payload.reward?.type === MilestoneRewardType.CELEBRATION && payload.reward?.celebrationLevel) {
-                const levelToMode = {
-                    low: CelebrationDisplayMode.CONFETTI,
-                    medium: CelebrationDisplayMode.OVERLAY,
-                    high: CelebrationDisplayMode.LOTTIE,
-                };
-                const mode = levelToMode[payload.reward.celebrationLevel] ?? CelebrationDisplayMode.CONFETTI;
+                // What the MILESTONE asked for, else what its level defaults to — the precedence is a
+                // named rule in saas-models, beside the vocabulary, rather than a `levelToMode` object
+                // literal here where an application could neither read it nor override it.
+                const mode = resolveCelebrationDisplayMode(payload.reward);
                 emit(FrontendEvents.NOTIFY_CUSTOM_SUCCESS, {
                     identifier: `milestone.${payload.milestoneRef}`,
                     data: {
@@ -1106,7 +1982,15 @@ export const GuidanceContextProvider = ({ children }) => {
         const unsubProgressionUpdate = on(FrontendEvents.PROGRESSION_UPDATED, (payload) => {
             const scope = payload.scope;
             setProgressionScopedStates(prev => {
-                const current = prev[scope] ?? { milestonesAchieved: {}, operationCounts: {}, totalPoints: 0, categoriesProgress: {} };
+                const current = prev[scope];
+                // Same reasoning as MILESTONE_ACHIEVED above: an unread scope is `null`, and seeding it
+                // from this event would assert `milestonesAchieved: {}` and `categoriesProgress: {}` —
+                // two fields this event says nothing about — as facts.
+                if (!current) {
+                    logDebug(`Progression update for unread progression scope ${scope} — dropped rather than seeded`);
+                    void recoverProgressionScope(scope);
+                    return prev;
+                }
                 return {
                     ...prev,
                     [scope]: {
@@ -1121,7 +2005,7 @@ export const GuidanceContextProvider = ({ children }) => {
             unsubMilestone();
             unsubProgressionUpdate();
         };
-    }, [on, logDebug, emit, featuresCtx]);
+    }, [on, logDebug, emit, featuresCtx, recoverProgressionScope]);
     // ─── Lifecycle WS Subscription (Phase 5) ────────────────────
     useEffect(() => {
         if (!lifecycleEnabled)
@@ -1256,6 +2140,8 @@ export const GuidanceContextProvider = ({ children }) => {
         activeFlows,
         flowStates,
         activateFlow,
+        recordFlowPresented,
+        reportFlowNotPresentable,
         completeElement,
         completeFlow,
         dismissFlow,
@@ -1270,6 +2156,7 @@ export const GuidanceContextProvider = ({ children }) => {
         activeFlows,
         flowStates,
         activateFlow,
+        recordFlowPresented,
         completeElement,
         completeFlow,
         dismissFlow,