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

package/dist/services/PNPToolResolver.d.ts

@@ -1,280 +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 type { AssessmentEntity, AssessmentItemRef, PersonalNeedsProfile } from "@pie-players/pie-players-shared/types";
-import type { ToolRegistry } from "./ToolRegistry.js";
-import { type PnpResolutionProvenance } from "./pnp-provenance.js";
-/**
- * Resolved tool configuration with source tracking
- */
-export interface ResolvedToolConfig {
-    id: string;
-    enabled: boolean;
-    required?: boolean;
-    alwaysAvailable?: boolean;
-    settings?: any;
-    source: "district" | "item" | "pnp" | "settings";
-}
-/**
- * Resolution result with provenance tracking
- */
-export interface ToolResolutionResult {
-    /** Resolved tool configurations */
-    tools: ResolvedToolConfig[];
-    /** Complete provenance trail (for debugging/display) */
-    provenance: PnpResolutionProvenance;
-}
-/**
- * Resolves tool availability from QTI 3.0 assessment structure
- */
-export declare class PnpToolResolver {
-    private toolRegistry;
-    private enableProvenance;
-    /**
-     * Create a PnpToolResolver
-     *
-     * @param toolRegistry Tool registry for PNP support mapping
-     * @param enableProvenance Enable detailed provenance tracking (default: true)
-     */
-    constructor(toolRegistry: ToolRegistry, enableProvenance?: boolean);
-    /**
-     * 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: AssessmentEntity, currentItemRef?: AssessmentItemRef): ResolvedToolConfig[];
-    /**
-     * 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: AssessmentEntity, currentItemRef?: AssessmentItemRef): ToolResolutionResult;
-    /**
-     * 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
-     */
-    private resolveSupport;
-    /**
-     * Create empty provenance when tracking is disabled
-     */
-    private createEmptyProvenance;
-    /**
-     * 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
-     */
-    private buildToolConfig;
-    /**
-     * 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: string, assessment: AssessmentEntity, itemRef?: AssessmentItemRef): boolean;
-    /**
-     * 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: string, assessment: AssessmentEntity, itemRef?: AssessmentItemRef): boolean;
-    /**
-     * 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: AssessmentEntity): string[];
-    /**
-     * 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: AssessmentEntity, itemRef?: AssessmentItemRef): string[];
-    /**
-     * 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: AssessmentEntity, itemRef?: AssessmentItemRef): string[];
-    /**
-     * 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: AssessmentEntity, overrideProfile: PersonalNeedsProfile | null, itemRef?: AssessmentItemRef): ToolResolutionResult;
-    /**
-     * 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: AssessmentEntity, itemRef?: AssessmentItemRef): {
-        toolIds: string[];
-        provenance: PnpResolutionProvenance;
-    };
-    /**
-     * 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: AssessmentEntity, itemRef?: AssessmentItemRef): string[];
-    /**
-     * 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: string, assessment: AssessmentEntity, itemRef?: AssessmentItemRef): any | null;
-}