@pie-players/pie-assessment-toolkit 0.3.64 → 0.3.66

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,6 +15,10 @@
  * 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";
@@ -35,6 +39,24 @@ export interface FeaturePolicyDecision {
     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 +69,11 @@ 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;
+}
 /**
  * Interpret a single-feature `PnpPolicySource.resolveFeature(...)` result.
  *
@@ -54,4 +81,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,20 @@
  * 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}"`;
 /**
  * Interpret a single-feature `PnpPolicySource.resolveFeature(...)` result.
  *
@@ -23,18 +36,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/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/composition-emit-scheduler.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Composition emit scheduler (PIE-885).
+ *
+ * `PieAssessmentToolkit.svelte` publishes the section composition to the
+ * players through exactly one path — the `composition-changed` event — and
+ * coalesces bursts of updates behind a one-shot latch so several changes
+ * within one frame produce a single emit.
+ *
+ * That latch used to be cleared only by a `requestAnimationFrame` callback,
+ * and the frame branch was chosen whenever `window.requestAnimationFrame`
+ * merely *existed* rather than when it was known to fire. In a document that
+ * never paints the callback never ran, the latch never cleared, and no
+ * `composition-changed` was ever dispatched: the section controller held a
+ * correct view model while the player kept its initial empty composition, so
+ * every `pie-section-player` route rendered no content at all. The permanent
+ * failure was in contexts with no compositor — headless browsers, hidden or
+ * offscreen tabs, agent and CI automation harnesses. A background tab only
+ * rendered late, because its pending frame becomes due on refocus.
+ *
+ * So the frame is raced against a deadline timer instead of trusted. Whichever
+ * arrives first releases the latch and flushes, and a non-painting document
+ * degrades to a slower render rather than a permanent blank. Svelte's own
+ * `tick()` races the same two primitives for the same reason.
+ *
+ * This scheduler owns the latch and both handles, which is what makes "the
+ * latch cannot stay set after a scheduled frame is cancelled or superseded"
+ * structural rather than a discipline every call site has to keep: releasing
+ * the latch and releasing the handles is one operation in one place.
+ *
+ * Deliberately stateless across cycles. A cycle the timer wins does not switch
+ * the scheduler into a timer-preferring mode: that trades the deadline cost for
+ * a mode which never returns to frame alignment once a single frame is missed,
+ * and a slower render is the accepted outcome.
+ *
+ * NOT a public surface: internal to the toolkit and not exported from
+ * `runtime/engine.ts`. It exists as its own module so the race can be pinned in
+ * a unit test without mounting the toolkit CE — same rationale as
+ * `runtime/stage-emit-gate.ts`.
+ */
+/**
+ * How long to wait for a frame before the timer takes over.
+ *
+ * Six frames at 60fps, so on any normally painting document the frame still
+ * wins and emits stay paint-aligned. Chrome clamps timers in hidden tabs to
+ * ≥1s and can clamp harder under intensive throttling; that makes a hidden tab
+ * bounded-slow instead of blank, which is the point.
+ */
+export declare const DEFAULT_FRAME_DEADLINE_MS = 100;
+/**
+ * Timing primitives, injectable so tests can drive the race deterministically.
+ *
+ * An omitted primitive is resolved from `globalThis` at `schedule()` time
+ * rather than captured at construction: the pre-fix code also checked per
+ * emit, and a host can install a `requestAnimationFrame` shim after the
+ * toolkit is constructed. An explicit `null` opts the primitive out.
+ */
+export interface CompositionEmitSchedulerTiming {
+    requestFrame?: ((callback: () => void) => number) | null;
+    cancelFrame?: ((handle: number) => void) | null;
+    setTimer?: ((callback: () => void, delayMs: number) => unknown) | null;
+    clearTimer?: ((handle: unknown) => void) | null;
+    queueMicrotaskFn?: ((callback: () => void) => void) | null;
+    frameDeadlineMs?: number;
+}
+export interface CompositionEmitScheduler {
+    /**
+     * Arm a flush. While a cycle is pending this only replaces the stored
+     * callback — that is the coalescing guarantee: one resolution, one flush.
+     */
+    schedule(flush: () => void): void;
+    /**
+     * Abandon a pending cycle. Releases the latch and both handles together,
+     * and is idempotent.
+     */
+    cancel(): void;
+    isPending(): boolean;
+}
+export declare function createCompositionEmitScheduler(timing?: CompositionEmitSchedulerTiming): CompositionEmitScheduler;

package/dist/runtime/composition-emit-scheduler.js

@@ -0,0 +1,154 @@
+/**
+ * Composition emit scheduler (PIE-885).
+ *
+ * `PieAssessmentToolkit.svelte` publishes the section composition to the
+ * players through exactly one path — the `composition-changed` event — and
+ * coalesces bursts of updates behind a one-shot latch so several changes
+ * within one frame produce a single emit.
+ *
+ * That latch used to be cleared only by a `requestAnimationFrame` callback,
+ * and the frame branch was chosen whenever `window.requestAnimationFrame`
+ * merely *existed* rather than when it was known to fire. In a document that
+ * never paints the callback never ran, the latch never cleared, and no
+ * `composition-changed` was ever dispatched: the section controller held a
+ * correct view model while the player kept its initial empty composition, so
+ * every `pie-section-player` route rendered no content at all. The permanent
+ * failure was in contexts with no compositor — headless browsers, hidden or
+ * offscreen tabs, agent and CI automation harnesses. A background tab only
+ * rendered late, because its pending frame becomes due on refocus.
+ *
+ * So the frame is raced against a deadline timer instead of trusted. Whichever
+ * arrives first releases the latch and flushes, and a non-painting document
+ * degrades to a slower render rather than a permanent blank. Svelte's own
+ * `tick()` races the same two primitives for the same reason.
+ *
+ * This scheduler owns the latch and both handles, which is what makes "the
+ * latch cannot stay set after a scheduled frame is cancelled or superseded"
+ * structural rather than a discipline every call site has to keep: releasing
+ * the latch and releasing the handles is one operation in one place.
+ *
+ * Deliberately stateless across cycles. A cycle the timer wins does not switch
+ * the scheduler into a timer-preferring mode: that trades the deadline cost for
+ * a mode which never returns to frame alignment once a single frame is missed,
+ * and a slower render is the accepted outcome.
+ *
+ * NOT a public surface: internal to the toolkit and not exported from
+ * `runtime/engine.ts`. It exists as its own module so the race can be pinned in
+ * a unit test without mounting the toolkit CE — same rationale as
+ * `runtime/stage-emit-gate.ts`.
+ */
+/**
+ * How long to wait for a frame before the timer takes over.
+ *
+ * Six frames at 60fps, so on any normally painting document the frame still
+ * wins and emits stay paint-aligned. Chrome clamps timers in hidden tabs to
+ * ≥1s and can clamp harder under intensive throttling; that makes a hidden tab
+ * bounded-slow instead of blank, which is the point.
+ */
+export const DEFAULT_FRAME_DEADLINE_MS = 100;
+function pickFunction(override, ambient) {
+    if (typeof override === "function")
+        return override;
+    if (override === null)
+        return null;
+    return typeof ambient === "function" ? ambient : null;
+}
+export function createCompositionEmitScheduler(timing = {}) {
+    const frameDeadlineMs = timing.frameDeadlineMs ?? DEFAULT_FRAME_DEADLINE_MS;
+    let pending = false;
+    let pendingFlush = null;
+    let frameHandle = null;
+    let timerHandle = null;
+    // Kept from the arming call so a cancel is paired with the primitive that
+    // actually armed the handle.
+    let cancelFrame = null;
+    let clearTimer = null;
+    function release() {
+        pending = false;
+        if (frameHandle !== null) {
+            cancelFrame?.(frameHandle);
+            frameHandle = null;
+        }
+        if (timerHandle !== null) {
+            clearTimer?.(timerHandle);
+            timerHandle = null;
+        }
+        cancelFrame = null;
+        clearTimer = null;
+    }
+    /**
+     * Resolve one cycle. `firedFrom` names the side that arrived so its own
+     * handle is dropped rather than handed back to a cancel that has nothing
+     * left to cancel.
+     *
+     * The latch is released before the flush callback runs, so a re-entrant
+     * `schedule()` from inside the flush arms a fresh cycle instead of being
+     * swallowed. The pre-fix code cleared its latch first for the same reason.
+     */
+    function resolve(firedFrom) {
+        if (!pending)
+            return;
+        if (firedFrom === "frame")
+            frameHandle = null;
+        if (firedFrom === "timer")
+            timerHandle = null;
+        const flushNow = pendingFlush;
+        pendingFlush = null;
+        release();
+        flushNow?.();
+    }
+    function schedule(flush) {
+        pendingFlush = flush;
+        if (pending)
+            return;
+        pending = true;
+        const ambient = globalThis;
+        const requestFrame = pickFunction(timing.requestFrame, ambient.requestAnimationFrame);
+        cancelFrame = pickFunction(timing.cancelFrame, ambient.cancelAnimationFrame);
+        const setTimer = pickFunction(timing.setTimer, ambient.setTimeout);
+        clearTimer = pickFunction(timing.clearTimer, ambient.clearTimeout);
+        if (requestFrame) {
+            const handle = requestFrame(() => resolve("frame"));
+            // A primitive that calls back synchronously has already flushed and
+            // released; arming anything else would leave a stray handle behind.
+            if (!pending)
+                return;
+            frameHandle = handle;
+            // The frame is not trusted to arrive. Without a timer alongside it, a
+            // document that never paints leaves the latch set forever.
+            if (setTimer) {
+                const deadlineHandle = setTimer(() => resolve("timer"), frameDeadlineMs);
+                if (pending)
+                    timerHandle = deadlineHandle;
+            }
+            return;
+        }
+        // No frame primitive at all (SSR, non-DOM test environments). Preserve
+        // the microtask timing those hosts already had.
+        const queueMicrotaskFn = pickFunction(timing.queueMicrotaskFn, ambient.queueMicrotask);
+        if (queueMicrotaskFn) {
+            queueMicrotaskFn(() => resolve("microtask"));
+            return;
+        }
+        if (setTimer) {
+            const deadlineHandle = setTimer(() => resolve("timer"), 0);
+            if (pending)
+                timerHandle = deadlineHandle;
+            return;
+        }
+        // Nothing to defer with. A synchronous flush is strictly better than
+        // dropping the composition on the floor.
+        resolve("microtask");
+    }
+    function cancel() {
+        if (!pending)
+            return;
+        pendingFlush = null;
+        release();
+    }
+    return {
+        schedule,
+        cancel,
+        isPending: () => pending,
+    };
+}

package/dist/runtime/core/engine-resolver.d.ts

@@ -120,7 +120,7 @@ export declare function resolveRuntime(args: {
     createSectionController: unknown;
     isolation: string;
     env: Record<string, unknown>;
-    toolConfigStrictness: "off" | "error" | "warn";
+    toolConfigStrictness: "off" | "warn" | "error";
     onFrameworkError: FrameworkErrorHandler | undefined;
     onStageChange: StageChangeHandler | undefined;
     onLoadingComplete: LoadingCompleteHandler | undefined;

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