@pie-players/pie-assessment-toolkit 0.3.75 → 1.0.0-beta.0

package/dist/policy/core/decision-types.d.ts

@@ -50,8 +50,10 @@ export interface ToolPolicyDecisionRequest {
 /**
  * Diagnostic codes the engine may emit alongside a decision.
  * `tool-policy.requiredToolBlocked` fires when a host policy gate
- * (`policy.blocked`, missing-from-`placement`, provider veto) removed a tool
- * that item or district `requiredTools` mandates.
+ * (`policy.blocked`, the allowlist, a provider veto, or placement at no level)
+ * removed a tool that item or district `requiredTools` mandates. A tool placed
+ * at another level is served there, so its absence from this level's placement
+ * is no conflict. `details` is {@link RequiredToolBlockedDetails}.
  *
  * `tool-policy.placementMissing` fires when a custom `PolicySource`
  * references a tool ID that is not present in `tools.placement[level]`
@@ -62,7 +64,9 @@ export interface ToolPolicyDecisionRequest {
  *
  * `tool-policy.unknownSupportId` fires for each id a profile, district
  * policy, test administration or item names that no tool is registered under.
- * `details` is {@link UnknownSupportIdDetails}.
+ * It describes the inputs, so the engine reports it on its resolved inputs'
+ * `diagnostics` rather than on a decision. `details` is
+ * {@link UnknownSupportIdDetails}.
  *
  * `tool-policy.itemSettingNotApplied` fires on a section-, assessment- or
  * passage-level decision for each tool on that toolbar a mounted item's
@@ -75,9 +79,10 @@ export interface ToolPolicyDecisionRequest {
  * `restrictedTools` or the profile's `prohibitedSupports` withdraws instead.
  * `details` is {@link OverrideBlockedDetails}.
  *
- * The toolkit coordinator logs each diagnostic once per code, tool and item.
+ * The toolkit coordinator logs each diagnostic once per code, tool and item,
+ * and hands the same ones to its `onPolicyDiagnostic` listeners.
  */
-export type ToolPolicyDiagnosticCode = "tool-policy.requiredToolBlocked" | "tool-policy.placementMissing" | "tool-policy.unknownSupportId" | "tool-policy.itemSettingNotApplied" | "tool-policy.overrideBlocked";
+export type ToolPolicyDiagnosticCode = keyof ToolPolicyDiagnosticDetails;
 /**
  * Which host gate removed a profile-mandated tool. Surfaced inside
  * `ToolPolicyDiagnostic.details` for `tool-policy.requiredToolBlocked`
@@ -87,44 +92,38 @@ export type ToolPolicyDiagnosticCode = "tool-policy.requiredToolBlocked" | "tool
  * `provenance.features[toolId].allDecisions`.
  *
  * The four values mirror steps 1–4 of `composeDecision`:
- *   - `placement-missing` — tool is not in `tools.placement[level]`
+ *   - `placement-missing` — no level of `tools.placement` lists the tool
  *   - `provider-disabled` — `tools.providers[id].enabled === false`
  *   - `host-allowlist`    — non-empty `tools.policy.allowed` excludes the id
  *   - `host-blocked`      — `tools.policy.blocked` lists the id
  */
 export type ToolPolicyHostGate = "placement-missing" | "provider-disabled" | "host-allowlist" | "host-blocked";
-/**
- * Strongly-typed payload for `tool-policy.requiredToolBlocked`
- * diagnostics. The diagnostic's `details` field still types as
- * `Record<string, unknown>` for forward compatibility, but engines
- * always populate this exact shape today and consumers can safely
- * cast.
- */
-export interface RequiredToolBlockedDetails extends Record<string, unknown> {
-    /** The profile policy rule that mandated the tool (e.g. `district-requirement`). */
-    rule: string;
+/** Payload of a `tool-policy.requiredToolBlocked` diagnostic. */
+export interface RequiredToolBlockedDetails {
+    /** The requirement that mandates the tool. */
+    rule: "item-requirement" | "district-requirement";
     /** Which host gate removed the tool. */
     hostRule: ToolPolicyHostGate;
     /** The host configuration value that triggered the gate (best-effort, may be omitted). */
     hostValue?: unknown;
 }
 /** Payload of a `tool-policy.unknownSupportId` diagnostic. */
-export interface UnknownSupportIdDetails extends Record<string, unknown> {
+export interface UnknownSupportIdDetails {
     /** The rules whose lists name the id, in precedence order. */
     origins: PnpPolicySourceRule[];
 }
 /** Payload of a `tool-policy.placementMissing` diagnostic. */
-export interface PlacementMissingDetails extends Record<string, unknown> {
+export interface PlacementMissingDetails {
     /** The custom `PolicySource` that named the tool. */
     customSourceId: string;
 }
 /** Payload of a `tool-policy.overrideBlocked` diagnostic. */
-export interface OverrideBlockedDetails extends Record<string, unknown> {
+export interface OverrideBlockedDetails {
     /** The rule that withdrew the granted tool. */
     rule: "item-restriction" | "pnp-prohibited";
 }
 /** Payload of a `tool-policy.itemSettingNotApplied` diagnostic. */
-export interface ItemSettingNotAppliedDetails extends Record<string, unknown> {
+export interface ItemSettingNotAppliedDetails {
     /** Canonical id of the item whose setting names the tool. */
     itemId: string;
     /** The item settings that name it. */
@@ -132,14 +131,28 @@ export interface ItemSettingNotAppliedDetails extends Record<string, unknown> {
     /** The level of the toolbar the tool is on. */
     toolbarLevel: ToolLevel;
 }
-export interface ToolPolicyDiagnostic {
-    code: ToolPolicyDiagnosticCode;
-    /** The toolbar level decided; absent on a feature decision. */
-    level?: ToolPlacementLevel;
-    toolId: string;
-    message: string;
-    details?: Record<string, unknown>;
+/** The payload each diagnostic code carries. */
+export interface ToolPolicyDiagnosticDetails {
+    "tool-policy.requiredToolBlocked": RequiredToolBlockedDetails;
+    "tool-policy.placementMissing": PlacementMissingDetails;
+    "tool-policy.unknownSupportId": UnknownSupportIdDetails;
+    "tool-policy.itemSettingNotApplied": ItemSettingNotAppliedDetails;
+    "tool-policy.overrideBlocked": OverrideBlockedDetails;
 }
+/** A policy diagnostic, its `details` typed by its `code`. */
+export type ToolPolicyDiagnostic = {
+    [C in ToolPolicyDiagnosticCode]: {
+        code: C;
+        /**
+         * The toolbar level decided; absent on a feature decision and on an input
+         * diagnostic.
+         */
+        level?: ToolPlacementLevel;
+        toolId: string;
+        message: string;
+        details: ToolPolicyDiagnosticDetails[C];
+    };
+}[ToolPolicyDiagnosticCode];
 export interface ToolPolicyEntry {
     toolId: string;
     /**
@@ -158,12 +171,11 @@ export interface ToolPolicyEntry {
      */
     alwaysAvailable: boolean;
     /**
-     * Tool-specific settings resolved from the assessment / item
-     * settings via the PNP policy source. Hosts that want to read these
-     * directly should use `entry.settings` rather than peeking into
-     * the assessment entity from above the engine.
+     * The tool's parameters: the item's `toolParameters` entry on the item's own
+     * toolbar, else the assessment's `toolParameters` entry. Set whether or not a
+     * grant admitted the tool.
      */
-    settings?: unknown;
+    parameters?: Record<string, unknown>;
 }
 export interface ToolPolicyDecision {
     visibleTools: ToolPolicyEntry[];

package/dist/policy/core/feature-decision.d.ts

@@ -27,10 +27,10 @@ import type { PnpPolicySourceRule, ToolPolicyResolutionDecision, ToolPolicySourc
  * A feature verdict comes from one of the eight PNP precedence levels, or from a
  * host gate that never reaches them: `tools.policy.blocked` and a non-empty
  * `tools.policy.allowed` are absolute for the id they name, exactly as they are
- * on the placement-scoped path.
+ * on the placement-scoped path. `"none"` is a feature no rule names.
  */
-export type FeaturePolicyRule = PnpPolicySourceRule | "host-allowlist" | "host-blocked";
-export interface FeaturePolicyDecision {
+export type FeaturePolicyRule = PnpPolicySourceRule | "host-allowlist" | "host-blocked" | "none";
+export interface FeaturePolicyDecision<P = Record<string, unknown>> {
     /** The PNP/AfA support id that was evaluated (e.g. `"signLanguage"`). */
     featureId: string;
     /**
@@ -42,7 +42,8 @@ export interface FeaturePolicyDecision {
     action: ToolPolicyResolutionDecision["action"];
     /** Which precedence rule produced the verdict. */
     rule: FeaturePolicyRule;
-    precedence: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+    /** The rule's precedence level; `null` for `rule: "none"`. */
+    precedence: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | null;
     sourceType: ToolPolicySourceType;
     /** Human-readable explanation, suitable for a policy debugger. */
     reason: string;
@@ -66,20 +67,21 @@ export interface FeaturePolicyDecision {
      */
     assessmentBound: boolean;
     /**
-     * `true` when the grant is a mandate (item or district `requiredTools`)
-     * rather than a student-profile support or a test-administration override.
+     * `true` when item or district `requiredTools` mandates the feature, including
+     * under a `true` test-administration override.
      */
     required: boolean;
     /**
-     * Feature parameters resolved from item `toolParameters` then assessment
-     * `toolConfigs`, keyed by the feature id. The seam a later configurable
-     * presentation would hang on; no vocabulary is defined yet.
+     * The feature's parameters: the item's `toolParameters` entry for an item's
+     * scope, else the assessment's `toolParameters` entry, keyed by the feature id.
+     * Set on a denial too; a host denial leaves it out.
      */
-    parameters?: unknown;
+    parameters?: P;
     /**
-     * Conflicts found while deciding: a `tool-policy.unknownSupportId` for each
-     * id the bound inputs name that no tool is registered under. Empty on a host
-     * denial, which consults no policy source.
+     * Conflicts found while deciding: a `tool-policy.overrideBlocked` for a
+     * granting override the decision withdrew. Empty on a host denial, which
+     * consults no policy source. An id no tool is registered under describes the
+     * inputs, so it is reported on the engine inputs' `diagnostics`.
      */
     diagnostics: ToolPolicyDiagnostic[];
 }
@@ -97,7 +99,7 @@ export interface FeatureDecisionContext {
  * blocklist is a verdict whether or not an assessment was bound, and the flag
  * only ever qualifies a *policy* denial.
  */
-export declare function hostFeatureDenial(featureId: string, rule: "host-allowlist" | "host-blocked", hostValue: readonly string[], context: FeatureDecisionContext): FeaturePolicyDecision;
+export declare function hostFeatureDenial(featureId: string, rule: "host-allowlist" | "host-blocked", hostValue: readonly string[], context: FeatureDecisionContext): FeaturePolicyDecision<never>;
 /**
  * Whether a host gate produced the verdict, rather than a policy source.
  *
@@ -114,4 +116,4 @@ export declare function isHostDeniedFeature(decision: Pick<FeaturePolicyDecision
  * exactly one decision and at most one flags entry — no mapped-tool-id
  * bookkeeping is needed to read it back out.
  */
-export declare function interpretFeatureResult(featureId: string, result: PnpPolicyResult, context: FeatureDecisionContext): FeaturePolicyDecision;
+export declare function interpretFeatureResult<P>(featureId: string, result: PnpPolicyResult, context: FeatureDecisionContext, parameters: P | undefined): FeaturePolicyDecision<P>;

package/dist/policy/core/feature-decision.js

@@ -20,14 +20,12 @@
  * "nothing was bound to ask against" are the same verdict for different
  * reasons, and only the second is a defect.
  */
-import { overrideBlockedDiagnostic, unknownSupportIdDiagnostic, } from "./compose-decision.js";
+import { overrideBlockedDiagnostic } from "./compose-decision.js";
 /**
  * Reason text for a denial that had no assessment to decide against.
  *
- * Used in place of the `pnp-support` skip's "not configured at any level",
- * which is true but reads as a completed evaluation. `rule` and `precedence`
- * stay as the source reported them: nothing fired, so naming a ninth rule
- * would describe a precedence level that does not exist.
+ * Used in place of "not configured", which is true but reads as a completed
+ * evaluation.
  */
 const unboundAssessmentReason = (featureId) => `No assessment is bound, so no policy source could grant "${featureId}"`;
 /**
@@ -73,17 +71,20 @@ export function isHostDeniedFeature(decision) {
  * exactly one decision and at most one flags entry — no mapped-tool-id
  * bookkeeping is needed to read it back out.
  */
-export function interpretFeatureResult(featureId, result, context) {
+export function interpretFeatureResult(featureId, result, context, parameters) {
     const decision = result.decisions[0];
     const flags = Array.from(result.perToolFlags.values())[0];
     const granted = decision?.action === "enable";
     const reason = decision?.reason ?? `Feature "${featureId}" not configured`;
+    // The source logs "no rule fired" as a skip at the last level so the trail
+    // stays ordered; the verdict names no rule for it.
+    const fired = decision !== undefined && decision.action !== "skip";
     return {
         featureId,
         granted,
         action: decision?.action ?? "skip",
-        rule: decision?.rule ?? "pnp-support",
-        precedence: decision?.precedence ?? 8,
+        rule: fired ? decision.rule : "none",
+        precedence: fired ? decision.precedence : null,
         sourceType: decision?.sourceType ?? "system",
         // Only a denial is re-worded. An unbound host can still be granted the
         // feature — an item's registered settings carrying `requiredTools` mandate
@@ -93,11 +94,8 @@ export function interpretFeatureResult(featureId, result, context) {
             ? reason
             : unboundAssessmentReason(featureId),
         required: Boolean(flags?.required),
-        parameters: flags?.settings,
+        parameters,
         assessmentBound: context.assessmentBound,
-        diagnostics: [
-            ...Array.from(result.unmappedSupportIds, ([supportId, origins]) => unknownSupportIdDiagnostic(supportId, origins)),
-            ...Array.from(result.blockedOverrides, ([toolId, rule]) => overrideBlockedDiagnostic(toolId, rule)),
-        ],
+        diagnostics: Array.from(result.blockedOverrides, ([toolId, rule]) => overrideBlockedDiagnostic(toolId, rule)),
     };
 }

package/dist/policy/core/pnp-policy-inputs.d.ts

@@ -15,7 +15,10 @@
  *   - `settings.districtPolicy` (any `blockedTools` or `requiredTools`),
  *   - `settings.testAdministration` (any `toolOverrides` entry),
  *   - or, for an item-scoped decision, the item's settings carry
- *     `requiredTools` / `restrictedTools` / `toolParameters`.
+ *     `requiredTools` / `restrictedTools`.
+ *
+ * Tool parameters are no policy material: the engine resolves them whatever the
+ * enforcement state.
  *
  * Hosts opt out of the auto-on behavior by passing
  * `pnpEnforcement: "off"` explicitly (engine input or
@@ -32,7 +35,7 @@ import type { AssessmentEntity, ItemSettings } from "@pie-players/pie-players-sh
 export declare function assessmentHasPnpPolicyInputs(assessment: AssessmentEntity | null | undefined): boolean;
 /**
  * Return `true` when an item's settings carry item-level profile policy
- * material (`requiredTools`, `restrictedTools`, or `toolParameters`).
+ * material (`requiredTools` or `restrictedTools`).
  *
  * Used in addition to {@link assessmentHasPnpPolicyInputs} for a decision scoped
  * to the item, so an item with profile-relevant settings engages PNP/profile

package/dist/policy/core/pnp-policy-inputs.js

@@ -15,12 +15,16 @@
  *   - `settings.districtPolicy` (any `blockedTools` or `requiredTools`),
  *   - `settings.testAdministration` (any `toolOverrides` entry),
  *   - or, for an item-scoped decision, the item's settings carry
- *     `requiredTools` / `restrictedTools` / `toolParameters`.
+ *     `requiredTools` / `restrictedTools`.
+ *
+ * Tool parameters are no policy material: the engine resolves them whatever the
+ * enforcement state.
  *
  * Hosts opt out of the auto-on behavior by passing
  * `pnpEnforcement: "off"` explicitly (engine input or
  * `ToolkitCoordinator.setPnpEnforcement("off")`).
  */
+const hasEntries = (value) => Array.isArray(value) && value.length > 0;
 /**
  * Return `true` when the assessment carries any PNP/profile policy
  * material that the engine's `PnpPolicySource` would consume.
@@ -32,26 +36,15 @@ export function assessmentHasPnpPolicyInputs(assessment) {
     if (!assessment)
         return false;
     const pnp = assessment.personalNeedsProfile;
-    if (pnp) {
-        if (Array.isArray(pnp.supports) && pnp.supports.length > 0)
-            return true;
-        if (Array.isArray(pnp.prohibitedSupports) &&
-            pnp.prohibitedSupports.length > 0) {
-            return true;
-        }
+    if (pnp && (hasEntries(pnp.supports) || hasEntries(pnp.prohibitedSupports))) {
+        return true;
     }
     const settings = assessment.settings;
     if (settings) {
         const district = settings.districtPolicy;
-        if (district) {
-            if (Array.isArray(district.blockedTools) &&
-                district.blockedTools.length > 0) {
-                return true;
-            }
-            if (Array.isArray(district.requiredTools) &&
-                district.requiredTools.length > 0) {
-                return true;
-            }
+        if (district &&
+            (hasEntries(district.blockedTools) || hasEntries(district.requiredTools))) {
+            return true;
         }
         const overrides = settings.testAdministration?.toolOverrides;
         if (overrides &&
@@ -64,7 +57,7 @@ export function assessmentHasPnpPolicyInputs(assessment) {
 }
 /**
  * Return `true` when an item's settings carry item-level profile policy
- * material (`requiredTools`, `restrictedTools`, or `toolParameters`).
+ * material (`requiredTools` or `restrictedTools`).
  *
  * Used in addition to {@link assessmentHasPnpPolicyInputs} for a decision scoped
  * to the item, so an item with profile-relevant settings engages PNP/profile
@@ -74,20 +67,7 @@ export function assessmentHasPnpPolicyInputs(assessment) {
 export function itemSettingsHavePnpPolicyInputs(settings) {
     if (!settings)
         return false;
-    if (Array.isArray(settings.requiredTools) &&
-        settings.requiredTools.length > 0) {
-        return true;
-    }
-    if (Array.isArray(settings.restrictedTools) &&
-        settings.restrictedTools.length > 0) {
-        return true;
-    }
-    if (settings.toolParameters &&
-        typeof settings.toolParameters === "object" &&
-        Object.keys(settings.toolParameters).length > 0) {
-        return true;
-    }
-    return false;
+    return hasEntries(settings.requiredTools) || hasEntries(settings.restrictedTools);
 }
 /**
  * Resolve the auto-mode `pnpEnforcement` for one decision.

package/dist/policy/core/provenance.d.ts

@@ -20,7 +20,7 @@ export interface ToolPolicyResolutionDecision {
     /** Monotonic step index across the entire decision log. */
     step: number;
     /**
-     * Precedence level. PNP/profile rules use `1`–`6`; non-profile rules use `0`
+     * Precedence level. PNP/profile rules use `1`–`8`; non-profile rules use `0`
      * for host-side gates, and a custom source, which runs after PNP/profile
      * policy, uses its own or `100 + i` for the `i`th registered source.
      */

package/dist/policy/core/tool-parameters.d.ts

@@ -0,0 +1,11 @@
+import type { AssessmentEntity, ToolParametersFor } from "@pie-players/pie-players-shared/types";
+import type { PnpPolicyItem } from "../sources/PnpPolicySource.js";
+/**
+ * A tool's parameters for one decision: the item's `toolParameters` entry, else
+ * the assessment's `toolParameters` entry.
+ *
+ * Parameters say how a tool behaves wherever policy shows it, so they reach a
+ * tool placed without a grant, and PNP enforcement does not gate them. `item` is
+ * set only for a decision about the item's own toolbar or content.
+ */
+export declare function resolveToolParameters<K extends string>(toolId: K, assessment: AssessmentEntity | null | undefined, item: PnpPolicyItem | undefined): ToolParametersFor<K> | undefined;

package/dist/policy/core/tool-parameters.js

@@ -0,0 +1,15 @@
+/**
+ * A tool's parameters for one decision: the item's `toolParameters` entry, else
+ * the assessment's `toolParameters` entry.
+ *
+ * Parameters say how a tool behaves wherever policy shows it, so they reach a
+ * tool placed without a grant, and PNP enforcement does not gate them. `item` is
+ * set only for a decision about the item's own toolbar or content.
+ */
+export function resolveToolParameters(toolId, assessment, item) {
+    const settings = assessment?.settings;
+    const value = item?.settings.toolParameters?.[toolId] ?? settings?.toolParameters?.[toolId];
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}

package/dist/policy/engine.d.ts

@@ -7,6 +7,6 @@
  */
 export { ToolPolicyEngine, type PnpEnforcementMode, type ResolvedEngineInputs, type ToolPolicyChangeEvent, type ToolPolicyChangeListener, type ToolPolicyEngineArgs, type ToolPolicyEngineInputs, } from "./core/ToolPolicyEngine.js";
 export { isHostDeniedFeature, type FeaturePolicyDecision, type FeaturePolicyRule, } from "./core/feature-decision.js";
-export type { ItemSettingNotAppliedDetails, OverrideBlockedDetails, PlacementMissingDetails, RequiredToolBlockedDetails, ToolPolicyDecision, ToolPolicyDecisionRequest, ToolPolicyDiagnostic, ToolPolicyDiagnosticCode, ToolPolicyEntry, ToolPolicyHostGate, ToolScope, UnknownSupportIdDetails, } from "./core/decision-types.js";
+export type { ItemSettingNotAppliedDetails, OverrideBlockedDetails, PlacementMissingDetails, RequiredToolBlockedDetails, ToolPolicyDecision, ToolPolicyDecisionRequest, ToolPolicyDiagnostic, ToolPolicyDiagnosticCode, ToolPolicyDiagnosticDetails, ToolPolicyEntry, ToolPolicyHostGate, ToolScope, UnknownSupportIdDetails, } from "./core/decision-types.js";
 export type { PolicySource, PolicySourceDecisionContext, PolicySourceProvenanceEntry, PolicySourceResult, } from "./core/PolicySource.js";
 export type { PnpPolicySourceRule, ToolPolicyDecisionRule, ToolPolicyFeatureTrail, ToolPolicyProvenance, ToolPolicyResolutionDecision, ToolPolicySourceType, } from "./core/provenance.js";

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

@@ -20,8 +20,6 @@ export interface PnpPolicyToolFlags {
      * override grants it (host UI cannot toggle off).
      */
     alwaysAvailable: boolean;
-    /** Tool-specific settings derived from item / assessment settings. */
-    settings?: unknown;
     /** Which PNP/profile rule contributed the surviving verdict. */
     rule: PnpPolicySourceRule;
 }
@@ -60,11 +58,12 @@ export interface PnpPolicyResult {
      */
     blockedToolIds: Set<string>;
     /**
-     * Tool IDs PNP/profile policy mandates (item or district `requiredTools`). Used
-     * by the engine to detect `tool-policy.requiredToolBlocked`
+     * Tools PNP/profile policy mandates (item or district `requiredTools`), each
+     * with the requirement that names it, including a tool a `true` override
+     * decides. Used by the engine to detect `tool-policy.requiredToolBlocked`
      * diagnostics for tools removed by host policy.
      */
-    mandatedToolIds: Set<string>;
+    mandates: Map<string, "item-requirement" | "district-requirement">;
     /**
      * Per-tool flags merged into surviving `ToolPolicyEntry`s.
      */
@@ -75,15 +74,6 @@ export interface PnpPolicyResult {
      * support id).
      */
     decisions: PnpPolicyDecisionEvent[];
-    /**
-     * Ids named by a profile, district policy, test administration or item that
-     * no tool is registered under, each with the rules whose lists name it, in
-     * precedence order. Nothing resolves them; the engine turns each into a
-     * `tool-policy.unknownSupportId` diagnostic. Empty when the registry is: an
-     * empty registry has nothing to check an id against, and
-     * `tool-config-validation` already reports it once.
-     */
-    unmappedSupportIds: Map<string, PnpPolicySourceRule[]>;
     /**
      * Ids a `true` test-administration override names that an item restriction
      * or a PNP prohibition withdrew instead, each with the rule that did. The
@@ -125,8 +115,8 @@ export declare class PnpPolicySource {
      * feature: the returned result carries exactly one decision, and
      * `decisions[0].action` is the verdict.
      *
-     * Reusing `resolveSupport(...)` rather than re-walking the precedence rules
-     * is the point — a second copy of the eight levels would drift.
+     * It reuses `resolveSupport(...)` because a second copy of the eight levels
+     * would drift.
      */
     resolveFeature(featureId: string, args: PnpPolicyApplyArgs): PnpPolicyResult;
     /**
@@ -136,11 +126,13 @@ export declare class PnpPolicySource {
     private prepare;
     private resolveSupport;
     /**
-     * The named ids no tool is registered under, with the rules naming each in
-     * precedence order. A support id is the id of the tool it grants, so an id
-     * missing from the registry matches nothing placed.
+     * Ids the assessment or any of `items` names that no tool is registered
+     * under, each with the rules whose lists name it, in precedence order. A
+     * support id is the id of the tool it grants, so an id missing from the
+     * registry matches nothing placed; the engine turns each into a
+     * `tool-policy.unknownSupportId` diagnostic. Empty when the registry is: an
+     * empty registry has nothing to check an id against, and
+     * `tool-config-validation` already reports it once.
      */
-    private unmappedIds;
-    /** Tool parameters: the item's entry, else the assessment's. */
-    private resolveToolSettings;
+    unknownSupportIds(assessment: AssessmentEntity | null | undefined, items: readonly ItemSettings[]): Map<string, PnpPolicySourceRule[]>;
 }

package/dist/policy/sources/PnpPolicySource.js

@@ -42,8 +42,8 @@ export class PnpPolicySource {
      * feature: the returned result carries exactly one decision, and
      * `decisions[0].action` is the verdict.
      *
-     * Reusing `resolveSupport(...)` rather than re-walking the precedence rules
-     * is the point — a second copy of the eight levels would drift.
+     * It reuses `resolveSupport(...)` because a second copy of the eight levels
+     * would drift.
      */
     resolveFeature(featureId, args) {
         const { ctx, result } = this.prepare(args);
@@ -61,10 +61,9 @@ export class PnpPolicySource {
         const itemSettings = item?.settings;
         const result = {
             blockedToolIds: new Set(),
-            mandatedToolIds: new Set(),
+            mandates: new Map(),
             perToolFlags: new Map(),
             decisions: [],
-            unmappedSupportIds: this.unmappedIds(pnp, settings, itemSettings),
             blockedOverrides: new Map(),
             sources: {},
         };
@@ -94,7 +93,6 @@ export class PnpPolicySource {
             districtPolicy: settings?.districtPolicy,
             testAdmin: settings?.testAdministration,
             itemSettings,
-            toolConfigs: settings?.toolConfigs,
         };
         return { ctx, result };
     }
@@ -164,13 +162,19 @@ export class PnpPolicySource {
             });
             return;
         }
+        const mandate = ctx.itemSettings?.requiredTools?.includes(supportId)
+            ? "item-requirement"
+            : ctx.districtPolicy?.requiredTools?.includes(supportId)
+                ? "district-requirement"
+                : undefined;
         // 5. Test administration override `true`: grants the support for the
-        // session.
+        // session. A requirement naming it keeps its mandate.
         if (override === true) {
+            if (mandate)
+                out.mandates.set(supportId, mandate);
             out.perToolFlags.set(supportId, {
-                required: false,
+                required: mandate !== undefined,
                 alwaysAvailable: true,
-                settings: this.resolveToolSettings(supportId, ctx),
                 rule: "test-admin-override",
             });
             out.decisions.push({
@@ -185,12 +189,11 @@ export class PnpPolicySource {
             return;
         }
         // 6. Item requirement (forces enable)
-        if (ctx.itemSettings?.requiredTools?.includes(supportId)) {
-            out.mandatedToolIds.add(supportId);
+        if (mandate === "item-requirement") {
+            out.mandates.set(supportId, mandate);
             out.perToolFlags.set(supportId, {
                 required: true,
                 alwaysAvailable: false,
-                settings: this.resolveToolSettings(supportId, ctx),
                 rule: "item-requirement",
             });
             out.decisions.push({
@@ -200,17 +203,16 @@ export class PnpPolicySource {
                 action: "enable",
                 sourceType: "item",
                 reason: `Item requires "${supportId}" for this question`,
-                value: ctx.itemSettings.requiredTools,
+                value: ctx.itemSettings?.requiredTools,
             });
             return;
         }
         // 7. District requirement
-        if (ctx.districtPolicy?.requiredTools?.includes(supportId)) {
-            out.mandatedToolIds.add(supportId);
+        if (mandate === "district-requirement") {
+            out.mandates.set(supportId, mandate);
             out.perToolFlags.set(supportId, {
                 required: true,
                 alwaysAvailable: false,
-                settings: this.resolveToolSettings(supportId, ctx),
                 rule: "district-requirement",
             });
             out.decisions.push({
@@ -220,7 +222,7 @@ export class PnpPolicySource {
                 action: "enable",
                 sourceType: "assessment",
                 reason: `District policy requires "${supportId}" for all assessments`,
-                value: ctx.districtPolicy.requiredTools,
+                value: ctx.districtPolicy?.requiredTools,
             });
             return;
         }
@@ -229,7 +231,6 @@ export class PnpPolicySource {
             out.perToolFlags.set(supportId, {
                 required: false,
                 alwaysAvailable: true,
-                settings: this.resolveToolSettings(supportId, ctx),
                 rule: "pnp-support",
             });
             out.decisions.push({
@@ -256,23 +257,29 @@ export class PnpPolicySource {
         });
     }
     /**
-     * The named ids no tool is registered under, with the rules naming each in
-     * precedence order. A support id is the id of the tool it grants, so an id
-     * missing from the registry matches nothing placed.
+     * Ids the assessment or any of `items` names that no tool is registered
+     * under, each with the rules whose lists name it, in precedence order. A
+     * support id is the id of the tool it grants, so an id missing from the
+     * registry matches nothing placed; the engine turns each into a
+     * `tool-policy.unknownSupportId` diagnostic. Empty when the registry is: an
+     * empty registry has nothing to check an id against, and
+     * `tool-config-validation` already reports it once.
      */
-    unmappedIds(pnp, settings, itemSettings) {
+    unknownSupportIds(assessment, items) {
         const unmapped = new Map();
         if (this.toolRegistry.getAllTools().length === 0)
             return unmapped;
+        const pnp = assessment?.personalNeedsProfile;
+        const settings = assessment?.settings;
         const named = [
             ["district-block", settings?.districtPolicy?.blockedTools],
             [
                 "test-admin-override",
                 Object.keys(settings?.testAdministration?.toolOverrides ?? {}),
             ],
-            ["item-restriction", itemSettings?.restrictedTools],
+            ["item-restriction", items.flatMap((item) => item.restrictedTools ?? [])],
             ["pnp-prohibited", pnp?.prohibitedSupports],
-            ["item-requirement", itemSettings?.requiredTools],
+            ["item-requirement", items.flatMap((item) => item.requiredTools ?? [])],
             ["district-requirement", settings?.districtPolicy?.requiredTools],
             ["pnp-support", pnp?.supports],
         ];
@@ -288,9 +295,4 @@ export class PnpPolicySource {
         }
         return unmapped;
     }
-    /** Tool parameters: the item's entry, else the assessment's. */
-    resolveToolSettings(supportId, ctx) {
-        return (ctx.itemSettings?.toolParameters?.[supportId] ??
-            ctx.toolConfigs?.[supportId]);
-    }
 }