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

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

@@ -12,7 +12,8 @@
  * `tests/policy/compose-decision.test.ts` lock the orchestration in.
  */
 import { normalizeToolList, } from "../../services/tools-config-normalizer.js";
-import { ToolPolicyProvenanceBuilder } from "./provenance.js";
+import { resolveToolParameters } from "./tool-parameters.js";
+import { ToolPolicyProvenanceBuilder, } from "./provenance.js";
 export function composeDecision(inputs) {
     const { request, tools, pnpPolicy, customSources, contextId } = inputs;
     const builder = new ToolPolicyProvenanceBuilder(contextId);
@@ -66,7 +67,7 @@ export function composeDecision(inputs) {
         }
         return true;
     });
-    // Step 3 — Host whitelist (only when non-empty).
+    // Step 3 — Host allowlist (only when non-empty).
     if (allowed.length > 0) {
         const allowedSet = new Set(allowed);
         candidates = candidates.filter((toolId) => {
@@ -103,23 +104,16 @@ export function composeDecision(inputs) {
     });
     // Step 5 — PNP/profile policy gates.
     const diagnostics = [];
-    const sourcesByTool = new Map();
-    for (const toolId of candidates) {
-        sourcesByTool.set(toolId, ["placement"]);
-    }
-    // Snapshot the post-host candidate set so step 5b can distinguish
-    // "host removed a required tool" (requiredToolBlocked fires)
-    // from "profile policy's own precedence removed a required tool" (fix
-    // per M8 PR 1 R1 S1 — multi-rule conflict on the same tool must
-    // not blame the host).
+    // Snapshot the post-host candidate set so step 5b reports
+    // requiredToolBlocked only for a mandated tool the host removed.
     const postHostCandidates = new Set(candidates);
     let pnpPolicyResult = null;
     if (pnpPolicy.enforcement === "on" &&
         pnpPolicy.source &&
-        (pnpPolicy.assessment || pnpPolicy.currentItemRef)) {
+        (pnpPolicy.assessment || pnpPolicy.item)) {
         pnpPolicyResult = pnpPolicy.source.apply({
             assessment: pnpPolicy.assessment,
-            currentItemRef: pnpPolicy.currentItemRef,
+            item: pnpPolicy.item,
         });
         if (pnpPolicyResult.sources.assessment) {
             builder.addSource("assessment", pnpPolicyResult.sources.assessment);
@@ -141,29 +135,12 @@ export function composeDecision(inputs) {
                 value: decision.value,
             });
         }
-        // A support id no registration claims resolves to itself and then matches
-        // nothing placed, so the capability is absent with no trace of why — the
-        // failure a host sending its own vocabulary instead of an AfA/QTI feature
-        // id actually hits. Reported per decision rather than at config time
-        // because the ids arrive with the profile, not with the tools config.
-        for (const supportId of pnpPolicyResult.unmappedSupportIds) {
-            diagnostics.push({
-                code: "tool-policy.unknownSupportId",
-                level: request.level,
-                toolId: supportId,
-                message: `No registered tool claims PNP support id "${supportId}"; it was carried through as a feature id and matched nothing. Expected an AfA 3.0 / QTI 3.0 access feature id.`,
-                source: "pnp.pnp-support",
-            });
+        for (const [toolId, rule] of pnpPolicyResult.blockedOverrides) {
+            diagnostics.push(overrideBlockedDiagnostic(toolId, rule, request.level));
         }
         // 5a — remove PNP/profile-blocked tools from the candidate set.
-        candidates = candidates.filter((toolId) => {
-            return !pnpPolicyResult.blockedToolIds.has(toolId);
-        });
-        for (const toolId of Array.from(sourcesByTool.keys())) {
-            if (pnpPolicyResult.blockedToolIds.has(toolId)) {
-                sourcesByTool.delete(toolId);
-            }
-        }
+        const { blockedToolIds } = pnpPolicyResult;
+        candidates = candidates.filter((toolId) => !blockedToolIds.has(toolId));
         // 5b — surface requiredToolBlocked diagnostics ONLY for
         // PNP/profile-mandated tools that the host removed (i.e., the tool was
         // NOT in `postHostCandidates`). Mandated tools removed by
@@ -171,20 +148,24 @@ export function composeDecision(inputs) {
         // blocking a `requiredTools` mandate) are an internal policy
         // resolution and must not be reported as a host conflict — the
         // loser's `block` decision is already in the trail with full
-        // provenance.
+        // provenance. A mandate names no level, so a tool placed at another
+        // level is served there: only placement at no level is a removal.
         //
         // `details` carries `{ rule, hostRule, hostValue }` so consumers
         // can render the conflict as a single sentence without
         // re-deriving the host gate from `provenance.features`. See
         // `RequiredToolBlockedDetails` for the typed shape.
-        for (const mandatedToolId of pnpPolicyResult.mandatedToolIds) {
-            const removedByHost = !postHostCandidates.has(mandatedToolId);
-            if (!removedByHost)
+        const placedAtAnyLevel = new Set(Object.values(tools.placement).flatMap(normalizeToolList));
+        for (const [mandatedToolId, ruleName] of pnpPolicyResult.mandates) {
+            if (postHostCandidates.has(mandatedToolId))
                 continue;
-            const flag = pnpPolicyResult.perToolFlags.get(mandatedToolId);
-            const ruleName = flag?.rule ?? "required-tool";
+            if (!placement.includes(mandatedToolId) &&
+                placedAtAnyLevel.has(mandatedToolId)) {
+                continue;
+            }
             const hostGate = detectHostRemovalGate(mandatedToolId, {
-                placement,
+                placedAtAnyLevel,
+                allTools: tools.placement,
                 allowed,
                 blocked,
                 providers: tools.providers,
@@ -198,7 +179,9 @@ export function composeDecision(inputs) {
                 code: "tool-policy.requiredToolBlocked",
                 level: request.level,
                 toolId: mandatedToolId,
-                message: `Profile policy mandates "${mandatedToolId}" (${ruleName}) but host policy removed it from level "${request.level}" via ${hostGate.hostRule}.`,
+                message: hostGate.hostRule === "placement-missing"
+                    ? `Profile policy mandates "${mandatedToolId}" (${ruleName}), but no level of tools.placement lists it.`
+                    : `Profile policy mandates "${mandatedToolId}" (${ruleName}), but host policy removes it via ${hostGate.hostRule}.`,
                 details,
             });
             builder.addDecision({
@@ -211,15 +194,6 @@ export function composeDecision(inputs) {
                 value: details,
             });
         }
-        // 5c — attach PNP policy source tags to surviving entries.
-        for (const toolId of candidates) {
-            const flag = pnpPolicyResult.perToolFlags.get(toolId);
-            if (flag) {
-                const tags = sourcesByTool.get(toolId) ?? [];
-                tags.push(`pnp.${flag.rule}`);
-                sourcesByTool.set(toolId, tags);
-            }
-        }
     }
     // Step 6 — Custom PolicySources.
     for (let i = 0; i < customSources.length; i++) {
@@ -238,7 +212,7 @@ export function composeDecision(inputs) {
                     level: request.level,
                     toolId,
                     message: `Custom source "${source.id}" tried to add tool "${toolId}" that was not in candidates; ignored.`,
-                    source: `custom.${source.id}`,
+                    details: { customSourceId: source.id },
                 });
                 refinedSet.delete(toolId);
             }
@@ -250,7 +224,7 @@ export function composeDecision(inputs) {
         // this auto-log, the provenance trail for a silently-removed
         // tool would show only the prior `enable` decisions and the
         // final-state reconciliation would have no evidence to mark it
-        // `blocked` (M8 PR 1 R2 S1 / M1 case B).
+        // `blocked`.
         const explicitBlocks = new Set();
         if (result.decisions) {
             for (const event of result.decisions) {
@@ -284,18 +258,27 @@ export function composeDecision(inputs) {
                 value: { customSourceId: source.id },
             });
         }
-        // Annotate surviving entries with `custom.<id>` so hosts can see
-        // which custom source kept them in.
-        for (const toolId of candidates) {
-            const tags = sourcesByTool.get(toolId) ?? ["placement"];
-            tags.push(`custom.${source.id}`);
-            sourcesByTool.set(toolId, tags);
-        }
-        // And drop attribution for IDs the source removed.
-        for (const toolId of before) {
-            if (!refinedSet.has(toolId)) {
-                sourcesByTool.delete(toolId);
-            }
+    }
+    // Step 7 — item settings a shared toolbar does not apply. Placement is the
+    // host's section-wide choice, so the tool stays; the diagnostic says where to
+    // place it for the item setting to hold.
+    for (const toolId of candidates) {
+        for (const item of inputs.unappliedItems ?? []) {
+            const settings = ["restrictedTools", "requiredTools"].filter((key) => item.settings[key]?.includes(toolId) === true);
+            if (settings.length === 0)
+                continue;
+            const details = {
+                itemId: item.id,
+                settings,
+                toolbarLevel: request.scope.level,
+            };
+            diagnostics.push({
+                code: "tool-policy.itemSettingNotApplied",
+                level: request.level,
+                toolId,
+                message: `Item "${item.id}" names "${toolId}" in ${settings.join(" and ")}, but "${toolId}" is on the ${request.scope.level}-level toolbar, which item settings do not reach. Place "${toolId}" at item level to enforce the setting per item.`,
+                details,
+            });
         }
     }
     const survivingIds = new Set(candidates);
@@ -305,8 +288,7 @@ export function composeDecision(inputs) {
             toolId,
             required: flag?.required ?? false,
             alwaysAvailable: flag?.alwaysAvailable ?? false,
-            settings: flag?.settings,
-            sources: sourcesByTool.get(toolId) ?? ["placement"],
+            parameters: resolveToolParameters(toolId, pnpPolicy.assessment, pnpPolicy.item),
         };
     });
     builder.reconcileFinalStates(survivingIds);
@@ -323,10 +305,11 @@ export function composeDecision(inputs) {
  * (blocklist) last — so the FIRST gate that would have matched wins,
  * which is the gate the pipeline actually invoked. Subsequent gates
  * never get to evaluate a tool that an earlier step already removed.
+ * Step 5b passes only a tool this level places or no level places.
  */
 function detectHostRemovalGate(toolId, args) {
-    if (!args.placement.includes(toolId)) {
-        return { hostRule: "placement-missing", hostValue: args.placement };
+    if (!args.placedAtAnyLevel.has(toolId)) {
+        return { hostRule: "placement-missing", hostValue: args.allTools };
     }
     if (args.providers?.[toolId]?.enabled === false) {
         return { hostRule: "provider-disabled", hostValue: false };
@@ -340,9 +323,47 @@ function detectHostRemovalGate(toolId, args) {
             hostValue: Array.from(args.blocked),
         };
     }
-    // Defensive: `removedByHost` is true at the call site (the tool is
-    // in `mandatedToolIds` but not in `postHostCandidates`), so one of
-    // the four gates above MUST have fired. If none did, the host
-    // pipeline has a bug; surface a best-effort rather than throwing.
-    return { hostRule: "placement-missing", hostValue: args.placement };
+    // Defensive: at the call site the tool is in `mandates` but not in
+    // `postHostCandidates`, so one of the four gates above MUST have
+    // fired. If none did, the host pipeline has a bug; surface a
+    // best-effort rather than throwing.
+    return { hostRule: "placement-missing", hostValue: args.allTools };
+}
+/** Where each PNP/profile rule's ids are authored. */
+const PNP_RULE_FIELDS = {
+    "district-block": "settings.districtPolicy.blockedTools",
+    "test-admin-override": "settings.testAdministration.toolOverrides",
+    "item-restriction": "item settings.restrictedTools",
+    "pnp-prohibited": "personalNeedsProfile.prohibitedSupports",
+    "item-requirement": "item settings.requiredTools",
+    "district-requirement": "settings.districtPolicy.requiredTools",
+    "pnp-support": "personalNeedsProfile.supports",
+};
+/**
+ * A `tool-policy.overrideBlocked` diagnostic for a tool a `true` test
+ * administration override grants and `rule` withdraws. `level` is absent on a
+ * feature decision, which has no toolbar level.
+ */
+export function overrideBlockedDiagnostic(toolId, rule, level) {
+    return {
+        code: "tool-policy.overrideBlocked",
+        ...(level ? { level } : {}),
+        toolId,
+        message: `settings.testAdministration.toolOverrides grants "${toolId}", but ${PNP_RULE_FIELDS[rule]} withdraws it and outranks a granting override.`,
+        details: { rule },
+    };
+}
+/**
+ * A `tool-policy.unknownSupportId` diagnostic for an id the registry lacks,
+ * naming every list that names it. It describes the engine's inputs rather
+ * than a decision, so it carries no level.
+ */
+export function unknownSupportIdDiagnostic(supportId, origins) {
+    const fields = origins.map((rule) => PNP_RULE_FIELDS[rule]).join(", ");
+    return {
+        code: "tool-policy.unknownSupportId",
+        toolId: supportId,
+        message: `No tool is registered under "${supportId}", named in ${fields}, so it matches nothing. These lists name tools by tool id.`,
+        details: { origins: [...origins] },
+    };
 }

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

@@ -11,16 +11,15 @@
  */
 import type { ToolPlacementLevel } from "../../services/tools-config-normalizer.js";
 import type { ToolContext, ToolLevel } from "../../services/tool-context.js";
-import type { PolicySourceTag } from "./policy-source-tag.js";
-import type { ToolPolicyProvenance } from "./provenance.js";
+import type { PnpPolicySourceRule, ToolPolicyProvenance } from "./provenance.js";
 /**
  * Scope identifier for a `decide(...)` request. The engine uses
  * `level` to pick which placement bucket to read; `scopeId` is opaque
  * to the engine (it is round-tripped into provenance for human-readable
  * trails) and is typically the section-id, item-id, or passage-id of
  * the surface asking the question. `contentKind` mirrors the
- * `ToolbarContext.scope.contentKind` field already in use by
- * `<pie-item-toolbar>` Pass-2 visibility.
+ * `ToolbarContext.scope.contentKind` field `<pie-item-toolbar>` reads for
+ * content relevance.
  */
 export interface ToolScope {
     level: ToolLevel;
@@ -41,29 +40,49 @@ export interface ToolPolicyDecisionRequest {
     level: ToolPlacementLevel;
     scope: ToolScope;
     /**
-     * Optional Pass-2 context. The engine itself does NOT call
-     * `isVisibleInContext(...)`; that gate is intentionally applied
-     * at the toolbar boundary (Pass-2 = relevance, Pass-1 = the
-     * engine's job). The context is forwarded to custom
-     * `PolicySource` instances so they can refine the candidate set
-     * if they need to.
+     * Optional tool context. The engine does not call
+     * `isVisibleInContext(...)`: content relevance is applied at the toolbar
+     * boundary. The context is forwarded to custom `PolicySource` instances so
+     * they can refine the candidate set.
      */
     context?: ToolContext;
 }
 /**
- * Diagnostic codes the engine may emit alongside a decision. The
- * canonical case in M8 is `tool-policy.requiredToolBlocked` — fired
- * when a host policy gate (`policy.blocked`, missing-from-`placement`,
- * provider veto) removed a tool that profile policy `requiredTools` /
- * `district.requiredTools` mandates.
+ * Diagnostic codes the engine may emit alongside a decision.
+ * `tool-policy.requiredToolBlocked` fires when a host policy gate
+ * (`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]`
- * for the resolved level. The host-side `ToolConfigDiagnostic` channel
+ * for the resolved level. `details` is {@link PlacementMissingDetails}.
+ * The host-side `ToolConfigDiagnostic` channel
  * (already used by `tool-config-validation.ts`) covers config-time
  * misconfiguration; this channel covers per-decision conflicts.
+ *
+ * `tool-policy.unknownSupportId` fires for each id a profile, district
+ * policy, test administration or item names that no tool is registered under.
+ * 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
+ * `restrictedTools` or `requiredTools` names, once per tool and item: item
+ * settings govern only the item's own toolbar. `details` is
+ * {@link ItemSettingNotAppliedDetails}.
+ *
+ * `tool-policy.overrideBlocked` fires for each tool a `true`
+ * `settings.testAdministration.toolOverrides` entry grants that an item's
+ * `restrictedTools` or the profile's `prohibitedSupports` withdraws instead.
+ * `details` is {@link OverrideBlockedDetails}.
+ *
+ * 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";
+export type ToolPolicyDiagnosticCode = keyof ToolPolicyDiagnosticDetails;
 /**
  * Which host gate removed a profile-mandated tool. Surfaced inside
  * `ToolPolicyDiagnostic.details` for `tool-policy.requiredToolBlocked`
@@ -73,66 +92,90 @@ 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;
 }
-export interface ToolPolicyDiagnostic {
-    code: ToolPolicyDiagnosticCode;
-    level: ToolPlacementLevel;
-    toolId: string;
-    message: string;
-    source?: PolicySourceTag;
-    details?: Record<string, unknown>;
+/** Payload of a `tool-policy.unknownSupportId` diagnostic. */
+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 {
+    /** The custom `PolicySource` that named the tool. */
+    customSourceId: string;
+}
+/** Payload of a `tool-policy.overrideBlocked` diagnostic. */
+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 {
+    /** Canonical id of the item whose setting names the tool. */
+    itemId: string;
+    /** The item settings that name it. */
+    settings: Array<"restrictedTools" | "requiredTools">;
+    /** The level of the toolbar the tool is on. */
+    toolbarLevel: ToolLevel;
 }
+/** 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;
     /**
      * `true` when PNP/profile policy mandates this tool (item or district
-     * `requiredTools`, or PNP support without prohibition). Advisory
-     * mandates that the host blocked do *not* surface here — they
-     * appear in `diagnostics` instead. Hosts that need to know about
-     * those should listen on the diagnostic channel.
+     * `requiredTools`). Advisory mandates that the host blocked do *not*
+     * surface here — they appear in `diagnostics` instead. Hosts that need
+     * to know about those should listen on the diagnostic channel.
      */
     required: boolean;
     /**
-     * `true` for PNP `supports` — UI-level signal that the host
-     * cannot toggle this tool off in user preferences. Does NOT
-     * override host blocks (they would have removed the entry
-     * before this flag is read).
+     * `true` for a tool the student's PNP `supports` or a
+     * `testAdministration.toolOverrides` entry grants — UI-level signal that
+     * the host cannot toggle this tool off in user preferences. Does NOT
+     * override host blocks (they would have removed the entry before this
+     * flag is read).
      */
     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.
-     */
-    settings?: unknown;
-    /**
-     * Every contributor that helped this entry survive the
-     * composition pipeline. Always non-empty — at minimum
-     * `["placement"]` for any entry that came from
-     * `tools.placement[level]`.
+     * 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.
      */
-    sources: PolicySourceTag[];
+    parameters?: Record<string, unknown>;
 }
 export interface ToolPolicyDecision {
     visibleTools: ToolPolicyEntry[];

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

@@ -21,20 +21,20 @@
  * reasons, and only the second is a defect.
  */
 import type { PnpPolicyResult } from "../sources/PnpPolicySource.js";
-import type { PnpPolicySourceRule } from "./policy-source-tag.js";
-import type { ToolPolicyResolutionDecision, ToolPolicySourceType } from "./provenance.js";
+import type { ToolPolicyDiagnostic } from "./decision-types.js";
+import type { PnpPolicySourceRule, ToolPolicyResolutionDecision, ToolPolicySourceType } from "./provenance.js";
 /**
- * A feature verdict comes from one of the six PNP precedence levels, or from a
+ * 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;
     /**
-     * `true` only when policy explicitly granted the feature at one of the six
+     * `true` only when policy explicitly granted the feature at one of the eight
      * precedence levels. A feature nobody configured is **not** available —
      * accommodations require a documented need, so silence means no.
      */
@@ -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;
+    /** 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;
@@ -51,9 +52,10 @@ export interface FeaturePolicyDecision {
      *
      * `false` makes a *denial* a wiring gap rather than a verdict: no profile,
      * district policy or test administration could be consulted, because there was
-     * no assessment to read them from. It is not itself a denial — an item ref
-     * carrying `requiredTools` mandates a feature at precedence 4 with no
-     * assessment bound — so read it alongside `granted` rather than instead of it.
+     * no assessment to read them from. It is not itself a denial — an item's
+     * registered settings carrying `requiredTools` mandate a feature at precedence
+     * 6 with no assessment bound — so read it alongside `granted` rather than
+     * instead of it.
      *
      * Granting is unaffected either way: an unbound host with no item mandate still
      * gets `granted: false`, since an accommodation requires a documented need and
@@ -65,16 +67,23 @@ export interface FeaturePolicyDecision {
      */
     assessmentBound: boolean;
     /**
-     * `true` when the grant is a mandate (item or district `requiredTools`)
-     * rather than a student-profile support.
+     * `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.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[];
 }
 /** What the engine knows that a single support-id resolution does not. */
 export interface FeatureDecisionContext {
@@ -90,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.
  *
@@ -107,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,13 +20,12 @@
  * "nothing was bound to ask against" are the same verdict for different
  * reasons, and only the second is a defect.
  */
+import { overrideBlockedDiagnostic } from "./compose-decision.js";
 /**
  * Reason text for a denial that had no assessment to decide against.
  *
- * Replaces 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 seventh 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}"`;
 /**
@@ -51,6 +50,7 @@ export function hostFeatureDenial(featureId, rule, hostValue, context) {
             : `Not listed in tools.policy.allowed (${hostValue.join(", ")})`,
         required: false,
         assessmentBound: context.assessmentBound,
+        diagnostics: [],
     };
 }
 /**
@@ -71,27 +71,31 @@ 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 ?? 6,
+        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 ref carrying `requiredTools` mandates it at precedence 4
-        // with no assessment in sight — and there the source's reason is the true
-        // one.
+        // feature — an item's registered settings carrying `requiredTools` mandate
+        // it at precedence 6 with no assessment in sight — and there the source's
+        // reason is the true one.
         reason: context.assessmentBound || granted
             ? reason
             : unboundAssessmentReason(featureId),
         required: Boolean(flags?.required),
-        parameters: flags?.settings,
+        parameters,
         assessmentBound: context.assessmentBound,
+        diagnostics: Array.from(result.blockedOverrides, ([toolId, rule]) => overrideBlockedDiagnostic(toolId, rule)),
     };
 }