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

package/dist/services/ToolRegistry.js

@@ -1,12 +1,20 @@
 /**
- * Tool Registry
+ * Tool registry: the registration contract every tool declares itself with,
+ * the shape validation `register` and `override` run, and the `ToolRegistry`
+ * class.
  *
- * Central registry for all assessment tools. Manages tool metadata, visibility logic,
- * and button/instance creation. Supports dynamic registration and override by integrators.
+ * Layout: the exported contract types come first, ending with
+ * `ToolRegistration`, then `assertToolRegistrationShape`, then the class. Its
+ * members run from mutation and change observation, through queries and the
+ * filters for the second and third passes of tool resolution (relevance in
+ * `filterVisibleInContext`, applicability in `filterDecidedToolIds`; the policy
+ * engine owns the first), to module loading with its undefined-element
+ * warnings and the toolbar and surface render helpers.
  */
 import { dynamicMessageKey } from "@pie-players/pie-players-shared/i18n/provider";
 import { resolveToolTag, } from "../tools/tool-tag-map.js";
 import { PENDING_INPUT_WARNING_DELAY_MS, warnOncePerDocument, } from "../runtime/page-warnings.js";
+const logToolCallbackFailure = (toolId, phase, error) => console.error(`[ToolRegistry] Tool '${toolId}' ${phase} check threw:`, error);
 /**
  * A registration's display name in the interface locale.
  *
@@ -228,10 +236,7 @@ export class ToolRegistry {
         return toolIds.map((toolId) => this.normalizeToolId(toolId));
     }
     /**
-     * Register a tool
-     *
-     * @param registration - Tool registration
-     * @throws Error if toolId is already registered
+     * Register a tool. Throws when its `toolId` is already registered.
      */
     register(registration) {
         assertToolRegistrationShape(registration);
@@ -242,9 +247,8 @@ export class ToolRegistry {
         this.emitChange({ kind: "register", toolIds: [registration.toolId] });
     }
     /**
-     * Override an existing tool registration
-     *
-     * @param registration - New tool registration (must have existing toolId)
+     * Replace an existing tool registration. Throws when its `toolId` is not
+     * registered.
      */
     override(registration) {
         assertToolRegistrationShape(registration);
@@ -255,9 +259,7 @@ export class ToolRegistry {
         this.emitChange({ kind: "override", toolIds: [registration.toolId] });
     }
     /**
-     * Unregister a tool
-     *
-     * @param toolId - Tool ID to remove
+     * Unregister a tool. An unknown id is a no-op and emits no change.
      */
     unregister(toolId) {
         if (!this.tools.has(toolId))
@@ -265,46 +267,21 @@ export class ToolRegistry {
         this.tools.delete(toolId);
         this.emitChange({ kind: "unregister", toolIds: [toolId] });
     }
-    /**
-     * Get a tool registration by ID
-     *
-     * @param toolId - Tool ID
-     * @returns Tool registration or undefined
-     */
     get(toolId) {
         return this.tools.get(toolId);
     }
-    /**
-     * Check if a tool is registered
-     *
-     * @param toolId - Tool ID
-     * @returns true if registered
-     */
     has(toolId) {
         return this.tools.has(toolId);
     }
-    /**
-     * Get all registered tool IDs
-     *
-     * @returns Array of tool IDs
-     */
+    /** Registered tool ids, in registration order. */
     getAllToolIds() {
         return Array.from(this.tools.keys());
     }
-    /**
-     * Get all tool registrations
-     *
-     * @returns Array of tool registrations
-     */
+    /** Registrations, in registration order. */
     getAllTools() {
         return Array.from(this.tools.values());
     }
-    /**
-     * Get tools that support a specific level
-     *
-     * @param level - Tool level (assessment, section, item, passage, element)
-     * @returns Array of tool registrations that support this level
-     */
+    /** Registrations whose `supportedLevels` include `level`. */
     getToolsByLevel(level) {
         return this.getAllTools().filter((tool) => tool.supportedLevels.includes(level));
     }
@@ -355,16 +332,14 @@ export class ToolRegistry {
         return toolIds.filter((toolId) => this.getToolActivation(toolId) === activation);
     }
     /**
-     * Filter tools by visibility in a given context
-     *
-     * Pass 2 of the three-pass model: Given a list of allowed tool IDs (from Pass 1),
-     * ask each tool if it's relevant in this context.
+     * Pass 2 of tool resolution: the registrations among `allowedToolIds` (the
+     * ids policy allowed in pass 1) that support `context.level` and answer
+     * `isVisibleInContext` with `true`.
      *
-     * @param allowedToolIds - Tool IDs that passed Pass 1 (orchestrator approval)
-     * @param context - Context to evaluate
-     * @returns Array of visible tool registrations
+     * @param onFailure - Receives a relevance check's throw; the tool is then not
+     *   visible. Logs when omitted.
      */
-    filterVisibleInContext(allowedToolIds, context) {
+    filterVisibleInContext(allowedToolIds, context, onFailure = logToolCallbackFailure) {
         const visible = [];
         for (const toolId of allowedToolIds) {
             const tool = this.get(toolId);
@@ -376,19 +351,18 @@ export class ToolRegistry {
                 }
                 continue;
             }
-            // Check if tool supports this level
             if (!tool.supportedLevels.includes(context.level)) {
                 continue;
             }
-            // Pass 2: Ask tool if it's relevant. A region capability declares no
-            // answer and has no toolbar presence, so it is never visible here.
+            // A region capability declares no answer and has no toolbar presence,
+            // so it is never visible here.
             try {
                 if (tool.isVisibleInContext?.(context)) {
                     visible.push(tool);
                 }
             }
             catch (error) {
-                console.error(`Error evaluating visibility for tool '${toolId}':`, error);
+                onFailure(toolId, "tool-visibility", error);
             }
         }
         return visible;
@@ -405,8 +379,10 @@ export class ToolRegistry {
      *
      * @param toolId - Tool to ask
      * @param contexts - Every context the tool could act on at this placement
+     * @param onFailure - Receives the gate's throw; the tool then counts as
+     *   applicable. Logs when omitted.
      */
-    isApplicableToAnyContext(toolId, contexts) {
+    isApplicableToAnyContext(toolId, contexts, onFailure = logToolCallbackFailure) {
         const tool = this.get(toolId);
         if (!tool?.isApplicableToContent)
             return true;
@@ -417,17 +393,64 @@ export class ToolRegistry {
                 return tool.isApplicableToContent?.(context) ?? true;
             }
             catch (error) {
-                console.error(`Error evaluating applicability for tool '${toolId}':`, error);
+                onFailure(toolId, "tool-applicability", error);
                 // A gate that throws has not established that the tool is useless.
                 return true;
             }
         });
     }
     /**
-     * Get tool metadata for building UIs
-     * Useful for building PNP configuration interfaces
+     * Passes 2 and 3 over a policy decision's tools: the ids a surface at `level`
+     * shows against `contexts`, in decision order. This is the rule a toolbar
+     * applies, for a host that builds its own tool surface.
      *
-     * @returns Array of tool metadata (id, name, description, levels, activation)
+     * - A tool that does not support `level` is dropped.
+     * - Relevance (`isVisibleInContext`) keeps a tool visible in any one context.
+     *   It does not run for a granted entry (`required` or `alwaysAvailable`),
+     *   at section level, whose relevance is item-dependent, or when `contexts`
+     *   is empty, since content that has not resolved cannot rule a tool out.
+     * - Applicability (`isApplicableToContent`) then removes a tool that can act
+     *   on none of `contexts`, granted or not. It does not run at section level.
+     *
+     * @param entries - The decision's surviving entries (Pass 1), such as
+     *   `ToolPolicyDecision.visibleTools`
+     * @param level - The level of the surface the tools render on
+     * @param contexts - Every context the tools could act on at that surface
+     * @param onFailure - Receives a relevance or applicability check's throw.
+     *   Logs when omitted.
+     */
+    filterDecidedToolIds(entries, level, contexts, onFailure = logToolCallbackFailure) {
+        const granted = new Set();
+        const decided = [];
+        for (const entry of entries) {
+            const toolId = this.normalizeToolId(entry.toolId);
+            if (!toolId)
+                continue;
+            if (entry.required || entry.alwaysAvailable)
+                granted.add(toolId);
+            if (decided.includes(toolId))
+                continue;
+            if (!this.get(toolId)?.supportedLevels.includes(level))
+                continue;
+            decided.push(toolId);
+        }
+        if (level === "section")
+            return decided;
+        const relevant = new Set(contexts.length === 0
+            ? decided
+            : decided.filter((toolId) => granted.has(toolId)));
+        for (const context of contexts) {
+            const ungranted = decided.filter((toolId) => !relevant.has(toolId));
+            for (const tool of this.filterVisibleInContext(ungranted, context, onFailure)) {
+                relevant.add(tool.toolId);
+            }
+        }
+        return decided.filter((toolId) => relevant.has(toolId) &&
+            this.isApplicableToAnyContext(toolId, contexts, onFailure));
+    }
+    /**
+     * Plain metadata for every registration, in registration order, for UIs
+     * such as a PNP configuration screen.
      */
     getToolMetadata() {
         return this.getAllTools().map((tool) => ({
@@ -575,7 +598,7 @@ export class ToolRegistry {
         const timer = setTimeout(() => {
             if (customElements.get(tagName))
                 return;
-            warnOncePerDocument(doc, `undefinedToolElement.${toolId}`, `[ToolRegistry] Tool "${toolId}" renders <${tagName}>, which is still undefined after ${PENDING_INPUT_WARNING_DELAY_MS / 1000} s, and its registry has no module loader for it. Pass toolModuleLoaders to createPackagedToolRegistry (DEFAULT_TOOL_MODULE_LOADERS from @pie-players/pie-default-tool-loaders loads the stock tools), register one with setToolModuleLoaders, or import the tool's package before it renders. Reported once per page.`);
+            warnOncePerDocument(doc, `undefinedToolElement.${toolId}`, `[ToolRegistry] Tool "${toolId}" renders <${tagName}>, which is still undefined after ${PENDING_INPUT_WARNING_DELAY_MS / 1000} s, and its registry has no module loader for it. Register one with setToolModuleLoaders or import the tool's package before it renders; a registry from createPackagedToolRegistry has the packaged loaders unless its toolModuleLoaders replaced them. Reported once per page.`);
         }, PENDING_INPUT_WARNING_DELAY_MS);
         void customElements.whenDefined(tagName).then(() => clearTimeout(timer));
     }
@@ -615,10 +638,7 @@ export class ToolRegistry {
         }
         const mergedContext = {
             ...toolbarContext,
-            componentOverrides: {
-                ...(this.componentOverrides || {}),
-                ...(toolbarContext.componentOverrides || {}),
-            },
+            componentOverrides: this.mergeComponentOverrides(toolbarContext.componentOverrides),
         };
         return tool.renderToolbar(context, mergedContext);
     }
@@ -641,10 +661,14 @@ export class ToolRegistry {
         }
         return tool.renderSurface({
             ...context,
-            componentOverrides: {
-                ...(this.componentOverrides || {}),
-                ...(context.componentOverrides || {}),
-            },
+            componentOverrides: this.mergeComponentOverrides(context.componentOverrides),
         });
     }
+    /** The registry's component overrides, with the caller's taking precedence. */
+    mergeComponentOverrides(contextOverrides) {
+        return {
+            ...(this.componentOverrides || {}),
+            ...(contextOverrides || {}),
+        };
+    }
 }

package/dist/services/ToolkitCoordinator.d.ts

@@ -1,19 +1,27 @@
 /**
- * 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 type { AccessibilityCatalog, AssessmentEntity, ItemSettings } from "@pie-players/pie-players-shared/types";
+import type { AccessibilityCatalog, AssessmentEntity, ItemSettings, ToolParametersFor } from "@pie-players/pie-players-shared/types";
 import { type CanonicalToolsConfig, type ToolPlacementConfig, type ToolPolicyConfig, type TextToSpeechToolProviderConfig, type ToolProviderConfig, type ToolProvidersConfig, type ToolsConfigInput } from "./tools-config-normalizer.js";
 import { type ToolConfigStrictness } from "./tool-config-validation.js";
 import { AccessibilityCatalogResolver } from "./AccessibilityCatalogResolver.js";
@@ -22,14 +30,15 @@ import { ElementToolStateStore } from "./ElementToolStateStore.js";
 import { type FrameworkErrorModel } from "./framework-error.js";
 import { FrameworkErrorBus, type FrameworkErrorListener } from "./framework-error-bus.js";
 import { HighlightCoordinator } from "./HighlightCoordinator.js";
-import { ToolCoordinator } from "./ToolCoordinator.js";
+import type { ToolCoordinatorApi } from "./interfaces.js";
 import { TTSService } from "./TTSService.js";
 import { ToolProviderRegistry } from "./tool-providers/index.js";
 import type { ToolProviderApi } from "./tool-providers/ToolProviderApi.js";
 import { ToolRegistry } from "./ToolRegistry.js";
 import type { ResolvedToolContext, ToolContextResolverContext, ToolContextResolverMap } from "./ToolRegistry.js";
+import type { ToolFailurePhase } from "./tool-failure.js";
 import type { ToolOpenRequest, ToolRequestTarget } from "./tool-request.js";
-import { type FeaturePolicyDecision, type PnpEnforcementMode, type PolicySource, type ResolvedEngineInputs, type ToolPolicyChangeListener, type ToolPolicyDecision, type ToolPolicyDecisionRequest, type ToolScope } from "../policy/engine.js";
+import { type FeaturePolicyDecision, type PnpEnforcementMode, type PolicySource, type ResolvedEngineInputs, type ToolPolicyChangeListener, type ToolPolicyDecision, type ToolPolicyDecisionRequest, type ToolPolicyDiagnostic, type ToolScope } from "../policy/engine.js";
 import type { SectionControllerContext, SectionControllerEvent, SectionControllerEventType, SectionControllerFactoryDefaults, SectionControllerHandle, SectionControllerKey, SectionControllerSessionState, SectionSessionPersistenceStrategy, SectionPersistenceFactoryDefaults } from "./section-controller-types.js";
 export type { SectionControllerContext, SectionControllerEvent, SectionControllerEventType, SectionControllerFactoryDefaults, SectionControllerHandle, SectionControllerKey, SectionControllerLoadedRenderable, SectionSessionPersistenceConfig, SectionSessionPersistenceStrategy, SectionControllerRuntimeState, SectionControllerSessionState, SectionPersistenceFactoryDefaults, } from "./section-controller-types.js";
 export type { FeaturePolicyDecision, PnpEnforcementMode, ResolvedEngineInputs, ToolPolicyChangeListener, ToolPolicyDecision, ToolPolicyDecisionRequest, } from "../policy/engine.js";
@@ -137,7 +146,7 @@ export interface ToolkitCoordinatorConfig {
     frameworkErrorBus?: FrameworkErrorBus;
 }
 export interface ToolkitErrorContext {
-    phase: "coordinator-ready" | "state-load" | "state-save" | "provider-register" | "provider-init" | "tts-init" | "section-controller-init" | "section-controller-dispose" | "tool-module-load";
+    phase: "coordinator-ready" | "state-load" | "state-save" | "provider-register" | "provider-init" | "tts-init" | "section-controller-init" | "section-controller-dispose" | ToolFailurePhase;
     /** The tool whose provider failed. */
     toolId?: string;
     details?: Record<string, unknown>;
@@ -154,8 +163,8 @@ export interface SectionControllerLifecycleEvent {
 /**
  * Subscribe-time arguments for {@link ToolkitCoordinator.subscribeSectionEvents}.
  *
- * Phase D contract: subscriptions follow the toolkit's *active section
- * cohort* automatically. The listener is bound to whatever section
+ * Subscriptions follow the toolkit's *active section cohort*
+ * automatically. The listener is bound to whatever section
  * controller is active at subscribe time and is migrated, with snapshot
  * replay, on every cohort transition. There is no per-subscription
  * `(sectionId, attemptId)` binding.
@@ -176,8 +185,8 @@ export type SectionScopedEvent = Extract<SectionControllerEvent, {
 /**
  * Subscribe-time arguments for {@link ToolkitCoordinator.subscribeItemEvents}.
  *
- * See {@link SectionEventSubscriptionArgs} for the Phase D active-cohort
- * binding contract.
+ * See {@link SectionEventSubscriptionArgs} for the active-cohort binding
+ * contract.
  */
 export interface SectionItemEventSubscriptionArgs {
     listener: (event: SectionItemEvent) => void;
@@ -188,8 +197,8 @@ export interface SectionItemEventSubscriptionArgs {
  * Subscribe-time arguments for
  * {@link ToolkitCoordinator.subscribeSectionLifecycleEvents}.
  *
- * See {@link SectionEventSubscriptionArgs} for the Phase D active-cohort
- * binding contract.
+ * See {@link SectionEventSubscriptionArgs} for the active-cohort binding
+ * contract.
  */
 export interface SectionScopedEventSubscriptionArgs {
     listener: (event: SectionScopedEvent) => void;
@@ -240,10 +249,8 @@ export type ToolkitTelemetryListener = (args: {
  *
  * @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({
@@ -275,7 +282,7 @@ export declare class ToolkitCoordinator {
     readonly config: ToolkitCoordinatorConfig;
     /** Managed services (public for direct access) */
     readonly ttsService: TTSService;
-    readonly toolCoordinator: ToolCoordinator;
+    readonly toolCoordinator: ToolCoordinatorApi;
     readonly highlightCoordinator: HighlightCoordinator;
     readonly elementToolStateStore: ElementToolStateStore;
     readonly catalogResolver: AccessibilityCatalogResolver;
@@ -288,7 +295,6 @@ export declare class ToolkitCoordinator {
     private ttsDegraded;
     private ttsInitPromise?;
     private ttsReconfigurePromise?;
-    private stateLoaded;
     /**
      * The loader ran, whether or not it returned state. A failed load is
      * reported once and the coordinator runs without saved tool state.
@@ -303,8 +309,8 @@ export declare class ToolkitCoordinator {
      * tools reports its failure again as fatal.
      */
     private readonly degradedTools;
-    /** Tools a toolbar reported a module failure for, each reported once. */
-    private readonly toolModuleFailures;
+    /** Tool failures already reported, by phase and tool, each reported once. */
+    private readonly reportedToolFailures;
     private readonly readyChangeListeners;
     private readonly eagerInit;
     private toolRegistry;
@@ -331,8 +337,8 @@ export declare class ToolkitCoordinator {
     private readonly sectionPersistenceStrategies;
     private readonly sectionControllerLifecycleListeners;
     /**
-     * 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
@@ -344,8 +350,8 @@ export declare class ToolkitCoordinator {
      */
     private readonly activeSubscriptions;
     /**
-     * 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.
@@ -362,6 +368,8 @@ export declare class ToolkitCoordinator {
     private readonly telemetryListeners;
     private readonly frameworkErrorBus;
     private readonly ownsFrameworkErrorBus;
+    /** The instance behind {@link toolCoordinator}, kept for disposal. */
+    private readonly ownedToolCoordinator;
     private frameworkErrorHookUnsubscribe;
     private disposePromise;
     /**
@@ -372,20 +380,12 @@ export declare class ToolkitCoordinator {
      */
     private readonly 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)`.
-     */
-    private pnpEnforcementOverride;
-    /**
-     * 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}.
      */
-    private readonly warnedPolicyDiagnostics;
+    private readonly reportedPolicyDiagnostics;
+    private readonly policyDiagnosticListeners;
     /**
      * Whether {@link decideFeaturePolicy} has already reported serving a decision
      * with no assessment bound.
@@ -460,13 +460,15 @@ export declare class ToolkitCoordinator {
     private emitSectionControllerLifecycle;
     /**
      * 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.
      */
     private handleError;
     /**
      * 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.
      */
     private isToolGranted;
     /**
@@ -475,15 +477,16 @@ export declare class ToolkitCoordinator {
      * `fallbackFollows` marks a failure another path absorbs, which is recoverable
      * whatever the policy.
      */
-    private reportToolFailure;
+    private reportStartFailure;
     /**
-     * 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: string, error: unknown): void;
+    reportToolFailure(toolId: string, phase: ToolFailurePhase, error: unknown): void;
     private reportNewlyGrantedFailures;
     /**
      * Subscribe to changes of {@link isReady}: state loading, text-to-speech
@@ -516,6 +519,7 @@ export declare class ToolkitCoordinator {
      * @internal
      */
     reportFrameworkError(model: FrameworkErrorModel): void;
+    private sectionControllerKey;
     private getSectionControllerMapKey;
     private createDefaultSectionPersistence;
     private resolveSectionPersistence;
@@ -536,9 +540,6 @@ export declare class ToolkitCoordinator {
      * @returns Whether `registry` was adopted.
      */
     adoptToolRegistry(registry: ToolRegistry | null): boolean;
-    /**
-     * Register tool providers in the registry
-     */
     private _registerToolProviders;
     private getProviderDescriptorTools;
     /**
@@ -567,7 +568,7 @@ export declare class ToolkitCoordinator {
     }): SectionControllerHandle | undefined;
     subscribeSectionEvents(args: SectionEventSubscriptionArgs): () => void;
     /**
-     * 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
@@ -600,6 +601,12 @@ export declare class ToolkitCoordinator {
      * re-bind them to the new controller.
      */
     private clearActiveCohortIfMatches;
+    /**
+     * Detach every active subscription from its controller. Iterates a snapshot,
+     * as `setActiveCohort` does, because a disposer may mutate
+     * `activeSubscriptions`.
+     */
+    private detachActiveSubscriptions;
     private buildSectionEventPredicate;
     private collectEventItemIds;
     /**
@@ -686,9 +693,9 @@ export declare class ToolkitCoordinator {
     private disposeOwnedResources;
     private waitForAdmittedInitialization;
     /**
-     * Initialize TTS service with provider
+     * Initialize the TTS service from the `textToSpeech` tool config.
      */
-    ensureTTSReady(config?: TextToSpeechToolProviderConfig): Promise<void>;
+    ensureTTSReady(): Promise<void>;
     private waitForPendingTTSReconfigure;
     private _initializeTTS;
     private resolveTTSToolConfig;
@@ -717,19 +724,12 @@ export declare class ToolkitCoordinator {
     setToolContextResolvers(resolvers: ToolContextResolverMap | null | undefined): void;
     private notifyToolContextResolverChange;
     /**
-     * Get tool configuration.
-     *
-     * @param toolId Tool identifier
-     * @returns Tool configuration or null if not configured
+     * Get tool configuration, or null if the tool is not configured.
      */
     getToolConfig(toolId: "textToSpeech"): TextToSpeechToolProviderConfig | null;
     getToolConfig(toolId: string): ToolProviderConfig | null;
     /**
-     * Update tool configuration.
-     * Applies changes to underlying services.
-     *
-     * @param toolId Tool identifier
-     * @param updates Partial configuration updates
+     * Update tool configuration and apply the change to the underlying services.
      */
     updateToolConfig(toolId: "textToSpeech", updates: Partial<TextToSpeechToolProviderConfig>): void;
     updateToolConfig(toolId: string, updates: Partial<ToolProviderConfig>): void;
@@ -750,11 +750,14 @@ export declare class ToolkitCoordinator {
      */
     decideToolPolicy(request: ToolPolicyDecisionRequest): ToolPolicyDecision;
     /**
-     * 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.
      */
     private warnPolicyDiagnostics;
+    private notifyPolicyDiagnosticListener;
     /**
      * File a mounted item's policy settings (`requiredTools`, `restrictedTools`,
      * `toolParameters`) under its canonical id. They govern the decisions scoped
@@ -772,8 +775,8 @@ export declare 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.
      *
@@ -785,7 +788,7 @@ export declare class ToolkitCoordinator {
      * `scope` is the surface asking; an item's scope brings in that item's
      * registered settings ({@link registerItemSettings}).
      */
-    decideFeaturePolicy(featureId: string, scope?: ToolScope): FeaturePolicyDecision;
+    decideFeaturePolicy<K extends string>(featureId: K, scope?: ToolScope): FeaturePolicyDecision<ToolParametersFor<K>>;
     /**
      * Subscribe to policy-engine change events. Fires whenever the
      * coordinator's bound inputs change (`updateToolConfig`,
@@ -804,6 +807,7 @@ export declare class ToolkitCoordinator {
      * their own lifetime ends before the coordinator's.
      */
     onPolicyChange(listener: ToolPolicyChangeListener): () => void;
+    onPolicyDiagnostic(listener: (diagnostic: ToolPolicyDiagnostic) => void): () => void;
     /**
      * Subscribe to accessibility-catalog registrations and removals.
      *
@@ -831,7 +835,8 @@ export declare class ToolkitCoordinator {
     updateAssessment(assessment: AssessmentEntity | null): void;
     /**
      * 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: PnpEnforcementMode | null): void;
     /**
@@ -877,10 +882,7 @@ export declare class ToolkitCoordinator {
     canRequestTool(toolId: string, level?: ToolOpenRequest["level"], scopeId?: string): boolean;
     onToolRequestTargetsChange(listener: () => void): () => void;
     private resolveConfiguredPnpEnforcement;
-    /**
-     * Apply tool configuration changes to underlying services.
-     * Called after updateToolConfig().
-     */
+    /** Apply an `updateToolConfig` change to the underlying services. */
     private _applyToolConfigChange;
     /**
      * Register the provider a tool's updated config builds, replacing the one