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

package/dist/policy/engine.js

@@ -0,0 +1,24 @@
+/**
+ * Tool policy engine — facade entry point (M8 PR 1).
+ *
+ * Narrow, stable public surface for hosts that want to instantiate or
+ * consume a `ToolPolicyEngine`. Re-exports the engine class, its
+ * decision request/response types, the Svelte context key, and the
+ * minimal `PolicySource` extension contract.
+ *
+ * **Pairing.** This module is the stable counterpart to
+ * `./policy/internal`, which exposes the wider, evolving surface
+ * (composition pipeline, provenance builder, QTI source). Consumers
+ * that only need to drive an engine and read its decisions should
+ * import from here. Consumers that need to reach past the facade
+ * (e.g. test the composition pipeline directly, build a custom QTI
+ * source variant, instrument provenance generation) should import
+ * from `./policy/internal` and accept the documented stability
+ * disclaimer there.
+ *
+ * Mirrors the M7 `runtime/engine` / `runtime/internal` split — see
+ * the same rationale in `src/runtime/engine.ts`.
+ */
+export { ToolPolicyEngine, } from "./core/ToolPolicyEngine.js";
+export { TOOL_POLICY_ENGINE_KEY, } from "./core/engine-context.js";
+//# sourceMappingURL=engine.js.map

package/dist/policy/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/policy/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACN,gBAAgB,GAOhB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACN,sBAAsB,GAEtB,MAAM,0BAA0B,CAAC"}

package/dist/policy/internal.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Tool policy engine — **internal** entry point (M8 PR 1).
+ *
+ * Re-exports the composition pipeline, the QTI source, and the
+ * provenance builder for advanced hosts that want to drive the engine
+ * components directly, and for the engine's own tests.
+ *
+ * **Stability posture.** This module is **not** part of the stable
+ * public API. Symbols here are subject to change between minor
+ * versions with only a changeset note. Hosts that need long-term
+ * stability should depend on the facade (`ToolPolicyEngine` exported
+ * from `./policy/engine`) instead.
+ *
+ * The split is intentional:
+ *   - `./policy/engine`   — narrow, stable facade for common host
+ *                           wiring and Svelte context.
+ *   - `./policy/internal` — wide, evolving surface for the
+ *                           composition pipeline, QTI source, and
+ *                           any host that wants to reach past the
+ *                           facade.
+ */
+export { composeDecision, type ComposeDecisionInputs, } from "./core/compose-decision.js";
+export { QtiPolicySource, type QtiPolicyApplyArgs, type QtiPolicyDecisionEvent, type QtiPolicyResult, type QtiToolFlags, } from "./sources/QtiPolicySource.js";
+export { ToolPolicyProvenanceBuilder } from "./core/provenance.js";
+export { assessmentHasQtiInputs, itemRefHasQtiInputs, resolveDefaultQtiEnforcement, } from "./core/qti-inputs.js";
+//# sourceMappingURL=internal.d.ts.map

package/dist/policy/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/policy/internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACN,eAAe,EACf,KAAK,qBAAqB,GAC1B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACN,eAAe,EACf,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,YAAY,GACjB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AAEnE,OAAO,EACN,sBAAsB,EACtB,mBAAmB,EACnB,4BAA4B,GAC5B,MAAM,sBAAsB,CAAC"}

package/dist/policy/internal.js

@@ -0,0 +1,26 @@
+/**
+ * Tool policy engine — **internal** entry point (M8 PR 1).
+ *
+ * Re-exports the composition pipeline, the QTI source, and the
+ * provenance builder for advanced hosts that want to drive the engine
+ * components directly, and for the engine's own tests.
+ *
+ * **Stability posture.** This module is **not** part of the stable
+ * public API. Symbols here are subject to change between minor
+ * versions with only a changeset note. Hosts that need long-term
+ * stability should depend on the facade (`ToolPolicyEngine` exported
+ * from `./policy/engine`) instead.
+ *
+ * The split is intentional:
+ *   - `./policy/engine`   — narrow, stable facade for common host
+ *                           wiring and Svelte context.
+ *   - `./policy/internal` — wide, evolving surface for the
+ *                           composition pipeline, QTI source, and
+ *                           any host that wants to reach past the
+ *                           facade.
+ */
+export { composeDecision, } from "./core/compose-decision.js";
+export { QtiPolicySource, } from "./sources/QtiPolicySource.js";
+export { ToolPolicyProvenanceBuilder } from "./core/provenance.js";
+export { assessmentHasQtiInputs, itemRefHasQtiInputs, resolveDefaultQtiEnforcement, } from "./core/qti-inputs.js";
+//# sourceMappingURL=internal.js.map

package/dist/policy/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../../src/policy/internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACN,eAAe,GAEf,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACN,eAAe,GAKf,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AAEnE,OAAO,EACN,sBAAsB,EACtB,mBAAmB,EACnB,4BAA4B,GAC5B,MAAM,sBAAsB,CAAC"}

package/dist/policy/sources/QtiPolicySource.d.ts

@@ -0,0 +1,146 @@
+/**
+ * QTI Policy Source — refactor of `PnpToolResolver` for the M8 engine
+ * (see `.cursor/plans/m8-design.md` § 3 step 5 and § 5 §).
+ *
+ * This source applies the QTI 6-level precedence rules used by today's
+ * `PnpToolResolver` but exposes them as a `(candidates, qtiInputs) →
+ * (refinedCandidates, perToolFlags, mandates, decisions)` function the
+ * engine can call once per `decide(...)` request, with all results
+ * routed through the unified `ToolPolicyProvenanceBuilder`.
+ *
+ * **Why this lives next to the legacy resolver instead of replacing
+ * it.** PR 1 introduces the engine without callers; the legacy
+ * `PnpToolResolver` is still in active use by `<pie-item-toolbar>`
+ * and by external tests. PR 5 deletes the legacy class once the
+ * toolbar (PR 3) and the QTI default flip (PR 4) have landed and the
+ * caller list is empty. Until then this source is the *canonical*
+ * implementation and the legacy class is the deprecated mirror.
+ */
+import type { AssessmentEntity, AssessmentItemRef } from "@pie-players/pie-players-shared/types";
+import type { ToolRegistry } from "../../services/ToolRegistry.js";
+import type { ToolPolicyResolutionDecision, ToolPolicySourceType } from "../core/provenance.js";
+import type { QtiPolicySourceRule } from "../core/policy-source-tag.js";
+/** Per-tool flags QTI may attach to a surviving entry. */
+export interface QtiToolFlags {
+    /** QTI mandates this tool (item or district `requiredTools`). */
+    required: boolean;
+    /** QTI marks this tool as a PNP support (host UI cannot toggle off). */
+    alwaysAvailable: boolean;
+    /** Tool-specific settings derived from item / assessment settings. */
+    settings?: unknown;
+    /** Which QTI rule contributed the surviving verdict. */
+    rule: QtiPolicySourceRule;
+    /** Source attribution for `ToolPolicyEntry.sources`. */
+    sourceType: ToolPolicySourceType;
+}
+export interface QtiPolicyApplyArgs {
+    assessment: AssessmentEntity;
+    currentItemRef?: AssessmentItemRef;
+}
+/**
+ * Provenance event the engine should append to its builder. Pre-baked
+ * here so the source has a single allocation pattern and the engine
+ * keeps a uniform `addDecision(...)` shape.
+ */
+export interface QtiPolicyDecisionEvent {
+    precedence: 1 | 2 | 3 | 4 | 5 | 6;
+    rule: "district-block" | "test-admin-override" | "item-restriction" | "item-requirement" | "district-requirement" | "pnp-support" | "pnp-prohibited";
+    featureId: string;
+    action: ToolPolicyResolutionDecision["action"];
+    sourceType: ToolPolicySourceType;
+    reason: string;
+    value?: unknown;
+}
+export interface QtiPolicyResult {
+    /**
+     * Tool IDs QTI explicitly blocked. Engine removes these from the
+     * candidate set in step 5.
+     */
+    blockedToolIds: Set<string>;
+    /**
+     * Tool IDs QTI mandates (item or district `requiredTools`). Used
+     * by the engine to detect `tool-policy.qtiRequiredBlocked`
+     * diagnostics for tools removed by host policy.
+     */
+    mandatedToolIds: Set<string>;
+    /**
+     * Per-tool flags merged into surviving `ToolPolicyEntry`s.
+     */
+    perToolFlags: Map<string, QtiToolFlags>;
+    /**
+     * Decision log entries the engine must record. Order matches the
+     * order rules fired internally (highest precedence first per
+     * support id).
+     */
+    decisions: QtiPolicyDecisionEvent[];
+    /** Configuration sources the engine should attach to its provenance. */
+    sources: {
+        assessment?: {
+            id: string;
+            name: string;
+            config?: unknown;
+        };
+        student?: {
+            id: string;
+            name: string;
+            config?: unknown;
+        };
+        item?: {
+            id: string;
+            name: string;
+            config?: unknown;
+        };
+    };
+}
+export declare class QtiPolicySource {
+    readonly id = "qti";
+    private readonly toolRegistry;
+    constructor(toolRegistry: ToolRegistry);
+    apply(args: QtiPolicyApplyArgs): QtiPolicyResult;
+    private resolveSupport;
+    /**
+     * Map a QTI / PNP support id (e.g. `"calculator-basic"`) to the
+     * registered tool id that owns it.
+     *
+     * Resolution rules:
+     *
+     *   1. **Multiple tools register the same support id:** the
+     *      *first-registered* tool wins. `ToolRegistry.getToolsByPNPSupport`
+     *      returns a `Set<string>` whose iteration order matches the
+     *      `register(...)` insertion order, so the result is
+     *      deterministic across runs but order-sensitive at registration
+     *      time. This is an unusual configuration — the typical case is
+     *      one tool per support id — but it is reachable when an
+     *      integrator overrides a default tool with a replacement that
+     *      claims the same `pnpSupportIds`. In that case the integrator
+     *      should `unregister(...)` the default before registering the
+     *      replacement.
+     *
+     *   2. **No tool registers the support id:** the support id is
+     *      returned verbatim as the `featureId` for provenance trails
+     *      and `ToolPolicyEntry.toolId`. This lets hosts use raw QTI
+     *      strings for tools the registry does not (yet) carry without
+     *      losing them in policy evaluation.
+     *
+     * The legacy `PnpToolResolver.resolveTool` had the same behavior;
+     * see `tests/policy/QtiPolicySource.test.ts` for the regression
+     * lock.
+     */
+    private mapSupportToToolId;
+    /**
+     * Resolve tool-specific settings, item-level taking precedence over
+     * assessment-level.
+     *
+     * Uses `??` (nullish-coalescing) rather than the legacy resolver's
+     * `||`. Tool config values are typed `unknown` and may legitimately
+     * be `false` / `0` / `""` (e.g. a tool whose canonical "off" config
+     * is the literal `false`). `||` would treat those as missing and
+     * silently fall through to the assessment-level config, masking the
+     * authored item-level intent. `??` only falls through on
+     * `null`/`undefined`, which matches the semantic of "value not
+     * provided." This is a deliberate behavior delta from the legacy
+     * `PnpToolResolver` (M8 PR 1).
+     */
+    private resolveToolSettings;
+}
+//# sourceMappingURL=QtiPolicySource.d.ts.map

package/dist/policy/sources/QtiPolicySource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QtiPolicySource.d.ts","sourceRoot":"","sources":["../../../src/policy/sources/QtiPolicySource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EACX,gBAAgB,EAChB,iBAAiB,EAIjB,MAAM,uCAAuC,CAAC;AAE/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,KAAK,EACX,4BAA4B,EAC5B,oBAAoB,EACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAExE,0DAA0D;AAC1D,MAAM,WAAW,YAAY;IAC5B,iEAAiE;IACjE,QAAQ,EAAE,OAAO,CAAC;IAClB,wEAAwE;IACxE,eAAe,EAAE,OAAO,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wDAAwD;IACxD,IAAI,EAAE,mBAAmB,CAAC;IAC1B,wDAAwD;IACxD,UAAU,EAAE,oBAAoB,CAAC;CACjC;AAED,MAAM,WAAW,kBAAkB;IAClC,UAAU,EAAE,gBAAgB,CAAC;IAC7B,cAAc,CAAC,EAAE,iBAAiB,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACtC,UAAU,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,EACD,gBAAgB,GAChB,qBAAqB,GACrB,kBAAkB,GAClB,kBAAkB,GAClB,sBAAsB,GACtB,aAAa,GACb,gBAAgB,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,4BAA4B,CAAC,QAAQ,CAAC,CAAC;IAC/C,UAAU,EAAE,oBAAoB,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC/B;;;OAGG;IACH,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B;;;;OAIG;IACH,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B;;OAEG;IACH,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACxC;;;;OAIG;IACH,SAAS,EAAE,sBAAsB,EAAE,CAAC;IACpC,wEAAwE;IACxE,OAAO,EAAE;QACR,UAAU,CAAC,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,OAAO,CAAA;SAAE,CAAC;QAC5D,OAAO,CAAC,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,OAAO,CAAA;SAAE,CAAC;QACzD,IAAI,CAAC,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,OAAO,CAAA;SAAE,CAAC;KACtD,CAAC;CACF;AAcD,qBAAa,eAAe;IAC3B,QAAQ,CAAC,EAAE,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;gBAEhC,YAAY,EAAE,YAAY;IAItC,KAAK,CAAC,IAAI,EAAE,kBAAkB,GAAG,eAAe;IA0DhD,OAAO,CAAC,cAAc;IAwJtB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,OAAO,CAAC,kBAAkB;IAM1B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,mBAAmB;CAS3B"}

package/dist/policy/sources/QtiPolicySource.js

@@ -0,0 +1,270 @@
+/**
+ * QTI Policy Source — refactor of `PnpToolResolver` for the M8 engine
+ * (see `.cursor/plans/m8-design.md` § 3 step 5 and § 5 §).
+ *
+ * This source applies the QTI 6-level precedence rules used by today's
+ * `PnpToolResolver` but exposes them as a `(candidates, qtiInputs) →
+ * (refinedCandidates, perToolFlags, mandates, decisions)` function the
+ * engine can call once per `decide(...)` request, with all results
+ * routed through the unified `ToolPolicyProvenanceBuilder`.
+ *
+ * **Why this lives next to the legacy resolver instead of replacing
+ * it.** PR 1 introduces the engine without callers; the legacy
+ * `PnpToolResolver` is still in active use by `<pie-item-toolbar>`
+ * and by external tests. PR 5 deletes the legacy class once the
+ * toolbar (PR 3) and the QTI default flip (PR 4) have landed and the
+ * caller list is empty. Until then this source is the *canonical*
+ * implementation and the legacy class is the deprecated mirror.
+ */
+export class QtiPolicySource {
+    id = "qti";
+    toolRegistry;
+    constructor(toolRegistry) {
+        this.toolRegistry = toolRegistry;
+    }
+    apply(args) {
+        const { assessment, currentItemRef } = args;
+        const pnp = assessment.personalNeedsProfile;
+        const settings = assessment.settings;
+        const itemSettings = currentItemRef?.settings;
+        const result = {
+            blockedToolIds: new Set(),
+            mandatedToolIds: new Set(),
+            perToolFlags: new Map(),
+            decisions: [],
+            sources: {},
+        };
+        if (settings?.districtPolicy || settings?.testAdministration) {
+            result.sources.assessment = {
+                id: assessment.id || "unknown",
+                name: assessment.name || assessment.id || "Assessment",
+                config: settings,
+            };
+        }
+        if (pnp) {
+            result.sources.student = {
+                id: "student",
+                name: "Student PNP Profile",
+                config: pnp,
+            };
+        }
+        if (currentItemRef && itemSettings) {
+            result.sources.item = {
+                id: currentItemRef.identifier,
+                name: currentItemRef.identifier,
+                config: itemSettings,
+            };
+        }
+        const allSupports = new Set();
+        pnp?.supports?.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 ctx = {
+            pnp,
+            districtPolicy: settings?.districtPolicy,
+            testAdmin: settings?.testAdministration,
+            itemSettings,
+            toolConfigs: settings?.toolConfigs,
+        };
+        for (const supportId of allSupports) {
+            this.resolveSupport(supportId, ctx, result);
+        }
+        return result;
+    }
+    resolveSupport(supportId, ctx, out) {
+        // 1. District block (absolute veto)
+        if (ctx.districtPolicy?.blockedTools?.includes(supportId)) {
+            const toolId = this.mapSupportToToolId(supportId);
+            out.blockedToolIds.add(toolId);
+            out.decisions.push({
+                precedence: 1,
+                rule: "district-block",
+                featureId: toolId,
+                action: "block",
+                sourceType: "assessment",
+                reason: `District policy blocks "${supportId}" for all assessments`,
+                value: ctx.districtPolicy.blockedTools,
+            });
+            return;
+        }
+        // 2. Test administration override
+        if (ctx.testAdmin?.toolOverrides?.[supportId] === false) {
+            const toolId = this.mapSupportToToolId(supportId);
+            out.blockedToolIds.add(toolId);
+            out.decisions.push({
+                precedence: 2,
+                rule: "test-admin-override",
+                featureId: toolId,
+                action: "block",
+                sourceType: "assessment",
+                reason: `Test administrator disabled "${supportId}" for this session`,
+                value: ctx.testAdmin.toolOverrides,
+            });
+            return;
+        }
+        // 3. Item restriction (per-item block)
+        if (ctx.itemSettings?.restrictedTools?.includes(supportId)) {
+            const toolId = this.mapSupportToToolId(supportId);
+            out.blockedToolIds.add(toolId);
+            out.decisions.push({
+                precedence: 3,
+                rule: "item-restriction",
+                featureId: toolId,
+                action: "block",
+                sourceType: "item",
+                reason: `Item restricts "${supportId}" (e.g., mental math question blocks calculator)`,
+                value: ctx.itemSettings.restrictedTools,
+            });
+            return;
+        }
+        // 4. Item requirement (forces enable)
+        if (ctx.itemSettings?.requiredTools?.includes(supportId)) {
+            const toolId = this.mapSupportToToolId(supportId);
+            out.mandatedToolIds.add(toolId);
+            out.perToolFlags.set(toolId, {
+                required: true,
+                alwaysAvailable: false,
+                settings: this.resolveToolSettings(supportId, ctx),
+                rule: "item-requirement",
+                sourceType: "item",
+            });
+            out.decisions.push({
+                precedence: 4,
+                rule: "item-requirement",
+                featureId: toolId,
+                action: "enable",
+                sourceType: "item",
+                reason: `Item requires "${supportId}" for this question`,
+                value: ctx.itemSettings.requiredTools,
+            });
+            return;
+        }
+        // 5. District requirement
+        if (ctx.districtPolicy?.requiredTools?.includes(supportId)) {
+            const toolId = this.mapSupportToToolId(supportId);
+            out.mandatedToolIds.add(toolId);
+            out.perToolFlags.set(toolId, {
+                required: true,
+                alwaysAvailable: false,
+                settings: this.resolveToolSettings(supportId, ctx),
+                rule: "district-requirement",
+                sourceType: "assessment",
+            });
+            out.decisions.push({
+                precedence: 5,
+                rule: "district-requirement",
+                featureId: toolId,
+                action: "enable",
+                sourceType: "assessment",
+                reason: `District policy requires "${supportId}" for all assessments`,
+                value: ctx.districtPolicy.requiredTools,
+            });
+            return;
+        }
+        // 6. PNP supports (student needs)
+        if (ctx.pnp?.supports?.includes(supportId)) {
+            const toolId = this.mapSupportToToolId(supportId);
+            const isProhibited = ctx.pnp.prohibitedSupports?.includes(supportId);
+            if (isProhibited) {
+                out.blockedToolIds.add(toolId);
+                out.decisions.push({
+                    precedence: 6,
+                    rule: "pnp-prohibited",
+                    featureId: toolId,
+                    action: "block",
+                    sourceType: "student",
+                    reason: `Student PNP profile prohibits "${supportId}"`,
+                    value: ctx.pnp.prohibitedSupports,
+                });
+                return;
+            }
+            out.perToolFlags.set(toolId, {
+                required: false,
+                alwaysAvailable: true,
+                settings: this.resolveToolSettings(supportId, ctx),
+                rule: "pnp-support",
+                sourceType: "student",
+            });
+            out.decisions.push({
+                precedence: 6,
+                rule: "pnp-support",
+                featureId: toolId,
+                action: "enable",
+                sourceType: "student",
+                reason: `Student PNP profile requests "${supportId}"`,
+                value: ctx.pnp.supports,
+            });
+            return;
+        }
+        // 6 (skip): support-id mentioned somewhere but no rule fired.
+        // Use the mapped tool id as `featureId` so the trail is keyed
+        // the same way as every other branch — PR 5's debugger surfaces
+        // index provenance trails by tool id and would otherwise show
+        // orphaned support-id entries here (M8 PR 1 R3 S1).
+        const toolId = this.mapSupportToToolId(supportId);
+        out.decisions.push({
+            precedence: 6,
+            rule: "pnp-support",
+            featureId: toolId,
+            action: "skip",
+            sourceType: "system",
+            reason: `Feature "${supportId}" not configured at any level`,
+            value: { supportId },
+        });
+    }
+    /**
+     * Map a QTI / PNP support id (e.g. `"calculator-basic"`) to the
+     * registered tool id that owns it.
+     *
+     * Resolution rules:
+     *
+     *   1. **Multiple tools register the same support id:** the
+     *      *first-registered* tool wins. `ToolRegistry.getToolsByPNPSupport`
+     *      returns a `Set<string>` whose iteration order matches the
+     *      `register(...)` insertion order, so the result is
+     *      deterministic across runs but order-sensitive at registration
+     *      time. This is an unusual configuration — the typical case is
+     *      one tool per support id — but it is reachable when an
+     *      integrator overrides a default tool with a replacement that
+     *      claims the same `pnpSupportIds`. In that case the integrator
+     *      should `unregister(...)` the default before registering the
+     *      replacement.
+     *
+     *   2. **No tool registers the support id:** the support id is
+     *      returned verbatim as the `featureId` for provenance trails
+     *      and `ToolPolicyEntry.toolId`. This lets hosts use raw QTI
+     *      strings for tools the registry does not (yet) carry without
+     *      losing them in policy evaluation.
+     *
+     * The legacy `PnpToolResolver.resolveTool` had the same behavior;
+     * see `tests/policy/QtiPolicySource.test.ts` for the regression
+     * lock.
+     */
+    mapSupportToToolId(supportId) {
+        const toolIds = this.toolRegistry.getToolsByPNPSupport(supportId);
+        if (toolIds.size === 0)
+            return supportId;
+        return Array.from(toolIds)[0];
+    }
+    /**
+     * Resolve tool-specific settings, item-level taking precedence over
+     * assessment-level.
+     *
+     * Uses `??` (nullish-coalescing) rather than the legacy resolver's
+     * `||`. Tool config values are typed `unknown` and may legitimately
+     * be `false` / `0` / `""` (e.g. a tool whose canonical "off" config
+     * is the literal `false`). `||` would treat those as missing and
+     * silently fall through to the assessment-level config, masking the
+     * authored item-level intent. `??` only falls through on
+     * `null`/`undefined`, which matches the semantic of "value not
+     * provided." This is a deliberate behavior delta from the legacy
+     * `PnpToolResolver` (M8 PR 1).
+     */
+    resolveToolSettings(supportId, ctx) {
+        return (ctx.itemSettings?.toolParameters?.[supportId] ??
+            ctx.toolConfigs?.[supportId]);
+    }
+}
+//# sourceMappingURL=QtiPolicySource.js.map

package/dist/policy/sources/QtiPolicySource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"QtiPolicySource.js","sourceRoot":"","sources":["../../../src/policy/sources/QtiPolicySource.ts"],"names":[],"mappings":"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"}