@pie-players/pie-assessment-toolkit 0.3.75 → 1.0.0-beta.1

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";
@@ -51,6 +59,16 @@ const mergeToolConfigUpdate = (toolId, current, updates) => {
     }
     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",
@@ -74,10 +92,8 @@ 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,
- * });
+ * // Exported by @pie-players/pie-default-tool-loaders
+ * const toolRegistry = createPackagedToolRegistry();
  *
  * // Create coordinator with configuration
  * const coordinator = new ToolkitCoordinator({
@@ -122,7 +138,6 @@ export class ToolkitCoordinator {
     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.
@@ -137,8 +152,8 @@ export class ToolkitCoordinator {
      * tools reports its failure again as fatal.
      */
     degradedTools = new Map();
-    /** Tools a toolbar reported a module failure for, each reported once. */
-    toolModuleFailures = new Set();
+    /** Tool failures already reported, by phase and tool, each reported once. */
+    reportedToolFailures = new Set();
     readyChangeListeners = new Set();
     eagerInit;
     toolRegistry;
@@ -157,7 +172,7 @@ export class ToolkitCoordinator {
     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();
@@ -165,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
@@ -178,8 +193,8 @@ 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, and `null` while the next requested
      * cohort is still starting.
@@ -196,6 +211,8 @@ export class ToolkitCoordinator {
     telemetryListeners = new Set();
     frameworkErrorBus;
     ownsFrameworkErrorBus;
+    /** The instance behind {@link toolCoordinator}, kept for disposal. */
+    ownedToolCoordinator;
     frameworkErrorHookUnsubscribe = null;
     disposePromise = null;
     /**
@@ -206,20 +223,12 @@ export class ToolkitCoordinator {
      */
     policyEngine;
     /**
-     * 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 swaps until the host clears
-     * the override by calling `setPnpEnforcement(null)`.
-     */
-    pnpEnforcementOverride = null;
-    /**
-     * Policy diagnostics already logged, keyed by code, tool id and, for
-     * `tool-policy.itemSettingNotApplied`, item id; see
+     * Policy diagnostics reported since the last input change, keyed by code,
+     * tool id and, for `tool-policy.itemSettingNotApplied`, item id; see
      * {@link warnPolicyDiagnostics}.
      */
-    warnedPolicyDiagnostics = new Set();
+    reportedPolicyDiagnostics = new Map();
+    policyDiagnosticListeners = new Set();
     /**
      * Whether {@link decideFeaturePolicy} has already reported serving a decision
      * with no assessment bound.
@@ -324,7 +333,6 @@ export class ToolkitCoordinator {
         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
         // pre-coordinator failures from the CE flow through the same
@@ -333,15 +341,13 @@ 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.
@@ -359,15 +365,23 @@ export class ToolkitCoordinator {
         this.policyEngine = new ToolPolicyEngine({
             toolRegistry: this.toolRegistry,
             contextId: `toolkit-coordinator:${this.assessmentId}`,
+            assessmentOptional: this.config.assessmentOptional === true,
             inputs: {
                 tools: this.config.tools,
                 assessment: null,
-                pnpEnforcement: this.pnpEnforcementOverride,
+                pnpEnforcement: this.resolveConfiguredPnpEnforcement(),
             },
         });
+        // 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")
-                this.reportNewlyGrantedFailures();
+            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) => {
@@ -460,25 +474,30 @@ export class ToolkitCoordinator {
     }
     /**
      * Every report site states whether the coordinator carries on after the
-     * failure; one that takes down only its section passes `scope: "cohort"`.
+     * failure; one that takes down only its section passes that section.
      */
-    handleError(error, context, scope = "runtime") {
+    handleError(error, context, cohort) {
         const model = frameworkErrorFromCoordinatorContext({
             error,
             context,
             recoverable: context.recoverable,
-            scope,
+            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. Read without the unbound-assessment warning.
+     * 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);
+            return this.policyEngine.grantsFeatureAnywhere(toolId, {
+                enforced: this.toolRegistry.getToolActivation(toolId) !== "region",
+            });
         }
         catch {
             return false;
@@ -490,7 +509,7 @@ export class ToolkitCoordinator {
      * `fallbackFollows` marks a failure another path absorbs, which is recoverable
      * whatever the policy.
      */
-    reportToolFailure(error, context, toolIds, fallbackFollows = false) {
+    reportStartFailure(error, context, toolIds, fallbackFollows = false) {
         const ids = Array.from(toolIds);
         const recoverable = fallbackFollows || !ids.some((toolId) => this.isToolGranted(toolId));
         if (recoverable && !fallbackFollows) {
@@ -500,21 +519,32 @@ export class ToolkitCoordinator {
         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.
+     * 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.
      */
-    reportToolModuleFailure(toolId, error) {
-        this.toolRequests.notifyTargetsChange();
-        if (this.toolModuleFailures.has(toolId))
+    reportToolFailure(toolId, phase, error) {
+        if (phase === "tool-module-load")
+            this.toolRequests.notifyTargetsChange();
+        const key = `${phase}\u0000${toolId}`;
+        if (this.reportedToolFailures.has(key))
             return;
-        this.toolModuleFailures.add(toolId);
+        this.reportedToolFailures.add(key);
         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]);
+        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) {
@@ -573,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 || ""}`;
     }
@@ -662,7 +699,6 @@ 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),
@@ -754,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) {
@@ -853,7 +886,7 @@ export class ToolkitCoordinator {
      */
     reportProviderRegisterFailure(err, toolId) {
         console.warn(`[ToolkitCoordinator] Failed to register the provider of tool "${toolId}":`, err);
-        this.reportToolFailure(err, { phase: "provider-register", toolId }, [toolId]);
+        this.reportStartFailure(err, { phase: "provider-register", toolId }, [toolId]);
     }
     async ensureProviderReady(toolId) {
         return this.initializeProvider(toolId, false);
@@ -890,7 +923,7 @@ export class ToolkitCoordinator {
                 if (err instanceof ToolkitCoordinatorDisposedError)
                     throw err;
                 const error = err instanceof Error ? err : new Error(String(err));
-                this.reportToolFailure(error, { phase: "provider-init", toolId }, 
+                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);
@@ -920,21 +953,15 @@ 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. A listener
-        // added while the next section is still starting binds when it
-        // becomes active.
+        // 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.");
@@ -973,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
@@ -1032,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);
         }
@@ -1056,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
@@ -1071,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;
@@ -1084,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) {
@@ -1223,11 +1239,7 @@ 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);
@@ -1316,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
@@ -1457,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.
@@ -1489,7 +1499,7 @@ export class ToolkitCoordinator {
                 attemptId: args.attemptId,
             },
             recoverable: false,
-        }, "cohort");
+        }, { sectionId: args.sectionId, attemptId: args.attemptId });
     }
     /**
      * A section that fails to start has no controller of its own to emit its
@@ -1517,11 +1527,7 @@ export class ToolkitCoordinator {
         }
     }
     disposeSectionController(args) {
-        const key = {
-            assessmentId: this.assessmentId,
-            sectionId: args.sectionId,
-            attemptId: args.attemptId,
-        };
+        const key = this.sectionControllerKey(args);
         const mapKey = this.getSectionControllerMapKey(key);
         const initEntry = this.sectionControllerInitEntries.get(mapKey);
         if (initEntry) {
@@ -1538,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.
@@ -1704,14 +1709,13 @@ export class ToolkitCoordinator {
         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?.();
@@ -1741,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();
@@ -1751,7 +1755,7 @@ 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;
@@ -1766,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);
@@ -1788,7 +1792,6 @@ export class ToolkitCoordinator {
             operation: "tts-init",
             backend: resolvedBackend,
         });
-        // Try to use TTS provider from registry if available
         if (this.toolProviderRegistry.has("textToSpeech")) {
             try {
                 // Browser speech follows a server provider that fails to start.
@@ -1845,7 +1848,7 @@ export class ToolkitCoordinator {
             if (error instanceof ToolkitCoordinatorDisposedError)
                 throw error;
             const normalized = error instanceof Error ? error : new Error(String(error));
-            this.reportToolFailure(normalized, { phase: "tts-init" }, ["textToSpeech"]);
+            this.reportStartFailure(normalized, { phase: "tts-init" }, ["textToSpeech"]);
             await this.emitTelemetry("pie-toolkit-tts-init-error", {
                 message: normalized.message,
             });
@@ -1859,8 +1862,8 @@ export class ToolkitCoordinator {
             throw normalized;
         }
     }
-    resolveTTSToolConfig(config) {
-        return config || this.getTTSConfigFromProviders() || {};
+    resolveTTSToolConfig() {
+        return this.getTTSConfigFromProviders() || {};
     }
     async initializeTTSService(provider, config) {
         const nextProviderOptions = {
@@ -1933,7 +1936,7 @@ export class ToolkitCoordinator {
      */
     async startTTSForReadiness() {
         try {
-            await this.ensureTTSReady(this.getTTSConfigFromProviders());
+            await this.ensureTTSReady();
         }
         catch (error) {
             if (error instanceof ToolkitCoordinatorDisposedError)
@@ -1951,13 +1954,11 @@ export class ToolkitCoordinator {
         if (typeof toolId !== "string" || toolId.trim().length === 0) {
             throw new Error("Tool id must be a non-empty string.");
         }
-        // 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)) {
@@ -2002,7 +2003,6 @@ export class ToolkitCoordinator {
         return this.config.tools?.providers?.[toolId] || null;
     }
     updateToolConfig(toolId, updates) {
-        // Update config
         this.assertCanonicalToolId(toolId);
         const current = this.getToolConfig(toolId) || {};
         if (!this.config.tools) {
@@ -2016,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,
         }, {
@@ -2027,13 +2027,11 @@ export class ToolkitCoordinator {
             source: "ToolkitCoordinator.updateToolConfig",
             toolRegistry: this.toolRegistry,
         });
+        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: this.config.tools,
-        });
+        this.policyEngine.updateInputs({ tools: validated });
         void this.emitTelemetry("pie-toolkit-tool-config-updated", { toolId });
-        // Apply configuration changes to services
         this._applyToolConfigChange(toolId);
     }
     /**
@@ -2072,9 +2070,7 @@ 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.
@@ -2088,9 +2084,11 @@ export class ToolkitCoordinator {
         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.
+     * 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) {
@@ -2098,10 +2096,21 @@ export class ToolkitCoordinator {
                 ? diagnostic.details.itemId
                 : "";
             const key = `${diagnostic.code}\0${diagnostic.toolId}\0${itemId}`;
-            if (this.warnedPolicyDiagnostics.has(key))
+            if (this.reportedPolicyDiagnostics.has(key))
                 continue;
-            this.warnedPolicyDiagnostics.add(key);
+            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);
         }
     }
     /**
@@ -2123,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.
      *
@@ -2139,13 +2148,11 @@ export class ToolkitCoordinator {
     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.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;
     }
@@ -2169,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.
      *
@@ -2200,10 +2216,10 @@ export class ToolkitCoordinator {
     }
     /**
      * Override the auto-mode PNP/profile enforcement decision; `null` returns
-     * to auto-mode.
+     * to auto-mode. `"on"` and `"off"` stick across assessment swaps until
+     * cleared.
      */
     setPnpEnforcement(mode) {
-        this.pnpEnforcementOverride = mode;
         this.policyEngine.updateInputs({ pnpEnforcement: mode });
     }
     /**
@@ -2314,13 +2330,9 @@ export class ToolkitCoordinator {
         return this.toolRequests.onTargetsChange(listener);
     }
     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().
-     */
+    /** Apply an `updateToolConfig` change to the underlying services. */
     _applyToolConfigChange(toolId) {
         if (this.disposePromise !== null)
             return;