@pie-players/pie-assessment-toolkit 0.3.73 → 0.3.75

package/dist/services/ToolkitCoordinator.js

@@ -14,7 +14,7 @@
  * Part of PIE Assessment Toolkit.
  */
 import { normalizeToolsConfig, } from "./tools-config-normalizer.js";
-import { normalizeAndValidateToolsConfig, normalizeToolConfigStrictness, } from "./tool-config-validation.js";
+import { collectToolConfigDiagnostics, normalizeToolConfigStrictness, reportToolConfigDiagnostics, } from "./tool-config-validation.js";
 import { AccessibilityCatalogResolver } from "./AccessibilityCatalogResolver.js";
 import { ElementToolStateStore } from "./ElementToolStateStore.js";
 import { frameworkErrorFromCoordinatorContext, } from "./framework-error.js";
@@ -22,13 +22,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 { 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,16 +45,9 @@ 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;
 };
@@ -81,13 +74,19 @@ const SECTION_SCOPED_EVENT_TYPES = [
  *
  * @example
  * ```typescript
+ * // Both are exported by @pie-players/pie-default-tool-loaders
+ * const toolRegistry = createPackagedToolRegistry({
+ *   toolModuleLoaders: DEFAULT_TOOL_MODULE_LOADERS,
+ * });
+ *
  * // Create coordinator with configuration
  * const coordinator = new ToolkitCoordinator({
  *   assessmentId: 'demo-three-questions',
+ *   toolRegistry,
  *   tools: {
  *     providers: {
  *       textToSpeech: { enabled: true, backend: 'browser' },
- *       answerEliminator: { enabled: true, strategy: 'strikethrough' }
+ *       answerEliminator: { enabled: true }
  *     },
  *     placement: {
  *       item: ['textToSpeech', 'answerEliminator']
@@ -96,7 +95,7 @@ const SECTION_SCOPED_EVENT_TYPES = [
  * });
  *
  * // Pass to section player
- * player.toolkitCoordinator = coordinator;
+ * player.runtime = { ...(player.runtime ?? {}), coordinator };
  *
  * // Access services directly
  * const ttsService = coordinator.ttsService;
@@ -119,14 +118,43 @@ 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();
+    /** Tools a toolbar reported a module failure for, each reported once. */
+    toolModuleFailures = 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.
+     */
+    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();
@@ -153,14 +181,16 @@ export class ToolkitCoordinator {
      * Phase D: 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();
@@ -176,32 +206,20 @@ 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}).
+     * Host-set override for PNP/profile enforcement, passed to the engine.
+     * `null` (the default) is auto-mode, which the engine resolves per decision
+     * from the policy material the bound assessment and the decision's item carry.
      * `"on"` / `"off"` are explicit host opt-in / opt-out and stick
-     * across subsequent assessment / item swaps until the host clears
+     * across subsequent assessment 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 already logged, keyed by code, tool id and, for
+     * `tool-policy.itemSettingNotApplied`, item id; see
+     * {@link warnPolicyDiagnostics}.
      */
-    boundCurrentItemRef = null;
+    warnedPolicyDiagnostics = new Set();
     /**
      * Whether {@link decideFeaturePolicy} has already reported serving a decision
      * with no assessment bound.
@@ -213,22 +231,40 @@ export class ToolkitCoordinator {
      * lifetime for no new information.
      */
     reportedUnboundFeaturePolicy = false;
-    static resolveConfig(config) {
+    /**
+     * Whether {@link _initializeTTS} has already reported a non-browser backend
+     * 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.
+     */
+    reportedMissingTTSProvider = false;
+    /**
+     * The backend of a fallback {@link reportMissingTTSProvider} held back while
+     * the registry was unsettled, reported if the bound toolkit has no registry.
+     */
+    heldMissingTTSProviderBackend = null;
+    /**
+     * Whether {@link validateToolsConfig} has already reported validating with
+     * no registry (`tools.registryUnavailable`). Once per coordinator: every
+     * {@link updateToolConfig} and {@link updateToolsPlacement} re-validates, and
+     * the missing registry is the same gap each time.
+     */
+    reportedRegistryUnavailable = false;
+    resolveConfig(config) {
         const strictness = normalizeToolConfigStrictness(config.toolConfigStrictness);
-        // An empty registry when the host supplies none. This package no longer
-        // holds the packaged capability set, so there is nothing to fall back to —
-        // a host that wants stock tools passes a registry from
-        // `@pie-players/pie-default-tool-loaders`. Tool-id validation is skipped
-        // against an empty registry (with a diagnostic saying so) rather than
+        // An empty placeholder when the host supplies none, replaced by the bound
+        // toolkit's registry in `adoptToolRegistry`. This package does not hold the
+        // packaged capability set, and importing it would be a dependency cycle.
+        // Tool-id validation is skipped against an empty registry rather than
         // rejecting every configured id.
         const toolRegistry = config.toolRegistry ?? new ToolRegistry();
         const normalized = config.deferToolConfigValidation === true
             ? normalizeToolsConfig(config.tools)
-            : normalizeAndValidateToolsConfig(config.tools, {
+            : this.validateToolsConfig(config.tools, {
                 strictness,
                 source: "ToolkitCoordinator.init",
                 toolRegistry,
-            }).config;
+            });
         const defaultProviders = {
             textToSpeech: {
                 enabled: true,
@@ -256,17 +292,38 @@ export class ToolkitCoordinator {
             },
         };
     }
+    /**
+     * `normalizeAndValidateToolsConfig`, except that `tools.registryUnavailable`
+     * is reported once per coordinator, whichever call validates.
+     */
+    validateToolsConfig(tools, options) {
+        const { config, diagnostics } = collectToolConfigDiagnostics(tools, options.toolRegistry);
+        const unreported = this.reportedRegistryUnavailable || this.toolRegistryPending()
+            ? diagnostics.filter((entry) => entry.code !== "tools.registryUnavailable")
+            : diagnostics;
+        reportToolConfigDiagnostics(unreported, options);
+        if (options.strictness !== "off" &&
+            unreported.some((entry) => entry.code === "tools.registryUnavailable")) {
+            this.reportedRegistryUnavailable = true;
+        }
+        return config;
+    }
     constructor(config) {
         if (!config.assessmentId) {
             throw new Error("ToolkitCoordinator requires assessmentId in config");
         }
-        const resolvedConfig = ToolkitCoordinator.resolveConfig(config);
+        this.toolRegistrySupplied = config.toolRegistry != null;
+        this.toolRegistrySettled = this.toolRegistrySupplied;
+        const resolvedConfig = this.resolveConfig(config);
         this.assessmentId = resolvedConfig.assessmentId;
         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.eagerInit = config.eagerInit ?? !this.lazyInit;
         this.pnpEnforcementOverride = this.resolveConfiguredPnpEnforcement();
         // Use the host-provided framework-error bus if one was passed
         // (typical when embedded inside <pie-assessment-toolkit>, so
@@ -286,31 +343,38 @@ export class ToolkitCoordinator {
         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}`,
             inputs: {
                 tools: this.config.tools,
                 assessment: null,
-                currentItemRef: null,
-                pnpEnforcement: this.resolveEffectivePnpEnforcement(),
+                pnpEnforcement: this.pnpEnforcementOverride,
             },
         });
-        if (!this.lazyInit) {
+        this.policyEngine.onPolicyChange((event) => {
+            if (event.reason !== "disposed")
+                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 });
             });
         }
     }
@@ -394,13 +458,92 @@ 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 `scope: "cohort"`.
+     */
+    handleError(error, context, scope = "runtime") {
         const model = frameworkErrorFromCoordinatorContext({
             error,
             context,
+            recoverable: context.recoverable,
+            scope,
         });
         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. Read without the unbound-assessment warning.
+     */
+    isToolGranted(toolId) {
+        try {
+            return this.policyEngine.grantsFeatureAnywhere(toolId);
+        }
+        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.
+     */
+    reportToolFailure(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 toolbar could not load a tool's module. The failure follows
+     * the start-failure policy: the tool degrades, so the toolbar withholds it,
+     * unless policy grants it. Reported once per tool however many toolbars fail
+     * to load it. Every report re-announces the request targets, since the
+     * reporting toolbar no longer hosts the tool.
+     */
+    reportToolModuleFailure(toolId, error) {
+        this.toolRequests.notifyTargetsChange();
+        if (this.toolModuleFailures.has(toolId))
+            return;
+        this.toolModuleFailures.add(toolId);
+        const detail = error instanceof Error && error.message.trim().length > 0
+            ? error.message
+            : String(error);
+        this.reportToolFailure(new Error(`Tool "${toolId}" failed to load: ${detail}`, { cause: error }), { phase: "tool-module-load", details: { toolId } }, [toolId]);
+    }
+    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.
      *
@@ -444,15 +587,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 {
@@ -463,14 +611,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);
             },
         };
     }
@@ -492,12 +642,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;
@@ -513,6 +663,7 @@ export class ToolkitCoordinator {
                     this.elementToolStateStore.loadState(state);
                 }
                 this.stateLoaded = true;
+                this.stateLoadSettled = true;
                 await this.emitTelemetry("pie-toolkit-tool-state-loaded", {
                     hasState: Boolean(state),
                 });
@@ -520,13 +671,89 @@ 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.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 "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, 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;
+        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,
+                toolRegistry: this.toolRegistry,
+            });
+            if (heldBackend)
+                this.reportMissingTTSProvider(heldBackend);
+            return false;
+        }
+        this.toolRegistrySettled = true;
+        this.toolRegistry = registry;
+        this.config.toolRegistry = registry;
+        try {
+            // Warn at most: the config was accepted at construction, and a binding
+            // toolkit has no caller to throw to.
+            this.config.tools = this.validateToolsConfig(this.config.tools, {
+                strictness: strictness === "off" ? "off" : "warn",
+                source,
+                toolRegistry: registry,
+            });
+        }
+        catch (err) {
+            console.warn("[ToolkitCoordinator] Tool config does not validate against the adopted tool registry:", err);
+        }
+        this.policyEngine.replaceToolRegistry(registry, this.config.tools);
+        const ttsStarted = this.ttsInitialized ||
+            this.ttsInitPromise !== undefined ||
+            this.ttsReconfigurePromise !== undefined;
+        for (const tool of this.getProviderDescriptorTools()) {
+            if (ttsStarted && tool.toolId === "textToSpeech")
+                continue;
+            void this.registerProviderFromTool(tool);
+        }
+        if (ttsStarted)
+            this.scheduleTTSReconfigure();
+        return true;
+    }
     /**
      * Register tool providers in the registry
      */
@@ -539,61 +766,63 @@ export class ToolkitCoordinator {
     getProviderDescriptorTools() {
         return this.toolRegistry.getAllTools().filter((tool) => !!tool.provider);
     }
-    async registerProviderFromTool(tool) {
+    /**
+     * Register the provider `tool`'s descriptor creates for the tool's current
+     * 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, replace = false) {
         const descriptor = tool.provider;
         if (!descriptor)
             return;
-        const toolConfig = this.getToolConfig(tool.toolId) || undefined;
-        if (toolConfig?.enabled === false)
-            return;
-        const providerId = descriptor.getProviderId?.(toolConfig) ??
-            toolConfig?.provider?.id ??
-            tool.toolId;
-        if (this.toolProviderRegistry.has(providerId))
+        const { toolId } = tool;
+        let registration;
+        try {
+            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;
+            }
+            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, initConfig);
+            const registryTelemetry = this.createToolTelemetryForwarder(toolId);
+            const authFetcher = descriptor.getAuthFetcher?.(toolConfig) ??
+                toolConfig?.provider?.runtime?.authFetcher;
+            registration = {
+                provider,
+                config: initConfigWithTelemetry,
+                lazy: descriptor.lazy ?? true,
+                authFetcher,
+                onTelemetry: registryTelemetry,
+            };
+        }
+        catch (err) {
+            this.reportProviderRegisterFailure(err, 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 authFetcher = descriptor.getAuthFetcher?.(toolConfig) ??
-            toolConfig?.provider?.runtime?.authFetcher;
-        await this.registerProvider(providerId, {
-            provider,
-            config: initConfigWithTelemetry,
-            lazy: descriptor.lazy ?? true,
-            authFetcher,
-            onTelemetry: registryTelemetry,
-        });
+        }
+        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);
@@ -602,44 +831,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) {
-            console.warn(`[ToolkitCoordinator] Failed to register provider "${providerId}":`, err);
-            this.handleError(err, { phase: "provider-register", providerId });
+            this.reportProviderRegisterFailure(err, toolId);
         }
     }
-    async ensureProviderReady(providerId) {
+    /**
+     * A console warning and a `provider-register` framework error, under the
+     * start-failure policy every other tool failure follows.
+     */
+    reportProviderRegisterFailure(err, toolId) {
+        console.warn(`[ToolkitCoordinator] Failed to register the provider of tool "${toolId}":`, err);
+        this.reportToolFailure(err, { phase: "provider-register", toolId }, [toolId]);
+    }
+    async ensureProviderReady(toolId) {
+        return this.initializeProvider(toolId, false);
+    }
+    /** `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();
-                await this.toolProviderRegistry.initialize(providerId);
+                // 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.hooks.onProviderReady?.(providerId, meta);
+                await this.toolProviderRegistry.initialize(toolId);
                 this.assertNotDisposed();
-                await this.emitTelemetry("pie-toolkit-provider-ready", { providerId });
+                // 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", { toolId });
                 this.assertNotDisposed();
                 return provider;
             }
@@ -647,13 +890,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.reportToolFailure(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) {
@@ -663,7 +909,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 });
             });
         }
     }
@@ -686,8 +932,11 @@ export class ToolkitCoordinator {
         // 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) {
+        // 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);
@@ -702,7 +951,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);
         }
@@ -980,18 +1231,29 @@ export class ToolkitCoordinator {
         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
@@ -1004,8 +1266,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,
@@ -1018,6 +1285,7 @@ export class ToolkitCoordinator {
         })
             .catch((err) => {
             this.handleSectionControllerInitError(err, args);
+            this.deliverSectionStartError(mapKey, err);
             throw err;
         })
             .finally(() => {
@@ -1098,7 +1366,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,
@@ -1110,6 +1391,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()
@@ -1135,6 +1432,7 @@ export class ToolkitCoordinator {
                     sectionId: args.key.sectionId,
                     attemptId: args.key.attemptId,
                 },
+                recoverable: true,
             });
         }
         finally {
@@ -1190,7 +1488,33 @@ export class ToolkitCoordinator {
                 sectionId: args.sectionId,
                 attemptId: args.attemptId,
             },
-        });
+            recoverable: false,
+        }, "cohort");
+    }
+    /**
+     * 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 = {
@@ -1277,6 +1601,7 @@ export class ToolkitCoordinator {
                     sectionId: args.args.sectionId,
                     attemptId: args.args.attemptId,
                 },
+                recoverable: true,
             });
         }
         finally {
@@ -1376,7 +1701,7 @@ 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()) {
@@ -1430,6 +1755,7 @@ export class ToolkitCoordinator {
             .then(() => this.assertNotDisposed())
             .finally(() => {
             this.ttsInitPromise = undefined;
+            this.notifyReadyChange();
         });
         return this.ttsInitPromise;
     }
@@ -1463,9 +1789,10 @@ export class ToolkitCoordinator {
             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", {
@@ -1477,25 +1804,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",
@@ -1505,10 +1821,16 @@ export class ToolkitCoordinator {
                 console.warn("[ToolkitCoordinator] Failed to initialize TTS via registry, falling back to browser provider:", normalized);
             }
         }
-        // Fallback to browser provider
+        else if (resolvedBackend !== "browser") {
+            this.reportMissingTTSProvider(resolvedBackend);
+        }
+        // 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",
             });
@@ -1523,7 +1845,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.reportToolFailure(normalized, { phase: "tts-init" }, ["textToSpeech"]);
             await this.emitTelemetry("pie-toolkit-tts-init-error", {
                 message: normalized.message,
             });
@@ -1542,7 +1864,7 @@ export class ToolkitCoordinator {
     }
     async initializeTTSService(provider, config) {
         const nextProviderOptions = {
-            ...((config.providerOptions || {}) || {}),
+            ...config.providerOptions,
             __pieTelemetry: async (eventName, payload) => {
                 await this.emitTelemetry(eventName, {
                     toolId: "textToSpeech",
@@ -1555,93 +1877,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())
@@ -1651,9 +1894,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) {
@@ -1670,41 +1912,52 @@ 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(this.getTTSConfigFromProviders());
+        }
+        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() {
-        const providers = this.config.tools?.providers || {};
-        return providers.textToSpeech;
+        return this.config.tools?.providers?.textToSpeech;
     }
     assertCanonicalToolId(toolId) {
         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.
-        // `normalizeAndValidateToolsConfig` already reports the missing registry
-        // once, as `tools.registryUnavailable`; a second report per call is noise.
+        // Validation reports the missing registry once per coordinator, as
+        // `tools.registryUnavailable`; a report per call would be noise.
         if (this.toolRegistry.getAllToolIds().length === 0)
             return;
         if (!this.toolRegistry.get(toolId)) {
@@ -1724,6 +1977,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);
@@ -1739,39 +1997,20 @@ 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;
-    }
-    /**
-     * Get tool configuration.
-     *
-     * @param toolId Tool identifier
-     * @returns Tool configuration or null if not configured
-     */
     getToolConfig(toolId) {
         this.assertCanonicalToolId(toolId);
-        return (this.config.tools?.providers?.[toolId] || null);
+        return this.config.tools?.providers?.[toolId] || null;
     }
     updateToolConfig(toolId, updates) {
         // Update config
         this.assertCanonicalToolId(toolId);
         const current = this.getToolConfig(toolId) || {};
         if (!this.config.tools) {
-            this.config.tools = normalizeAndValidateToolsConfig(undefined, {
+            this.config.tools = this.validateToolsConfig(undefined, {
                 strictness: this.config.toolConfigStrictness ?? "error",
                 source: "ToolkitCoordinator.updateToolConfig",
                 toolRegistry: this.toolRegistry,
-            }).config;
+            });
         }
         if (!this.config.tools.providers) {
             this.config.tools.providers = {};
@@ -1780,7 +2019,7 @@ export class ToolkitCoordinator {
             ...(this.config.tools.providers || {}),
             [toolId]: mergeToolConfigUpdate(toolId, current, updates),
         };
-        const validated = normalizeAndValidateToolsConfig({
+        this.config.tools = this.validateToolsConfig({
             ...this.config.tools,
             providers: nextProviders,
         }, {
@@ -1788,39 +2027,30 @@ export class ToolkitCoordinator {
             source: "ToolkitCoordinator.updateToolConfig",
             toolRegistry: this.toolRegistry,
         });
-        this.config.tools = validated.config;
-        // 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.
+        // The engine's tools input follows the validated config; its `inputs`
+        // change event is what makes toolbars re-decide.
         this.policyEngine.updateInputs({
             tools: this.config.tools,
         });
         void this.emitTelemetry("pie-toolkit-tool-config-updated", { toolId });
         // Apply configuration changes to services
-        this._applyToolConfigChange(toolId, updates);
+        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 = normalizeAndValidateToolsConfig(undefined, {
+            this.config.tools = this.validateToolsConfig(undefined, {
                 strictness: this.config.toolConfigStrictness ?? "error",
                 source: "ToolkitCoordinator.updateToolsPlacement",
                 toolRegistry: this.toolRegistry,
-            }).config;
+            });
         }
         const currentPlacement = this.config.tools?.placement ?? {
             section: [],
@@ -1832,7 +2062,7 @@ export class ToolkitCoordinator {
             item: [...(partial.item ?? currentPlacement.item ?? [])],
             passage: [...(partial.passage ?? currentPlacement.passage ?? [])],
         };
-        const validated = normalizeAndValidateToolsConfig({
+        const validated = this.validateToolsConfig({
             ...this.config.tools,
             placement: nextPlacement,
         }, {
@@ -1840,8 +2070,8 @@ export class ToolkitCoordinator {
             source: "ToolkitCoordinator.updateToolsPlacement",
             toolRegistry: this.toolRegistry,
         });
-        validated.config.placement = nextPlacement;
-        this.config.tools = validated.config;
+        validated.placement = nextPlacement;
+        this.config.tools = validated;
         this.policyEngine.updateInputs({
             tools: this.config.tools,
         });
@@ -1849,10 +2079,40 @@ export class ToolkitCoordinator {
     /**
      * 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;
+    }
+    /**
+     * Log each policy diagnostic as a console warning, once per code and tool
+     * id, and per item for `tool-policy.itemSettingNotApplied`. Decisions re-run
+     * on every input change, so a conflict would otherwise repeat on each.
+     */
+    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.warnedPolicyDiagnostics.has(key))
+                continue;
+            this.warnedPolicyDiagnostics.add(key);
+            console.warn(`[ToolkitCoordinator] ${diagnostic.message}`);
+        }
+    }
+    /**
+     * 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
@@ -1867,10 +2127,23 @@ export class ToolkitCoordinator {
      * capability it asks about, which is indistinguishable from a student who was
      * properly declined — so without this, forgetting {@link updateAssessment}
      * presents as an accommodation that silently never appears.
+     *
+     * A coordinator built with `assessmentOptional` reports only while PNP
+     * 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);
-        if (!decision.assessmentBound && !this.reportedUnboundFeaturePolicy) {
+    decideFeaturePolicy(featureId, scope) {
+        const decision = this.policyEngine.decideFeature(featureId, scope);
+        this.warnPolicyDiagnostics(decision.diagnostics);
+        const unboundIsMisconfigured = this.config.assessmentOptional !== true ||
+            this.pnpEnforcementOverride === "on";
+        if (!decision.assessmentBound &&
+            unboundIsMisconfigured &&
+            !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.`);
         }
@@ -1879,9 +2152,10 @@ export class ToolkitCoordinator {
     /**
      * 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
@@ -1911,49 +2185,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(),
-        });
-    }
-    /**
-     * 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(),
-        });
+        this.policyEngine.updateInputs({ assessment });
     }
     /**
-     * Override the auto-mode PNP/profile enforcement decision.
+     * Override the auto-mode PNP/profile enforcement decision; `null` returns
+     * to auto-mode.
      */
     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
@@ -1977,29 +2228,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);
@@ -2047,6 +2275,9 @@ export class ToolkitCoordinator {
             this.toolContextResolverChangeListeners.delete(listener);
         };
     }
+    getToolRegistry() {
+        return this.toolRegistry;
+    }
     /**
      * Claim requests for one placement level. Called by a toolbar on mount.
      */
@@ -2070,39 +2301,18 @@ 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;
@@ -2111,46 +2321,70 @@ export class ToolkitCoordinator {
      * Apply tool configuration changes to underlying services.
      * Called after updateToolConfig().
      */
-    _applyToolConfigChange(toolId, _updates) {
+    _applyToolConfigChange(toolId) {
         if (this.disposePromise !== null)
             return;
-        // Apply configuration changes based on tool
-        switch (toolId) {
-            case "textToSpeech": {
-                const reconfigurePromise = this._reconfigureTTSProvider();
-                this.ttsReconfigurePromise = reconfigurePromise;
-                void reconfigurePromise.finally(() => {
-                    if (this.ttsReconfigurePromise === reconfigurePromise) {
-                        this.ttsReconfigurePromise = undefined;
-                    }
-                });
-                void reconfigurePromise.then(async () => {
-                    if (this.disposePromise !== null)
-                        return;
-                    const ttsConfig = this.getTTSConfigFromProviders();
-                    if (!this.lazyInit && ttsConfig?.enabled !== false) {
-                        await this.ensureTTSReady(ttsConfig);
-                    }
-                });
-                break;
-            }
-            case "answerEliminator":
-                // Future: Could notify answer eliminator tools of strategy change
-                break;
-            // Add cases for other tools as needed
+        if (toolId === "textToSpeech") {
+            this.scheduleTTSReconfigure();
+            return;
         }
+        this._registerChangedToolProvider(toolId);
+    }
+    /**
+     * 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) {
+        const registration = this.getProviderDescriptorTools().find((tool) => tool.toolId === toolId);
+        if (!registration)
+            return;
+        // A failure of the replaced provider no longer describes the tool.
+        this.degradedTools.delete(toolId);
+        void this.registerProviderFromTool(registration, true);
+    }
+    /**
+     * 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.
+     */
+    scheduleTTSReconfigure() {
+        const inFlight = this.ttsInitPromise;
+        const reconfigurePromise = inFlight
+            ? inFlight.catch(() => { }).then(() => this._reconfigureTTSProvider())
+            : this._reconfigureTTSProvider();
+        this.ttsReconfigurePromise = reconfigurePromise;
+        void reconfigurePromise.finally(() => {
+            if (this.ttsReconfigurePromise === reconfigurePromise) {
+                this.ttsReconfigurePromise = undefined;
+            }
+        });
+        void reconfigurePromise
+            .then(async () => {
+            if (this.disposePromise !== null)
+                return;
+            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;