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

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

@@ -2,28 +2,19 @@
  * 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
@@ -34,9 +25,8 @@
  * 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)
@@ -49,9 +39,6 @@ export function assessmentHasPnpPolicyInputs(assessment) {
             pnp.prohibitedSupports.length > 0) {
             return true;
         }
-        if (Array.isArray(pnp.activateAtInit) && pnp.activateAtInit.length > 0) {
-            return true;
-        }
     }
     const settings = assessment.settings;
     if (settings) {
@@ -65,42 +52,26 @@ export function assessmentHasPnpPolicyInputs(assessment) {
                 district.requiredTools.length > 0) {
                 return true;
             }
-            if (district.policies &&
-                typeof district.policies === "object" &&
-                Object.keys(district.policies).length > 0) {
-                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
+ * 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 function itemRefHasPnpPolicyInputs(itemRef) {
-    const settings = itemRef?.settings;
+export function itemSettingsHavePnpPolicyInputs(settings) {
     if (!settings)
         return false;
     if (Array.isArray(settings.requiredTools) &&
@@ -119,18 +90,19 @@ export function itemRefHasPnpPolicyInputs(itemRef) {
     return false;
 }
 /**
- * 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.
+     * 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/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, 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,37 @@
  * 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 +45,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;
@@ -66,13 +76,20 @@ 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 named by a profile, district policy, test administration or item that
+     * no tool is registered under, each with the rules whose lists name it, in
+     * precedence order. Nothing resolves them; the engine turns each into a
+     * `tool-policy.unknownSupportId` diagnostic. Empty when the registry is: an
+     * empty registry has nothing to check an id against, and
+     * `tool-config-validation` already reports it once.
+     */
+    unmappedSupportIds: Map<string, PnpPolicySourceRule[]>;
+    /**
+     * Ids a `true` test-administration override names that an item restriction
+     * or a PNP prohibition withdrew instead, each with the rule that did. The
+     * 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 +115,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.
+     * is the point — a second copy of the eight levels would drift.
      */
     resolveFeature(featureId: string, args: PnpPolicyApplyArgs): PnpPolicyResult;
     /**
@@ -121,43 +136,11 @@ 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."
+     * The named ids no tool is registered under, with the rules naming each in
+     * precedence order. A support id is the id of the tool it grants, so an id
+     * missing from the registry matches nothing placed.
      */
+    private unmappedIds;
+    /** Tool parameters: the item's entry, else the assessment's. */
     private resolveToolSettings;
 }