@hypersoniclabs/helix-cli 0.1.6 → 0.1.23

package/dist/visualsConfig.js

@@ -0,0 +1,1333 @@
+"use strict";
+// Vendored `helix.visuals.json` v1 validator — the per-world visual contract the engine's visual runtime
+// parses at boot. A world authors its LOOK here — mode, time of day, the sun/sky/environment/shadows transport
+// knobs, grade, exposure, bloom, fog, AO, practicals, local post-processing volumes, and the bake's probe volume
+// with its budget and bounces — while tier ladders, face sizes and pass order stay engine internals (quality
+// tiers may DROP a pass on weak hardware; they never re-author these values).
+// SYNC OBLIGATION: mirrors `parseVisualsConfig` + `bakedLightingPointerOf` / `BAKED_LIGHTING_VERSION` in
+// helix-web-engine-new/systems/visual/src/runtime/visualsConfig.ts — plus the `AgxLookName` vocabulary from
+// .../src/color/agxLook.ts, DEFAULT_SUN_PATH / wrapHours from .../src/tod/sunPath.ts, and the baked artifact's
+// shape from .../src/tod/keyframes.ts (`ProbeKeyframeStore.fromJSON`) + .../src/runtime/bakedField.ts
+// (`createBakedField`, where a missing `volume` is fatal and a missing `geometry` only degrades visibility).
+// Fix bugs there first, then mirror here; do not diverge. The parser THROWS on the first bad field, so
+// everything it throws on is an ERROR here (a world whose config the runtime rejects does not boot); everything
+// it tolerates — unknown top-level keys, wrapped hours, a clamped cycle, angles outside any range — is at most
+// a WARNING.
+// The AgX presets' CDL numbers are deliberately NOT mirrored: no rule reads them, only the preset names.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BAKED_LIGHTING_VERSION = exports.AGX_LOOK_NAMES = exports.VISUALS_MODES = exports.VISUALS_CONFIG_VERSION = exports.VISUALS_CONFIG_SOURCE_PATH = exports.VISUALS_CONFIG_FILE = void 0;
+exports.auditVisualsConfig = auditVisualsConfig;
+exports.auditVisualsConfigText = auditVisualsConfigText;
+exports.auditBakedArtifact = auditBakedArtifact;
+exports.auditBakedArtifactText = auditBakedArtifactText;
+/** The document's filename. A world SOURCE keeps it in `public/`; a built bundle serves it from the root. */
+exports.VISUALS_CONFIG_FILE = 'helix.visuals.json';
+exports.VISUALS_CONFIG_SOURCE_PATH = `public/${exports.VISUALS_CONFIG_FILE}`;
+exports.VISUALS_CONFIG_VERSION = 1;
+/** `baked` = a keyframed probe field shipped as publish-time data; `dynamic` = zero-bake, lit at runtime. */
+exports.VISUALS_MODES = ['baked', 'dynamic'];
+/** The calibrated AgX look presets `grade.look` may name. */
+exports.AGX_LOOK_NAMES = ['none', 'needle', 'daylight', 'punchy'];
+/** Contract version of the `bakedLighting` block the bake step writes into the document. */
+exports.BAKED_LIGHTING_VERSION = 1;
+/** The scaffold default: zero-bake, static noon sun on the default path, the calibrated daylight grade. */
+const DEFAULT_MODE = 'dynamic';
+const DEFAULT_HOURS = 12;
+const DEFAULT_LOOK = 'daylight';
+const DEFAULT_SUN_PATH = { latitudeDeg: 45, declinationDeg: 0, noonAzimuthDeg: 180 };
+// The authored post-stack blocks' calibrated defaults and bounds — mirrored from the engine's
+// DEFAULT_EXPOSURE / DEFAULT_BLOOM / DEFAULT_FOG / DEFAULT_AO + EXPOSURE_COMPENSATION_LIMIT.
+const EXPOSURE_COMPENSATION_LIMIT = 5;
+const DEFAULT_EXPOSURE = { compensation: 0, min: 0.4, max: 40, postGain: 1 };
+// `key` IS the auto-exposure target, verbatim at every hour — absent (or null) is the day/night schedule the
+// calibration was derived under. `postGain` is the tone mapper's own multiplier, applied past bloom.
+const EXPOSURE_KEY_BAND = { min: 0.005, max: 1 };
+const EXPOSURE_POST_GAIN_BAND = { min: 0.1, max: 4 };
+// The LIGHT TRANSPORT blocks' calibrated defaults and bounds — mirrored from the engine's DEFAULT_SUN /
+// DEFAULT_ENVIRONMENT / DEFAULT_SHADOWS. Unlike the post stack these feed the probe BAKE, not the frame.
+const DEFAULT_SUN_INTENSITY_SCALE = 1;
+const SUN_INTENSITY_SCALE_BAND = { min: 0.05, max: 20 };
+/** How `sun.tint` meets the elevation warm ramp: `multiply` colours the ramp, `replace` hands the tint over
+ *  verbatim at every hour — the only way to author an exact sun colour, a pure white one included. */
+const SUN_TINT_MODES = ['multiply', 'replace'];
+const DEFAULT_SUN_TINT_MODE = 'multiply';
+const DEFAULT_ENVIRONMENT_INTENSITY = 0.05;
+const ENVIRONMENT_INTENSITY_BAND = { min: 0, max: 4 };
+const DEFAULT_SHADOW_OPACITY = 1;
+const SHADOW_OPACITY_BAND = { min: 0, max: 1 };
+// The sun's square ortho shadow box, half-extent in metres. Absent is the fit the rig derives from the probe
+// volume; an authored one buys COVERAGE with resolution, the texel being 2·extent/mapSize on the tier's map.
+const SHADOW_EXTENT_BAND = { min: 4, max: 200 };
+// The sky model — mirrored from the engine's DEFAULT_SKY + SKY_TURBIDITY_* / SKY_IRRADIANCE_SCALE_*. TL is
+// Linke's turbidity: 2.5 is a clear day, and past 4 the sky out-lights the sun.
+const DEFAULT_SKY_TURBIDITY = 2.5;
+const SKY_TURBIDITY_BAND = { min: 1, max: 10 };
+const DEFAULT_SKY_IRRADIANCE_SCALE = 1;
+const SKY_IRRADIANCE_SCALE_BAND = { min: 0.1, max: 4 };
+// What is left of the frozen-sunset dome once the sun is 6° under — mirrored from DEFAULT_TWILIGHT_FLOOR /
+// SKY_TWILIGHT_FLOOR_*. Runtime-blended, never baked: the keys photograph the sun above the horizon.
+const DEFAULT_SKY_TWILIGHT_FLOOR = 0.001;
+const SKY_TWILIGHT_FLOOR_BAND = { min: 0.0001, max: 1 };
+// The probe field's own shape — mirrored from DEFAULT_PROBE_BUDGET / PROBE_BUDGET_PRESETS / PROBE_BOUNCES_*.
+// A budget outside its band is refused WHOLE and falls back to the default: a per-axis clamp would hand back a
+// grid nobody authored, half-honoured exactly where the bake cost changed.
+const DEFAULT_PROBE_BUDGET = [7, 4, 7];
+const PROBE_BUDGET_PRESETS = { default: DEFAULT_PROBE_BUDGET, large: [12, 6, 10] };
+const PROBE_BUDGET_AXIS_BAND = { min: 2, max: 16 };
+const PROBE_BUDGET_MAX = 1536;
+const DEFAULT_PROBE_BOUNCES = 1;
+const PROBE_BOUNCES_BAND = { min: 1, max: 4 };
+/** The engine's own box — `DEFAULT_PROBE_VOLUME` in probeRung.ts, 6 m cells over the default budget. It is
+ *  what an unauthored `probes.size` lands at, so a budget's cell pitch can be reported without one. */
+const DEFAULT_PROBE_SPAN = [36, 18, 36];
+/** Keys the parser claims. Everything else is CARRIED — the bake step writes its artifact pointer here. */
+const CLAIMED_KEYS = [
+    'version', 'mode', 'timeOfDay', 'sun', 'sky', 'environment', 'shadows', 'grade', 'exposure', 'bloom', 'fog', 'ao', 'probes', 'practicals',
+    'volumes', 'weather', 'ocean',
+];
+const TIME_OF_DAY_KEYS = ['hours', 'cycleSeconds', 'paused', 'latitudeDeg', 'declinationDeg', 'noonAzimuthDeg'];
+const SUN_KEYS = ['intensityScale', 'tint', 'tintMode'];
+const SKY_KEYS = ['turbidity', 'irradianceScale', 'twilightFloor'];
+const ENVIRONMENT_KEYS = ['intensity'];
+const SHADOWS_KEYS = ['opacity', 'extent'];
+/** The blocks that feed the probe bake rather than the frame — the ones a `baked` world has to re-bake for. */
+const TRANSPORT_KEYS = ['sun', 'sky', 'environment', 'shadows', 'weather', 'ocean'];
+const GRADE_KEYS = ['look', 'slope', 'power', 'saturation'];
+const EXPOSURE_KEYS = ['compensation', 'min', 'max', 'key', 'postGain'];
+const BLOOM_KEYS = ['intensity', 'nightIntensity', 'threshold'];
+const FOG_KEYS = ['enabled', 'density', 'heightDensity'];
+const AO_KEYS = ['intensity', 'radius'];
+const PROBES_KEYS = ['center', 'size', 'budget', 'bounces', 'skyFallback', 'volumes'];
+/** SYNC OBLIGATION: mirrors the engine's nested-volume parser (`parseProbeVolumes` / `parseProbePad`,
+ *  systems/visual/src/runtime/visualsConfig.ts) — widen both in lockstep. */
+const PROBE_VOLUME_KEYS = ['center', 'size', 'budget', 'blendMetres', 'pad'];
+const PROBE_VOLUME_MAX = 4;
+const DEFAULT_PROBE_VOLUME_BLEND = 0.5;
+/** Interior corners leak past this nested cell pitch — measured on the reference shed: 2.5–3.1 m cells bled
+ *  a sunlit strip down every vertical corner, 1.5–1.9 m rendered them clean. A hint, never a gate. */
+const NESTED_CELL_CORNER_HINT = 1.9;
+const VOLUME_KEYS = ['center', 'size', 'blendMetres', 'exposure', 'bloom', 'fog', 'ao'];
+/** The post-stack blocks a volume may override locally, and the document-level ones it may not. */
+const VOLUME_OVERRIDE_KEYS = ['exposure', 'bloom', 'fog', 'ao'];
+const VOLUME_EXCLUDED_KEYS = ['grade', 'timeOfDay', 'probes', 'mode', 'practicals', ...TRANSPORT_KEYS];
+// `enabled` is authorable on the document's fog but not in a volume: a volume blends, and there is no half-off.
+const VOLUME_FOG_KEYS = ['density', 'heightDensity'];
+const DEFAULT_VOLUME_BLEND_METRES = 1;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** Mirrors engine-core/weather's strict optional weather block; defaults stay in the runtime. */
+function auditWeather(audit, raw, mode) {
+    if (raw === undefined)
+        return;
+    const error = (message) => { audit.errors.push(`${audit.file}: ${message}`); };
+    if (!isRecord(raw)) {
+        error('weather must be an object');
+        return;
+    }
+    const values = ['coverage', 'density', 'rain', 'storm', 'windX', 'windZ'];
+    const keys = ['enabled', 'preset', 'seed', 'cloudBaseM', 'cloudScaleM', 'cloudShadows', ...values];
+    for (const key of Object.keys(raw))
+        if (!keys.includes(key))
+            error(`unknown weather field: ${key}`);
+    const presets = ['clear', 'fair', 'overcast', 'rain', 'storm'];
+    if (raw.preset != null && !presets.includes(raw.preset))
+        error(`weather.preset must be one of ${presets.join(', ')}`);
+    for (const key of ['enabled', 'cloudShadows']) {
+        if (raw[key] !== undefined && typeof raw[key] !== 'boolean')
+            error(`weather.${key} must be a boolean`);
+    }
+    const number = (key, min, max, nullIsAbsent = false) => {
+        const value = raw[key];
+        if (value === undefined || (value === null && nullIsAbsent))
+            return;
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) {
+            error(`weather.${key} must be a finite number in [${min}, ${max}]`);
+        }
+    };
+    number('seed', 0, 0xffffffff, true);
+    if (typeof raw.seed === 'number' && Number.isFinite(raw.seed) && !Number.isInteger(raw.seed))
+        error('weather.seed must be an integer');
+    number('cloudBaseM', 100, 20000, true);
+    number('cloudScaleM', 500, 50000, true);
+    for (const key of values)
+        number(key, key.startsWith('wind') ? -40 : 0, key.startsWith('wind') ? 40 : 1);
+    if (raw.enabled === true && mode === 'baked')
+        error('Weather requires dynamic lighting; baked lighting artifacts do not contain weather states.');
+}
+/** Mirrors visual/ocean/oceanConfig.ts; scene documents and their sealed hashes are unaffected. */
+function auditOcean(audit, raw, mode) {
+    if (raw === undefined)
+        return;
+    const error = (message) => { audit.errors.push(`${audit.file}: ${message}`); };
+    if (!isRecord(raw)) {
+        error('ocean must be an object');
+        return;
+    }
+    const keys = ['enabled', 'level', 'seed', 'significantWaveHeight', 'peakWavelength', 'windDirectionDeg', 'bathymetry', 'refraction', 'reflections'];
+    for (const key of Object.keys(raw))
+        if (!keys.includes(key))
+            error(`unknown ocean field: ${key}`);
+    for (const key of ['enabled', 'refraction', 'reflections']) {
+        if (raw[key] !== undefined && typeof raw[key] !== 'boolean')
+            error(`ocean.${key} must be a boolean`);
+    }
+    for (const [key, min, max] of [['level', -10000, 10000], ['seed', 0, 0xffffffff], ['significantWaveHeight', 0, 8],
+        ['peakWavelength', 2, 1000], ['windDirectionDeg', -360, 360]]) {
+        const value = raw[key];
+        if (value !== undefined && (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max)) {
+            error(`ocean.${key} must be in [${min}, ${max}]`);
+        }
+    }
+    if (raw.seed !== undefined && !Number.isInteger(raw.seed))
+        error('ocean.seed must be an integer');
+    const peak = raw.peakWavelength ?? 20, height = raw.significantWaveHeight ?? 0.8;
+    if (typeof peak === 'number' && typeof height === 'number' && peak < height * 12) {
+        error('ocean.peakWavelength must be at least 12 times significantWaveHeight');
+    }
+    if (raw.bathymetry != null && (typeof raw.bathymetry !== 'string' || raw.bathymetry.trim() === '')) {
+        error('ocean.bathymetry must be a non-empty URL or null');
+    }
+    if (raw.enabled === true && mode === 'baked')
+        error('Ocean currently requires dynamic lighting.');
+}
+/** Wrap a clock reading into [0, 24) — the cycle is periodic, so a scrub past midnight is not an error. */
+function wrapHours(hours) {
+    const h = hours % 24;
+    return h < 0 ? h + 24 : h;
+}
+function editDistance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i += 1) {
+        let previous = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j += 1) {
+            const swap = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+            previous = swap;
+        }
+    }
+    return row[b.length];
+}
+/**
+ * The closest known key within two edits — a typo, not a different word. `null` when nothing is close.
+ * A dropped or invented unit suffix (`latitude` for `latitudeDeg`, `saturationDeg` for `saturation`) is the
+ * commonest miss here and outruns two edits, so a prefix relation counts as one.
+ */
+function didYouMean(key, known) {
+    const lower = key.toLowerCase();
+    let best = null;
+    let bestDistance = 3;
+    for (const candidate of known) {
+        const other = candidate.toLowerCase();
+        const prefixed = lower.length >= 4 && (other.startsWith(lower) || lower.startsWith(other));
+        const distance = prefixed ? 1 : editDistance(lower, other);
+        if (distance < bestDistance) {
+            best = candidate;
+            bestDistance = distance;
+        }
+    }
+    return best;
+}
+function numberField(audit, source, key, fallback, what) {
+    const value = source[key];
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        audit.errors.push(`${audit.file}: ${what}.${key} must be a finite number`);
+        return fallback;
+    }
+    return value;
+}
+function booleanField(audit, source, key, fallback, what) {
+    const value = source[key];
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'boolean') {
+        audit.errors.push(`${audit.file}: ${what}.${key} must be a boolean`);
+        return fallback;
+    }
+    return value;
+}
+// Unknown keys inside a claimed BLOCK are dropped on the floor by the parser (only the top level is carried),
+// so a typo there is silent: the world boots with the default and looks subtly wrong.
+function reportUnknownKeys(audit, source, known, what) {
+    for (const key of Object.keys(source)) {
+        if (known.includes(key))
+            continue;
+        const suggestion = didYouMean(key, known);
+        audit.warnings.push(`${audit.file}: ${what}.${key} is not read by the runtime and is ignored${suggestion ? ` — did you mean "${suggestion}"?` : ''}`);
+    }
+}
+/** A boolean with a THIRD state: absent — or an explicit null — is "decide for me", which the runtime resolves
+ *  rather than a value it is missing. A wrong TYPE still throws engine-side, so it is an error here. */
+function tristateField(audit, source, key, what) {
+    const value = source[key];
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== 'boolean') {
+        audit.errors.push(`${audit.file}: ${what}.${key} must be a boolean or null`);
+        return null;
+    }
+    return value;
+}
+function auditTimeOfDay(audit, raw) {
+    if (raw === undefined)
+        return { fragment: `sun ${DEFAULT_HOURS}h, static`, cycleSeconds: 0 };
+    if (!isRecord(raw)) {
+        audit.errors.push(`${audit.file}: timeOfDay must be an object`);
+        return { fragment: 'sun ?', cycleSeconds: 0 };
+    }
+    reportUnknownKeys(audit, raw, TIME_OF_DAY_KEYS, 'timeOfDay');
+    const authoredCycle = numberField(audit, raw, 'cycleSeconds', 0, 'timeOfDay');
+    const cycleSeconds = Math.max(0, authoredCycle);
+    if (authoredCycle < 0) {
+        audit.warnings.push(`${audit.file}: timeOfDay.cycleSeconds ${authoredCycle} is clamped to 0 — the sun will not move`);
+    }
+    const authoredHours = numberField(audit, raw, 'hours', DEFAULT_HOURS, 'timeOfDay');
+    const hours = wrapHours(authoredHours);
+    if (hours !== authoredHours) {
+        audit.warnings.push(`${audit.file}: timeOfDay.hours ${authoredHours} wraps to ${hours}`);
+    }
+    const paused = booleanField(audit, raw, 'paused', false, 'timeOfDay');
+    const path = {
+        latitudeDeg: numberField(audit, raw, 'latitudeDeg', DEFAULT_SUN_PATH.latitudeDeg, 'timeOfDay'),
+        declinationDeg: numberField(audit, raw, 'declinationDeg', DEFAULT_SUN_PATH.declinationDeg, 'timeOfDay'),
+        noonAzimuthDeg: numberField(audit, raw, 'noonAzimuthDeg', DEFAULT_SUN_PATH.noonAzimuthDeg, 'timeOfDay'),
+    };
+    const movement = cycleSeconds === 0 ? 'static' : `${cycleSeconds}s/day${paused ? ', paused' : ''}`;
+    const moved = Object.keys(path).some((key) => path[key] !== DEFAULT_SUN_PATH[key]);
+    const pathText = moved
+        ? ` · path lat ${path.latitudeDeg}° dec ${path.declinationDeg}° noon ${path.noonAzimuthDeg}°`
+        : '';
+    return { fragment: `sun ${hours}h, ${movement}${pathText}`, cycleSeconds };
+}
+function auditGrade(audit, raw) {
+    if (raw === undefined)
+        return `grade ${DEFAULT_LOOK}`;
+    if (!isRecord(raw)) {
+        audit.errors.push(`${audit.file}: grade must be an object`);
+        return 'grade ?';
+    }
+    reportUnknownKeys(audit, raw, GRADE_KEYS, 'grade');
+    const look = raw.look;
+    let name = DEFAULT_LOOK;
+    if (look !== undefined) {
+        if (typeof look !== 'string' || !exports.AGX_LOOK_NAMES.includes(look)) {
+            audit.errors.push(`${audit.file}: grade.look must be one of ${exports.AGX_LOOK_NAMES.join(' | ')}`);
+        }
+        else {
+            name = look;
+        }
+    }
+    // The three CDL numbers override whatever the preset sets, one by one.
+    const overridden = ['slope', 'power', 'saturation'].filter((key) => {
+        if (raw[key] === undefined)
+            return false;
+        numberField(audit, raw, key, 0, 'grade');
+        return true;
+    });
+    return `grade ${name}${overridden.length ? ` (${overridden.join('/')} overridden)` : ''}`;
+}
+/** Warn-and-clamp for the fields the engine parser silently clamps non-negative (the cycleSeconds pattern). */
+function nonNegativeField(audit, source, key, fallback, what) {
+    const value = numberField(audit, source, key, fallback, what);
+    if (value < 0) {
+        audit.warnings.push(`${audit.file}: ${what}.${key} ${value} is clamped to 0`);
+        return 0;
+    }
+    return value;
+}
+/** Warn-and-clamp into an authored band, and hand back the value the runtime will actually use. */
+function clampedField(audit, source, key, fallback, what, band) {
+    const authored = numberField(audit, source, key, fallback, what);
+    const clamped = Math.min(Math.max(authored, band.min), band.max);
+    if (clamped !== authored) {
+        audit.warnings.push(`${audit.file}: ${what}.${key} ${authored} is clamped to ${clamped} [${band.min}..${band.max}]`);
+    }
+    return clamped;
+}
+/** A banded number with a THIRD state: absent — or an explicit null — is the engine's own derivation (the
+ *  schedule, the fitted box) rather than a value that went missing. A wrong TYPE still throws engine-side. */
+function clampedNullableField(audit, source, key, what, band) {
+    const value = source[key];
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        audit.errors.push(`${audit.file}: ${what}.${key} must be a finite number or null`);
+        return null;
+    }
+    const clamped = Math.min(Math.max(value, band.min), band.max);
+    if (clamped !== value) {
+        audit.warnings.push(`${audit.file}: ${what}.${key} ${value} is clamped to ${clamped} [${band.min}..${band.max}]`);
+    }
+    return clamped;
+}
+const HEX_COLOR = /^#?(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+/** A `#rrggbb` / `#rgb` tint, `#` optional — the engine parser accepts the bare form too, and this mirror
+ *  must never warn on a value the runtime happily consumes. A bad one is a warning: the runtime ignores it. */
+function hexColorField(audit, source, key, what) {
+    const value = source[key];
+    if (value === undefined)
+        return null;
+    if (typeof value !== 'string' || !HEX_COLOR.test(value)) {
+        audit.warnings.push(`${audit.file}: ${what}.${key} ${JSON.stringify(value)} is not a hex colour ("#rrggbb" or "#rgb") and is ignored`);
+        return null;
+    }
+    return value;
+}
+/** Warn-and-clamp on a compensation outside the calibrated ±EV band, and hand back the value the runtime uses. */
+function clampedCompensation(audit, source, what) {
+    const authored = numberField(audit, source, 'compensation', DEFAULT_EXPOSURE.compensation, what);
+    const compensation = Math.min(Math.max(authored, -EXPOSURE_COMPENSATION_LIMIT), EXPOSURE_COMPENSATION_LIMIT);
+    if (compensation !== authored) {
+        audit.warnings.push(`${audit.file}: ${what}.compensation ${authored} is clamped to ${compensation} (±${EXPOSURE_COMPENSATION_LIMIT} EV)`);
+    }
+    return compensation;
+}
+// The engine parser THROWS on an incoherent band — an exposure multiplier of zero or below renders black or
+// inverted, and min above max has no sensible normalization — so both are errors here.
+function auditExposureBand(audit, min, max, what) {
+    if (!(min > 0) || !(max > 0)) {
+        audit.errors.push(`${audit.file}: ${what}.min and ${what}.max must be positive exposure multipliers`);
+    }
+    else if (min > max) {
+        audit.errors.push(`${audit.file}: ${what}.min must not exceed ${what}.max (equal pins the exposure)`);
+    }
+}
+function auditExposure(audit, raw) {
+    if (raw === undefined)
+        return null;
+    if (!isRecord(raw)) {
+        audit.errors.push(`${audit.file}: exposure must be an object`);
+        return 'exposure ?';
+    }
+    reportUnknownKeys(audit, raw, EXPOSURE_KEYS, 'exposure');
+    const compensation = clampedCompensation(audit, raw, 'exposure');
+    const min = numberField(audit, raw, 'min', DEFAULT_EXPOSURE.min, 'exposure');
+    const max = numberField(audit, raw, 'max', DEFAULT_EXPOSURE.max, 'exposure');
+    auditExposureBand(audit, min, max, 'exposure');
+    const key = clampedNullableField(audit, raw, 'key', 'exposure', EXPOSURE_KEY_BAND);
+    // Said out loud: an authored key IS the target at every hour, so the EV stops left in the document beside it
+    // do nothing at all.
+    if (key !== null && raw.compensation !== undefined) {
+        audit.warnings.push(`${audit.file}: exposure.key pins the auto-exposure target, so exposure.compensation is ignored beside it (the key wins)`);
+    }
+    const postGain = raw.postGain === undefined
+        ? null
+        : clampedField(audit, raw, 'postGain', DEFAULT_EXPOSURE.postGain, 'exposure', EXPOSURE_POST_GAIN_BAND);
+    const sign = compensation > 0 ? '+' : '';
+    return `exposure ${sign}${compensation} EV [${min}..${max}${min === max ? ', pinned' : ''}]`
+        + (key === null ? '' : ` key ${key}`)
+        + (postGain === null ? '' : ` · gain ${postGain}`);
+}
+function auditBloom(audit, raw) {
+    if (raw === undefined)
+        return null;
+    if (!isRecord(raw)) {
+        audit.errors.push(`${audit.file}: bloom must be an object`);
+        return 'bloom ?';
+    }
+    reportUnknownKeys(audit, raw, BLOOM_KEYS, 'bloom');
+    const intensity = nonNegativeField(audit, raw, 'intensity', 0.4, 'bloom');
+    const night = nonNegativeField(audit, raw, 'nightIntensity', 0.12, 'bloom');
+    const threshold = nonNegativeField(audit, raw, 'threshold', 4, 'bloom');
+    return `bloom ${intensity}/${night} @${threshold}`;
+}
+function auditFog(audit, raw) {
+    if (raw === undefined)
+        return null;
+    if (!isRecord(raw)) {
+        audit.errors.push(`${audit.file}: fog must be an object`);
+        return 'fog ?';
+    }
+    reportUnknownKeys(audit, raw, FOG_KEYS, 'fog');
+    const enabled = booleanField(audit, raw, 'enabled', true, 'fog');
+    const density = nonNegativeField(audit, raw, 'density', 0.0012, 'fog');
+    const heightDensity = nonNegativeField(audit, raw, 'heightDensity', 0.002, 'fog');
+    return enabled ? `fog ${density}/${heightDensity}` : 'fog off';
+}
+function auditAo(audit, raw) {
+    if (raw === undefined)
+        return null;
+    if (!isRecord(raw)) {
+        audit.errors.push(`${audit.file}: ao must be an object`);
+        return 'ao ?';
+    }
+    reportUnknownKeys(audit, raw, AO_KEYS, 'ao');
+    const intensity = nonNegativeField(audit, raw, 'intensity', 3, 'ao');
+    const radius = nonNegativeField(audit, raw, 'radius', 1.8, 'ao');
+    return `ao ${intensity} r${radius}`;
+}
+const UNAUTHORED_TRANSPORT = { fragment: null, retuned: false };
+/**
+ * An enum, so a wrong SPELLING fails the way `grade.look` does — a mode that silently fell back would leave the
+ * warm ramp on a sun the world believes it replaced. `replace` with nothing to replace the ramp WITH is the one
+ * incoherent pair: the engine warns and behaves as `multiply`, so this warns too.
+ */
+function sunTintModeField(audit, source, tint) {
+    const value = source.tintMode;
+    if (value === undefined)
+        return DEFAULT_SUN_TINT_MODE;
+    if (typeof value !== 'string' || !SUN_TINT_MODES.includes(value)) {
+        audit.errors.push(`${audit.file}: sun.tintMode must be one of ${SUN_TINT_MODES.join(' | ')} (got ${JSON.stringify(value)})`);
+        return DEFAULT_SUN_TINT_MODE;
+    }
+    if (value === 'replace' && tint === null) {
+        audit.warnings.push(`${audit.file}: sun.tintMode "replace" needs a sun.tint to replace the elevation warm ramp with — it behaves as "multiply"`);
+        return DEFAULT_SUN_TINT_MODE;
+    }
+    return value;
+}
+/** The sun's strength and colour. Transport, not post: it lights the world the probe bake captures. */
+function auditSun(audit, raw) {
+    if (raw === undefined)
+        return UNAUTHORED_TRANSPORT;
+    if (!isRecord(raw)) {
+        audit.errors.push(`${audit.file}: sun must be an object`);
+        return { fragment: 'sun ?', retuned: false };
+    }
+    reportUnknownKeys(audit, raw, SUN_KEYS, 'sun');
+    const scale = clampedField(audit, raw, 'intensityScale', DEFAULT_SUN_INTENSITY_SCALE, 'sun', SUN_INTENSITY_SCALE_BAND);
+    const tint = hexColorField(audit, raw, 'tint', 'sun');
+    const tintMode = sunTintModeField(audit, raw, tint);
+    return {
+        fragment: `sun ×${scale}${tint === null ? '' : ` ${tint}`}${tintMode === DEFAULT_SUN_TINT_MODE ? '' : ` ${tintMode}`}`,
+        retuned: scale !== DEFAULT_SUN_INTENSITY_SCALE || tint !== null || tintMode !== DEFAULT_SUN_TINT_MODE,
+    };
+}
+/**
+ * The sky itself: how thick its air reads (Linke's TL) and how bright the whole dome is. Transport — the probe
+ * cubes photograph this sky, and TL shapes the SUN BEAM's own elevation curve too, so the direct and sky halves
+ * of one daylight never disagree. `irradianceScale` is NOT `environment.intensity`: this says the sky IS
+ * brighter, that one says how much of it the materials see as IBL, and the two multiply.
+ */
+function auditSky(audit, raw) {
+    if (raw === undefined)
+        return UNAUTHORED_TRANSPORT;
+    if (!isRecord(raw)) {
+        audit.errors.push(`${audit.file}: sky must be an object`);
+        return { fragment: 'sky ?', retuned: false };
+    }
+    reportUnknownKeys(audit, raw, SKY_KEYS, 'sky');
+    const turbidity = clampedField(audit, raw, 'turbidity', DEFAULT_SKY_TURBIDITY, 'sky', SKY_TURBIDITY_BAND);
+    const scale = clampedField(audit, raw, 'irradianceScale', DEFAULT_SKY_IRRADIANCE_SCALE, 'sky', SKY_IRRADIANCE_SCALE_BAND);
+    const floor = clampedField(audit, raw, 'twilightFloor', DEFAULT_SKY_TWILIGHT_FLOOR, 'sky', SKY_TWILIGHT_FLOOR_BAND);
+    // The floor is blended at runtime on top of whatever was baked, so it never asks for a re-bake.
+    return {
+        fragment: `sky TL ${turbidity} ×${scale}${floor !== DEFAULT_SKY_TWILIGHT_FLOOR ? ` · night floor ${floor}` : ''}`,
+        retuned: turbidity !== DEFAULT_SKY_TURBIDITY || scale !== DEFAULT_SKY_IRRADIANCE_SCALE,
+    };
+}
+/** The environment (sky/ambient) light's strength — transport, so the bake captures whatever it is set to. */
+function auditEnvironment(audit, raw) {
+    if (raw === undefined)
+        return UNAUTHORED_TRANSPORT;
+    if (!isRecord(raw)) {
+        audit.errors.push(`${audit.file}: environment must be an object`);
+        return { fragment: 'env ?', retuned: false };
+    }
+    reportUnknownKeys(audit, raw, ENVIRONMENT_KEYS, 'environment');
+    const intensity = clampedField(audit, raw, 'intensity', DEFAULT_ENVIRONMENT_INTENSITY, 'environment', ENVIRONMENT_INTENSITY_BAND);
+    return { fragment: `env ${intensity}`, retuned: intensity !== DEFAULT_ENVIRONMENT_INTENSITY };
+}
+/**
+ * How strongly a shadow darkens what it falls on, 0 (none) to 1 (full), and how far the sun's ortho box reaches
+ * — both transport, so the bake holds them: it photographs the scene WITH its shadows.
+ */
+function auditShadows(audit, raw) {
+    if (raw === undefined)
+        return UNAUTHORED_TRANSPORT;
+    if (!isRecord(raw)) {
+        audit.errors.push(`${audit.file}: shadows must be an object`);
+        return { fragment: 'shadows ?', retuned: false };
+    }
+    reportUnknownKeys(audit, raw, SHADOWS_KEYS, 'shadows');
+    const opacity = clampedField(audit, raw, 'opacity', DEFAULT_SHADOW_OPACITY, 'shadows', SHADOW_OPACITY_BAND);
+    const extent = clampedNullableField(audit, raw, 'extent', 'shadows', SHADOW_EXTENT_BAND);
+    return {
+        fragment: `shadows ${opacity}${extent === null ? '' : ` extent ${extent}m`}`,
+        retuned: opacity !== DEFAULT_SHADOW_OPACITY || extent !== null,
+    };
+}
+/**
+ * Exactly three finite numbers, or null where the field is absent. `positive` additionally rejects a zero or
+ * negative extent. The engine parser THROWS on both — a collapsed axis is a degenerate box, not a small one —
+ * so both are errors here, per the mirror rule.
+ */
+function tripleField(audit, source, key, what, positive) {
+    const value = source[key];
+    if (value === undefined)
+        return null;
+    if (!Array.isArray(value) || value.length !== 3 || value.some((n) => typeof n !== 'number' || !Number.isFinite(n))) {
+        audit.errors.push(`${audit.file}: ${what}.${key} must be three finite numbers [x, y, z]`);
+        return null;
+    }
+    const numbers = value;
+    if (positive && numbers.some((n) => !(n > 0))) {
+        audit.errors.push(`${audit.file}: ${what}.${key} components must all be greater than 0`);
+        return null;
+    }
+    return numbers;
+}
+/**
+ * The authored probe budget, mirroring `parseProbeBudget`: a preset name, or three whole probe counts. A budget
+ * outside the band is refused WHOLE — the engine warns and falls back to the default — while a value that is not
+ * a budget at all (an unknown preset, a two-member array) is a throw there and an error here. Null = unauthored.
+ */
+function probeBudgetField(audit, source, what = 'probes') {
+    const value = source.budget;
+    if (value === undefined)
+        return null;
+    const presets = Object.keys(PROBE_BUDGET_PRESETS).join(' | ');
+    if (typeof value === 'string') {
+        const preset = PROBE_BUDGET_PRESETS[value];
+        if (preset === undefined) {
+            audit.errors.push(`${audit.file}: ${what}.budget must be ${presets} or three probe counts [nx, ny, nz]`);
+            return null;
+        }
+        return preset;
+    }
+    if (!Array.isArray(value) || value.length !== 3 || value.some((n) => typeof n !== 'number' || !Number.isFinite(n))) {
+        audit.errors.push(`${audit.file}: ${what}.budget must be three probe counts [nx, ny, nz] or one of ${presets}`);
+        return null;
+    }
+    const budget = value;
+    const refused = `— using the default budget [${DEFAULT_PROBE_BUDGET.join(', ')}]`;
+    for (let index = 0; index < 3; index += 1) {
+        const count = budget[index];
+        const axis = 'xyz'[index];
+        if (!Number.isInteger(count)) {
+            audit.warnings.push(`${audit.file}: ${what}.budget ${axis} is ${count} and probes are whole ${refused}`);
+            return DEFAULT_PROBE_BUDGET;
+        }
+        if (count < PROBE_BUDGET_AXIS_BAND.min || count > PROBE_BUDGET_AXIS_BAND.max) {
+            audit.warnings.push(`${audit.file}: ${what}.budget ${axis} is ${count}, outside [${PROBE_BUDGET_AXIS_BAND.min}, ${PROBE_BUDGET_AXIS_BAND.max}] ${refused}`);
+            return DEFAULT_PROBE_BUDGET;
+        }
+    }
+    const total = budget[0] * budget[1] * budget[2];
+    if (total > PROBE_BUDGET_MAX) {
+        audit.warnings.push(`${audit.file}: ${what}.budget [${budget.join(', ')}] is ${total} probes, over the cap of ${PROBE_BUDGET_MAX} ${refused}`);
+        return DEFAULT_PROBE_BUDGET;
+    }
+    return budget;
+}
+// The atlas the field lives in, mirrored from `probeAtlasLayout` (systems/visual/src/probes/probeVisibility.ts):
+// 7 SH slices per padded Z layer, the params row, ONE depth tile per probe, the cell mask, the anchor, the occlusion slab at 8 voxels per
+// cell per axis over a 34² tile pitch, then the nz relocation-offset slices — LAST, so the sampler derives their base as `depth - nz`.
+// 196 probes ask for 322 slices, 720 for 1045.
+const PROBE_OCT_PADDED = 34;
+// The engine's OCC_PER_CELL (probeOcclusion.ts) — raised 4 → 8 in the corner wave: at 4 a 5 m cell makes
+// 1.25 m voxels over 0.3 m walls and the corner junction is ambiguous under every gate.
+const OCC_PER_CELL = 8;
+/** GLES3 guarantees 256 3D-texture layers; desktop drivers report 2048. A field over the floor is a phone that
+ *  cannot allocate the atlas, which costs it DDGI visibility — not a world that fails to boot. */
+const PROBE_ATLAS_MOBILE_FLOOR = 256;
+const PROBE_ATLAS_DESKTOP_MAX = 2048;
+function probeAtlasDepth([nx, ny, nz]) {
+    const cells = [Math.max(nx - 1, 1), Math.max(ny - 1, 1), Math.max(nz - 1, 1)];
+    const voxels = cells[0] * cells[1] * cells[2] * OCC_PER_CELL ** 3;
+    const occlusionBase = 7 * (nz + 2) + 1 + nx * ny * nz + cells[2] + 1;
+    return occlusionBase + Math.ceil(voxels / (Math.max(nx, PROBE_OCT_PADDED) * Math.max(ny, PROBE_OCT_PADDED))) + nz;
+}
+const metres = (value) => String(Math.round(value * 100) / 100);
+/**
+ * What a budget actually buys, neither number being visible in the document: the CELL pitch it lands at inside
+ * the box (the probes span it corner to corner, so `size / (n - 1)`), and the 3D-texture slices its atlas asks
+ * for. A bigger budget buys tighter cells over the same box — `probes.size` is what buys a different box.
+ */
+function reportProbeGrid(audit, budget, size) {
+    const [nx, ny, nz] = budget;
+    const cells = budget.map((count, axis) => size[axis] / Math.max(count - 1, 1));
+    const depth = probeAtlasDepth(budget);
+    audit.notes.push(`${audit.file}: probes ${nx}×${ny}×${nz} = ${nx * ny * nz} over ${size.map(metres).join(' × ')} m — cells ` +
+        `${cells.map(metres).join(' × ')} m · atlas ${depth} slices`);
+    if (depth > PROBE_ATLAS_DESKTOP_MAX) {
+        audit.errors.push(`${audit.file}: that atlas is ${depth} 3D-texture slices, past the ${PROBE_ATLAS_DESKTOP_MAX} desktop drivers report — ` +
+            'it cannot be allocated anywhere; lower probes.budget');
+    }
+    else if (depth > PROBE_ATLAS_MOBILE_FLOOR) {
+        audit.notes.push(`${audit.file}: that atlas is ${depth} 3D-texture slices, over the ${PROBE_ATLAS_MOBILE_FLOOR} GLES3 guarantees — ` +
+            'a phone that caps there loses DDGI visibility for this world');
+    }
+}
+/**
+ * The probe volume box: where `helix bake-lighting` captures the field, AND — via an authored centre — where a
+ * dynamic world pins its runtime volume statically instead of following the camera, so the pre-bake world
+ * previews the exact box its bake will use. Absent a centre the placement is camera-derived (the bake pins off
+ * the boot camera, which stands where the world STARTS; a dynamic volume scrolls, and `size` is ignored there).
+ * `budget` and `bounces` are the FIELD's own shape, so they are transport too — and bake-only: a dynamic world's
+ * live refresh runs its own budget-free feedback bounce and never reads either.
+ */
+function auditProbes(audit, raw) {
+    if (raw === undefined)
+        return UNAUTHORED_TRANSPORT;
+    if (!isRecord(raw)) {
+        audit.errors.push(`${audit.file}: probes must be an object`);
+        return { fragment: 'bake volume ?', retuned: false };
+    }
+    reportUnknownKeys(audit, raw, PROBES_KEYS, 'probes');
+    const center = tripleField(audit, raw, 'center', 'probes', false);
+    const size = tripleField(audit, raw, 'size', 'probes', true);
+    const budget = probeBudgetField(audit, raw);
+    // Rounded after the band, exactly as the engine parser does — 2.5 passes lands on a real pass count.
+    const bounces = raw.bounces === undefined
+        ? null
+        : Math.round(clampedField(audit, raw, 'bounces', DEFAULT_PROBE_BOUNCES, 'probes', PROBE_BOUNCES_BAND));
+    const skyFallback = tristateField(audit, raw, 'skyFallback', 'probes');
+    if (budget !== null || size !== null)
+        reportProbeGrid(audit, budget ?? DEFAULT_PROBE_BUDGET, size ?? DEFAULT_PROBE_SPAN);
+    const nested = auditProbeVolumes(audit, raw.volumes);
+    if (nested.count > 0) {
+        // Every volume stacks into ONE 3D texture (plus a one-slice directory), so the LIMITS are judged on the sum.
+        const total = probeAtlasDepth(budget ?? DEFAULT_PROBE_BUDGET) + nested.slices + 1;
+        audit.notes.push(`${audit.file}: probes + ${nested.count} nested volume${nested.count === 1 ? '' : 's'} stack into one atlas ≈ ${total} slices`);
+        if (total > PROBE_ATLAS_DESKTOP_MAX) {
+            audit.errors.push(`${audit.file}: that stacked atlas is ≈ ${total} 3D-texture slices, past the ${PROBE_ATLAS_DESKTOP_MAX} desktop drivers report — ` +
+                'it cannot be allocated anywhere; lower a budget or drop a volume');
+        }
+        else if (total > PROBE_ATLAS_MOBILE_FLOOR) {
+            audit.notes.push(`${audit.file}: that stacked atlas is ≈ ${total} 3D-texture slices, over the ${PROBE_ATLAS_MOBILE_FLOOR} GLES3 guarantees — ` +
+                'a phone that caps there loses DDGI visibility for this world');
+        }
+    }
+    const authored = [
+        center === null ? null : `centre [${center.join(', ')}]`,
+        size === null ? null : `size [${size.join(', ')}]`,
+        budget === null ? null : `budget [${budget.join(', ')}]`,
+        bounces === null ? null : `${bounces} bounce${bounces === 1 ? '' : 's'}`,
+        skyFallback === null ? null : `sky fallback ${skyFallback ? 'on' : 'off'}`,
+        nested.count === 0 ? null : `${nested.count} nested volume${nested.count === 1 ? '' : 's'}`,
+    ].filter((part) => part !== null);
+    const budgetMoved = budget !== null && budget.some((count, axis) => count !== DEFAULT_PROBE_BUDGET[axis]);
+    return {
+        fragment: `bake volume ${authored.length ? authored.join(' ') : 'engine-derived'}`,
+        retuned: budgetMoved || (bounces !== null && bounces !== DEFAULT_PROBE_BOUNCES) || nested.count > 0,
+    };
+}
+/** One nested volume's `pad` — metres past the box its SELECTION still owns. Mirrors the engine's
+ *  `parseProbePad` shapes exactly; the engine throws where this reports an error. */
+function padField(audit, value, what) {
+    if (value === undefined)
+        return;
+    const shapes = `${audit.file}: ${what}.pad must be metres >= 0 — a number, [x, y, z], or { x?, y?, z? } each a number or [minFace, maxFace]`;
+    const face = (v) => (typeof v === 'number' && Number.isFinite(v) && v >= 0) ||
+        (Array.isArray(v) && v.length === 2 && v.every((n) => typeof n === 'number' && Number.isFinite(n) && n >= 0));
+    if (typeof value === 'number') {
+        if (!(Number.isFinite(value) && value >= 0))
+            audit.errors.push(shapes);
+        return;
+    }
+    if (Array.isArray(value)) {
+        if (value.length !== 3 || value.some((n) => typeof n !== 'number' || !Number.isFinite(n) || n < 0))
+            audit.errors.push(shapes);
+        return;
+    }
+    if (!isRecord(value)) {
+        audit.errors.push(shapes);
+        return;
+    }
+    reportUnknownKeys(audit, value, ['x', 'y', 'z'], `${what}.pad`);
+    for (const axis of ['x', 'y', 'z']) {
+        if (value[axis] !== undefined && !face(value[axis])) {
+            audit.errors.push(shapes);
+            return;
+        }
+    }
+}
+/**
+ * The NESTED probe volumes — a denser lattice over one room, baked into the same artifact. Mirrors the
+ * engine's `parseProbeVolumes`: `center` and `size` are REQUIRED (a volume without a box is nothing, and the
+ * engine refuses the document), the budget shares the world band, `blendMetres` past half the smallest extent
+ * never reaches full weight, and the cells are reported against the measured corner floor.
+ */
+function auditProbeVolumes(audit, raw) {
+    if (raw === undefined)
+        return { count: 0, slices: 0 };
+    if (!Array.isArray(raw)) {
+        audit.errors.push(`${audit.file}: probes.volumes must be an array of nested probe volumes`);
+        return { count: 0, slices: 0 };
+    }
+    if (raw.length > PROBE_VOLUME_MAX) {
+        audit.warnings.push(`${audit.file}: probes.volumes has ${raw.length} volumes, over the cap of ${PROBE_VOLUME_MAX} — the extras are ignored`);
+    }
+    const entries = raw.slice(0, PROBE_VOLUME_MAX);
+    let slices = 0;
+    for (const [index, entry] of entries.entries()) {
+        const what = `probes.volumes[${index}]`;
+        if (!isRecord(entry)) {
+            audit.errors.push(`${audit.file}: ${what} must be an object`);
+            continue;
+        }
+        reportUnknownKeys(audit, entry, PROBE_VOLUME_KEYS, what);
+        const size = tripleField(audit, entry, 'size', what, true);
+        if (entry.center === undefined) {
+            audit.errors.push(`${audit.file}: ${what}.center is required — a nested volume is a box somewhere, or it is nothing`);
+        }
+        else {
+            tripleField(audit, entry, 'center', what, false);
+        }
+        if (entry.size === undefined) {
+            audit.errors.push(`${audit.file}: ${what}.size is required — a nested volume is a box of some extent, or it is nothing`);
+        }
+        const budget = probeBudgetField(audit, entry, what) ?? DEFAULT_PROBE_BUDGET;
+        if (entry.blendMetres !== undefined) {
+            const blend = nonNegativeField(audit, entry, 'blendMetres', DEFAULT_PROBE_VOLUME_BLEND, what);
+            if (size !== null && blend > Math.min(...size) / 2) {
+                audit.warnings.push(`${audit.file}: ${what}.blendMetres ${blend} exceeds half the smallest extent (${metres(Math.min(...size) / 2)}) — ` +
+                    'the volume never reaches full weight anywhere inside itself');
+            }
+        }
+        padField(audit, entry.pad, what);
+        slices += probeAtlasDepth(budget);
+        if (size !== null) {
+            const cells = budget.map((count, axis) => size[axis] / Math.max(count - 1, 1));
+            audit.notes.push(`${audit.file}: ${what} ${budget.join('×')} = ${budget[0] * budget[1] * budget[2]} over ${size.map(metres).join(' × ')} m — ` +
+                `cells ${cells.map(metres).join(' × ')} m`);
+            if (Math.max(...cells) > NESTED_CELL_CORNER_HINT) {
+                audit.notes.push(`${audit.file}: ${what} cells reach ${metres(Math.max(...cells))} m — interior corners hold at ~${NESTED_CELL_CORNER_HINT} m ` +
+                    'and under (measured); raise its budget or shrink its box');
+            }
+        }
+    }
+    return { count: entries.length, slices };
+}
+/** A volume's override of a post-stack block is SPARSE: an unauthored field keeps the document's value. */
+function auditVolumeBlock(audit, raw, known, numbers, what) {
+    if (raw === undefined)
+        return;
+    if (!isRecord(raw)) {
+        audit.errors.push(`${audit.file}: ${what} must be an object`);
+        return;
+    }
+    reportUnknownKeys(audit, raw, known, what);
+    for (const key of numbers) {
+        if (raw[key] !== undefined)
+            nonNegativeField(audit, raw, key, 0, what);
+    }
+}
+function auditVolumeExposure(audit, raw, what) {
+    if (raw === undefined)
+        return;
+    if (!isRecord(raw)) {
+        audit.errors.push(`${audit.file}: ${what} must be an object`);
+        return;
+    }
+    reportUnknownKeys(audit, raw, EXPOSURE_KEYS, what);
+    clampedCompensation(audit, raw, what);
+    auditVolumeExposureKeys(audit, raw, what);
+    // Sparse, so an unauthored end still comes from the document: the band is only coherence-checked when the
+    // volume authors both, and a lone end is judged on its sign alone.
+    const min = raw.min === undefined ? null : numberField(audit, raw, 'min', DEFAULT_EXPOSURE.min, what);
+    const max = raw.max === undefined ? null : numberField(audit, raw, 'max', DEFAULT_EXPOSURE.max, what);
+    if (min !== null && max !== null) {
+        auditExposureBand(audit, min, max, what);
+        return;
+    }
+    const lone = min ?? max;
+    if (lone !== null && !(lone > 0)) {
+        audit.errors.push(`${audit.file}: ${what}.${min !== null ? 'min' : 'max'} must be a positive exposure multiplier`);
+    }
+}
+/** The two post-stack exposure knobs a volume may also pull. An explicit `key: null` is AUTHORED here, not
+ *  absent: it is how a box inside a keyed document hands the hour back to the day/night schedule. */
+function auditVolumeExposureKeys(audit, raw, what) {
+    if (raw.key !== undefined)
+        clampedNullableField(audit, raw, 'key', what, EXPOSURE_KEY_BAND);
+    if (raw.postGain !== undefined)
+        clampedField(audit, raw, 'postGain', DEFAULT_EXPOSURE.postGain, what, EXPOSURE_POST_GAIN_BAND);
+}
+function auditVolume(audit, raw, what) {
+    if (!isRecord(raw)) {
+        audit.errors.push(`${audit.file}: ${what} must be an object`);
+        return;
+    }
+    // The document-level blocks a volume cannot take get their own word, so they are not reported as typos.
+    for (const key of VOLUME_EXCLUDED_KEYS) {
+        if (raw[key] === undefined)
+            continue;
+        const why = key === 'grade'
+            ? ' — the grade is baked at compile time, so it cannot vary with the camera'
+            : TRANSPORT_KEYS.includes(key)
+                ? ' — it is a light-transport value that lights the whole world, so it cannot vary with the camera position'
+                : '';
+        audit.warnings.push(`${audit.file}: ${what}.${key} is not overridable per volume and is ignored${why}; a volume may override ${VOLUME_OVERRIDE_KEYS.join(', ')}`);
+    }
+    const scoped = Object.fromEntries(Object.entries(raw).filter(([key]) => !VOLUME_EXCLUDED_KEYS.includes(key)));
+    reportUnknownKeys(audit, scoped, VOLUME_KEYS, what);
+    // The box is the whole point of a volume: without a centre or an extent there is nothing to blend inside of.
+    if (raw.center === undefined) {
+        audit.errors.push(`${audit.file}: ${what}.center is required — three finite numbers [x, y, z], the box centre`);
+    }
+    else {
+        tripleField(audit, raw, 'center', what, false);
+    }
+    if (raw.size === undefined) {
+        audit.errors.push(`${audit.file}: ${what}.size is required — three finite numbers [x, y, z], the box extent`);
+    }
+    else {
+        tripleField(audit, raw, 'size', what, true);
+    }
+    nonNegativeField(audit, raw, 'blendMetres', DEFAULT_VOLUME_BLEND_METRES, what);
+    auditVolumeExposure(audit, raw.exposure, `${what}.exposure`);
+    auditVolumeBlock(audit, raw.bloom, BLOOM_KEYS, BLOOM_KEYS, `${what}.bloom`);
+    auditVolumeBlock(audit, raw.fog, FOG_KEYS, VOLUME_FOG_KEYS, `${what}.fog`);
+    if (isRecord(raw.fog) && raw.fog.enabled !== undefined) {
+        audit.warnings.push(`${audit.file}: ${what}.fog.enabled is not overridable per volume and is ignored — fade a volume's fog by blending fog.density toward 0`);
+    }
+    auditVolumeBlock(audit, raw.ao, AO_KEYS, AO_KEYS, `${what}.ao`);
+}
+/**
+ * The post-processing volumes: camera-position-driven local overrides of the document's own look blocks. Weight
+ * is 1 inside the box and ramps to 0 over `blendMetres` OUTWARD from its surface, and the volumes compose in
+ * ARRAY ORDER — effective = lerp(effective, volumeValue, weight) per authored field, starting from the document.
+ */
+function auditVolumes(audit, raw) {
+    if (raw === undefined)
+        return null;
+    if (!Array.isArray(raw)) {
+        audit.errors.push(`${audit.file}: volumes must be an array of post-processing volumes`);
+        return 'volumes ?';
+    }
+    raw.forEach((entry, index) => auditVolume(audit, entry, `volumes[${index}]`));
+    return `${raw.length} volumes`;
+}
+function auditPracticals(audit, raw) {
+    if (raw === undefined)
+        return '0 practicals';
+    if (!Array.isArray(raw)) {
+        audit.errors.push(`${audit.file}: practicals must be an array`);
+        return '? practicals';
+    }
+    raw.forEach((entry, index) => {
+        if (!isRecord(entry))
+            audit.errors.push(`${audit.file}: practicals[${index}] must be an object`);
+    });
+    if (raw.length) {
+        // The engine carries practicals verbatim: the practicals/night rig has not moved into the package yet.
+        audit.warnings.push(`${audit.file}: ${raw.length} practical(s) are carried verbatim — nothing in the visual runtime reads them yet`);
+    }
+    return `${raw.length} practicals`;
+}
+/**
+ * The bake step's artifact pointer. ABSENT IS NOT AN ERROR HERE, exactly as it is not in the engine parser: the
+ * bake writes the block into this same document later, and refusing an un-baked `mode: "baked"` world would make
+ * it unopenable by the very tool that has to bake it. A pointer that IS there is checked on the spot — but the
+ * runtime only READS it on a `baked` world (it throws there rather than fall back to the zero-bake look), so on
+ * any other mode a malformed block is something the engine tolerates: a WARNING, per the mirror rule.
+ */
+function auditBakedLightingPointer(audit, raw, severe) {
+    if (raw === undefined || raw === null)
+        return null;
+    const sink = severe ? audit.errors : audit.warnings;
+    if (!isRecord(raw)) {
+        sink.push(`${audit.file}: bakedLighting must be an object`);
+        return null;
+    }
+    const version = raw.version;
+    const artifact = raw.artifact;
+    let valid = true;
+    if (typeof version !== 'number' || version !== exports.BAKED_LIGHTING_VERSION) {
+        sink.push(`${audit.file}: bakedLighting.version must be ${exports.BAKED_LIGHTING_VERSION} (got ${JSON.stringify(version)})`);
+        valid = false;
+    }
+    if (typeof artifact !== 'string' || artifact.trim() === '') {
+        sink.push(`${audit.file}: bakedLighting.artifact must be a non-empty string — the baked field, relative to the world root`);
+        valid = false;
+    }
+    // The key receipt is the bake's, and a pointer written before it existed carries none — absent is not a fault.
+    const rawKeys = raw.keys;
+    let keys = null;
+    if (rawKeys !== undefined && rawKeys !== null) {
+        if (typeof rawKeys !== 'number' || !Number.isInteger(rawKeys) || rawKeys < 1) {
+            sink.push(`${audit.file}: bakedLighting.keys must be a positive integer — the sun keys the artifact carries (got ${JSON.stringify(rawKeys)})`);
+            valid = false;
+        }
+        else {
+            keys = rawKeys;
+        }
+    }
+    return valid ? { version: version, artifact: artifact, keys } : null;
+}
+/**
+ * The bake's key receipt against the world's own sun. ONE key is the STATIC plan and plays back clamped onto its
+ * only key at every hour, so under a moving sun the indirect light is pinned to the baked hour while the sky goes
+ * on turning — the runtime says so at boot, and this says so at publish, where it can still be re-baked.
+ */
+function auditBakedKeys(audit, pointer, cycleSeconds) {
+    const keys = pointer?.keys ?? null;
+    if (keys === null)
+        return;
+    if (keys === 1 && cycleSeconds > 0) {
+        audit.errors.push(`${audit.file}: the artifact carries ONE sun key and this world's sun cycles (timeOfDay.cycleSeconds ${cycleSeconds}) — the ` +
+            'indirect light stays pinned to the baked hour while the sky moves; re-bake with `helix bake-lighting --keys N`');
+    }
+    else if (keys > 1 && cycleSeconds === 0) {
+        audit.notes.push(`${audit.file}: the artifact carries ${keys} sun keys and this world's sun is static — a static sun needs one key; ` +
+            `re-bake for a ~${keys}× smaller artifact`);
+    }
+}
+/**
+ * Audits a parsed `helix.visuals.json` document against the v1 rules the engine's parser enforces. `file` is
+ * the path the messages name, so the creator is told which copy is wrong when both source and bundle carry one.
+ */
+function auditVisualsConfig(raw, file = exports.VISUALS_CONFIG_FILE) {
+    const audit = { errors: [], warnings: [], notes: [], file };
+    // The parser answers a null/absent document with the scaffold default, so a `null` file boots — but nobody
+    // means it, and the world then renders the default look rather than the one the file was meant to declare.
+    if (raw === null) {
+        return {
+            errors: [],
+            warnings: [`${file}: the document is null — the runtime falls back to the scaffold default (dynamic, static noon sun)`],
+            notes: [],
+            summary: `${file}: null · the scaffold default (dynamic, sun ${DEFAULT_HOURS}h, grade ${DEFAULT_LOOK})`,
+            cycleSeconds: 0,
+            mode: DEFAULT_MODE,
+            bakedLighting: null,
+            hasBakedLighting: false,
+        };
+    }
+    if (!isRecord(raw)) {
+        return {
+            errors: [`${file}: the document must be an object`],
+            warnings: [],
+            notes: [],
+            summary: null,
+            cycleSeconds: 0,
+            mode: null,
+            bakedLighting: null,
+            hasBakedLighting: false,
+        };
+    }
+    const version = raw.version;
+    if (typeof version !== 'number' || version !== exports.VISUALS_CONFIG_VERSION) {
+        audit.errors.push(`${file}: version must be ${exports.VISUALS_CONFIG_VERSION} (got ${JSON.stringify(version)})`);
+    }
+    const mode = raw.mode;
+    let declaredMode = null;
+    if (typeof mode !== 'string' || !exports.VISUALS_MODES.includes(mode)) {
+        audit.errors.push(`${file}: mode must be one of ${exports.VISUALS_MODES.join(' | ')} (got ${JSON.stringify(mode)})`);
+    }
+    else {
+        declaredMode = mode;
+    }
+    // What `mode: "baked"` POINTS AT is only half-checkable from the document: the pointer's shape is judged here,
+    // whether it resolves to a shipped artifact by the bundle rule in bundle.ts.
+    const bakedLighting = auditBakedLightingPointer(audit, raw.bakedLighting, declaredMode === 'baked');
+    const timeOfDay = auditTimeOfDay(audit, raw.timeOfDay);
+    auditWeather(audit, raw.weather, declaredMode);
+    auditOcean(audit, raw.ocean, declaredMode);
+    if (declaredMode === 'baked')
+        auditBakedKeys(audit, bakedLighting, timeOfDay.cycleSeconds);
+    // The transport blocks sit beside the sun's own segment in the line: they are what the world is LIT with,
+    // where the grade and the post stack below are what the frame is then developed with.
+    const transport = [
+        ['sun', auditSun(audit, raw.sun)],
+        ['sky', auditSky(audit, raw.sky)],
+        ['environment', auditEnvironment(audit, raw.environment)],
+        ['shadows', auditShadows(audit, raw.shadows)],
+    ];
+    const transportBlocks = transport
+        .map(([, block]) => block.fragment)
+        .filter((fragment) => fragment !== null);
+    // The probe block is transport too, but its fragment belongs with the boxes further down the line, so it is
+    // audited here — in the transport pass whose re-bake warning it joins — and placed there.
+    const probes = auditProbes(audit, raw.probes);
+    // LIVE nested volumes need a PINNED volume: the engine serves them on a dynamic world only with an authored
+    // probes.center (the sampler reads every volume's box from a directory written once, which a camera-following
+    // volume would strand on its first crossing). Mirrors the engine parser's warning, message for message.
+    if (declaredMode === 'dynamic' && isRecord(raw.probes) && raw.probes.center === undefined
+        && Array.isArray(raw.probes.volumes) && raw.probes.volumes.length > 0) {
+        audit.warnings.push(`${file}: probes.volumes on a dynamic world without probes.center — nested volumes need a PINNED volume` +
+            ' (author probes.center + probes.size), so they will not serve in this world as authored');
+    }
+    // A transport value is captured INTO the field at bake time, so on a baked world an edit here is inert until
+    // the next bake — the one way a valid document still renders something other than what it says.
+    const retuned = [...transport.filter(([, block]) => block.retuned).map(([name]) => name), ...(probes.retuned ? ['probes'] : [])];
+    if (retuned.length && declaredMode === 'baked') {
+        audit.warnings.push(`${file}: ${retuned.join(', ')} — light transport, captured INTO the field on a mode "baked" world — so the shipped ` +
+            'field still holds what it was baked with; re-run `helix bake-lighting` for a change here to take effect');
+    }
+    const grade = auditGrade(audit, raw.grade);
+    // The authored post-stack blocks, the bake volume and the post-processing volumes appear in the summary only
+    // when the document carries them.
+    const optionalBlocks = [
+        auditExposure(audit, raw.exposure),
+        auditBloom(audit, raw.bloom),
+        auditFog(audit, raw.fog),
+        auditAo(audit, raw.ao),
+        probes.fragment,
+        auditVolumes(audit, raw.volumes),
+    ].filter((fragment) => fragment !== null);
+    const practicals = auditPracticals(audit, raw.practicals);
+    // Unknown TOP-LEVEL keys are carried on purpose (the bake artifact pointer rides here, and an older runtime
+    // must still boot a newer document) — so they are never an error, and only a near-miss of a claimed key is
+    // worth a word.
+    const carried = Object.keys(raw).filter((key) => !CLAIMED_KEYS.includes(key));
+    for (const key of carried) {
+        const suggestion = didYouMean(key, CLAIMED_KEYS);
+        if (suggestion) {
+            audit.warnings.push(`${file}: "${key}" is carried verbatim, not read — did you mean "${suggestion}"?`);
+        }
+    }
+    const summary = audit.errors.length
+        ? null
+        : `${file}: v${exports.VISUALS_CONFIG_VERSION} ${String(mode)} · ${timeOfDay.fragment}` +
+            (transportBlocks.length ? ` · ${transportBlocks.join(' · ')}` : '') +
+            ` · ${grade}` +
+            (optionalBlocks.length ? ` · ${optionalBlocks.join(' · ')}` : '') +
+            ` · ${practicals}` +
+            (carried.length ? ` · carries ${carried.join(', ')}` : '');
+    return {
+        errors: audit.errors,
+        warnings: audit.warnings,
+        notes: audit.notes,
+        summary,
+        cycleSeconds: timeOfDay.cycleSeconds,
+        mode: declaredMode,
+        bakedLighting,
+        hasBakedLighting: raw.bakedLighting !== undefined && raw.bakedLighting !== null,
+    };
+}
+/** The same audit over the document's TEXT — unparseable JSON is an error here, as it is a throw at boot. */
+function auditVisualsConfigText(text, file = exports.VISUALS_CONFIG_FILE) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        return {
+            errors: [`${file} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`],
+            warnings: [],
+            notes: [],
+            summary: null,
+            cycleSeconds: 0,
+            mode: null,
+            bakedLighting: null,
+            hasBakedLighting: false,
+        };
+    }
+    return auditVisualsConfig(parsed, file);
+}
+const isFiniteTriple = (value) => Array.isArray(value) && value.length === 3 && value.every((n) => typeof n === 'number' && Number.isFinite(n));
+const isCountTriple = (value) => Array.isArray(value) && value.length === 3 && value.every((n) => typeof n === 'number' && Number.isInteger(n) && n > 0);
+const isBase64Payload = (value) => typeof value === 'string' && value !== '';
+function positiveInteger(audit, value, what) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
+        audit.errors.push(`${audit.file}: ${what} must be a positive integer (got ${JSON.stringify(value)})`);
+        return null;
+    }
+    return value;
+}
+function auditArtifactKeys(audit, raw) {
+    if (!Array.isArray(raw)) {
+        audit.errors.push(`${audit.file}: keys must be an array of keyframes`);
+        return 0;
+    }
+    if (raw.length === 0) {
+        audit.errors.push(`${audit.file}: keys is empty — a store with no keyframes plays a black field`);
+        return 0;
+    }
+    // One bad key is enough: a store this shape came out of one export, and it fails identically on every key.
+    for (let index = 0; index < raw.length; index += 1) {
+        const before = audit.errors.length;
+        const key = raw[index];
+        if (!isRecord(key)) {
+            audit.errors.push(`${audit.file}: keys[${index}] must be an object`);
+        }
+        else {
+            if (typeof key.hours !== 'number' || !Number.isFinite(key.hours)) {
+                audit.errors.push(`${audit.file}: keys[${index}].hours must be a finite number — the sun time this key was baked at`);
+            }
+            if (!isBase64Payload(key.sh)) {
+                audit.errors.push(`${audit.file}: keys[${index}].sh must be a non-empty base64 string — the key's SH coefficients`);
+            }
+        }
+        if (audit.errors.length > before)
+            break;
+    }
+    return raw.length;
+}
+/** The metadata shape shared by the legacy top-level `volume` and each volume-list entry: the box triples and
+ *  the probes lattice. Returns the lattice count and label, or null when the shape is unusable. */
+function auditVolumeMetadataShape(audit, raw, what) {
+    if (!isRecord(raw)) {
+        audit.errors.push(`${audit.file}: ${what} must be an object`);
+        return null;
+    }
+    for (const key of ['size', 'center']) {
+        if (!isFiniteTriple(raw[key]))
+            audit.errors.push(`${audit.file}: ${what}.${key} must be three finite numbers [x, y, z]`);
+    }
+    if (!isCountTriple(raw.probes)) {
+        audit.errors.push(`${audit.file}: ${what}.probes must be three positive integers [x, y, z]`);
+        return null;
+    }
+    const [px, py, pz] = raw.probes;
+    return { count: px * py * pz, lattice: `${px}x${py}x${pz}` };
+}
+/** The box the field was baked in — the LEGACY single-volume shape. MANDATORY: without it the runtime has no
+ *  grid to rebuild and refuses to boot. */
+function auditArtifactVolume(audit, raw, probeCount) {
+    if (raw === undefined || raw === null) {
+        audit.errors.push(`${audit.file}: no \`volume\` block — the runtime has no box to rebuild the probe grid in and throws at boot; re-export the bake`);
+        return '?';
+    }
+    const metadata = auditVolumeMetadataShape(audit, raw, 'volume');
+    if (metadata === null)
+        return '?';
+    if (probeCount !== null && metadata.count !== probeCount) {
+        audit.errors.push(`${audit.file}: volume ${metadata.lattice} holds ${metadata.count} probes, not the ${probeCount} its field carries`);
+    }
+    return metadata.lattice;
+}
+/**
+ * The MULTI-VOLUME artifact shape — `volumes`, world volume first — which `helix bake-lighting` writes for a
+ * world authoring nested probe volumes. Mirrors the engine reader exactly: `store.volume` is
+ * `volumes[0].volume`, so entry 0 must carry one or the runtime has no box and throws at boot; and playback
+ * refuses a field whose volumes declare a different probe total than it carries. A volume-less LATER entry is
+ * legal (a geometry-only slot spans the rest), so the total is only judged when every entry declared a lattice.
+ */
+function auditArtifactVolumeList(audit, raw, probeCount) {
+    if (!Array.isArray(raw) || raw.length === 0) {
+        audit.errors.push(`${audit.file}: volumes must be a non-empty array — the field's volume list, world volume first`);
+        return { volume: '?', geometry: false };
+    }
+    let declared = 0;
+    let allPlaced = true;
+    let world = '?';
+    let worldGeometry = false;
+    raw.forEach((entry, index) => {
+        const what = `volumes[${index}]`;
+        if (!isRecord(entry)) {
+            audit.errors.push(`${audit.file}: ${what} must be an object`);
+            allPlaced = false;
+            return;
+        }
+        if (typeof entry.firstProbe !== 'number' || !Number.isInteger(entry.firstProbe) || entry.firstProbe < 0) {
+            audit.errors.push(`${audit.file}: ${what}.firstProbe must be a non-negative integer — where this volume's span starts in every key`);
+        }
+        if (entry.volume === undefined || entry.volume === null) {
+            if (index === 0) {
+                audit.errors.push(`${audit.file}: volumes[0] carries no \`volume\` block — the world volume is the box the runtime rebuilds the probe grid in, ` +
+                    'and it throws at boot without one; re-export the bake');
+            }
+            allPlaced = false;
+        }
+        else {
+            const metadata = auditVolumeMetadataShape(audit, entry.volume, `${what}.volume`);
+            if (metadata === null)
+                allPlaced = false;
+            else {
+                declared += metadata.count;
+                if (index === 0)
+                    world = metadata.lattice;
+            }
+        }
+        // Geometry rides PER VOLUME in this shape. Entry 0's absence is the same SH-only warning the legacy shape
+        // gets; a nested volume without one plays SH-only for its own room, which the runtime notes at boot.
+        if (entry.geometry === undefined || entry.geometry === null) {
+            if (index === 0) {
+                audit.warnings.push(`${audit.file}: volumes[0] has no \`geometry\` block — this is an SH-only field, so DDGI visibility is OFF for this world ` +
+                    '(indirect light leaks through walls and the runtime warns at boot); re-export the bake with the geometry half');
+            }
+            else {
+                audit.notes.push(`${audit.file}: ${what} has no \`geometry\` block — that nested volume ships SH only`);
+            }
+        }
+        else {
+            const ok = auditArtifactGeometry(audit, entry.geometry, `${what}.geometry`);
+            if (index === 0)
+                worldGeometry = ok;
+        }
+    });
+    if (probeCount !== null && allPlaced && declared !== probeCount) {
+        audit.errors.push(`${audit.file}: the ${raw.length} volume(s) hold ${declared} probes, not the ${probeCount} the field carries`);
+    }
+    const nested = raw.length - 1;
+    return { volume: nested > 0 ? `${world} + ${nested} nested` : world, geometry: worldGeometry };
+}
+/** The sun-independent half — depth tiles, params row, cell mask. Optional, and its absence costs visibility.
+ *  `what` relabels the messages for a volume-list entry's own block; the default keeps the legacy wording. */
+function auditArtifactGeometry(audit, raw, what = 'geometry') {
+    if (raw === undefined || raw === null) {
+        audit.warnings.push(`${audit.file}: no \`geometry\` block — this is an SH-only field, so DDGI visibility is OFF for this world ` +
+            '(indirect light leaks through walls and the runtime warns at boot); re-export the bake with the geometry half');
+        return false;
+    }
+    if (!isRecord(raw)) {
+        audit.errors.push(`${audit.file}: ${what} must be an object`);
+        return false;
+    }
+    positiveInteger(audit, raw.octPadded, `${what}.octPadded`);
+    positiveInteger(audit, raw.paramTexels, `${what}.paramTexels`);
+    if (!isCountTriple(raw.maskCells))
+        audit.errors.push(`${audit.file}: ${what}.maskCells must be three positive integers [x, y, z]`);
+    for (const key of ['depth', 'params', 'mask']) {
+        if (!isBase64Payload(raw[key]))
+            audit.errors.push(`${audit.file}: ${what}.${key} must be a non-empty base64 string`);
+    }
+    return true;
+}
+/**
+ * Audits the artifact a `mode: "baked"` world points at — the engine's `ProbeKeyframeStore` JSON. SHAPE AND
+ * COUNTS ONLY: the base64 float payloads are never decoded, so `validate` stays a read of the header rather
+ * than a megabyte of atob per world. What the engine throws on decoding them (array lengths against the
+ * declared dimensions) is therefore NOT mirrored — the counts that can be checked cheaply are.
+ */
+function auditBakedArtifact(raw, file, options = {}) {
+    const audit = { errors: [], warnings: [], notes: [], file };
+    if (!isRecord(raw)) {
+        return {
+            errors: [`${file}: the baked lighting artifact must be an object — a probe keyframe store`],
+            warnings: [],
+            notes: [],
+            summary: null,
+        };
+    }
+    const probeCount = positiveInteger(audit, raw.probeCount, 'probeCount');
+    const keys = auditArtifactKeys(audit, raw.keys);
+    // The document's own receipt is judged in `auditBakedKeys`; this is the same rule read off the FIELD, which is
+    // the copy that cannot be stale — a one-key store plays back clamped onto its only key at every hour.
+    if (keys === 1 && (options.cycleSeconds ?? 0) > 0) {
+        audit.errors.push(`${file}: this field carries ONE sun key but this world's sun CYCLES — the indirect light is pinned to the baked hour ` +
+            'while the sky moves; re-bake with `helix bake-lighting --keys N`');
+    }
+    // `undefined` is NOT `null` here: the loader hands anything but null straight to atob, so a store missing the
+    // field throws where an SH-only one nulls it.
+    if (raw.practicals !== null && typeof raw.practicals !== 'string') {
+        audit.errors.push(`${file}: practicals must be a base64 string or null — the field's night term`);
+    }
+    // TWO shapes, same precedence as the engine reader: a `volumes` LIST (world volume first — what
+    // `helix bake-lighting` writes for a world authoring nested probe volumes) wins over the legacy bare
+    // `volume` + `geometry` pair every pre-nested artifact carries.
+    let volume;
+    let geometry;
+    if (raw.volumes !== undefined) {
+        ({ volume, geometry } = auditArtifactVolumeList(audit, raw.volumes, probeCount));
+    }
+    else {
+        volume = auditArtifactVolume(audit, raw.volume, probeCount);
+        geometry = auditArtifactGeometry(audit, raw.geometry);
+    }
+    const summary = audit.errors.length
+        ? null
+        : `${file}: baked field · ${probeCount} probes · ${keys} keys · volume ${volume}${geometry ? ' · geometry' : ' · SH only'}`;
+    return { errors: audit.errors, warnings: audit.warnings, notes: audit.notes, summary };
+}
+/** The same audit over the artifact's TEXT — unparseable JSON is an error, as it is a throw at boot. */
+function auditBakedArtifactText(text, file, options = {}) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        return {
+            errors: [`${file} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`],
+            warnings: [],
+            notes: [],
+            summary: null,
+        };
+    }
+    return auditBakedArtifact(parsed, file, options);
+}
+//# sourceMappingURL=visualsConfig.js.map