@pie-players/pie-assessment-toolkit 0.3.73 → 0.3.75

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

@@ -12,7 +12,7 @@
  * `tests/policy/compose-decision.test.ts` lock the orchestration in.
  */
 import { normalizeToolList, } from "../../services/tools-config-normalizer.js";
-import { ToolPolicyProvenanceBuilder } from "./provenance.js";
+import { ToolPolicyProvenanceBuilder, } from "./provenance.js";
 export function composeDecision(inputs) {
     const { request, tools, pnpPolicy, customSources, contextId } = inputs;
     const builder = new ToolPolicyProvenanceBuilder(contextId);
@@ -103,23 +103,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 +134,19 @@ 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",
-            });
+        // An id no tool is registered under matches nothing placed, so whatever it
+        // names is absent with no trace of why. Reported per decision because the
+        // ids arrive with the profile and settings, after the tools config.
+        for (const [supportId, origins] of pnpPolicyResult.unmappedSupportIds) {
+            diagnostics.push(unknownSupportIdDiagnostic(supportId, origins, request.level));
+        }
+        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);
-            }
-        }
         // 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
@@ -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);
@@ -306,7 +289,6 @@ export function composeDecision(inputs) {
             required: flag?.required ?? false,
             alwaysAvailable: flag?.alwaysAvailable ?? false,
             settings: flag?.settings,
-            sources: sourcesByTool.get(toolId) ?? ["placement"],
         };
     });
     builder.reconcileFinalStates(survivingIds);
@@ -346,3 +328,42 @@ function detectHostRemovalGate(toolId, args) {
     // pipeline has a bug; surface a best-effort rather than throwing.
     return { hostRule: "placement-missing", hostValue: args.placement };
 }
+/** 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,
+ * attributed to the highest-precedence rule naming it. `level` is absent on a
+ * feature decision, which has no toolbar level.
+ */
+export function unknownSupportIdDiagnostic(supportId, origins, level) {
+    const fields = origins.map((rule) => PNP_RULE_FIELDS[rule]).join(", ");
+    return {
+        code: "tool-policy.unknownSupportId",
+        ...(level ? { level } : {}),
+        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,44 @@ 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`, missing-from-`placement`, provider veto) removed a tool
+ * that item or district `requiredTools` mandates.
  *
  * `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.
+ * `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.
  */
-export type ToolPolicyDiagnosticCode = "tool-policy.requiredToolBlocked" | "tool-policy.placementMissing" | "tool-policy.unknownSupportId";
+export type ToolPolicyDiagnosticCode = "tool-policy.requiredToolBlocked" | "tool-policy.placementMissing" | "tool-policy.unknownSupportId" | "tool-policy.itemSettingNotApplied" | "tool-policy.overrideBlocked";
 /**
  * Which host gate removed a profile-mandated tool. Surfaced inside
  * `ToolPolicyDiagnostic.details` for `tool-policy.requiredToolBlocked`
@@ -94,29 +108,53 @@ export interface RequiredToolBlockedDetails extends Record<string, unknown> {
     /** 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> {
+    /** 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> {
+    /** The custom `PolicySource` that named the tool. */
+    customSourceId: string;
+}
+/** Payload of a `tool-policy.overrideBlocked` diagnostic. */
+export interface OverrideBlockedDetails extends Record<string, unknown> {
+    /** 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> {
+    /** 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;
+}
 export interface ToolPolicyDiagnostic {
     code: ToolPolicyDiagnosticCode;
-    level: ToolPlacementLevel;
+    /** The toolbar level decided; absent on a feature decision. */
+    level?: ToolPlacementLevel;
     toolId: string;
     message: string;
-    source?: PolicySourceTag;
     details?: Record<string, unknown>;
 }
 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;
     /**
@@ -126,13 +164,6 @@ export interface ToolPolicyEntry {
      * 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]`.
-     */
-    sources: PolicySourceTag[];
 }
 export interface ToolPolicyDecision {
     visibleTools: ToolPolicyEntry[];

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

@@ -21,10 +21,10 @@
  * 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.
@@ -34,7 +34,7 @@ export interface FeaturePolicyDecision {
     /** 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,7 @@ export interface FeaturePolicyDecision {
     action: ToolPolicyResolutionDecision["action"];
     /** Which precedence rule produced the verdict. */
     rule: FeaturePolicyRule;
-    precedence: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    precedence: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
     sourceType: ToolPolicySourceType;
     /** Human-readable explanation, suitable for a policy debugger. */
     reason: string;
@@ -51,9 +51,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
@@ -66,7 +67,7 @@ export interface FeaturePolicyDecision {
     assessmentBound: boolean;
     /**
      * `true` when the grant is a mandate (item or district `requiredTools`)
-     * rather than a student-profile support.
+     * rather than a student-profile support or a test-administration override.
      */
     required: boolean;
     /**
@@ -75,6 +76,12 @@ export interface FeaturePolicyDecision {
      * presentation would hang on; no vocabulary is defined yet.
      */
     parameters?: unknown;
+    /**
+     * 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.
+     */
+    diagnostics: ToolPolicyDiagnostic[];
 }
 /** What the engine knows that a single support-id resolution does not. */
 export interface FeatureDecisionContext {

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

@@ -20,13 +20,14 @@
  * "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";
 /**
  * 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 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.
  */
 const unboundAssessmentReason = (featureId) => `No assessment is bound, so no policy source could grant "${featureId}"`;
 /**
@@ -51,6 +52,7 @@ export function hostFeatureDenial(featureId, rule, hostValue, context) {
             : `Not listed in tools.policy.allowed (${hostValue.join(", ")})`,
         required: false,
         assessmentBound: context.assessmentBound,
+        diagnostics: [],
     };
 }
 /**
@@ -81,17 +83,21 @@ export function interpretFeatureResult(featureId, result, context) {
         granted,
         action: decision?.action ?? "skip",
         rule: decision?.rule ?? "pnp-support",
-        precedence: decision?.precedence ?? 6,
+        precedence: decision?.precedence ?? 8,
         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,
         assessmentBound: context.assessmentBound,
+        diagnostics: [
+            ...Array.from(result.unmappedSupportIds, ([supportId, origins]) => unknownSupportIdDiagnostic(supportId, origins)),
+            ...Array.from(result.blockedOverrides, ([toolId, rule]) => overrideBlockedDiagnostic(toolId, rule)),
+        ],
     };
 }

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

@@ -2,64 +2,55 @@
  * 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
+ *   - `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` / `toolParameters`.
  *
  * 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
+ * Return `true` when an item's settings carry item-level profile policy
  * material (`requiredTools`, `restrictedTools`, or `toolParameters`).
  *
- * 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";