@instruktlabs/kiln 0.0.0-stage → 1.0.0

package/lib/qa/requirements-run.js

@@ -0,0 +1,370 @@
+import { Object3D } from 'three';
+import { analyzeVfxArtifactEvidenceV1, analyzeAssetScopeObservationV1 } from "./breadth-evidence.js";
+import { inspectEffectsExact, inspectEffectsAdvisory, VFX_EXACT_QA_RULE, VFX_ADVISORY_QA_RULE, inspectAssetScope, ASSET_SCOPE_QA_RULE, } from "./breadth.js";
+import { analyzeFinalVfxGlbBytesV1, inspectFinalEffects, finalEffectsMetrics, } from "./breadth-final.js";
+import { QaRegistry } from "./registry.js";
+import { UNIVERSAL_QA_KERNELS, UNIVERSAL_QA_RULES } from "./universal.js";
+import { MATERIAL_QA_RULE, inspectPortableSceneMaterials } from "./material.js";
+import { inspectPlacement, inspectArticulation, inspectContainerOpening, PROP_EXACT_QA_RULE, PROP_ADVISORY_QA_RULE, } from "./prop.js";
+import { inspectPartConnectivity, PART_CONNECTIVITY_QA_RULE } from "./part-connectivity.js";
+import { inspectSweepGeometry, SWEEP_QA_RULE } from "./sweep.js";
+import { analyzePartPenetration, inspectPartPenetration, SELF_INTERSECTION_QA_RULE, } from "./self-intersection.js";
+import { inspectMobility, VEHICLE_QA_RULES } from "./vehicle.js";
+import { inspectMobilityAdvisory } from "./vehicle-advisory.js";
+import { inspectFoliageContact, inspectFoliageAdvisory, VEGETATION_QA_RULES } from "./vegetation.js";
+import { inspectRig, CHARACTER_QA_RULE } from "./character.js";
+import { inspectRigAdvisory, CHARACTER_ADVISORY_QA_RULE } from "./character-advisory.js";
+import { inspectStructure, ARCHITECTURE_QA_RULES } from "./architecture.js";
+import { inspectPlacementSockets, inspectTileEdges, inspectNavigationClearance, inspectSpatialSupport, ENVIRONMENT_QA_RULES, } from "./environment.js";
+import { resolveRequirementsApplicability } from "./requirements-applicability.js";
+import { createRequirementsQaReport, } from "./requirements-report.js";
+import { gltfReportFindings } from "./run.js";
+const registry = new QaRegistry([
+    ...UNIVERSAL_QA_RULES,
+    MATERIAL_QA_RULE,
+    PROP_EXACT_QA_RULE,
+    PROP_ADVISORY_QA_RULE,
+    PART_CONNECTIVITY_QA_RULE,
+    SELF_INTERSECTION_QA_RULE,
+    SWEEP_QA_RULE,
+    ...VEHICLE_QA_RULES,
+    ...ARCHITECTURE_QA_RULES,
+    ...ENVIRONMENT_QA_RULES,
+    ...VEGETATION_QA_RULES,
+    CHARACTER_QA_RULE,
+    CHARACTER_ADVISORY_QA_RULE,
+    VFX_EXACT_QA_RULE,
+    VFX_ADVISORY_QA_RULE,
+    ASSET_SCOPE_QA_RULE,
+]);
+function sceneDecisions(context, policy) {
+    const applicable = new Set(resolveRequirementsApplicability(context.requirements)
+        .rules.filter((rule) => rule.status === 'evaluate')
+        .map((rule) => rule.id));
+    return new QaRegistry(registry.list().filter((rule) => applicable.has(rule.id))).describePolicy(policy);
+}
+/** Async engine measurements; no authored declarations, images or category policy are read. */
+export async function collectRequirementsSceneEvidence(context, scene, policy = {}) {
+    if (!(scene instanceof Object3D) ||
+        !sceneDecisions(context, policy).some((d) => d.ruleId === SELF_INTERSECTION_QA_RULE.id && d.mode !== 'off'))
+        return {};
+    try {
+        return { partPenetration: await analyzePartPenetration(scene) };
+    }
+    catch {
+        // An optional observation can be unavailable; it cannot become a clean measurement.
+        return { partPenetrationFailed: true };
+    }
+}
+export function runRequirementsSceneQa(context, scene, clips, policy = {}, evidence = {}) {
+    const needs = context.requirements.requirements;
+    const parts = needs.parts?.state === 'requested' ? needs.parts.value.required : [];
+    const animation = needs.animation?.state === 'requested' ? needs.animation.value : undefined;
+    const rig = needs.rig?.state === 'requested' ? needs.rig.value : undefined;
+    const requiredClips = [
+        ...new Set([...(animation?.clips ?? []), ...(rig?.clips?.map((clip) => clip.name) ?? [])]),
+    ];
+    const tangents = needs.representation?.state === 'requested' &&
+        needs.representation.value.precomputedTangents === true;
+    const findings = [];
+    const decisions = sceneDecisions(context, policy);
+    const geometryMetrics = {};
+    const mobilityInput = {
+        scene,
+        mobility: needs.mobility?.state === 'requested' ? needs.mobility.value : undefined,
+        groundPlaneY: needs.grounding?.state === 'requested' ? needs.grounding.value.planeY : undefined,
+    };
+    // One measurement pass feeds the exact and advisory modes without re-deriving policy.
+    const mobilityFindings = mobilityInput.mobility &&
+        decisions.some((d) => (d.ruleId === 'VEHICLE_PROFILE' || d.ruleId === 'VEHICLE_ADVISORY_PROFILE') &&
+            d.mode !== 'off')
+        ? inspectMobility(mobilityInput)
+        : [];
+    const executedRules = [];
+    const rigInput = {
+        scene,
+        clips,
+        rig,
+        groundPlaneY: needs.grounding?.state === 'requested' ? needs.grounding.value.planeY : undefined,
+    };
+    const foliageInput = {
+        scene,
+        foliage: needs.foliage?.state === 'requested' ? needs.foliage.value : undefined,
+        materialMode: needs.material?.state === 'requested' ? needs.material.value.mode : undefined,
+        groundPlaneY: needs.grounding?.state === 'requested' ? needs.grounding.value.planeY : undefined,
+    };
+    const effects = needs.effects?.state === 'requested' ? needs.effects.value : undefined;
+    const scope = context.requirements.scope;
+    const scopeObservation = scope?.state === 'requested' &&
+        scene instanceof Object3D &&
+        decisions.some((d) => d.ruleId === ASSET_SCOPE_QA_RULE.id && d.mode !== 'off')
+        ? analyzeAssetScopeObservationV1(scene)
+        : undefined;
+    const effectsInput = {
+        effects,
+        derivedEvidence: {
+            source: 'engine-scene-analysis',
+            ...(effects &&
+                scene instanceof Object3D &&
+                decisions.some((d) => d.ruleId.startsWith('VFX_') && d.mode !== 'off')
+                ? { vfxArtifact: analyzeVfxArtifactEvidenceV1(effects, scene, clips) }
+                : {}),
+        },
+    };
+    const spatialInput = {
+        scene,
+        tileable: needs.tiling?.state === 'requested' ||
+            (needs.spatialLayout?.state === 'requested' && needs.spatialLayout.value.tileable === true),
+        navigable: needs.navigation?.state === 'requested' ||
+            (needs.spatialLayout?.state === 'requested' && needs.spatialLayout.value.navigable === true),
+        navigation: needs.navigation?.state === 'requested' ? needs.navigation.value : undefined,
+        groundPlaneY: needs.grounding?.state === 'requested' ? (needs.grounding.value.planeY ?? 0) : undefined,
+    };
+    const spatialFindings = decisions.some((d) => d.ruleId.startsWith('ENVIRONMENT_') && d.mode !== 'off')
+        ? [
+            ...inspectPlacementSockets(spatialInput),
+            ...inspectTileEdges(spatialInput),
+            ...inspectNavigationClearance(spatialInput),
+            ...inspectSpatialSupport(spatialInput),
+        ]
+        : [];
+    const structureFindings = needs.structure?.state === 'requested' &&
+        decisions.some((d) => d.ruleId.startsWith('ARCHITECTURE_') && d.mode !== 'off')
+        ? inspectStructure({
+            scene,
+            structure: needs.structure.value,
+            opening: needs.opening?.state === 'requested',
+        })
+        : [];
+    for (const decision of decisions) {
+        if (decision.mode === 'off')
+            continue;
+        if (decision.ruleId === SELF_INTERSECTION_QA_RULE.id) {
+            const volume = evidence.partPenetration;
+            if (volume) {
+                const acknowledged = volume.acknowledged?.length ?? 0;
+                // An acknowledged open shell leaves its pairs unmeasured as surely as a skipped part.
+                const partial = volume.truncated || volume.skipped.length > 0 || acknowledged > 0;
+                if (!partial)
+                    executedRules.push(decision.ruleId);
+                findings.push(...inspectPartPenetration(volume));
+                Object.assign(geometryMetrics, {
+                    partVolumeCoverage: partial ? 'partial' : 'complete-static-pairs',
+                    partVolumeScope: 'Visible static closed mesh pairs, except alternates on different LOD levels; excludes intra-mesh intersections, motion, open surfaces and usable passage space. Positive overlap may be intentional.',
+                    partVolumeEligibleParts: volume.partsAnalyzed,
+                    partVolumeCandidatePairs: volume.candidatePairs,
+                    partVolumeCandidatesLowerBound: volume.broadPhaseTruncated === true,
+                    partVolumePairsTested: volume.pairsTested,
+                    partVolumeUnmeasurablePairs: volume.pairsUnmeasurable,
+                    partVolumePairsNotReached: volume.pairsNotReached,
+                    partVolumeLodAlternatePairs: volume.pairsLodAlternates,
+                    partVolumeSkipped: volume.skipped.length,
+                    ...(acknowledged > 0
+                        ? {
+                            partVolumeAcknowledgedParts: acknowledged,
+                            partVolumeAcknowledgedPairs: volume.pairsUnmeasurableAcknowledged ?? 0,
+                        }
+                        : {}),
+                });
+            }
+            else if (evidence.partPenetrationFailed) {
+                findings.push({
+                    code: 'GEO_PART_SELF_INTERSECTION_UNMEASURED',
+                    disposition: 'observe',
+                    dimension: 'visualQuality',
+                    profile: 'geometry.selfIntersection',
+                    message: 'Part-volume analysis could not complete. Overlap and clearance remain unmeasured.',
+                });
+                geometryMetrics.partVolumeCoverage = 'unavailable';
+            }
+            continue;
+        }
+        if (decision.ruleId === ASSET_SCOPE_QA_RULE.id && !scopeObservation)
+            continue;
+        if (decision.ruleId === PART_CONNECTIVITY_QA_RULE.id && !(scene instanceof Object3D))
+            continue;
+        executedRules.push(decision.ruleId);
+        if (decision.ruleId === PROP_EXACT_QA_RULE.id) {
+            const measured = [
+                ...(needs.articulation?.state === 'requested' ? inspectArticulation({ scene }) : []),
+                ...(needs.opening?.state === 'requested' ? inspectContainerOpening({ scene }) : []),
+            ];
+            for (const finding of measured)
+                findings.push(decision.mode === 'observe' || decision.mode === 'warn'
+                    ? { ...finding, disposition: decision.mode }
+                    : finding);
+            continue;
+        }
+        const measured = decision.ruleId === SWEEP_QA_RULE.id
+            ? inspectSweepGeometry(scene)
+            : decision.ruleId === PART_CONNECTIVITY_QA_RULE.id
+                ? inspectPartConnectivity(scene)
+                : decision.ruleId === ASSET_SCOPE_QA_RULE.id && scope?.state === 'requested'
+                    ? inspectAssetScope({
+                        profile: 'asset.requirements.v1',
+                        scope: { schemaVersion: 1, scope: scope.value, explicit: true },
+                        derivedEvidence: { source: 'engine-scene-analysis', assetScope: scopeObservation },
+                    })
+                    : decision.ruleId === 'CHARACTER_PROFILE'
+                        ? inspectRig(rigInput)
+                        : decision.ruleId === 'CHARACTER_ADVISORY_PROFILE'
+                            ? inspectRigAdvisory(rigInput)
+                            : decision.ruleId === 'VEGETATION_CONTACT_PROFILE'
+                                ? inspectFoliageContact(foliageInput)
+                                : decision.ruleId === 'VEGETATION_ADVISORY_PROFILE'
+                                    ? inspectFoliageAdvisory(foliageInput)
+                                    : decision.ruleId === MATERIAL_QA_RULE.id
+                                        ? inspectPortableSceneMaterials(scene, tangents)
+                                        : decision.ruleId === 'VFX_EXACT_PROFILE'
+                                            ? inspectEffectsExact(effectsInput)
+                                            : decision.ruleId === 'VFX_ADVISORY_PROFILE'
+                                                ? inspectEffectsAdvisory(effectsInput)
+                                                : decision.ruleId === 'ARCHITECTURE_PROFILE'
+                                                    ? structureFindings.filter((f) => f.disposition === 'block')
+                                                    : decision.ruleId === 'ARCHITECTURE_ADVISORY_PROFILE'
+                                                        ? structureFindings.filter((f) => f.disposition !== 'block')
+                                                        : decision.ruleId === 'ENVIRONMENT_EXACT_PROFILE'
+                                                            ? spatialFindings.filter((f) => f.disposition === 'block')
+                                                            : decision.ruleId === 'ENVIRONMENT_ADVISORY_PROFILE'
+                                                                ? spatialFindings.filter((f) => f.disposition !== 'block')
+                                                                : decision.ruleId === 'VEHICLE_PROFILE'
+                                                                    ? mobilityFindings.filter((f) => f.disposition === 'block')
+                                                                    : decision.ruleId === 'VEHICLE_ADVISORY_PROFILE'
+                                                                        ? mobilityFindings.filter((f) => f.disposition !== 'block')
+                                                                        : decision.ruleId === 'VEHICLE_W6_ADVISORY_PROFILE'
+                                                                            ? inspectMobilityAdvisory(mobilityInput)
+                                                                            : decision.ruleId === PROP_ADVISORY_QA_RULE.id
+                                                                                ? inspectPlacement({
+                                                                                    scene,
+                                                                                    bounds: needs.bounds?.state === 'requested'
+                                                                                        ? needs.bounds.value
+                                                                                        : undefined,
+                                                                                    groundPlaneY: needs.grounding?.state === 'requested'
+                                                                                        ? (needs.grounding.value.planeY ?? 0)
+                                                                                        : undefined,
+                                                                                })
+                                                                                : UNIVERSAL_QA_KERNELS[decision.ruleId]({
+                                                                                    scene,
+                                                                                    clips,
+                                                                                    requiredParts: parts,
+                                                                                    animation: { clips: requiredClips },
+                                                                                });
+        for (const finding of measured)
+            findings.push(decision.mode === 'observe' || decision.mode === 'warn'
+                ? { ...finding, disposition: decision.mode }
+                : finding);
+    }
+    return createRequirementsQaReport(context, {
+        findings,
+        executedRules,
+        modes: Object.fromEntries(decisions.map((x) => [x.ruleId, x.mode])),
+        metrics: {
+            ...(Object.keys(geometryMetrics).length ? { visualQuality: geometryMetrics } : {}),
+            ...(scopeObservation
+                ? {
+                    promptAlignment: {
+                        scopeTopLevelAssetRoots: scopeObservation.topLevelAssetRoots,
+                        scopeReusableMemberCount: scopeObservation.reusableMemberCount,
+                        scopeDressingSignalCount: scopeObservation.sceneDressingRoles.length,
+                    },
+                }
+                : {}),
+        },
+        ...(scopeObservation
+            ? {
+                evaluatedDimensions: ['exportIntegrity', 'requirementReadiness', 'promptAlignment'],
+            }
+            : {}),
+    });
+}
+/** Rebuild the same report without losing applicability, modes or unmet obligations. */
+export function appendRequirementsQa(context, report, findings, metrics = {}) {
+    const priorMetrics = Object.fromEntries(Object.entries(report.dimensions).flatMap(([dimension, value]) => value.metrics ? [[dimension, value.metrics]] : []));
+    const merged = { ...priorMetrics };
+    for (const [dimension, value] of Object.entries(metrics ?? {}))
+        merged[dimension] = { ...priorMetrics[dimension], ...value };
+    return createRequirementsQaReport(context, {
+        findings: [...Object.values(report.dimensions).flatMap((x) => x.findings), ...findings],
+        executedRules: report.rules.filter((x) => x.status === 'evaluated').map((x) => x.id),
+        modes: Object.fromEntries(report.rules.map((x) => [x.id, x.mode])),
+        evaluatedDimensions: [
+            ...new Set([
+                ...Object.entries(report.dimensions)
+                    .filter(([, value]) => value.status !== 'notEvaluated')
+                    .map(([key]) => key),
+                ...Object.keys(metrics ?? {}),
+            ]),
+        ],
+        metrics: merged,
+    });
+}
+/** Final-byte and runtime measurements remain separate from acceptance obligations. */
+export async function appendRequirementsFinalQa(context, report, gltf, bytes, instanceability, metricsError, material, warnings = []) {
+    const gltfFindings = gltfReportFindings(gltf, report.qaProfile);
+    const findings = [
+        ...gltfFindings,
+        ...warnings.map((w) => ({
+            code: w.code,
+            disposition: 'warn',
+            dimension: 'runtimeCost',
+            profile: `${w.profile}.${w.tier}`,
+            message: `${w.message} ${w.advice}`,
+            measurement: w.measurement,
+        })),
+    ];
+    if (metricsError)
+        findings.push({
+            code: 'RUNTIME_COST_METRICS_FAILED',
+            disposition: 'warn',
+            dimension: 'runtimeCost',
+            profile: report.qaProfile,
+            message: `Runtime-cost metrics could not be computed: ${metricsError}`,
+        });
+    const cost = {};
+    if (instanceability)
+        Object.assign(cost, {
+            instanceabilityGrade: instanceability.grade,
+            instanceabilitySummary: instanceability.summary,
+            ...instanceability.metrics,
+        });
+    if (material)
+        Object.assign(cost, {
+            materialCount: material.materialCount,
+            opaqueMaterials: material.opaqueMaterials,
+            maskedMaterials: material.maskedMaterials,
+            blendedMaterials: material.blendedMaterials,
+            singleSidedMaterials: material.singleSidedMaterials,
+            doubleSidedMaterials: material.doubleSidedMaterials,
+            texturedMaterials: material.texturedMaterials,
+            materialExtensionCount: material.materialExtensionCount,
+            materialExtensionsUsed: material.materialExtensionsUsed.join(','),
+            imageCount: material.imageCount,
+            maxImageDimension: material.maxImageDimension,
+            decodedImageBytesRgba8: material.decodedImageBytesRgba8,
+            estimatedGpuBytesWithMipmaps: material.estimatedGpuBytesWithMipmaps,
+            blendedSurfaceAreaRatio: material.blendedSurfaceAreaRatio,
+        });
+    let result = appendRequirementsQa(context, report, findings, {
+        exportIntegrity: {
+            gltfErrors: gltf.issues.numErrors,
+            gltfWarnings: gltfFindings.filter((x) => x.disposition === 'warn').length,
+        },
+        runtimeCost: cost,
+    });
+    const effects = context.requirements.requirements.effects;
+    const rule = report.rules.find((r) => r.id === 'VFX_EXACT_PROFILE');
+    if (effects?.state === 'requested' && rule?.status === 'evaluated' && rule.mode !== 'off') {
+        const evidence = await analyzeFinalVfxGlbBytesV1(bytes);
+        const measured = inspectFinalEffects(effects.value, evidence);
+        const findings = rule.mode === 'enforce'
+            ? measured
+            : measured.map((f) => ({
+                ...f,
+                disposition: rule.mode,
+            }));
+        result = appendRequirementsQa(context, result, findings, {
+            exportIntegrity: finalEffectsMetrics(evidence),
+        });
+    }
+    return result;
+}

package/lib/qa/run.d.ts

@@ -0,0 +1,54 @@
+import type { AssetIntentV1 } from "../contracts/index.js";
+import type { InstanceabilityReport } from "../metrics.js";
+import { type ReferenceComparisonEvidenceV1 } from "./reference-comparison.js";
+import { QaRegistry, type QaRulePolicy } from "./registry.js";
+import { type AssetQaReportV1, type AssetQaReport, type QaContext, type QaFinding } from "./types.js";
+import type { KhronosGltfValidationReport } from "./gltf.js";
+import type { MaterialBudgetWarningV1, MaterialMetricsV1 } from "../material-metrics.js";
+export declare const DETERMINISTIC_QA_REGISTRY: QaRegistry;
+export declare function runDeterministicSceneQa(context: QaContext, policy?: QaRulePolicy): AssetQaReportV1;
+export declare function gltfReportFindings(report: KhronosGltfValidationReport, profile: string): QaFinding[];
+export declare function appendFinalGltfQa(intent: AssetIntentV1, sceneReport: AssetQaReportV1, gltfReport: KhronosGltfValidationReport): AssetQaReportV1;
+/**
+ * Attach the existing A–F instanceability result only to the runtime-cost
+ * dimension. It is deliberately not promoted to a composite quality grade.
+ */
+export declare function appendRuntimeCostQa(intent: AssetIntentV1, report: AssetQaReportV1, instanceability?: InstanceabilityReport, metricsError?: string): AssetQaReportV1;
+/** Attach portable material metrics and advisory budget findings to runtimeCost
+ * without collapsing them into the independent instanceability grade. */
+export declare function appendMaterialMetricsQa(intent: AssetIntentV1, report: AssetQaReportV1, materialMetrics: MaterialMetricsV1, budgetWarnings?: readonly MaterialBudgetWarningV1[]): AssetQaReportV1;
+/**
+ * Attach reference-image agreement to promptAlignment.
+ *
+ * A separate appender rather than evidence on the pre-export context, because
+ * the rendered views this compares against do not exist until after the GLB is
+ * written — the scene QA pass runs strictly earlier. The findings come from
+ * {@link referenceComparisonFindings}, the same code the registered rule uses,
+ * so the two paths cannot drift into different opinions about disagreement.
+ *
+ * Observe-only, so this can never turn a passing asset into a blocked one; the
+ * dimension status it produces is at worst unchanged.
+ */
+export declare function appendReferenceComparisonQa(intent: AssetIntentV1, report: AssetQaReportV1, evidence: ReferenceComparisonEvidenceV1): AssetQaReportV1;
+/**
+ * Ops kill switch (H-40): `KILN_QA_MODE=observe|off` overrides every rule's
+ * default mode, feeding the registry's otherwise-unfed {@link QaRulePolicy}.
+ * DOWNGRADE-ONLY by design: 'observe'/'off' are always authorized, while
+ * 'warn'/'enforce' would throw mid-render on rules whose promotion evidence
+ * doesn't authorize them — promotion stays a code change, not an env flip.
+ * Unset or an unrecognized value = ship defaults (exact rules at enforce).
+ */
+export declare function qaPolicyFromEnv(env?: Record<string, string | undefined>): QaRulePolicy;
+/**
+ * Whether a `disposition: 'block'` QA report may abort a render. False under
+ * `KILN_QA_MODE=observe|off` — the emergency downgrade for a misfiring rule in
+ * prod: reports still record block dispositions (telemetry stays honest), but
+ * the render completes with a warning instead of throwing.
+ */
+export declare function qaBlockingEnabled(env?: Record<string, string | undefined>): boolean;
+export declare class AssetQaBlockedError extends Error {
+    readonly report: AssetQaReport;
+    readonly stage: 'scene' | 'final-glb';
+    readonly gltfValidation?: KhronosGltfValidationReport;
+    constructor(report: AssetQaReport, stage: 'scene' | 'final-glb', gltfValidation?: KhronosGltfValidationReport);
+}

package/lib/qa/run.js

@@ -0,0 +1,240 @@
+import { MATERIAL_QA_RULE } from "./material.js";
+import { ARCHITECTURE_QA_RULES } from "./architecture.js";
+import { CHARACTER_QA_RULE } from "./character.js";
+import { CHARACTER_ADVISORY_QA_RULE } from "./character-advisory.js";
+import { VEHICLE_QA_RULES } from "./vehicle.js";
+import { VEGETATION_QA_RULES } from "./vegetation.js";
+import { PROP_QA_RULES } from "./prop.js";
+import { PART_CONNECTIVITY_QA_RULE } from "./part-connectivity.js";
+import { REFERENCE_COMPARISON_QA_RULE, referenceComparisonFindings, } from "./reference-comparison.js";
+import { SELF_INTERSECTION_QA_RULE } from "./self-intersection.js";
+import { SWEEP_QA_RULE } from "./sweep.js";
+import { ENVIRONMENT_QA_RULES } from "./environment.js";
+import { W7_BREADTH_QA_RULES } from "./breadth.js";
+import { withDerivedW7BreadthEvidence } from "./breadth-evidence.js";
+import { QaRegistry } from "./registry.js";
+import { createAssetQaReportV1, } from "./types.js";
+import { UNIVERSAL_QA_RULES } from "./universal.js";
+export const DETERMINISTIC_QA_REGISTRY = new QaRegistry([
+    ...UNIVERSAL_QA_RULES,
+    MATERIAL_QA_RULE,
+    ...ARCHITECTURE_QA_RULES,
+    CHARACTER_QA_RULE,
+    CHARACTER_ADVISORY_QA_RULE,
+    ...VEHICLE_QA_RULES,
+    ...VEGETATION_QA_RULES,
+    ...PROP_QA_RULES,
+    ...ENVIRONMENT_QA_RULES,
+    ...W7_BREADTH_QA_RULES,
+    SELF_INTERSECTION_QA_RULE,
+    SWEEP_QA_RULE,
+    PART_CONNECTIVITY_QA_RULE,
+    REFERENCE_COMPARISON_QA_RULE,
+]);
+export function runDeterministicSceneQa(context, policy = {}) {
+    const result = DETERMINISTIC_QA_REGISTRY.run(withDerivedW7BreadthEvidence(context), policy);
+    return createAssetQaReportV1(context.intent, {
+        findings: result.findings,
+        evaluatedDimensions: ['exportIntegrity', 'categoryReadiness'],
+    });
+}
+export function gltfReportFindings(report, profile) {
+    return report.issues.messages
+        .filter((issue) => issue.severity === 0 || issue.severity === 1)
+        .filter((issue) => !isExpectedKtx2ValidatorLimitation(report, issue))
+        .map((issue) => ({
+        code: `GLTF_${issue.code}`.replace(/[^A-Z0-9_]/g, '_'),
+        disposition: issue.severity === 0 ? 'block' : 'warn',
+        dimension: 'exportIntegrity',
+        profile,
+        message: issue.message,
+        ...(issue.pointer ? { affected: { nodePath: issue.pointer } } : {}),
+    }));
+}
+/** gltf-validator 2.0.0-dev.3.10 does not understand the image/ktx2 MIME used by
+ * KHR_texture_basisu. Ignore only its exact, pointer-bound false warnings when
+ * the artifact explicitly requires that extension; every other warning remains. */
+function isExpectedKtx2ValidatorLimitation(report, issue) {
+    const required = report.info?.['extensionsRequired'];
+    if (!Array.isArray(required) || !required.includes('KHR_texture_basisu'))
+        return false;
+    if (issue.code === 'VALUE_NOT_IN_LIST') {
+        return (/^\/images\/\d+\/mimeType$/.test(issue.pointer ?? '') &&
+            issue.message === "Invalid value 'image/ktx2'. Valid values are ('image/jpeg', 'image/png').");
+    }
+    return (issue.code === 'IMAGE_UNRECOGNIZED_FORMAT' &&
+        /^\/images\/\d+$/.test(issue.pointer ?? '') &&
+        issue.message === 'Image format not recognized.');
+}
+export function appendFinalGltfQa(intent, sceneReport, gltfReport) {
+    const findings = Object.values(sceneReport.dimensions).flatMap((dimension) => dimension.findings);
+    const gltfFindings = gltfReportFindings(gltfReport, intent.qaProfile);
+    findings.push(...gltfFindings);
+    return createAssetQaReportV1(intent, {
+        findings,
+        evaluatedDimensions: ['exportIntegrity', 'categoryReadiness'],
+        metrics: {
+            exportIntegrity: {
+                gltfErrors: gltfReport.issues.numErrors,
+                gltfWarnings: gltfFindings.filter((finding) => finding.disposition === 'warn').length,
+            },
+        },
+    });
+}
+/**
+ * Attach the existing A–F instanceability result only to the runtime-cost
+ * dimension. It is deliberately not promoted to a composite quality grade.
+ */
+export function appendRuntimeCostQa(intent, report, instanceability, metricsError) {
+    const findings = Object.values(report.dimensions).flatMap((dimension) => dimension.findings);
+    if (metricsError) {
+        findings.push({
+            code: 'RUNTIME_COST_METRICS_FAILED',
+            disposition: 'warn',
+            dimension: 'runtimeCost',
+            profile: intent.qaProfile,
+            message: `Runtime-cost metrics could not be computed: ${metricsError}`,
+        });
+    }
+    const evaluatedDimensions = Object.entries(report.dimensions)
+        .filter(([, dimension]) => dimension.status !== 'notEvaluated')
+        .map(([dimension]) => dimension);
+    evaluatedDimensions.push('runtimeCost');
+    const metrics = Object.fromEntries(Object.entries(report.dimensions).flatMap(([dimension, result]) => result.metrics ? [[dimension, result.metrics]] : []));
+    if (instanceability) {
+        metrics.runtimeCost = {
+            instanceabilityGrade: instanceability.grade,
+            instanceabilitySummary: instanceability.summary,
+            uniqueGeometries: instanceability.metrics.uniqueGeometries,
+            uniqueMaterials: instanceability.metrics.uniqueMaterials,
+            drawCalls: instanceability.metrics.drawCalls,
+            textureCount: instanceability.metrics.textureCount,
+            transparentMaterials: instanceability.metrics.transparentMaterials,
+            triangles: instanceability.metrics.triangles,
+            skinned: instanceability.metrics.skinned,
+        };
+    }
+    return createAssetQaReportV1(intent, {
+        findings,
+        evaluatedDimensions,
+        ...(Object.keys(metrics).length > 0 ? { metrics } : {}),
+    });
+}
+/** Attach portable material metrics and advisory budget findings to runtimeCost
+ * without collapsing them into the independent instanceability grade. */
+export function appendMaterialMetricsQa(intent, report, materialMetrics, budgetWarnings = []) {
+    const findings = Object.values(report.dimensions).flatMap((dimension) => dimension.findings);
+    findings.push(...budgetWarnings.map((warning) => ({
+        code: warning.code,
+        disposition: 'warn',
+        dimension: 'runtimeCost',
+        profile: `${warning.profile}.${warning.tier}`,
+        message: `${warning.message} ${warning.advice}`,
+        measurement: warning.measurement,
+    })));
+    const evaluatedDimensions = Object.entries(report.dimensions)
+        .filter(([, dimension]) => dimension.status !== 'notEvaluated')
+        .map(([dimension]) => dimension);
+    if (!evaluatedDimensions.includes('runtimeCost'))
+        evaluatedDimensions.push('runtimeCost');
+    const metrics = Object.fromEntries(Object.entries(report.dimensions).flatMap(([dimension, result]) => result.metrics ? [[dimension, result.metrics]] : []));
+    metrics.runtimeCost = {
+        ...(metrics.runtimeCost ?? {}),
+        materialCount: materialMetrics.materialCount,
+        opaqueMaterials: materialMetrics.opaqueMaterials,
+        maskedMaterials: materialMetrics.maskedMaterials,
+        blendedMaterials: materialMetrics.blendedMaterials,
+        singleSidedMaterials: materialMetrics.singleSidedMaterials,
+        doubleSidedMaterials: materialMetrics.doubleSidedMaterials,
+        texturedMaterials: materialMetrics.texturedMaterials,
+        materialExtensionCount: materialMetrics.materialExtensionCount,
+        materialExtensionsUsed: materialMetrics.materialExtensionsUsed.join(','),
+        imageCount: materialMetrics.imageCount,
+        maxImageDimension: materialMetrics.maxImageDimension,
+        decodedImageBytesRgba8: materialMetrics.decodedImageBytesRgba8,
+        estimatedGpuBytesWithMipmaps: materialMetrics.estimatedGpuBytesWithMipmaps,
+        blendedSurfaceAreaRatio: materialMetrics.blendedSurfaceAreaRatio,
+    };
+    return createAssetQaReportV1(intent, { findings, evaluatedDimensions, metrics });
+}
+/**
+ * Attach reference-image agreement to promptAlignment.
+ *
+ * A separate appender rather than evidence on the pre-export context, because
+ * the rendered views this compares against do not exist until after the GLB is
+ * written — the scene QA pass runs strictly earlier. The findings come from
+ * {@link referenceComparisonFindings}, the same code the registered rule uses,
+ * so the two paths cannot drift into different opinions about disagreement.
+ *
+ * Observe-only, so this can never turn a passing asset into a blocked one; the
+ * dimension status it produces is at worst unchanged.
+ */
+export function appendReferenceComparisonQa(intent, report, evidence) {
+    const findings = Object.values(report.dimensions).flatMap((dimension) => dimension.findings);
+    findings.push(...referenceComparisonFindings(evidence, 'reference.comparison'));
+    const evaluatedDimensions = Object.entries(report.dimensions)
+        .filter(([, dimension]) => dimension.status !== 'notEvaluated')
+        .map(([dimension]) => dimension);
+    if (!evaluatedDimensions.includes('promptAlignment'))
+        evaluatedDimensions.push('promptAlignment');
+    const metrics = Object.fromEntries(Object.entries(report.dimensions).flatMap(([dimension, result]) => result.metrics ? [[dimension, result.metrics]] : []));
+    metrics.promptAlignment = {
+        ...(metrics.promptAlignment ?? {}),
+        referenceSilhouetteIoU: evidence.silhouetteIoU,
+        referenceColorAgreement: evidence.colorAgreement,
+        referenceCoverageRatio: evidence.coverageRatio,
+        // Surfaced because a reference with no rejected shadow pixels is either a
+        // cutout or flat-lit, and the coverage numbers mean something different then.
+        referenceShadowPixels: evidence.reference.shadowPixels,
+    };
+    return createAssetQaReportV1(intent, { findings, evaluatedDimensions, metrics });
+}
+/**
+ * Ops kill switch (H-40): `KILN_QA_MODE=observe|off` overrides every rule's
+ * default mode, feeding the registry's otherwise-unfed {@link QaRulePolicy}.
+ * DOWNGRADE-ONLY by design: 'observe'/'off' are always authorized, while
+ * 'warn'/'enforce' would throw mid-render on rules whose promotion evidence
+ * doesn't authorize them — promotion stays a code change, not an env flip.
+ * Unset or an unrecognized value = ship defaults (exact rules at enforce).
+ */
+export function qaPolicyFromEnv(env = process.env) {
+    const mode = env['KILN_QA_MODE'];
+    return mode === 'observe' || mode === 'off' ? { defaultMode: mode } : {};
+}
+/**
+ * Whether a `disposition: 'block'` QA report may abort a render. False under
+ * `KILN_QA_MODE=observe|off` — the emergency downgrade for a misfiring rule in
+ * prod: reports still record block dispositions (telemetry stays honest), but
+ * the render completes with a warning instead of throwing.
+ */
+export function qaBlockingEnabled(env = process.env) {
+    const mode = env['KILN_QA_MODE'];
+    return mode !== 'observe' && mode !== 'off';
+}
+/** Blockers spelled out in full per message; the rest collapse to a count. */
+const MAX_DETAILED_BLOCKERS = 6;
+export class AssetQaBlockedError extends Error {
+    report;
+    stage;
+    gltfValidation;
+    constructor(report, stage, gltfValidation) {
+        const blockers = Object.values(report.dimensions)
+            .flatMap((dimension) => dimension.findings)
+            .filter((finding) => finding.disposition === 'block');
+        // H-40(3): this message IS what the agent reads when a mid-loop render is
+        // QA-blocked (kiln_render catches and returns { ok:false, error: message }),
+        // Include the measured target as quoted data as well as repair advice.
+        // Some messages (for example missing UVs) contain no part identity of their own.
+        const detailed = blockers
+            .slice(0, MAX_DETAILED_BLOCKERS)
+            .map((finding) => `${finding.code}: ${finding.message}${finding.affected ? ` AFFECTED: ${JSON.stringify(finding.affected)}` : ''}${finding.repairText ? ` FIX: ${finding.repairText}` : ''}`);
+        const overflow = blockers.length > MAX_DETAILED_BLOCKERS
+            ? ` (+${blockers.length - MAX_DETAILED_BLOCKERS} more blockers)`
+            : '';
+        super(`Asset QA blocked at ${stage}: ${detailed.join(' | ') || 'unknown blocker'}${overflow}`);
+        this.name = 'AssetQaBlockedError';
+        this.report = report;
+        this.stage = stage;
+        this.gltfValidation = gltfValidation;
+    }
+}