check-dropped-frame-ears.ts

#!/usr/bin/env tsx
// SPDX-License-Identifier: AGPL-3.0-or-later
// Copyright (c) 2025-2026 Matthew Kissinger

import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
import { join, relative, resolve } from 'node:path';
import { pathToFileURL } from 'node:url';

type CheckStatus = 'pass' | 'warn' | 'fail';
export type DroppedFrameEarsClassification = 'proven' | 'diagnostic' | 'rejected';
type RequiredScenario = 'open_frontier' | 'a_shau_valley';

export interface DroppedFrameEarsCheck {
  id: string;
  status: CheckStatus;
  message: string;
  value?: string | number | boolean | null;
}

export interface DroppedFrameEarsArtifactEvaluation {
  artifactDir: string;
  artifactRelPath: string;
  scenario: string | null;
  classification: DroppedFrameEarsClassification;
  contactQualified: boolean;
  materializationQualified: boolean;
  completionLaneQualified: boolean;
  criticalPass: boolean;
  failCount: number;
  warnCount: number;
  checks: DroppedFrameEarsCheck[];
}

export interface DroppedFrameEarsEvaluation {
  status: CheckStatus;
  requiredScenarios: readonly RequiredScenario[];
  passingScenarios: RequiredScenario[];
  missingScenarios: RequiredScenario[];
  artifacts: DroppedFrameEarsArtifactEvaluation[];
}

type ValidationCheck = {
  id?: string;
  status?: CheckStatus;
  value?: unknown;
  message?: string;
};

type ThresholdCheck = {
  id: string;
  maxExclusive: number;
  fallbackPath: readonly string[];
  label: string;
};

type BooleanRuntimeFlag = {
  id: string;
  path: readonly string[];
  equals?: boolean | string;
  message: string;
};

const ARTIFACT_ROOT = join(process.cwd(), 'artifacts', 'perf');
const REQUIRED_SCENARIOS = ['open_frontier', 'a_shau_valley'] as const satisfies readonly RequiredScenario[];
const REQUIRED_FILES = [
  'summary.json',
  'validation.json',
  'measurement-trust.json',
  'presentation-epochs.json',
  'runtime-render-submission-samples.json',
  'final-frame.png',
] as const;

const MIN_SUSTAINED_MATERIALIZATION_SAMPLES = 3;
const MIN_SUSTAINED_MATERIALIZATION_RATIO = 0.1;
const MIN_SUSTAINED_COMBAT_SHOT_INCREASE_SAMPLES = 3;
const MIN_SUSTAINED_COMBAT_SHOT_INCREASE_RATIO = 0.05;
const RENDER_MAIN_RENDER_WARN_MS = 33;
const RENDER_MAIN_RENDER_FAIL_MS = 100;
const ATMOSPHERE_SYNC_WARN_MS = 4;
const ATMOSPHERE_SYNC_FAIL_MS = 16;
const RENDERER_RESOURCE_TEXTURE_JUMP_WARN = 16;
const RENDERER_RESOURCE_GEOMETRY_JUMP_WARN = 16;
const RENDERER_RESOURCE_PROGRAM_JUMP_WARN = 2;
const COMBAT_FIRE_TERRAIN_BLOCK_MIN_REQUESTS = 10;
const COMBAT_FIRE_TERRAIN_BLOCK_WARN_RATE = 0.25;
const COMBAT_FIRE_TERRAIN_BLOCK_FAIL_RATE = 0.5;

const RAF_THRESHOLDS: readonly ThresholdCheck[] = [
  {
    id: 'raf_stutter_25ms_percent',
    maxExclusive: 0.5,
    fallbackPath: ['droppedFrameMetrics', 'browserRaf', 'stutter25Percent'],
    label: 'rAF gaps >25ms percent',
  },
  {
    id: 'raf_hitch_33ms_percent',
    maxExclusive: 0.25,
    fallbackPath: ['droppedFrameMetrics', 'browserRaf', 'hitch33Percent'],
    label: 'rAF gaps >33ms percent',
  },
  {
    id: 'raf_estimated_dropped_60hz_frames_per_second',
    maxExclusive: 0.1,
    fallbackPath: ['droppedFrameMetrics', 'browserRaf', 'estimatedDropped60HzFramesPerSecond'],
    label: 'estimated dropped 60Hz frames per second',
  },
  {
    id: 'raf_dropped_frame_time_60hz_ms_per_second',
    maxExclusive: 1,
    fallbackPath: ['droppedFrameMetrics', 'browserRaf', 'droppedFrameTime60HzMsPerSecond'],
    label: 'dropped-frame time over 60Hz budget per second',
  },
];

const HARNESS_EQUIVALENCE_IDS = [
  'harness_route_snap_trust',
  'harness_frontline_compression_equivalence',
  'harness_movement_mode_equivalence',
  'harness_view_slew_request_equivalence',
  'harness_shot_presentation_context_equivalence',
] as const;

const FORBIDDEN_RUNTIME_FLAGS: readonly BooleanRuntimeFlag[] = [
  {
    id: 'presentation_context_capture_disabled',
    path: ['perfRuntime', 'presentationContextCapture'],
    equals: false,
    message: 'rich presentation context capture is disabled',
  },
  {
    id: 'frontline_compression_requested',
    path: ['perfRuntime', 'frontlineCompressionRequested'],
    message: 'frontline compression was requested',
  },
  {
    id: 'npc_close_models_disabled',
    path: ['perfRuntime', 'npcCloseModelsDisabled'],
    message: 'close NPC models are disabled',
  },
  {
    id: 'terrain_shadows_disabled',
    path: ['perfRuntime', 'terrainShadowsDisabled'],
    message: 'terrain shadows are disabled',
  },
  {
    id: 'terrain_full_shadow_pass_enabled',
    path: ['perfRuntime', 'terrainFullShadowPassEnabled'],
    message: 'full terrain shadow pass is a diagnostic variant',
  },
  {
    id: 'bounded_terrain_shadow_pass_requested',
    path: ['perfRuntime', 'boundedTerrainShadowPassRequested'],
    message: 'bounded terrain shadow pass was explicitly requested as a diagnostic flag',
  },
  {
    id: 'terrain_force_instance_upload_enabled',
    path: ['perfRuntime', 'terrainForceInstanceUploadEnabled'],
    message: 'terrain instance uploads are forced',
  },
  {
    id: 'terrain_height_aware_frustum_requested',
    path: ['perfRuntime', 'terrainHeightAwareFrustumRequested'],
    message: 'height-aware terrain frustum was explicitly requested as a diagnostic flag',
  },
  {
    id: 'terrain_height_bounds_heuristic_enabled',
    path: ['perfRuntime', 'terrainHeightBoundsSource'],
    equals: 'heuristic-samples',
    message: 'heuristic-sampled terrain height bounds are diagnostic-only',
  },
  {
    id: 'terrain_full_skirts_requested',
    path: ['perfRuntime', 'terrainFullSkirtsRequested'],
    message: 'legacy full terrain skirts are explicitly requested',
  },
  {
    id: 'terrain_sparse_skirts_requested',
    path: ['perfRuntime', 'terrainSparseSkirtsRequested'],
    message: 'adaptive terrain skirts are explicitly requested by diagnostic flag',
  },
  {
    id: 'terrain_skirts_disabled',
    path: ['perfRuntime', 'terrainSkirtsDisabled'],
    message: 'terrain skirts are disabled',
  },
  {
    id: 'terrain_far_canopy_tint_disabled',
    path: ['perfRuntime', 'terrainFarCanopyTintDisabled'],
    message: 'far-canopy terrain tint is disabled',
  },
  {
    id: 'terrain_low_sun_occlusion_disabled',
    path: ['perfRuntime', 'terrainLowSunOcclusionDisabled'],
    message: 'low-sun terrain occlusion is disabled',
  },
  {
    id: 'wildlife_disabled',
    path: ['perfRuntime', 'wildlifeDisabled'],
    message: 'wildlife is disabled',
  },
];

const FORBIDDEN_QUERY_FLAGS = [
  'perfDisableNpcCloseModels',
  'perfDisableTerrainShadows',
  'perfBoundedTerrainShadowPass',
  'terrainFullShadowPass',
  'terrainForceInstanceUpload',
  'terrainEnableHeightAwareFrustum',
  'perfTerrainHeightAwareFrustum',
  'terrainFullTerrainSkirts',
  'terrainSparseTerrainSkirts',
  'perfDisableTerrainSkirts',
  'perfDisableTerrainFarCanopyTint',
  'perfDisableTerrainLowSunOcclusion',
  'perfDisableWildlife',
] as const;

function asRecord(value: unknown): Record<string, unknown> | null {
  return value !== null && typeof value === 'object' && !Array.isArray(value)
    ? value as Record<string, unknown>
    : null;
}

function asArray(value: unknown): unknown[] {
  return Array.isArray(value) ? value : [];
}

function getRendererCounter(sample: unknown, key: 'textures' | 'geometries' | 'programs'): number | null {
  const renderer = asRecord(asRecord(sample)?.renderer);
  const value = renderer?.[key];
  return typeof value === 'number' && Number.isFinite(value) ? value : null;
}

function readJsonObject(path: string): Record<string, unknown> | null {
  if (!existsSync(path)) return null;
  try {
    return asRecord(JSON.parse(readFileSync(path, 'utf-8')));
  } catch {
    return null;
  }
}

function readJsonArray(path: string): unknown[] | null {
  if (!existsSync(path)) return null;
  try {
    const parsed = JSON.parse(readFileSync(path, 'utf-8'));
    return Array.isArray(parsed) ? parsed : null;
  } catch {
    return null;
  }
}

function getPath(root: Record<string, unknown> | null, path: readonly string[]): unknown {
  let cursor: unknown = root;
  for (const part of path) {
    const record = asRecord(cursor);
    if (!record) return undefined;
    cursor = record[part];
  }
  return cursor;
}

function getString(root: Record<string, unknown> | null, path: readonly string[]): string | null {
  const value = getPath(root, path);
  return typeof value === 'string' ? value : null;
}

function getNumber(root: Record<string, unknown> | null, path: readonly string[]): number | null {
  const value = getPath(root, path);
  return typeof value === 'number' && Number.isFinite(value) ? value : null;
}

function getBoolean(root: Record<string, unknown> | null, path: readonly string[]): boolean | null {
  const value = getPath(root, path);
  return typeof value === 'boolean' ? value : null;
}

function getValidationChecks(validation: Record<string, unknown> | null, summary: Record<string, unknown> | null): ValidationCheck[] {
  const directChecks = asArray(getPath(validation, ['checks']));
  const summaryChecks = asArray(getPath(summary, ['validation', 'checks']));
  const checks = directChecks.length > 0 ? directChecks : summaryChecks;
  return checks
    .map((value) => asRecord(value))
    .filter((value): value is Record<string, unknown> => value !== null)
    .map((value) => ({
      id: typeof value.id === 'string' ? value.id : undefined,
      status: value.status === 'pass' || value.status === 'warn' || value.status === 'fail'
        ? value.status
        : undefined,
      value: value.value,
      message: typeof value.message === 'string' ? value.message : undefined,
    }));
}

function validationCheck(checks: readonly ValidationCheck[], id: string): ValidationCheck | null {
  return checks.find((check) => check.id === id) ?? null;
}

function checkPassed(checks: readonly DroppedFrameEarsCheck[], id: string): boolean {
  return checks.some((check) => check.id === id && check.status === 'pass');
}

function checkStatus(status: boolean, id: string, passMessage: string, failMessage: string, value?: DroppedFrameEarsCheck['value']): DroppedFrameEarsCheck {
  return {
    id,
    status: status ? 'pass' : 'fail',
    message: status ? passMessage : failMessage,
    value,
  };
}

function closeEnough(actual: number | null, expected: number | null): boolean {
  if (actual === null || expected === null || !Number.isFinite(actual) || !Number.isFinite(expected)) {
    return false;
  }
  const tolerance = Math.max(0.01, Math.abs(expected) * 0.000001);
  return Math.abs(actual - expected) <= tolerance;
}

function formatPercent(value: number | null): string {
  return value === null ? 'missing' : `${(value * 100).toFixed(1)}%`;
}

function rel(path: string): string {
  return relative(process.cwd(), path).replaceAll('\\', '/');
}

function isRequiredScenario(value: string | null): value is RequiredScenario {
  return value === 'open_frontier' || value === 'a_shau_valley';
}

function validationOverall(validation: Record<string, unknown> | null, summary: Record<string, unknown> | null): string | null {
  return getString(validation, ['overall']) ?? getString(summary, ['validation', 'overall']);
}

function measurementTrustStatus(measurementTrust: Record<string, unknown> | null, summary: Record<string, unknown> | null): string | null {
  return getString(measurementTrust, ['status']) ?? getString(summary, ['measurementTrust', 'status']);
}

function rendererResolvedBackend(measurementTrust: Record<string, unknown> | null, summary: Record<string, unknown> | null): string | null {
  return getString(summary, ['rendererBackend', 'resolvedBackend'])
    ?? getString(summary, ['measurementTrust', 'rendererBackend', 'resolvedBackend'])
    ?? getString(measurementTrust, ['rendererBackend', 'resolvedBackend']);
}

function rendererStrictWebGpu(measurementTrust: Record<string, unknown> | null, summary: Record<string, unknown> | null): boolean {
  return getBoolean(summary, ['rendererBackend', 'strictWebGPU'])
    ?? getBoolean(summary, ['measurementTrust', 'rendererBackend', 'strictWebGPU'])
    ?? getBoolean(measurementTrust, ['rendererBackend', 'strictWebGPU'])
    ?? false;
}

function urlSearchParams(summary: Record<string, unknown> | null): URLSearchParams | null {
  const rawUrl = getString(summary, ['url']);
  if (!rawUrl) return null;
  try {
    return new URL(rawUrl).searchParams;
  } catch {
    return null;
  }
}

function addRequiredFileChecks(artifactDir: string, checks: DroppedFrameEarsCheck[]): void {
  for (const fileName of REQUIRED_FILES) {
    const path = join(artifactDir, fileName);
    const present = existsSync(path);
    checks.push(checkStatus(
      present,
      `required_file_${fileName.replaceAll('.', '_').replaceAll('-', '_')}`,
      `${fileName} is present`,
      `${fileName} is missing`,
      present
    ));
  }
}

function addRafChecks(
  checks: DroppedFrameEarsCheck[],
  validationChecks: readonly ValidationCheck[],
  summary: Record<string, unknown> | null
): void {
  for (const threshold of RAF_THRESHOLDS) {
    const fromValidation = validationCheck(validationChecks, threshold.id);
    const value = typeof fromValidation?.value === 'number'
      ? fromValidation.value
      : getNumber(summary, threshold.fallbackPath);
    const passed = value !== null && value < threshold.maxExclusive;
    checks.push({
      id: threshold.id,
      status: passed ? 'pass' : 'fail',
      value,
      message: value === null
        ? `${threshold.label} is missing; threshold is <${threshold.maxExclusive}`
        : `${threshold.label} ${value.toFixed(3)}; threshold is <${threshold.maxExclusive}`,
    });
  }
}

function addQuietMachineSnapshotCheck(
  checks: DroppedFrameEarsCheck[],
  summary: Record<string, unknown> | null,
  quietMachineAttested: boolean | null
): void {
  if (quietMachineAttested !== true) return;

  const snapshotStatus = getString(summary, ['captureEnvironment', 'quietMachineSnapshot', 'status']);
  const cpuAvg = getNumber(summary, ['captureEnvironment', 'quietMachineSnapshot', 'cpu', 'avgPercent']);
  const cpuMax = getNumber(summary, ['captureEnvironment', 'quietMachineSnapshot', 'cpu', 'maxPercent']);
  const gpuUtil = getNumber(summary, ['captureEnvironment', 'quietMachineSnapshot', 'gpu', 'utilizationPercent']);
  const gpuLoadClass = getString(summary, ['captureEnvironment', 'quietMachineSnapshot', 'gpu', 'loadClass']);
  const warnings = asArray(getPath(summary, ['captureEnvironment', 'quietMachineSnapshot', 'warnings']))
    .filter((value): value is string => typeof value === 'string');
  const warningSummary = warnings.length > 0 ? ` warnings=${warnings.join(' | ')}` : '';

  checks.push({
    id: 'quiet_machine_snapshot_idle',
    status: snapshotStatus === 'pass' || snapshotStatus === 'warn'
      ? snapshotStatus
      : 'fail',
    value: snapshotStatus,
    message: snapshotStatus === 'pass'
      ? `Quiet-machine snapshot passed (cpuAvg=${cpuAvg ?? 'missing'}%, cpuMax=${cpuMax ?? 'missing'}%, gpu=${gpuUtil ?? 'missing'}%/${gpuLoadClass ?? 'unknown'})`
      : snapshotStatus === 'warn'
        ? `Quiet-machine snapshot had warning-band sensors but no recorded busy failure (cpuAvg=${cpuAvg ?? 'missing'}%, cpuMax=${cpuMax ?? 'missing'}%, gpu=${gpuUtil ?? 'missing'}%/${gpuLoadClass ?? 'unknown'}).${warningSummary}`
        : `Quiet-machine snapshot is missing or busy (status=${snapshotStatus ?? 'missing'}, cpuAvg=${cpuAvg ?? 'missing'}%, cpuMax=${cpuMax ?? 'missing'}%, gpu=${gpuUtil ?? 'missing'}%/${gpuLoadClass ?? 'unknown'}).${warningSummary}`,
  });
}

function runtimeSampleShotCount(sample: unknown): number | null {
  const record = asRecord(sample);
  if (!record) return null;
  const harnessDriver = asRecord(record.harnessDriver);
  const driverShots = harnessDriver ? harnessDriver.engineShotsFired : undefined;
  if (typeof driverShots === 'number' && Number.isFinite(driverShots)) return driverShots;
  const sessionShots = record.shotsThisSession;
  return typeof sessionShots === 'number' && Number.isFinite(sessionShots) ? sessionShots : null;
}

function addCombatFireTerrainBlockChecks(
  checks: DroppedFrameEarsCheck[],
  validationChecks: readonly ValidationCheck[],
  runtimeSamples: readonly unknown[] | null
): void {
  const validationTerrainBlock = validationCheck(validationChecks, 'combat_fire_terrain_block_rate');
  if (runtimeSamples === null) {
    checks.push({
      id: 'combat_fire_terrain_block_rate',
      status: validationTerrainBlock?.status ?? 'warn',
      value: typeof validationTerrainBlock?.value === 'number' ? validationTerrainBlock.value : null,
      message: validationTerrainBlock?.message
        ?? 'Runtime samples are unavailable; cannot prove combat-fire terrain blocking stayed low',
    });
    return;
  }

  let bestBudget: Record<string, unknown> | null = null;
  let bestTotalRequested = -1;
  for (const sample of runtimeSamples) {
    const sampleRecord = asRecord(sample);
    const combatBreakdown = asRecord(sampleRecord?.combatBreakdown);
    const budget = asRecord(combatBreakdown?.combatFireRaycastBudget);
    if (!budget) continue;
    const totalRequested = typeof budget.totalRequested === 'number' && Number.isFinite(budget.totalRequested)
      ? budget.totalRequested
      : -1;
    if (totalRequested >= bestTotalRequested) {
      bestTotalRequested = totalRequested;
      bestBudget = budget;
    }
  }

  if (!bestBudget) {
    checks.push({
      id: 'combat_fire_terrain_block_rate',
      status: validationTerrainBlock?.status ?? 'warn',
      value: typeof validationTerrainBlock?.value === 'number' ? validationTerrainBlock.value : null,
      message: validationTerrainBlock?.message
        ?? 'Combat-fire terrain-block telemetry is missing; cannot prove the measured fight had valid fire geometry',
    });
    return;
  }

  const totalRequested = Math.max(0, Number(bestBudget.totalRequested ?? 0));
  const totalTerrainBlocked = Math.max(0, Number(bestBudget.totalTerrainBlocked ?? 0));
  const reportedRate = Number(bestBudget.terrainBlockRate);
  const blockRate = Number.isFinite(reportedRate)
    ? reportedRate
    : totalRequested > 0
      ? totalTerrainBlocked / totalRequested
      : 0;
  const status: CheckStatus = totalRequested < COMBAT_FIRE_TERRAIN_BLOCK_MIN_REQUESTS
    ? 'warn'
    : blockRate < COMBAT_FIRE_TERRAIN_BLOCK_WARN_RATE
      ? 'pass'
      : blockRate < COMBAT_FIRE_TERRAIN_BLOCK_FAIL_RATE
        ? 'warn'
        : 'fail';

  checks.push({
    id: 'combat_fire_terrain_block_rate',
    status,
    value: blockRate,
    message: totalRequested < COMBAT_FIRE_TERRAIN_BLOCK_MIN_REQUESTS
      ? `Combat-fire terrain-block sample is too thin (${totalTerrainBlocked}/${totalRequested}); keep contact geometry diagnostic`
      : status === 'pass'
        ? `Combat-fire terrain blocking stayed low (${formatPercent(blockRate)}, ${totalTerrainBlocked}/${totalRequested})`
        : `Combat-fire terrain blocking is high (${formatPercent(blockRate)}, ${totalTerrainBlocked}/${totalRequested}; warn>=${formatPercent(COMBAT_FIRE_TERRAIN_BLOCK_WARN_RATE)}, fail>=${formatPercent(COMBAT_FIRE_TERRAIN_BLOCK_FAIL_RATE)}); contact geometry/LOS must be fixed before trusting dropped-frame completion evidence`,
  });
}

function addCombatChecks(
  checks: DroppedFrameEarsCheck[],
  validationChecks: readonly ValidationCheck[],
  runtimeSamples: readonly unknown[] | null
): void {
  const shots = validationCheck(validationChecks, 'harness_min_shots_fired')
    ?? validationCheck(validationChecks, 'player_shots_recorded');
  const hits = validationCheck(validationChecks, 'harness_min_hits_recorded')
    ?? validationCheck(validationChecks, 'player_hits_recorded');
  const aggregateCombatPassed = shots?.status === 'pass' && hits?.status === 'pass';
  checks.push(checkStatus(
    shots?.status === 'pass',
    'active_combat_shots',
    'active combat shot threshold passed',
    'active combat shot threshold is missing or failed',
    typeof shots?.value === 'number' ? shots.value : null
  ));
  checks.push(checkStatus(
    hits?.status === 'pass',
    'active_combat_hits',
    'active combat hit threshold passed',
    'active combat hit threshold is missing or failed',
    typeof hits?.value === 'number' ? hits.value : null
  ));

  if (runtimeSamples === null) {
    checks.push({
      id: 'active_combat_sustained_contact',
      status: aggregateCombatPassed ? 'pass' : 'fail',
      value: null,
      message: aggregateCombatPassed
        ? 'Aggregate combat thresholds passed; runtime sample distribution is unavailable in this artifact'
        : 'Aggregate combat thresholds failed and runtime sample distribution is unavailable',
    });
    return;
  }

  const shotCounts = runtimeSamples
    .map(runtimeSampleShotCount)
    .filter((value): value is number => value !== null);
  let previousMaxShots = 0;
  let samplesWithAnyShots = 0;
  let samplesWithShotIncreases = 0;
  for (const shotCount of shotCounts) {
    if (shotCount > 0) samplesWithAnyShots++;
    if (shotCount > previousMaxShots) {
      samplesWithShotIncreases++;
      previousMaxShots = shotCount;
    }
  }
  const shotIncreaseRatio = shotCounts.length > 0
    ? samplesWithShotIncreases / shotCounts.length
    : null;
  const sustained = aggregateCombatPassed
    && samplesWithAnyShots >= MIN_SUSTAINED_COMBAT_SHOT_INCREASE_SAMPLES
    && samplesWithShotIncreases >= MIN_SUSTAINED_COMBAT_SHOT_INCREASE_SAMPLES
    && shotIncreaseRatio !== null
    && shotIncreaseRatio >= MIN_SUSTAINED_COMBAT_SHOT_INCREASE_RATIO;
  checks.push({
    id: 'active_combat_sustained_contact',
    status: sustained ? 'pass' : 'fail',
    value: shotIncreaseRatio,
    message: sustained
      ? `Active combat was sustained across runtime samples (shot increases=${samplesWithShotIncreases}/${shotCounts.length}, samplesWithShots=${samplesWithAnyShots}, ${formatPercent(shotIncreaseRatio)})`
      : `Active combat was absent or too bursty for completion comparison (shot increases=${samplesWithShotIncreases}/${shotCounts.length}, samplesWithShots=${samplesWithAnyShots}, ${formatPercent(shotIncreaseRatio)}; min increases=${MIN_SUSTAINED_COMBAT_SHOT_INCREASE_SAMPLES}, min ratio=${formatPercent(MIN_SUSTAINED_COMBAT_SHOT_INCREASE_RATIO)})`,
  });
}

function addMaterializationEnvelopeChecks(
  checks: DroppedFrameEarsCheck[],
  validationChecks: readonly ValidationCheck[],
  summary: Record<string, unknown> | null
): void {
  const validationPressure = validationCheck(validationChecks, 'npc_materialization_pressure');
  const peakCandidates = typeof validationPressure?.value === 'number'
    ? validationPressure.value
    : getNumber(summary, ['closeModelEnvelope', 'peakCandidatesWithinCloseRadius']);
  const peakRendered = getNumber(summary, ['closeModelEnvelope', 'peakRenderedCloseModels']);
  const samplesWithCandidates = getNumber(summary, ['closeModelEnvelope', 'samplesWithCandidates']);
  const sampleCount = getNumber(summary, ['closeModelEnvelope', 'sampleCount']);
  const samplesWithRenderedCloseModels = getNumber(summary, ['closeModelEnvelope', 'samplesWithRenderedCloseModels']);
  const candidateSampleRatio = sampleCount !== null && sampleCount > 0 && samplesWithCandidates !== null
    ? samplesWithCandidates / sampleCount
    : null;
  const fallbackPassed = peakCandidates !== null
    && peakRendered !== null
    && samplesWithCandidates !== null
    && peakCandidates >= 4
    && peakRendered >= 2
    && samplesWithCandidates >= 2;
  const passed = validationPressure
    ? validationPressure.status === 'pass'
    : fallbackPassed;

  checks.push({
    id: 'npc_materialization_pressure',
    status: passed ? 'pass' : 'fail',
    value: peakCandidates,
    message: passed
      ? `NPC materialization pressure was represented (peak candidates=${peakCandidates ?? 'unknown'}, peak rendered=${peakRendered ?? 'unknown'}, samplesWithCandidates=${samplesWithCandidates ?? 'unknown'}/${sampleCount ?? 'unknown'})`
      : `NPC materialization pressure is missing or thin (peak candidates=${peakCandidates ?? 'missing'}, peak rendered=${peakRendered ?? 'missing'}, samplesWithCandidates=${samplesWithCandidates ?? 'missing'}/${sampleCount ?? 'missing'}); completion evidence must not close a materialization fix from low-contact route variance`,
  });

  const sustained = sampleCount !== null
    && samplesWithCandidates !== null
    && samplesWithRenderedCloseModels !== null
    && samplesWithCandidates >= MIN_SUSTAINED_MATERIALIZATION_SAMPLES
    && samplesWithRenderedCloseModels >= MIN_SUSTAINED_MATERIALIZATION_SAMPLES
    && candidateSampleRatio !== null
    && candidateSampleRatio >= MIN_SUSTAINED_MATERIALIZATION_RATIO;
  checks.push({
    id: 'npc_materialization_sustained_contact',
    status: sustained ? 'pass' : 'fail',
    value: candidateSampleRatio,
    message: sustained
      ? `NPC materialization contact was sustained across detailed samples (${samplesWithCandidates}/${sampleCount}, ${formatPercent(candidateSampleRatio)}; rendered=${samplesWithRenderedCloseModels})`
      : `NPC materialization contact was too bursty for completion comparison (${samplesWithCandidates ?? 'missing'}/${sampleCount ?? 'missing'}, ${formatPercent(candidateSampleRatio)}; rendered=${samplesWithRenderedCloseModels ?? 'missing'}; min samples=${MIN_SUSTAINED_MATERIALIZATION_SAMPLES}, min ratio=${formatPercent(MIN_SUSTAINED_MATERIALIZATION_RATIO)})`,
  });
}

function addCloseModelRuntimePoolLoadChecks(
  checks: DroppedFrameEarsCheck[],
  runtimeSamples: readonly unknown[] | null
): void {
  if (runtimeSamples === null) {
    checks.push({
      id: 'npc_close_model_runtime_pool_loads_clear',
      status: 'warn',
      value: null,
      message: 'Runtime samples are unavailable; cannot prove close-model pools stayed resident during measured play',
    });
    return;
  }

  let samplesWithCloseModelStats = 0;
  let samplesWithPoolLoads = 0;
  let maxPoolLoads = 0;
  for (const sample of runtimeSamples) {
    const sampleRecord = asRecord(sample);
    const closeModelStats = asRecord(sampleRecord?.closeModelStats);
    if (!closeModelStats) continue;
    samplesWithCloseModelStats++;
    const poolLoads = typeof closeModelStats.poolLoads === 'number' && Number.isFinite(closeModelStats.poolLoads)
      ? closeModelStats.poolLoads
      : 0;
    maxPoolLoads = Math.max(maxPoolLoads, poolLoads);
    if (poolLoads > 0) samplesWithPoolLoads++;
  }

  if (samplesWithCloseModelStats === 0) {
    checks.push({
      id: 'npc_close_model_runtime_pool_loads_clear',
      status: 'warn',
      value: null,
      message: 'Runtime close-model stats are unavailable; cannot prove no live close-model pool loads occurred',
    });
    return;
  }

  checks.push({
    id: 'npc_close_model_runtime_pool_loads_clear',
    status: samplesWithPoolLoads === 0 ? 'pass' : 'fail',
    value: samplesWithPoolLoads,
    message: samplesWithPoolLoads === 0
      ? `No live close-model pool loads during measured runtime (${samplesWithCloseModelStats} close-model samples, max poolLoads=${maxPoolLoads})`
      : `Close-model pools were still loading during measured runtime (${samplesWithPoolLoads}/${samplesWithCloseModelStats} close-model samples, max poolLoads=${maxPoolLoads}); materialization evidence is diagnostic until pool residency is prepared before play`,
  });
}

function addMaterializationTransitionTelemetryChecks(
  checks: DroppedFrameEarsCheck[],
  summary: Record<string, unknown> | null,
  runtimeSamples: readonly unknown[] | null,
): void {
  const peakActiveCloseModels = getNumber(summary, ['closeModelEnvelope', 'peakActiveCloseModels']);
  const samplesWithRenderedCloseModels = getNumber(summary, ['closeModelEnvelope', 'samplesWithRenderedCloseModels']);
  const summaryEventTotal = getNumber(summary, ['materializationTierMetrics', 'totalEvents']);
  const transitionWindowTotal = getNumber(summary, ['materializationTierMetrics', 'transitionWindowTotalEvents']);
  const closeModelsWereActive = (peakActiveCloseModels ?? 0) > 0
    && (samplesWithRenderedCloseModels ?? 0) > 0;

  let samplesWithEventArrays = 0;
  let runtimeEventTotal = 0;
  if (runtimeSamples) {
    for (const sample of runtimeSamples) {
      const sampleRecord = asRecord(sample);
      const events = sampleRecord?.materializationTierEvents;
      if (Array.isArray(events)) {
        samplesWithEventArrays++;
        runtimeEventTotal += events.length;
      }
      const closeModelStats = asRecord(sampleRecord?.closeModelStats);
      const transitionWindow = asRecord(closeModelStats?.transitionWindow);
      const transitionTotal = typeof transitionWindow?.total === 'number' && Number.isFinite(transitionWindow.total)
        ? transitionWindow.total
        : 0;
      runtimeEventTotal += transitionTotal;
    }
  }

  const eventTotal = Math.max(summaryEventTotal ?? 0, transitionWindowTotal ?? 0, runtimeEventTotal);
  if (!closeModelsWereActive) {
    checks.push({
      id: 'npc_materialization_transition_telemetry',
      status: 'pass',
      value: eventTotal,
      message: 'No active close models were sampled; tier-transition telemetry is not required for this artifact',
    });
    return;
  }

  if (runtimeSamples === null && summaryEventTotal === null) {
    checks.push({
      id: 'npc_materialization_transition_telemetry',
      status: 'warn',
      value: null,
      message: 'Runtime samples and materialization event summary are unavailable; cannot prove tier-transition telemetry was captured',
    });
    return;
  }

  checks.push({
    id: 'npc_materialization_transition_telemetry',
    status: eventTotal > 0 ? 'pass' : 'fail',
    value: eventTotal,
    message: eventTotal > 0
      ? `Tier-transition telemetry was captured while close models were active (events=${eventTotal}, eventSamples=${samplesWithEventArrays}, transitionWindowEvents=${transitionWindowTotal ?? 0})`
      : `Close models were active (${peakActiveCloseModels ?? 'unknown'} peak, ${samplesWithRenderedCloseModels ?? 'unknown'} rendered samples) but no materialization tier events were captured; this artifact cannot be trusted for transition-stutter claims`,
  });
}

function addHarnessEquivalenceChecks(checks: DroppedFrameEarsCheck[], validationChecks: readonly ValidationCheck[]): void {
  for (const id of HARNESS_EQUIVALENCE_IDS) {
    const check = validationCheck(validationChecks, id);
    const passed = check?.status === 'pass';
    checks.push({
      id,
      status: passed ? 'pass' : 'fail',
      value: typeof check?.value === 'number' || typeof check?.value === 'string' ? check.value : null,
      message: passed
        ? `${id} passed`
        : `${id} is missing, warning, or failed; completion evidence must explain or remove this harness mismatch`,
    });
  }
}

function addForbiddenRuntimeChecks(
  checks: DroppedFrameEarsCheck[],
  summary: Record<string, unknown> | null,
  searchParams: URLSearchParams | null
): void {
  for (const flag of FORBIDDEN_RUNTIME_FLAGS) {
    const actual = getPath(summary, flag.path);
    const forbiddenValue = flag.equals ?? true;
    const enabled = actual === forbiddenValue;
    checks.push({
      id: `forbidden_${flag.id}`,
      status: enabled ? 'fail' : 'pass',
      value: typeof actual === 'string' || typeof actual === 'boolean' || typeof actual === 'number'
        ? actual
        : null,
      message: enabled
        ? `Rejected content/runtime variant: ${flag.message}`
        : `Forbidden runtime flag is not set: ${flag.id}`,
    });
  }

  const shadowMode = getString(summary, ['perfRuntime', 'terrainShadowPassMode']);
  const diagnosticShadowMode = shadowMode === 'bounded-requested' || shadowMode === 'full-diagnostic';
  checks.push({
    id: 'forbidden_terrain_shadow_pass_mode',
    status: diagnosticShadowMode ? 'fail' : 'pass',
    value: shadowMode,
    message: diagnosticShadowMode
      ? `Rejected terrain shadow pass mode: ${shadowMode}`
      : `Terrain shadow pass mode is completion-compatible: ${shadowMode ?? 'unknown'}`,
  });

  const vegetationDensityScale = getNumber(summary, ['perfRuntime', 'vegetationDensityScale'])
    ?? (searchParams?.has('perfVegetationDensityScale')
      ? Number(searchParams.get('perfVegetationDensityScale'))
      : null);
  const changedVegetationDensity = vegetationDensityScale !== null
    && Number.isFinite(vegetationDensityScale)
    && Math.abs(vegetationDensityScale - 1) > 0.001;
  checks.push({
    id: 'forbidden_vegetation_density_scale',
    status: changedVegetationDensity ? 'fail' : 'pass',
    value: vegetationDensityScale,
    message: changedVegetationDensity
      ? `Rejected vegetation density scale: ${vegetationDensityScale}`
      : `Vegetation density scale is default-compatible: ${vegetationDensityScale ?? 'default'}`,
  });

  const weatherStateOverride = getString(summary, ['perfRuntime', 'weatherStateOverride']);
  const changedWeatherState = weatherStateOverride !== null && weatherStateOverride !== 'default';
  checks.push({
    id: 'forbidden_weather_state_override',
    status: changedWeatherState ? 'fail' : 'pass',
    value: weatherStateOverride,
    message: changedWeatherState
      ? `Rejected weather-state diagnostic override: ${weatherStateOverride}`
      : `Weather state is scenario default-compatible: ${weatherStateOverride ?? 'default'}`,
  });

  for (const queryFlag of FORBIDDEN_QUERY_FLAGS) {
    const enabled = searchParams?.get(queryFlag) === '1';
    checks.push({
      id: `forbidden_query_${queryFlag}`,
      status: enabled ? 'fail' : 'pass',
      value: enabled,
      message: enabled
        ? `Rejected URL/runtime diagnostic flag: ${queryFlag}=1`
        : `Forbidden query flag is not set: ${queryFlag}`,
    });
  }
}

function addPressureReadyWarmupChecks(
  checks: DroppedFrameEarsCheck[],
  summary: Record<string, unknown> | null
): void {
  const requested = getBoolean(summary, ['perfRuntime', 'pressureReadyWarmupRequested']);
  const status = getString(summary, ['perfRuntime', 'pressureReadyWarmupStatus']);
  const reason = getString(summary, ['perfRuntime', 'pressureReadyWarmupReason']);
  const elapsedMs = getNumber(summary, ['perfRuntime', 'pressureReadyWarmupElapsedMs']);
  const samples = getNumber(summary, ['perfRuntime', 'pressureReadyWarmupSamples']);
  const snapshot = asRecord(getPath(summary, ['perfRuntime', 'pressureReadyWarmupLastSnapshot']));
  const closeCandidates = getNumber(snapshot, ['closeCandidates']);
  const renderedCloseModels = getNumber(snapshot, ['renderedCloseModels']);
  const engineShotsFired = getNumber(snapshot, ['engineShotsFired']);
  const botState = getString(snapshot, ['botState']);

  if (requested !== true) {
    checks.push({
      id: 'pressure_ready_measurement_window',
      status: 'fail',
      value: requested,
      message: 'Pressure-ready warmup was not requested; cannot prove the measured window began under contact/materialization pressure.',
    });
    return;
  }

  checks.push({
    id: 'pressure_ready_measurement_window',
    status: status === 'ready' ? 'pass' : 'fail',
    value: status,
    message: status === 'ready'
      ? `Measured window started after pressure-ready warmup (${reason ?? 'unknown'}, elapsed=${elapsedMs ?? 'n/a'}ms, samples=${samples ?? 'n/a'}, close=${renderedCloseModels ?? 'n/a'}/${closeCandidates ?? 'n/a'}, shots=${engineShotsFired ?? 'n/a'}, state=${botState ?? 'unknown'}).`
      : `Pressure-ready warmup did not pass (status=${status ?? 'unknown'}, reason=${reason ?? 'unknown'}, elapsed=${elapsedMs ?? 'n/a'}ms, samples=${samples ?? 'n/a'}, close=${renderedCloseModels ?? 'n/a'}/${closeCandidates ?? 'n/a'}, shots=${engineShotsFired ?? 'n/a'}, state=${botState ?? 'unknown'}); keep this artifact diagnostic for contact/routing, not perf completion.`,
  });
}

function addTerrainHeightBoundsTrustChecks(
  checks: DroppedFrameEarsCheck[],
  summary: Record<string, unknown> | null
): void {
  const source = getString(summary, ['perfRuntime', 'terrainHeightBoundsSource']);
  const tests = getNumber(summary, ['perfRuntime', 'terrainHeightBoundsTests']);
  const fallbacks = getNumber(summary, ['perfRuntime', 'terrainHeightBoundsFallbacks']);

  if (source !== 'baked-grid') {
    checks.push({
      id: 'terrain_height_bounds_baked_grid_trust',
      status: 'pass',
      value: source,
      message: `Production baked-grid terrain bounds are not active: ${source ?? 'unknown'}`,
    });
    return;
  }

  const trusted = tests !== null && tests > 0 && fallbacks === 0;
  checks.push({
    id: 'terrain_height_bounds_baked_grid_trust',
    status: trusted ? 'pass' : 'fail',
    value: fallbacks,
    message: trusted
      ? `Baked-grid terrain bounds covered selection (${tests} tests, ${fallbacks} fallbacks)`
      : `Baked-grid terrain bounds were incomplete (${tests ?? 'missing'} tests, ${fallbacks ?? 'missing'} fallbacks)`,
  });
}

function addTerrainVisualDomainTrustChecks(
  checks: DroppedFrameEarsCheck[],
  summary: Record<string, unknown> | null
): void {
  const playableWorldSize = getNumber(summary, ['perfRuntime', 'terrainPlayableWorldSize']);
  const visualWorldSize = getNumber(summary, ['perfRuntime', 'terrainVisualWorldSize']);
  const visualMargin = getNumber(summary, ['perfRuntime', 'terrainVisualMargin']);
  const maxLODLevels = getNumber(summary, ['perfRuntime', 'terrainMaxLODLevels']);
  const lodRange0 = getNumber(summary, ['perfRuntime', 'terrainLodRange0']);
  const lodRangeLast = getNumber(summary, ['perfRuntime', 'terrainLodRangeLast']);
  const lod0VertexSpacing = getNumber(summary, ['perfRuntime', 'terrainLod0VertexSpacing']);

  const expectedVisualWorldSize = playableWorldSize !== null && visualMargin !== null
    ? playableWorldSize + visualMargin * 2
    : null;
  const visualExtentAligned = closeEnough(visualWorldSize, expectedVisualWorldSize);
  checks.push({
    id: 'terrain_visual_world_size_alignment',
    status: visualExtentAligned ? 'pass' : 'fail',
    value: visualWorldSize,
    message: visualExtentAligned
      ? `Terrain visual world size matches playable extent plus margin (${visualWorldSize})`
      : `Terrain visual world size is not aligned with playable extent plus margin (actual ${visualWorldSize ?? 'missing'}, expected ${expectedVisualWorldSize ?? 'missing'})`,
  });

  const lodCount = maxLODLevels !== null && Number.isInteger(maxLODLevels) && maxLODLevels > 0
    ? maxLODLevels
    : null;
  const expectedLodRange0 = visualWorldSize !== null && lodCount !== null
    ? (visualWorldSize / Math.pow(2, lodCount)) * 4
    : null;
  const expectedLodRangeLast = expectedLodRange0 !== null && lodCount !== null
    ? expectedLodRange0 * Math.pow(2, lodCount - 1)
    : null;
  const rangesAligned = closeEnough(lodRange0, expectedLodRange0)
    && closeEnough(lodRangeLast, expectedLodRangeLast)
    && lod0VertexSpacing !== null
    && lod0VertexSpacing > 0;
  checks.push({
    id: 'terrain_lod_ranges_visual_extent_alignment',
    status: rangesAligned ? 'pass' : 'fail',
    value: lodRange0,
    message: rangesAligned
      ? `Terrain LOD ranges are derived from the visual quadtree extent (LOD0 ${lodRange0}, last ${lodRangeLast})`
      : `Terrain LOD ranges are not derived from the visual quadtree extent (LOD0 ${lodRange0 ?? 'missing'} expected ${expectedLodRange0 ?? 'missing'}, last ${lodRangeLast ?? 'missing'} expected ${expectedLodRangeLast ?? 'missing'}, spacing ${lod0VertexSpacing ?? 'missing'})`,
  });
}

function addTerrainPresentationIntegrityChecks(
  checks: DroppedFrameEarsCheck[],
  summary: Record<string, unknown> | null
): void {
  const presentationGapCount = getNumber(summary, ['presentationGapContexts', 'gapCount']);
  const noPresentationGaps = presentationGapCount === 0;
  const unsyncedBufferVisibleChanges = getNumber(
    summary,
    ['presentationGapContexts', 'terrain', 'terrainStageBufferVisibleChangedWithoutSubmissionCount']
  );
  const bufferVisibleChanges = getNumber(
    summary,
    ['presentationGapContexts', 'terrain', 'terrainStageBufferVisibleChangedCount']
  );
  const morphChanges = getNumber(
    summary,
    ['presentationGapContexts', 'terrain', 'terrainStageMorphHashChangedCount']
  );
  const terrainGapCount = getNumber(summary, ['presentationGapContexts', 'terrain', 'gapCount']);
  const terrainSelectionSaturatedCount = getNumber(
    summary,
    ['presentationGapContexts', 'terrain', 'terrainSelectionSaturatedCount']
  );

  const hasTerrainGapSummary = terrainGapCount !== null;
  const coherent = noPresentationGaps || (
    hasTerrainGapSummary
    && unsyncedBufferVisibleChanges !== null
    && unsyncedBufferVisibleChanges === 0
  );
  checks.push({
    id: 'terrain_stage_buffer_submission_integrity',
    status: coherent ? 'pass' : 'fail',
    value: unsyncedBufferVisibleChanges,
    message: noPresentationGaps
      ? 'No presentation gaps were captured; no dropped-frame CDLOD stage mismatch to classify'
      : coherent
        ? `CDLOD buffer-visible terrain stage changes were submitted (${bufferVisibleChanges ?? 0} buffer-visible changes; ${morphChanges ?? 0} morph-only changes may use shader uniforms)`
      : hasTerrainGapSummary
        ? `CDLOD buffer-visible terrain stage changed without terrain buffer submission (${unsyncedBufferVisibleChanges ?? 'missing'} unsynced of ${bufferVisibleChanges ?? 'missing'} changes)`
        : 'Presentation gap terrain summary is missing; cannot prove CDLOD buffer submission integrity',
  });

  const selectionCapacityTrusted = noPresentationGaps || (
    hasTerrainGapSummary
    && terrainSelectionSaturatedCount !== null
    && terrainSelectionSaturatedCount === 0
  );
  checks.push({
    id: 'terrain_cdlod_selection_capacity',
    status: selectionCapacityTrusted ? 'pass' : 'fail',
    value: terrainSelectionSaturatedCount,
    message: noPresentationGaps
      ? 'No presentation gaps were captured; CDLOD selection capacity did not coincide with a dropped-frame context'
      : selectionCapacityTrusted
        ? 'CDLOD selection did not hit the tile cap in dropped-frame contexts'
        : hasTerrainGapSummary
          ? `CDLOD selection hit the tile cap in ${terrainSelectionSaturatedCount ?? 'missing'} dropped-frame contexts`
          : 'Presentation gap terrain summary is missing; cannot prove CDLOD selection capacity',
  });
}

function addRenderTailAttributionChecks(
  checks: DroppedFrameEarsCheck[],
  runtimeSamples: readonly unknown[] | null
): void {
  if (runtimeSamples === null) {
    checks.push({
      id: 'render_main_renderer_render_tail',
      status: 'warn',
      value: null,
      message: 'Runtime samples are unavailable; cannot attribute render-main frame tails',
    });
    return;
  }

  let observedFrames = 0;
  let warnFrames = 0;
  let failFrames = 0;
  let peakRenderMs = -1;
  let peakFrame: number | null = null;
  let peakSampleFrame: number | null = null;
  let peakSampleIndex: number | null = null;
  let peakCallbackMs: number | null = null;
  let peakSimulationMs: number | null = null;

  runtimeSamples.forEach((sample, sampleIndex) => {
    const sampleRecord = asRecord(sample);
    const sampleFrame = typeof sampleRecord?.frameCount === 'number' && Number.isFinite(sampleRecord.frameCount)
      ? sampleRecord.frameCount
      : null;
    for (const frame of asArray(sampleRecord?.loopFrameBreakdown)) {
      const frameRecord = asRecord(frame);
      const segments = asRecord(frameRecord?.segments);
      const renderMs = typeof segments?.['RenderMain.renderer.render'] === 'number'
        && Number.isFinite(segments['RenderMain.renderer.render'])
        ? segments['RenderMain.renderer.render']
        : null;
      if (renderMs === null) continue;

      observedFrames++;
      if (renderMs >= RENDER_MAIN_RENDER_WARN_MS) warnFrames++;
      if (renderMs >= RENDER_MAIN_RENDER_FAIL_MS) failFrames++;
      if (renderMs > peakRenderMs) {
        peakRenderMs = renderMs;
        peakFrame = typeof frameRecord?.frameCount === 'number' && Number.isFinite(frameRecord.frameCount)
          ? frameRecord.frameCount
          : null;
        peakSampleFrame = sampleFrame;
        peakSampleIndex = sampleIndex;
        peakCallbackMs = typeof frameRecord?.callbackDurationMs === 'number' && Number.isFinite(frameRecord.callbackDurationMs)
          ? frameRecord.callbackDurationMs
          : null;
        peakSimulationMs = typeof segments?.['Simulation.updateSystems'] === 'number'
          && Number.isFinite(segments['Simulation.updateSystems'])
          ? segments['Simulation.updateSystems']
          : null;
      }
    }
  });

  if (observedFrames === 0) {
    checks.push({
      id: 'render_main_renderer_render_tail',
      status: 'warn',
      value: null,
      message: 'No loop-frame render-main attribution was found; cannot distinguish render tails from simulation tails',
    });
    return;
  }

  const status: CheckStatus = peakRenderMs >= RENDER_MAIN_RENDER_FAIL_MS
    ? 'fail'
    : peakRenderMs >= RENDER_MAIN_RENDER_WARN_MS
      ? 'warn'
      : 'pass';
  const peakFrameText = peakFrame !== null
    ? `frame ${peakFrame}`
    : 'unknown frame';
  const sampleFrameText = peakSampleFrame !== null
    ? `sampleFrame=${peakSampleFrame}`
    : 'sampleFrame=unknown';
  const callbackText = peakCallbackMs !== null
    ? `callback=${peakCallbackMs.toFixed(1)}ms`
    : 'callback=missing';
  const simulationText = peakSimulationMs !== null
    ? `simulation=${peakSimulationMs.toFixed(1)}ms`
    : 'simulation=missing';

  checks.push({
    id: 'render_main_renderer_render_tail',
    status,
    value: peakRenderMs,
    message: status === 'pass'
      ? `Render-main attribution present and below warning threshold (peak=${peakRenderMs.toFixed(1)}ms across ${observedFrames} loop frames)`
      : `Render-main tail detected: peak RenderMain.renderer.render=${peakRenderMs.toFixed(1)}ms at ${peakFrameText} (${sampleFrameText}, ${callbackText}, ${simulationText}); frames >=${RENDER_MAIN_RENDER_WARN_MS}ms=${warnFrames}, >=${RENDER_MAIN_RENDER_FAIL_MS}ms=${failFrames}. Prioritize render-side attribution before simulation or atmosphere cuts.`,
  });

  if (peakRenderMs < RENDER_MAIN_RENDER_WARN_MS) {
    checks.push({
      id: 'render_main_renderer_resource_growth_context',
      status: 'pass',
      value: null,
      message: 'Renderer resource growth context is not required because render-main attribution is below the warning threshold',
    });
    return;
  }

  if (peakSampleIndex === null || peakSampleIndex <= 0) {
    checks.push({
      id: 'render_main_renderer_resource_growth_context',
      status: 'warn',
      value: null,
      message: 'Render-main tail exists but no previous runtime sample is available for renderer resource-growth attribution',
    });
    return;
  }

  const previousSample = runtimeSamples[peakSampleIndex - 1];
  const peakSample = runtimeSamples[peakSampleIndex];
  const previousTextures = getRendererCounter(previousSample, 'textures');
  const peakTextures = getRendererCounter(peakSample, 'textures');
  const previousGeometries = getRendererCounter(previousSample, 'geometries');
  const peakGeometries = getRendererCounter(peakSample, 'geometries');
  const previousPrograms = getRendererCounter(previousSample, 'programs');
  const peakPrograms = getRendererCounter(peakSample, 'programs');
  if (
    previousTextures === null
    || peakTextures === null
    || previousGeometries === null
    || peakGeometries === null
    || previousPrograms === null
    || peakPrograms === null
  ) {
    checks.push({
      id: 'render_main_renderer_resource_growth_context',
      status: 'warn',
      value: null,
      message: 'Render-main tail exists but renderer texture/geometry/program counters are missing around the peak sample',
    });
    return;
  }

  const textureDelta = peakTextures - previousTextures;
  const geometryDelta = peakGeometries - previousGeometries;
  const programDelta = peakPrograms - previousPrograms;
  const resourceJumpDetected = textureDelta >= RENDERER_RESOURCE_TEXTURE_JUMP_WARN
    || geometryDelta >= RENDERER_RESOURCE_GEOMETRY_JUMP_WARN
    || programDelta >= RENDERER_RESOURCE_PROGRAM_JUMP_WARN;
  checks.push({
    id: 'render_main_renderer_resource_growth_context',
    status: resourceJumpDetected ? 'fail' : 'pass',
    value: `textures+${textureDelta} geometries+${geometryDelta} programs+${programDelta}`,
    message: resourceJumpDetected
      ? `Render-main tail coincides with renderer resource growth (textures +${textureDelta}, geometries +${geometryDelta}, programs +${programDelta}); treat GPU residency/material warmup as unproven even if CPU-side pool-load counters are zero.`
      : `Render-main tail did not coincide with a large renderer resource jump (textures +${textureDelta}, geometries +${geometryDelta}, programs +${programDelta})`,
  });
}

function addAtmosphereTailChecks(
  checks: DroppedFrameEarsCheck[],
  runtimeSamples: readonly unknown[] | null
): void {
  if (runtimeSamples === null) {
    checks.push({
      id: 'atmosphere_cpu_sync_tail',
      status: 'warn',
      value: null,
      message: 'Runtime samples are unavailable; cannot classify atmosphere/fog CPU sync cost',
    });
    return;
  }

  let observedFrames = 0;
  let warnFrames = 0;
  let failFrames = 0;
  let peakAtmosphereMs = -1;
  let peakFrame: number | null = null;
  let peakSampleFrame: number | null = null;

  runtimeSamples.forEach((sample) => {
    const sampleRecord = asRecord(sample);
    const sampleFrame = typeof sampleRecord?.frameCount === 'number' && Number.isFinite(sampleRecord.frameCount)
      ? sampleRecord.frameCount
      : null;
    for (const frame of asArray(sampleRecord?.loopFrameBreakdown)) {
      const frameRecord = asRecord(frame);
      const segments = asRecord(frameRecord?.segments);
      const atmosphereMs = typeof segments?.['World.atmosphereSync'] === 'number'
        && Number.isFinite(segments['World.atmosphereSync'])
        ? segments['World.atmosphereSync']
        : null;
      if (atmosphereMs === null) continue;

      observedFrames++;
      if (atmosphereMs >= ATMOSPHERE_SYNC_WARN_MS) warnFrames++;
      if (atmosphereMs >= ATMOSPHERE_SYNC_FAIL_MS) failFrames++;
      if (atmosphereMs > peakAtmosphereMs) {
        peakAtmosphereMs = atmosphereMs;
        peakFrame = typeof frameRecord?.frameCount === 'number' && Number.isFinite(frameRecord.frameCount)
          ? frameRecord.frameCount
          : null;
        peakSampleFrame = sampleFrame;
      }
    }
  });

  if (observedFrames === 0) {
    checks.push({
      id: 'atmosphere_cpu_sync_tail',
      status: 'warn',
      value: null,
      message: 'No World.atmosphereSync loop-frame attribution was found; cannot classify atmosphere/fog CPU sync cost',
    });
    return;
  }

  const status: CheckStatus = peakAtmosphereMs >= ATMOSPHERE_SYNC_FAIL_MS
    ? 'fail'
    : peakAtmosphereMs >= ATMOSPHERE_SYNC_WARN_MS
      ? 'warn'
      : 'pass';
  const peakFrameText = peakFrame !== null
    ? `frame ${peakFrame}`
    : 'unknown frame';
  const sampleFrameText = peakSampleFrame !== null
    ? `sampleFrame=${peakSampleFrame}`
    : 'sampleFrame=unknown';

  checks.push({
    id: 'atmosphere_cpu_sync_tail',
    status,
    value: peakAtmosphereMs,
    message: status === 'pass'
      ? `Atmosphere/fog CPU sync attribution is below warning threshold (peak World.atmosphereSync=${peakAtmosphereMs.toFixed(1)}ms across ${observedFrames} loop frames); shader-side fog cost may still be inside RenderMain.renderer.render.`
      : `Atmosphere/fog CPU sync tail detected: peak World.atmosphereSync=${peakAtmosphereMs.toFixed(1)}ms at ${peakFrameText} (${sampleFrameText}); frames >=${ATMOSPHERE_SYNC_WARN_MS}ms=${warnFrames}, >=${ATMOSPHERE_SYNC_FAIL_MS}ms=${failFrames}. Evaluate sky/fog/atmosphere authority before preserving the current visual path.`,
  });
}

export function evaluateDroppedFrameEarsArtifact(artifactDir: string): DroppedFrameEarsArtifactEvaluation {
  const absoluteArtifactDir = resolve(artifactDir);
  const summary = readJsonObject(join(absoluteArtifactDir, 'summary.json'));
  const validation = readJsonObject(join(absoluteArtifactDir, 'validation.json'));
  const measurementTrust = readJsonObject(join(absoluteArtifactDir, 'measurement-trust.json'));
  const runtimeSamples = readJsonArray(join(absoluteArtifactDir, 'runtime-samples.json'));
  const validationChecks = getValidationChecks(validation, summary);
  const searchParams = urlSearchParams(summary);
  const checks: DroppedFrameEarsCheck[] = [];

  addRequiredFileChecks(absoluteArtifactDir, checks);

  const scenario = getString(summary, ['scenario', 'requestedMode'])
    ?? getString(summary, ['scenario', 'mode'])
    ?? getString(summary, ['mode']);
  checks.push(checkStatus(
    isRequiredScenario(scenario),
    'required_scenario',
    `Scenario ${scenario} is in the completion lane`,
    `Scenario ${scenario ?? 'unknown'} is not in the Open Frontier / A Shau completion lane`,
    scenario
  ));

  const quietMachineAttested = getBoolean(summary, ['captureEnvironment', 'quietMachineAttested']);
  checks.push(checkStatus(
    quietMachineAttested === true,
    'quiet_machine_attested',
    'Quiet-machine attestation is present',
    'Quiet-machine attestation is missing or false',
    quietMachineAttested
  ));
  addQuietMachineSnapshotCheck(checks, summary, quietMachineAttested);

  const status = getString(summary, ['status']);
  checks.push(checkStatus(
    status === 'ok',
    'capture_status_ok',
    'Capture status is ok',
    `Capture status is ${status ?? 'unknown'}`,
    status
  ));

  const overall = validationOverall(validation, summary);
  checks.push(checkStatus(
    overall === 'pass',
    'validation_pass',
    'Validation overall is pass',
    `Validation overall is ${overall ?? 'unknown'}`,
    overall
  ));

  const trust = measurementTrustStatus(measurementTrust, summary);
  checks.push(checkStatus(
    trust === 'pass',
    'measurement_trust_pass',
    'Measurement trust passed',
    `Measurement trust is ${trust ?? 'unknown'}`,
    trust
  ));

  const resolvedBackend = rendererResolvedBackend(measurementTrust, summary);
  const strictWebGpu = rendererStrictWebGpu(measurementTrust, summary);
  checks.push(checkStatus(
    resolvedBackend === 'webgpu' && strictWebGpu,
    'strict_webgpu_backend',
    'Renderer resolved to strict WebGPU',
    `Renderer backend is ${resolvedBackend ?? 'unknown'} strictWebGPU=${strictWebGpu}`,
    resolvedBackend
  ));

  addRafChecks(checks, validationChecks, summary);
  addCombatChecks(checks, validationChecks, runtimeSamples);
  addCombatFireTerrainBlockChecks(checks, validationChecks, runtimeSamples);
  addMaterializationEnvelopeChecks(checks, validationChecks, summary);
  addCloseModelRuntimePoolLoadChecks(checks, runtimeSamples);
  addMaterializationTransitionTelemetryChecks(checks, summary, runtimeSamples);
  addHarnessEquivalenceChecks(checks, validationChecks);
  addForbiddenRuntimeChecks(checks, summary, searchParams);
  addPressureReadyWarmupChecks(checks, summary);
  addTerrainHeightBoundsTrustChecks(checks, summary);
  addTerrainVisualDomainTrustChecks(checks, summary);
  addTerrainPresentationIntegrityChecks(checks, summary);
  addRenderTailAttributionChecks(checks, runtimeSamples);
  addAtmosphereTailChecks(checks, runtimeSamples);

  checks.push({
    id: 'owner_visual_acceptance_required',
    status: 'warn',
    message: 'Automated artifacts cannot prove the terrain/camera glitch is owner-accepted; keep owner playtest in the release gate.',
    value: null,
  });

  const failCount = checks.filter((check) => check.status === 'fail').length;
  const warnCount = checks.filter((check) => check.status === 'warn').length;
  const rejected = checks.some((check) => check.status === 'fail' && check.id.startsWith('forbidden_'));
  const classification: DroppedFrameEarsClassification = rejected
    ? 'rejected'
    : failCount === 0
      ? 'proven'
      : 'diagnostic';
  const contactQualified = checkPassed(checks, 'active_combat_shots')
    && checkPassed(checks, 'active_combat_hits')
    && checkPassed(checks, 'active_combat_sustained_contact');
  const materializationQualified = checkPassed(checks, 'npc_materialization_pressure')
    && checkPassed(checks, 'npc_materialization_sustained_contact')
    && checkPassed(checks, 'npc_close_model_runtime_pool_loads_clear')
    && checkPassed(checks, 'npc_materialization_transition_telemetry');
  const completionLaneQualified = classification === 'proven'
    && contactQualified
    && materializationQualified;

  return {
    artifactDir: absoluteArtifactDir,
    artifactRelPath: rel(absoluteArtifactDir),
    scenario,
    classification,
    contactQualified,
    materializationQualified,
    completionLaneQualified,
    criticalPass: completionLaneQualified,
    failCount,
    warnCount,
    checks,
  };
}

export function evaluateDroppedFrameEars(artifactDirs: readonly string[]): DroppedFrameEarsEvaluation {
  const artifacts = artifactDirs.map((artifactDir) => evaluateDroppedFrameEarsArtifact(artifactDir));
  const passingScenarios = REQUIRED_SCENARIOS.filter((scenario) =>
    artifacts.some((artifact) => artifact.scenario === scenario && artifact.criticalPass)
  );
  const missingScenarios = REQUIRED_SCENARIOS.filter((scenario) => !passingScenarios.includes(scenario));
  return {
    status: missingScenarios.length === 0 ? 'pass' : 'fail',
    requiredScenarios: REQUIRED_SCENARIOS,
    passingScenarios,
    missingScenarios,
    artifacts,
  };
}

function latestArtifactDir(): string | null {
  if (!existsSync(ARTIFACT_ROOT)) return null;
  const dirs = readdirSync(ARTIFACT_ROOT, { withFileTypes: true })
    .filter((entry) => entry.isDirectory())
    .map((entry) => join(ARTIFACT_ROOT, entry.name))
    .filter((path) => existsSync(join(path, 'summary.json')))
    .sort((a, b) => statSync(a).mtimeMs - statSync(b).mtimeMs);
  return dirs.at(-1) ?? null;
}

function parseArgs(argv: readonly string[]): { dirs: string[]; strict: boolean; json: boolean; help: boolean } {
  const dirs: string[] = [];
  let strict = false;
  let json = false;
  let help = false;
  for (let i = 0; i < argv.length; i++) {
    const arg = argv[i];
    if (arg === '--strict') {
      strict = true;
    } else if (arg === '--json') {
      json = true;
    } else if (arg === '--help' || arg === '-h') {
      help = true;
    } else if (arg === '--latest') {
      const latest = latestArtifactDir();
      if (latest) dirs.push(latest);
    } else if (arg === '--dir') {
      const next = argv[++i];
      if (!next) throw new Error('--dir requires a path');
      dirs.push(next);
    } else if (arg.startsWith('--dir=')) {
      dirs.push(arg.slice('--dir='.length));
    } else if (arg.startsWith('-')) {
      throw new Error(`Unknown option: ${arg}`);
    } else {
      dirs.push(arg);
    }
  }

  if (dirs.length === 0 && !help) {
    const latest = latestArtifactDir();
    if (latest) dirs.push(latest);
  }

  return { dirs, strict, json, help };
}

function printHelp(): void {
  console.log([
    'Usage: npm run check:dropped-frame-ears -- [--dir artifacts/perf/<capture>] [--strict] [--json]',
    '',
    'Classifies perf artifacts against the STABILIZAT-4 dropped-frame EARS criteria.',
    'Completion requires one passing Open Frontier artifact and one passing A Shau artifact.',
    'Without --dir, the latest artifacts/perf capture is evaluated.',
  ].join('\n'));
}

function printHumanReport(evaluation: DroppedFrameEarsEvaluation): void {
  console.log([
    `[ST4-EARS] overall=${evaluation.status}`,
    `required=${evaluation.requiredScenarios.join(',')}`,
    `passing=${evaluation.passingScenarios.join(',') || 'none'}`,
    `missing=${evaluation.missingScenarios.join(',') || 'none'}`,
  ].join(' '));

  for (const artifact of evaluation.artifacts) {
    console.log(`[ST4-EARS] ${artifact.artifactRelPath} scenario=${artifact.scenario ?? 'unknown'} classification=${artifact.classification} contact=${artifact.contactQualified ? 'qualified' : 'low'} materialization=${artifact.materializationQualified ? 'qualified' : 'thin'} fail=${artifact.failCount} warn=${artifact.warnCount}`);
    for (const check of artifact.checks.filter((entry) => entry.status !== 'pass')) {
      console.log(`  ${check.status.toUpperCase()} ${check.id}: ${check.message}`);
    }
  }
}

function main(): void {
  const options = parseArgs(process.argv.slice(2));
  if (options.help) {
    printHelp();
    return;
  }
  if (options.dirs.length === 0) {
    throw new Error('No perf artifact directories found. Pass --dir artifacts/perf/<capture>.');
  }

  const evaluation = evaluateDroppedFrameEars(options.dirs);
  if (options.json) {
    console.log(JSON.stringify(evaluation, null, 2));
  } else {
    printHumanReport(evaluation);
  }

  if (options.strict && evaluation.status !== 'pass') {
    process.exitCode = 1;
  }
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  main();
}