@pie-players/pie-assessment-toolkit 0.3.75 → 1.0.0-beta.1

package/dist/index.d.ts

@@ -16,38 +16,38 @@ export { connectToolRuntimeContext, dispatchCrossBoundaryEvent, } from "./runtim
 export type { AccessibilityCatalogResolverApi, ElementToolStateStoreApi, HighlightCoordinatorApi, ToolCoordinatorApi, ToolkitCoordinatorApi, SpeakOptions, TtsServiceApi, ToolState, ToolStateFilter, } from "./services/interfaces.js";
 export type { CatalogCardForm, CatalogChangeEvent, CatalogChangeListener, CatalogChangeReason, CatalogLookupContext, CatalogLookupOptions, CatalogOwnerCard, CatalogOwnerRegistration, CatalogOwnerSnapshot, CatalogOwnerView, CatalogStatistics, CatalogType, ResolvedCatalog, } from "./services/AccessibilityCatalogResolver.js";
 export { AccessibilityCatalogResolver } from "./services/AccessibilityCatalogResolver.js";
-export { ElementToolStateStore } from "./services/ElementToolStateStore.js";
+export { type ElementIdComponents, ElementToolStateStore, } from "./services/ElementToolStateStore.js";
 export type { Annotation } from "./services/HighlightCoordinator.js";
 export { HighlightColor, HighlightCoordinator, HighlightType, } from "./services/HighlightCoordinator.js";
 export type { SerializedRange } from "./services/RangeSerializer.js";
 export type { I18nProvider, InterpolationValues, LocaleCode, MessageKeyInput, PluralOptions, TextDirection, } from "@pie-players/pie-players-shared/i18n";
-export type { ResolvedToolContext, ToolbarContext, ToolContextResolver, ToolContextResolverContext, ToolContextResolverMap, ToolContextResolverResult, ToolActivation, ToolContentDependency, ToolContentDependencyContext, ToolModuleLoader, ToolRegistryChangeEvent, ToolRegistryChangeKind, ToolRegistryChangeListener, ToolSingletonScope, ToolSurfaceRenderContext, ToolSurfaceRenderResult, ToolSurfaceServices, ToolToolbarButtonDefinition, ToolToolbarRenderResult, ToolRegistration, } from "./services/ToolRegistry.js";
+export type { ResolvedToolContext, ToolbarContext, ToolContextResolver, ToolContextResolverContext, ToolContextResolverMap, ToolContextResolverResult, ToolActivation, ToolCallbackFailureHandler, ToolContentDependency, ToolContentDependencyContext, ToolModuleLoader, ToolRegistryChangeEvent, ToolRegistryChangeKind, ToolRegistryChangeListener, ToolSingletonScope, ToolSurfaceRenderContext, ToolSurfaceRenderResult, ToolSurfaceServices, ToolToolbarButtonDefinition, ToolToolbarRenderResult, ToolRegistration, } from "./services/ToolRegistry.js";
 export { ToolRegistry } from "./services/ToolRegistry.js";
 export type { ToolOpenRequest, ToolRequestTarget, } from "./services/tool-request.js";
 export type { AssessmentToolContext, BaseToolContext, ElementToolContext, ItemToolContext, PassageToolContext, RubricToolContext, SectionToolContext, ToolContext, ToolLevel, } from "./services/tool-context.js";
-export { hasReadableText } from "./services/tool-context.js";
+export { hasReadableText, hasSpokenContent, } from "./services/tool-context.js";
 export type { CreateToolsConfigArgs } from "./services/create-tools-config.js";
 export { createToolsConfig } from "./services/create-tools-config.js";
 export type { ToolComponentFactory, ToolComponentFactoryMap, ToolComponentOverrides, ToolTagMap, } from "./tools/tool-tag-map.js";
 export type { ExtractionResult } from "./services/SSMLExtractor.js";
 export { SSMLExtractor } from "./services/SSMLExtractor.js";
-export { ToolCoordinator, ZIndexLayer } from "./services/ToolCoordinator.js";
+export { ZIndexLayer } from "./services/ToolCoordinator.js";
 export type { ProviderLifecycleContext, SectionControllerContext, SectionControllerEvent, SectionControllerEventType, SectionItemEvent, SectionItemEventType, SectionControllerFactoryDefaults, SectionControllerHandle, SectionControllerKey, SectionScopedEvent, SectionScopedEventType, SectionSessionPersistenceConfig, SectionItemEventSubscriptionArgs, SectionScopedEventSubscriptionArgs, SectionEventSubscriptionArgs, SectionSessionPersistenceStrategy, SectionControllerLoadedRenderable, SectionControllerRuntimeState, SectionControllerSessionState, SectionPersistenceFactoryDefaults, ToolkitCoordinatorConfig, ToolkitCoordinatorHooks, ToolkitErrorContext, } from "./services/ToolkitCoordinator.js";
 export { ToolkitCoordinator } from "./services/ToolkitCoordinator.js";
 export type { CalculatorToolProviderConfig, CanonicalToolsConfig, ToolPlacementConfig, ToolPlacementLevel, ToolPolicyConfig, ToolProvidersConfig, ToolsConfigInput, TextToSpeechToolProviderConfig, } from "./services/tools-config-normalizer.js";
-export type { FrameworkErrorKind, FrameworkErrorModel, FrameworkErrorScope, FrameworkErrorSeverity, } from "./services/framework-error.js";
+export type { FrameworkErrorCohort, FrameworkErrorKind, FrameworkErrorModel, FrameworkErrorScope, FrameworkErrorSeverity, } from "./services/framework-error.js";
 export { frameworkErrorFromUnknown, toFrameworkErrorModel, } from "./services/framework-error.js";
 export type { FrameworkErrorListener } from "./services/framework-error-bus.js";
+export type { ToolFailurePhase } from "./services/tool-failure.js";
 export type { ToolConfigDiagnostic, ToolConfigDiagnosticSeverity, ToolConfigStrictness, ToolConfigValidationResult, } from "./services/tool-config-validation.js";
 export type { ToolbarButtonItem, ToolbarItem, ToolbarItemBase, ToolbarLinkItem, } from "./services/toolbar-items.js";
 export type { ToolScopeLevel } from "./services/tool-instance-id.js";
 export { createScopedToolId } from "./services/tool-instance-id.js";
-export type { TTSConfig } from "./services/TTSService.js";
 export { PlaybackState, TTSService } from "./services/TTSService.js";
 export { BrowserTTSProvider } from "./services/tts/browser-provider.js";
 export type { SREMathSpeechOptions } from "./services/tts/math-speech.js";
 export type { TTSLayoutMode, TTSRuntimeSettings, TTSSpeedOption, TTSSpeedOptionConfig, } from "./services/tts-runtime-config.js";
-export type { ITTSProvider, ITTSProviderImplementation, TTSSpeechSegment, TTSProviderCapabilities, } from "@pie-players/pie-tts";
+export type { ITTSProvider, ITTSProviderImplementation, TTSConfig, TTSSpeechSegment, TTSProviderCapabilities, } from "@pie-players/pie-tts";
 export type { TestAttemptItemSession, TestAttemptSession, TestAttemptSessionNavigationState, TestAttemptSessionRealization, } from "./attempt/TestSession.js";
 export { createNewTestAttemptSession, setCurrentPosition, toItemSessionsRecord, upsertItemSessionFromPieSessionChange, upsertVisitedItem, } from "./attempt/TestSession.js";
 export type { AssessmentSession, AssessmentSectionSessionState, AssessmentSessionNavigationState, AssessmentSessionRealization, } from "./attempt/AssessmentSession.js";

package/dist/index.js

@@ -15,25 +15,19 @@ export { createShellEventBridge, } from "./runtime/shell-event-bridge.js";
 export { connectToolRuntimeContext, dispatchCrossBoundaryEvent, } from "./runtime/tool-host-contract.js";
 export { AccessibilityCatalogResolver } from "./services/AccessibilityCatalogResolver.js";
 // Element Tool State Store (Element-level ephemeral tool state)
-export { ElementToolStateStore } from "./services/ElementToolStateStore.js";
+export { ElementToolStateStore, } from "./services/ElementToolStateStore.js";
 export { HighlightColor, HighlightCoordinator, HighlightType, } from "./services/HighlightCoordinator.js";
 export { ToolRegistry } from "./services/ToolRegistry.js";
-export { hasReadableText } from "./services/tool-context.js";
+export { hasReadableText, hasSpokenContent, } from "./services/tool-context.js";
 export { createToolsConfig } from "./services/create-tools-config.js";
 export { SSMLExtractor } from "./services/SSMLExtractor.js";
 // Tool Coordinator
-export { ToolCoordinator, ZIndexLayer } from "./services/ToolCoordinator.js";
+export { ZIndexLayer } from "./services/ToolCoordinator.js";
 export { ToolkitCoordinator } from "./services/ToolkitCoordinator.js";
 export { frameworkErrorFromUnknown, toFrameworkErrorModel, } from "./services/framework-error.js";
 export { createScopedToolId } from "./services/tool-instance-id.js";
+// Text-to-Speech Service
 export { PlaybackState, TTSService } from "./services/TTSService.js";
 export { BrowserTTSProvider } from "./services/tts/browser-provider.js";
 export { createNewTestAttemptSession, setCurrentPosition, toItemSessionsRecord, upsertItemSessionFromPieSessionChange, upsertVisitedItem, } from "./attempt/TestSession.js";
 export { createNewAssessmentSession, setCurrentSectionPosition, upsertSectionSession, } from "./attempt/AssessmentSession.js";
-// Section Player - Use @pie-players/pie-section-player web component
-// ============================================================================
-// Shared Components
-// ============================================================================
-// ItemToolBar custom element registration helper is exported via package.json exports field
-// Import using: import '@pie-players/pie-assessment-toolkit/components/item-toolbar-element';
-// PieAssessmentToolkit custom element registration helper is exported via package.json exports field

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

@@ -36,7 +36,7 @@ export interface PolicySourceProvenanceEntry {
      * Custom precedence value used for the decision log. Defaults to
      * `100 + sourceIndex` (engine-assigned) when `undefined`. Sources
      * MAY override only if they know what they are doing — overriding
-     * to a value `<= 6` lets the source masquerade as a PNP/profile rule and
+     * to a value `<= 8` lets the source masquerade as a PNP/profile rule and
      * is generally a bug.
      */
     precedence?: number;

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

@@ -14,13 +14,13 @@
  * connectedCallback. `ToolkitCoordinator` owns the instance, and
  * `<pie-item-toolbar>` reads its decisions through the coordinator.
  */
-import type { AssessmentEntity, ItemSettings } from "@pie-players/pie-players-shared/types";
-import type { CanonicalToolsConfig, ToolPlacementLevel } from "../../services/tools-config-normalizer.js";
+import type { AssessmentEntity, ItemSettings, ToolParametersFor } from "@pie-players/pie-players-shared/types";
+import type { CanonicalToolsConfig, PnpEnforcementMode, ToolPlacementLevel } from "../../services/tools-config-normalizer.js";
 import type { ToolRegistry } from "../../services/ToolRegistry.js";
-import type { ToolPolicyDecision, ToolPolicyDecisionRequest, ToolScope } from "./decision-types.js";
+import type { ToolPolicyDecision, ToolPolicyDecisionRequest, ToolPolicyDiagnostic, ToolScope } from "./decision-types.js";
 import type { PolicySource } from "./PolicySource.js";
 import type { FeaturePolicyDecision } from "./feature-decision.js";
-export type PnpEnforcementMode = "on" | "off";
+export type { PnpEnforcementMode };
 export interface ToolPolicyEngineInputs {
     tools?: CanonicalToolsConfig | null;
     assessment?: AssessmentEntity | null;
@@ -29,7 +29,7 @@ export interface ToolPolicyEngineInputs {
      * resolves per decision through {@link resolveDefaultPnpEnforcement}: `"on"`
      * when the bound `assessment` carries PNP/profile policy material (PNP,
      * district policy, test administration), and for a decision scoped to an item
-     * also when that item's settings carry required/restricted/parameters;
+     * also when that item's settings require or restrict a tool;
      * `"off"` otherwise. `tests/policy/pnp-default-on.test.ts` locks the rule.
      *
      * Hosts that want to force a mode pass `"on"` or `"off"`
@@ -44,6 +44,12 @@ export interface ToolPolicyEngineArgs {
     customSources?: readonly PolicySource[];
     /** Stable context label used in provenance trails. Defaults to "tool-policy". */
     contextId?: string;
+    /**
+     * Whether the host may leave the assessment unbound without that being a
+     * misconfiguration; see {@link ResolvedEngineInputs.assessmentExpected}.
+     * Defaults to `false`.
+     */
+    assessmentOptional?: boolean;
 }
 export interface ToolPolicyChangeEvent {
     /**
@@ -65,11 +71,26 @@ export interface ResolvedEngineInputs {
     pnpEnforcement: PnpEnforcementMode;
     /** The host's override of auto-mode, or `null` in auto-mode. */
     pnpEnforcementOverride: PnpEnforcementMode | null;
+    /**
+     * Whether an unbound assessment is a misconfiguration: always, unless the
+     * engine was built `assessmentOptional`, and then only while enforcement is
+     * overridden `"on"`.
+     */
+    assessmentExpected: boolean;
+    /**
+     * Conflicts in the inputs themselves, independent of any decision: a
+     * `tool-policy.unknownSupportId` for each id the assessment or a mounted
+     * item's settings name that no registered tool carries. Recomputed when the
+     * assessment, an item's settings or the registry's tools change.
+     */
+    diagnostics: readonly ToolPolicyDiagnostic[];
 }
 export type ToolPolicyChangeListener = (event: ToolPolicyChangeEvent) => void;
 export declare class ToolPolicyEngine {
     private toolRegistry;
+    private unsubscribeRegistry;
     private readonly contextId;
+    private readonly assessmentOptional;
     private pnpPolicySource;
     private readonly customSources;
     private readonly listeners;
@@ -81,6 +102,7 @@ export declare class ToolPolicyEngine {
      * see {@link registerItemSettings}.
      */
     private readonly itemSettings;
+    private inputDiagnostics;
     private disposed;
     constructor(args: ToolPolicyEngineArgs);
     /**
@@ -109,8 +131,13 @@ export declare class ToolPolicyEngine {
      * 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: string): boolean;
+    grantsFeatureAnywhere(featureId: string, options?: {
+        enforced?: boolean;
+    }): boolean;
     /**
      * 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
@@ -148,7 +175,7 @@ export declare class ToolPolicyEngine {
      * `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: string, scope?: ToolScope): FeaturePolicyDecision;
+    decideFeature<K extends string>(featureId: K, scope?: ToolScope): FeaturePolicyDecision<ToolParametersFor<K>>;
     /**
      * The host gates that hold for a feature id, or `null` when none fires.
      *
@@ -195,6 +222,18 @@ export declare class ToolPolicyEngine {
     /** The settings that apply to `itemId`: its newest registration's. */
     private itemSettingsFor;
     private emitIfItemSettingsChanged;
+    /**
+     * Recompute {@link ResolvedEngineInputs.diagnostics} from the bound
+     * assessment, every mounted item's settings and the registry. Returns
+     * whether they changed.
+     */
+    private refreshInputDiagnostics;
+    /**
+     * 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.
+     */
+    private watchRegistry;
     /**
      * The registered item an item scope names, by its canonical id. A scope
      * of any other level names none.

package/dist/policy/core/ToolPolicyEngine.js

@@ -16,8 +16,9 @@
  */
 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 { resolveToolParameters } from "./tool-parameters.js";
 import { structurallyEqual } from "../../utils/structural-equality.js";
 import { PnpPolicySource, } from "../sources/PnpPolicySource.js";
 const DEFAULT_TOOLS = normalizeToolsConfig({
@@ -27,7 +28,9 @@ const DEFAULT_TOOLS = normalizeToolsConfig({
 });
 export class ToolPolicyEngine {
     toolRegistry;
+    unsubscribeRegistry;
     contextId;
+    assessmentOptional;
     pnpPolicySource;
     customSources;
     listeners = new Set();
@@ -39,16 +42,20 @@ export class ToolPolicyEngine {
      * 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.pnpEnforcementOverride = inputs.pnpEnforcement ?? null;
+        this.refreshInputDiagnostics();
+        this.unsubscribeRegistry = this.watchRegistry();
     }
     /**
      * Resolve the visible tool set for a given placement level and
@@ -98,11 +105,18 @@ export class ToolPolicyEngine {
      * 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) {
-        if (this.decideFeature(featureId).granted)
+    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;
             }
@@ -172,14 +186,15 @@ export class ToolPolicyEngine {
         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,
-            item: this.itemForScope(scope),
+            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.
@@ -239,9 +254,12 @@ export class ToolPolicyEngine {
         }
         if ("assessment" in patch) {
             const next = patch.assessment ?? null;
-            if (!structurallyEqual(this.assessment, next))
-                changed = true;
+            const assessmentChanged = !structurallyEqual(this.assessment, next);
             this.assessment = next;
+            if (assessmentChanged) {
+                changed = true;
+                this.refreshInputDiagnostics();
+            }
         }
         if ("pnpEnforcement" in patch) {
             const next = patch.pnpEnforcement ?? null;
@@ -264,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) {
@@ -278,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) {
@@ -302,6 +323,7 @@ export class ToolPolicyEngine {
         if (this.disposed)
             return;
         this.disposed = true;
+        this.unsubscribeRegistry();
         this.emit({
             reason: "disposed",
             inputs: this.snapshotInputs(),
@@ -316,6 +338,8 @@ export class ToolPolicyEngine {
             assessment: this.assessment,
             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. */
@@ -333,8 +357,41 @@ export class ToolPolicyEngine {
     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.

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

@@ -52,7 +52,7 @@ export declare function composeDecision(inputs: ComposeDecisionInputs): ToolPoli
 export declare function overrideBlockedDiagnostic(toolId: string, rule: OverrideBlockedDetails["rule"], level?: ToolPlacementLevel): ToolPolicyDiagnostic;
 /**
  * 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.
+ * 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[], level?: ToolPlacementLevel): ToolPolicyDiagnostic;
+export declare function unknownSupportIdDiagnostic(supportId: string, origins: readonly PnpPolicySourceRule[]): ToolPolicyDiagnostic;

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

@@ -12,6 +12,7 @@
  * `tests/policy/compose-decision.test.ts` lock the orchestration in.
  */
 import { normalizeToolList, } from "../../services/tools-config-normalizer.js";
+import { resolveToolParameters } from "./tool-parameters.js";
 import { ToolPolicyProvenanceBuilder, } from "./provenance.js";
 export function composeDecision(inputs) {
     const { request, tools, pnpPolicy, customSources, contextId } = inputs;
@@ -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) => {
@@ -134,19 +135,12 @@ export function composeDecision(inputs) {
                 value: decision.value,
             });
         }
-        // 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);
-        });
+        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
@@ -154,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;
+            if (!placement.includes(mandatedToolId) &&
+                placedAtAnyLevel.has(mandatedToolId)) {
                 continue;
-            const flag = pnpPolicyResult.perToolFlags.get(mandatedToolId);
-            const ruleName = flag?.rule ?? "required-tool";
+            }
             const hostGate = detectHostRemovalGate(mandatedToolId, {
-                placement,
+                placedAtAnyLevel,
+                allTools: tools.placement,
                 allowed,
                 blocked,
                 providers: tools.providers,
@@ -181,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({
@@ -288,7 +288,8 @@ export function composeDecision(inputs) {
             toolId,
             required: flag?.required ?? false,
             alwaysAvailable: flag?.alwaysAvailable ?? false,
-            settings: flag?.settings,
+            activateAtInit: flag?.activateAtInit ?? false,
+            parameters: resolveToolParameters(toolId, pnpPolicy.assessment, pnpPolicy.item),
         };
     });
     builder.reconcileFinalStates(survivingIds);
@@ -305,10 +306,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 };
@@ -322,11 +324,11 @@ 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 = {
@@ -337,6 +339,7 @@ const PNP_RULE_FIELDS = {
     "item-requirement": "item settings.requiredTools",
     "district-requirement": "settings.districtPolicy.requiredTools",
     "pnp-support": "personalNeedsProfile.supports",
+    "pnp-activate-at-init": "personalNeedsProfile.activateAtInit",
 };
 /**
  * A `tool-policy.overrideBlocked` diagnostic for a tool a `true` test
@@ -354,14 +357,13 @@ export function overrideBlockedDiagnostic(toolId, rule, level) {
 }
 /**
  * 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.
+ * 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, level) {
+export function unknownSupportIdDiagnostic(supportId, origins) {
     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] },