@pie-players/pie-assessment-toolkit 0.3.65 → 0.3.67

package/dist/index.d.ts

@@ -10,11 +10,11 @@ export type { AssessmentToolkitHostRuntimeContext, AssessmentToolkitRegionScopeC
 export type { TTSHighlightContext, TTSHighlightTargetResolver, TTSHighlightTargetResolverProvider, TTSHighlightTargetResolverRuntime, } from "./services/tts/highlight-target-resolver.js";
 export { assessmentToolkitHostRuntimeContext, assessmentToolkitRegionScopeContext, assessmentToolkitRuntimeContext, assessmentToolkitShellContext, } from "./context/assessment-toolkit-context.js";
 export { connectAssessmentToolkitHostRuntimeContext, connectAssessmentToolkitRegionScopeContext, connectAssessmentToolkitRuntimeContext, connectAssessmentToolkitShellContext, } from "./context/runtime-context-consumer.js";
-export { catalogOwnerContextFor, collectCatalogRegistrations, collectEntityCatalogRegistrations, type CatalogOwnerIdentity, type CatalogRegistration, type CatalogSourceEntity, } from "./runtime/catalog-registration.js";
+export { catalogOwnerContextFor, type CatalogOwnerContext, type CatalogOwnerIdentity, type CatalogOwnerKind, type CatalogSourceEntity, } from "./services/catalog-owner.js";
 export { PIE_INTERNAL_CONTENT_LOADED_EVENT, PIE_INTERNAL_ITEM_SESSION_CHANGED_EVENT, PIE_INTERNAL_ITEM_PLAYER_ERROR_EVENT, PIE_ITEM_SESSION_CHANGED_EVENT, PIE_REGISTER_EVENT, PIE_UNREGISTER_EVENT, type InternalContentLoadedDetail, type InternalItemSessionChangedDetail, type InternalItemPlayerErrorDetail, type ItemSessionChangedDetail, type RuntimeRegistrationDetail, type RuntimeRegistrationKind, } from "./runtime/registration-events.js";
 export { connectToolRegionScopeContext, connectToolRuntimeContext, connectToolShellContext, createCrossBoundaryEvent, dispatchCrossBoundaryEvent, isContextValueDefined, } from "./runtime/tool-host-contract.js";
 export type { AccessibilityCatalogResolverApi, ElementToolStateStoreApi, HighlightCoordinatorApi, I18nServiceApi, ThemeProviderApi, ToolCoordinatorApi, ToolkitCoordinatorApi, TtsServiceApi, ToolState, } from "./services/interfaces.js";
-export type { CatalogCardForm, CatalogChangeEvent, CatalogChangeListener, CatalogChangeReason, CatalogLookupContext, CatalogLookupOptions, CatalogOwnerContext, CatalogOwnerKind, CatalogStatistics, CatalogType, ResolvedCatalog, } from "./services/AccessibilityCatalogResolver.js";
+export type { CatalogCardForm, CatalogChangeEvent, CatalogChangeListener, CatalogChangeReason, CatalogLookupContext, CatalogLookupOptions, CatalogOwnerCard, CatalogOwnerRegistration, CatalogOwnerSnapshot, CatalogOwnerView, CatalogStatistics, CatalogType, ResolvedCatalog, } from "./services/AccessibilityCatalogResolver.js";
 export { AccessibilityCatalogResolver, catalogCardForm, isKnownCatalogType, KNOWN_CATALOG_TYPES, } from "./services/AccessibilityCatalogResolver.js";
 export { ContextVariableStore } from "./services/ContextVariableStore.js";
 export { ElementToolStateStore } from "./services/ElementToolStateStore.js";
@@ -24,7 +24,7 @@ export type { SerializedRange } from "./services/RangeSerializer.js";
 export { RangeSerializer } from "./services/RangeSerializer.js";
 export type { I18nConfig, PluralTranslation, TranslationBundle, } from "./services/I18nService.js";
 export { I18nService } from "./services/I18nService.js";
-export type { ResolvedToolContext, ToolbarContext, ToolContextResolver, ToolContextResolverContext, ToolContextResolverMap, ToolContextResolverResult, ToolActivation, ToolContentDependency, ToolContentDependencyContext, ToolModuleLoader, ToolSingletonScope, ToolSurfaceRenderContext, ToolSurfaceRenderResult, ToolSurfaceServices, ToolToolbarButtonDefinition, ToolToolbarRenderResult, ToolWindowShellAction, ToolWindowShellAlign, ToolWindowShellConfig, ToolWindowShellContentConfig, ToolRegistration, } from "./services/ToolRegistry.js";
+export type { ResolvedToolContext, ToolbarContext, ToolContextResolver, ToolContextResolverContext, ToolContextResolverMap, ToolContextResolverResult, ToolActivation, ToolContentDependency, ToolContentDependencyContext, ToolModuleLoader, ToolRegistryChangeEvent, ToolRegistryChangeKind, ToolRegistryChangeListener, ToolSingletonScope, ToolSurfaceRenderContext, ToolSurfaceRenderResult, ToolSurfaceServices, ToolToolbarButtonDefinition, ToolToolbarRenderResult, ToolWindowShellAction, ToolWindowShellAlign, ToolWindowShellConfig, ToolWindowShellContentConfig, ToolRegistration, } from "./services/ToolRegistry.js";
 export { ToolRegistry } from "./services/ToolRegistry.js";
 export type { AssessmentToolContext, BaseToolContext, ElementToolContext, ItemToolContext, PassageToolContext, RubricToolContext, SectionToolContext, ToolContext, ToolLevel, } from "./services/tool-context.js";
 export { extractTextContent, hasChoiceInteraction, hasMathContent, hasReadableText, isAssessmentContext, isElementContext, isItemContext, isPassageContext, isRubricContext, isSectionContext, } from "./services/tool-context.js";
@@ -53,6 +53,7 @@ export type { ToolConfigDiagnostic, ToolConfigDiagnosticSeverity, ToolConfigStri
 export type { ToolbarButtonItem, ToolbarItem, ToolbarItemBase, ToolbarLinkItem, } from "./services/toolbar-items.js";
 export { isExternalIconUrl, isInlineSvgIcon, isToolbarLinkItem, isValidToolbarItemShape, } from "./services/toolbar-items.js";
 export { normalizeToolsConfig, normalizeToolAlias, normalizeToolList, parseToolList, } from "./services/tools-config-normalizer.js";
+export { isHostDeniedFeature } from "./policy/core/feature-decision.js";
 export { frameworkErrorFromToolConfigValidation, normalizeAndValidateToolsConfig, } from "./services/tool-config-validation.js";
 export type { ParsedToolInstanceId, ToolScopeLevel, } from "./services/tool-instance-id.js";
 export { createScopedToolId, parseScopedToolId, toOverlayToolId, } from "./services/tool-instance-id.js";

package/dist/index.js

@@ -8,7 +8,7 @@
  */
 export { assessmentToolkitHostRuntimeContext, assessmentToolkitRegionScopeContext, assessmentToolkitRuntimeContext, assessmentToolkitShellContext, } from "./context/assessment-toolkit-context.js";
 export { connectAssessmentToolkitHostRuntimeContext, connectAssessmentToolkitRegionScopeContext, connectAssessmentToolkitRuntimeContext, connectAssessmentToolkitShellContext, } from "./context/runtime-context-consumer.js";
-export { catalogOwnerContextFor, collectCatalogRegistrations, collectEntityCatalogRegistrations, } from "./runtime/catalog-registration.js";
+export { catalogOwnerContextFor, } from "./services/catalog-owner.js";
 export { PIE_INTERNAL_CONTENT_LOADED_EVENT, PIE_INTERNAL_ITEM_SESSION_CHANGED_EVENT, PIE_INTERNAL_ITEM_PLAYER_ERROR_EVENT, PIE_ITEM_SESSION_CHANGED_EVENT, PIE_REGISTER_EVENT, PIE_UNREGISTER_EVENT, } from "./runtime/registration-events.js";
 export { connectToolRegionScopeContext, connectToolRuntimeContext, connectToolShellContext, createCrossBoundaryEvent, dispatchCrossBoundaryEvent, isContextValueDefined, } from "./runtime/tool-host-contract.js";
 export { AccessibilityCatalogResolver, catalogCardForm, isKnownCatalogType, KNOWN_CATALOG_TYPES, } from "./services/AccessibilityCatalogResolver.js";
@@ -42,6 +42,7 @@ export { ToolkitCoordinator } from "./services/ToolkitCoordinator.js";
 export { formatFrameworkErrorForConsole, frameworkErrorFromToolConfigDiagnostics, frameworkErrorFromUnknown, toFrameworkErrorModel, } from "./services/framework-error.js";
 export { isExternalIconUrl, isInlineSvgIcon, isToolbarLinkItem, isValidToolbarItemShape, } from "./services/toolbar-items.js";
 export { normalizeToolsConfig, normalizeToolAlias, normalizeToolList, parseToolList, } from "./services/tools-config-normalizer.js";
+export { isHostDeniedFeature } from "./policy/core/feature-decision.js";
 export { frameworkErrorFromToolConfigValidation, normalizeAndValidateToolsConfig, } from "./services/tool-config-validation.js";
 export { createScopedToolId, parseScopedToolId, toOverlayToolId, } from "./services/tool-instance-id.js";
 export { PlaybackState, TTSService } from "./services/TTSService.js";

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

@@ -1,6 +1,6 @@
 /**
- * Custom `PolicySource` extension point (M8 — see
- * `.cursor/plans/m8-design.md` § 5).
+ * Custom `PolicySource` extension point. See
+ * `docs/tools-and-accomodations/architecture.md`.
  *
  * Custom sources run in step 6 of the composition pipeline — *after*
  * placement membership, provider veto, host policy, and PNP/profile gates.

package/dist/policy/core/PolicySource.js

@@ -1,6 +1,6 @@
 /**
- * Custom `PolicySource` extension point (M8 — see
- * `.cursor/plans/m8-design.md` § 5).
+ * Custom `PolicySource` extension point. See
+ * `docs/tools-and-accomodations/architecture.md`.
  *
  * Custom sources run in step 6 of the composition pipeline — *after*
  * placement membership, provider veto, host policy, and PNP/profile gates.

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

@@ -1,6 +1,6 @@
 /**
- * Tool Policy Engine — facade class (M8 — see
- * `.cursor/plans/m8-design.md` § 2).
+ * Tool Policy Engine — facade class. See
+ * `docs/tools-and-accomodations/architecture.md`.
  *
  * Wraps `composeDecision(...)` with engine-instance state:
  *   - bound inputs (`tools`, `assessment`, `currentItemRef`, ...)
@@ -33,7 +33,7 @@ export interface ToolPolicyEngineInputs {
      * `assessment` and `currentItemRef`: `"on"` if they carry any
      * PNP/profile policy material (PNP, district policy, test
      * administration, item-level required/restricted/parameters),
-     * `"off"` otherwise. See `.cursor/plans/m8-design.md` F2.
+     * `"off"` otherwise. `tests/policy/pnp-default-on.test.ts` locks the rule.
      *
      * Hosts that want to force a mode pass `"on"` or `"off"`
      * explicitly. Embedded under `<pie-section-player-*>` the preferred
@@ -107,8 +107,24 @@ export declare class ToolPolicyEngine {
      * whenever profile material exists, so this only diverges for a host that
      * explicitly forces `"off"` while supplying a profile that grants the
      * feature — and there, honouring the profile is the safer failure.
+     *
+     * 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}.
      */
     decideFeature(featureId: string): FeaturePolicyDecision;
+    /**
+     * The host gates that hold for a feature id, or `null` when none fires.
+     *
+     * `policy.allowed` / `policy.blocked` name capabilities, not placements, so
+     * they are the one part of the host pipeline that is meaningful without a
+     * placement level — and the only lever a host has over a capability that
+     * renders as its own surface, since a `region` capability is rejected from
+     * `tools.placement` by configuration validation. `provider-disabled` and
+     * `placement-membership` are deliberately not applied: both are statements
+     * about a toolbar the feature was never on.
+     */
+    private hostFeatureGate;
     /**
      * Convenience wrapper for hosts that just want the visible tool
      * IDs. Equivalent to `decide(...).visibleTools.map(e => e.toolId)`.

package/dist/policy/core/ToolPolicyEngine.js

@@ -1,6 +1,6 @@
 /**
- * Tool Policy Engine — facade class (M8 — see
- * `.cursor/plans/m8-design.md` § 2).
+ * Tool Policy Engine — facade class. See
+ * `docs/tools-and-accomodations/architecture.md`.
  *
  * Wraps `composeDecision(...)` with engine-instance state:
  *   - bound inputs (`tools`, `assessment`, `currentItemRef`, ...)
@@ -16,8 +16,8 @@
  * PR 1 ships the engine *without callers*. PR 2 wires it into
  * `ToolkitCoordinator`. PR 3 switches `<pie-item-toolbar>` over.
  */
-import { normalizeToolsConfig } from "../../services/tools-config-normalizer.js";
-import { interpretFeatureResult } from "./feature-decision.js";
+import { normalizeToolList, normalizeToolsConfig, } from "../../services/tools-config-normalizer.js";
+import { hostFeatureDenial, interpretFeatureResult, } from "./feature-decision.js";
 import { composeDecision } from "./compose-decision.js";
 import { resolveDefaultPnpEnforcement } from "./pnp-policy-inputs.js";
 import { PnpPolicySource } from "../sources/PnpPolicySource.js";
@@ -104,13 +104,47 @@ export class ToolPolicyEngine {
      * whenever profile material exists, so this only diverges for a host that
      * explicitly forces `"off"` while supplying a profile that grants the
      * feature — and there, honouring the profile is the safer failure.
+     *
+     * 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}.
      */
     decideFeature(featureId) {
         this.assertNotDisposed();
+        const hostDenial = this.hostFeatureGate(featureId);
+        if (hostDenial)
+            return hostDenial;
         return interpretFeatureResult(featureId, this.pnpPolicySource.resolveFeature(featureId, {
             assessment: this.assessment ?? undefined,
             currentItemRef: this.currentItemRef ?? undefined,
-        }));
+        }), 
+        // `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 });
+    }
+    /**
+     * The host gates that hold for a feature id, or `null` when none fires.
+     *
+     * `policy.allowed` / `policy.blocked` name capabilities, not placements, so
+     * they are the one part of the host pipeline that is meaningful without a
+     * placement level — and the only lever a host has over a capability that
+     * renders as its own surface, since a `region` capability is rejected from
+     * `tools.placement` by configuration validation. `provider-disabled` and
+     * `placement-membership` are deliberately not applied: both are statements
+     * about a toolbar the feature was never on.
+     */
+    hostFeatureGate(featureId) {
+        const context = { assessmentBound: this.assessment !== null };
+        const blocked = normalizeToolList(this.tools.policy.blocked);
+        if (blocked.includes(featureId)) {
+            return hostFeatureDenial(featureId, "host-blocked", blocked, context);
+        }
+        const allowed = normalizeToolList(this.tools.policy.allowed);
+        if (allowed.length > 0 && !allowed.includes(featureId)) {
+            return hostFeatureDenial(featureId, "host-allowlist", allowed, context);
+        }
+        return null;
     }
     /**
      * Convenience wrapper for hosts that just want the visible tool

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

@@ -1,5 +1,6 @@
 /**
- * Compose-decision pipeline (M8 — see `.cursor/plans/m8-design.md` § 3).
+ * Compose-decision pipeline. See
+ * `docs/tools-and-accomodations/architecture.md`.
  *
  * Pure function: given a decision request, the host's tools config,
  * an optional PNP policy source, and the registered custom sources, returns
@@ -7,7 +8,7 @@
  * mutable state, and never reaches into Svelte / DOM — that is the
  * `ToolPolicyEngine` class's job.
  *
- * The six steps below mirror the design doc exactly. The tests in
+ * The tests in
  * `tests/policy/compose-decision.test.ts` lock the orchestration in.
  */
 import type { AssessmentEntity, AssessmentItemRef } from "@pie-players/pie-players-shared/types";

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

@@ -1,5 +1,6 @@
 /**
- * Compose-decision pipeline (M8 — see `.cursor/plans/m8-design.md` § 3).
+ * Compose-decision pipeline. See
+ * `docs/tools-and-accomodations/architecture.md`.
  *
  * Pure function: given a decision request, the host's tools config,
  * an optional PNP policy source, and the registered custom sources, returns
@@ -7,7 +8,7 @@
  * mutable state, and never reaches into Svelte / DOM — that is the
  * `ToolPolicyEngine` class's job.
  *
- * The six steps below mirror the design doc exactly. The tests in
+ * The tests in
  * `tests/policy/compose-decision.test.ts` lock the orchestration in.
  */
 import { normalizeToolList, } from "../../services/tools-config-normalizer.js";

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

@@ -6,8 +6,8 @@
  * composition pipeline that produces the response, lives in sibling
  * modules.
  *
- * See `.cursor/plans/m8-design.md` § 2 for the engine shape, § 3 for
- * the composition rule, and § 4 for the provenance contract.
+ * `docs/tools-and-accomodations/architecture.md` covers the engine shape,
+ * the composition rule, and the provenance contract.
  */
 import type { ToolPlacementLevel } from "../../services/tools-config-normalizer.js";
 import type { ToolContext, ToolLevel } from "../../services/tool-context.js";

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

@@ -6,7 +6,7 @@
  * composition pipeline that produces the response, lives in sibling
  * modules.
  *
- * See `.cursor/plans/m8-design.md` § 2 for the engine shape, § 3 for
- * the composition rule, and § 4 for the provenance contract.
+ * `docs/tools-and-accomodations/architecture.md` covers the engine shape,
+ * the composition rule, and the provenance contract.
  */
 export {};

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

@@ -15,10 +15,21 @@
  * feature id?* Whether the capability has anything to show is a separate,
  * independent check owned by its renderer — for signing, whether a matching
  * catalog card exists. Both are required; neither implies the other.
+ *
+ * A denial carries `assessmentBound`, because "nobody asked for this" and
+ * "nothing was bound to ask against" are the same verdict for different
+ * 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";
+/**
+ * A feature verdict comes from one of the six 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.
+ */
+export type FeaturePolicyRule = PnpPolicySourceRule | "host-allowlist" | "host-blocked";
 export interface FeaturePolicyDecision {
     /** The PNP/AfA support id that was evaluated (e.g. `"signLanguage"`). */
     featureId: string;
@@ -30,11 +41,29 @@ export interface FeaturePolicyDecision {
     granted: boolean;
     action: ToolPolicyResolutionDecision["action"];
     /** Which precedence rule produced the verdict. */
-    rule: PnpPolicySourceRule;
-    precedence: 1 | 2 | 3 | 4 | 5 | 6;
+    rule: FeaturePolicyRule;
+    precedence: 0 | 1 | 2 | 3 | 4 | 5 | 6;
     sourceType: ToolPolicySourceType;
     /** Human-readable explanation, suitable for a policy debugger. */
     reason: string;
+    /**
+     * Whether an assessment was bound when this was decided.
+     *
+     * `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.
+     *
+     * Granting is unaffected either way: an unbound host with no item mandate still
+     * gets `granted: false`, since an accommodation requires a documented need and
+     * an absent profile documents nothing.
+     *
+     * A bound assessment carrying no profile material is deliberately `true`: a
+     * test that grants nobody an accommodation is a legitimate configuration,
+     * while never binding one cannot be.
+     */
+    assessmentBound: boolean;
     /**
      * `true` when the grant is a mandate (item or district `requiredTools`)
      * rather than a student-profile support.
@@ -47,6 +76,30 @@ export interface FeaturePolicyDecision {
      */
     parameters?: unknown;
 }
+/** What the engine knows that a single support-id resolution does not. */
+export interface FeatureDecisionContext {
+    /** Whether the engine has an assessment bound. */
+    assessmentBound: boolean;
+}
+/**
+ * A host gate denied the feature outright, so no policy source was consulted.
+ *
+ * `precedence: 0` and the two `host-*` rules are the same values
+ * `composeDecision(...)` records for the placement-scoped path, so a debugger
+ * reads one vocabulary for both. `assessmentBound` is still reported: a host
+ * blocklist is a verdict whether or not an assessment was bound, and the flag
+ * only ever qualifies a *policy* denial.
+ */
+export declare function hostFeatureDenial(featureId: string, rule: "host-allowlist" | "host-blocked", hostValue: readonly string[], context: FeatureDecisionContext): FeaturePolicyDecision;
+/**
+ * Whether a host gate produced the verdict, rather than a policy source.
+ *
+ * The distinction is load-bearing for a content-dependent capability that
+ * declares `resolvesWithoutGrant`: an absent grant is a case it is allowed to
+ * answer from the content alone, while a host denial is the host's off switch
+ * and nothing may reopen it.
+ */
+export declare function isHostDeniedFeature(decision: Pick<FeaturePolicyDecision, "rule"> | null | undefined): boolean;
 /**
  * Interpret a single-feature `PnpPolicySource.resolveFeature(...)` result.
  *
@@ -54,4 +107,4 @@ export interface FeaturePolicyDecision {
  * exactly one decision and at most one flags entry — no mapped-tool-id
  * bookkeeping is needed to read it back out.
  */
-export declare function interpretFeatureResult(featureId: string, result: PnpPolicyResult): FeaturePolicyDecision;
+export declare function interpretFeatureResult(featureId: string, result: PnpPolicyResult, context: FeatureDecisionContext): FeaturePolicyDecision;

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

@@ -15,7 +15,55 @@
  * feature id?* Whether the capability has anything to show is a separate,
  * independent check owned by its renderer — for signing, whether a matching
  * catalog card exists. Both are required; neither implies the other.
+ *
+ * A denial carries `assessmentBound`, because "nobody asked for this" and
+ * "nothing was bound to ask against" are the same verdict for different
+ * reasons, and only the second is a defect.
+ */
+/**
+ * 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.
  */
+const unboundAssessmentReason = (featureId) => `No assessment is bound, so no policy source could grant "${featureId}"`;
+/**
+ * A host gate denied the feature outright, so no policy source was consulted.
+ *
+ * `precedence: 0` and the two `host-*` rules are the same values
+ * `composeDecision(...)` records for the placement-scoped path, so a debugger
+ * reads one vocabulary for both. `assessmentBound` is still reported: a host
+ * blocklist is a verdict whether or not an assessment was bound, and the flag
+ * only ever qualifies a *policy* denial.
+ */
+export function hostFeatureDenial(featureId, rule, hostValue, context) {
+    return {
+        featureId,
+        granted: false,
+        action: "block",
+        rule,
+        precedence: 0,
+        sourceType: "host",
+        reason: rule === "host-blocked"
+            ? "Listed in tools.policy.blocked"
+            : `Not listed in tools.policy.allowed (${hostValue.join(", ")})`,
+        required: false,
+        assessmentBound: context.assessmentBound,
+    };
+}
+/**
+ * Whether a host gate produced the verdict, rather than a policy source.
+ *
+ * The distinction is load-bearing for a content-dependent capability that
+ * declares `resolvesWithoutGrant`: an absent grant is a case it is allowed to
+ * answer from the content alone, while a host denial is the host's off switch
+ * and nothing may reopen it.
+ */
+export function isHostDeniedFeature(decision) {
+    return (decision?.rule === "host-blocked" || decision?.rule === "host-allowlist");
+}
 /**
  * Interpret a single-feature `PnpPolicySource.resolveFeature(...)` result.
  *
@@ -23,18 +71,27 @@
  * exactly one decision and at most one flags entry — no mapped-tool-id
  * bookkeeping is needed to read it back out.
  */
-export function interpretFeatureResult(featureId, result) {
+export function interpretFeatureResult(featureId, result, context) {
     const decision = result.decisions[0];
     const flags = Array.from(result.perToolFlags.values())[0];
+    const granted = decision?.action === "enable";
+    const reason = decision?.reason ?? `Feature "${featureId}" not configured`;
     return {
         featureId,
-        granted: decision?.action === "enable",
+        granted,
         action: decision?.action ?? "skip",
         rule: decision?.rule ?? "pnp-support",
         precedence: decision?.precedence ?? 6,
         sourceType: decision?.sourceType ?? "system",
-        reason: decision?.reason ?? `Feature "${featureId}" not configured`,
+        // 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.
+        reason: context.assessmentBound || granted
+            ? reason
+            : unboundAssessmentReason(featureId),
         required: Boolean(flags?.required),
         parameters: flags?.settings,
+        assessmentBound: context.assessmentBound,
     };
 }

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

@@ -1,6 +1,6 @@
 /**
- * PNP/profile policy input detection (M8 PR 4 — see `.cursor/plans/m8-design.md` F2 and
- * `.cursor/plans/m8-implementation-plan.md` § PR 4).
+ * 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:

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

@@ -1,6 +1,6 @@
 /**
- * PNP/profile policy input detection (M8 PR 4 — see `.cursor/plans/m8-design.md` F2 and
- * `.cursor/plans/m8-implementation-plan.md` § PR 4).
+ * 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:

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

@@ -1,5 +1,8 @@
 /**
- * Tool Policy Provenance (M8 — see `.cursor/plans/m8-design.md` § 4).
+ * Tool Policy Provenance.
+ *
+ * Precedence and the rule vocabulary are documented in
+ * `docs/tools-and-accomodations/architecture.md`.
  *
  * Tracks decisions from every Pass-1 contributor: host placement, host policy,
  * provider veto, PNP/profile gates, and custom policy sources.

package/dist/policy/core/provenance.js

@@ -1,5 +1,8 @@
 /**
- * Tool Policy Provenance (M8 — see `.cursor/plans/m8-design.md` § 4).
+ * Tool Policy Provenance.
+ *
+ * Precedence and the rule vocabulary are documented in
+ * `docs/tools-and-accomodations/architecture.md`.
  *
  * Tracks decisions from every Pass-1 contributor: host placement, host policy,
  * provider veto, PNP/profile gates, and custom policy sources.

package/dist/policy/engine.d.ts

@@ -21,7 +21,7 @@
  */
 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 type { FeaturePolicyDecision } from "./core/feature-decision.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 { PolicySource, PolicySourceDecisionContext, PolicySourceProvenanceEntry, PolicySourceResult, } from "./core/PolicySource.js";
 export type { PolicySourceTag, PnpPolicySourceRule, PnpPolicySourceTag, CustomPolicySourceTag, } from "./core/policy-source-tag.js";

package/dist/policy/engine.js

@@ -21,3 +21,4 @@
  */
 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,7 @@
 /**
  * PNP Policy Source for the M8 engine
- * (see `.cursor/plans/m8-design.md` § 3 step 5 and § 5).
+ * (see
+ * `docs/tools-and-accomodations/architecture.md`).
  *
  * This source applies the PNP/profile precedence rules as a `(candidates, pnpPolicyInputs) →
  * (refinedCandidates, perToolFlags, mandates, decisions)` function the

package/dist/policy/sources/PnpPolicySource.js

@@ -1,6 +1,7 @@
 /**
  * PNP Policy Source for the M8 engine
- * (see `.cursor/plans/m8-design.md` § 3 step 5 and § 5).
+ * (see
+ * `docs/tools-and-accomodations/architecture.md`).
  *
  * This source applies the PNP/profile precedence rules as a `(candidates, pnpPolicyInputs) →
  * (refinedCandidates, perToolFlags, mandates, decisions)` function the

package/dist/runtime/core/engine-transition.js

@@ -227,7 +227,9 @@ export function transition(state, input) {
                     lastFrameworkError: input.error,
                     readinessSignals: {
                         ...state.readinessSignals,
-                        runtimeError: true,
+                        runtimeError: input.error.recoverable === true
+                            ? state.readinessSignals.runtimeError
+                            : true,
                     },
                 },
                 outputs: [{ kind: "framework-error", error: input.error }],

package/dist/services/AccessibilityCatalogResolver.d.ts

@@ -1,15 +1,38 @@
 import type { AccessibilityCatalog, CatalogCard, CatalogCardPayload } from "@pie-players/pie-players-shared/types";
-export type CatalogOwnerKind = "global" | "passage" | "itemModel";
-export interface CatalogOwnerContext {
-    ownerKind: CatalogOwnerKind;
-    assessmentId?: string;
-    sectionId?: string;
-    canonicalItemId?: string;
-    itemId?: string;
-    passageId?: string;
-    modelId?: string;
-}
+import { type CatalogOwnerContext, type CatalogOwnerIdentity, type CatalogSourceEntity } from "./catalog-owner.js";
 export type CatalogLookupContext = CatalogOwnerContext;
+/** One card visible from a mounted content owner's catalog scope. */
+export interface CatalogOwnerCard {
+    /** Author-owned identifier; never normalized or prefixed. */
+    readonly catalogId: string;
+    /** Read-only authored card, including capability-specific metadata. */
+    readonly card: Readonly<CatalogCard>;
+}
+/**
+ * Immutable point-in-time view of the cards owned by an item or passage.
+ *
+ * Ordering is deterministic and matches registration precedence: entity-root,
+ * extractor-generated, then model-owned catalogs in model order. Capabilities
+ * interpret card meaning; the generic resolver owns only scope and traversal.
+ */
+export interface CatalogOwnerSnapshot {
+    readonly cards: readonly CatalogOwnerCard[];
+}
+/**
+ * Owner-bound catalog interface used by content capabilities and their host.
+ *
+ * The owner context is captured once. Callers no longer coordinate a raw entity,
+ * a resolver and a separately assembled lookup context.
+ */
+export interface CatalogOwnerView {
+    snapshot(): CatalogOwnerSnapshot;
+    onChange(listener: () => void): () => void;
+}
+/** Everything needed to register one mounted catalog owner. */
+export interface CatalogOwnerRegistration {
+    owner: CatalogOwnerIdentity;
+    entity: CatalogSourceEntity | null | undefined;
+}
 /** What changed in the resolver's catalog set. */
 export type CatalogChangeReason = "scoped-registered" | "scoped-removed" | "item-added" | "item-cleared";
 /**
@@ -155,6 +178,7 @@ export declare class AccessibilityCatalogResolver {
     private defaultLanguage;
     private sanitizedSpokenCache;
     private catalogChangeListeners;
+    private reportedSnapshotProblems;
     constructor(assessmentCatalogs?: AccessibilityCatalog[], defaultLanguage?: string);
     /**
      * Set the default language for fallback resolution
@@ -191,7 +215,19 @@ export declare class AccessibilityCatalogResolver {
      * Index catalogs into the appropriate map
      */
     private indexCatalogs;
+    private insertScopedCatalogs;
+    private removeScopedInsertion;
     registerCatalogs(context: CatalogOwnerContext, catalogs?: AccessibilityCatalog[]): () => void;
+    /**
+     * Register every catalog carried by one mounted item or passage as one
+     * owner-level transaction.
+     *
+     * The resolver owns the entity walk and emits one post-mutation signal, so a
+     * reader never observes only the root or only the model half of an owner.
+     */
+    registerOwner(registration: CatalogOwnerRegistration): () => void;
+    /** Bind catalog reads and change observation to one content owner. */
+    forOwner(context: CatalogOwnerContext): CatalogOwnerView;
     /**
      * Add item-level catalogs (called when rendering a new item)
      */
@@ -216,6 +252,9 @@ export declare class AccessibilityCatalogResolver {
     private scopedCatalogEntries;
     private findScopedCandidates;
     private isCompatibleOwnerContext;
+    private ownerScopedCatalogEntries;
+    private createOwnerSnapshot;
+    private catalogChangeAffectsOwner;
     private sanitizeCatalogs;
     /**
      * Find a matching catalog card based on lookup options