@pie-players/pie-assessment-toolkit 0.3.30 → 0.3.32

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

@@ -0,0 +1,332 @@
+/**
+ * Compose-decision pipeline (M8 — see `.cursor/plans/m8-design.md` § 3).
+ *
+ * Pure function: given a decision request, the host's tools config,
+ * an optional QTI source, and the registered custom sources, returns
+ * a `ToolPolicyDecision`. The function performs no I/O, holds no
+ * 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
+ * `tests/policy/compose-decision.test.ts` lock the orchestration in.
+ */
+import { normalizeToolList, } from "../../services/tools-config-normalizer.js";
+import { ToolPolicyProvenanceBuilder } from "./provenance.js";
+export function composeDecision(inputs) {
+    const { request, tools, qti, customSources, contextId } = inputs;
+    const builder = new ToolPolicyProvenanceBuilder(contextId);
+    builder.addSource("host", {
+        id: request.scope.scopeId,
+        name: `${request.level}:${request.scope.scopeId}`,
+        config: {
+            placement: tools.placement,
+            policy: tools.policy,
+        },
+    });
+    const placement = normalizeToolList(tools.placement[request.level]);
+    const allowed = normalizeToolList(tools.policy.allowed);
+    const blocked = new Set(normalizeToolList(tools.policy.blocked));
+    // Step 1 — Membership filter.
+    //
+    // Logged with `action: "skip"` rather than `"enable"` because a
+    // placement-membership entry is the pipeline's starting point, not
+    // a winning decision. Subsequent steps may block the tool at the
+    // same precedence (0); the builder's `decision.precedence <
+    // winning.precedence` rule would otherwise let the placement entry
+    // win equality and mask later blocks. Surviving tools are flipped
+    // to `enabled` by `builder.reconcileFinalStates(...)` at the end of
+    // the pipeline once the final candidate set is known.
+    let candidates = [];
+    for (const toolId of placement) {
+        candidates.push(toolId);
+        builder.addDecision({
+            precedence: 0,
+            rule: "placement-membership",
+            featureId: toolId,
+            action: "skip",
+            sourceType: "host",
+            reason: `Listed in tools.placement.${request.level}`,
+        });
+    }
+    // Step 2 — Provider veto.
+    candidates = candidates.filter((toolId) => {
+        const providerEnabled = tools.providers?.[toolId]?.enabled;
+        if (providerEnabled === false) {
+            builder.addDecision({
+                precedence: 0,
+                rule: "provider-disabled",
+                featureId: toolId,
+                action: "block",
+                sourceType: "host",
+                reason: `tools.providers.${toolId}.enabled === false`,
+                value: false,
+            });
+            return false;
+        }
+        return true;
+    });
+    // Step 3 — Host whitelist (only when non-empty).
+    if (allowed.length > 0) {
+        const allowedSet = new Set(allowed);
+        candidates = candidates.filter((toolId) => {
+            if (!allowedSet.has(toolId)) {
+                builder.addDecision({
+                    precedence: 0,
+                    rule: "host-allowlist",
+                    featureId: toolId,
+                    action: "block",
+                    sourceType: "host",
+                    reason: "Not present in tools.policy.allowed",
+                    value: allowed,
+                });
+                return false;
+            }
+            return true;
+        });
+    }
+    // Step 4 — Host blocklist (absolute).
+    candidates = candidates.filter((toolId) => {
+        if (blocked.has(toolId)) {
+            builder.addDecision({
+                precedence: 0,
+                rule: "host-blocked",
+                featureId: toolId,
+                action: "block",
+                sourceType: "host",
+                reason: "Listed in tools.policy.blocked",
+                value: tools.policy.blocked,
+            });
+            return false;
+        }
+        return true;
+    });
+    // Step 5 — QTI gates.
+    const diagnostics = [];
+    const sourcesByTool = new Map();
+    for (const toolId of candidates) {
+        sourcesByTool.set(toolId, ["placement"]);
+    }
+    // Snapshot the post-host candidate set so step 5b can distinguish
+    // "host removed a QTI-mandated tool" (qtiRequiredBlocked fires)
+    // from "QTI's own precedence removed a QTI-mandated tool" (fix
+    // per M8 PR 1 R1 S1 — multi-rule conflict on the same tool must
+    // not blame the host).
+    const postHostCandidates = new Set(candidates);
+    let qtiResult = null;
+    if (qti.enforcement === "on" && qti.source && qti.assessment) {
+        qtiResult = qti.source.apply({
+            assessment: qti.assessment,
+            currentItemRef: qti.currentItemRef,
+        });
+        if (qtiResult.sources.assessment) {
+            builder.addSource("assessment", qtiResult.sources.assessment);
+        }
+        if (qtiResult.sources.student) {
+            builder.addSource("student", qtiResult.sources.student);
+        }
+        if (qtiResult.sources.item) {
+            builder.addSource("item", qtiResult.sources.item);
+        }
+        for (const decision of qtiResult.decisions) {
+            builder.addDecision({
+                precedence: decision.precedence,
+                rule: decision.rule,
+                featureId: decision.featureId,
+                action: decision.action,
+                sourceType: decision.sourceType,
+                reason: decision.reason,
+                value: decision.value,
+            });
+        }
+        // 5a — remove QTI-blocked tools from the candidate set.
+        candidates = candidates.filter((toolId) => {
+            return !qtiResult.blockedToolIds.has(toolId);
+        });
+        for (const toolId of Array.from(sourcesByTool.keys())) {
+            if (qtiResult.blockedToolIds.has(toolId)) {
+                sourcesByTool.delete(toolId);
+            }
+        }
+        // 5b — surface qtiRequiredBlocked diagnostics ONLY for
+        // QTI-mandated tools that the host removed (i.e., the tool was
+        // NOT in `postHostCandidates`). Mandated tools removed by
+        // QTI's own higher-precedence rule (e.g. `restrictedTools`
+        // blocking a `requiredTools` mandate) are an internal QTI
+        // resolution and must not be reported as a host conflict — the
+        // loser's `block` decision is already in the trail with full
+        // QTI provenance.
+        //
+        // `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
+        // `QtiRequiredBlockedDetails` for the typed shape.
+        for (const mandatedToolId of qtiResult.mandatedToolIds) {
+            const removedByHost = !postHostCandidates.has(mandatedToolId);
+            if (!removedByHost)
+                continue;
+            const flag = qtiResult.perToolFlags.get(mandatedToolId);
+            const ruleName = flag?.rule ?? "qti-required";
+            const hostGate = detectHostRemovalGate(mandatedToolId, {
+                placement,
+                allowed,
+                blocked,
+                providers: tools.providers,
+            });
+            const details = {
+                rule: ruleName,
+                hostRule: hostGate.hostRule,
+                hostValue: hostGate.hostValue,
+            };
+            diagnostics.push({
+                code: "tool-policy.qtiRequiredBlocked",
+                level: request.level,
+                toolId: mandatedToolId,
+                message: `QTI mandates "${mandatedToolId}" (${ruleName}) but host policy removed it from level "${request.level}" via ${hostGate.hostRule}.`,
+                details,
+            });
+            builder.addDecision({
+                precedence: 0,
+                rule: "qti-required-blocked",
+                featureId: mandatedToolId,
+                action: "advisory",
+                sourceType: "host",
+                reason: `Host removed QTI-mandated tool "${mandatedToolId}" via ${hostGate.hostRule}`,
+                value: details,
+            });
+        }
+        // 5c — attach QTI source tags to surviving entries.
+        for (const toolId of candidates) {
+            const flag = qtiResult.perToolFlags.get(toolId);
+            if (flag) {
+                const tags = sourcesByTool.get(toolId) ?? [];
+                tags.push(`qti.${flag.rule}`);
+                sourcesByTool.set(toolId, tags);
+            }
+        }
+    }
+    // Step 6 — Custom PolicySources.
+    for (let i = 0; i < customSources.length; i++) {
+        const source = customSources[i];
+        const before = candidates.slice();
+        const result = source.refine({
+            request,
+            candidates: before,
+        });
+        const refinedSet = new Set(result.refinedCandidates);
+        // Reject any superset additions (custom sources can only narrow).
+        for (const toolId of result.refinedCandidates) {
+            if (!before.includes(toolId)) {
+                diagnostics.push({
+                    code: "tool-policy.placementMissing",
+                    level: request.level,
+                    toolId,
+                    message: `Custom source "${source.id}" tried to add tool "${toolId}" that was not in candidates; ignored.`,
+                    source: `custom.${source.id}`,
+                });
+                refinedSet.delete(toolId);
+            }
+        }
+        candidates = before.filter((id) => refinedSet.has(id));
+        // Index the source's emitted block decisions by featureId so we
+        // can detect "silent removals" — tools the source dropped from
+        // the candidate set without logging an explicit block. Without
+        // this auto-log, the provenance trail for a silently-removed
+        // tool would show only the prior `enable` decisions and the
+        // final-state reconciliation would have no evidence to mark it
+        // `blocked` (M8 PR 1 R2 S1 / M1 case B).
+        const explicitBlocks = new Set();
+        if (result.decisions) {
+            for (const event of result.decisions) {
+                builder.addDecision({
+                    precedence: event.precedence ?? 100 + i,
+                    rule: event.rule,
+                    featureId: event.featureId,
+                    action: event.action,
+                    sourceType: event.sourceType,
+                    reason: event.reason,
+                    value: event.value,
+                });
+                if (event.action === "block") {
+                    explicitBlocks.add(event.featureId);
+                }
+            }
+        }
+        // Auto-log a `custom-source / block` decision for silent removals.
+        for (const toolId of before) {
+            if (refinedSet.has(toolId))
+                continue;
+            if (explicitBlocks.has(toolId))
+                continue;
+            builder.addDecision({
+                precedence: 100 + i,
+                rule: "custom-source",
+                featureId: toolId,
+                action: "block",
+                sourceType: "custom",
+                reason: `Custom policy source "${source.id}" removed tool "${toolId}" from candidates without emitting a decision; auto-logged for trail completeness.`,
+                value: { customSourceId: source.id },
+            });
+        }
+        // Annotate surviving entries with `custom.<id>` so hosts can see
+        // which custom source kept them in.
+        for (const toolId of candidates) {
+            const tags = sourcesByTool.get(toolId) ?? ["placement"];
+            tags.push(`custom.${source.id}`);
+            sourcesByTool.set(toolId, tags);
+        }
+        // And drop attribution for IDs the source removed.
+        for (const toolId of before) {
+            if (!refinedSet.has(toolId)) {
+                sourcesByTool.delete(toolId);
+            }
+        }
+    }
+    const survivingIds = new Set(candidates);
+    const visibleTools = candidates.map((toolId) => {
+        const flag = qtiResult?.perToolFlags.get(toolId);
+        return {
+            toolId,
+            required: flag?.required ?? false,
+            alwaysAvailable: flag?.alwaysAvailable ?? false,
+            settings: flag?.settings,
+            sources: sourcesByTool.get(toolId) ?? ["placement"],
+        };
+    });
+    builder.reconcileFinalStates(survivingIds);
+    return {
+        visibleTools,
+        diagnostics,
+        provenance: builder.build(),
+    };
+}
+/**
+ * Identify which step-1-through-4 host gate removed a tool. Used by
+ * step 5b to enrich `tool-policy.qtiRequiredBlocked` diagnostics. The
+ * checks mirror the pipeline order — step 1 (placement) first, step 4
+ * (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.
+ */
+function detectHostRemovalGate(toolId, args) {
+    if (!args.placement.includes(toolId)) {
+        return { hostRule: "placement-missing", hostValue: args.placement };
+    }
+    if (args.providers?.[toolId]?.enabled === false) {
+        return { hostRule: "provider-disabled", hostValue: false };
+    }
+    if (args.allowed.length > 0 && !args.allowed.includes(toolId)) {
+        return { hostRule: "host-allowlist", hostValue: args.allowed };
+    }
+    if (args.blocked.has(toolId)) {
+        return {
+            hostRule: "host-blocked",
+            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 };
+}
+//# sourceMappingURL=compose-decision.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compose-decision.js","sourceRoot":"","sources":["../../../src/policy/core/compose-decision.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,142 @@
+/**
+ * Tool Policy Engine — decision input/output types.
+ *
+ * These types describe the *request/response* contract for
+ * `ToolPolicyEngine.decide(...)`. The engine itself, plus the
+ * 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.
+ */
+import type { ToolPlacementLevel } from "../../services/tools-config-normalizer.js";
+import type { ToolContext, ToolLevel } from "../../services/tool-context.js";
+import type { PolicySourceTag } from "./policy-source-tag.js";
+import type { ToolPolicyProvenance } from "./provenance.js";
+/**
+ * Scope identifier for a `decide(...)` request. The engine uses
+ * `level` to pick which placement bucket to read; `scopeId` is opaque
+ * to the engine (it is round-tripped into provenance for human-readable
+ * trails) and is typically the section-id, item-id, or passage-id of
+ * the surface asking the question. `contentKind` mirrors the
+ * `ToolbarContext.scope.contentKind` field already in use by
+ * `<pie-item-toolbar>` Pass-2 visibility.
+ */
+export interface ToolScope {
+    level: ToolLevel;
+    scopeId: string;
+    assessmentId?: string;
+    sectionId?: string;
+    itemId?: string;
+    canonicalItemId?: string;
+    contentKind?: string;
+}
+export interface ToolPolicyDecisionRequest {
+    /**
+     * Placement bucket the engine reads from
+     * (`tools.placement[level]`). Stays narrow (`section | item |
+     * passage`) — broader `ToolLevel` values from `tool-context.ts`
+     * are surfaced through `scope.level` only.
+     */
+    level: ToolPlacementLevel;
+    scope: ToolScope;
+    /**
+     * Optional Pass-2 context. The engine itself does NOT call
+     * `isVisibleInContext(...)`; that gate is intentionally applied
+     * at the toolbar boundary (Pass-2 = relevance, Pass-1 = the
+     * engine's job). The context is forwarded to custom
+     * `PolicySource` instances so they can refine the candidate set
+     * if they need to.
+     */
+    context?: ToolContext;
+}
+/**
+ * Diagnostic codes the engine may emit alongside a decision. The
+ * canonical case in M8 is `tool-policy.qtiRequiredBlocked` — fired
+ * when a host policy gate (`policy.blocked`, missing-from-`placement`,
+ * provider veto) removed a tool that QTI's `requiredTools` /
+ * `district.requiredTools` mandates.
+ *
+ * `tool-policy.placementMissing` fires when a custom `PolicySource`
+ * references a tool ID that is not present in `tools.placement[level]`
+ * for the resolved level. The host-side `ToolConfigDiagnostic` channel
+ * (already used by `tool-config-validation.ts`) covers config-time
+ * misconfiguration; this channel covers per-decision conflicts.
+ */
+export type ToolPolicyDiagnosticCode = "tool-policy.qtiRequiredBlocked" | "tool-policy.placementMissing";
+/**
+ * Which host gate removed a QTI-mandated tool. Surfaced inside
+ * `ToolPolicyDiagnostic.details` for `tool-policy.qtiRequiredBlocked`
+ * so consumers can render a single human-readable explanation
+ * ("the proctor blocked the calculator that this student's IEP
+ * requires") without re-deriving the host gate from
+ * `provenance.features[toolId].allDecisions`.
+ *
+ * The four values mirror steps 1–4 of `composeDecision`:
+ *   - `placement-missing` — tool is not in `tools.placement[level]`
+ *   - `provider-disabled` — `tools.providers[id].enabled === false`
+ *   - `host-allowlist`    — non-empty `tools.policy.allowed` excludes the id
+ *   - `host-blocked`      — `tools.policy.blocked` lists the id
+ */
+export type ToolPolicyHostGate = "placement-missing" | "provider-disabled" | "host-allowlist" | "host-blocked";
+/**
+ * Strongly-typed payload for `tool-policy.qtiRequiredBlocked`
+ * diagnostics. The diagnostic's `details` field still types as
+ * `Record<string, unknown>` for forward compatibility, but engines
+ * always populate this exact shape today and consumers can safely
+ * cast.
+ */
+export interface QtiRequiredBlockedDetails extends Record<string, unknown> {
+    /** The QTI rule that mandated the tool (e.g. `district-requirement`). */
+    rule: string;
+    /** Which host gate removed the tool. */
+    hostRule: ToolPolicyHostGate;
+    /** The host configuration value that triggered the gate (best-effort, may be omitted). */
+    hostValue?: unknown;
+}
+export interface ToolPolicyDiagnostic {
+    code: ToolPolicyDiagnosticCode;
+    level: ToolPlacementLevel;
+    toolId: string;
+    message: string;
+    source?: PolicySourceTag;
+    details?: Record<string, unknown>;
+}
+export interface ToolPolicyEntry {
+    toolId: string;
+    /**
+     * `true` when QTI mandates this tool (item or district
+     * `requiredTools`, or PNP support without prohibition). Advisory
+     * mandates that the host blocked do *not* surface here — they
+     * appear in `diagnostics` instead. Hosts that need to know about
+     * those should listen on the diagnostic channel.
+     */
+    required: boolean;
+    /**
+     * `true` for PNP `supports` — UI-level signal that the host
+     * cannot toggle this tool off in user preferences. Does NOT
+     * override host blocks (they would have removed the entry
+     * before this flag is read).
+     */
+    alwaysAvailable: boolean;
+    /**
+     * Tool-specific settings resolved from the assessment / item
+     * settings via the QTI source. Hosts that want to read these
+     * directly should use `entry.settings` rather than peeking into
+     * the assessment entity from above the engine.
+     */
+    settings?: unknown;
+    /**
+     * Every contributor that helped this entry survive the
+     * composition pipeline. Always non-empty — at minimum
+     * `["placement"]` for any entry that came from
+     * `tools.placement[level]`.
+     */
+    sources: PolicySourceTag[];
+}
+export interface ToolPolicyDecision {
+    visibleTools: ToolPolicyEntry[];
+    diagnostics: ToolPolicyDiagnostic[];
+    provenance: ToolPolicyProvenance;
+}
+//# sourceMappingURL=decision-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"decision-types.d.ts","sourceRoot":"","sources":["../../../src/policy/core/decision-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2CAA2C,CAAC;AACpF,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC7E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAE5D;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACzB,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,yBAAyB;IACzC;;;;;OAKG;IACH,KAAK,EAAE,kBAAkB,CAAC;IAC1B,KAAK,EAAE,SAAS,CAAC;IACjB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,wBAAwB,GACjC,gCAAgC,GAChC,8BAA8B,CAAC;AAElC;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,kBAAkB,GAC3B,mBAAmB,GACnB,mBAAmB,GACnB,gBAAgB,GAChB,cAAc,CAAC;AAElB;;;;;;GAMG;AACH,MAAM,WAAW,yBAA0B,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACzE,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,0FAA0F;IAC1F,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,wBAAwB,CAAC;IAC/B,KAAK,EAAE,kBAAkB,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,eAAe,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,OAAO,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IAClC,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,WAAW,EAAE,oBAAoB,EAAE,CAAC;IACpC,UAAU,EAAE,oBAAoB,CAAC;CACjC"}

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

@@ -0,0 +1,13 @@
+/**
+ * Tool Policy Engine — decision input/output types.
+ *
+ * These types describe the *request/response* contract for
+ * `ToolPolicyEngine.decide(...)`. The engine itself, plus the
+ * 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.
+ */
+export {};
+//# sourceMappingURL=decision-types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"decision-types.js","sourceRoot":"","sources":["../../../src/policy/core/decision-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/policy/core/engine-context.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Svelte context key for the tool policy engine (M8 PR 1).
+ *
+ * Components inside an assessment toolkit subtree consume the engine
+ * through Svelte's native `getContext(TOOL_POLICY_ENGINE_KEY)`. The
+ * canonical provider is the `ToolkitCoordinator` wiring (M8 PR 2):
+ * the toolkit CE constructs a `ToolPolicyEngine`, attaches it to the
+ * coordinator, and exposes it to descendants via
+ * `setContext(TOOL_POLICY_ENGINE_KEY, engine)`.
+ *
+ * Mirrors the M7 `SECTION_RUNTIME_ENGINE_KEY` pattern. As with the
+ * runtime engine, the key is a `Symbol` so it cannot collide with
+ * userland context keys and so descendants are forced to import this
+ * module rather than guess a string id.
+ *
+ * **No cross-CE bridge.** Unlike the runtime engine, there is no
+ * `connectToolPolicyEngineHostContext` helper — see M8 design Q8.
+ * Every CE in the tree gets its engine from its own coordinator
+ * (the toolkit element). This avoids subscription-bridge overhead
+ * for a function-style engine that hosts can simply re-call after
+ * an input swap.
+ *
+ * **Stability.** This export is part of the stable `policy/engine`
+ * surface; renaming or replacing the symbol is a major breaking
+ * change.
+ */
+import type { ToolPolicyEngine } from "./ToolPolicyEngine.js";
+export declare const TOOL_POLICY_ENGINE_KEY: unique symbol;
+export type ToolPolicyEngineContext = ToolPolicyEngine;
+//# sourceMappingURL=engine-context.d.ts.map

package/dist/policy/core/engine-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-context.d.ts","sourceRoot":"","sources":["../../../src/policy/core/engine-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,eAAO,MAAM,sBAAsB,EAAE,OAAO,MAE3C,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,CAAC"}

package/dist/policy/core/engine-context.js

@@ -0,0 +1,28 @@
+/**
+ * Svelte context key for the tool policy engine (M8 PR 1).
+ *
+ * Components inside an assessment toolkit subtree consume the engine
+ * through Svelte's native `getContext(TOOL_POLICY_ENGINE_KEY)`. The
+ * canonical provider is the `ToolkitCoordinator` wiring (M8 PR 2):
+ * the toolkit CE constructs a `ToolPolicyEngine`, attaches it to the
+ * coordinator, and exposes it to descendants via
+ * `setContext(TOOL_POLICY_ENGINE_KEY, engine)`.
+ *
+ * Mirrors the M7 `SECTION_RUNTIME_ENGINE_KEY` pattern. As with the
+ * runtime engine, the key is a `Symbol` so it cannot collide with
+ * userland context keys and so descendants are forced to import this
+ * module rather than guess a string id.
+ *
+ * **No cross-CE bridge.** Unlike the runtime engine, there is no
+ * `connectToolPolicyEngineHostContext` helper — see M8 design Q8.
+ * Every CE in the tree gets its engine from its own coordinator
+ * (the toolkit element). This avoids subscription-bridge overhead
+ * for a function-style engine that hosts can simply re-call after
+ * an input swap.
+ *
+ * **Stability.** This export is part of the stable `policy/engine`
+ * surface; renaming or replacing the symbol is a major breaking
+ * change.
+ */
+export const TOOL_POLICY_ENGINE_KEY = Symbol("@pie-players/tool-policy-engine");
+//# sourceMappingURL=engine-context.js.map

package/dist/policy/core/engine-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-context.js","sourceRoot":"","sources":["../../../src/policy/core/engine-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,MAAM,CAAC,MAAM,sBAAsB,GAAkB,MAAM,CAC1D,iCAAiC,CACjC,CAAC"}

package/dist/policy/core/policy-source-tag.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Policy source tag — attribution for `ToolPolicyEntry.sources`.
+ *
+ * The engine attaches a `PolicySourceTag` to every `ToolPolicyEntry` it
+ * emits, capturing every step from `compose-decision.ts` that contributed
+ * to the entry being kept (or, in the case of `qti-required-blocked`,
+ * the step that surfaced the conflict).
+ *
+ * Tag vocabulary maps onto the six composition steps in
+ * `m8-design.md` § 3:
+ *
+ *   1. Membership filter   → `"placement"`
+ *   2. Provider veto       → `"provider"` (negative; only present when
+ *                                            the entry survived a
+ *                                            non-`enabled: false` check)
+ *   3. Host whitelist      → `"policy"`
+ *   4. Host blocklist      → `"policy"` (negative)
+ *   5. QTI gates           → `"qti.${rule}"` (e.g. `"qti.pnp-support"`,
+ *                                              `"qti.item-requirement"`)
+ *   6. Custom PolicySources → `"custom.${source.id}"`
+ *
+ * Negative tags do not appear on surviving entries — they are reflected
+ * only in `ToolPolicyProvenance` decisions. The tag union therefore
+ * tracks contributors that *kept* a tool, not contributors that
+ * *removed* one. Diagnostic surfacing of removals is the
+ * provenance/diagnostic channel's job.
+ */
+export type QtiPolicySourceRule = "district-block" | "test-admin-override" | "item-restriction" | "item-requirement" | "district-requirement" | "pnp-support" | "pnp-prohibited";
+export type QtiPolicySourceTag = `qti.${QtiPolicySourceRule}`;
+export type CustomPolicySourceTag = `custom.${string}`;
+export type PolicySourceTag = "placement" | "policy" | "provider" | QtiPolicySourceTag | CustomPolicySourceTag;
+//# sourceMappingURL=policy-source-tag.d.ts.map

package/dist/policy/core/policy-source-tag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-source-tag.d.ts","sourceRoot":"","sources":["../../../src/policy/core/policy-source-tag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,MAAM,mBAAmB,GAC5B,gBAAgB,GAChB,qBAAqB,GACrB,kBAAkB,GAClB,kBAAkB,GAClB,sBAAsB,GACtB,aAAa,GACb,gBAAgB,CAAC;AAEpB,MAAM,MAAM,kBAAkB,GAAG,OAAO,mBAAmB,EAAE,CAAC;AAE9D,MAAM,MAAM,qBAAqB,GAAG,UAAU,MAAM,EAAE,CAAC;AAEvD,MAAM,MAAM,eAAe,GACxB,WAAW,GACX,QAAQ,GACR,UAAU,GACV,kBAAkB,GAClB,qBAAqB,CAAC"}

package/dist/policy/core/policy-source-tag.js

@@ -0,0 +1,29 @@
+/**
+ * Policy source tag — attribution for `ToolPolicyEntry.sources`.
+ *
+ * The engine attaches a `PolicySourceTag` to every `ToolPolicyEntry` it
+ * emits, capturing every step from `compose-decision.ts` that contributed
+ * to the entry being kept (or, in the case of `qti-required-blocked`,
+ * the step that surfaced the conflict).
+ *
+ * Tag vocabulary maps onto the six composition steps in
+ * `m8-design.md` § 3:
+ *
+ *   1. Membership filter   → `"placement"`
+ *   2. Provider veto       → `"provider"` (negative; only present when
+ *                                            the entry survived a
+ *                                            non-`enabled: false` check)
+ *   3. Host whitelist      → `"policy"`
+ *   4. Host blocklist      → `"policy"` (negative)
+ *   5. QTI gates           → `"qti.${rule}"` (e.g. `"qti.pnp-support"`,
+ *                                              `"qti.item-requirement"`)
+ *   6. Custom PolicySources → `"custom.${source.id}"`
+ *
+ * Negative tags do not appear on surviving entries — they are reflected
+ * only in `ToolPolicyProvenance` decisions. The tag union therefore
+ * tracks contributors that *kept* a tool, not contributors that
+ * *removed* one. Diagnostic surfacing of removals is the
+ * provenance/diagnostic channel's job.
+ */
+export {};
+//# sourceMappingURL=policy-source-tag.js.map

package/dist/policy/core/policy-source-tag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-source-tag.js","sourceRoot":"","sources":["../../../src/policy/core/policy-source-tag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG"}