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

package/dist/services/pnp-provenance.d.ts

@@ -1,166 +0,0 @@
-/**
- * PNP Resolution Provenance Tracking
- *
- * Provides detailed tracking of how PNP profiles are resolved, including:
- * - Decision steps at each precedence level
- * - Sources of configuration (district, assessment, item, student)
- * - Reasons for tool enablement/blocking
- * - Merge operations and overrides
- *
- * This enables:
- * - Visual explanation components for users
- * - Debugging tool resolution issues
- * - Compliance auditing and reporting
- * - Developer troubleshooting
- *
- * Part of PIE Assessment Toolkit.
- */
-/**
- * Decision made during PNP resolution
- */
-export interface ResolutionDecision {
-    /** Unique step identifier */
-    step: number;
-    /** Precedence level (1-6, lower = higher priority) */
-    precedence: 1 | 2 | 3 | 4 | 5 | 6;
-    /** Human-readable rule name */
-    rule: "district-block" | "test-admin-override" | "item-restriction" | "item-requirement" | "district-requirement" | "pnp-support" | "pnp-prohibited" | "system-default";
-    /** Tool or feature ID being resolved */
-    featureId: string;
-    /** Decision outcome */
-    action: "block" | "enable" | "skip";
-    /** Where the decision came from */
-    source: {
-        type: "organization" | "assessment" | "section" | "item" | "student" | "system";
-        id?: string;
-        name?: string;
-    };
-    /** Why this decision was made */
-    reason: string;
-    /** Configuration value that triggered this decision */
-    value?: any;
-    /** Timestamp of decision */
-    timestamp: Date;
-}
-/**
- * Complete resolution trail for a single feature
- */
-export interface FeatureResolutionTrail {
-    /** Feature ID (QTI 3.0 or tool ID) */
-    featureId: string;
-    /** Final decision */
-    finalState: "enabled" | "blocked" | "not-configured";
-    /** Winning decision (highest precedence) */
-    winningDecision?: ResolutionDecision;
-    /** All decisions considered (in precedence order) */
-    allDecisions: ResolutionDecision[];
-    /** Human-readable explanation */
-    explanation: string;
-}
-/**
- * Complete provenance for an entire PNP resolution
- */
-export interface PnpResolutionProvenance {
-    /** Session or resolution context ID */
-    contextId: string;
-    /** When resolution occurred */
-    resolvedAt: Date;
-    /** All configuration sources consulted */
-    sources: {
-        organization?: {
-            id: string;
-            name: string;
-            pnpDefaults?: any;
-        };
-        assessment?: {
-            id: string;
-            name: string;
-            settings?: any;
-        };
-        section?: {
-            id: string;
-            title?: string;
-            settings?: any;
-        };
-        item?: {
-            id: string;
-            name?: string;
-            settings?: any;
-        };
-        student?: {
-            id: string;
-            pnpProfile?: any;
-        };
-    };
-    /** Resolution trail for each feature */
-    features: Map<string, FeatureResolutionTrail>;
-    /** All decisions in chronological order */
-    decisionLog: ResolutionDecision[];
-    /** Summary statistics */
-    summary: {
-        totalFeatures: number;
-        enabled: number;
-        blocked: number;
-        notConfigured: number;
-        bySource: Record<string, number>;
-        byRule: Record<string, number>;
-    };
-}
-/**
- * Provenance builder for tracking PNP resolution
- */
-export declare class PnpProvenanceBuilder {
-    private provenance;
-    private stepCounter;
-    constructor(contextId: string);
-    /**
-     * Add a configuration source
-     */
-    addSource(type: "organization" | "assessment" | "section" | "item" | "student", data: {
-        id: string;
-        name?: string;
-        config?: any;
-    }): this;
-    /**
-     * Record a decision during resolution
-     */
-    addDecision(params: {
-        precedence: 1 | 2 | 3 | 4 | 5 | 6;
-        rule: ResolutionDecision["rule"];
-        featureId: string;
-        action: "block" | "enable" | "skip";
-        sourceType: ResolutionDecision["source"]["type"];
-        sourceId?: string;
-        sourceName?: string;
-        reason: string;
-        value?: any;
-    }): this;
-    /**
-     * Build final provenance with explanations
-     */
-    build(): PnpResolutionProvenance;
-    /**
-     * Generate human-readable explanation for a feature resolution
-     */
-    private generateExplanation;
-    /**
-     * Get human-readable rule name
-     */
-    private getRuleName;
-    /**
-     * Get current provenance (without explanations)
-     */
-    getCurrent(): PnpResolutionProvenance;
-}
-/**
- * Format provenance as markdown for display
- */
-export declare function formatProvenanceAsMarkdown(provenance: PnpResolutionProvenance): string;
-/**
- * Format provenance as JSON (for APIs)
- */
-export declare function formatProvenanceAsJSON(provenance: PnpResolutionProvenance): string;
-/**
- * Get simple explanation for a specific feature
- */
-export declare function getFeatureExplanation(provenance: PnpResolutionProvenance, featureId: string): string | null;

package/dist/services/pnp-provenance.js

@@ -1,231 +0,0 @@
-/**
- * PNP Resolution Provenance Tracking
- *
- * Provides detailed tracking of how PNP profiles are resolved, including:
- * - Decision steps at each precedence level
- * - Sources of configuration (district, assessment, item, student)
- * - Reasons for tool enablement/blocking
- * - Merge operations and overrides
- *
- * This enables:
- * - Visual explanation components for users
- * - Debugging tool resolution issues
- * - Compliance auditing and reporting
- * - Developer troubleshooting
- *
- * Part of PIE Assessment Toolkit.
- */
-/**
- * Provenance builder for tracking PNP resolution
- */
-export class PnpProvenanceBuilder {
-    provenance;
-    stepCounter = 0;
-    constructor(contextId) {
-        this.provenance = {
-            contextId,
-            resolvedAt: new Date(),
-            sources: {},
-            features: new Map(),
-            decisionLog: [],
-            summary: {
-                totalFeatures: 0,
-                enabled: 0,
-                blocked: 0,
-                notConfigured: 0,
-                bySource: {},
-                byRule: {},
-            },
-        };
-    }
-    /**
-     * Add a configuration source
-     */
-    addSource(type, data) {
-        this.provenance.sources[type] = {
-            id: data.id,
-            name: data.name || data.id,
-            ...(type === "organization" && { pnpDefaults: data.config }),
-            ...(type === "assessment" && { settings: data.config }),
-            ...(type === "section" && { settings: data.config }),
-            ...(type === "item" && { settings: data.config }),
-            ...(type === "student" && { pnpProfile: data.config }),
-        };
-        return this;
-    }
-    /**
-     * Record a decision during resolution
-     */
-    addDecision(params) {
-        const decision = {
-            step: ++this.stepCounter,
-            precedence: params.precedence,
-            rule: params.rule,
-            featureId: params.featureId,
-            action: params.action,
-            source: {
-                type: params.sourceType,
-                id: params.sourceId,
-                name: params.sourceName,
-            },
-            reason: params.reason,
-            value: params.value,
-            timestamp: new Date(),
-        };
-        // Add to decision log
-        this.provenance.decisionLog.push(decision);
-        // Update feature trail
-        if (!this.provenance.features.has(params.featureId)) {
-            this.provenance.features.set(params.featureId, {
-                featureId: params.featureId,
-                finalState: "not-configured",
-                allDecisions: [],
-                explanation: "",
-            });
-        }
-        const trail = this.provenance.features.get(params.featureId);
-        trail.allDecisions.push(decision);
-        // Update winning decision if this has higher precedence
-        if (params.action !== "skip" &&
-            (!trail.winningDecision ||
-                decision.precedence < trail.winningDecision.precedence)) {
-            trail.winningDecision = decision;
-            trail.finalState = decision.action === "enable" ? "enabled" : "blocked";
-        }
-        // Update summary
-        this.provenance.summary.bySource[params.sourceType] =
-            (this.provenance.summary.bySource[params.sourceType] || 0) + 1;
-        this.provenance.summary.byRule[params.rule] =
-            (this.provenance.summary.byRule[params.rule] || 0) + 1;
-        return this;
-    }
-    /**
-     * Build final provenance with explanations
-     */
-    build() {
-        // Generate explanations for each feature
-        for (const [featureId, trail] of this.provenance.features.entries()) {
-            trail.explanation = this.generateExplanation(trail);
-        }
-        // Update summary counts
-        for (const trail of this.provenance.features.values()) {
-            this.provenance.summary.totalFeatures++;
-            if (trail.finalState === "enabled") {
-                this.provenance.summary.enabled++;
-            }
-            else if (trail.finalState === "blocked") {
-                this.provenance.summary.blocked++;
-            }
-            else {
-                this.provenance.summary.notConfigured++;
-            }
-        }
-        return this.provenance;
-    }
-    /**
-     * Generate human-readable explanation for a feature resolution
-     */
-    generateExplanation(trail) {
-        if (!trail.winningDecision) {
-            return `Feature "${trail.featureId}" was not configured at any level.`;
-        }
-        const decision = trail.winningDecision;
-        const source = decision.source;
-        const sourceName = source.name || source.type;
-        let explanation = `Feature "${trail.featureId}" is ${trail.finalState}.\n\n`;
-        // Explain winning decision
-        explanation += `**Primary Reason** (${this.getRuleName(decision.rule)}):\n`;
-        explanation += `${decision.reason}\n`;
-        explanation += `Source: ${sourceName} (${source.type})\n\n`;
-        // Show overridden decisions if any
-        const overridden = trail.allDecisions.filter((d) => d.step !== decision.step &&
-            d.action !== "skip" &&
-            d.precedence > decision.precedence);
-        if (overridden.length > 0) {
-            explanation += `**Overridden Rules**:\n`;
-            overridden.forEach((d) => {
-                explanation += `- ${this.getRuleName(d.rule)}: ${d.reason} (overridden by higher precedence)\n`;
-            });
-        }
-        return explanation;
-    }
-    /**
-     * Get human-readable rule name
-     */
-    getRuleName(rule) {
-        const names = {
-            "district-block": "District Block",
-            "test-admin-override": "Test Administrator Override",
-            "item-restriction": "Item Restriction",
-            "item-requirement": "Item Requirement",
-            "district-requirement": "District Requirement",
-            "pnp-support": "Student PNP Support",
-            "pnp-prohibited": "Student PNP Prohibition",
-            "system-default": "System Default",
-        };
-        return names[rule];
-    }
-    /**
-     * Get current provenance (without explanations)
-     */
-    getCurrent() {
-        return this.provenance;
-    }
-}
-/**
- * Format provenance as markdown for display
- */
-export function formatProvenanceAsMarkdown(provenance) {
-    let md = `# PNP Resolution Report\n\n`;
-    md += `**Context**: ${provenance.contextId}\n`;
-    md += `**Resolved At**: ${provenance.resolvedAt.toISOString()}\n\n`;
-    // Summary
-    md += `## Summary\n\n`;
-    md += `- Total Features: ${provenance.summary.totalFeatures}\n`;
-    md += `- Enabled: ${provenance.summary.enabled}\n`;
-    md += `- Blocked: ${provenance.summary.blocked}\n`;
-    md += `- Not Configured: ${provenance.summary.notConfigured}\n\n`;
-    // Sources
-    md += `## Configuration Sources\n\n`;
-    Object.entries(provenance.sources).forEach(([type, source]) => {
-        const sourceName = source.name || source.title || source.id;
-        md += `- **${type}**: ${sourceName} (${source.id})\n`;
-    });
-    md += `\n`;
-    // Features
-    md += `## Feature Resolution\n\n`;
-    for (const trail of provenance.features.values()) {
-        md += `### ${trail.featureId}\n\n`;
-        md += `**Status**: ${trail.finalState}\n\n`;
-        md += trail.explanation + `\n\n`;
-    }
-    // Decision log
-    md += `## Decision Log\n\n`;
-    provenance.decisionLog.forEach((decision) => {
-        md += `${decision.step}. **${decision.rule}** (precedence ${decision.precedence})\n`;
-        md += `   - Feature: ${decision.featureId}\n`;
-        md += `   - Action: ${decision.action}\n`;
-        md += `   - Source: ${decision.source.name || decision.source.type}\n`;
-        md += `   - Reason: ${decision.reason}\n\n`;
-    });
-    return md;
-}
-/**
- * Format provenance as JSON (for APIs)
- */
-export function formatProvenanceAsJSON(provenance) {
-    // Convert Map to object for JSON serialization
-    const serializable = {
-        ...provenance,
-        features: Array.from(provenance.features.entries()).map(([_featureId, trail]) => trail),
-    };
-    return JSON.stringify(serializable, null, 2);
-}
-/**
- * Get simple explanation for a specific feature
- */
-export function getFeatureExplanation(provenance, featureId) {
-    const trail = provenance.features.get(featureId);
-    return trail?.explanation || null;
-}
-//# sourceMappingURL=pnp-provenance.js.map

package/dist/services/pnp-provenance.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"pnp-provenance.js","sourceRoot":"","sources":["../../src/services/pnp-provenance.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * PNP Resolution Provenance Tracking\n *\n * Provides detailed tracking of how PNP profiles are resolved, including:\n * - Decision steps at each precedence level\n * - Sources of configuration (district, assessment, item, student)\n * - Reasons for tool enablement/blocking\n * - Merge operations and overrides\n *\n * This enables:\n * - Visual explanation components for users\n * - Debugging tool resolution issues\n * - Compliance auditing and reporting\n * - Developer troubleshooting\n *\n * Part of PIE Assessment Toolkit.\n */\n\n/**\n * Decision made during PNP resolution\n */\nexport interface ResolutionDecision {\n\t/** Unique step identifier */\n\tstep: number;\n\n\t/** Precedence level (1-6, lower = higher priority) */\n\tprecedence: 1 | 2 | 3 | 4 | 5 | 6;\n\n\t/** Human-readable rule name */\n\trule:\n\t\t| \"district-block\"\n\t\t| \"test-admin-override\"\n\t\t| \"item-restriction\"\n\t\t| \"item-requirement\"\n\t\t| \"district-requirement\"\n\t\t| \"pnp-support\"\n\t\t| \"pnp-prohibited\"\n\t\t| \"system-default\";\n\n\t/** Tool or feature ID being resolved */\n\tfeatureId: string;\n\n\t/** Decision outcome */\n\taction: \"block\" | \"enable\" | \"skip\";\n\n\t/** Where the decision came from */\n\tsource: {\n\t\ttype:\n\t\t\t| \"organization\"\n\t\t\t| \"assessment\"\n\t\t\t| \"section\"\n\t\t\t| \"item\"\n\t\t\t| \"student\"\n\t\t\t| \"system\";\n\t\tid?: string; // Entity ID (e.g., org ID, assessment ID)\n\t\tname?: string; // Human-readable name\n\t};\n\n\t/** Why this decision was made */\n\treason: string;\n\n\t/** Configuration value that triggered this decision */\n\tvalue?: any;\n\n\t/** Timestamp of decision */\n\ttimestamp: Date;\n}\n\n/**\n * Complete resolution trail for a single feature\n */\nexport interface FeatureResolutionTrail {\n\t/** Feature ID (QTI 3.0 or tool ID) */\n\tfeatureId: string;\n\n\t/** Final decision */\n\tfinalState: \"enabled\" | \"blocked\" | \"not-configured\";\n\n\t/** Winning decision (highest precedence) */\n\twinningDecision?: ResolutionDecision;\n\n\t/** All decisions considered (in precedence order) */\n\tallDecisions: ResolutionDecision[];\n\n\t/** Human-readable explanation */\n\texplanation: string;\n}\n\n/**\n * Complete provenance for an entire PNP resolution\n */\nexport interface PnpResolutionProvenance {\n\t/** Session or resolution context ID */\n\tcontextId: string;\n\n\t/** When resolution occurred */\n\tresolvedAt: Date;\n\n\t/** All configuration sources consulted */\n\tsources: {\n\t\torganization?: {\n\t\t\tid: string;\n\t\t\tname: string;\n\t\t\tpnpDefaults?: any;\n\t\t};\n\t\tassessment?: {\n\t\t\tid: string;\n\t\t\tname: string;\n\t\t\tsettings?: any;\n\t\t};\n\t\tsection?: {\n\t\t\tid: string;\n\t\t\ttitle?: string;\n\t\t\tsettings?: any;\n\t\t};\n\t\titem?: {\n\t\t\tid: string;\n\t\t\tname?: string;\n\t\t\tsettings?: any;\n\t\t};\n\t\tstudent?: {\n\t\t\tid: string;\n\t\t\tpnpProfile?: any;\n\t\t};\n\t};\n\n\t/** Resolution trail for each feature */\n\tfeatures: Map<string, FeatureResolutionTrail>;\n\n\t/** All decisions in chronological order */\n\tdecisionLog: ResolutionDecision[];\n\n\t/** Summary statistics */\n\tsummary: {\n\t\ttotalFeatures: number;\n\t\tenabled: number;\n\t\tblocked: number;\n\t\tnotConfigured: number;\n\t\tbySource: Record<string, number>;\n\t\tbyRule: Record<string, number>;\n\t};\n}\n\n/**\n * Provenance builder for tracking PNP resolution\n */\nexport class PnpProvenanceBuilder {\n\tprivate provenance: PnpResolutionProvenance;\n\tprivate stepCounter = 0;\n\n\tconstructor(contextId: string) {\n\t\tthis.provenance = {\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 * Add a configuration source\n\t */\n\taddSource(\n\t\ttype: \"organization\" | \"assessment\" | \"section\" | \"item\" | \"student\",\n\t\tdata: { id: string; name?: string; config?: any },\n\t): this {\n\t\tthis.provenance.sources[type] = {\n\t\t\tid: data.id,\n\t\t\tname: data.name || data.id,\n\t\t\t...(type === \"organization\" && { pnpDefaults: data.config }),\n\t\t\t...(type === \"assessment\" && { settings: data.config }),\n\t\t\t...(type === \"section\" && { settings: data.config }),\n\t\t\t...(type === \"item\" && { settings: data.config }),\n\t\t\t...(type === \"student\" && { pnpProfile: data.config }),\n\t\t} as any;\n\t\treturn this;\n\t}\n\n\t/**\n\t * Record a decision during resolution\n\t */\n\taddDecision(params: {\n\t\tprecedence: 1 | 2 | 3 | 4 | 5 | 6;\n\t\trule: ResolutionDecision[\"rule\"];\n\t\tfeatureId: string;\n\t\taction: \"block\" | \"enable\" | \"skip\";\n\t\tsourceType: ResolutionDecision[\"source\"][\"type\"];\n\t\tsourceId?: string;\n\t\tsourceName?: string;\n\t\treason: string;\n\t\tvalue?: any;\n\t}): this {\n\t\tconst decision: ResolutionDecision = {\n\t\t\tstep: ++this.stepCounter,\n\t\t\tprecedence: params.precedence,\n\t\t\trule: params.rule,\n\t\t\tfeatureId: params.featureId,\n\t\t\taction: params.action,\n\t\t\tsource: {\n\t\t\t\ttype: params.sourceType,\n\t\t\t\tid: params.sourceId,\n\t\t\t\tname: params.sourceName,\n\t\t\t},\n\t\t\treason: params.reason,\n\t\t\tvalue: params.value,\n\t\t\ttimestamp: new Date(),\n\t\t};\n\n\t\t// Add to decision log\n\t\tthis.provenance.decisionLog.push(decision);\n\n\t\t// Update feature trail\n\t\tif (!this.provenance.features.has(params.featureId)) {\n\t\t\tthis.provenance.features.set(params.featureId, {\n\t\t\t\tfeatureId: params.featureId,\n\t\t\t\tfinalState: \"not-configured\",\n\t\t\t\tallDecisions: [],\n\t\t\t\texplanation: \"\",\n\t\t\t});\n\t\t}\n\n\t\tconst trail = this.provenance.features.get(params.featureId)!;\n\t\ttrail.allDecisions.push(decision);\n\n\t\t// Update winning decision if this has higher precedence\n\t\tif (\n\t\t\tparams.action !== \"skip\" &&\n\t\t\t(!trail.winningDecision ||\n\t\t\t\tdecision.precedence < trail.winningDecision.precedence)\n\t\t) {\n\t\t\ttrail.winningDecision = decision;\n\t\t\ttrail.finalState = decision.action === \"enable\" ? \"enabled\" : \"blocked\";\n\t\t}\n\n\t\t// Update summary\n\t\tthis.provenance.summary.bySource[params.sourceType] =\n\t\t\t(this.provenance.summary.bySource[params.sourceType] || 0) + 1;\n\t\tthis.provenance.summary.byRule[params.rule] =\n\t\t\t(this.provenance.summary.byRule[params.rule] || 0) + 1;\n\n\t\treturn this;\n\t}\n\n\t/**\n\t * Build final provenance with explanations\n\t */\n\tbuild(): PnpResolutionProvenance {\n\t\t// Generate explanations for each feature\n\t\tfor (const [featureId, trail] of this.provenance.features.entries()) {\n\t\t\ttrail.explanation = this.generateExplanation(trail);\n\t\t}\n\n\t\t// Update summary counts\n\t\tfor (const trail of this.provenance.features.values()) {\n\t\t\tthis.provenance.summary.totalFeatures++;\n\t\t\tif (trail.finalState === \"enabled\") {\n\t\t\t\tthis.provenance.summary.enabled++;\n\t\t\t} else if (trail.finalState === \"blocked\") {\n\t\t\t\tthis.provenance.summary.blocked++;\n\t\t\t} else {\n\t\t\t\tthis.provenance.summary.notConfigured++;\n\t\t\t}\n\t\t}\n\n\t\treturn this.provenance;\n\t}\n\n\t/**\n\t * Generate human-readable explanation for a feature resolution\n\t */\n\tprivate generateExplanation(trail: FeatureResolutionTrail): string {\n\t\tif (!trail.winningDecision) {\n\t\t\treturn `Feature \"${trail.featureId}\" was not configured at any level.`;\n\t\t}\n\n\t\tconst decision = trail.winningDecision;\n\t\tconst source = decision.source;\n\t\tconst sourceName = source.name || source.type;\n\n\t\tlet explanation = `Feature \"${trail.featureId}\" is ${trail.finalState}.\\n\\n`;\n\n\t\t// Explain winning decision\n\t\texplanation += `**Primary Reason** (${this.getRuleName(decision.rule)}):\\n`;\n\t\texplanation += `${decision.reason}\\n`;\n\t\texplanation += `Source: ${sourceName} (${source.type})\\n\\n`;\n\n\t\t// Show overridden decisions if any\n\t\tconst overridden = trail.allDecisions.filter(\n\t\t\t(d) =>\n\t\t\t\td.step !== decision.step &&\n\t\t\t\td.action !== \"skip\" &&\n\t\t\t\td.precedence > decision.precedence,\n\t\t);\n\n\t\tif (overridden.length > 0) {\n\t\t\texplanation += `**Overridden Rules**:\\n`;\n\t\t\toverridden.forEach((d) => {\n\t\t\t\texplanation += `- ${this.getRuleName(d.rule)}: ${d.reason} (overridden by higher precedence)\\n`;\n\t\t\t});\n\t\t}\n\n\t\treturn explanation;\n\t}\n\n\t/**\n\t * Get human-readable rule name\n\t */\n\tprivate getRuleName(rule: ResolutionDecision[\"rule\"]): string {\n\t\tconst names: Record<ResolutionDecision[\"rule\"], string> = {\n\t\t\t\"district-block\": \"District Block\",\n\t\t\t\"test-admin-override\": \"Test Administrator Override\",\n\t\t\t\"item-restriction\": \"Item Restriction\",\n\t\t\t\"item-requirement\": \"Item Requirement\",\n\t\t\t\"district-requirement\": \"District Requirement\",\n\t\t\t\"pnp-support\": \"Student PNP Support\",\n\t\t\t\"pnp-prohibited\": \"Student PNP Prohibition\",\n\t\t\t\"system-default\": \"System Default\",\n\t\t};\n\t\treturn names[rule];\n\t}\n\n\t/**\n\t * Get current provenance (without explanations)\n\t */\n\tgetCurrent(): PnpResolutionProvenance {\n\t\treturn this.provenance;\n\t}\n}\n\n/**\n * Format provenance as markdown for display\n */\nexport function formatProvenanceAsMarkdown(\n\tprovenance: PnpResolutionProvenance,\n): string {\n\tlet md = `# PNP Resolution Report\\n\\n`;\n\tmd += `**Context**: ${provenance.contextId}\\n`;\n\tmd += `**Resolved At**: ${provenance.resolvedAt.toISOString()}\\n\\n`;\n\n\t// Summary\n\tmd += `## Summary\\n\\n`;\n\tmd += `- Total Features: ${provenance.summary.totalFeatures}\\n`;\n\tmd += `- Enabled: ${provenance.summary.enabled}\\n`;\n\tmd += `- Blocked: ${provenance.summary.blocked}\\n`;\n\tmd += `- Not Configured: ${provenance.summary.notConfigured}\\n\\n`;\n\n\t// Sources\n\tmd += `## Configuration Sources\\n\\n`;\n\tObject.entries(provenance.sources).forEach(([type, source]) => {\n\t\tconst sourceName =\n\t\t\t(source as any).name || (source as any).title || source.id;\n\t\tmd += `- **${type}**: ${sourceName} (${source.id})\\n`;\n\t});\n\tmd += `\\n`;\n\n\t// Features\n\tmd += `## Feature Resolution\\n\\n`;\n\tfor (const trail of provenance.features.values()) {\n\t\tmd += `### ${trail.featureId}\\n\\n`;\n\t\tmd += `**Status**: ${trail.finalState}\\n\\n`;\n\t\tmd += trail.explanation + `\\n\\n`;\n\t}\n\n\t// Decision log\n\tmd += `## Decision Log\\n\\n`;\n\tprovenance.decisionLog.forEach((decision) => {\n\t\tmd += `${decision.step}. **${decision.rule}** (precedence ${decision.precedence})\\n`;\n\t\tmd += `   - Feature: ${decision.featureId}\\n`;\n\t\tmd += `   - Action: ${decision.action}\\n`;\n\t\tmd += `   - Source: ${decision.source.name || decision.source.type}\\n`;\n\t\tmd += `   - Reason: ${decision.reason}\\n\\n`;\n\t});\n\n\treturn md;\n}\n\n/**\n * Format provenance as JSON (for APIs)\n */\nexport function formatProvenanceAsJSON(\n\tprovenance: PnpResolutionProvenance,\n): string {\n\t// Convert Map to object for JSON serialization\n\tconst serializable = {\n\t\t...provenance,\n\t\tfeatures: Array.from(provenance.features.entries()).map(\n\t\t\t([_featureId, trail]) => trail,\n\t\t),\n\t};\n\treturn JSON.stringify(serializable, null, 2);\n}\n\n/**\n * Get simple explanation for a specific feature\n */\nexport function getFeatureExplanation(\n\tprovenance: PnpResolutionProvenance,\n\tfeatureId: string,\n): string | null {\n\tconst trail = provenance.features.get(featureId);\n\treturn trail?.explanation || null;\n}\n"]}