@pie-players/pie-assessment-toolkit 0.3.30 → 0.3.32

package/dist/services/ToolkitCoordinator.js

@@ -13,10 +13,12 @@
  *
  * Part of PIE Assessment Toolkit.
  */
-import { normalizeToolsConfig, resolveToolsForLevel, } from "./tools-config-normalizer.js";
+import { normalizeToolsConfig, } from "./tools-config-normalizer.js";
 import { normalizeAndValidateToolsConfig, normalizeToolConfigStrictness, } from "./tool-config-validation.js";
 import { AccessibilityCatalogResolver } from "./AccessibilityCatalogResolver.js";
 import { ElementToolStateStore } from "./ElementToolStateStore.js";
+import { frameworkErrorFromCoordinatorContext, } from "./framework-error.js";
+import { FrameworkErrorBus, } from "./framework-error-bus.js";
 import { HighlightCoordinator } from "./HighlightCoordinator.js";
 import { ToolCoordinator } from "./ToolCoordinator.js";
 import { TTSService } from "./TTSService.js";
@@ -24,6 +26,8 @@ import { BrowserTTSProvider } from "./tts/browser-provider.js";
 import { buildRuntimeTTSConfig, resolveTTSBackend, } from "./tts-runtime-config.js";
 import { ToolProviderRegistry } from "./tool-providers/index.js";
 import { createPackagedToolRegistry } from "./createDefaultToolRegistry.js";
+import { ToolPolicyEngine, } from "../policy/engine.js";
+import { resolveDefaultQtiEnforcement } from "../policy/internal.js";
 const SECTION_ITEM_EVENT_TYPES = [
     "item-selected",
     "item-session-data-changed",
@@ -98,7 +102,51 @@ export class ToolkitCoordinator {
     sectionEventListenerIds = new WeakMap();
     sectionEventSubscriptions = new Map();
     telemetryListeners = new Set();
+    frameworkErrorBus;
+    ownsFrameworkErrorBus;
     nextSectionEventListenerId = 1;
+    /**
+     * Unified Tool Policy Engine. Owned by the coordinator and lives
+     * for the lifetime of the coordinator instance — there is no
+     * explicit teardown path today; the engine and its listener set
+     * are reclaimed by GC when the coordinator becomes unreachable.
+     * Subscribers attached via {@link onPolicyChange} must therefore
+     * detach via the unsubscribe function the engine returns; do not
+     * rely on a `disposed` event being emitted on coordinator teardown.
+     *
+     * Hosts read decisions via {@link decideToolPolicy} or subscribe
+     * to changes via {@link onPolicyChange}. The legacy
+     * `resolveToolsForLevel` / `PnpToolResolver` paths still coexist
+     * until the upcoming compat-removal sweep deletes them.
+     */
+    policyEngine;
+    /**
+     * Host-set override for QTI enforcement. `null` (the default) means
+     * "auto" — the coordinator infers the effective mode from the
+     * QTI inputs the bound `AssessmentEntity` and `AssessmentItemRef`
+     * actually carry (see {@link resolveEffectiveQtiEnforcement}).
+     * `"on"` / `"off"` are explicit host opt-in / opt-out and stick
+     * across subsequent assessment / item swaps until the host clears
+     * the override by calling `setQtiEnforcement(null)`.
+     */
+    qtiEnforcementOverride = null;
+    /**
+     * Last assessment passed to {@link updateAssessment}. Read by
+     * {@link resolveEffectiveQtiEnforcement} 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 resolveEffectiveQtiEnforcement} can detect item-level
+     * QTI inputs (`requiredTools` / `restrictedTools` /
+     * `toolParameters`) without round-tripping through the engine's
+     * frozen snapshot.
+     */
+    boundCurrentItemRef = null;
     /** Callback for floating tools changes */
     floatingToolsChangeCallback = null;
     static resolveConfig(config) {
@@ -148,6 +196,13 @@ export class ToolkitCoordinator {
         this.toolRegistry = resolvedConfig.toolRegistry ?? createPackagedToolRegistry();
         this.hooks = resolvedConfig.hooks ?? {};
         this.lazyInit = config.lazyInit === true;
+        // 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
+        // fan-out as coordinator failures). Otherwise own a private one.
+        this.frameworkErrorBus = config.frameworkErrorBus ?? new FrameworkErrorBus();
+        this.ownsFrameworkErrorBus = !config.frameworkErrorBus;
+        this.subscribeFrameworkErrorHookAdapters();
         // Initialize all services
         this.toolCoordinator = new ToolCoordinator();
         this.highlightCoordinator = new HighlightCoordinator();
@@ -159,6 +214,24 @@ export class ToolkitCoordinator {
         // Initialize TTS service based on config
         this.ttsService = new TTSService();
         this.setupStatePersistenceHooks();
+        // M8 PR 2 — construct the unified ToolPolicyEngine seeded with
+        // the validated tools config. QTI inputs (`assessment`,
+        // `currentItemRef`) start `null`; `qtiEnforcement` is resolved
+        // through {@link resolveEffectiveQtiEnforcement}, which flips
+        // to `"on"` only once the bound assessment or item carries
+        // actual QTI material (PR 4). Hosts that only consume the
+        // engine for placement/policy gating get the pre-PR-2 behavior
+        // bit-for-bit.
+        this.policyEngine = new ToolPolicyEngine({
+            toolRegistry: this.toolRegistry,
+            contextId: `toolkit-coordinator:${this.assessmentId}`,
+            inputs: {
+                tools: this.config.tools,
+                assessment: null,
+                currentItemRef: null,
+                qtiEnforcement: this.resolveEffectiveQtiEnforcement(),
+            },
+        });
         if (!this.lazyInit) {
             void this.waitUntilReady().catch((err) => {
                 console.error("[ToolkitCoordinator] Failed eager initialization:", err);
@@ -166,6 +239,50 @@ export class ToolkitCoordinator {
             });
         }
     }
+    /**
+     * Subscribe the canonical `onFrameworkError` hook adapter to the
+     * framework-error bus.
+     *
+     * Called once from the constructor. The adapter inspects the live
+     * `this.hooks` reference, so a hook added later via {@link setHooks}
+     * is picked up automatically without re-subscribing.
+     */
+    subscribeFrameworkErrorHookAdapters() {
+        this.frameworkErrorBus.subscribeFrameworkErrors((model) => {
+            const hook = this.hooks.onFrameworkError;
+            if (!hook)
+                return;
+            try {
+                hook(model);
+            }
+            catch (hookError) {
+                console.warn("[ToolkitCoordinator] onFrameworkError hook failed:", hookError);
+            }
+        });
+    }
+    /**
+     * Emit a telemetry event to `onTelemetry` hook + all `subscribeTelemetry`
+     * listeners.
+     *
+     * **Naming convention.** Event names MUST be prefixed at the call site,
+     * not auto-decorated here. The convention is:
+     *
+     * - `pie-toolkit-*` for toolkit lifecycle (state load, providers,
+     *   coordinator readiness, section-controller register/dispose, TTS
+     *   bring-up, tool-config updates, etc.).
+     * - `pie-tool-*` for individual tool events (provider init lifecycle,
+     *   provider backend calls, tool-specific telemetry forwarded from
+     *   `__pieTelemetry`).
+     * - `pie-section-*` is reserved for section-player layout events
+     *   surfaced via `attachInstrumentationEventBridge` and is not emitted
+     *   from this method directly.
+     *
+     * Anything that does not fit a documented prefix is a deliberate decision
+     * to be raised in code review, not a fallback. There is no "auto prefix"
+     * here on purpose: it keeps every emit-site honest about which namespace
+     * it owns, and lets `subscribeTelemetry` consumers compare against
+     * documented strings without per-consumer normalization.
+     */
     async emitTelemetry(eventName, payload) {
         try {
             await this.hooks.onTelemetry?.(eventName, payload);
@@ -197,13 +314,40 @@ export class ToolkitCoordinator {
         }
     }
     handleError(error, context) {
-        const normalized = error instanceof Error ? error : new Error(String(error));
-        try {
-            this.hooks.onError?.(normalized, context);
-        }
-        catch (hookError) {
-            console.warn("[ToolkitCoordinator] onError hook failed:", hookError);
-        }
+        const model = frameworkErrorFromCoordinatorContext({
+            error,
+            context,
+        });
+        this.frameworkErrorBus.reportFrameworkError(model);
+    }
+    /**
+     * Subscribe to framework-error events emitted by this coordinator.
+     *
+     * See `ToolkitCoordinatorApi.subscribeFrameworkErrors` for the
+     * contract. The bus is shared with the canonical
+     * `onFrameworkError` lifecycle hook, so a listener registered here
+     * sees the same fan-out the hook sees.
+     */
+    subscribeFrameworkErrors(listener) {
+        return this.frameworkErrorBus.subscribeFrameworkErrors(listener);
+    }
+    /**
+     * Report a framework-error model directly into this coordinator's bus.
+     *
+     * Used by embedding hosts (e.g. `<pie-assessment-toolkit>`) that
+     * pre-construct their own framework-error model in a path that does
+     * not go through `handleError` — for example, `runtime-init` failures
+     * raised before any coordinator phase, or `tool-config` failures
+     * synthesized from validation diagnostics.
+     *
+     * Hosts that already share their bus via the constructor's
+     * `frameworkErrorBus` config field do not need to call this; their
+     * own `bus.reportFrameworkError(model)` is observed here.
+     *
+     * @internal
+     */
+    reportFrameworkError(model) {
+        this.frameworkErrorBus.reportFrameworkError(model);
     }
     getSectionControllerMapKey(key) {
         return `${key.assessmentId}::${key.sectionId}::${key.attemptId || ""}`;
@@ -287,7 +431,7 @@ export class ToolkitCoordinator {
                     this.elementToolStateStore.loadState(state);
                 }
                 this.stateLoaded = true;
-                await this.emitTelemetry("tool-state-loaded", {
+                await this.emitTelemetry("pie-toolkit-tool-state-loaded", {
                     hasState: Boolean(state),
                 });
             }
@@ -382,7 +526,7 @@ export class ToolkitCoordinator {
                 providerName: config.provider.providerName,
             };
             await this.hooks.onProviderRegistered?.(providerId, meta);
-            await this.emitTelemetry("provider-registered", {
+            await this.emitTelemetry("pie-toolkit-provider-registered", {
                 providerId,
                 providerName: config.provider.providerName,
             });
@@ -390,10 +534,6 @@ export class ToolkitCoordinator {
         catch (err) {
             console.warn(`[ToolkitCoordinator] Failed to register provider "${providerId}":`, err);
             this.handleError(err, { phase: "provider-register", providerId });
-            this.hooks.onProviderError?.(providerId, err, {
-                phase: "provider-register",
-                providerId,
-            });
         }
     }
     async ensureProviderReady(providerId) {
@@ -410,15 +550,11 @@ export class ToolkitCoordinator {
                 await this.hooks.onProviderInitStart?.(providerId, meta);
                 await this.toolProviderRegistry.initialize(providerId);
                 await this.hooks.onProviderReady?.(providerId, meta);
-                await this.emitTelemetry("provider-ready", { providerId });
+                await this.emitTelemetry("pie-toolkit-provider-ready", { providerId });
                 return provider;
             }
             catch (err) {
                 const error = err instanceof Error ? err : new Error(String(err));
-                this.hooks.onProviderError?.(providerId, error, {
-                    phase: "provider-init",
-                    providerId,
-                });
                 this.handleError(error, { phase: "provider-init", providerId });
                 throw error;
             }
@@ -473,6 +609,21 @@ export class ToolkitCoordinator {
                 return;
             args.listener(event);
         });
+        // Replay `content-loaded` events first so a late subscriber observes
+        // the same ordering a live subscriber would have seen (per-renderable
+        // loads, then the aggregate `section-loading-complete`). Symmetric
+        // with `section-loading-complete` replay below; without this, a
+        // consumer that attaches after a cohort transition (e.g. a fresh
+        // section controller created on navigation) silently misses every
+        // `content-loaded` event for items that finished loading before the
+        // subscription attached. See PIE-512 for the consumer-observable
+        // regression.
+        const contentLoadedReplays = this.buildContentLoadedReplayEvents(controller);
+        for (const event of contentLoadedReplays) {
+            if (shouldDeliverEvent(event)) {
+                args.listener(event);
+            }
+        }
         const replayEvent = this.buildLoadingCompleteReplayEvent(controller);
         if (replayEvent && shouldDeliverEvent(replayEvent)) {
             args.listener(replayEvent);
@@ -543,6 +694,53 @@ export class ToolkitCoordinator {
         }
         return itemIds;
     }
+    /**
+     * Build replay `content-loaded` events for renderables the controller has
+     * already finished loading.
+     *
+     * Strict by design: only renderables explicitly reported in
+     * `runtimeState.loadedRenderables` are replayed. Synthetic test harnesses
+     * that omit the field (or controllers from older revisions that did not
+     * populate it) get an empty replay set rather than a fabricated one — that
+     * preserves the contract that replays mirror events that actually fired.
+     *
+     * Order follows registration order from
+     * `SectionController.collectLoadedRenderableSnapshot`, which mirrors the
+     * order live `content-loaded` events were emitted in.
+     */
+    buildContentLoadedReplayEvents(controller) {
+        const runtimeState = controller.getRuntimeState?.();
+        const loadedRenderables = runtimeState?.loadedRenderables;
+        if (!Array.isArray(loadedRenderables) || loadedRenderables.length === 0) {
+            return [];
+        }
+        const currentItemIndex = typeof runtimeState?.currentItemIndex === "number" &&
+            Number.isFinite(runtimeState.currentItemIndex)
+            ? runtimeState.currentItemIndex
+            : 0;
+        const timestamp = Date.now();
+        const events = [];
+        for (const renderable of loadedRenderables) {
+            if (!renderable)
+                continue;
+            const itemId = renderable.itemId;
+            const canonicalItemId = typeof renderable.canonicalItemId === "string" &&
+                renderable.canonicalItemId
+                ? renderable.canonicalItemId
+                : itemId;
+            if (typeof itemId !== "string" || !itemId)
+                continue;
+            events.push({
+                type: "content-loaded",
+                contentKind: renderable.contentKind ?? "unknown",
+                itemId,
+                canonicalItemId,
+                currentItemIndex,
+                timestamp,
+            });
+        }
+        return events;
+    }
     buildLoadingCompleteReplayEvent(controller) {
         const runtimeState = controller.getRuntimeState?.();
         if (runtimeState?.loadingComplete !== true)
@@ -751,7 +949,7 @@ export class ToolkitCoordinator {
             controller: args.controller,
         });
         await this.hooks.onSectionControllerReady?.(args.context, args.controller);
-        await this.emitTelemetry("section-controller-ready", {
+        await this.emitTelemetry("pie-toolkit-section-controller-ready", {
             assessmentId: args.key.assessmentId,
             sectionId: args.key.sectionId,
             attemptId: args.key.attemptId,
@@ -821,7 +1019,7 @@ export class ToolkitCoordinator {
         }
         await args.controller.dispose?.();
         await this.hooks.onSectionControllerDispose?.(args.context, args.controller);
-        await this.emitTelemetry("section-controller-disposed", {
+        await this.emitTelemetry("pie-toolkit-section-controller-disposed", {
             assessmentId: args.key.assessmentId,
             sectionId: args.key.sectionId,
             attemptId: args.key.attemptId,
@@ -873,7 +1071,7 @@ export class ToolkitCoordinator {
                 backend: resolvedBackend,
             },
         });
-        await this.emitTelemetry("tts-init-start", {
+        await this.emitTelemetry("pie-toolkit-tts-init-start", {
             backend: resolvedBackend,
         });
         await this.emitTelemetry("pie-tool-init-start", {
@@ -887,7 +1085,7 @@ export class ToolkitCoordinator {
                 const ttsProvider = await this.ensureProviderReady("tts");
                 const providerInstance = await ttsProvider.createInstance();
                 await this.initializeTTSService(providerInstance, runtimeTTSConfig);
-                await this.emitTelemetry("tts-init-success", {
+                await this.emitTelemetry("pie-toolkit-tts-init-success", {
                     provider: "registry",
                 });
                 await this.emitTelemetry("pie-tool-init-success", {
@@ -926,7 +1124,7 @@ export class ToolkitCoordinator {
         const provider = new BrowserTTSProvider();
         try {
             await this.initializeTTSService(provider, runtimeTTSConfig);
-            await this.emitTelemetry("tts-init-success", {
+            await this.emitTelemetry("pie-toolkit-tts-init-success", {
                 provider: "browser-fallback",
             });
             await this.emitTelemetry("pie-tool-init-success", {
@@ -938,9 +1136,8 @@ export class ToolkitCoordinator {
         }
         catch (error) {
             const normalized = error instanceof Error ? error : new Error(String(error));
-            this.hooks.onTTSError?.(normalized, { phase: "tts-init" });
             this.handleError(normalized, { phase: "tts-init" });
-            await this.emitTelemetry("tts-init-error", {
+            await this.emitTelemetry("pie-toolkit-tts-init-error", {
                 message: normalized.message,
             });
             await this.emitTelemetry("pie-tool-init-error", {
@@ -1013,7 +1210,7 @@ export class ToolkitCoordinator {
             }
         });
         const voicesAfterWait = synth.getVoices();
-        await this.emitTelemetry("tts-browser-voices-ready", {
+        await this.emitTelemetry("pie-toolkit-tts-browser-voices-ready", {
             voiceCount: voicesAfterWait.length,
             timedOut: voicesAfterWait.length === 0,
         });
@@ -1055,7 +1252,7 @@ export class ToolkitCoordinator {
             if (!this.coordinatorReadyNotified) {
                 this.coordinatorReadyNotified = true;
                 await this.hooks.onCoordinatorReady?.(this);
-                await this.emitTelemetry("coordinator-ready", {
+                await this.emitTelemetry("pie-toolkit-coordinator-ready", {
                     assessmentId: this.assessmentId,
                 });
             }
@@ -1155,7 +1352,14 @@ export class ToolkitCoordinator {
             toolRegistry: this.toolRegistry,
         });
         this.config.tools = validated.config;
-        void this.emitTelemetry("tool-config-updated", { toolId });
+        // M8 PR 2 — keep the policy engine's tools input in lockstep
+        // with the validated coordinator config. The engine emits an
+        // `inputs` change event so subscribers (e.g. PR 3 toolbars) can
+        // re-decide without us managing a parallel pub/sub.
+        this.policyEngine.updateInputs({
+            tools: this.config.tools,
+        });
+        void this.emitTelemetry("pie-toolkit-tool-config-updated", { toolId });
         // Apply configuration changes to services
         this._applyToolConfigChange(toolId, updates);
     }
@@ -1186,20 +1390,57 @@ export class ToolkitCoordinator {
             toolRegistry: this.toolRegistry,
         });
         this.config.tools = validated.config;
+        // M8 PR 2 — keep the policy engine in lockstep with the
+        // floating-tools placement update. See `updateToolConfig` for
+        // the same pattern.
+        this.policyEngine.updateInputs({
+            tools: this.config.tools,
+        });
         // Notify listener of change
         if (this.floatingToolsChangeCallback) {
             this.floatingToolsChangeCallback(toolIds);
         }
     }
     /**
-     * Get currently enabled floating tools.
+     * Get currently enabled floating tools (section-level placement).
+     *
+     * @returns Array of enabled tool IDs.
+     *
+     * @remarks
+     * As of M8 PR 2 this routes through the {@link ToolPolicyEngine}
+     * rather than the legacy `resolveToolsForLevel(...)` shim. The two
+     * paths agree on `placement → policy.allowed → policy.blocked`,
+     * but the engine additionally enforces:
+     *
+     *   - **Provider veto** — `tools.providers[id].enabled === false`
+     *     removes the tool from the visible set. The legacy resolver
+     *     ignored this flag for floating tools.
+     *   - **QTI gates** — when `qtiEnforcement` is `"on"` (set by host
+     *     via {@link setQtiEnforcement}, or auto-promoted when the
+     *     bound `AssessmentEntity` / current `AssessmentItemRef`
+     *     carries QTI 6-level precedence material — see
+     *     {@link resolveEffectiveQtiEnforcement}) **and an assessment
+     *     is bound**, the QTI 6-level precedence (district block →
+     *     test-admin override → item restriction/requirement →
+     *     district requirement → PNP supports / prohibitions) is
+     *     applied. `qtiEnforcement: "on"` without a bound assessment
+     *     is a no-op for QTI gating.
+     *   - **Custom `PolicySource`s** registered via
+     *     {@link registerPolicySource}.
+     *
+     * Under the default no-assessment, no-override, no-provider-veto
+     * configuration the result still matches `resolveToolsForLevel(...)`
+     * exactly — a parity asserted by the integration tests in
+     * `tests/policy/coordinator-integration.test.ts`. Once PR 5 deletes
+     * the legacy resolver this method becomes the canonical surface.
      *
-     * @returns Array of enabled tool IDs
+     * Consumers that need the full decision (provenance, diagnostics)
+     * should call {@link decideToolPolicy} instead.
      */
     getFloatingTools() {
         if (!this.config.tools)
             return [];
-        return resolveToolsForLevel(this.config.tools, "section");
+        return this.policyEngine.getVisibleToolIds("section", "*");
     }
     /**
      * Set a callback to be notified when floating tools change.
@@ -1216,6 +1457,145 @@ export class ToolkitCoordinator {
             this.floatingToolsChangeCallback = null;
         };
     }
+    // ----------------------------------------------------------------
+    // M8 PR 2 — Tool Policy Engine surface
+    //
+    // The methods below are additive in PR 2: hosts can already drive
+    // the unified ToolPolicyEngine, but the existing toolbar / section-
+    // player render paths still consume the legacy `resolveToolsForLevel`
+    // / `PnpToolResolver` chain. PR 3 switches consumers; PR 5 deletes
+    // the legacy path. See `.cursor/plans/m8-implementation-plan.md`.
+    // ----------------------------------------------------------------
+    /**
+     * Resolve the visible tool set for a given placement level + scope.
+     *
+     * Thin shim over the owned tool-policy engine. Hosts that need
+     * richer outputs (provenance, diagnostics) read this directly;
+     * hosts that only need the section-level tool IDs can call
+     * {@link getFloatingTools} instead.
+     */
+    decideToolPolicy(request) {
+        return this.policyEngine.decide(request);
+    }
+    /**
+     * Subscribe to policy-engine change events. Fires whenever the
+     * coordinator's bound inputs change (`updateToolConfig`,
+     * `updateFloatingTools`, `updateAssessment`, `updateCurrentItemRef`,
+     * `setQtiEnforcement`) 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
+     * that want the new visible tool set should call
+     * {@link decideToolPolicy} with their level / scope.
+     *
+     * Note: the engine itself can also emit `reason: "disposed"`, but
+     * the coordinator does not dispose its engine on teardown today,
+     * so subscribers attached via this method will not observe that
+     * reason. Detach via the returned unsubscribe function instead of
+     * relying on a `disposed` event.
+     */
+    onPolicyChange(listener) {
+        return this.policyEngine.onPolicyChange(listener);
+    }
+    /**
+     * Bind (or clear) the active QTI assessment for policy decisions.
+     *
+     * Under auto-mode (no host override via {@link setQtiEnforcement}),
+     * the coordinator promotes the engine to `qtiEnforcement: "on"`
+     * iff the assessment carries any QTI 6-level precedence material
+     * (`personalNeedsProfile`, `settings.districtPolicy`,
+     * `settings.testAdministration`) or the currently-bound item ref
+     * carries item-level QTI inputs. A bare assessment record (just
+     * `id` / `name`, no PNP, no settings) keeps `"off"`.
+     *
+     * The host override set via {@link setQtiEnforcement} is sticky
+     * across assessment swaps; calling with `null` clears the binding
+     * and re-runs the auto-mode helper.
+     */
+    updateAssessment(assessment) {
+        this.boundAssessment = assessment;
+        this.policyEngine.updateInputs({
+            assessment,
+            qtiEnforcement: this.resolveEffectiveQtiEnforcement(),
+        });
+    }
+    /**
+     * Bind (or clear) the current item reference for policy decisions.
+     *
+     * Used by item-level QTI gates (item `requiredTools` /
+     * `restrictedTools` / `toolParameters`). Item-level QTI material
+     * also feeds {@link resolveEffectiveQtiEnforcement} — navigating
+     * to an item with QTI settings can flip auto-mode to `"on"` even
+     * when the parent assessment carries no QTI block of its own.
+     */
+    updateCurrentItemRef(itemRef) {
+        this.boundCurrentItemRef = itemRef;
+        this.policyEngine.updateInputs({
+            currentItemRef: itemRef,
+            qtiEnforcement: this.resolveEffectiveQtiEnforcement(),
+        });
+    }
+    /**
+     * Override the auto-mode QTI enforcement decision.
+     *
+     * Pass `"on"` to force QTI enforcement even when no QTI inputs
+     * are bound (useful for tests / fixtures). Pass `"off"` to opt
+     * out even when QTI inputs are present. Pass `null` to clear the
+     * override and return to auto-mode — `"on"` iff
+     * {@link resolveDefaultQtiEnforcement} reports any QTI material
+     * on the bound assessment or current item, otherwise `"off"`.
+     */
+    setQtiEnforcement(mode) {
+        this.qtiEnforcementOverride = mode;
+        this.policyEngine.updateInputs({
+            qtiEnforcement: this.resolveEffectiveQtiEnforcement(),
+        });
+    }
+    /**
+     * Get the policy engine inputs currently driving decisions. Useful
+     * for debugging / instrumentation; do not mutate.
+     */
+    getPolicyInputs() {
+        return this.policyEngine.getInputs();
+    }
+    /**
+     * Register a custom {@link PolicySource} with the owned policy
+     * engine. The source participates in every subsequent
+     * {@link decideToolPolicy} call until disposed (the returned
+     * function detaches and emits a `policy-source-removed` event).
+     *
+     * Delegates verbatim to
+     * {@link ToolPolicyEngine.registerPolicySource} — see that
+     * method for the full contract (event ordering, idempotency of
+     * the returned dispose function, and how registered sources
+     * compose with the built-in QTI source).
+     */
+    registerPolicySource(source) {
+        return this.policyEngine.registerPolicySource(source);
+    }
+    /**
+     * Compute the effective `qtiEnforcement` mode given the explicit
+     * host override and the auto-mode helper.
+     *
+     * Auto-mode (no override) defers to
+     * {@link resolveDefaultQtiEnforcement}, which returns `"on"`
+     * exactly when the bound assessment or current item ref carries
+     * QTI 6-level precedence material (PNP, district policy, test
+     * administration, item-level required/restricted/parameters), and
+     * `"off"` otherwise. Hosts that bind a bare assessment record
+     * (just `id` / `name`) therefore keep the legacy floating-tools
+     * behavior — QTI gates engage the moment QTI material is present.
+     */
+    resolveEffectiveQtiEnforcement() {
+        if (this.qtiEnforcementOverride !== null) {
+            return this.qtiEnforcementOverride;
+        }
+        return resolveDefaultQtiEnforcement({
+            assessment: this.boundAssessment,
+            currentItemRef: this.boundCurrentItemRef,
+        });
+    }
     /**
      * Apply tool configuration changes to underlying services.
      * Called after updateToolConfig().