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

package/dist/policy/core/ToolPolicyEngine.js

@@ -3,24 +3,24 @@
  * `docs/tools-and-accomodations/architecture.md`.
  *
  * Wraps `composeDecision(...)` with engine-instance state:
- *   - bound inputs (`tools`, `assessment`, `currentItemRef`, ...)
+ *   - bound inputs (`tools`, `assessment`, `pnpEnforcement`) and the
+ *     settings of the mounted items
  *   - registered custom `PolicySource`s
  *   - `onPolicyChange` subscriber bus
  *   - `dispose()` clean-up
  *
  * The class has no DOM dependency and no Svelte runes. It is safe to
  * instantiate inside a worker, in a Node test, or inside a CE
- * connectedCallback. The Svelte context glue (`TOOL_POLICY_ENGINE_KEY`)
- * lives in `engine-context.ts`.
- *
- * PR 1 ships the engine *without callers*. PR 2 wires it into
- * `ToolkitCoordinator`. PR 3 switches `<pie-item-toolbar>` over.
+ * connectedCallback. `ToolkitCoordinator` owns the instance, and
+ * `<pie-item-toolbar>` reads its decisions through the coordinator.
  */
 import { normalizeToolList, normalizeToolsConfig, } from "../../services/tools-config-normalizer.js";
 import { hostFeatureDenial, interpretFeatureResult, } from "./feature-decision.js";
-import { composeDecision } from "./compose-decision.js";
+import { composeDecision, unknownSupportIdDiagnostic, } from "./compose-decision.js";
 import { resolveDefaultPnpEnforcement } from "./pnp-policy-inputs.js";
-import { PnpPolicySource } from "../sources/PnpPolicySource.js";
+import { resolveToolParameters } from "./tool-parameters.js";
+import { structurallyEqual } from "../../utils/structural-equality.js";
+import { PnpPolicySource, } from "../sources/PnpPolicySource.js";
 const DEFAULT_TOOLS = normalizeToolsConfig({
     policy: { allowed: [], blocked: [] },
     placement: { section: [], item: [], passage: [] },
@@ -28,30 +28,34 @@ const DEFAULT_TOOLS = normalizeToolsConfig({
 });
 export class ToolPolicyEngine {
     toolRegistry;
+    unsubscribeRegistry;
     contextId;
+    assessmentOptional;
     pnpPolicySource;
     customSources;
     listeners = new Set();
     tools;
     assessment;
-    currentItemRef;
-    pnpEnforcement;
+    pnpEnforcementOverride;
+    /**
+     * Mounted items' settings by canonical item id, newest registration last;
+     * see {@link registerItemSettings}.
+     */
+    itemSettings = new Map();
+    inputDiagnostics = Object.freeze([]);
     disposed = false;
     constructor(args) {
         this.toolRegistry = args.toolRegistry;
         this.contextId = args.contextId ?? "tool-policy";
+        this.assessmentOptional = args.assessmentOptional === true;
         this.pnpPolicySource = new PnpPolicySource(this.toolRegistry);
         this.customSources = args.customSources ? [...args.customSources] : [];
         const inputs = args.inputs ?? {};
         this.tools = inputs.tools ?? DEFAULT_TOOLS;
         this.assessment = inputs.assessment ?? null;
-        this.currentItemRef = inputs.currentItemRef ?? null;
-        this.pnpEnforcement =
-            inputs.pnpEnforcement ??
-                resolveDefaultPnpEnforcement({
-                    assessment: this.assessment,
-                    currentItemRef: this.currentItemRef,
-                });
+        this.pnpEnforcementOverride = inputs.pnpEnforcement ?? null;
+        this.refreshInputDiagnostics();
+        this.unsubscribeRegistry = this.watchRegistry();
     }
     /**
      * Resolve the visible tool set for a given placement level and
@@ -67,27 +71,92 @@ export class ToolPolicyEngine {
      * values even though the policy decision itself is identical.
      * Hosts that want timestamp-stable provenance should reuse a
      * cached `ToolPolicyDecision` rather than re-call `decide(...)`.
+     *
+     * An item's registered settings apply to the item's own toolbar: a request
+     * at item level whose scope is the item. Every other request — a section,
+     * assessment or passage toolbar — is shared by the items it sits beside, so
+     * it leaves every item's settings out and reports each tool on its toolbar
+     * that one restricts or requires as `tool-policy.itemSettingNotApplied`.
      */
     decide(request) {
         this.assertNotDisposed();
         const requestContextId = request.scope.scopeId
             ? `${this.contextId}:${request.level}:${request.scope.scopeId}`
             : `${this.contextId}:${request.level}`;
+        const item = request.level === "item" ? this.itemForScope(request.scope) : undefined;
+        const shared = request.level !== "item" ||
+            request.scope.level === "section" ||
+            request.scope.level === "assessment";
         return composeDecision({
             request,
             tools: this.tools,
             pnpPolicy: {
                 source: this.pnpPolicySource,
                 assessment: this.assessment ?? undefined,
-                currentItemRef: this.currentItemRef ?? undefined,
-                enforcement: this.pnpEnforcement,
+                item,
+                enforcement: this.enforcementFor(item),
             },
+            unappliedItems: shared ? this.enforcedItems() : undefined,
             customSources: this.customSources,
             contextId: requestContextId,
         });
     }
     /**
-     * Resolve eligibility for one PNP/AfA feature id through the six-level
+     * Whether some surface is granted `featureId`: a decision with no item scope,
+     * or one scoped to a registered item. A provider serves every surface, so its
+     * failure denies the accommodation wherever one surface is granted it.
+     *
+     * `enforced` counts only scopes whose `pnpEnforcement` is on, as a toolbar
+     * tool's decisions do; a feature with no placement leaves it unset.
+     */
+    grantsFeatureAnywhere(featureId, options = {}) {
+        const counts = (item) => !options.enforced || this.enforcementFor(item) === "on";
+        if (counts() && this.decideFeature(featureId).granted)
+            return true;
+        for (const id of this.itemSettings.keys()) {
+            const settings = this.itemSettingsFor(id);
+            if (!counts(settings ? { id, settings } : undefined))
+                continue;
+            if (this.decideFeature(featureId, { level: "item", scopeId: id }).granted) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * File a mounted item's settings under its canonical id. They govern the
+     * decisions scoped to that item: its own toolbar, and a feature its content
+     * asks about with the item's scope. See {@link decide}.
+     *
+     * The same item mounted twice registers twice; the newest registration
+     * applies, and its cleanup hands the item back to the one before. Emits an
+     * `"item-settings"` change whenever the settings that apply to the item
+     * change.
+     */
+    registerItemSettings(itemId, settings) {
+        this.assertNotDisposed();
+        const entry = { settings };
+        const before = this.itemSettingsFor(itemId);
+        const entries = this.itemSettings.get(itemId) ?? [];
+        entries.push(entry);
+        this.itemSettings.set(itemId, entries);
+        this.emitIfItemSettingsChanged(itemId, before);
+        return () => {
+            if (this.disposed)
+                return;
+            const current = this.itemSettings.get(itemId);
+            const index = current?.indexOf(entry) ?? -1;
+            if (!current || index < 0)
+                return;
+            const previous = this.itemSettingsFor(itemId);
+            current.splice(index, 1);
+            if (current.length === 0)
+                this.itemSettings.delete(itemId);
+            this.emitIfItemSettingsChanged(itemId, previous);
+        };
+    }
+    /**
+     * Resolve eligibility for one PNP/AfA feature id through the eight-level
      * precedence, independent of toolbar placement.
      *
      * For capabilities that render as their own surface rather than a toolbar
@@ -108,20 +177,24 @@ export class ToolPolicyEngine {
      * The decision reports whether an assessment was bound, which is the engine's
      * to answer rather than the policy source's — see
      * {@link FeaturePolicyDecision.assessmentBound}.
+     *
+     * `scope` is the surface asking. An item's scope brings in the item's
+     * registered settings, as {@link decide} does for the item's toolbar.
      */
-    decideFeature(featureId) {
+    decideFeature(featureId, scope) {
         this.assertNotDisposed();
         const hostDenial = this.hostFeatureGate(featureId);
         if (hostDenial)
             return hostDenial;
+        const item = this.itemForScope(scope);
         return interpretFeatureResult(featureId, this.pnpPolicySource.resolveFeature(featureId, {
             assessment: this.assessment ?? undefined,
-            currentItemRef: this.currentItemRef ?? undefined,
+            item,
         }), 
         // `resolveFeature` takes the assessment as `undefined` either way, so the
         // source cannot tell an unbound host from one whose profile is silent.
         // The engine can.
-        { assessmentBound: this.assessment !== null });
+        { assessmentBound: this.assessment !== null }, resolveToolParameters(featureId, this.assessment, item));
     }
     /**
      * The host gates that hold for a feature id, or `null` when none fires.
@@ -159,17 +232,14 @@ export class ToolPolicyEngine {
     /**
      * Apply a partial input update.
      *
-     * Each key is value-diffed via `Object.is` before storing, so callers
-     * may safely re-push the same reference (e.g. on Svelte effect
-     * re-runs caused by unrelated tracked reads): no-op patches do not
-     * fire `onPolicyChange` listeners. This contract is relied on by
-     * `PieAssessmentToolkit.svelte`'s prop-forwarding effect and by the
-     * coordinator's `decideToolPolicy()` tests.
+     * A key that did not change does not fire `onPolicyChange` listeners.
+     * `tools` is diffed with `Object.is`. `assessment` is diffed structurally,
+     * because hosts rebuild it from their own state on every render; the latest
+     * reference is stored either way.
      *
-     * `pnpEnforcement` is stored on its own field and always emits with
-     * a distinct `"pnp-enforcement"` reason when no other key changed,
-     * so PR 4's auto-on flip can target that reason without a separate
-     * event channel.
+     * `pnpEnforcement` sets the override, `null` or `undefined` returning to
+     * auto-mode, and emits with a distinct `"pnp-enforcement"` reason when no
+     * other key changed.
      */
     updateInputs(patch) {
         this.assertNotDisposed();
@@ -184,21 +254,17 @@ export class ToolPolicyEngine {
         }
         if ("assessment" in patch) {
             const next = patch.assessment ?? null;
-            if (!Object.is(this.assessment, next)) {
-                this.assessment = next;
+            const assessmentChanged = !structurallyEqual(this.assessment, next);
+            this.assessment = next;
+            if (assessmentChanged) {
                 changed = true;
+                this.refreshInputDiagnostics();
             }
         }
-        if ("currentItemRef" in patch) {
-            const next = patch.currentItemRef ?? null;
-            if (!Object.is(this.currentItemRef, next)) {
-                this.currentItemRef = next;
-                changed = true;
-            }
-        }
-        if ("pnpEnforcement" in patch && patch.pnpEnforcement) {
-            if (this.pnpEnforcement !== patch.pnpEnforcement) {
-                this.pnpEnforcement = patch.pnpEnforcement;
+        if ("pnpEnforcement" in patch) {
+            const next = patch.pnpEnforcement ?? null;
+            if (this.pnpEnforcementOverride !== next) {
+                this.pnpEnforcementOverride = next;
                 pnpChanged = true;
             }
         }
@@ -216,9 +282,12 @@ export class ToolPolicyEngine {
      */
     replaceToolRegistry(toolRegistry, tools) {
         this.assertNotDisposed();
+        this.unsubscribeRegistry();
         this.toolRegistry = toolRegistry;
         this.pnpPolicySource = new PnpPolicySource(toolRegistry);
+        this.unsubscribeRegistry = this.watchRegistry();
         this.tools = tools;
+        this.refreshInputDiagnostics();
         this.emit({ reason: "inputs", inputs: this.snapshotInputs() });
     }
     registerPolicySource(source) {
@@ -230,15 +299,15 @@ export class ToolPolicyEngine {
         });
         return () => {
             const idx = this.customSources.indexOf(source);
-            if (idx !== -1) {
-                this.customSources.splice(idx, 1);
-                if (!this.disposed) {
-                    this.emit({
-                        reason: "policy-source-removed",
-                        inputs: this.snapshotInputs(),
-                    });
-                }
-            }
+            if (idx === -1)
+                return;
+            this.customSources.splice(idx, 1);
+            if (this.disposed)
+                return;
+            this.emit({
+                reason: "policy-source-removed",
+                inputs: this.snapshotInputs(),
+            });
         };
     }
     onPolicyChange(listener) {
@@ -254,21 +323,99 @@ export class ToolPolicyEngine {
         if (this.disposed)
             return;
         this.disposed = true;
+        this.unsubscribeRegistry();
         this.emit({
             reason: "disposed",
             inputs: this.snapshotInputs(),
         });
         this.listeners.clear();
+        this.itemSettings.clear();
         this.customSources.length = 0;
     }
     snapshotInputs() {
         return Object.freeze({
             tools: this.tools,
             assessment: this.assessment,
-            currentItemRef: this.currentItemRef,
-            pnpEnforcement: this.pnpEnforcement,
+            pnpEnforcement: this.enforcementFor(),
+            pnpEnforcementOverride: this.pnpEnforcementOverride,
+            assessmentExpected: !this.assessmentOptional || this.pnpEnforcementOverride === "on",
+            diagnostics: this.inputDiagnostics,
         });
     }
+    /** The override, else auto-mode over the assessment and `item`'s settings. */
+    enforcementFor(item) {
+        return (this.pnpEnforcementOverride ??
+            resolveDefaultPnpEnforcement({
+                assessment: this.assessment,
+                itemSettings: item?.settings,
+            }));
+    }
+    /** The settings that apply to `itemId`: its newest registration's. */
+    itemSettingsFor(itemId) {
+        return this.itemSettings.get(itemId)?.at(-1)?.settings;
+    }
+    emitIfItemSettingsChanged(itemId, before) {
+        if (structurallyEqual(before, this.itemSettingsFor(itemId)))
+            return;
+        this.refreshInputDiagnostics();
+        this.emit({ reason: "item-settings", inputs: this.snapshotInputs() });
+    }
+    /**
+     * Recompute {@link ResolvedEngineInputs.diagnostics} from the bound
+     * assessment, every mounted item's settings and the registry. Returns
+     * whether they changed.
+     */
+    refreshInputDiagnostics() {
+        const items = [];
+        for (const id of this.itemSettings.keys()) {
+            const settings = this.itemSettingsFor(id);
+            if (settings)
+                items.push(settings);
+        }
+        const next = Array.from(this.pnpPolicySource.unknownSupportIds(this.assessment, items), ([supportId, origins]) => unknownSupportIdDiagnostic(supportId, origins));
+        if (structurallyEqual(this.inputDiagnostics, next))
+            return false;
+        this.inputDiagnostics = Object.freeze(next);
+        return true;
+    }
+    /**
+     * Registering a tool into the bound registry, or removing one, can make a
+     * named id known or unknown, so it emits an `"inputs"` change when the input
+     * diagnostics move.
+     */
+    watchRegistry() {
+        return this.toolRegistry.onRegistryChange(() => {
+            if (this.disposed)
+                return;
+            if (this.refreshInputDiagnostics()) {
+                this.emit({ reason: "inputs", inputs: this.snapshotInputs() });
+            }
+        });
+    }
+    /**
+     * The registered item an item scope names, by its canonical id. A scope
+     * of any other level names none.
+     */
+    itemForScope(scope) {
+        if (scope?.level !== "item")
+            return undefined;
+        const id = scope.canonicalItemId || scope.itemId || scope.scopeId;
+        const settings = id ? this.itemSettingsFor(id) : undefined;
+        return settings ? { id, settings } : undefined;
+    }
+    /** The registered items whose settings their own toolbar enforces. */
+    enforcedItems() {
+        const items = [];
+        for (const id of this.itemSettings.keys()) {
+            const settings = this.itemSettingsFor(id);
+            if (!settings)
+                continue;
+            const item = { id, settings };
+            if (this.enforcementFor(item) === "on")
+                items.push(item);
+        }
+        return items;
+    }
     emit(event) {
         for (const listener of Array.from(this.listeners)) {
             try {

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

@@ -11,27 +11,48 @@
  * The tests in
  * `tests/policy/compose-decision.test.ts` lock the orchestration in.
  */
-import type { AssessmentEntity, AssessmentItemRef } from "@pie-players/pie-players-shared/types";
-import { type CanonicalToolsConfig } from "../../services/tools-config-normalizer.js";
-import type { ToolPolicyDecision, ToolPolicyDecisionRequest } from "./decision-types.js";
+import type { AssessmentEntity } from "@pie-players/pie-players-shared/types";
+import { type CanonicalToolsConfig, type ToolPlacementLevel } from "../../services/tools-config-normalizer.js";
+import type { OverrideBlockedDetails, ToolPolicyDecision, ToolPolicyDecisionRequest, ToolPolicyDiagnostic } from "./decision-types.js";
 import type { PolicySource } from "./PolicySource.js";
-import type { PnpPolicySource } from "../sources/PnpPolicySource.js";
+import { type PnpPolicySourceRule } from "./provenance.js";
+import type { PnpPolicyItem, PnpPolicySource } from "../sources/PnpPolicySource.js";
 export interface ComposeDecisionInputs {
     request: ToolPolicyDecisionRequest;
     tools: CanonicalToolsConfig;
     pnpPolicy: {
         source: PnpPolicySource | null;
         assessment?: AssessmentEntity;
-        currentItemRef?: AssessmentItemRef;
+        /** The item an item-scoped decision is for; see {@link PnpPolicyItem}. */
+        item?: PnpPolicyItem;
         /**
          * "on" applies the PNP/profile precedence rules; "off" skips step 5
-         * entirely. Defaults to "on" when an assessment is present
-         * and the source is non-null (see M8 design Q5).
+         * entirely. The engine resolves it from the enforcement override, or
+         * from whether the assessment or item carries PNP/profile material.
          */
         enforcement: "on" | "off";
     };
+    /**
+     * Mounted items whose settings this decision leaves out: set for a section-
+     * or assessment-level toolbar. A tool on that toolbar that one of them
+     * restricts or requires gets a `tool-policy.itemSettingNotApplied`
+     * diagnostic.
+     */
+    unappliedItems?: readonly PnpPolicyItem[];
     customSources: readonly PolicySource[];
     /** Stable identifier used as the provenance `contextId`. */
     contextId: string;
 }
 export declare function composeDecision(inputs: ComposeDecisionInputs): ToolPolicyDecision;
+/**
+ * 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 declare function overrideBlockedDiagnostic(toolId: string, rule: OverrideBlockedDetails["rule"], level?: ToolPlacementLevel): ToolPolicyDiagnostic;
+/**
+ * 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 declare function unknownSupportIdDiagnostic(supportId: string, origins: readonly PnpPolicySourceRule[]): ToolPolicyDiagnostic;