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

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

@@ -0,0 +1,163 @@
+/**
+ * Tool Policy Provenance — generalization of `PnpResolutionProvenance`
+ * (M8 — see `.cursor/plans/m8-design.md` § 4).
+ *
+ * Today's `PnpResolutionProvenance` (in `services/pnp-provenance.ts`)
+ * tracks decisions made by `PnpToolResolver` only. M8 generalizes the
+ * shape to track decisions from every Pass-1 contributor — host
+ * placement, host policy, provider veto, QTI gates, and custom policy
+ * sources — without losing PNP debugger compatibility.
+ *
+ * **Compatibility posture.** This module is the new home of the shape;
+ * the legacy `pnp-provenance.ts` module remains untouched in PR 1 and
+ * is deleted in PR 5 (the rip-out PR) once every consumer has migrated
+ * to the engine. The shape stays structurally compatible: existing
+ * fields (`contextId`, `resolvedAt`, `sources`, `features`,
+ * `decisionLog`, `summary`) are preserved verbatim. The rule
+ * vocabulary expands, and `ResolutionDecision.precedence` widens from
+ * `1 | 2 | 3 | 4 | 5 | 6` to a `number` so non-QTI rules can fit
+ * (the QTI rules continue to use `1`–`6` exactly as before).
+ */
+/**
+ * Expanded rule vocabulary for `ResolutionDecision.rule` in M8.
+ *
+ * The first six values map 1:1 onto `PnpResolutionProvenance`'s
+ * existing rule names (the QTI 6-level precedence). The remaining
+ * values capture the new contributors the M8 engine surfaces:
+ * placement membership (step 1), provider veto (step 2), host policy
+ * (steps 3 / 4), the QTI-conflict diagnostic (`qti-required-blocked`),
+ * custom sources (step 6), and the catch-all `system-default` for the
+ * "not configured at any level" fallback.
+ */
+export type ToolPolicyDecisionRule = "district-block" | "test-admin-override" | "item-restriction" | "item-requirement" | "district-requirement" | "pnp-support" | "pnp-prohibited" | "placement-membership" | "provider-disabled" | "host-allowlist" | "host-blocked" | "qti-required-blocked" | "custom-source" | "system-default";
+export type ToolPolicySourceType = "organization" | "assessment" | "section" | "item" | "student" | "system" | "host" | "custom";
+export interface ToolPolicyResolutionDecision {
+    /** Monotonic step index across the entire decision log. */
+    step: number;
+    /**
+     * Precedence level. QTI rules use `1`–`6` exactly as in today's
+     * `PnpResolutionProvenance`. Non-QTI rules use `0` (host-side
+     * gates that always fire before QTI) or `7+` (custom sources that
+     * fire after QTI).
+     */
+    precedence: number;
+    rule: ToolPolicyDecisionRule;
+    /** Tool ID being resolved (post-PNP-support-mapping where applicable). */
+    featureId: string;
+    action: "block" | "enable" | "skip" | "advisory";
+    source: {
+        type: ToolPolicySourceType;
+        id?: string;
+        name?: string;
+    };
+    reason: string;
+    value?: unknown;
+    timestamp: Date;
+}
+export interface ToolPolicyFeatureTrail {
+    featureId: string;
+    finalState: "enabled" | "blocked" | "not-configured" | "advisory-only";
+    winningDecision?: ToolPolicyResolutionDecision;
+    allDecisions: ToolPolicyResolutionDecision[];
+    explanation: string;
+}
+export interface ToolPolicyProvenance {
+    contextId: string;
+    resolvedAt: Date;
+    sources: {
+        organization?: {
+            id: string;
+            name: string;
+            pnpDefaults?: unknown;
+        };
+        assessment?: {
+            id: string;
+            name: string;
+            settings?: unknown;
+        };
+        section?: {
+            id: string;
+            title?: string;
+            settings?: unknown;
+        };
+        item?: {
+            id: string;
+            name?: string;
+            settings?: unknown;
+        };
+        student?: {
+            id: string;
+            pnpProfile?: unknown;
+        };
+        host?: {
+            id: string;
+            config?: unknown;
+        };
+    };
+    features: Map<string, ToolPolicyFeatureTrail>;
+    decisionLog: ToolPolicyResolutionDecision[];
+    summary: {
+        totalFeatures: number;
+        enabled: number;
+        blocked: number;
+        notConfigured: number;
+        bySource: Record<string, number>;
+        byRule: Record<string, number>;
+    };
+}
+interface AddDecisionParams {
+    precedence: number;
+    rule: ToolPolicyDecisionRule;
+    featureId: string;
+    action: ToolPolicyResolutionDecision["action"];
+    sourceType: ToolPolicySourceType;
+    sourceId?: string;
+    sourceName?: string;
+    reason: string;
+    value?: unknown;
+}
+/**
+ * Builder mirroring `PnpProvenanceBuilder` but emitting the expanded
+ * `ToolPolicyProvenance` shape. Identical API where the field names
+ * overlap so an `M8 PR 5` rename of the legacy builder is a near-pure
+ * import-path swap.
+ */
+export declare class ToolPolicyProvenanceBuilder {
+    private provenance;
+    private stepCounter;
+    constructor(contextId: string);
+    addSource(type: keyof ToolPolicyProvenance["sources"], data: {
+        id: string;
+        name?: string;
+        config?: unknown;
+    }): this;
+    addDecision(params: AddDecisionParams): this;
+    /**
+     * Reconcile every feature's `finalState` against the post-pipeline
+     * candidate set.
+     *
+     * The eager `finalState` updates inside `addDecision` track the
+     * highest-precedence non-skip decision per feature, but a tool's
+     * *actual* visibility is only known after step 6 of the
+     * composition pipeline — earlier decisions can be reversed by
+     * later host gates, QTI gates, or custom sources. This method
+     * walks every feature trail and rewrites `finalState` from the
+     * final candidate set so callers can rely on
+     * `provenance.features.get(toolId)?.finalState` as the canonical
+     * "is this tool visible right now?" answer (M8 design § 4 + § 12).
+     *
+     * Semantics applied per feature:
+     *   - In `survivingIds`                                 → "enabled"
+     *   - Not in `survivingIds`, has any non-skip decision  → "blocked"
+     *   - Not in `survivingIds`, only advisory decisions    → "advisory-only"
+     *   - Otherwise                                         → "not-configured"
+     *
+     * Surviving features without any logged decisions get a synthetic
+     * "enabled" trail so the provenance is dense enough for hosts that
+     * iterate `provenance.features` to find the visible set.
+     */
+    reconcileFinalStates(survivingIds: ReadonlySet<string>): this;
+    build(): ToolPolicyProvenance;
+}
+export {};
+//# sourceMappingURL=provenance.d.ts.map

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

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

package/dist/policy/core/provenance.js

@@ -0,0 +1,232 @@
+/**
+ * Tool Policy Provenance — generalization of `PnpResolutionProvenance`
+ * (M8 — see `.cursor/plans/m8-design.md` § 4).
+ *
+ * Today's `PnpResolutionProvenance` (in `services/pnp-provenance.ts`)
+ * tracks decisions made by `PnpToolResolver` only. M8 generalizes the
+ * shape to track decisions from every Pass-1 contributor — host
+ * placement, host policy, provider veto, QTI gates, and custom policy
+ * sources — without losing PNP debugger compatibility.
+ *
+ * **Compatibility posture.** This module is the new home of the shape;
+ * the legacy `pnp-provenance.ts` module remains untouched in PR 1 and
+ * is deleted in PR 5 (the rip-out PR) once every consumer has migrated
+ * to the engine. The shape stays structurally compatible: existing
+ * fields (`contextId`, `resolvedAt`, `sources`, `features`,
+ * `decisionLog`, `summary`) are preserved verbatim. The rule
+ * vocabulary expands, and `ResolutionDecision.precedence` widens from
+ * `1 | 2 | 3 | 4 | 5 | 6` to a `number` so non-QTI rules can fit
+ * (the QTI rules continue to use `1`–`6` exactly as before).
+ */
+/**
+ * Builder mirroring `PnpProvenanceBuilder` but emitting the expanded
+ * `ToolPolicyProvenance` shape. Identical API where the field names
+ * overlap so an `M8 PR 5` rename of the legacy builder is a near-pure
+ * import-path swap.
+ */
+export class ToolPolicyProvenanceBuilder {
+    provenance;
+    stepCounter = 0;
+    constructor(contextId) {
+        this.provenance = {
+            contextId,
+            resolvedAt: new Date(),
+            sources: {},
+            features: new Map(),
+            decisionLog: [],
+            summary: {
+                totalFeatures: 0,
+                enabled: 0,
+                blocked: 0,
+                notConfigured: 0,
+                bySource: {},
+                byRule: {},
+            },
+        };
+    }
+    addSource(type, data) {
+        const base = { id: data.id, name: data.name ?? data.id };
+        switch (type) {
+            case "organization":
+                this.provenance.sources.organization = {
+                    ...base,
+                    pnpDefaults: data.config,
+                };
+                break;
+            case "assessment":
+                this.provenance.sources.assessment = {
+                    ...base,
+                    settings: data.config,
+                };
+                break;
+            case "section":
+                this.provenance.sources.section = { ...base, settings: data.config };
+                break;
+            case "item":
+                this.provenance.sources.item = { ...base, settings: data.config };
+                break;
+            case "student":
+                this.provenance.sources.student = {
+                    id: data.id,
+                    pnpProfile: data.config,
+                };
+                break;
+            case "host":
+                this.provenance.sources.host = { id: data.id, config: data.config };
+                break;
+        }
+        return this;
+    }
+    addDecision(params) {
+        const decision = {
+            step: ++this.stepCounter,
+            precedence: params.precedence,
+            rule: params.rule,
+            featureId: params.featureId,
+            action: params.action,
+            source: {
+                type: params.sourceType,
+                id: params.sourceId,
+                name: params.sourceName,
+            },
+            reason: params.reason,
+            value: params.value,
+            timestamp: new Date(),
+        };
+        this.provenance.decisionLog.push(decision);
+        let trail = this.provenance.features.get(params.featureId);
+        if (!trail) {
+            trail = {
+                featureId: params.featureId,
+                finalState: "not-configured",
+                allDecisions: [],
+                explanation: "",
+            };
+            this.provenance.features.set(params.featureId, trail);
+        }
+        trail.allDecisions.push(decision);
+        // "advisory" doesn't change finalState — it preserves the existing
+        // blocked/enabled state and only flags a documented conflict.
+        if (params.action === "advisory") {
+            if (trail.finalState === "not-configured") {
+                trail.finalState = "advisory-only";
+            }
+        }
+        else if (params.action !== "skip") {
+            const isWinning = !trail.winningDecision ||
+                decision.precedence < trail.winningDecision.precedence;
+            if (isWinning) {
+                trail.winningDecision = decision;
+                trail.finalState = decision.action === "enable" ? "enabled" : "blocked";
+            }
+        }
+        this.provenance.summary.bySource[params.sourceType] =
+            (this.provenance.summary.bySource[params.sourceType] || 0) + 1;
+        this.provenance.summary.byRule[params.rule] =
+            (this.provenance.summary.byRule[params.rule] || 0) + 1;
+        return this;
+    }
+    /**
+     * Reconcile every feature's `finalState` against the post-pipeline
+     * candidate set.
+     *
+     * The eager `finalState` updates inside `addDecision` track the
+     * highest-precedence non-skip decision per feature, but a tool's
+     * *actual* visibility is only known after step 6 of the
+     * composition pipeline — earlier decisions can be reversed by
+     * later host gates, QTI gates, or custom sources. This method
+     * walks every feature trail and rewrites `finalState` from the
+     * final candidate set so callers can rely on
+     * `provenance.features.get(toolId)?.finalState` as the canonical
+     * "is this tool visible right now?" answer (M8 design § 4 + § 12).
+     *
+     * Semantics applied per feature:
+     *   - In `survivingIds`                                 → "enabled"
+     *   - Not in `survivingIds`, has any non-skip decision  → "blocked"
+     *   - Not in `survivingIds`, only advisory decisions    → "advisory-only"
+     *   - Otherwise                                         → "not-configured"
+     *
+     * Surviving features without any logged decisions get a synthetic
+     * "enabled" trail so the provenance is dense enough for hosts that
+     * iterate `provenance.features` to find the visible set.
+     */
+    reconcileFinalStates(survivingIds) {
+        for (const featureId of survivingIds) {
+            let trail = this.provenance.features.get(featureId);
+            if (!trail) {
+                trail = {
+                    featureId,
+                    finalState: "enabled",
+                    allDecisions: [],
+                    explanation: "",
+                };
+                this.provenance.features.set(featureId, trail);
+                continue;
+            }
+            trail.finalState = "enabled";
+        }
+        for (const trail of this.provenance.features.values()) {
+            if (survivingIds.has(trail.featureId))
+                continue;
+            const hasNonSkip = trail.allDecisions.some((d) => d.action !== "skip" && d.action !== "advisory");
+            const hasAdvisory = trail.allDecisions.some((d) => d.action === "advisory");
+            if (hasNonSkip) {
+                trail.finalState = "blocked";
+            }
+            else if (hasAdvisory) {
+                trail.finalState = "advisory-only";
+            }
+            else {
+                trail.finalState = "not-configured";
+            }
+        }
+        return this;
+    }
+    build() {
+        for (const trail of this.provenance.features.values()) {
+            trail.explanation = generateExplanation(trail);
+        }
+        for (const trail of this.provenance.features.values()) {
+            this.provenance.summary.totalFeatures++;
+            if (trail.finalState === "enabled") {
+                this.provenance.summary.enabled++;
+            }
+            else if (trail.finalState === "blocked") {
+                this.provenance.summary.blocked++;
+            }
+            else {
+                this.provenance.summary.notConfigured++;
+            }
+        }
+        return this.provenance;
+    }
+}
+function generateExplanation(trail) {
+    if (!trail.winningDecision) {
+        if (trail.finalState === "advisory-only") {
+            const advisory = trail.allDecisions.find((d) => d.action === "advisory");
+            return advisory
+                ? `Feature "${trail.featureId}" was kept in its host-decided state; ${advisory.reason}`
+                : `Feature "${trail.featureId}" carries an advisory note.`;
+        }
+        return `Feature "${trail.featureId}" was not configured at any level.`;
+    }
+    const decision = trail.winningDecision;
+    const sourceName = decision.source.name || decision.source.type;
+    let explanation = `Feature "${trail.featureId}" is ${trail.finalState}.\n\n`;
+    explanation += `**Primary Reason** (${decision.rule}):\n`;
+    explanation += `${decision.reason}\n`;
+    explanation += `Source: ${sourceName} (${decision.source.type})\n`;
+    const overridden = trail.allDecisions.filter((d) => d.step !== decision.step &&
+        d.action !== "skip" &&
+        d.action !== "advisory" &&
+        d.precedence > decision.precedence);
+    if (overridden.length > 0) {
+        explanation += `\n**Overridden Rules**:\n`;
+        for (const d of overridden) {
+            explanation += `- ${d.rule}: ${d.reason}\n`;
+        }
+    }
+    return explanation;
+}
+//# sourceMappingURL=provenance.js.map

package/dist/policy/core/provenance.js.map

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

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

@@ -0,0 +1,67 @@
+/**
+ * QTI input detection (M8 PR 4 — see `.cursor/plans/m8-design.md` F2 and
+ * `.cursor/plans/m8-implementation-plan.md` § PR 4).
+ *
+ * Pure helpers that decide whether the inputs the engine has been given
+ * actually carry QTI 6-level precedence material. Used by:
+ *
+ *   - {@link ToolPolicyEngine}'s constructor as the auto-default for
+ *     `qtiEnforcement` when the host did not pass an explicit `"on"` /
+ *     `"off"`.
+ *   - {@link ToolkitCoordinator.resolveEffectiveQtiEnforcement} as the
+ *     auto-mode rule. PR 2 used a coarse "any non-null assessment → on"
+ *     placeholder; PR 4 narrows it to "assessment OR currentItemRef
+ *     carries QTI material."
+ *
+ * The rule is intentionally narrow. Hosts that bind a bare assessment
+ * record (only `id` / `name`, no PNP and no settings) get the legacy
+ * floating-tools behavior — QTI gates do not engage. The flip happens
+ * the moment the assessment carries any of:
+ *
+ *   - `personalNeedsProfile` (any `supports`, `prohibitedSupports`, or
+ *     `activateAtInit`),
+ *   - `settings.districtPolicy` (any `blockedTools`, `requiredTools`,
+ *     or `policies`),
+ *   - `settings.testAdministration` (any populated key — `mode`,
+ *     `toolOverrides`, etc.),
+ *   - or the bound `currentItemRef.settings` carries
+ *     `requiredTools` / `restrictedTools` / `toolParameters`.
+ *
+ * Hosts opt out of the auto-on behavior by passing
+ * `qtiEnforcement: "off"` explicitly (engine input or
+ * `ToolkitCoordinator.setQtiEnforcement("off")`).
+ */
+import type { AssessmentEntity, AssessmentItemRef } from "@pie-players/pie-players-shared/types";
+/**
+ * Return `true` when the assessment carries any QTI 6-level precedence
+ * material that the engine's `QtiPolicySource` would consume.
+ *
+ * The check is structural — the presence of a non-empty PNP, district
+ * policy, or test administration block is enough; the content does not
+ * have to validate against any specific rule.
+ */
+export declare function assessmentHasQtiInputs(assessment: AssessmentEntity | null | undefined): boolean;
+/**
+ * Return `true` when the bound item reference carries item-level QTI
+ * material (`requiredTools`, `restrictedTools`, or `toolParameters`).
+ *
+ * Used in addition to {@link assessmentHasQtiInputs} so a host that
+ * navigates to an item with QTI-relevant settings — without a parent
+ * assessment carrying its own PNP/district/test-admin block — still
+ * gets QTI gates engaged for that item.
+ */
+export declare function itemRefHasQtiInputs(itemRef: AssessmentItemRef | null | undefined): boolean;
+/**
+ * Resolve the default `qtiEnforcement` mode given the bound inputs.
+ *
+ * Returns `"on"` when {@link assessmentHasQtiInputs} or
+ * {@link itemRefHasQtiInputs} reports any QTI material; otherwise
+ * `"off"`. Hosts override the default by passing an explicit
+ * `qtiEnforcement` value (engine input) or by calling
+ * `ToolkitCoordinator.setQtiEnforcement("on" | "off")`.
+ */
+export declare function resolveDefaultQtiEnforcement(args: {
+    assessment?: AssessmentEntity | null;
+    currentItemRef?: AssessmentItemRef | null;
+}): "on" | "off";
+//# sourceMappingURL=qti-inputs.d.ts.map

package/dist/policy/core/qti-inputs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qti-inputs.d.ts","sourceRoot":"","sources":["../../../src/policy/core/qti-inputs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EACX,gBAAgB,EAChB,iBAAiB,EACjB,MAAM,uCAAuC,CAAC;AAE/C;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACrC,UAAU,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GAC7C,OAAO,CA4DT;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,GAC3C,OAAO,CAuBT;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE;IAClD,UAAU,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACrC,cAAc,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;CAC1C,GAAG,IAAI,GAAG,KAAK,CAIf"}

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

@@ -0,0 +1,139 @@
+/**
+ * QTI input detection (M8 PR 4 — see `.cursor/plans/m8-design.md` F2 and
+ * `.cursor/plans/m8-implementation-plan.md` § PR 4).
+ *
+ * Pure helpers that decide whether the inputs the engine has been given
+ * actually carry QTI 6-level precedence material. Used by:
+ *
+ *   - {@link ToolPolicyEngine}'s constructor as the auto-default for
+ *     `qtiEnforcement` when the host did not pass an explicit `"on"` /
+ *     `"off"`.
+ *   - {@link ToolkitCoordinator.resolveEffectiveQtiEnforcement} as the
+ *     auto-mode rule. PR 2 used a coarse "any non-null assessment → on"
+ *     placeholder; PR 4 narrows it to "assessment OR currentItemRef
+ *     carries QTI material."
+ *
+ * The rule is intentionally narrow. Hosts that bind a bare assessment
+ * record (only `id` / `name`, no PNP and no settings) get the legacy
+ * floating-tools behavior — QTI gates do not engage. The flip happens
+ * the moment the assessment carries any of:
+ *
+ *   - `personalNeedsProfile` (any `supports`, `prohibitedSupports`, or
+ *     `activateAtInit`),
+ *   - `settings.districtPolicy` (any `blockedTools`, `requiredTools`,
+ *     or `policies`),
+ *   - `settings.testAdministration` (any populated key — `mode`,
+ *     `toolOverrides`, etc.),
+ *   - or the bound `currentItemRef.settings` carries
+ *     `requiredTools` / `restrictedTools` / `toolParameters`.
+ *
+ * Hosts opt out of the auto-on behavior by passing
+ * `qtiEnforcement: "off"` explicitly (engine input or
+ * `ToolkitCoordinator.setQtiEnforcement("off")`).
+ */
+/**
+ * Return `true` when the assessment carries any QTI 6-level precedence
+ * material that the engine's `QtiPolicySource` would consume.
+ *
+ * The check is structural — the presence of a non-empty PNP, district
+ * policy, or test administration block is enough; the content does not
+ * have to validate against any specific rule.
+ */
+export function assessmentHasQtiInputs(assessment) {
+    if (!assessment)
+        return false;
+    const pnp = assessment.personalNeedsProfile;
+    if (pnp) {
+        if (Array.isArray(pnp.supports) && pnp.supports.length > 0)
+            return true;
+        if (Array.isArray(pnp.prohibitedSupports) &&
+            pnp.prohibitedSupports.length > 0) {
+            return true;
+        }
+        if (Array.isArray(pnp.activateAtInit) &&
+            pnp.activateAtInit.length > 0) {
+            return true;
+        }
+    }
+    const settings = assessment.settings;
+    if (settings) {
+        const district = settings.districtPolicy;
+        if (district) {
+            if (Array.isArray(district.blockedTools) &&
+                district.blockedTools.length > 0) {
+                return true;
+            }
+            if (Array.isArray(district.requiredTools) &&
+                district.requiredTools.length > 0) {
+                return true;
+            }
+            if (district.policies &&
+                typeof district.policies === "object" &&
+                Object.keys(district.policies).length > 0) {
+                return true;
+            }
+        }
+        const admin = settings.testAdministration;
+        if (admin && typeof admin === "object") {
+            for (const key of Object.keys(admin)) {
+                const value = admin[key];
+                if (value === undefined || value === null)
+                    continue;
+                if (Array.isArray(value) && value.length === 0)
+                    continue;
+                if (typeof value === "object" &&
+                    !Array.isArray(value) &&
+                    Object.keys(value).length === 0) {
+                    continue;
+                }
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Return `true` when the bound item reference carries item-level QTI
+ * material (`requiredTools`, `restrictedTools`, or `toolParameters`).
+ *
+ * Used in addition to {@link assessmentHasQtiInputs} so a host that
+ * navigates to an item with QTI-relevant settings — without a parent
+ * assessment carrying its own PNP/district/test-admin block — still
+ * gets QTI gates engaged for that item.
+ */
+export function itemRefHasQtiInputs(itemRef) {
+    const settings = itemRef?.settings;
+    if (!settings)
+        return false;
+    if (Array.isArray(settings.requiredTools) &&
+        settings.requiredTools.length > 0) {
+        return true;
+    }
+    if (Array.isArray(settings.restrictedTools) &&
+        settings.restrictedTools.length > 0) {
+        return true;
+    }
+    if (settings.toolParameters &&
+        typeof settings.toolParameters === "object" &&
+        Object.keys(settings.toolParameters).length > 0) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Resolve the default `qtiEnforcement` mode given the bound inputs.
+ *
+ * Returns `"on"` when {@link assessmentHasQtiInputs} or
+ * {@link itemRefHasQtiInputs} reports any QTI material; otherwise
+ * `"off"`. Hosts override the default by passing an explicit
+ * `qtiEnforcement` value (engine input) or by calling
+ * `ToolkitCoordinator.setQtiEnforcement("on" | "off")`.
+ */
+export function resolveDefaultQtiEnforcement(args) {
+    if (assessmentHasQtiInputs(args.assessment))
+        return "on";
+    if (itemRefHasQtiInputs(args.currentItemRef))
+        return "on";
+    return "off";
+}
+//# sourceMappingURL=qti-inputs.js.map

package/dist/policy/core/qti-inputs.js.map

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

package/dist/policy/engine.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Tool policy engine — facade entry point (M8 PR 1).
+ *
+ * Narrow, stable public surface for hosts that want to instantiate or
+ * consume a `ToolPolicyEngine`. Re-exports the engine class, its
+ * decision request/response types, the Svelte context key, and the
+ * minimal `PolicySource` extension contract.
+ *
+ * **Pairing.** This module is the stable counterpart to
+ * `./policy/internal`, which exposes the wider, evolving surface
+ * (composition pipeline, provenance builder, QTI source). Consumers
+ * that only need to drive an engine and read its decisions should
+ * import from here. Consumers that need to reach past the facade
+ * (e.g. test the composition pipeline directly, build a custom QTI
+ * source variant, instrument provenance generation) should import
+ * from `./policy/internal` and accept the documented stability
+ * disclaimer there.
+ *
+ * Mirrors the M7 `runtime/engine` / `runtime/internal` split — see
+ * the same rationale in `src/runtime/engine.ts`.
+ */
+export { ToolPolicyEngine, type QtiEnforcementMode, 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 { QtiRequiredBlockedDetails, 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, QtiPolicySourceRule, QtiPolicySourceTag, CustomPolicySourceTag, } from "./core/policy-source-tag.js";
+export type { ToolPolicyDecisionRule, ToolPolicyFeatureTrail, ToolPolicyProvenance, ToolPolicyResolutionDecision, ToolPolicySourceType, } from "./core/provenance.js";
+//# sourceMappingURL=engine.d.ts.map

package/dist/policy/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/policy/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACN,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,GAC3B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACN,sBAAsB,EACtB,KAAK,uBAAuB,GAC5B,MAAM,0BAA0B,CAAC;AAElC,YAAY,EACX,yBAAyB,EACzB,kBAAkB,EAClB,yBAAyB,EACzB,oBAAoB,EACpB,wBAAwB,EACxB,eAAe,EACf,kBAAkB,EAClB,SAAS,GACT,MAAM,0BAA0B,CAAC;AAElC,YAAY,EACX,YAAY,EACZ,2BAA2B,EAC3B,2BAA2B,EAC3B,kBAAkB,GAClB,MAAM,wBAAwB,CAAC;AAEhC,YAAY,EACX,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,GACrB,MAAM,6BAA6B,CAAC;AAErC,YAAY,EACX,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,4BAA4B,EAC5B,oBAAoB,GACpB,MAAM,sBAAsB,CAAC"}