@pie-players/pie-assessment-toolkit 0.2.3 → 0.2.4

package/dist/services/PNPToolResolver.d.ts

@@ -2,19 +2,49 @@
  * PNP Tool Resolver
  *
  * Resolves tool availability from QTI 3.0 Personal Needs Profile (PNP) and
- * assessment settings. Implements precedence hierarchy for tool configuration.
+ * assessment settings. Implements a precedence hierarchy for tool configuration
+ * based on common assessment platform governance patterns.
  *
- * Precedence (highest to lowest):
- * 1. District block (absolute veto)
- * 2. Test administration override
- * 3. Item restriction (per-item block)
- * 4. Item requirement (forces enable)
- * 5. District requirement
- * 6. PNP supports (student needs)
+ * 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 } from "@pie-players/pie-players-shared/types";
+import type { AssessmentEntity, AssessmentItemRef, PersonalNeedsProfile } from "@pie-players/pie-players-shared/types";
+import type { ToolRegistry } from "./ToolRegistry";
+import { type PNPResolutionProvenance } from "./pnp-provenance";
 /**
  * Resolved tool configuration with source tracking
  */
@@ -26,25 +56,72 @@ export interface ResolvedToolConfig {
     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
+     * @returns Array of resolved tool configurations (for backward compatibility)
+     *
+     * @deprecated Use resolveToolsWithProvenance() to get provenance tracking
      *
      * @example
-     * const resolver = new PNPToolResolver();
+     * 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
      *
@@ -52,9 +129,14 @@ export declare class PNPToolResolver {
      *
      * @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
      *
@@ -69,7 +151,7 @@ export declare class PNPToolResolver {
     /**
      * Check if a specific tool is enabled
      *
-     * @param toolId PIE tool identifier (e.g., 'pie-tool-calculator')
+     * @param toolId Toolkit tool identifier (e.g., 'calculator')
      * @param assessment Assessment with PNP
      * @param itemRef Optional item context
      * @returns true if tool is enabled
@@ -78,7 +160,7 @@ export declare class PNPToolResolver {
     /**
      * Check if a tool is required (cannot be disabled)
      *
-     * @param toolId PIE tool identifier
+     * @param toolId Toolkit tool identifier
      * @param assessment Assessment with PNP
      * @param itemRef Optional item context
      * @returns true if tool is required or always available
@@ -95,7 +177,7 @@ export declare class PNPToolResolver {
      *
      * @example
      * const autoActivate = resolver.getAutoActivateTools(assessment);
-     * // Returns: ['pie-tool-text-to-speech', 'pie-tool-line-reader']
+     * // Returns: ['textToSpeech', 'lineReader']
      */
     getAutoActivateTools(assessment: AssessmentEntity): string[];
     /**
@@ -106,6 +188,80 @@ export declare class PNPToolResolver {
      * @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
      *
@@ -117,7 +273,7 @@ export declare class PNPToolResolver {
     /**
      * Get tool configuration settings
      *
-     * @param toolId PIE tool identifier
+     * @param toolId Toolkit tool identifier
      * @param assessment Assessment with PNP
      * @param itemRef Optional item context
      * @returns Tool-specific settings or null if not found

package/dist/services/PNPToolResolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PNPToolResolver.d.ts","sourceRoot":"","sources":["../../src/services/PNPToolResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACX,gBAAgB,EAChB,iBAAiB,EAIjB,MAAM,uCAAuC,CAAC;AAG/C;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,GAAG,CAAC;IACf,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,UAAU,CAAC;CACjD;AAaD;;GAEG;AACH,qBAAa,eAAe;IAC3B;;;;;;;;;;;;;OAaG;IACH,YAAY,CACX,UAAU,EAAE,gBAAgB,EAC5B,cAAc,CAAC,EAAE,iBAAiB,GAChC,kBAAkB,EAAE;IAgCvB;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAsDtB;;;;;;;;;OASG;IACH,OAAO,CAAC,eAAe;IA2BvB;;;;;;;OAOG;IACH,aAAa,CACZ,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,gBAAgB,EAC5B,OAAO,CAAC,EAAE,iBAAiB,GACzB,OAAO;IAKV;;;;;;;OAOG;IACH,cAAc,CACb,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,gBAAgB,EAC5B,OAAO,CAAC,EAAE,iBAAiB,GACzB,OAAO;IAMV;;;;;;;;;;;;OAYG;IACH,oBAAoB,CAAC,UAAU,EAAE,gBAAgB,GAAG,MAAM,EAAE;IAS5D;;;;;;OAMG;IACH,eAAe,CACd,UAAU,EAAE,gBAAgB,EAC5B,OAAO,CAAC,EAAE,iBAAiB,GACzB,MAAM,EAAE;IAKX;;;;;;OAMG;IACH,gBAAgB,CACf,UAAU,EAAE,gBAAgB,EAC5B,OAAO,CAAC,EAAE,iBAAiB,GACzB,MAAM,EAAE;IAOX;;;;;;;OAOG;IACH,eAAe,CACd,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,gBAAgB,EAC5B,OAAO,CAAC,EAAE,iBAAiB,GACzB,GAAG,GAAG,IAAI;CAKb"}
+{"version":3,"file":"PNPToolResolver.d.ts","sourceRoot":"","sources":["../../src/services/PNPToolResolver.ts"],"names":[],"mappings":"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"}