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

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

@@ -2,64 +2,58 @@
  * PNP/profile policy input detection. See
  * `docs/tools-and-accomodations/architecture.md`.
  *
- * Pure helpers that decide whether the inputs the engine has been given
- * actually carry PNP/profile policy material. Used by:
- *
- *   - {@link ToolPolicyEngine}'s constructor as the auto-default for
- *     `pnpEnforcement` when the host did not pass an explicit `"on"` /
- *     `"off"`.
- *   - {@link ToolkitCoordinator.resolveEffectivePnpEnforcement} as the
- *     auto-mode rule. PR 2 used a coarse "any non-null assessment → on"
- *     placeholder; PR 4 narrows it to "assessment OR currentItemRef
- *     carries profile policy material."
+ * Pure helpers that decide whether policy inputs carry PNP/profile policy
+ * material, which is what auto-mode `pnpEnforcement` turns on for. The engine
+ * resolves auto-mode per decision: the bound assessment for every decision, and
+ * for a decision scoped to an item, that item's settings as well.
  *
  * The rule is intentionally narrow. Hosts that bind a bare assessment
  * record (only `id` / `name`, no PNP and no settings) do not engage
  * PNP/profile gates. The flip happens the moment the assessment carries any of:
  *
- *   - `personalNeedsProfile` (any `supports`, `prohibitedSupports`, or
- *     `activateAtInit`),
- *   - `settings.districtPolicy` (any `blockedTools`, `requiredTools`,
- *     or `policies`),
- *   - `settings.testAdministration` (any populated key — `mode`,
- *     `toolOverrides`, etc.),
- *   - or the bound `currentItemRef.settings` carries
- *     `requiredTools` / `restrictedTools` / `toolParameters`.
+ *   - `personalNeedsProfile` (any `supports` or `prohibitedSupports`),
+ *   - `settings.districtPolicy` (any `blockedTools` or `requiredTools`),
+ *   - `settings.testAdministration` (any `toolOverrides` entry),
+ *   - or, for an item-scoped decision, the item's settings carry
+ *     `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")`).
  */
-import type { AssessmentEntity, AssessmentItemRef } from "@pie-players/pie-players-shared/types";
+import type { AssessmentEntity, ItemSettings } from "@pie-players/pie-players-shared/types";
 /**
  * Return `true` when the assessment carries any PNP/profile policy
  * material that the engine's `PnpPolicySource` would consume.
  *
- * The check is structural — the presence of a non-empty PNP, district
- * policy, or test administration block is enough; the content does not
- * have to validate against any specific rule.
+ * The check is structural — a non-empty field the source reads is enough;
+ * the content does not have to validate against any specific rule.
  */
 export declare function assessmentHasPnpPolicyInputs(assessment: AssessmentEntity | null | undefined): boolean;
 /**
- * Return `true` when the bound item reference carries item-level profile policy
- * material (`requiredTools`, `restrictedTools`, or `toolParameters`).
+ * Return `true` when an item's settings carry item-level profile policy
+ * material (`requiredTools` or `restrictedTools`).
  *
- * Used in addition to {@link assessmentHasPnpPolicyInputs} so a host that
- * navigates to an item with profile-relevant settings — without a parent
- * assessment carrying its own PNP/district/test-admin block — still
- * gets PNP/profile gates engaged for that item.
+ * Used in addition to {@link assessmentHasPnpPolicyInputs} for a decision scoped
+ * to the item, so an item with profile-relevant settings engages PNP/profile
+ * gates on its own toolbar without a parent assessment carrying a
+ * PNP/district/test-admin block.
  */
-export declare function itemRefHasPnpPolicyInputs(itemRef: AssessmentItemRef | null | undefined): boolean;
+export declare function itemSettingsHavePnpPolicyInputs(settings: ItemSettings | null | undefined): boolean;
 /**
- * Resolve the default `pnpEnforcement` mode given the bound inputs.
+ * Resolve the auto-mode `pnpEnforcement` for one decision.
  *
- * Returns `"on"` when {@link assessmentHasPnpPolicyInputs} or
- * {@link itemRefHasPnpPolicyInputs} reports any profile policy material; otherwise
- * `"off"`. Hosts override the default by passing an explicit
- * `pnpEnforcement` value (engine input) or by calling
+ * Returns `"on"` when {@link assessmentHasPnpPolicyInputs} reports profile
+ * policy material, or when `itemSettings` (the settings of the item a decision
+ * is scoped to) do per {@link itemSettingsHavePnpPolicyInputs}; otherwise
+ * `"off"`. Hosts override the default by passing an explicit `pnpEnforcement`
+ * value (engine input) or by calling
  * `ToolkitCoordinator.setPnpEnforcement("on" | "off")`.
  */
 export declare function resolveDefaultPnpEnforcement(args: {
     assessment?: AssessmentEntity | null;
-    currentItemRef?: AssessmentItemRef | null;
+    itemSettings?: ItemSettings | null;
 }): "on" | "off";

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

@@ -2,135 +2,87 @@
  * PNP/profile policy input detection. See
  * `docs/tools-and-accomodations/architecture.md`.
  *
- * Pure helpers that decide whether the inputs the engine has been given
- * actually carry PNP/profile policy material. Used by:
- *
- *   - {@link ToolPolicyEngine}'s constructor as the auto-default for
- *     `pnpEnforcement` when the host did not pass an explicit `"on"` /
- *     `"off"`.
- *   - {@link ToolkitCoordinator.resolveEffectivePnpEnforcement} as the
- *     auto-mode rule. PR 2 used a coarse "any non-null assessment → on"
- *     placeholder; PR 4 narrows it to "assessment OR currentItemRef
- *     carries profile policy material."
+ * Pure helpers that decide whether policy inputs carry PNP/profile policy
+ * material, which is what auto-mode `pnpEnforcement` turns on for. The engine
+ * resolves auto-mode per decision: the bound assessment for every decision, and
+ * for a decision scoped to an item, that item's settings as well.
  *
  * The rule is intentionally narrow. Hosts that bind a bare assessment
  * record (only `id` / `name`, no PNP and no settings) do not engage
  * PNP/profile gates. The flip happens the moment the assessment carries any of:
  *
- *   - `personalNeedsProfile` (any `supports`, `prohibitedSupports`, or
- *     `activateAtInit`),
- *   - `settings.districtPolicy` (any `blockedTools`, `requiredTools`,
- *     or `policies`),
- *   - `settings.testAdministration` (any populated key — `mode`,
- *     `toolOverrides`, etc.),
- *   - or the bound `currentItemRef.settings` carries
- *     `requiredTools` / `restrictedTools` / `toolParameters`.
+ *   - `personalNeedsProfile` (any `supports` or `prohibitedSupports`),
+ *   - `settings.districtPolicy` (any `blockedTools` or `requiredTools`),
+ *   - `settings.testAdministration` (any `toolOverrides` entry),
+ *   - or, for an item-scoped decision, the item's settings carry
+ *     `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.
  *
- * The check is structural — the presence of a non-empty PNP, district
- * policy, or test administration block is enough; the content does not
- * have to validate against any specific rule.
+ * The check is structural — a non-empty field the source reads is enough;
+ * the content does not have to validate against any specific rule.
  */
 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 (Array.isArray(pnp.activateAtInit) && pnp.activateAtInit.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.policies &&
-                typeof district.policies === "object" &&
-                Object.keys(district.policies).length > 0) {
-                return true;
-            }
+        if (district &&
+            (hasEntries(district.blockedTools) || hasEntries(district.requiredTools))) {
+            return true;
         }
-        const admin = settings.testAdministration;
-        if (admin && typeof admin === "object") {
-            for (const key of Object.keys(admin)) {
-                const value = admin[key];
-                if (value === undefined || value === null)
-                    continue;
-                if (Array.isArray(value) && value.length === 0)
-                    continue;
-                if (typeof value === "object" &&
-                    !Array.isArray(value) &&
-                    Object.keys(value).length === 0) {
-                    continue;
-                }
-                return true;
-            }
+        const overrides = settings.testAdministration?.toolOverrides;
+        if (overrides &&
+            typeof overrides === "object" &&
+            Object.keys(overrides).length > 0) {
+            return true;
         }
     }
     return false;
 }
 /**
- * Return `true` when the bound item reference carries item-level profile policy
- * material (`requiredTools`, `restrictedTools`, or `toolParameters`).
+ * Return `true` when an item's settings carry item-level profile policy
+ * material (`requiredTools` or `restrictedTools`).
  *
- * Used in addition to {@link assessmentHasPnpPolicyInputs} so a host that
- * navigates to an item with profile-relevant settings — without a parent
- * assessment carrying its own PNP/district/test-admin block — still
- * gets PNP/profile gates engaged for that item.
+ * Used in addition to {@link assessmentHasPnpPolicyInputs} for a decision scoped
+ * to the item, so an item with profile-relevant settings engages PNP/profile
+ * gates on its own toolbar without a parent assessment carrying a
+ * PNP/district/test-admin block.
  */
-export function itemRefHasPnpPolicyInputs(itemRef) {
-    const settings = itemRef?.settings;
+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 default `pnpEnforcement` mode given the bound inputs.
+ * Resolve the auto-mode `pnpEnforcement` for one decision.
  *
- * Returns `"on"` when {@link assessmentHasPnpPolicyInputs} or
- * {@link itemRefHasPnpPolicyInputs} reports any profile policy material; otherwise
- * `"off"`. Hosts override the default by passing an explicit
- * `pnpEnforcement` value (engine input) or by calling
+ * Returns `"on"` when {@link assessmentHasPnpPolicyInputs} reports profile
+ * policy material, or when `itemSettings` (the settings of the item a decision
+ * is scoped to) do per {@link itemSettingsHavePnpPolicyInputs}; otherwise
+ * `"off"`. Hosts override the default by passing an explicit `pnpEnforcement`
+ * value (engine input) or by calling
  * `ToolkitCoordinator.setPnpEnforcement("on" | "off")`.
  */
 export function resolveDefaultPnpEnforcement(args) {
     if (assessmentHasPnpPolicyInputs(args.assessment))
         return "on";
-    if (itemRefHasPnpPolicyInputs(args.currentItemRef))
+    if (itemSettingsHavePnpPolicyInputs(args.itemSettings))
         return "on";
     return "off";
 }

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

@@ -7,17 +7,22 @@
  * Tracks decisions from every Pass-1 contributor: host placement, host policy,
  * provider veto, PNP/profile gates, and custom policy sources.
  */
+/** The PNP/profile precedence rules, highest first. */
+export type PnpPolicySourceRule = "district-block" | "test-admin-override" | "item-restriction" | "pnp-prohibited" | "item-requirement" | "district-requirement" | "pnp-support";
 /**
- * Rule vocabulary for tool policy decisions.
+ * Rule vocabulary for tool policy decisions. A decision's `rule` is the one
+ * attribution channel: it names the step that enabled, blocked or advised on a
+ * tool.
  */
-export type ToolPolicyDecisionRule = "district-block" | "test-admin-override" | "item-restriction" | "item-requirement" | "district-requirement" | "pnp-support" | "pnp-prohibited" | "placement-membership" | "provider-disabled" | "host-allowlist" | "host-blocked" | "required-tool-blocked" | "custom-source" | "system-default";
+export type ToolPolicyDecisionRule = PnpPolicySourceRule | "placement-membership" | "provider-disabled" | "host-allowlist" | "host-blocked" | "required-tool-blocked" | "custom-source" | "system-default";
 export type ToolPolicySourceType = "organization" | "assessment" | "section" | "item" | "student" | "system" | "host" | "custom";
 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`
-     * for host-side gates or `7+` for custom sources that run after PNP/profile policy.
+     * 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.
      */
     precedence: number;
     rule: ToolPolicyDecisionRule;
@@ -120,7 +125,7 @@ export declare class ToolPolicyProvenanceBuilder {
      * walks every feature trail and rewrites `finalState` from the
      * final candidate set so callers can rely on
      * `provenance.features.get(toolId)?.finalState` as the canonical
-     * "is this tool visible right now?" answer (M8 design § 4 + § 12).
+     * "is this tool visible right now?" answer.
      *
      * Semantics applied per feature:
      *   - In `survivingIds`                                 → "enabled"

package/dist/policy/core/provenance.js

@@ -124,7 +124,7 @@ export class ToolPolicyProvenanceBuilder {
      * walks every feature trail and rewrites `finalState` from the
      * final candidate set so callers can rely on
      * `provenance.features.get(toolId)?.finalState` as the canonical
-     * "is this tool visible right now?" answer (M8 design § 4 + § 12).
+     * "is this tool visible right now?" answer.
      *
      * Semantics applied per feature:
      *   - In `survivingIds`                                 → "enabled"

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

@@ -1,28 +1,12 @@
 /**
- * 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, PNP policy 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 PNP policy
- * 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`.
+ * Tool policy engine — the stable entry for a host that instantiates or
+ * consumes a `ToolPolicyEngine`: the engine class, its decision request and
+ * response types, and the `PolicySource` extension contract. The composition
+ * pipeline, the PNP policy source and the provenance builder stay behind the
+ * engine, with no entry of their own.
  */
 export { ToolPolicyEngine, type PnpEnforcementMode, type ResolvedEngineInputs, type ToolPolicyChangeEvent, type ToolPolicyChangeListener, type ToolPolicyEngineArgs, type ToolPolicyEngineInputs, } from "./core/ToolPolicyEngine.js";
-export { TOOL_POLICY_ENGINE_KEY, type ToolPolicyEngineContext, } from "./core/engine-context.js";
 export { isHostDeniedFeature, type FeaturePolicyDecision, type FeaturePolicyRule, } from "./core/feature-decision.js";
-export type { RequiredToolBlockedDetails, ToolPolicyDecision, ToolPolicyDecisionRequest, ToolPolicyDiagnostic, ToolPolicyDiagnosticCode, ToolPolicyEntry, ToolPolicyHostGate, ToolScope, } 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 { PolicySourceTag, PnpPolicySourceRule, PnpPolicySourceTag, CustomPolicySourceTag, } from "./core/policy-source-tag.js";
-export type { ToolPolicyDecisionRule, ToolPolicyFeatureTrail, ToolPolicyProvenance, ToolPolicyResolutionDecision, ToolPolicySourceType, } from "./core/provenance.js";
+export type { PnpPolicySourceRule, ToolPolicyDecisionRule, ToolPolicyFeatureTrail, ToolPolicyProvenance, ToolPolicyResolutionDecision, ToolPolicySourceType, } from "./core/provenance.js";

package/dist/policy/engine.js

@@ -1,24 +1,9 @@
 /**
- * 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, PNP policy 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 PNP policy
- * 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`.
+ * Tool policy engine — the stable entry for a host that instantiates or
+ * consumes a `ToolPolicyEngine`: the engine class, its decision request and
+ * response types, and the `PolicySource` extension contract. The composition
+ * pipeline, the PNP policy source and the provenance builder stay behind the
+ * engine, with no entry of their own.
  */
 export { ToolPolicyEngine, } from "./core/ToolPolicyEngine.js";
-export { TOOL_POLICY_ENGINE_KEY, } from "./core/engine-context.js";
 export { isHostDeniedFeature, } from "./core/feature-decision.js";

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

@@ -1,6 +1,5 @@
 /**
- * PNP Policy Source for the M8 engine
- * (see
+ * PNP Policy Source: step 5 of `composeDecision` (see
  * `docs/tools-and-accomodations/architecture.md`).
  *
  * This source applies the PNP/profile precedence rules as a `(candidates, pnpPolicyInputs) →
@@ -8,26 +7,35 @@
  * engine can call once per `decide(...)` request, with all results
  * routed through the unified `ToolPolicyProvenanceBuilder`.
  */
-import type { AssessmentEntity, AssessmentItemRef } from "@pie-players/pie-players-shared/types";
+import type { AssessmentEntity, ItemSettings } from "@pie-players/pie-players-shared/types";
 import type { ToolRegistry } from "../../services/ToolRegistry.js";
-import type { ToolPolicyResolutionDecision, ToolPolicySourceType } from "../core/provenance.js";
-import type { PnpPolicySourceRule } from "../core/policy-source-tag.js";
+import type { PnpPolicySourceRule, ToolPolicyResolutionDecision, ToolPolicySourceType } from "../core/provenance.js";
+import type { OverrideBlockedDetails } from "../core/decision-types.js";
 /** Per-tool flags PNP/profile policy may attach to a surviving entry. */
 export interface PnpPolicyToolFlags {
     /** PNP/profile policy mandates this tool (item or district `requiredTools`). */
     required: boolean;
-    /** Student PNP marks this tool as a support (host UI cannot toggle off). */
+    /**
+     * The student's profile supports this tool, or a test-administration
+     * 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;
-    /** Source attribution for `ToolPolicyEntry.sources`. */
-    sourceType: ToolPolicySourceType;
+}
+/** An item a decision is scoped to, by its canonical id, with its settings. */
+export interface PnpPolicyItem {
+    id: string;
+    settings: ItemSettings;
 }
 export interface PnpPolicyApplyArgs {
     assessment?: AssessmentEntity | null;
-    currentItemRef?: AssessmentItemRef;
+    /**
+     * The item the decision is scoped to. Only a decision for the item's own
+     * toolbar or content carries one: an item's settings do not reach a section-
+     * or assessment-level decision.
+     */
+    item?: PnpPolicyItem;
 }
 /**
  * Provenance event the engine should append to its builder. Pre-baked
@@ -35,8 +43,8 @@ export interface PnpPolicyApplyArgs {
  * keeps a uniform `addDecision(...)` shape.
  */
 export interface PnpPolicyDecisionEvent {
-    precedence: 1 | 2 | 3 | 4 | 5 | 6;
-    rule: "district-block" | "test-admin-override" | "item-restriction" | "item-requirement" | "district-requirement" | "pnp-support" | "pnp-prohibited";
+    precedence: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+    rule: PnpPolicySourceRule;
     featureId: string;
     action: ToolPolicyResolutionDecision["action"];
     sourceType: ToolPolicySourceType;
@@ -50,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.
      */
@@ -66,13 +75,11 @@ export interface PnpPolicyResult {
      */
     decisions: PnpPolicyDecisionEvent[];
     /**
-     * Support ids named by a profile, district policy or item that no
-     * registration claims. Nothing resolves them, so they are silently inert —
-     * the engine turns each into a `tool-policy.unknownSupportId` diagnostic so a
-     * host sending its own label instead of an AfA/QTI feature id learns of it
-     * rather than seeing a tool quietly fail to appear.
+     * Ids a `true` test-administration override names that an item restriction
+     * or a PNP prohibition withdrew instead, each with the rule that did. The
+     * engine turns each into a `tool-policy.overrideBlocked` diagnostic.
      */
-    unmappedSupportIds: Set<string>;
+    blockedOverrides: Map<string, OverrideBlockedDetails["rule"]>;
     /** Configuration sources the engine should attach to its provenance. */
     sources: {
         assessment?: {
@@ -98,20 +105,18 @@ export declare class PnpPolicySource {
     constructor(toolRegistry: ToolRegistry);
     apply(args: PnpPolicyApplyArgs): PnpPolicyResult;
     /**
-     * Evaluate exactly one PNP support id through the same six-level
+     * Evaluate exactly one PNP support id through the same eight-level
      * precedence `apply(...)` uses.
      *
      * This exists for **policy-addressable capabilities that are not toolbar
      * tools** — a signed alternate rendered as its own region, for example.
      * `apply(...)` only evaluates support ids that appear somewhere in the
-     * bound policy inputs, and it keys its result maps by *mapped tool id*, so
-     * a caller asking about one feature would have to re-derive that mapping
-     * and could collide with another support id that maps to the same tool.
-     * Evaluating one id in isolation avoids both problems: the returned result
-     * carries exactly one decision, and `decisions[0].action` is the verdict.
+     * bound policy inputs. Evaluating one id in isolation answers for any
+     * 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 six levels would drift.
+     * It reuses `resolveSupport(...)` because a second copy of the eight levels
+     * would drift.
      */
     resolveFeature(featureId: string, args: PnpPolicyApplyArgs): PnpPolicyResult;
     /**
@@ -121,43 +126,13 @@ export declare class PnpPolicySource {
     private prepare;
     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.
-     *
-     * `tests/policy/PnpPolicySource.test.ts` locks this mapping behavior.
-     */
-    private mapSupportToToolId;
-    /**
-     * Resolve tool-specific settings, item-level taking precedence over
-     * assessment-level.
-     *
-     * Uses `??` (nullish-coalescing). 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."
+     * 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 resolveToolSettings;
+    unknownSupportIds(assessment: AssessmentEntity | null | undefined, items: readonly ItemSettings[]): Map<string, PnpPolicySourceRule[]>;
 }