@pie-players/pie-assessment-toolkit 0.3.44 → 0.3.45

package/dist/services/PNPToolResolver.js

@@ -1,514 +0,0 @@
-/**
- * PNP Tool Resolver
- *
- * Resolves tool availability from QTI 3.0 Personal Needs Profile (PNP) and
- * assessment settings. Implements a precedence hierarchy for tool configuration
- * based on common assessment platform governance patterns.
- *
- * PRECEDENCE HIERARCHY (highest to lowest):
- * ==========================================
- *
- * Standards-Based (QTI 3.0):
- * - PNP supports (#6): Student's documented accessibility needs (accessibilityInfo.accessFeature)
- * - Item-level settings (#3, #4): Per-item accessibility requirements/restrictions
- *
- * Implementation-Specific (Common Practice):
- * - District policy (#1, #5): Institutional governance and legal compliance
- * - Test administration (#2): Session-level operational control
- *
- * The hierarchy itself is NOT defined by QTI 3.0 standards but follows common
- * patterns in K-12 assessment platforms, aligning with US IEP/504 accommodation
- * hierarchies where legal requirements and institutional policies take precedence.
- *
- * Precedence Order:
- * 1. District block (absolute veto) - Legal/policy requirements
- * 2. Test administration override - Proctor/administrator operational control
- * 3. Item restriction (per-item block) - Content author can disable for specific items
- * 4. Item requirement (forces enable) - Required by IEP/504 or content needs
- * 5. District requirement - Institutional accessibility requirements
- * 6. PNP supports (student needs) - QTI 3.0 standard student preferences
- *
- * Governance Context:
- * - Institutional veto (district) trumps individual preferences (legal compliance)
- * - Session control (test admin) enables operational flexibility
- * - Content restrictions (item) prevent tools that invalidate assessment
- * - Required accommodations (IEP/504) ensure legal compliance
- * - Student preferences (PNP) are honored when not overridden
- *
- * References:
- * - QTI 3.0: https://www.imsglobal.org/spec/qti/v3p0
- * - IMS AfA 3.0: https://www.imsglobal.org/spec/afa/v3p0
- * - Common assessment platform governance patterns (not standardized)
- *
- * Part of PIE Assessment Toolkit.
- */
-import { PnpProvenanceBuilder, } from "./pnp-provenance.js";
-/**
- * Resolves tool availability from QTI 3.0 assessment structure
- */
-export class PnpToolResolver {
-    toolRegistry;
-    enableProvenance;
-    /**
-     * Create a PnpToolResolver
-     *
-     * @param toolRegistry Tool registry for PNP support mapping
-     * @param enableProvenance Enable detailed provenance tracking (default: true)
-     */
-    constructor(toolRegistry, enableProvenance = true) {
-        this.toolRegistry = toolRegistry;
-        this.enableProvenance = enableProvenance;
-    }
-    /**
-     * Resolve all tools from QTI 3.0 assessment + optional item context
-     *
-     * @param assessment QTI 3.0 assessment with personalNeedsProfile
-     * @param currentItemRef Current item for item-specific requirements (optional)
-     * @returns Array of resolved tool configurations
-     *
-     * @example
-     * const resolver = new PnpToolResolver(registry);
-     * const tools = resolver.resolveTools(assessment, itemRef);
-     * tools.forEach(tool => {
-     *   console.log(`${tool.id}: ${tool.enabled ? 'enabled' : 'disabled'}`);
-     * });
-     */
-    resolveTools(assessment, currentItemRef) {
-        const result = this.resolveToolsWithProvenance(assessment, currentItemRef);
-        return result.tools;
-    }
-    /**
-     * Resolve all tools with full provenance tracking
-     *
-     * Returns both resolved tools and complete provenance trail showing:
-     * - All configuration sources consulted
-     * - Decision steps at each precedence level
-     * - Reasons for enabling/blocking each feature
-     * - Human-readable explanations
-     *
-     * @param assessment QTI 3.0 assessment with personalNeedsProfile
-     * @param currentItemRef Current item for item-specific requirements (optional)
-     * @returns Resolution result with tools and provenance
-     *
-     * @example
-     * const resolver = new PnpToolResolver(registry);
-     * const result = resolver.resolveToolsWithProvenance(assessment, itemRef);
-     *
-     * // Use resolved tools
-     * result.tools.forEach(tool => console.log(tool.id, tool.enabled));
-     *
-     * // Display provenance to user
-     * console.log(result.provenance.summary);
-     * result.provenance.features.forEach((trail, featureId) => {
-     *   console.log(`${featureId}: ${trail.explanation}`);
-     * });
-     */
-    resolveToolsWithProvenance(assessment, currentItemRef) {
-        const pnp = assessment.personalNeedsProfile;
-        const settings = assessment.settings;
-        const itemSettings = currentItemRef?.settings;
-        // Initialize provenance builder
-        const contextId = `assessment-${assessment.id || "unknown"}${currentItemRef ? `-item-${currentItemRef.identifier}` : ""}`;
-        const provenanceBuilder = this.enableProvenance
-            ? new PnpProvenanceBuilder(contextId)
-            : null;
-        // Record configuration sources
-        if (provenanceBuilder) {
-            if (settings?.districtPolicy || settings?.testAdministration) {
-                provenanceBuilder.addSource("assessment", {
-                    id: assessment.id || "unknown",
-                    name: assessment.name || assessment.id || "Assessment",
-                    config: settings,
-                });
-            }
-            if (pnp) {
-                provenanceBuilder.addSource("student", {
-                    id: "student", // Would come from session context
-                    name: "Student PNP Profile",
-                    config: pnp,
-                });
-            }
-            if (currentItemRef && itemSettings) {
-                provenanceBuilder.addSource("item", {
-                    id: currentItemRef.identifier,
-                    name: currentItemRef.identifier,
-                    config: itemSettings,
-                });
-            }
-        }
-        // Collect all PNP support IDs mentioned anywhere
-        const allSupports = new Set();
-        pnp?.supports?.forEach((s) => allSupports.add(s));
-        pnp?.prohibitedSupports?.forEach((s) => allSupports.add(s));
-        settings?.districtPolicy?.blockedTools?.forEach((s) => allSupports.add(s));
-        settings?.districtPolicy?.requiredTools?.forEach((s) => allSupports.add(s));
-        itemSettings?.requiredTools?.forEach((s) => allSupports.add(s));
-        itemSettings?.restrictedTools?.forEach((s) => allSupports.add(s));
-        const resolved = [];
-        const context = {
-            pnp,
-            districtPolicy: settings?.districtPolicy,
-            testAdmin: settings?.testAdministration,
-            itemSettings,
-            toolConfigs: settings?.toolConfigs,
-        };
-        for (const supportId of allSupports) {
-            const config = this.resolveSupport(supportId, context, provenanceBuilder);
-            if (config) {
-                resolved.push(config);
-            }
-        }
-        return {
-            tools: resolved,
-            provenance: provenanceBuilder
-                ? provenanceBuilder.build()
-                : this.createEmptyProvenance(contextId),
-        };
-    }
-    /**
-     * Resolve availability of a single PNP support
-     *
-     * Applies precedence rules to determine if support should be enabled.
-     *
-     * @param supportId PNP support identifier
-     * @param context Resolution context with all configuration sources
-     * @param provenanceBuilder Provenance tracking (optional)
-     * @returns Resolved config or null if blocked/disabled
-     */
-    resolveSupport(supportId, context, provenanceBuilder) {
-        // Precedence (highest to lowest):
-        // 1. District block (absolute veto)
-        if (context.districtPolicy?.blockedTools?.includes(supportId)) {
-            provenanceBuilder?.addDecision({
-                precedence: 1,
-                rule: "district-block",
-                featureId: supportId,
-                action: "block",
-                sourceType: "assessment",
-                reason: `District policy blocks "${supportId}" for all assessments`,
-                value: context.districtPolicy.blockedTools,
-            });
-            return null; // Blocked
-        }
-        // 2. Test administration override
-        if (context.testAdmin?.toolOverrides?.[supportId] === false) {
-            provenanceBuilder?.addDecision({
-                precedence: 2,
-                rule: "test-admin-override",
-                featureId: supportId,
-                action: "block",
-                sourceType: "assessment",
-                reason: `Test administrator disabled "${supportId}" for this session`,
-                value: context.testAdmin.toolOverrides,
-            });
-            return null; // Blocked
-        }
-        // 3. Item restriction
-        if (context.itemSettings?.restrictedTools?.includes(supportId)) {
-            provenanceBuilder?.addDecision({
-                precedence: 3,
-                rule: "item-restriction",
-                featureId: supportId,
-                action: "block",
-                sourceType: "item",
-                reason: `Item restricts "${supportId}" (e.g., mental math question blocks calculator)`,
-                value: context.itemSettings.restrictedTools,
-            });
-            return null; // Blocked for this item
-        }
-        // 4. Item requirement (forces enable)
-        if (context.itemSettings?.requiredTools?.includes(supportId)) {
-            provenanceBuilder?.addDecision({
-                precedence: 4,
-                rule: "item-requirement",
-                featureId: supportId,
-                action: "enable",
-                sourceType: "item",
-                reason: `Item requires "${supportId}" for this question`,
-                value: context.itemSettings.requiredTools,
-            });
-            return this.buildToolConfig(supportId, context, {
-                required: true,
-                source: "item",
-            });
-        }
-        // 5. District requirement
-        if (context.districtPolicy?.requiredTools?.includes(supportId)) {
-            provenanceBuilder?.addDecision({
-                precedence: 5,
-                rule: "district-requirement",
-                featureId: supportId,
-                action: "enable",
-                sourceType: "assessment",
-                reason: `District policy requires "${supportId}" for all assessments`,
-                value: context.districtPolicy.requiredTools,
-            });
-            return this.buildToolConfig(supportId, context, {
-                required: true,
-                source: "district",
-            });
-        }
-        // 6. PNP prohibitions and supports (student needs)
-        if (context.pnp?.prohibitedSupports?.includes(supportId)) {
-            provenanceBuilder?.addDecision({
-                precedence: 6,
-                rule: "pnp-prohibited",
-                featureId: supportId,
-                action: "block",
-                sourceType: "student",
-                reason: `Student PNP profile prohibits "${supportId}"`,
-                value: context.pnp.prohibitedSupports,
-            });
-            return null;
-        }
-        if (context.pnp?.supports?.includes(supportId)) {
-            provenanceBuilder?.addDecision({
-                precedence: 6,
-                rule: "pnp-support",
-                featureId: supportId,
-                action: "enable",
-                sourceType: "student",
-                reason: `Student PNP profile requests "${supportId}"`,
-                value: context.pnp.supports,
-            });
-            return this.buildToolConfig(supportId, context, {
-                alwaysAvailable: true,
-                source: "pnp",
-            });
-        }
-        // Not enabled - log as skipped
-        provenanceBuilder?.addDecision({
-            precedence: 6,
-            rule: "pnp-support",
-            featureId: supportId,
-            action: "skip",
-            sourceType: "system",
-            reason: `Feature "${supportId}" not configured at any level`,
-        });
-        return null;
-    }
-    /**
-     * Create empty provenance when tracking is disabled
-     */
-    createEmptyProvenance(contextId) {
-        return {
-            contextId,
-            resolvedAt: new Date(),
-            sources: {},
-            features: new Map(),
-            decisionLog: [],
-            summary: {
-                totalFeatures: 0,
-                enabled: 0,
-                blocked: 0,
-                notConfigured: 0,
-                bySource: {},
-                byRule: {},
-            },
-        };
-    }
-    /**
-     * Build resolved tool configuration
-     *
-     * Maps PNP support ID to PIE tool ID and merges tool-specific settings.
-     *
-     * @param supportId PNP support identifier
-     * @param context Resolution context for settings lookup
-     * @param flags Availability flags (required, alwaysAvailable, source)
-     * @returns Complete resolved tool configuration
-     */
-    buildToolConfig(supportId, context, flags) {
-        // Map PNP support ID to PIE tool ID via registry
-        const toolIds = this.toolRegistry.getToolsByPNPSupport(supportId);
-        // Use first matching tool (usually only one per PNP support)
-        // If no mapping exists, use the support ID directly as tool ID
-        const pieToolId = toolIds.size > 0 ? Array.from(toolIds)[0] : supportId;
-        // Get tool-specific config from settings (item takes precedence)
-        const toolConfig = context.itemSettings?.toolParameters?.[supportId] ||
-            context.toolConfigs?.[supportId];
-        return {
-            id: pieToolId,
-            enabled: true,
-            required: flags.required || false,
-            alwaysAvailable: flags.alwaysAvailable || false,
-            settings: toolConfig,
-            source: flags.source,
-        };
-    }
-    /**
-     * Check if a specific tool is enabled
-     *
-     * @param toolId Toolkit tool identifier (e.g., 'calculator')
-     * @param assessment Assessment with PNP
-     * @param itemRef Optional item context
-     * @returns true if tool is enabled
-     */
-    isToolEnabled(toolId, assessment, itemRef) {
-        const resolved = this.resolveTools(assessment, itemRef);
-        return resolved.some((t) => t.id === toolId && t.enabled);
-    }
-    /**
-     * Check if a tool is required (cannot be disabled)
-     *
-     * @param toolId Toolkit tool identifier
-     * @param assessment Assessment with PNP
-     * @param itemRef Optional item context
-     * @returns true if tool is required or always available
-     */
-    isToolRequired(toolId, assessment, itemRef) {
-        const resolved = this.resolveTools(assessment, itemRef);
-        const tool = resolved.find((t) => t.id === toolId);
-        return tool?.required || tool?.alwaysAvailable || false;
-    }
-    /**
-     * Get list of auto-activate tools from PNP
-     *
-     * Returns PIE tool IDs that should be automatically opened/activated
-     * when the assessment starts, based on PNP activateAtInit field.
-     *
-     * @param assessment Assessment with PNP
-     * @returns Array of PIE tool IDs to auto-activate
-     *
-     * @example
-     * const autoActivate = resolver.getAutoActivateTools(assessment);
-     * // Returns: ['textToSpeech', 'lineReader']
-     */
-    getAutoActivateTools(assessment) {
-        const pnp = assessment.personalNeedsProfile;
-        if (!pnp?.activateAtInit)
-            return [];
-        return pnp.activateAtInit
-            .map((supportId) => {
-            const toolIds = this.toolRegistry.getToolsByPNPSupport(supportId);
-            return toolIds.size > 0 ? Array.from(toolIds)[0] : null;
-        })
-            .filter(Boolean);
-    }
-    /**
-     * Get all enabled tools
-     *
-     * @param assessment Assessment with PNP
-     * @param itemRef Optional item context
-     * @returns Array of PIE tool IDs that are enabled
-     */
-    getEnabledTools(assessment, itemRef) {
-        const resolved = this.resolveTools(assessment, itemRef);
-        return Array.from(new Set(resolved
-            .filter((t) => t.enabled)
-            .map((t) => this.toolRegistry.normalizeToolId(t.id))
-            .filter(Boolean)));
-    }
-    /**
-     * Get allowed tool IDs (Pass 1 of two-pass visibility model)
-     *
-     * Returns tool IDs that pass orchestrator-level checks (PNP + policies + settings).
-     * This is the first gate - tools still need to pass Pass 2 (relevance check).
-     *
-     * This is the primary method to use with ToolRegistry.filterVisibleInContext()
-     *
-     * @param assessment Assessment with PNP
-     * @param itemRef Optional item context
-     * @returns Array of allowed tool IDs (Pass 1)
-     *
-     * @example
-     * // Two-pass visibility model
-     * const allowedToolIds = resolver.getAllowedToolIds(assessment, itemRef);
-     * const visibleTools = toolRegistry.filterVisibleInContext(allowedToolIds, context);
-     */
-    getAllowedToolIds(assessment, itemRef) {
-        return this.getEnabledTools(assessment, itemRef);
-    }
-    /**
-     * Resolve tools with a test/override PNP profile
-     *
-     * FOR TESTING/DEVELOPMENT ONLY
-     *
-     * Allows direct injection of a PNP profile for testing accessibility configurations
-     * without modifying the assessment entity. The override profile replaces the
-     * assessment's personalNeedsProfile entirely.
-     *
-     * Use cases:
-     * - Development/testing UI for trying different profiles
-     * - Automated testing with various accessibility configurations
-     * - Preview tools with profile simulation
-     * - Accessibility team testing and validation
-     *
-     * @param assessment Base assessment (settings, policies, etc.)
-     * @param overrideProfile PNP profile to inject (replaces assessment.personalNeedsProfile)
-     * @param itemRef Optional item context
-     * @returns Resolution result with tools and provenance
-     *
-     * @example
-     * // Test with low vision profile
-     * const testProfile = {
-     *   supports: ['magnification', 'textToSpeech', 'highContrastDisplay']
-     * };
-     * const result = resolver.resolveWithOverride(assessment, testProfile);
-     *
-     * @example
-     * // Test with null profile (no accessibility features)
-     * const result = resolver.resolveWithOverride(assessment, null);
-     */
-    resolveWithOverride(assessment, overrideProfile, itemRef) {
-        // Create assessment clone with overridden PNP
-        const testAssessment = {
-            ...assessment,
-            personalNeedsProfile: overrideProfile || undefined,
-        };
-        return this.resolveToolsWithProvenance(testAssessment, itemRef);
-    }
-    /**
-     * Get allowed tool IDs with full provenance tracking
-     *
-     * Returns both tool IDs and complete resolution provenance for debugging,
-     * auditing, and displaying to users.
-     *
-     * @param assessment Assessment with PNP
-     * @param itemRef Optional item context
-     * @returns Object with tool IDs and provenance
-     *
-     * @example
-     * const result = resolver.getAllowedToolIdsWithProvenance(assessment, itemRef);
-     *
-     * // Use tool IDs
-     * const visibleTools = toolRegistry.filterVisibleInContext(result.toolIds, context);
-     *
-     * // Display provenance to user
-     * console.log('Resolution Summary:', result.provenance.summary);
-     * console.log('Explanation for calculator:', result.provenance.features.get('calculator')?.explanation);
-     */
-    getAllowedToolIdsWithProvenance(assessment, itemRef) {
-        const result = this.resolveToolsWithProvenance(assessment, itemRef);
-        return {
-            toolIds: result.tools.map((t) => t.id),
-            provenance: result.provenance,
-        };
-    }
-    /**
-     * Get all required tools
-     *
-     * @param assessment Assessment with PNP
-     * @param itemRef Optional item context
-     * @returns Array of PIE tool IDs that are required
-     */
-    getRequiredTools(assessment, itemRef) {
-        const resolved = this.resolveTools(assessment, itemRef);
-        return resolved
-            .filter((t) => t.required || t.alwaysAvailable)
-            .map((t) => t.id);
-    }
-    /**
-     * Get tool configuration settings
-     *
-     * @param toolId Toolkit tool identifier
-     * @param assessment Assessment with PNP
-     * @param itemRef Optional item context
-     * @returns Tool-specific settings or null if not found
-     */
-    getToolSettings(toolId, assessment, itemRef) {
-        const resolved = this.resolveTools(assessment, itemRef);
-        const tool = resolved.find((t) => t.id === toolId);
-        return tool?.settings || null;
-    }
-}
-//# sourceMappingURL=PNPToolResolver.js.map

package/dist/services/PNPToolResolver.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"PNPToolResolver.js","sourceRoot":"","sources":["../../src/services/PNPToolResolver.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * PNP Tool Resolver\n *\n * Resolves tool availability from QTI 3.0 Personal Needs Profile (PNP) and\n * assessment settings. Implements a precedence hierarchy for tool configuration\n * based on common assessment platform governance patterns.\n *\n * PRECEDENCE HIERARCHY (highest to lowest):\n * ==========================================\n *\n * Standards-Based (QTI 3.0):\n * - PNP supports (#6): Student's documented accessibility needs (accessibilityInfo.accessFeature)\n * - Item-level settings (#3, #4): Per-item accessibility requirements/restrictions\n *\n * Implementation-Specific (Common Practice):\n * - District policy (#1, #5): Institutional governance and legal compliance\n * - Test administration (#2): Session-level operational control\n *\n * The hierarchy itself is NOT defined by QTI 3.0 standards but follows common\n * patterns in K-12 assessment platforms, aligning with US IEP/504 accommodation\n * hierarchies where legal requirements and institutional policies take precedence.\n *\n * Precedence Order:\n * 1. District block (absolute veto) - Legal/policy requirements\n * 2. Test administration override - Proctor/administrator operational control\n * 3. Item restriction (per-item block) - Content author can disable for specific items\n * 4. Item requirement (forces enable) - Required by IEP/504 or content needs\n * 5. District requirement - Institutional accessibility requirements\n * 6. PNP supports (student needs) - QTI 3.0 standard student preferences\n *\n * Governance Context:\n * - Institutional veto (district) trumps individual preferences (legal compliance)\n * - Session control (test admin) enables operational flexibility\n * - Content restrictions (item) prevent tools that invalidate assessment\n * - Required accommodations (IEP/504) ensure legal compliance\n * - Student preferences (PNP) are honored when not overridden\n *\n * References:\n * - QTI 3.0: https://www.imsglobal.org/spec/qti/v3p0\n * - IMS AfA 3.0: https://www.imsglobal.org/spec/afa/v3p0\n * - Common assessment platform governance patterns (not standardized)\n *\n * Part of PIE Assessment Toolkit.\n */\n\nimport type {\n\tAssessmentEntity,\n\tAssessmentItemRef,\n\tAssessmentSettings,\n\tItemSettings,\n\tPersonalNeedsProfile,\n} from \"@pie-players/pie-players-shared/types\";\nimport type { ToolRegistry } from \"./ToolRegistry.js\";\nimport {\n\tPnpProvenanceBuilder,\n\ttype PnpResolutionProvenance,\n} from \"./pnp-provenance.js\";\n\n/**\n * Resolved tool configuration with source tracking\n */\nexport interface ResolvedToolConfig {\n\tid: string; // PIE tool ID\n\tenabled: boolean;\n\trequired?: boolean; // Must be available (item/district requirement)\n\talwaysAvailable?: boolean; // PNP support (can't be toggled off)\n\tsettings?: any; // Tool-specific configuration\n\tsource: \"district\" | \"item\" | \"pnp\" | \"settings\"; // Configuration source\n}\n\n/**\n * Resolution result with provenance tracking\n */\nexport interface ToolResolutionResult {\n\t/** Resolved tool configurations */\n\ttools: ResolvedToolConfig[];\n\n\t/** Complete provenance trail (for debugging/display) */\n\tprovenance: PnpResolutionProvenance;\n}\n\n/**\n * Internal context for tool resolution\n */\ninterface ResolutionContext {\n\tpnp?: PersonalNeedsProfile;\n\tdistrictPolicy?: AssessmentSettings[\"districtPolicy\"];\n\ttestAdmin?: AssessmentSettings[\"testAdministration\"];\n\titemSettings?: ItemSettings;\n\ttoolConfigs?: AssessmentSettings[\"toolConfigs\"];\n}\n\n/**\n * Resolves tool availability from QTI 3.0 assessment structure\n */\nexport class PnpToolResolver {\n\tprivate toolRegistry: ToolRegistry;\n\tprivate enableProvenance: boolean;\n\n\t/**\n\t * Create a PnpToolResolver\n\t *\n\t * @param toolRegistry Tool registry for PNP support mapping\n\t * @param enableProvenance Enable detailed provenance tracking (default: true)\n\t */\n\tconstructor(toolRegistry: ToolRegistry, enableProvenance = true) {\n\t\tthis.toolRegistry = toolRegistry;\n\t\tthis.enableProvenance = enableProvenance;\n\t}\n\n\t/**\n\t * Resolve all tools from QTI 3.0 assessment + optional item context\n\t *\n\t * @param assessment QTI 3.0 assessment with personalNeedsProfile\n\t * @param currentItemRef Current item for item-specific requirements (optional)\n\t * @returns Array of resolved tool configurations\n\t *\n\t * @example\n\t * const resolver = new PnpToolResolver(registry);\n\t * const tools = resolver.resolveTools(assessment, itemRef);\n\t * tools.forEach(tool => {\n\t *   console.log(`${tool.id}: ${tool.enabled ? 'enabled' : 'disabled'}`);\n\t * });\n\t */\n\tresolveTools(\n\t\tassessment: AssessmentEntity,\n\t\tcurrentItemRef?: AssessmentItemRef,\n\t): ResolvedToolConfig[] {\n\t\tconst result = this.resolveToolsWithProvenance(assessment, currentItemRef);\n\t\treturn result.tools;\n\t}\n\n\t/**\n\t * Resolve all tools with full provenance tracking\n\t *\n\t * Returns both resolved tools and complete provenance trail showing:\n\t * - All configuration sources consulted\n\t * - Decision steps at each precedence level\n\t * - Reasons for enabling/blocking each feature\n\t * - Human-readable explanations\n\t *\n\t * @param assessment QTI 3.0 assessment with personalNeedsProfile\n\t * @param currentItemRef Current item for item-specific requirements (optional)\n\t * @returns Resolution result with tools and provenance\n\t *\n\t * @example\n\t * const resolver = new PnpToolResolver(registry);\n\t * const result = resolver.resolveToolsWithProvenance(assessment, itemRef);\n\t *\n\t * // Use resolved tools\n\t * result.tools.forEach(tool => console.log(tool.id, tool.enabled));\n\t *\n\t * // Display provenance to user\n\t * console.log(result.provenance.summary);\n\t * result.provenance.features.forEach((trail, featureId) => {\n\t *   console.log(`${featureId}: ${trail.explanation}`);\n\t * });\n\t */\n\tresolveToolsWithProvenance(\n\t\tassessment: AssessmentEntity,\n\t\tcurrentItemRef?: AssessmentItemRef,\n\t): ToolResolutionResult {\n\t\tconst pnp = assessment.personalNeedsProfile;\n\t\tconst settings = assessment.settings as AssessmentSettings;\n\t\tconst itemSettings = currentItemRef?.settings as ItemSettings;\n\n\t\t// Initialize provenance builder\n\t\tconst contextId = `assessment-${assessment.id || \"unknown\"}${currentItemRef ? `-item-${currentItemRef.identifier}` : \"\"}`;\n\t\tconst provenanceBuilder = this.enableProvenance\n\t\t\t? new PnpProvenanceBuilder(contextId)\n\t\t\t: null;\n\n\t\t// Record configuration sources\n\t\tif (provenanceBuilder) {\n\t\t\tif (settings?.districtPolicy || settings?.testAdministration) {\n\t\t\t\tprovenanceBuilder.addSource(\"assessment\", {\n\t\t\t\t\tid: assessment.id || \"unknown\",\n\t\t\t\t\tname: assessment.name || assessment.id || \"Assessment\",\n\t\t\t\t\tconfig: settings,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tif (pnp) {\n\t\t\t\tprovenanceBuilder.addSource(\"student\", {\n\t\t\t\t\tid: \"student\", // Would come from session context\n\t\t\t\t\tname: \"Student PNP Profile\",\n\t\t\t\t\tconfig: pnp,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tif (currentItemRef && itemSettings) {\n\t\t\t\tprovenanceBuilder.addSource(\"item\", {\n\t\t\t\t\tid: currentItemRef.identifier,\n\t\t\t\t\tname: currentItemRef.identifier,\n\t\t\t\t\tconfig: itemSettings,\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\n\t\t// Collect all PNP support IDs mentioned anywhere\n\t\tconst allSupports = new Set<string>();\n\t\tpnp?.supports?.forEach((s) => allSupports.add(s));\n\t\tpnp?.prohibitedSupports?.forEach((s) => allSupports.add(s));\n\t\tsettings?.districtPolicy?.blockedTools?.forEach((s) => allSupports.add(s));\n\t\tsettings?.districtPolicy?.requiredTools?.forEach((s) => allSupports.add(s));\n\t\titemSettings?.requiredTools?.forEach((s) => allSupports.add(s));\n\t\titemSettings?.restrictedTools?.forEach((s) => allSupports.add(s));\n\n\t\tconst resolved: ResolvedToolConfig[] = [];\n\t\tconst context: ResolutionContext = {\n\t\t\tpnp,\n\t\t\tdistrictPolicy: settings?.districtPolicy,\n\t\t\ttestAdmin: settings?.testAdministration,\n\t\t\titemSettings,\n\t\t\ttoolConfigs: settings?.toolConfigs,\n\t\t};\n\n\t\tfor (const supportId of allSupports) {\n\t\t\tconst config = this.resolveSupport(supportId, context, provenanceBuilder);\n\n\t\t\tif (config) {\n\t\t\t\tresolved.push(config);\n\t\t\t}\n\t\t}\n\n\t\treturn {\n\t\t\ttools: resolved,\n\t\t\tprovenance: provenanceBuilder\n\t\t\t\t? provenanceBuilder.build()\n\t\t\t\t: this.createEmptyProvenance(contextId),\n\t\t};\n\t}\n\n\t/**\n\t * Resolve availability of a single PNP support\n\t *\n\t * Applies precedence rules to determine if support should be enabled.\n\t *\n\t * @param supportId PNP support identifier\n\t * @param context Resolution context with all configuration sources\n\t * @param provenanceBuilder Provenance tracking (optional)\n\t * @returns Resolved config or null if blocked/disabled\n\t */\n\tprivate resolveSupport(\n\t\tsupportId: string,\n\t\tcontext: ResolutionContext,\n\t\tprovenanceBuilder: PnpProvenanceBuilder | null,\n\t): ResolvedToolConfig | null {\n\t\t// Precedence (highest to lowest):\n\n\t\t// 1. District block (absolute veto)\n\t\tif (context.districtPolicy?.blockedTools?.includes(supportId)) {\n\t\t\tprovenanceBuilder?.addDecision({\n\t\t\t\tprecedence: 1,\n\t\t\t\trule: \"district-block\",\n\t\t\t\tfeatureId: supportId,\n\t\t\t\taction: \"block\",\n\t\t\t\tsourceType: \"assessment\",\n\t\t\t\treason: `District policy blocks \"${supportId}\" for all assessments`,\n\t\t\t\tvalue: context.districtPolicy.blockedTools,\n\t\t\t});\n\t\t\treturn null; // Blocked\n\t\t}\n\n\t\t// 2. Test administration override\n\t\tif (context.testAdmin?.toolOverrides?.[supportId] === false) {\n\t\t\tprovenanceBuilder?.addDecision({\n\t\t\t\tprecedence: 2,\n\t\t\t\trule: \"test-admin-override\",\n\t\t\t\tfeatureId: supportId,\n\t\t\t\taction: \"block\",\n\t\t\t\tsourceType: \"assessment\",\n\t\t\t\treason: `Test administrator disabled \"${supportId}\" for this session`,\n\t\t\t\tvalue: context.testAdmin.toolOverrides,\n\t\t\t});\n\t\t\treturn null; // Blocked\n\t\t}\n\n\t\t// 3. Item restriction\n\t\tif (context.itemSettings?.restrictedTools?.includes(supportId)) {\n\t\t\tprovenanceBuilder?.addDecision({\n\t\t\t\tprecedence: 3,\n\t\t\t\trule: \"item-restriction\",\n\t\t\t\tfeatureId: supportId,\n\t\t\t\taction: \"block\",\n\t\t\t\tsourceType: \"item\",\n\t\t\t\treason: `Item restricts \"${supportId}\" (e.g., mental math question blocks calculator)`,\n\t\t\t\tvalue: context.itemSettings.restrictedTools,\n\t\t\t});\n\t\t\treturn null; // Blocked for this item\n\t\t}\n\n\t\t// 4. Item requirement (forces enable)\n\t\tif (context.itemSettings?.requiredTools?.includes(supportId)) {\n\t\t\tprovenanceBuilder?.addDecision({\n\t\t\t\tprecedence: 4,\n\t\t\t\trule: \"item-requirement\",\n\t\t\t\tfeatureId: supportId,\n\t\t\t\taction: \"enable\",\n\t\t\t\tsourceType: \"item\",\n\t\t\t\treason: `Item requires \"${supportId}\" for this question`,\n\t\t\t\tvalue: context.itemSettings.requiredTools,\n\t\t\t});\n\t\t\treturn this.buildToolConfig(supportId, context, {\n\t\t\t\trequired: true,\n\t\t\t\tsource: \"item\",\n\t\t\t});\n\t\t}\n\n\t\t// 5. District requirement\n\t\tif (context.districtPolicy?.requiredTools?.includes(supportId)) {\n\t\t\tprovenanceBuilder?.addDecision({\n\t\t\t\tprecedence: 5,\n\t\t\t\trule: \"district-requirement\",\n\t\t\t\tfeatureId: supportId,\n\t\t\t\taction: \"enable\",\n\t\t\t\tsourceType: \"assessment\",\n\t\t\t\treason: `District policy requires \"${supportId}\" for all assessments`,\n\t\t\t\tvalue: context.districtPolicy.requiredTools,\n\t\t\t});\n\t\t\treturn this.buildToolConfig(supportId, context, {\n\t\t\t\trequired: true,\n\t\t\t\tsource: \"district\",\n\t\t\t});\n\t\t}\n\n\t\t// 6. PNP prohibitions and supports (student needs)\n\t\tif (context.pnp?.prohibitedSupports?.includes(supportId)) {\n\t\t\tprovenanceBuilder?.addDecision({\n\t\t\t\tprecedence: 6,\n\t\t\t\trule: \"pnp-prohibited\",\n\t\t\t\tfeatureId: supportId,\n\t\t\t\taction: \"block\",\n\t\t\t\tsourceType: \"student\",\n\t\t\t\treason: `Student PNP profile prohibits \"${supportId}\"`,\n\t\t\t\tvalue: context.pnp.prohibitedSupports,\n\t\t\t});\n\t\t\treturn null;\n\t\t}\n\n\t\tif (context.pnp?.supports?.includes(supportId)) {\n\t\t\tprovenanceBuilder?.addDecision({\n\t\t\t\tprecedence: 6,\n\t\t\t\trule: \"pnp-support\",\n\t\t\t\tfeatureId: supportId,\n\t\t\t\taction: \"enable\",\n\t\t\t\tsourceType: \"student\",\n\t\t\t\treason: `Student PNP profile requests \"${supportId}\"`,\n\t\t\t\tvalue: context.pnp.supports,\n\t\t\t});\n\n\t\t\treturn this.buildToolConfig(supportId, context, {\n\t\t\t\talwaysAvailable: true,\n\t\t\t\tsource: \"pnp\",\n\t\t\t});\n\t\t}\n\n\t\t// Not enabled - log as skipped\n\t\tprovenanceBuilder?.addDecision({\n\t\t\tprecedence: 6,\n\t\t\trule: \"pnp-support\",\n\t\t\tfeatureId: supportId,\n\t\t\taction: \"skip\",\n\t\t\tsourceType: \"system\",\n\t\t\treason: `Feature \"${supportId}\" not configured at any level`,\n\t\t});\n\n\t\treturn null;\n\t}\n\n\t/**\n\t * Create empty provenance when tracking is disabled\n\t */\n\tprivate createEmptyProvenance(contextId: string): PnpResolutionProvenance {\n\t\treturn {\n\t\t\tcontextId,\n\t\t\tresolvedAt: new Date(),\n\t\t\tsources: {},\n\t\t\tfeatures: new Map(),\n\t\t\tdecisionLog: [],\n\t\t\tsummary: {\n\t\t\t\ttotalFeatures: 0,\n\t\t\t\tenabled: 0,\n\t\t\t\tblocked: 0,\n\t\t\t\tnotConfigured: 0,\n\t\t\t\tbySource: {},\n\t\t\t\tbyRule: {},\n\t\t\t},\n\t\t};\n\t}\n\n\t/**\n\t * Build resolved tool configuration\n\t *\n\t * Maps PNP support ID to PIE tool ID and merges tool-specific settings.\n\t *\n\t * @param supportId PNP support identifier\n\t * @param context Resolution context for settings lookup\n\t * @param flags Availability flags (required, alwaysAvailable, source)\n\t * @returns Complete resolved tool configuration\n\t */\n\tprivate buildToolConfig(\n\t\tsupportId: string,\n\t\tcontext: ResolutionContext,\n\t\tflags: {\n\t\t\trequired?: boolean;\n\t\t\talwaysAvailable?: boolean;\n\t\t\tsource: string;\n\t\t},\n\t): ResolvedToolConfig {\n\t\t// Map PNP support ID to PIE tool ID via registry\n\t\tconst toolIds = this.toolRegistry.getToolsByPNPSupport(supportId);\n\n\t\t// Use first matching tool (usually only one per PNP support)\n\t\t// If no mapping exists, use the support ID directly as tool ID\n\t\tconst pieToolId = toolIds.size > 0 ? Array.from(toolIds)[0] : supportId;\n\n\t\t// Get tool-specific config from settings (item takes precedence)\n\t\tconst toolConfig =\n\t\t\tcontext.itemSettings?.toolParameters?.[supportId] ||\n\t\t\tcontext.toolConfigs?.[supportId];\n\n\t\treturn {\n\t\t\tid: pieToolId,\n\t\t\tenabled: true,\n\t\t\trequired: flags.required || false,\n\t\t\talwaysAvailable: flags.alwaysAvailable || false,\n\t\t\tsettings: toolConfig,\n\t\t\tsource: flags.source as any,\n\t\t};\n\t}\n\n\t/**\n\t * Check if a specific tool is enabled\n\t *\n\t * @param toolId Toolkit tool identifier (e.g., 'calculator')\n\t * @param assessment Assessment with PNP\n\t * @param itemRef Optional item context\n\t * @returns true if tool is enabled\n\t */\n\tisToolEnabled(\n\t\ttoolId: string,\n\t\tassessment: AssessmentEntity,\n\t\titemRef?: AssessmentItemRef,\n\t): boolean {\n\t\tconst resolved = this.resolveTools(assessment, itemRef);\n\t\treturn resolved.some((t) => t.id === toolId && t.enabled);\n\t}\n\n\t/**\n\t * Check if a tool is required (cannot be disabled)\n\t *\n\t * @param toolId Toolkit tool identifier\n\t * @param assessment Assessment with PNP\n\t * @param itemRef Optional item context\n\t * @returns true if tool is required or always available\n\t */\n\tisToolRequired(\n\t\ttoolId: string,\n\t\tassessment: AssessmentEntity,\n\t\titemRef?: AssessmentItemRef,\n\t): boolean {\n\t\tconst resolved = this.resolveTools(assessment, itemRef);\n\t\tconst tool = resolved.find((t) => t.id === toolId);\n\t\treturn tool?.required || tool?.alwaysAvailable || false;\n\t}\n\n\t/**\n\t * Get list of auto-activate tools from PNP\n\t *\n\t * Returns PIE tool IDs that should be automatically opened/activated\n\t * when the assessment starts, based on PNP activateAtInit field.\n\t *\n\t * @param assessment Assessment with PNP\n\t * @returns Array of PIE tool IDs to auto-activate\n\t *\n\t * @example\n\t * const autoActivate = resolver.getAutoActivateTools(assessment);\n\t * // Returns: ['textToSpeech', 'lineReader']\n\t */\n\tgetAutoActivateTools(assessment: AssessmentEntity): string[] {\n\t\tconst pnp = assessment.personalNeedsProfile;\n\t\tif (!pnp?.activateAtInit) return [];\n\n\t\treturn pnp.activateAtInit\n\t\t\t.map((supportId) => {\n\t\t\t\tconst toolIds = this.toolRegistry.getToolsByPNPSupport(supportId);\n\t\t\t\treturn toolIds.size > 0 ? Array.from(toolIds)[0] : null;\n\t\t\t})\n\t\t\t.filter(Boolean) as string[];\n\t}\n\n\t/**\n\t * Get all enabled tools\n\t *\n\t * @param assessment Assessment with PNP\n\t * @param itemRef Optional item context\n\t * @returns Array of PIE tool IDs that are enabled\n\t */\n\tgetEnabledTools(\n\t\tassessment: AssessmentEntity,\n\t\titemRef?: AssessmentItemRef,\n\t): string[] {\n\t\tconst resolved = this.resolveTools(assessment, itemRef);\n\t\treturn Array.from(\n\t\t\tnew Set(\n\t\t\t\tresolved\n\t\t\t\t\t.filter((t) => t.enabled)\n\t\t\t\t\t.map((t) => this.toolRegistry.normalizeToolId(t.id))\n\t\t\t\t\t.filter(Boolean),\n\t\t\t),\n\t\t);\n\t}\n\n\t/**\n\t * Get allowed tool IDs (Pass 1 of two-pass visibility model)\n\t *\n\t * Returns tool IDs that pass orchestrator-level checks (PNP + policies + settings).\n\t * This is the first gate - tools still need to pass Pass 2 (relevance check).\n\t *\n\t * This is the primary method to use with ToolRegistry.filterVisibleInContext()\n\t *\n\t * @param assessment Assessment with PNP\n\t * @param itemRef Optional item context\n\t * @returns Array of allowed tool IDs (Pass 1)\n\t *\n\t * @example\n\t * // Two-pass visibility model\n\t * const allowedToolIds = resolver.getAllowedToolIds(assessment, itemRef);\n\t * const visibleTools = toolRegistry.filterVisibleInContext(allowedToolIds, context);\n\t */\n\tgetAllowedToolIds(\n\t\tassessment: AssessmentEntity,\n\t\titemRef?: AssessmentItemRef,\n\t): string[] {\n\t\treturn this.getEnabledTools(assessment, itemRef);\n\t}\n\n\t/**\n\t * Resolve tools with a test/override PNP profile\n\t *\n\t * FOR TESTING/DEVELOPMENT ONLY\n\t *\n\t * Allows direct injection of a PNP profile for testing accessibility configurations\n\t * without modifying the assessment entity. The override profile replaces the\n\t * assessment's personalNeedsProfile entirely.\n\t *\n\t * Use cases:\n\t * - Development/testing UI for trying different profiles\n\t * - Automated testing with various accessibility configurations\n\t * - Preview tools with profile simulation\n\t * - Accessibility team testing and validation\n\t *\n\t * @param assessment Base assessment (settings, policies, etc.)\n\t * @param overrideProfile PNP profile to inject (replaces assessment.personalNeedsProfile)\n\t * @param itemRef Optional item context\n\t * @returns Resolution result with tools and provenance\n\t *\n\t * @example\n\t * // Test with low vision profile\n\t * const testProfile = {\n\t *   supports: ['magnification', 'textToSpeech', 'highContrastDisplay']\n\t * };\n\t * const result = resolver.resolveWithOverride(assessment, testProfile);\n\t *\n\t * @example\n\t * // Test with null profile (no accessibility features)\n\t * const result = resolver.resolveWithOverride(assessment, null);\n\t */\n\tresolveWithOverride(\n\t\tassessment: AssessmentEntity,\n\t\toverrideProfile: PersonalNeedsProfile | null,\n\t\titemRef?: AssessmentItemRef,\n\t): ToolResolutionResult {\n\t\t// Create assessment clone with overridden PNP\n\t\tconst testAssessment: AssessmentEntity = {\n\t\t\t...assessment,\n\t\t\tpersonalNeedsProfile: overrideProfile || undefined,\n\t\t};\n\n\t\treturn this.resolveToolsWithProvenance(testAssessment, itemRef);\n\t}\n\n\t/**\n\t * Get allowed tool IDs with full provenance tracking\n\t *\n\t * Returns both tool IDs and complete resolution provenance for debugging,\n\t * auditing, and displaying to users.\n\t *\n\t * @param assessment Assessment with PNP\n\t * @param itemRef Optional item context\n\t * @returns Object with tool IDs and provenance\n\t *\n\t * @example\n\t * const result = resolver.getAllowedToolIdsWithProvenance(assessment, itemRef);\n\t *\n\t * // Use tool IDs\n\t * const visibleTools = toolRegistry.filterVisibleInContext(result.toolIds, context);\n\t *\n\t * // Display provenance to user\n\t * console.log('Resolution Summary:', result.provenance.summary);\n\t * console.log('Explanation for calculator:', result.provenance.features.get('calculator')?.explanation);\n\t */\n\tgetAllowedToolIdsWithProvenance(\n\t\tassessment: AssessmentEntity,\n\t\titemRef?: AssessmentItemRef,\n\t): { toolIds: string[]; provenance: PnpResolutionProvenance } {\n\t\tconst result = this.resolveToolsWithProvenance(assessment, itemRef);\n\t\treturn {\n\t\t\ttoolIds: result.tools.map((t) => t.id),\n\t\t\tprovenance: result.provenance,\n\t\t};\n\t}\n\n\t/**\n\t * Get all required tools\n\t *\n\t * @param assessment Assessment with PNP\n\t * @param itemRef Optional item context\n\t * @returns Array of PIE tool IDs that are required\n\t */\n\tgetRequiredTools(\n\t\tassessment: AssessmentEntity,\n\t\titemRef?: AssessmentItemRef,\n\t): string[] {\n\t\tconst resolved = this.resolveTools(assessment, itemRef);\n\t\treturn resolved\n\t\t\t.filter((t) => t.required || t.alwaysAvailable)\n\t\t\t.map((t) => t.id);\n\t}\n\n\t/**\n\t * Get tool configuration settings\n\t *\n\t * @param toolId Toolkit tool identifier\n\t * @param assessment Assessment with PNP\n\t * @param itemRef Optional item context\n\t * @returns Tool-specific settings or null if not found\n\t */\n\tgetToolSettings(\n\t\ttoolId: string,\n\t\tassessment: AssessmentEntity,\n\t\titemRef?: AssessmentItemRef,\n\t): any | null {\n\t\tconst resolved = this.resolveTools(assessment, itemRef);\n\t\tconst tool = resolved.find((t) => t.id === toolId);\n\t\treturn tool?.settings || null;\n\t}\n}\n"]}