@pie-players/pie-assessment-toolkit 0.3.74 → 1.0.0-beta.0

package/dist/services/ToolkitCoordinator.js

@@ -1,17 +1,25 @@
 /**
- * ToolkitCoordinator - Centralized Assessment Toolkit Service Management
+ * ToolkitCoordinator: one per assessment, the owner of every toolkit service
+ * (TTSService, ToolCoordinator, HighlightCoordinator, ElementToolStateStore,
+ * AccessibilityCatalogResolver, ToolProviderRegistry), the ToolPolicyEngine,
+ * the framework-error bus and the section controllers. It holds toolkit
+ * concerns only; navigation, timing and progress belong to the player.
  *
- * Orchestrates all toolkit services (TTS, tools, accessibility, state management) from a single entry point.
- * Provides centralized configuration for tool availability and settings.
- *
- * Key features:
- * - Owns all toolkit services (TTSService, ToolCoordinator, HighlightCoordinator, ElementToolStateStore, AccessibilityCatalogResolver)
- * - Single configuration point for tool availability and settings
- * - Sensible defaults for standalone usage
- * - Direct access for settings widgets (no player dependency)
- * - Clean separation: toolkit concerns only (NOT assessment state like navigation, timing, progress)
- *
- * Part of PIE Assessment Toolkit.
+ * Layout: the module's exported config, hook and event types come first, then
+ * the class, whose members run in this order:
+ * - config resolution and the constructor;
+ * - error, telemetry and tool-failure reporting, readiness listeners and the
+ *   framework-error bus;
+ * - element tool-state persistence;
+ * - tool registry adoption and provider registration;
+ * - section-event subscriptions, which follow the active cohort;
+ * - section controller creation, publication and disposal;
+ * - coordinator disposal;
+ * - TTS bring-up and readiness;
+ * - tool config updates and the policy engine surface, with the tool-context
+ *   resolvers split around it (installation before, queries after);
+ * - tool-open requests;
+ * - config-change application and TTS reconfiguration, last.
  */
 import { normalizeToolsConfig, } from "./tools-config-normalizer.js";
 import { collectToolConfigDiagnostics, normalizeToolConfigStrictness, reportToolConfigDiagnostics, } from "./tool-config-validation.js";
@@ -22,13 +30,13 @@ import { FrameworkErrorBus, } from "./framework-error-bus.js";
 import { HighlightCoordinator } from "./HighlightCoordinator.js";
 import { ToolCoordinator } from "./ToolCoordinator.js";
 import { TTSService } from "./TTSService.js";
-import { BrowserTTSProvider } from "./tts/browser-provider.js";
+import { BrowserTTSProvider, browserFallbackConfig, } from "./tts/browser-provider.js";
 import { buildRuntimeTTSConfig, resolveTTSBackend, resolveTTSRuntimeSettings, } from "./tts-runtime-config.js";
 import { ToolProviderRegistry } from "./tool-providers/index.js";
-import { resolveToolProviderId, ToolRegistry } from "./ToolRegistry.js";
+import { ToolRegistry } from "./ToolRegistry.js";
 import { ToolRequestRegistry } from "./tool-request.js";
 import { ToolPolicyEngine, } from "../policy/engine.js";
-import { resolveDefaultPnpEnforcement } from "../policy/internal.js";
+import { resolveSectionSessionAssignment } from "./section-session-assignment.js";
 class ToolkitCoordinatorDisposedError extends Error {
     constructor() {
         super("ToolkitCoordinator has been disposed.");
@@ -45,19 +53,22 @@ const isPlainRecord = (value) => !!value && typeof value === "object" && !Array.
 const mergeToolConfigUpdate = (toolId, current, updates) => {
     const next = { ...current, ...updates };
     if (toolId === "textToSpeech" &&
-        isPlainRecord(current.settings) &&
-        isPlainRecord(updates.settings)) {
-        next.settings = { ...current.settings, ...updates.settings };
-        if (isPlainRecord(current.settings.mathSpeech) &&
-            isPlainRecord(updates.settings.mathSpeech)) {
-            next.settings.mathSpeech = {
-                ...current.settings.mathSpeech,
-                ...updates.settings.mathSpeech,
-            };
-        }
+        isPlainRecord(current.mathSpeech) &&
+        isPlainRecord(updates.mathSpeech)) {
+        next.mathSpeech = { ...current.mathSpeech, ...updates.mathSpeech };
     }
     return next;
 };
+const TOOL_FAILURE_SUMMARY = {
+    "tool-module-load": "failed to load",
+    "tool-request-open": "failed to open on request",
+    "tool-request-host-check": "failed its toolbar's host check",
+    "tool-visibility": "failed its relevance check",
+    "tool-applicability": "failed its applicability check",
+    "tool-state-load": "failed to restore its state",
+    "tool-state-save": "failed to save its state",
+    "tool-playback": "failed during playback",
+};
 const SECTION_ITEM_EVENT_TYPES = [
     "item-selected",
     "item-session-data-changed",
@@ -81,7 +92,7 @@ const SECTION_SCOPED_EVENT_TYPES = [
  *
  * @example
  * ```typescript
- * // createPackagedToolRegistry is exported by @pie-players/pie-default-tool-loaders
+ * // Exported by @pie-players/pie-default-tool-loaders
  * const toolRegistry = createPackagedToolRegistry();
  *
  * // Create coordinator with configuration
@@ -91,7 +102,7 @@ const SECTION_SCOPED_EVENT_TYPES = [
  *   tools: {
  *     providers: {
  *       textToSpeech: { enabled: true, backend: 'browser' },
- *       answerEliminator: { enabled: true, strategy: 'strikethrough' }
+ *       answerEliminator: { enabled: true }
  *     },
  *     placement: {
  *       item: ['textToSpeech', 'answerEliminator']
@@ -123,25 +134,45 @@ export class ToolkitCoordinator {
     lazyInit;
     /** Track TTS initialization state */
     ttsInitialized = false;
+    /** Text-to-speech failed to start and policy does not grant it. */
+    ttsDegraded = false;
     ttsInitPromise;
     ttsReconfigurePromise;
-    stateLoaded = false;
+    /**
+     * The loader ran, whether or not it returned state. A failed load is
+     * reported once and the coordinator runs without saved tool state.
+     */
+    stateLoadSettled = false;
     stateLoadPromise;
     coordinatorReadyPromise;
     coordinatorReadyNotified = false;
     providerInitPromises = new Map();
+    /**
+     * Recoverable failures, by tool. A policy change that grants one of these
+     * tools reports its failure again as fatal.
+     */
+    degradedTools = new Map();
+    /** Tool failures already reported, by phase and tool, each reported once. */
+    reportedToolFailures = new Set();
+    readyChangeListeners = new Set();
+    eagerInit;
     toolRegistry;
     /** Whether the host passed `toolRegistry`, which then always stands. */
     toolRegistrySupplied;
     /**
      * Whether the registry is final: supplied at construction, or adopted from
-     * the toolkit this coordinator is bound to. Until then the empty placeholder
-     * reports no missing registry, since the toolkit will supply one.
+     * the toolkit this coordinator is bound to.
      */
     toolRegistrySettled;
+    /**
+     * Whether a bound toolkit reported having no registry. Until then, or until a
+     * registry settles, the empty placeholder reports no missing registry, since
+     * the toolkit may supply one.
+     */
+    toolRegistryAbsent = false;
     toolContextResolvers = new Map();
     toolContextResolverChangeListeners = new Set();
-    toolRequests = new ToolRequestRegistry();
+    toolRequests = new ToolRequestRegistry((toolId, phase, error) => this.reportToolFailure(toolId, phase, error));
     sectionControllers = new Map();
     sectionControllerKeys = new Map();
     sectionControllerInitEntries = new Map();
@@ -149,8 +180,8 @@ export class ToolkitCoordinator {
     sectionPersistenceStrategies = new Map();
     sectionControllerLifecycleListeners = new Set();
     /**
-     * Phase D: every active section-event subscription, indexed by
-     * listener identity. The listener follows the toolkit's active
+     * Every active section-event subscription, indexed by listener
+     * identity. The listener follows the toolkit's active
      * section cohort across transitions; this map is the registry the
      * coordinator iterates on every cohort change to detach the listener
      * from the outgoing controller, attach it to the new one, and replay
@@ -162,22 +193,26 @@ export class ToolkitCoordinator {
      */
     activeSubscriptions = new Map();
     /**
-     * Phase D: map key of the section controller currently treated as
-     * the *active cohort*. Set by `getOrCreateSectionController` (both
+     * Map key of the section controller currently treated as the
+     * *active cohort*. Set by `getOrCreateSectionController` (both
      * the create-new and resolve-existing paths) and cleared when the
-     * matching controller is disposed. `null` while no cohort exists,
-     * which is the only state where `subscribeSectionEvents` throws.
+     * matching controller is disposed, and `null` while the next requested
+     * cohort is still starting.
      */
     activeCohortMapKey = null;
     /**
      * Latest requested active cohort. Async controller initialization can
      * resolve out of order; only the most recent request may migrate active
      * subscriptions. Older completions still populate the controller cache.
+     * `null` until the first request, which is the only state where
+     * `subscribeSectionEvents` throws.
      */
     latestRequestedActiveCohortMapKey = null;
     telemetryListeners = new Set();
     frameworkErrorBus;
     ownsFrameworkErrorBus;
+    /** The instance behind {@link toolCoordinator}, kept for disposal. */
+    ownedToolCoordinator;
     frameworkErrorHookUnsubscribe = null;
     disposePromise = null;
     /**
@@ -188,32 +223,12 @@ export class ToolkitCoordinator {
      */
     policyEngine;
     /**
-     * Host-set override for PNP/profile enforcement. `null` (the default) means
-     * "auto" — the coordinator infers the effective mode from the
-     * PNP/profile policy inputs the bound `AssessmentEntity` and `AssessmentItemRef`
-     * actually carry (see {@link resolveEffectivePnpEnforcement}).
-     * `"on"` / `"off"` are explicit host opt-in / opt-out and stick
-     * across subsequent assessment / item swaps until the host clears
-     * the override by calling `setPnpEnforcement(null)`.
-     */
-    pnpEnforcementOverride = null;
-    /**
-     * Last assessment passed to {@link updateAssessment}. Read by
-     * {@link resolveEffectivePnpEnforcement} to compute auto-mode.
-     * The engine's own copy is the canonical record for decisions;
-     * this mirror exists only so the auto-mode helper does not need
-     * to round-trip through {@link policyEngine}'s frozen snapshot.
-     */
-    boundAssessment = null;
-    /**
-     * Last item reference passed to {@link updateCurrentItemRef}.
-     * Mirrored alongside {@link boundAssessment} so
-     * {@link resolveEffectivePnpEnforcement} can detect item-level
-     * profile policy inputs (`requiredTools` / `restrictedTools` /
-     * `toolParameters`) without round-tripping through the engine's
-     * frozen snapshot.
+     * Policy diagnostics reported since the last input change, keyed by code,
+     * tool id and, for `tool-policy.itemSettingNotApplied`, item id; see
+     * {@link warnPolicyDiagnostics}.
      */
-    boundCurrentItemRef = null;
+    reportedPolicyDiagnostics = new Map();
+    policyDiagnosticListeners = new Set();
     /**
      * Whether {@link decideFeaturePolicy} has already reported serving a decision
      * with no assessment bound.
@@ -227,7 +242,7 @@ export class ToolkitCoordinator {
     reportedUnboundFeaturePolicy = false;
     /**
      * Whether {@link _initializeTTS} has already reported a non-browser backend
-     * falling back to browser speech because no `tts` provider is registered.
+     * falling back to browser speech because no text-to-speech provider is registered.
      * Once per coordinator: a text-to-speech config change re-runs
      * initialization, and the missing provider is the same gap each time.
      */
@@ -292,7 +307,7 @@ export class ToolkitCoordinator {
      */
     validateToolsConfig(tools, options) {
         const { config, diagnostics } = collectToolConfigDiagnostics(tools, options.toolRegistry);
-        const unreported = this.reportedRegistryUnavailable || !this.toolRegistrySettled
+        const unreported = this.reportedRegistryUnavailable || this.toolRegistryPending()
             ? diagnostics.filter((entry) => entry.code !== "tools.registryUnavailable")
             : diagnostics;
         reportToolConfigDiagnostics(unreported, options);
@@ -313,9 +328,11 @@ export class ToolkitCoordinator {
         this.config = resolvedConfig;
         this.toolRegistry = resolvedConfig.toolRegistry ?? new ToolRegistry();
         this.installToolContextResolvers(resolvedConfig.toolContextResolvers);
-        this.hooks = resolvedConfig.hooks ?? {};
+        // The coordinator's own copy, so `setHooks` leaves the host's object as it
+        // passed it.
+        this.hooks = { ...resolvedConfig.hooks };
         this.lazyInit = config.lazyInit === true;
-        this.pnpEnforcementOverride = this.resolveConfiguredPnpEnforcement();
+        this.eagerInit = config.eagerInit ?? !this.lazyInit;
         // Use the host-provided framework-error bus if one was passed
         // (typical when embedded inside <pie-assessment-toolkit>, so
         // pre-coordinator failures from the CE flow through the same
@@ -324,44 +341,54 @@ export class ToolkitCoordinator {
             config.frameworkErrorBus ?? new FrameworkErrorBus();
         this.ownsFrameworkErrorBus = !config.frameworkErrorBus;
         this.subscribeFrameworkErrorHookAdapters();
-        // Initialize all services
-        this.toolCoordinator = new ToolCoordinator();
+        this.ownedToolCoordinator = new ToolCoordinator();
+        this.toolCoordinator = this.ownedToolCoordinator;
         this.highlightCoordinator = new HighlightCoordinator();
         this.elementToolStateStore = new ElementToolStateStore();
         this.catalogResolver = new AccessibilityCatalogResolver(resolvedConfig.accessibility?.catalogs || [], resolvedConfig.accessibility?.language || "en-US");
-        // Initialize tool provider registry
         this.toolProviderRegistry = new ToolProviderRegistry();
         this._registerToolProviders();
-        // Initialize TTS service based on config
         this.ttsService = new TTSService();
         // Selection read-aloud speaks through this service without the inline TTS
         // tool ever having run, so it cannot rely on that tool to attach highlights.
         this.ttsService.setHighlightCoordinator(this.highlightCoordinator);
+        // A caller that speaks without `ensureTTSReady()` first, such as selection
+        // read-aloud, starts the service instead of finding it uninitialized.
+        this.ttsService.setReadinessGate(() => this.ensureTTSReady());
+        this.ttsService.setMathSpeechSource(() => buildRuntimeTTSConfig(resolveTTSRuntimeSettings(this.resolveTTSToolConfig())).providerOptions?.mathSpeech);
         this.setupStatePersistenceHooks();
-        // M8 PR 2 — construct the unified ToolPolicyEngine seeded with
-        // the validated tools config. PNP/profile inputs (`assessment`,
-        // `currentItemRef`) start `null`; `pnpEnforcement` is resolved
-        // through {@link resolveEffectivePnpEnforcement}, which flips
-        // to `"on"` only once the bound assessment or item carries
-        // actual profile material. Hosts that only consume the
-        // engine for placement/policy gating get the pre-PR-2 behavior
-        // bit-for-bit.
+        // The unified ToolPolicyEngine, seeded with the validated tools config.
+        // The assessment starts `null` and items register their settings as they
+        // mount; auto-mode enforcement turns on only once the policy material a
+        // decision reads is present, so a host that consumes the engine for
+        // placement/policy gating alone sees no PNP/profile gate.
         this.policyEngine = new ToolPolicyEngine({
             toolRegistry: this.toolRegistry,
             contextId: `toolkit-coordinator:${this.assessmentId}`,
+            assessmentOptional: this.config.assessmentOptional === true,
             inputs: {
                 tools: this.config.tools,
                 assessment: null,
-                currentItemRef: null,
-                pnpEnforcement: this.resolveEffectivePnpEnforcement(),
+                pnpEnforcement: this.resolveConfiguredPnpEnforcement(),
             },
         });
-        if (!this.lazyInit) {
+        // Input diagnostics are computed once per change, so they are reported
+        // here rather than with each decision.
+        this.policyEngine.onPolicyChange((event) => {
+            if (event.reason === "disposed")
+                return;
+            if (event.reason === "inputs" || event.reason === "pnp-enforcement") {
+                this.reportedPolicyDiagnostics.clear();
+            }
+            this.warnPolicyDiagnostics(event.inputs.diagnostics);
+            this.reportNewlyGrantedFailures();
+        });
+        if (this.eagerInit) {
             void this.waitUntilReady().catch((err) => {
                 if (err instanceof ToolkitCoordinatorDisposedError)
                     return;
                 console.error("[ToolkitCoordinator] Failed eager initialization:", err);
-                this.handleError(err, { phase: "coordinator-ready" });
+                this.handleError(err, { phase: "coordinator-ready", recoverable: false });
             });
         }
     }
@@ -445,13 +472,108 @@ export class ToolkitCoordinator {
             }
         }
     }
-    handleError(error, context) {
+    /**
+     * Every report site states whether the coordinator carries on after the
+     * failure; one that takes down only its section passes that section.
+     */
+    handleError(error, context, cohort) {
         const model = frameworkErrorFromCoordinatorContext({
             error,
             context,
+            recoverable: context.recoverable,
+            scope: cohort ? "cohort" : "runtime",
+            cohort,
         });
         this.frameworkErrorBus.reportFrameworkError(model);
     }
+    /**
+     * Whether policy grants `toolId` as an accommodation on some surface: a
+     * test-administration override, a mounted item's or a district requirement,
+     * or profile support. A toolbar tool counts only surfaces where PNP
+     * enforcement is on; a region feature ignores enforcement, as its decisions
+     * do. Read without the unbound-assessment warning.
+     */
+    isToolGranted(toolId) {
+        try {
+            return this.policyEngine.grantsFeatureAnywhere(toolId, {
+                enforced: this.toolRegistry.getToolActivation(toolId) !== "region",
+            });
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Reports a tool's start failure: recoverable, so the tool reports itself
+     * unavailable and the assessment goes on, unless policy grants the tool.
+     * `fallbackFollows` marks a failure another path absorbs, which is recoverable
+     * whatever the policy.
+     */
+    reportStartFailure(error, context, toolIds, fallbackFollows = false) {
+        const ids = Array.from(toolIds);
+        const recoverable = fallbackFollows || !ids.some((toolId) => this.isToolGranted(toolId));
+        if (recoverable && !fallbackFollows) {
+            for (const toolId of ids)
+                this.degradedTools.set(toolId, { error, context });
+        }
+        this.handleError(error, { ...context, recoverable });
+    }
+    /**
+     * Report that a tool failed in `phase`. A module that failed to load follows
+     * the start-failure policy: the tool degrades, so toolbars withhold it, unless
+     * policy grants it. Every other phase is recoverable, since its report site
+     * keeps a recovery, and is reported on a microtask. Reported once per tool and
+     * phase however many toolbars or instances fail. A module failure re-announces the request targets, since
+     * the reporting toolbar no longer hosts the tool.
+     */
+    reportToolFailure(toolId, phase, error) {
+        if (phase === "tool-module-load")
+            this.toolRequests.notifyTargetsChange();
+        const key = `${phase}\u0000${toolId}`;
+        if (this.reportedToolFailures.has(key))
+            return;
+        this.reportedToolFailures.add(key);
+        const detail = error instanceof Error && error.message.trim().length > 0
+            ? error.message
+            : String(error);
+        const report = () => this.reportStartFailure(new Error(`Tool "${toolId}" ${TOOL_FAILURE_SUMMARY[phase]}: ${detail}`, {
+            cause: error,
+        }), { phase, details: { toolId } }, [toolId], phase !== "tool-module-load");
+        // The recoverable phases fail inside a toolbar's derived state, where a
+        // listener writing state would throw.
+        if (phase === "tool-module-load")
+            report();
+        else
+            queueMicrotask(report);
+    }
+    reportNewlyGrantedFailures() {
+        for (const [toolId, failure] of this.degradedTools) {
+            if (!this.isToolGranted(toolId))
+                continue;
+            this.degradedTools.delete(toolId);
+            this.handleError(failure.error, { ...failure.context, recoverable: false });
+        }
+    }
+    /**
+     * Subscribe to changes of {@link isReady}: state loading, text-to-speech
+     * starting, failing or reconfiguring. The listener reads the status itself.
+     */
+    onReadyChange(listener) {
+        this.readyChangeListeners.add(listener);
+        return () => {
+            this.readyChangeListeners.delete(listener);
+        };
+    }
+    notifyReadyChange() {
+        for (const listener of this.readyChangeListeners) {
+            try {
+                listener();
+            }
+            catch (error) {
+                console.warn("[ToolkitCoordinator] ready-change listener failed:", error);
+            }
+        }
+    }
     /**
      * Subscribe to framework-error events emitted by this coordinator.
      *
@@ -481,6 +603,13 @@ export class ToolkitCoordinator {
     reportFrameworkError(model) {
         this.frameworkErrorBus.reportFrameworkError(model);
     }
+    sectionControllerKey(args) {
+        return {
+            assessmentId: this.assessmentId,
+            sectionId: args.sectionId,
+            attemptId: args.attemptId,
+        };
+    }
     getSectionControllerMapKey(key) {
         return `${key.assessmentId}::${key.sectionId}::${key.attemptId || ""}`;
     }
@@ -495,15 +624,20 @@ export class ToolkitCoordinator {
                 return null;
             }
         })();
+        // Stored per attempt. Without an attempt id nothing tells two learners on
+        // one device apart, so the section is neither read nor written.
         const getStorageKey = (context) => {
             const { assessmentId, sectionId, attemptId } = context.key;
-            return `pie:section-controller:v1:${assessmentId}:${sectionId}:${attemptId || "default"}`;
+            if (!attemptId)
+                return null;
+            return `pie:section-controller:v1:${assessmentId}:${sectionId}:${attemptId}`;
         };
         return {
             async loadSession(context) {
-                if (!storage)
+                const key = getStorageKey(context);
+                if (!storage || !key)
                     return null;
-                const value = storage.getItem(getStorageKey(context));
+                const value = storage.getItem(key);
                 if (!value)
                     return null;
                 try {
@@ -514,14 +648,16 @@ export class ToolkitCoordinator {
                 }
             },
             async saveSession(context, session) {
-                if (!storage)
+                const key = getStorageKey(context);
+                if (!storage || !key)
                     return;
-                storage.setItem(getStorageKey(context), JSON.stringify(session));
+                storage.setItem(key, JSON.stringify(session));
             },
             async clearSession(context) {
-                if (!storage)
+                const key = getStorageKey(context);
+                if (!storage || !key)
                     return;
-                storage.removeItem(getStorageKey(context));
+                storage.removeItem(key);
             },
         };
     }
@@ -543,12 +679,12 @@ export class ToolkitCoordinator {
             if (!this.hooks.saveToolState)
                 return;
             void Promise.resolve(this.hooks.saveToolState(state)).catch((err) => {
-                this.handleError(err, { phase: "state-save" });
+                this.handleError(err, { phase: "state-save", recoverable: true });
             });
         });
     }
     async ensureStateLoaded() {
-        if (this.stateLoaded)
+        if (this.stateLoadSettled)
             return;
         if (this.stateLoadPromise)
             return this.stateLoadPromise;
@@ -563,7 +699,7 @@ export class ToolkitCoordinator {
                 if (state && typeof state === "object") {
                     this.elementToolStateStore.loadState(state);
                 }
-                this.stateLoaded = true;
+                this.stateLoadSettled = true;
                 await this.emitTelemetry("pie-toolkit-tool-state-loaded", {
                     hasState: Boolean(state),
                 });
@@ -571,43 +707,52 @@ export class ToolkitCoordinator {
             catch (err) {
                 if (err instanceof ToolkitCoordinatorDisposedError)
                     throw err;
-                this.handleError(err, { phase: "state-load" });
+                this.stateLoadSettled = true;
+                this.handleError(err, { phase: "state-load", recoverable: true });
             }
         })().finally(() => {
             this.stateLoadPromise = undefined;
+            this.notifyReadyChange();
         });
         return this.stateLoadPromise;
     }
+    /** Whether the toolkit this coordinator binds to may still supply a registry. */
+    toolRegistryPending() {
+        return !this.toolRegistrySettled && !this.toolRegistryAbsent;
+    }
     reportMissingTTSProvider(backend) {
         // The toolkit this coordinator binds to may still supply the provider.
-        if (!this.toolRegistrySettled) {
+        if (this.toolRegistryPending()) {
             this.heldMissingTTSProviderBackend = backend;
             return;
         }
         if (this.reportedMissingTTSProvider)
             return;
         this.reportedMissingTTSProvider = true;
-        console.warn(`[ToolkitCoordinator] Text-to-speech is configured for the "${backend}" backend but falls back to browser speech: no "tts" tool provider is registered. A coordinator registers tool providers only from its \`toolRegistry\`, or from its toolkit's when constructed without one, so supply one that carries the text-to-speech registration — for the packaged capability set, \`createPackagedToolRegistry()\` from "@pie-players/pie-default-tool-loaders". Reported once per coordinator.`);
+        console.warn(`[ToolkitCoordinator] Text-to-speech is configured for the "${backend}" backend but falls back to browser speech: no "textToSpeech" tool provider is registered. A coordinator registers tool providers only from its \`toolRegistry\`, or from its toolkit's when constructed without one, so supply one that carries the text-to-speech registration — for the packaged capability set, \`createPackagedToolRegistry()\` from "@pie-players/pie-default-tool-loaders". Reported once per coordinator.`);
     }
     /**
      * Take the registry of the toolkit this coordinator is bound to, when the host
      * constructed it without one: the config is validated against it, its
      * providers register, and text-to-speech re-initializes through it if it
-     * already started. The toolkit elements call this on binding. A registry
-     * passed at construction stands, and the first call wins; `null` records a
-     * toolkit without one, which reports the registry as missing.
+     * already started. The toolkit elements call this on binding, and again when
+     * their registry changes. A registry passed at construction stands, and the
+     * first registry adopted wins; `null` records a toolkit without one, which
+     * reports the registry as missing and still adopts one that arrives later.
      *
      * @returns Whether `registry` was adopted.
      */
     adoptToolRegistry(registry) {
         if (this.disposePromise !== null || this.toolRegistrySettled)
             return false;
-        this.toolRegistrySettled = true;
+        if (!registry && this.toolRegistryAbsent)
+            return false;
         const heldBackend = this.heldMissingTTSProviderBackend;
         this.heldMissingTTSProviderBackend = null;
         const strictness = this.config.toolConfigStrictness ?? "error";
         const source = "ToolkitCoordinator.adoptToolRegistry";
         if (!registry) {
+            this.toolRegistryAbsent = true;
             this.validateToolsConfig(this.config.tools, {
                 strictness,
                 source,
@@ -617,6 +762,7 @@ export class ToolkitCoordinator {
                 this.reportMissingTTSProvider(heldBackend);
             return false;
         }
+        this.toolRegistrySettled = true;
         this.toolRegistry = registry;
         this.config.toolRegistry = registry;
         try {
@@ -644,9 +790,6 @@ export class ToolkitCoordinator {
             this.scheduleTTSReconfigure();
         return true;
     }
-    /**
-     * Register tool providers in the registry
-     */
     _registerToolProviders() {
         const descriptorTools = this.getProviderDescriptorTools();
         for (const tool of descriptorTools) {
@@ -658,35 +801,32 @@ export class ToolkitCoordinator {
     }
     /**
      * Register the provider `tool`'s descriptor creates for the tool's current
-     * config, unless the tool is disabled or that provider id is registered. A
-     * descriptor that throws is reported the way a failed registration is.
+     * config under the tool's id, unless the tool is disabled or, without
+     * `replace`, a provider is registered under that id. A descriptor that throws
+     * is reported the way a failed registration is.
      */
-    async registerProviderFromTool(tool) {
+    async registerProviderFromTool(tool, replace = false) {
         const descriptor = tool.provider;
         if (!descriptor)
             return;
-        let providerId = null;
+        const { toolId } = tool;
         let registration;
         try {
-            const toolConfig = this.getToolConfig(tool.toolId) || undefined;
-            if (toolConfig?.enabled === false)
+            const toolConfig = this.getToolConfig(toolId) || undefined;
+            if (toolConfig?.enabled === false) {
+                // A disabled tool keeps no provider, including the one it replaces.
+                if (replace)
+                    void this.toolProviderRegistry.unregister(toolId);
                 return;
-            providerId = resolveToolProviderId(tool, toolConfig);
-            if (!providerId || this.toolProviderRegistry.has(providerId))
+            }
+            if (!replace && this.toolProviderRegistry.has(toolId))
                 return;
             const provider = descriptor.createProvider(toolConfig);
             const initConfig = descriptor.getInitConfig?.(toolConfig) ??
                 toolConfig?.provider?.init ??
                 {};
-            const initConfigWithTelemetry = this.addToolTelemetryReporter({
-                toolId: tool.toolId,
-                providerId,
-                initConfig,
-            });
-            const registryTelemetry = this.createToolTelemetryForwarder({
-                toolId: tool.toolId,
-                providerId,
-            });
+            const initConfigWithTelemetry = this.addToolTelemetryReporter(toolId, initConfig);
+            const registryTelemetry = this.createToolTelemetryForwarder(toolId);
             const authFetcher = descriptor.getAuthFetcher?.(toolConfig) ??
                 toolConfig?.provider?.runtime?.authFetcher;
             registration = {
@@ -698,31 +838,24 @@ export class ToolkitCoordinator {
             };
         }
         catch (err) {
-            this.reportProviderRegisterFailure(err, providerId, tool.toolId);
+            this.reportProviderRegisterFailure(err, toolId);
             return;
         }
-        await this.registerProvider(providerId, registration);
+        await this.registerProvider(toolId, registration);
     }
-    createToolTelemetryForwarder(args) {
+    createToolTelemetryForwarder(toolId) {
         return async (eventName, payload) => {
-            await this.emitTelemetry(eventName, {
-                ...(payload || {}),
-                toolId: args.toolId,
-                providerId: args.providerId,
-            });
+            await this.emitTelemetry(eventName, { ...(payload || {}), toolId });
         };
     }
-    addToolTelemetryReporter(args) {
-        const configObject = args.initConfig && typeof args.initConfig === "object"
-            ? { ...args.initConfig }
+    addToolTelemetryReporter(toolId, initConfig) {
+        const configObject = initConfig && typeof initConfig === "object"
+            ? { ...initConfig }
             : {};
         const existingReporter = typeof configObject.onTelemetry === "function"
             ? configObject.onTelemetry
             : null;
-        const forwardTelemetry = this.createToolTelemetryForwarder({
-            toolId: args.toolId,
-            providerId: args.providerId,
-        });
+        const forwardTelemetry = this.createToolTelemetryForwarder(toolId);
         configObject.onTelemetry = async (eventName, payload) => {
             if (existingReporter) {
                 await existingReporter(eventName, payload);
@@ -731,56 +864,58 @@ export class ToolkitCoordinator {
         };
         return configObject;
     }
-    async registerProvider(providerId, config) {
+    async registerProvider(toolId, config) {
         try {
-            this.toolProviderRegistry.register(providerId, config);
+            this.toolProviderRegistry.register(toolId, config);
             const meta = {
-                providerId,
                 providerName: config.provider.providerName,
             };
-            await this.hooks.onProviderRegistered?.(providerId, meta);
+            await this.hooks.onProviderRegistered?.(toolId, meta);
             await this.emitTelemetry("pie-toolkit-provider-registered", {
-                providerId,
+                toolId,
                 providerName: config.provider.providerName,
             });
         }
         catch (err) {
-            this.reportProviderRegisterFailure(err, providerId);
+            this.reportProviderRegisterFailure(err, toolId);
         }
     }
     /**
-     * A console warning and a `provider-register` framework error. `providerId`
-     * is null when resolving it is what failed; the warning names the tool then.
+     * A console warning and a `provider-register` framework error, under the
+     * start-failure policy every other tool failure follows.
      */
-    reportProviderRegisterFailure(err, providerId, toolId) {
-        console.warn(providerId
-            ? `[ToolkitCoordinator] Failed to register provider "${providerId}":`
-            : `[ToolkitCoordinator] Failed to register the provider of tool "${toolId}":`, err);
-        this.handleError(err, {
-            phase: "provider-register",
-            providerId: providerId ?? undefined,
-        });
+    reportProviderRegisterFailure(err, toolId) {
+        console.warn(`[ToolkitCoordinator] Failed to register the provider of tool "${toolId}":`, err);
+        this.reportStartFailure(err, { phase: "provider-register", toolId }, [toolId]);
+    }
+    async ensureProviderReady(toolId) {
+        return this.initializeProvider(toolId, false);
     }
-    async ensureProviderReady(providerId) {
+    /** `fallbackFollows`: the caller recovers from a failure on its own. */
+    async initializeProvider(toolId, fallbackFollows) {
         this.assertNotDisposed();
-        const existing = this.providerInitPromises.get(providerId);
+        const existing = this.providerInitPromises.get(toolId);
         if (existing)
             return existing;
         const promise = (async () => {
-            const provider = await this.toolProviderRegistry.getProvider(providerId, false);
-            this.assertNotDisposed();
-            const meta = {
-                providerId,
-                providerName: provider.providerName,
-            };
             try {
-                await this.hooks.onProviderInitStart?.(providerId, meta);
+                let provider = await this.toolProviderRegistry.getProvider(toolId, false);
+                this.assertNotDisposed();
+                // A tool asks each time it opens; the lifecycle hooks report the start once.
+                if (this.toolProviderRegistry.isInitialized(toolId))
+                    return provider;
+                const meta = {
+                    providerName: provider.providerName,
+                };
+                await this.hooks.onProviderInitStart?.(toolId, meta);
                 this.assertNotDisposed();
-                await this.toolProviderRegistry.initialize(providerId);
+                await this.toolProviderRegistry.initialize(toolId);
                 this.assertNotDisposed();
-                await this.hooks.onProviderReady?.(providerId, meta);
+                // A config update may have replaced the provider during its start.
+                provider = await this.toolProviderRegistry.getProvider(toolId, false);
+                await this.hooks.onProviderReady?.(toolId, meta);
                 this.assertNotDisposed();
-                await this.emitTelemetry("pie-toolkit-provider-ready", { providerId });
+                await this.emitTelemetry("pie-toolkit-provider-ready", { toolId });
                 this.assertNotDisposed();
                 return provider;
             }
@@ -788,13 +923,16 @@ export class ToolkitCoordinator {
                 if (err instanceof ToolkitCoordinatorDisposedError)
                     throw err;
                 const error = err instanceof Error ? err : new Error(String(err));
-                this.handleError(error, { phase: "provider-init", providerId });
+                this.reportStartFailure(error, { phase: "provider-init", toolId }, 
+                // Attributed when the id names a tool with a provider; any other id
+                // was never a tool's.
+                this.toolRegistry.get(toolId)?.provider ? [toolId] : [], fallbackFollows);
                 throw error;
             }
         })().finally(() => {
-            this.providerInitPromises.delete(providerId);
+            this.providerInitPromises.delete(toolId);
         });
-        this.providerInitPromises.set(providerId, promise);
+        this.providerInitPromises.set(toolId, promise);
         return promise;
     }
     setHooks(hooks) {
@@ -804,7 +942,7 @@ export class ToolkitCoordinator {
             hooks.onCoordinatorReady &&
             this.isReady()) {
             void Promise.resolve(hooks.onCoordinatorReady(this)).catch((err) => {
-                this.handleError(err, { phase: "coordinator-ready" });
+                this.handleError(err, { phase: "coordinator-ready", recoverable: false });
             });
         }
     }
@@ -815,20 +953,17 @@ export class ToolkitCoordinator {
         };
     }
     getSectionController(args) {
-        const key = {
-            assessmentId: this.assessmentId,
-            sectionId: args.sectionId,
-            attemptId: args.attemptId,
-        };
+        const key = this.sectionControllerKey(args);
         return this.sectionControllers.get(this.getSectionControllerMapKey(key));
     }
     subscribeSectionEvents(args) {
-        // Phase D: subscriptions follow the toolkit's *active section
-        // cohort* automatically. We bind the listener to whichever
-        // controller is currently active and re-bind it on every
-        // `getOrCreateSectionController` / `disposeSectionController`
-        // transition, with snapshot replay on each migration.
-        if (this.activeCohortMapKey === null) {
+        // The listener binds to whichever controller is currently active and
+        // re-binds on every `getOrCreateSectionController` /
+        // `disposeSectionController` transition, with snapshot replay on each
+        // migration. A listener added while the next section is still
+        // starting binds when it becomes active.
+        if (this.activeCohortMapKey === null &&
+            this.latestRequestedActiveCohortMapKey === null) {
             throw new Error("[ToolkitCoordinator] subscribeSectionEvents requires an active section cohort; call getOrCreateSectionController first.");
         }
         const previous = this.activeSubscriptions.get(args.listener);
@@ -843,7 +978,9 @@ export class ToolkitCoordinator {
             unsubscribeCurrent: null,
         };
         this.activeSubscriptions.set(args.listener, sub);
-        const controller = this.sectionControllers.get(this.activeCohortMapKey);
+        const controller = this.activeCohortMapKey === null
+            ? undefined
+            : this.sectionControllers.get(this.activeCohortMapKey);
         if (controller) {
             this.bindSubscriptionToController(sub, controller);
         }
@@ -863,7 +1000,7 @@ export class ToolkitCoordinator {
         };
     }
     /**
-     * Bind a Phase D subscription to a section controller. Detaches any
+     * Bind an active-cohort subscription to a section controller. Detaches any
      * prior controller binding the subscription was holding, attaches a
      * fresh `controller.subscribe(...)` callback, and replays the
      * canonical late-subscribe sequence (content-loaded × N then
@@ -922,15 +1059,9 @@ export class ToolkitCoordinator {
         const controller = this.sectionControllers.get(mapKey);
         if (!controller)
             return;
-        // Snapshot the subscription list before iterating: a listener may
-        // synchronously call `subscribeSectionEvents(...)` from inside its
-        // replay delivery, which inserts a new entry into
-        // `activeSubscriptions`. Map iteration yields keys inserted
-        // during the loop; without snapshotting, the inner subscribe path
-        // would bind the new listener once (correctly, with replay) and
-        // the outer loop would then visit it a second time, double-
-        // replaying the snapshot. Snapshot keeps "replay once per cohort
-        // transition" intact.
+        // Iterate a snapshot: a listener may call `subscribeSectionEvents` from
+        // inside its replay delivery, and live Map iteration would then visit the
+        // new entry and replay it a second time.
         for (const sub of Array.from(this.activeSubscriptions.values())) {
             this.bindSubscriptionToController(sub, controller);
         }
@@ -946,10 +1077,7 @@ export class ToolkitCoordinator {
         if (this.activeCohortMapKey === mapKey)
             return;
         this.activeCohortMapKey = null;
-        for (const sub of Array.from(this.activeSubscriptions.values())) {
-            sub.unsubscribeCurrent?.();
-            sub.unsubscribeCurrent = null;
-        }
+        this.detachActiveSubscriptions();
     }
     /**
      * Clear the active cohort if `mapKey` matches it, detaching every
@@ -961,10 +1089,14 @@ export class ToolkitCoordinator {
         if (this.activeCohortMapKey !== mapKey)
             return;
         this.activeCohortMapKey = null;
-        // Symmetric snapshot for safety: a disposer fired during detach
-        // could mutate `activeSubscriptions`. Detach is silent (no listener
-        // fan-out), so re-entrancy exposure is lower than `setActiveCohort`,
-        // but the snapshot keeps both paths uniform.
+        this.detachActiveSubscriptions();
+    }
+    /**
+     * Detach every active subscription from its controller. Iterates a snapshot,
+     * as `setActiveCohort` does, because a disposer may mutate
+     * `activeSubscriptions`.
+     */
+    detachActiveSubscriptions() {
         for (const sub of Array.from(this.activeSubscriptions.values())) {
             sub.unsubscribeCurrent?.();
             sub.unsubscribeCurrent = null;
@@ -974,20 +1106,14 @@ export class ToolkitCoordinator {
         const eventTypeFilter = args.eventTypes ? new Set(args.eventTypes) : null;
         const itemIdFilter = args.itemIds ? new Set(args.itemIds) : null;
         return (event) => {
-            if (eventTypeFilter || itemIdFilter) {
-                const eventType = event?.type || null;
-                if (eventTypeFilter &&
-                    (!eventType || !eventTypeFilter.has(eventType))) {
+            if (eventTypeFilter) {
+                const eventType = event?.type;
+                if (!eventType || !eventTypeFilter.has(eventType))
                     return false;
-                }
-                if (itemIdFilter) {
-                    const hasMatchingItem = Array.from(this.collectEventItemIds(event)).some((itemId) => itemIdFilter.has(itemId));
-                    if (!hasMatchingItem) {
-                        return false;
-                    }
-                }
             }
-            return true;
+            if (!itemIdFilter)
+                return true;
+            return Array.from(this.collectEventItemIds(event)).some((itemId) => itemIdFilter.has(itemId));
         };
     }
     collectEventItemIds(event) {
@@ -1113,26 +1239,33 @@ export class ToolkitCoordinator {
         if (this.disposePromise !== null) {
             throw new ToolkitCoordinatorDisposedError();
         }
-        const key = {
-            assessmentId: this.assessmentId,
-            sectionId: args.sectionId,
-            attemptId: args.attemptId,
-        };
+        const key = this.sectionControllerKey(args);
         const mapKey = this.getSectionControllerMapKey(key);
         this.latestRequestedActiveCohortMapKey = mapKey;
         this.suspendActiveCohortIfSuperseded(mapKey);
-        const existingController = await this.resolveExistingSectionController({
-            mapKey,
-            key,
-            input: args.input,
-            updateExisting: args.updateExisting,
-        });
-        if (existingController) {
-            if (this.disposePromise !== null) {
-                throw new ToolkitCoordinatorDisposedError();
+        let existingController;
+        try {
+            existingController = await this.resolveExistingSectionController({
+                mapKey,
+                key,
+                input: args.input,
+                updateExisting: args.updateExisting,
+            });
+            if (existingController) {
+                if (this.disposePromise !== null) {
+                    throw new ToolkitCoordinatorDisposedError();
+                }
+                if (args.initialSession) {
+                    await this.assignSessionToPublishedController(existingController, args.initialSession);
+                }
             }
-            return existingController;
         }
+        catch (err) {
+            this.deliverSectionStartError(mapKey, err);
+            throw err;
+        }
+        if (existingController)
+            return existingController;
         const pendingDisposal = this.sectionControllerDisposePromises.get(mapKey);
         if (pendingDisposal) {
             // Persistence and hydration share the cohort's durable state. Keep the
@@ -1145,8 +1278,13 @@ export class ToolkitCoordinator {
             throw new ToolkitCoordinatorDisposedError();
         }
         const existingEntry = this.sectionControllerInitEntries.get(mapKey);
-        if (existingEntry)
-            return existingEntry.promise;
+        if (existingEntry) {
+            if (!args.initialSession)
+                return existingEntry.promise;
+            const pendingController = await existingEntry.promise;
+            await this.assignSessionToPublishedController(pendingController, args.initialSession);
+            return pendingController;
+        }
         const token = {
             retired: false,
             candidateClaimed: false,
@@ -1159,6 +1297,7 @@ export class ToolkitCoordinator {
         })
             .catch((err) => {
             this.handleSectionControllerInitError(err, args);
+            this.deliverSectionStartError(mapKey, err);
             throw err;
         })
             .finally(() => {
@@ -1189,8 +1328,7 @@ export class ToolkitCoordinator {
         if (this.sectionControllers.get(args.mapKey) !== existingController) {
             return undefined;
         }
-        // PIE-512 Phase D: a `getOrCreateSectionController` call that
-        // resolves to a previously-created controller still represents a
+        // A `getOrCreateSectionController` call that resolves to a previously-created controller still represents a
         // cohort transition from the toolkit's perspective (same-cohort
         // re-entry is a no-op inside `setActiveCohort`). Active
         // subscriptions migrate here so a host that subscribed once on
@@ -1239,7 +1377,20 @@ export class ToolkitCoordinator {
             await this.retireUnpublishedSectionControllerIfNeeded(candidate);
             await controller.initialize?.(args.args.input);
             await this.retireUnpublishedSectionControllerIfNeeded(candidate);
-            await controller.hydrate?.();
+            // A session the host supplied takes the place of the strategy's stored
+            // snapshot, and is applied before publication so the ready lifecycle
+            // event and every reader after it see it. The strategy still receives
+            // every `persist()`.
+            const initialSession = args.args.initialSession;
+            if (initialSession) {
+                if (!controller.applySession) {
+                    throw new Error("Section controller cannot apply the session it was created with: it has no applySession.");
+                }
+                await controller.applySession(initialSession, { mode: "replace" });
+            }
+            else {
+                await controller.hydrate?.();
+            }
             await this.finalizeSectionControllerReady({
                 ...candidate,
                 context,
@@ -1251,6 +1402,22 @@ export class ToolkitCoordinator {
             throw error;
         }
     }
+    /**
+     * Apply a host-supplied session to a controller that is already published,
+     * under the rules `resolveSectionSessionAssignment` sets: an equal session is a
+     * no-op and recorded responses are not replaced by response-free ones.
+     */
+    async assignSessionToPublishedController(controller, session) {
+        if (!session)
+            return;
+        if (!controller.applySession) {
+            throw new Error("Section controller cannot apply the assigned session: it has no applySession.");
+        }
+        const resolved = resolveSectionSessionAssignment(controller.getSession?.() ?? null, session);
+        if (!resolved)
+            return;
+        await controller.applySession(resolved, { mode: "replace" });
+    }
     createSectionControllerRetirementError() {
         return this.disposePromise !== null
             ? new ToolkitCoordinatorDisposedError()
@@ -1276,6 +1443,7 @@ export class ToolkitCoordinator {
                     sectionId: args.key.sectionId,
                     attemptId: args.key.attemptId,
                 },
+                recoverable: true,
             });
         }
         finally {
@@ -1300,8 +1468,7 @@ export class ToolkitCoordinator {
         this.sectionControllers.set(args.mapKey, args.controller);
         this.sectionControllerKeys.set(args.mapKey, args.key);
         args.token.candidateClaimed = true;
-        // PIE-512 Phase D: a freshly-resolved controller becomes the
-        // active cohort. Active subscriptions migrate to it before the
+        // A freshly-resolved controller becomes the active cohort. Active subscriptions migrate to it before the
         // `ready` lifecycle event and `onSectionControllerReady` hook
         // fire so any synchronous post-ready work observes a coherent
         // active-cohort view.
@@ -1331,14 +1498,36 @@ export class ToolkitCoordinator {
                 sectionId: args.sectionId,
                 attemptId: args.attemptId,
             },
-        });
+            recoverable: false,
+        }, { sectionId: args.sectionId, attemptId: args.attemptId });
     }
-    disposeSectionController(args) {
-        const key = {
-            assessmentId: this.assessmentId,
-            sectionId: args.sectionId,
-            attemptId: args.attemptId,
+    /**
+     * A section that fails to start has no controller of its own to emit its
+     * `section-error`, and the host's subscriptions are already off the outgoing
+     * section, so the coordinator delivers the error to them while that section
+     * is still the one requested.
+     */
+    deliverSectionStartError(mapKey, error) {
+        if (error instanceof ToolkitCoordinatorDisposedError ||
+            error instanceof SectionControllerRetiredError ||
+            this.latestRequestedActiveCohortMapKey !== mapKey) {
+            return;
+        }
+        const event = {
+            type: "section-error",
+            source: "section-runtime",
+            error,
+            currentItemIndex: 0,
+            timestamp: Date.now(),
         };
+        for (const sub of Array.from(this.activeSubscriptions.values())) {
+            if (this.buildSectionEventPredicate(sub)(event)) {
+                this.deliverSectionEventSafely(sub.listener, event);
+            }
+        }
+    }
+    disposeSectionController(args) {
+        const key = this.sectionControllerKey(args);
         const mapKey = this.getSectionControllerMapKey(key);
         const initEntry = this.sectionControllerInitEntries.get(mapKey);
         if (initEntry) {
@@ -1355,8 +1544,7 @@ export class ToolkitCoordinator {
             return this.trackSectionControllerDisposal(mapKey, retirementBarrier);
         }
         const persistenceStrategy = this.sectionPersistenceStrategies.get(mapKey);
-        // PIE-512 Phase D: if the disposing cohort is the active one,
-        // detach all listener-controller bindings before the controller
+        // If the disposing cohort is the active one, detach all listener-controller bindings before the controller
         // itself disposes. The subscription registry stays intact so a
         // later `getOrCreateSectionController(...)` re-binds the same
         // listeners to the new controller.
@@ -1418,6 +1606,7 @@ export class ToolkitCoordinator {
                     sectionId: args.args.sectionId,
                     attemptId: args.args.attemptId,
                 },
+                recoverable: true,
             });
         }
         finally {
@@ -1517,17 +1706,16 @@ export class ToolkitCoordinator {
         this.activeSubscriptions.clear();
         this.activeCohortMapKey = null;
         this.latestRequestedActiveCohortMapKey = null;
-        await cleanup(() => this.ttsService.stop());
+        await cleanup(() => this.ttsService.dispose());
         await cleanup(() => this.toolProviderRegistry.destroy());
         await cleanup(() => this.highlightCoordinator.destroy());
-        for (const toolId of this.toolCoordinator.getRegisteredTools()) {
-            await cleanup(() => this.toolCoordinator.releaseTool(toolId));
-        }
+        await cleanup(() => this.ownedToolCoordinator.destroy());
         await cleanup(() => this.catalogResolver.destroy());
         await cleanup(() => this.toolRequests.dispose());
         await cleanup(() => this.policyEngine.dispose());
         this.toolContextResolvers.clear();
         this.toolContextResolverChangeListeners.clear();
+        this.policyDiagnosticListeners.clear();
         this.sectionControllerLifecycleListeners.clear();
         this.telemetryListeners.clear();
         this.frameworkErrorHookUnsubscribe?.();
@@ -1557,9 +1745,9 @@ export class ToolkitCoordinator {
         await Promise.allSettled(pending);
     }
     /**
-     * Initialize TTS service with provider
+     * Initialize the TTS service from the `textToSpeech` tool config.
      */
-    async ensureTTSReady(config) {
+    async ensureTTSReady() {
         this.assertNotDisposed();
         await this.waitForPendingTTSReconfigure();
         this.assertNotDisposed();
@@ -1567,10 +1755,11 @@ export class ToolkitCoordinator {
             return;
         if (this.ttsInitPromise)
             return this.ttsInitPromise;
-        this.ttsInitPromise = this._initializeTTS(config)
+        this.ttsInitPromise = this._initializeTTS()
             .then(() => this.assertNotDisposed())
             .finally(() => {
             this.ttsInitPromise = undefined;
+            this.notifyReadyChange();
         });
         return this.ttsInitPromise;
     }
@@ -1581,10 +1770,10 @@ export class ToolkitCoordinator {
             pending = this.ttsReconfigurePromise;
         }
     }
-    async _initializeTTS(config) {
+    async _initializeTTS() {
         if (this.ttsInitialized)
             return;
-        const resolvedToolConfig = this.resolveTTSToolConfig(config);
+        const resolvedToolConfig = this.resolveTTSToolConfig();
         const runtimeSettings = resolveTTSRuntimeSettings(resolvedToolConfig);
         const resolvedBackend = resolveTTSBackend(runtimeSettings);
         const runtimeTTSConfig = buildRuntimeTTSConfig(runtimeSettings);
@@ -1603,10 +1792,10 @@ export class ToolkitCoordinator {
             operation: "tts-init",
             backend: resolvedBackend,
         });
-        // Try to use TTS provider from registry if available
-        if (this.toolProviderRegistry.has("tts")) {
+        if (this.toolProviderRegistry.has("textToSpeech")) {
             try {
-                const ttsProvider = await this.ensureProviderReady("tts");
+                // Browser speech follows a server provider that fails to start.
+                const ttsProvider = await this.initializeProvider("textToSpeech", true);
                 const providerInstance = await ttsProvider.createInstance();
                 await this.initializeTTSService(providerInstance, runtimeTTSConfig);
                 await this.emitTelemetry("pie-toolkit-tts-init-success", {
@@ -1618,25 +1807,14 @@ export class ToolkitCoordinator {
                     backend: resolvedBackend,
                     provider: "registry",
                 });
-                console.log("[ToolkitCoordinator] TTS initialized via ToolProviderRegistry");
                 return;
             }
             catch (error) {
                 if (error instanceof ToolkitCoordinatorDisposedError)
                     throw error;
                 const normalized = error instanceof Error ? error : new Error(String(error));
-                await this.emitTelemetry("pie-tool-init-error", {
-                    toolId: "textToSpeech",
-                    providerId: "tts",
-                    operation: "tts-init",
-                    backend: resolvedBackend,
-                    errorType: "TTSRegistryInitError",
-                    message: normalized.message,
-                    recovered: true,
-                });
                 await this.emitTelemetry("pie-tool-init-fallback", {
                     toolId: "textToSpeech",
-                    providerId: "tts",
                     operation: "tts-init",
                     backend: resolvedBackend,
                     fromProvider: "registry",
@@ -1649,10 +1827,13 @@ export class ToolkitCoordinator {
         else if (resolvedBackend !== "browser") {
             this.reportMissingTTSProvider(resolvedBackend);
         }
-        // Fallback to browser provider
+        // Browser speech, configured or standing in for a backend that has no
+        // provider or failed to start.
         const provider = new BrowserTTSProvider();
         try {
-            await this.initializeTTSService(provider, runtimeTTSConfig);
+            await this.initializeTTSService(provider, resolvedBackend === "browser"
+                ? runtimeTTSConfig
+                : browserFallbackConfig(runtimeTTSConfig));
             await this.emitTelemetry("pie-toolkit-tts-init-success", {
                 provider: "browser-fallback",
             });
@@ -1667,7 +1848,7 @@ export class ToolkitCoordinator {
             if (error instanceof ToolkitCoordinatorDisposedError)
                 throw error;
             const normalized = error instanceof Error ? error : new Error(String(error));
-            this.handleError(normalized, { phase: "tts-init" });
+            this.reportStartFailure(normalized, { phase: "tts-init" }, ["textToSpeech"]);
             await this.emitTelemetry("pie-toolkit-tts-init-error", {
                 message: normalized.message,
             });
@@ -1681,12 +1862,12 @@ export class ToolkitCoordinator {
             throw normalized;
         }
     }
-    resolveTTSToolConfig(config) {
-        return config || this.getTTSConfigFromProviders() || {};
+    resolveTTSToolConfig() {
+        return this.getTTSConfigFromProviders() || {};
     }
     async initializeTTSService(provider, config) {
         const nextProviderOptions = {
-            ...((config.providerOptions || {}) || {}),
+            ...config.providerOptions,
             __pieTelemetry: async (eventName, payload) => {
                 await this.emitTelemetry(eventName, {
                     toolId: "textToSpeech",
@@ -1699,93 +1880,14 @@ export class ToolkitCoordinator {
             providerOptions: nextProviderOptions,
         };
         await this.ttsService.initialize(provider, nextConfig);
-        await this.ensureBrowserVoicesReady(provider);
         this.assertNotDisposed();
         this.ttsService.setCatalogResolver(this.catalogResolver);
         this.ttsInitialized = true;
+        this.ttsDegraded = false;
+        this.degradedTools.delete("textToSpeech");
         await this.hooks.onTTSReady?.();
         this.assertNotDisposed();
     }
-    async ensureBrowserVoicesReady(provider, timeoutMs = 1200) {
-        if (provider.providerId !== "browser")
-            return;
-        if (typeof window === "undefined")
-            return;
-        if (!("speechSynthesis" in window))
-            return;
-        const synth = window.speechSynthesis;
-        const voices = synth.getVoices();
-        if (voices.length > 0)
-            return;
-        await new Promise((resolve) => {
-            let settled = false;
-            const canUseEventTarget = typeof synth.addEventListener === "function" &&
-                typeof synth.removeEventListener === "function";
-            const canUseHandler = !canUseEventTarget && "onvoiceschanged" in synth;
-            const previousHandler = canUseHandler ? synth.onvoiceschanged : null;
-            let assignedHandler = false;
-            const finish = () => {
-                if (settled)
-                    return;
-                settled = true;
-                window.clearTimeout(timeoutId);
-                if (canUseEventTarget) {
-                    synth.removeEventListener("voiceschanged", onVoicesChanged);
-                }
-                else if (assignedHandler &&
-                    synth.onvoiceschanged === onVoicesChanged) {
-                    synth.onvoiceschanged = previousHandler;
-                }
-                resolve();
-            };
-            const onVoicesChanged = (event) => {
-                if (!canUseEventTarget &&
-                    typeof previousHandler === "function" &&
-                    event) {
-                    previousHandler.call(synth, event);
-                }
-                finish();
-            };
-            const timeoutId = window.setTimeout(finish, timeoutMs);
-            if (canUseEventTarget) {
-                synth.addEventListener("voiceschanged", onVoicesChanged, {
-                    once: true,
-                });
-            }
-            else if (canUseHandler) {
-                synth.onvoiceschanged = onVoicesChanged;
-                assignedHandler = true;
-            }
-        });
-        const voicesAfterWait = synth.getVoices();
-        await this.emitTelemetry("pie-toolkit-tts-browser-voices-ready", {
-            voiceCount: voicesAfterWait.length,
-            timedOut: voicesAfterWait.length === 0,
-        });
-    }
-    /**
-     * Get all services as a bundle for section player convenience.
-     * Section player can extract and pass services to child components.
-     */
-    getServiceBundle() {
-        return {
-            ttsService: this.ttsService,
-            toolCoordinator: this.toolCoordinator,
-            highlightCoordinator: this.highlightCoordinator,
-            elementToolStateStore: this.elementToolStateStore,
-            catalogResolver: this.catalogResolver,
-            toolProviderRegistry: this.toolProviderRegistry,
-        };
-    }
-    /**
-     * Get a tool provider from the registry
-     *
-     * @param providerId Provider identifier
-     * @returns Tool provider instance
-     */
-    async getToolProvider(providerId) {
-        return this.ensureProviderReady(providerId);
-    }
     async waitUntilReady() {
         this.assertNotDisposed();
         if (this.isReady())
@@ -1795,9 +1897,8 @@ export class ToolkitCoordinator {
         this.coordinatorReadyPromise = (async () => {
             await this.ensureStateLoaded();
             this.assertNotDisposed();
-            const ttsConfig = this.getTTSConfigFromProviders();
-            if (ttsConfig?.enabled !== false) {
-                await this.ensureTTSReady(ttsConfig);
+            if (this.ttsRequiredForReadiness()) {
+                await this.startTTSForReadiness();
             }
             this.assertNotDisposed();
             if (!this.coordinatorReadyNotified) {
@@ -1814,22 +1915,37 @@ export class ToolkitCoordinator {
         return this.coordinatorReadyPromise;
     }
     isReady() {
-        return this.getInitStatus().coordinator;
+        return ((this.stateLoadSettled || !this.hooks.loadToolState) &&
+            (this.ttsInitialized ||
+                this.ttsDegraded ||
+                !this.ttsRequiredForReadiness()));
+    }
+    /**
+     * Readiness waits for text-to-speech when it is enabled and either starts
+     * eagerly or is granted: a granted read-aloud fails before the learner starts.
+     */
+    ttsRequiredForReadiness() {
+        if (this.getTTSConfigFromProviders()?.enabled === false)
+            return false;
+        return !this.lazyInit || this.isToolGranted("textToSpeech");
     }
-    getInitStatus() {
-        const providers = {};
-        for (const providerId of this.toolProviderRegistry.getProviderIds()) {
-            providers[providerId] =
-                this.toolProviderRegistry.isInitialized(providerId);
+    /**
+     * Starts text-to-speech for readiness. A failure policy does not grant leaves
+     * the tool degraded, reporting itself unavailable, and readiness settles; a
+     * granted tool's failure rejects.
+     */
+    async startTTSForReadiness() {
+        try {
+            await this.ensureTTSReady();
+        }
+        catch (error) {
+            if (error instanceof ToolkitCoordinatorDisposedError)
+                throw error;
+            if (this.isToolGranted("textToSpeech"))
+                throw error;
+            this.ttsDegraded = true;
+            this.notifyReadyChange();
         }
-        const ttsConfig = this.getTTSConfigFromProviders();
-        return {
-            tts: this.ttsInitialized,
-            stateLoaded: this.stateLoaded || !this.hooks.loadToolState,
-            coordinator: (this.stateLoaded || !this.hooks.loadToolState) &&
-                (this.ttsInitialized || ttsConfig?.enabled === false),
-            providers,
-        };
     }
     getTTSConfigFromProviders() {
         return this.config.tools?.providers?.textToSpeech;
@@ -1838,16 +1954,11 @@ export class ToolkitCoordinator {
         if (typeof toolId !== "string" || toolId.trim().length === 0) {
             throw new Error("Tool id must be a non-empty string.");
         }
-        if (toolId === "tts") {
-            throw new Error(`Tool id "tts" is no longer supported. Use "textToSpeech".`);
-        }
-        // An empty registry means the host supplied none, not that every id is
-        // wrong. There is nothing to check an id against, and throwing turns a
-        // host's every tool-config call into an exception — including the calls
-        // this coordinator's own default-provider block provokes, which is how a
-        // host that passes no registry ended up unable to read its own config.
-        // Validation reports the missing registry once per coordinator, as
-        // `tools.registryUnavailable`; a report per call would be noise.
+        // An empty registry means the host supplied none, so there is nothing to
+        // check an id against. Throwing here would fail every tool-config call,
+        // the default providers' own included, and once left a host without a
+        // registry unable to read its config. Validation reports the missing
+        // registry once per coordinator, as `tools.registryUnavailable`.
         if (this.toolRegistry.getAllToolIds().length === 0)
             return;
         if (!this.toolRegistry.get(toolId)) {
@@ -1867,6 +1978,11 @@ export class ToolkitCoordinator {
             this.toolContextResolvers.set(toolId, resolver);
         }
     }
+    /**
+     * Replace all host-owned render-context resolvers. The toolkit element
+     * calls this from `runtime.toolContextResolvers`; it is not on
+     * `ToolkitCoordinatorApi`.
+     */
     setToolContextResolvers(resolvers) {
         this.toolContextResolvers.clear();
         this.installToolContextResolvers(resolvers ?? undefined);
@@ -1882,25 +1998,11 @@ export class ToolkitCoordinator {
             }
         }
     }
-    /**
-     * Check if a tool is enabled.
-     * Tools are enabled by default unless explicitly disabled.
-     *
-     * @param toolId Tool identifier (e.g., 'textToSpeech', 'answerEliminator')
-     * @returns True if tool is enabled
-     */
-    isToolEnabled(toolId) {
-        this.assertCanonicalToolId(toolId);
-        const toolConfig = this.config.tools?.providers?.[toolId];
-        // Enabled by default unless explicitly set to false
-        return toolConfig?.enabled !== false;
-    }
     getToolConfig(toolId) {
         this.assertCanonicalToolId(toolId);
         return this.config.tools?.providers?.[toolId] || null;
     }
     updateToolConfig(toolId, updates) {
-        // Update config
         this.assertCanonicalToolId(toolId);
         const current = this.getToolConfig(toolId) || {};
         if (!this.config.tools) {
@@ -1914,10 +2016,10 @@ export class ToolkitCoordinator {
             this.config.tools.providers = {};
         }
         const nextProviders = {
-            ...(this.config.tools.providers || {}),
+            ...this.config.tools.providers,
             [toolId]: mergeToolConfigUpdate(toolId, current, updates),
         };
-        this.config.tools = this.validateToolsConfig({
+        const validated = this.validateToolsConfig({
             ...this.config.tools,
             providers: nextProviders,
         }, {
@@ -1925,31 +2027,21 @@ export class ToolkitCoordinator {
             source: "ToolkitCoordinator.updateToolConfig",
             toolRegistry: this.toolRegistry,
         });
-        // M8 PR 2 — keep the policy engine's tools input in lockstep
-        // with the validated coordinator config. The engine emits an
-        // `inputs` change event so subscribers (e.g. PR 3 toolbars) can
-        // re-decide without us managing a parallel pub/sub.
-        this.policyEngine.updateInputs({
-            tools: this.config.tools,
-        });
+        this.config.tools = validated;
+        // The engine's tools input follows the validated config; its `inputs`
+        // change event is what makes toolbars re-decide.
+        this.policyEngine.updateInputs({ tools: validated });
         void this.emitTelemetry("pie-toolkit-tool-config-updated", { toolId });
-        // Apply configuration changes to services
-        this._applyToolConfigChange(toolId, current);
+        this._applyToolConfigChange(toolId);
     }
     /**
-     * Update the enabled tool list for one placement level.
+     * Patch one or more placement levels in the canonical tools config.
      *
      * This is the generic placement companion to {@link updateToolConfig}:
      * it validates the next canonical tools config, keeps the policy
      * engine in lockstep, and emits the same policy-change event used by
      * live toolbars/debug panels.
      */
-    updateToolPlacement(level, toolIds) {
-        this.updateToolsPlacement({ [level]: [...toolIds] });
-    }
-    /**
-     * Patch one or more placement levels in the canonical tools config.
-     */
     updateToolsPlacement(partial) {
         if (!this.config.tools) {
             this.config.tools = this.validateToolsConfig(undefined, {
@@ -1978,17 +2070,58 @@ export class ToolkitCoordinator {
         });
         validated.placement = nextPlacement;
         this.config.tools = validated;
-        this.policyEngine.updateInputs({
-            tools: this.config.tools,
-        });
+        this.policyEngine.updateInputs({ tools: validated });
     }
     /**
      * Resolve the visible tool set for a given placement level + scope.
      *
-     * Thin shim over the owned tool-policy engine.
+     * Delegates to the owned tool-policy engine and logs the decision's
+     * diagnostics through {@link warnPolicyDiagnostics}.
      */
     decideToolPolicy(request) {
-        return this.policyEngine.decide(request);
+        const decision = this.policyEngine.decide(request);
+        this.warnPolicyDiagnostics(decision.diagnostics);
+        return decision;
+    }
+    /**
+     * Report each policy diagnostic as a console warning and to the
+     * {@link onPolicyDiagnostic} listeners, once per code and tool id, and per
+     * item for `tool-policy.itemSettingNotApplied`. Every toolbar and feature
+     * asks for decisions, so a conflict would otherwise repeat on each; the
+     * engine's input diagnostics arrive with each policy change.
+     */
+    warnPolicyDiagnostics(diagnostics) {
+        for (const diagnostic of diagnostics) {
+            const itemId = diagnostic.code === "tool-policy.itemSettingNotApplied"
+                ? diagnostic.details.itemId
+                : "";
+            const key = `${diagnostic.code}\0${diagnostic.toolId}\0${itemId}`;
+            if (this.reportedPolicyDiagnostics.has(key))
+                continue;
+            this.reportedPolicyDiagnostics.set(key, diagnostic);
+            console.warn(`[ToolkitCoordinator] ${diagnostic.message}`);
+            for (const listener of Array.from(this.policyDiagnosticListeners)) {
+                this.notifyPolicyDiagnosticListener(listener, diagnostic);
+            }
+        }
+    }
+    notifyPolicyDiagnosticListener(listener, diagnostic) {
+        try {
+            listener(diagnostic);
+        }
+        catch (error) {
+            console.error("[ToolkitCoordinator] Policy diagnostic listener failed:", error);
+        }
+    }
+    /**
+     * File a mounted item's policy settings (`requiredTools`, `restrictedTools`,
+     * `toolParameters`) under its canonical id. They govern the decisions scoped
+     * to that item: its own item-level toolbar, and the feature decisions its
+     * content asks with the item's scope. `pie-item-scope` registers them from
+     * its `settings` property; the returned function withdraws them.
+     */
+    registerItemSettings(itemId, settings) {
+        return this.policyEngine.registerItemSettings(itemId, settings);
     }
     /**
      * Resolve eligibility for one PNP/AfA feature id, independent of toolbar
@@ -1999,8 +2132,8 @@ export class ToolkitCoordinator {
      * `pnpEnforcement` is not consulted.
      *
      * Reports once per coordinator when it is asked about a feature with no
-     * assessment bound. A host in that state gets a correct denial for every
-     * capability it asks about, which is indistinguishable from a student who was
+     * assessment bound. A host in that state gets a denial for every capability
+     * no item requires, which is indistinguishable from a student who was
      * properly declined — so without this, forgetting {@link updateAssessment}
      * presents as an accommodation that silently never appears.
      *
@@ -2008,25 +2141,28 @@ export class ToolkitCoordinator {
      * enforcement is explicitly `"on"`. Its toolkit binds whatever assessment the
      * host gave, usually none, and a host that passes no profile and leaves
      * enforcement unset or `"off"` has asked for no accommodation.
+     *
+     * `scope` is the surface asking; an item's scope brings in that item's
+     * registered settings ({@link registerItemSettings}).
      */
-    decideFeaturePolicy(featureId) {
-        const decision = this.policyEngine.decideFeature(featureId);
-        const unboundIsMisconfigured = this.config.assessmentOptional !== true ||
-            this.pnpEnforcementOverride === "on";
+    decideFeaturePolicy(featureId, scope) {
+        const decision = this.policyEngine.decideFeature(featureId, scope);
+        this.warnPolicyDiagnostics(decision.diagnostics);
         if (!decision.assessmentBound &&
-            unboundIsMisconfigured &&
+            this.policyEngine.getInputs().assessmentExpected &&
             !this.reportedUnboundFeaturePolicy) {
             this.reportedUnboundFeaturePolicy = true;
-            console.warn(`[ToolkitCoordinator] Feature policy was asked about "${featureId}" with no assessment bound, so every capability will be declined for want of a profile to read. Call updateAssessment(...) with the assessment (its personalNeedsProfile, settings.districtPolicy and settings.testAdministration are what policy reads) before relying on any accommodation. Reported once per coordinator.`);
+            console.warn(`[ToolkitCoordinator] Feature policy was asked about "${featureId}" with no assessment bound, so profile, district and test-administration policy have nothing to read and only an item's requiredTools can grant. Pass the assessment to the toolkit's assessment property, or call updateAssessment(...), before relying on any accommodation. Reported once per coordinator.`);
         }
         return decision;
     }
     /**
      * Subscribe to policy-engine change events. Fires whenever the
      * coordinator's bound inputs change (`updateToolConfig`,
-     * `updateToolPlacement`, `updateAssessment`, `updateCurrentItemRef`,
-     * `setPnpEnforcement`) or a custom `PolicySource` is registered /
-     * removed via {@link registerPolicySource}.
+     * `updateToolsPlacement`, `updateAssessment`, `setPnpEnforcement`), an
+     * item's settings are registered or withdrawn ({@link registerItemSettings}),
+     * or a custom `PolicySource` is registered / removed via
+     * {@link registerPolicySource}.
      *
      * The listener receives a `ToolPolicyChangeEvent` with the event
      * `reason` and a frozen snapshot of the engine inputs. Listeners
@@ -2040,6 +2176,15 @@ export class ToolkitCoordinator {
     onPolicyChange(listener) {
         return this.policyEngine.onPolicyChange(listener);
     }
+    onPolicyDiagnostic(listener) {
+        this.policyDiagnosticListeners.add(listener);
+        for (const diagnostic of Array.from(this.reportedPolicyDiagnostics.values())) {
+            this.notifyPolicyDiagnosticListener(listener, diagnostic);
+        }
+        return () => {
+            this.policyDiagnosticListeners.delete(listener);
+        };
+    }
     /**
      * Subscribe to accessibility-catalog registrations and removals.
      *
@@ -2056,49 +2201,26 @@ export class ToolkitCoordinator {
     /**
      * Bind (or clear) the active assessment for PNP/profile policy decisions.
      *
-     * Under auto-mode (no host override via {@link setPnpEnforcement}),
-     * the coordinator promotes the engine to `pnpEnforcement: "on"`
-     * iff the assessment carries any profile precedence material
-     * (`personalNeedsProfile`, `settings.districtPolicy`,
-     * `settings.testAdministration`) or the currently-bound item ref
-     * carries item-level profile policy inputs. A bare assessment record (just
+     * Under auto-mode (no host override via {@link setPnpEnforcement}), a
+     * decision enforces PNP/profile policy iff the assessment carries profile
+     * precedence material (`personalNeedsProfile`, `settings.districtPolicy`,
+     * `settings.testAdministration`), or the decision is scoped to an item whose
+     * settings carry item-level policy inputs. A bare assessment record (just
      * `id` / `name`, no PNP, no settings) keeps `"off"`.
      *
      * The host override set via {@link setPnpEnforcement} is sticky
-     * across assessment swaps; calling with `null` clears the binding
-     * and re-runs the auto-mode helper.
+     * across assessment swaps.
      */
     updateAssessment(assessment) {
-        this.boundAssessment = assessment;
-        this.policyEngine.updateInputs({
-            assessment,
-            pnpEnforcement: this.resolveEffectivePnpEnforcement(),
-        });
+        this.policyEngine.updateInputs({ assessment });
     }
     /**
-     * Bind (or clear) the current item reference for policy decisions.
-     *
-     * Used by item-level profile gates (item `requiredTools` /
-     * `restrictedTools` / `toolParameters`). Item-level profile material
-     * also feeds {@link resolveEffectivePnpEnforcement} — navigating
-     * to an item with profile settings can flip auto-mode to `"on"` even
-     * when the parent assessment carries no profile block of its own.
-     */
-    updateCurrentItemRef(itemRef) {
-        this.boundCurrentItemRef = itemRef;
-        this.policyEngine.updateInputs({
-            currentItemRef: itemRef,
-            pnpEnforcement: this.resolveEffectivePnpEnforcement(),
-        });
-    }
-    /**
-     * Override the auto-mode PNP/profile enforcement decision.
+     * Override the auto-mode PNP/profile enforcement decision; `null` returns
+     * to auto-mode. `"on"` and `"off"` stick across assessment swaps until
+     * cleared.
      */
     setPnpEnforcement(mode) {
-        this.pnpEnforcementOverride = mode;
-        this.policyEngine.updateInputs({
-            pnpEnforcement: this.resolveEffectivePnpEnforcement(),
-        });
+        this.policyEngine.updateInputs({ pnpEnforcement: mode });
     }
     /**
      * Get the policy engine inputs currently driving decisions. Useful
@@ -2122,29 +2244,6 @@ export class ToolkitCoordinator {
     registerPolicySource(source) {
         return this.policyEngine.registerPolicySource(source);
     }
-    /**
-     * Register a host-owned resolver for one tool's render context.
-     *
-     * Resolvers are evaluated only for tools that already survived the
-     * framework policy pipeline. They can hide the tool for the current
-     * scope or attach render params consumed by the packaged registration;
-     * they cannot re-enable tools blocked by placement, provider config,
-     * host policy, or PNP/profile rules.
-     */
-    registerToolContextResolver(toolId, resolver) {
-        this.assertCanonicalToolId(toolId);
-        if (typeof resolver !== "function") {
-            throw new Error(`Invalid tool context resolver for "${toolId}": expected a function.`);
-        }
-        this.toolContextResolvers.set(toolId, resolver);
-        this.notifyToolContextResolverChange();
-        return () => {
-            if (this.toolContextResolvers.get(toolId) !== resolver)
-                return;
-            this.toolContextResolvers.delete(toolId);
-            this.notifyToolContextResolverChange();
-        };
-    }
     hasToolContextResolver(toolId) {
         this.assertCanonicalToolId(toolId);
         return this.toolContextResolvers.has(toolId);
@@ -2192,6 +2291,9 @@ export class ToolkitCoordinator {
             this.toolContextResolverChangeListeners.delete(listener);
         };
     }
+    getToolRegistry() {
+        return this.toolRegistry;
+    }
     /**
      * Claim requests for one placement level. Called by a toolbar on mount.
      */
@@ -2215,95 +2317,46 @@ export class ToolkitCoordinator {
      * surface, and a host that swapped the registry for one without the tool would
      * otherwise lose the whole surface to an exception over an absent action.
      */
-    canRequestTool(toolId, level) {
+    canRequestTool(toolId, level, scopeId) {
         try {
             this.assertCanonicalToolId(toolId);
         }
         catch {
             return false;
         }
-        return this.toolRequests.canRequest(toolId, level);
+        return this.toolRequests.canRequest(toolId, level, scopeId);
     }
     onToolRequestTargetsChange(listener) {
         return this.toolRequests.onTargetsChange(listener);
     }
-    /**
-     * Compute the effective PNP/profile enforcement mode given the explicit
-     * host override and the auto-mode helper.
-     *
-     * Auto-mode (no override) defers to
-     * {@link resolveDefaultPnpEnforcement}, which returns `"on"`
-     * exactly when the bound assessment or current item ref carries
-     * profile precedence material (PNP, district policy, test
-     * administration, item-level required/restricted/parameters), and
-     * `"off"` otherwise. Profile gates engage the moment profile material
-     * is present.
-     */
-    resolveEffectivePnpEnforcement() {
-        if (this.pnpEnforcementOverride !== null) {
-            return this.pnpEnforcementOverride;
-        }
-        return resolveDefaultPnpEnforcement({
-            assessment: this.boundAssessment,
-            currentItemRef: this.boundCurrentItemRef,
-        });
-    }
     resolveConfiguredPnpEnforcement() {
-        const tools = this.config.tools;
-        return tools?.pnpEnforcement ?? null;
+        return this.config.tools?.pnpEnforcement ?? null;
     }
-    /**
-     * Apply tool configuration changes to underlying services.
-     * Called after updateToolConfig() with the tool's config before the update.
-     */
-    _applyToolConfigChange(toolId, previousConfig) {
+    /** Apply an `updateToolConfig` change to the underlying services. */
+    _applyToolConfigChange(toolId) {
         if (this.disposePromise !== null)
             return;
-        // Apply configuration changes based on tool
-        switch (toolId) {
-            case "textToSpeech":
-                this.scheduleTTSReconfigure();
-                break;
-            case "answerEliminator":
-                // Future: Could notify answer eliminator tools of strategy change
-                break;
-            default:
-                this._registerChangedToolProvider(toolId, previousConfig);
+        if (toolId === "textToSpeech") {
+            this.scheduleTTSReconfigure();
+            return;
         }
+        this._registerChangedToolProvider(toolId);
     }
     /**
-     * Register the provider a tool's updated config names, and unregister the
-     * one its previous config named when the provider id changed, as
-     * {@link _reconfigureTTSProvider} does for `tts`. Registration completes
-     * before this returns, so a check on the policy change the update dispatched
-     * finds the new provider.
+     * Register the provider a tool's updated config builds, replacing the one
+     * registered under the tool's id. Registration completes before this returns,
+     * so a check on the policy change the update dispatched finds the new provider.
      */
-    _registerChangedToolProvider(toolId, previousConfig) {
+    _registerChangedToolProvider(toolId) {
         const registration = this.getProviderDescriptorTools().find((tool) => tool.toolId === toolId);
         if (!registration)
             return;
-        void this.registerProviderFromTool(registration);
-        const resolveQuietly = (config) => {
-            try {
-                return resolveToolProviderId(registration, config);
-            }
-            catch {
-                return null;
-            }
-        };
-        const previousId = resolveQuietly(previousConfig);
-        const nextId = resolveQuietly(this.getToolConfig(toolId) || undefined);
-        if (!previousId ||
-            previousId === nextId ||
-            !this.toolProviderRegistry.has(previousId)) {
-            return;
-        }
-        void this.toolProviderRegistry.unregister(previousId).catch((err) => {
-            console.warn(`[ToolkitCoordinator] Failed to unregister provider "${previousId}":`, err);
-        });
+        // A failure of the replaced provider no longer describes the tool.
+        this.degradedTools.delete(toolId);
+        void this.registerProviderFromTool(registration, true);
     }
     /**
-     * Re-register the `tts` provider for the current config and registry, then
+     * Re-register the text-to-speech provider for the current config and registry, then
      * re-initialize unless initialization is lazy. An initialization already
      * running finishes first: it would otherwise mark its provider ready after
      * the reset.
@@ -2319,26 +2372,31 @@ export class ToolkitCoordinator {
                 this.ttsReconfigurePromise = undefined;
             }
         });
-        void reconfigurePromise.then(async () => {
+        void reconfigurePromise
+            .then(async () => {
             if (this.disposePromise !== null)
                 return;
-            const ttsConfig = this.getTTSConfigFromProviders();
-            if (!this.lazyInit && ttsConfig?.enabled !== false) {
-                await this.ensureTTSReady(ttsConfig);
-            }
-        });
+            if (this.ttsRequiredForReadiness())
+                await this.startTTSForReadiness();
+        })
+            // Reported where it failed; a granted failure has nowhere else to go.
+            .catch(() => { });
     }
     async _reconfigureTTSProvider() {
         this.ttsInitialized = false;
+        this.ttsDegraded = false;
+        this.degradedTools.delete("textToSpeech");
         this.ttsInitPromise = undefined;
+        this.notifyReadyChange();
         try {
-            this.ttsService.stop();
+            // The next speak waits on readiness, which starts the new provider.
+            this.ttsService.releaseProvider();
         }
         catch {
-            // noop: stop best effort
+            // noop: release best effort
         }
-        if (this.toolProviderRegistry.has("tts")) {
-            await this.toolProviderRegistry.unregister("tts");
+        if (this.toolProviderRegistry.has("textToSpeech")) {
+            await this.toolProviderRegistry.unregister("textToSpeech");
         }
         if (this.disposePromise !== null)
             return;