@hypersoniclabs/helix-cli 0.1.7 → 0.1.24-helix3.438

package/dist/vehicle/audio.js

@@ -0,0 +1,1069 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultFetch = exports.PENDING_AUDIO_ORIGIN = exports.FIRING_COMB_OCTAVE_OFF = exports.FIRING_COMB_PASS = exports.QUIET_RMS_DBFS = exports.SILENT_PEAK_DBFS = void 0;
+exports.measureWav = measureWav;
+exports.judgeWav = judgeWav;
+exports.judgeRungSpectral = judgeRungSpectral;
+exports.judgeClipDc = judgeClipDc;
+exports.judgeHornRow = judgeHornRow;
+exports.collectLadders = collectLadders;
+exports.judgeLadders = judgeLadders;
+exports.judgeRevLimiterRow = judgeRevLimiterRow;
+exports.sourceRepitchTake = sourceRepitchTake;
+exports.sourcedRecordingKey = sourcedRecordingKey;
+exports.judgeNearDuplicates = judgeNearDuplicates;
+exports.rungClips = rungClips;
+exports.judgeAgainstReference = judgeAgainstReference;
+exports.audioPitchMeta = audioPitchMeta;
+exports.judgeRungPitch = judgeRungPitch;
+exports.collectAudioRows = collectAudioRows;
+exports.runtimeRowIssues = runtimeRowIssues;
+exports.sha256OfCid = sha256OfCid;
+exports.sealedClosureSha256s = sealedClosureSha256s;
+exports.unconsumedAudioRows = unconsumedAudioRows;
+exports.closureMembershipIssues = closureMembershipIssues;
+exports.localFileFor = localFileFor;
+exports.provisionalAudio = provisionalAudio;
+exports.checkAudioLocal = checkAudioLocal;
+exports.checkAudioReadBack = checkAudioReadBack;
+exports.formatAudioReport = formatAudioReport;
+/**
+ * `helix vehicle audio-check` — does every sound a vehicle package declares actually play?
+ *
+ * WHY. A vehicle's audio fails SILENTLY. The engine's PortableVehicleAudioAdapter (helix-web-engine-new
+ * systems/engine-core/src/audio/vehicle/PortableVehicleAudioAdapter.ts) loads an asset row only when it carries a
+ * non-empty `url`, a hex `checksumSha256`, positive `bytes` and `mediaType: "audio/wav"`; it then fetches the url and
+ * refuses any body whose size or digest differs. A `cid`-only row, a url that 404s, a re-encoded file or an MP3 all
+ * end the same way: no error anywhere, a car that makes no sound, and a visual-QA pass (the gate never plays audio).
+ *
+ * This mirrors the adapter's selection rules exactly:
+ *   - bank samples: every rung named by the `engineBlend` / `exhaustBlend` blends must be a `bank.assets` row by name;
+ *   - slot one-shots: a slot row's asset is used when its `name` is one of that slot's `buffers`.
+ * and then goes one step further than the adapter: it decodes the WAV and measures it, because a digest-correct file
+ * of digital silence plays "successfully" and is still a silent car.
+ *
+ * Two modes share one report: PRE-SEAL (local files beside the package, before any upload) and READ-BACK (the
+ * published item's package, every url fetched over the network exactly as the engine will).
+ */
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const audioDefects_1 = require("./audioDefects");
+const audioDistinct_1 = require("./audioDistinct");
+const audioReference_1 = require("./audioReference");
+const audioSpectral_1 = require("./audioSpectral");
+const audioProvenance_1 = require("./audioProvenance");
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** Below this peak a sample is treated as silent. −60 dBFS is ~0.1 % of full scale. */
+exports.SILENT_PEAK_DBFS = -60;
+/** Below this RMS a sample is "very quiet": audible only with gain, flagged as a warning. */
+exports.QUIET_RMS_DBFS = -50;
+const dbfs = (linear) => (linear > 0 ? 20 * Math.log10(linear) : Number.NEGATIVE_INFINITY);
+const round1 = (n) => (Number.isFinite(n) ? Math.round(n * 10) / 10 : n);
+/**
+ * Parse a RIFF/WAVE file and measure it. Throws with a plain reason on anything the engine's decoder would not take.
+ * Handles PCM 8/16/24/32-bit and IEEE float 32/64, plus WAVE_FORMAT_EXTENSIBLE carrying either.
+ */
+function measureWav(bytes) {
+    const buf = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (buf.length < 12 || buf.toString('ascii', 0, 4) !== 'RIFF' || buf.toString('ascii', 8, 12) !== 'WAVE') {
+        const head = buf.toString('ascii', 0, 4);
+        const hint = head.startsWith('ID3') || (buf[0] === 0xff && (buf[1] & 0xe0) === 0xe0) ? ' (this looks like an MP3)'
+            : head === 'OggS' ? ' (this is an OGG)' : head === 'fLaC' ? ' (this is a FLAC)' : '';
+        throw new Error(`not a RIFF/WAVE file${hint}`);
+    }
+    let offset = 12;
+    let fmt;
+    let data;
+    while (offset + 8 <= buf.length) {
+        const id = buf.toString('ascii', offset, offset + 4);
+        const size = buf.readUInt32LE(offset + 4);
+        const body = offset + 8;
+        if (id === 'fmt ') {
+            if (size < 16)
+                throw new Error('WAV fmt chunk is truncated');
+            let tag = buf.readUInt16LE(body);
+            if (tag === 0xfffe && size >= 40)
+                tag = buf.readUInt16LE(body + 24); // EXTENSIBLE: the real tag is in the sub-format GUID
+            fmt = {
+                tag,
+                channels: buf.readUInt16LE(body + 2),
+                rate: buf.readUInt32LE(body + 4),
+                blockAlign: buf.readUInt16LE(body + 12),
+                bits: buf.readUInt16LE(body + 14),
+            };
+        }
+        else if (id === 'data') {
+            data = buf.subarray(body, Math.min(buf.length, body + size));
+        }
+        offset = body + size + (size % 2);
+    }
+    if (!fmt)
+        throw new Error('WAV has no fmt chunk');
+    if (!data)
+        throw new Error('WAV has no data chunk');
+    if (fmt.channels < 1 || fmt.rate < 1 || fmt.blockAlign < 1)
+        throw new Error('WAV fmt chunk is malformed');
+    const format = fmt.tag === 1 ? 'pcm' : fmt.tag === 3 ? 'float' : 'other';
+    const frames = Math.floor(data.length / fmt.blockAlign);
+    const bytesPerSample = fmt.bits / 8;
+    let peak = 0;
+    let sumSquares = 0;
+    let count = 0;
+    if (format !== 'other' && Number.isInteger(bytesPerSample) && bytesPerSample >= 1) {
+        const read = (at) => {
+            if (format === 'float')
+                return bytesPerSample === 8 ? data.readDoubleLE(at) : data.readFloatLE(at);
+            switch (bytesPerSample) {
+                case 1: return (data.readUInt8(at) - 128) / 128;
+                case 2: return data.readInt16LE(at) / 32768;
+                case 3: return data.readIntLE(at, 3) / 8388608;
+                case 4: return data.readInt32LE(at) / 2147483648;
+                default: return 0;
+            }
+        };
+        const total = frames * fmt.channels;
+        // Large ladders are ~1-3 MB; a stride keeps a 100 MB file from stalling the CLI while staying statistically exact
+        // enough for a silence verdict (peak is still taken over every visited sample).
+        const stride = total > 4_000_000 ? Math.ceil(total / 4_000_000) : 1;
+        for (let i = 0; i < total; i += stride) {
+            const at = i * bytesPerSample;
+            if (at + bytesPerSample > data.length)
+                break;
+            const v = read(at);
+            const a = Math.abs(v);
+            if (a > peak)
+                peak = a;
+            sumSquares += v * v;
+            count += 1;
+        }
+    }
+    return {
+        format,
+        formatTag: fmt.tag,
+        channels: fmt.channels,
+        sampleRate: fmt.rate,
+        bitsPerSample: fmt.bits,
+        frames,
+        durationS: frames / fmt.rate,
+        peakDbfs: round1(dbfs(peak)),
+        rmsDbfs: round1(dbfs(count > 0 ? Math.sqrt(sumSquares / count) : 0)),
+    };
+}
+/** Judge one decoded sample. Returns issues; empty means it will play and is audible. */
+function judgeWav(path, label, m) {
+    const issues = [];
+    if (m.format === 'other') {
+        issues.push({ code: 'AUDIO_NOT_PCM', level: 'error', path, message: `${label} is WAV format tag ${m.formatTag}, not PCM or float`,
+            fix: 'transcode to PCM: ffmpeg -i in.wav -ac 1 -ar 48000 -c:a pcm_s16le out.wav' });
+        return issues;
+    }
+    if (m.frames === 0 || m.durationS < 0.01) {
+        issues.push({ code: 'AUDIO_EMPTY', level: 'error', path, message: `${label} has no audio frames`, fix: 'replace it with the real recording' });
+        return issues;
+    }
+    if (m.peakDbfs < exports.SILENT_PEAK_DBFS) {
+        issues.push({ code: 'AUDIO_SILENT', level: 'error', path,
+            message: `${label} is silent (peak ${m.peakDbfs} dBFS over ${m.durationS.toFixed(2)} s)`,
+            fix: 'the file decodes but carries no sound: re-export the recording (check the source track and any fade/gain stage)' });
+    }
+    else if (m.rmsDbfs < exports.QUIET_RMS_DBFS) {
+        issues.push({ code: 'AUDIO_VERY_QUIET', level: 'warn', path,
+            message: `${label} is very quiet (RMS ${m.rmsDbfs} dBFS, peak ${m.peakDbfs} dBFS)`,
+            fix: 'normalise it (ladder rungs to each other) and set the level with engineGainDb / exhaustGainDb' });
+    }
+    return issues;
+}
+/** A bank rung must be a real broadband engine sound, not a near-pure synthetic tone (round 5's biggest regression). */
+function judgeRungSpectral(path, label, bytes) {
+    let rich;
+    try {
+        const { samples, sampleRate } = (0, audioSpectral_1.decodeWavMono)(bytes);
+        rich = (0, audioSpectral_1.spectralRichness)(samples, sampleRate);
+    }
+    catch {
+        return []; // a malformed/undecodable WAV is already named by judgeWav/measureWav; nothing more to add here
+    }
+    if (!rich.isNearPureTone)
+        return [];
+    return [{
+            code: 'AUDIO_NEAR_PURE_TONE', level: 'error', path,
+            message: `${label} is a near-pure synthetic tone, not an engine recording: ${rich.why} (autocorr ${rich.autocorrMax.toFixed(4)}, flatness ${rich.flatness.toFixed(3)}, ${rich.nLines20} line(s))`,
+            fix: 'replace the rung with the recording from the most accurate sim mod of the car (`helix vehicle audio-import`), else a mod of the same engine family; vehicle audio is never synthesised',
+        }];
+}
+/**
+ * Clipping and DC offset, measured on the decoded samples of any row. Flat-topped runs (>= 3 consecutive samples) at
+ * the converter's rails, or at the file's own peak after it was clipped and turned down, are hard distortion the ear
+ * hears on a sustained engine note; the calibration set of real recordings (993, F355, platform pack, 41 field recordings) peaks at 0.04 % of samples,
+ * the F40's limited rungs sit at 0.1-0.7 %. DC offset
+ * clicks when a one-shot starts or a loop wraps; real recordings measured up to 0.0045 full scale (0.0143 on the worst of 41 field recordings).
+ */
+function judgeClipDc(path, label, bytes, use) {
+    let stats;
+    try {
+        stats = (0, audioDefects_1.clipDcStats)((0, audioSpectral_1.decodeWavMono)(bytes, true).samples);
+    }
+    catch {
+        return []; // an undecodable WAV is already named by measureWav
+    }
+    const issues = [];
+    if (stats.peak < 1e-3)
+        return issues; // silent: AUDIO_SILENT says it
+    const pct = (stats.clipFraction * 100).toFixed(2);
+    const severe = stats.clipFraction >= (use === 'bank' ? 0.005 : 0.02);
+    if (stats.clipSamples >= 12 && (severe || stats.clipFraction >= 0.001)) {
+        const where = stats.clipKind === 'full-scale' ? 'at full scale' : `at the file's own peak (${(20 * Math.log10(stats.peak)).toFixed(1)} dBFS), i.e. clipped and then turned down`;
+        issues.push({ code: 'AUDIO_CLIPPED', level: severe ? 'error' : 'warn', path,
+            message: `${label} is clipped: ${pct}% of its samples (${stats.clipSamples}, longest flat run ${stats.clipRun}) sit in flat-topped runs ${where}`,
+            fix: 'render or normalise with headroom (peak at -3 dBFS or lower, no hard limiter or tanh drive pushed past the rails) before exporting; a recording that clips at capture needs re-gaining and re-recording, turning a clipped file down does not unclip it' });
+    }
+    const adc = Math.abs(stats.dc);
+    const ratio = stats.rms > 0 ? adc / stats.rms : 0;
+    if (adc >= 0.02) {
+        const bad = adc >= 0.05 || ratio >= 0.5;
+        issues.push({ code: 'AUDIO_DC_OFFSET', level: bad ? 'error' : 'warn', path,
+            message: `${label} has a DC offset of ${stats.dc >= 0 ? '+' : ''}${stats.dc.toFixed(4)} full scale (${(ratio * 100).toFixed(0)}% of its RMS): it clicks when the sample starts or the loop wraps`,
+            fix: 'remove it before export: subtract the mean, or high-pass at 20-30 Hz (ffmpeg -i in.wav -af highpass=f=25 out.wav); a synthesis chain with an asymmetric limiter or waveshaper adds it, so remove the mean after the nonlinearity' });
+    }
+    return issues;
+}
+/** A horn recorded from a real car has jitter and a noise floor; an exactly periodic synthetic tone is a beep. */
+function judgeHornRow(path, label, bytes) {
+    try {
+        const { samples, sampleRate } = (0, audioSpectral_1.decodeWavMono)(bytes, true);
+        let peak = 0;
+        for (let i = 0; i < samples.length; i += 1)
+            peak = Math.max(peak, Math.abs(samples[i]));
+        if (peak < 1e-3)
+            return [];
+        const verdict = (0, audioDefects_1.judgeHorn)(samples, sampleRate);
+        if (!verdict.periodic)
+            return [];
+        return [{ code: 'AUDIO_HORN_SYNTHETIC', level: 'warn', path,
+                message: `${label} is a perfectly periodic synthetic tone: ${verdict.why}`,
+                fix: 'use a recording of a real horn, or add what a real horn has: slow pitch jitter (+-0.3-1 %), amplitude shimmer, a faint broadband floor and a short attack and release; a two-tone horn is fine, an exact two-sine sum is not' }];
+    }
+    catch {
+        return [];
+    }
+}
+/** Every distinct rung ladder the package's engine and exhaust blends drive. */
+function collectLadders(pkg) {
+    const audio = isRecord(pkg) && isRecord(pkg.audio) ? pkg.audio : undefined;
+    const bank = audio && isRecord(audio.bank) ? audio.bank : undefined;
+    if (!audio || !bank)
+        return [];
+    const blends = isRecord(bank.blends) ? bank.blends : {};
+    const seen = new Set();
+    const out = [];
+    for (const key of ['engineBlend', 'exhaustBlend']) {
+        const name = audio[key];
+        if (typeof name !== 'string')
+            continue;
+        const blend = blends[name];
+        if (!isRecord(blend) || !Array.isArray(blend.samples))
+            continue;
+        blend.samples.forEach((ladder, index) => {
+            if (!Array.isArray(ladder))
+                return;
+            const rungs = ladder
+                .filter((r) => Array.isArray(r) && typeof r[0] === 'string' && typeof r[1] === 'number' && r[1] > 0)
+                .map((r) => ({ name: r[0], rpm: r[1] }));
+            const id = rungs.map((r) => `${r.name}@${r.rpm}`).join('|');
+            if (rungs.length === 0 || seen.has(id))
+                return;
+            seen.add(id);
+            out.push({ path: `audio.bank.blends.${name}.samples[${index}]`, blend: name, rungs });
+        });
+    }
+    return out;
+}
+/** Ladder-level content defects: a copied rung, a fixed formant stack, a fixed tone. Needs each rung's decoded bytes. */
+function judgeLadders(pkg, bytesByName) {
+    const meta = audioPitchMeta(pkg);
+    const issues = [];
+    for (const ladder of collectLadders(pkg)) {
+        const rungs = [];
+        for (const r of ladder.rungs) {
+            const bytes = bytesByName.get(r.name);
+            if (!bytes)
+                continue;
+            try {
+                const { samples, sampleRate } = (0, audioSpectral_1.decodeWavMono)(bytes, true);
+                rungs.push({ rpm: r.rpm, f0: (0, audioSpectral_1.firingFundamental)(r.rpm, meta.cylinderCount, meta.strokes, meta.crankLayout), samples, sampleRate });
+            }
+            catch {
+                // named by judgeWav
+            }
+        }
+        if (rungs.length < 3)
+            continue;
+        const where = `ladder ${ladder.blend} (${ladder.path})`;
+        const formants = (0, audioDefects_1.ladderFormantConstancy)(rungs);
+        if (formants && formants.meanFarCorrelation >= 0.3) {
+            const err = formants.meanFarCorrelation >= 0.5;
+            issues.push({ code: 'AUDIO_LADDER_FIXED_FORMANTS', level: err ? 'error' : 'warn', path: ladder.path,
+                message: `${where}: every rung carries the same spectral peaks and notches at the same absolute frequencies regardless of rpm (harmonic-envelope correlation ${formants.meanFarCorrelation.toFixed(2)} across ${formants.pairs} rung pairs; real recordings measure <= 0.1): a fixed resonator stack, which reads as a synthetic voice`,
+                fix: 'a fixed resonator stack is a synthesis artefact: take the ladder from a sim mod\'s own recordings (`helix vehicle audio-import`), where the dominant bands move with rpm and load as a real engine\'s do' });
+        }
+        const tone = (0, audioDefects_1.ladderFixedTone)(rungs);
+        if (tone && tone.rungs >= 5 && tone.rungs >= 0.55 * tone.total) {
+            const err = tone.rungs >= 6 && tone.rungs >= 0.75 * tone.total;
+            issues.push({ code: 'AUDIO_LADDER_FIXED_TONE', level: err ? 'error' : 'warn', path: ladder.path,
+                message: `${where}: a narrowband line at ~${Math.round(tone.hz)} Hz sits at the same frequency in ${tone.rungs} of ${tone.total} rungs while the firing fundamental moves (real recordings reach at most 6 of 15): a fixed oscillator or resonator ring mixed into every rung`,
+                fix: 'take the ladder from a sim mod\'s recordings (`helix vehicle audio-import`); a fixed tone in every rung is a synthesis artefact, and engine tones must track rpm' });
+        }
+        const bankAssets = (() => {
+            const audio = isRecord(pkg) && isRecord(pkg.audio) ? pkg.audio : {};
+            return isRecord(audio.bank) && Array.isArray(audio.bank.assets) ? audio.bank.assets.filter(isRecord) : [];
+        })();
+        const takeAt = new Map(ladder.rungs.map((r) => [r.rpm, sourceRepitchTake(bankAssets.find((a) => a.name === r.name))]));
+        for (const copy of (0, audioDefects_1.ladderResampledCopies)(rungs)) {
+            if (copy.score < 0.65)
+                continue;
+            const take = takeAt.get(copy.lowRpm);
+            if (take && take === takeAt.get(copy.highRpm))
+                continue; // the source plays this one take at both rpms
+            const err = copy.score >= 0.8;
+            issues.push({ code: 'AUDIO_LADDER_RUNG_COPY', level: err ? 'error' : 'warn', path: ladder.path,
+                message: `${where}: the ${copy.highRpm} rpm rung is a resampled copy of the ${copy.lowRpm} rpm rung (aperiodic residual correlation ${copy.score.toFixed(2)} at playback ratio ${copy.ratio.toFixed(3)}; independent rungs measure <= 0.5): one recording stretched to two pitches`,
+                fix: 'do not resample one rung into its neighbours: use a sim mod\'s independently recorded rungs (`helix vehicle audio-import`); the runtime already pitch-shifts between rungs' });
+        }
+    }
+    return issues;
+}
+/** The rev limiter slot is re-fired every 60 ms by the runtime, so it has to be a short crack: a long clip stacks into a held tone. */
+function judgeRevLimiterRow(path, label, bytes) {
+    try {
+        const { samples, sampleRate } = (0, audioSpectral_1.decodeWavMono)(bytes, true);
+        let peak = 0;
+        for (let i = 0; i < samples.length; i += 1)
+            peak = Math.max(peak, Math.abs(samples[i]));
+        if (peak < 1e-3)
+            return [];
+        const v = (0, audioDefects_1.judgeRevLimiter)(samples, sampleRate);
+        if (v.level === 'ok')
+            return [];
+        const cut = v.cutHz > 0 && v.cutDepthDb >= 6 ? ` (it carries its own ${v.cutHz.toFixed(1)} Hz cut ${v.cutDepthDb.toFixed(0)} dB deep, which the overlap smears away)` : '';
+        return [{ code: 'AUDIO_REV_LIMITER_HELD', level: v.level, path,
+                message: `${label} is ${v.durationS.toFixed(2)} s long, but the runtime fires the rev-limiter slot every ${(audioDefects_1.REV_LIMITER_INTERVAL_S * 1000).toFixed(0)} ms while the car sits on its limiter, so about ${v.stackedVoices.toFixed(0)} copies play at once: that is a held tone, not a fuel-cut stutter${cut}`,
+                fix: 'use a real recording of this car (or a BeamNG mod of it) cut down to one fuel-cut crack of 0.05-0.2 s with its natural decay: the stutter is the 60 ms retrigger, so a long recording of the car held on its limiter is not the sample' }];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The identity of the sourced recording a row cites: two roles citing the same take of the same source file are the
+ * sim's own choice to play one recording for both (BeamNG drives tyre squeal and scrub from one skid loop; the idle
+ * slot names the ladder's own idle rung), not lazy reuse. Undefined for an unsourced row.
+ */
+/**
+ * A rung the SOURCE itself re-pitched (Assetto Corsa auto-pitch, an FMOD event's RPM pitch automation): the take it
+ * plays, without the rate. Rungs sharing it are the sim playing one recording at several rpms — what the source does,
+ * not a resampled copy passed off as independent recordings. Undefined for any other row.
+ */
+function sourceRepitchTake(row) {
+    const p = row && isRecord(row.provenance) ? row.provenance : undefined;
+    if (!p || !['sim-mod', 'sim-official'].includes(String(p.kind)) || typeof p.sourceSha256 !== 'string')
+        return undefined;
+    const transforms = Array.isArray(p.transforms) ? p.transforms : [];
+    if (!transforms.some((t) => isRecord(t) && /^fmod-(autopitch|pitch-automation)-varispeed$/.test(String(t.kind))))
+        return undefined;
+    return JSON.stringify([p.sourceSha256, p.sourceFile ?? null, p.sample ?? null, p.subsong ?? null]);
+}
+function sourcedRecordingKey(row) {
+    const p = isRecord(row.provenance) ? row.provenance : undefined;
+    if (!p || !['sim-mod', 'sim-official', 'recording'].includes(String(p.kind)))
+        return undefined;
+    if (typeof p.sourceSha256 !== 'string' || !p.sourceSha256)
+        return undefined;
+    return JSON.stringify([p.sourceSha256, p.sourceFile ?? null, p.sample ?? null, p.subsong ?? null, p.transforms ?? null]);
+}
+/**
+ * Near-duplicate SLOTS across roles: one take, one random seed or one resampled recording used under two names that are
+ * meant to sound different (shift up vs shift down, horn vs an engine rung, an engine rung vs an exhaust rung, a door
+ * open vs close). Same-ladder clusters are an error once they take half the ladder (or three rungs), a warning below.
+ */
+function judgeNearDuplicates(clips) {
+    const distinct = [];
+    const byId = new Map();
+    for (const c of clips) {
+        try {
+            const { samples, sampleRate } = (0, audioSpectral_1.decodeWavMono)(c.bytes, true);
+            let peak = 0;
+            for (let i = 0; i < samples.length; i += 1)
+                peak = Math.max(peak, Math.abs(samples[i]));
+            if (peak < 1e-3)
+                continue;
+            const id = `${c.use === 'bank' ? `rung ${c.name}@${c.rpm} rpm` : `slot ${c.role} "${c.name}"`} [${c.role}]`;
+            byId.set(id, c);
+            distinct.push({ id, samples, sampleRate, role: c.role, rpm: c.rpm });
+        }
+        catch {
+            // named by measureWav
+        }
+    }
+    if (distinct.length < 2)
+        return [];
+    const { clusters } = (0, audioDistinct_1.findNearDuplicates)(distinct);
+    const issues = [];
+    const ladderSize = new Map();
+    for (const d of distinct)
+        if (d.rpm !== undefined)
+            ladderSize.set(d.role, (ladderSize.get(d.role) ?? 0) + 1);
+    for (const cl of clusters) {
+        const refs = cl.ids.map((id) => byId.get(id));
+        const names = refs.map((r) => (r.use === 'bank' ? `${r.name} (${r.rpm} rpm)` : `slot ${r.role}`));
+        const roles = [...new Set(refs.map((r) => (r.use === 'bank' ? `ladder ${r.role}` : `slot ${r.role}`)))];
+        const top = cl.pairs.reduce((m, p) => (p.envNcc > m.envNcc ? p : m), cl.pairs[0] ?? { envNcc: 0, ratio: 1, lineNcc: 0 });
+        const best = top.envNcc;
+        const keys = new Set(refs.map((r) => r.source));
+        if ((cl.crossRole || cl.exact) && keys.size === 1 && refs[0].source)
+            continue; // one sourced take, by the sim's own choice
+        const takes = new Set(refs.map((r) => r.take));
+        if (!cl.crossRole && takes.size === 1 && refs[0].take)
+            continue; // one take the source itself plays at several rpms
+        const evidence = cl.exact
+            ? 'the samples are identical'
+            : `band-envelope correlation ${best.toFixed(2)} after undoing a ${top.ratio.toFixed(3)} playback ratio (line-pattern correlation ${top.lineNcc.toFixed(2)}); independent recordings measure <= 0.66, a resampled copy 0.93-1.0`;
+        const first = refs[0];
+        const proof = cl.confirmed ? '' : ' (the match is below copy strength and the line pattern does not corroborate it, so this is a suspicion: check by ear and by spectrogram)';
+        if (cl.crossRole || cl.exact) {
+            issues.push({ code: cl.confirmed ? 'AUDIO_NEAR_DUPLICATE_SOUNDS' : 'AUDIO_POSSIBLE_DUPLICATE_SOUNDS', level: cl.confirmed ? 'error' : 'warn', path: first.path,
+                message: `${names.join(', ')} are one recording under different roles (${roles.join('; ')}): ${evidence}${proof}`,
+                fix: 'use a distinct real recording for each role (a BeamNG mod of the car usually ships separate ones); a shift-down is not the shift-up retimed, a horn is not an engine rung, an exhaust rung is not an engine rung resampled' });
+            continue;
+        }
+        const total = ladderSize.get(first.role) ?? cl.ids.length;
+        const heavy = cl.confirmed && (cl.ids.length >= 3 || cl.ids.length >= total / 2);
+        issues.push({ code: 'AUDIO_NEAR_DUPLICATE_RUNGS', level: heavy ? 'error' : 'warn', path: first.path,
+            message: `${cl.ids.length} rungs of ladder ${first.role} (${names.join(', ')}) are one recording resampled to different pitches: ${evidence}${proof}`,
+            fix: 'use a distinct real recording for every rung (own take, own cycle-to-cycle variation); the runtime already pitch-shifts between rungs' });
+    }
+    return issues;
+}
+/** Every (ladder, rung) pair that has decoded bytes, as clips with the ladder as their role. */
+function rungClips(pkg, rungBytes) {
+    const out = [];
+    const audio = isRecord(pkg) && isRecord(pkg.audio) ? pkg.audio : {};
+    const bankAssets = isRecord(audio.bank) && Array.isArray(audio.bank.assets) ? audio.bank.assets.filter(isRecord) : [];
+    for (const ladder of collectLadders(pkg)) {
+        for (const r of ladder.rungs) {
+            const bytes = rungBytes.get(r.name);
+            const asset = bankAssets.find((a) => a.name === r.name);
+            if (bytes)
+                out.push({ use: 'bank', path: ladder.path, role: ladder.path, name: r.name, rpm: r.rpm, label: `${r.name} (${r.rpm} rpm)`, bytes, source: asset ? sourcedRecordingKey(asset) : undefined, take: sourceRepitchTake(asset) });
+        }
+    }
+    return out;
+}
+/** Compare the candidate's idle voice (and any named slot) with real-car reference clips. */
+function judgeAgainstReference(pkg, clips, reference) {
+    const issues = [];
+    const rows = [];
+    const bySlot = (slot) => clips.find((c) => c.use === 'slot' && c.role === slot);
+    const lowestRung = () => {
+        const ladders = collectLadders(pkg);
+        for (const ladder of ladders) {
+            const rung = [...ladder.rungs].sort((a, b) => a.rpm - b.rpm)[0];
+            const hit = rung && clips.find((c) => c.use === 'bank' && c.name === rung.name);
+            if (hit)
+                return hit;
+        }
+        return undefined;
+    };
+    for (const [slot, refs] of reference.bySlot) {
+        const target = slot === 'idle' ? (bySlot('idle') ?? lowestRung()) : bySlot(slot);
+        if (!target) {
+            issues.push({ code: 'AUDIO_REFERENCE_SLOT_MISSING', level: 'warn', path: `audio.slots[${slot}]`,
+                message: `a reference clip was supplied for "${slot}" but the package ships no ${slot === 'idle' ? 'idle sample or engine-ladder rung' : `consumed ${slot} sample`} to compare it with`,
+                fix: slot === 'idle' ? 'ship the engine ladder, or drop the reference' : `ship a ${slot} sample, or drop the reference` });
+            continue;
+        }
+        let cand;
+        try {
+            const d = (0, audioSpectral_1.decodeWavMono)(target.bytes, true);
+            cand = (0, audioReference_1.timbreMetrics)(d.samples, d.sampleRate);
+        }
+        catch {
+            continue;
+        }
+        const refMetrics = refs.map((r) => (0, audioReference_1.timbreMetrics)(r.samples, r.sampleRate));
+        const comparisons = (0, audioReference_1.compareToReference)(cand, refMetrics);
+        rows.push({ slot, candidate: target.label, references: refs.map((r) => r.source), comparisons });
+        const spread = refMetrics.length > 1 ? ` (${refMetrics.length} reference clips, median)` : '';
+        for (const c of comparisons) {
+            if (c.level === 'ok')
+                continue;
+            const unit = c.metric === 'roughness' ? '' : ' Hz';
+            const dir = c.ratio > 1 ? 'higher' : 'lower';
+            issues.push({ code: 'AUDIO_REFERENCE_TIMBRE', level: c.level, path: target.path,
+                message: `${slot === 'idle' ? 'idle voice' : `slot ${slot}`} (${target.label}): ${c.label} ${c.candidate.toFixed(c.metric === 'roughness' ? 2 : 0)}${unit} against ${c.reference.toFixed(c.metric === 'roughness' ? 2 : 0)}${unit} in the reference${spread}: x${c.ratio.toFixed(2)}, ${dir} than the real sound by more than a recording alone explains`,
+                fix: c.ratio > 1
+                    ? 'the sample is far brighter or rougher than the real car: source this sound from a real recording of the car (or a BeamNG mod of it) made close to the engine, not a different engine or a recording with heavy added noise'
+                    : 'the sample is far duller or smoother than the real car: source this sound from a real recording of the car (or a BeamNG mod of it) with the mechanical and exhaust content intact, not a different engine, a low-passed recording or a heavily processed one' });
+        }
+    }
+    return { issues, rows };
+}
+/**
+ * Comb ratio (the better of the firing series and its half-order series) at or above which a rung is pitched at its
+ * label. Measured on real sim-mod/official F40 ladders (Kunos AC, euan / Gabry BeamNG mods; 130 rungs): 0 below 1.5,
+ * 11 between 1.5 and 3, the rest above.
+ */
+exports.FIRING_COMB_PASS = 3;
+/**
+ * Below this the rung is off its label: two-octaves-down copies of those ladders measured below it on 128 of 130 rungs,
+ * one-octave-down copies on 74; a synthesised rung at the crank order (round 7's fault) measures about 0.6.
+ */
+exports.FIRING_COMB_OCTAVE_OFF = 1.5;
+function audioPitchMeta(pkg) {
+    const audio = isRecord(pkg) && isRecord(pkg.audio) ? pkg.audio : {};
+    const cylinderCount = typeof audio.sampleCylinderCount === 'number' && Number.isFinite(audio.sampleCylinderCount) && audio.sampleCylinderCount > 0 ? audio.sampleCylinderCount : 4;
+    const strokes = typeof audio.strokes === 'number' && audio.strokes > 0 ? audio.strokes : 4;
+    const crankLayout = typeof audio.crankLayout === 'string' ? audio.crankLayout : undefined;
+    return { cylinderCount, strokes, crankLayout, electric: (0, audioProvenance_1.isElectricCar)(pkg) };
+}
+/**
+ * A ladder rung's pitch must match its rpm label against the firing fundamental for the declared cylinder count,
+ * strokes and crank layout. Rejects a rung an octave or more off (round 7 synthesised a flat-plane V8 at the crank
+ * order — two octaves low); a rung that merely shows no clear comb is a warning, not a fail (its pitch is unverifiable).
+ */
+function judgeRungPitch(path, label, bytes, rpm, meta) {
+    if (meta.electric)
+        return []; // a motor whine has no firing series to judge a label against
+    const expected = (0, audioSpectral_1.firingFundamental)(rpm, meta.cylinderCount, meta.strokes, meta.crankLayout);
+    const layout = meta.crankLayout ?? 'flat-plane';
+    let est = null;
+    let comb = null;
+    try {
+        const { samples, sampleRate } = (0, audioSpectral_1.decodeWavMono)(bytes);
+        // A silent rung has no pitch to judge; judgeWav's AUDIO_SILENT already names it, so say nothing here.
+        let peak = 0;
+        for (let i = 0; i < samples.length; i += 1)
+            peak = Math.max(peak, Math.abs(samples[i]));
+        if (peak < 1e-3)
+            return [];
+        // The firing-comb cross-check decides first: a rung whose energy sits on the labelled firing comb is pitched at its
+        // label, whatever sub-harmonic a periodicity tracker locks onto (it did on every real F40 sim-mod ladder).
+        // Real flat-plane V8 and flat-six recordings carry the half-order series (each bank's collector) as strongly as
+        // the firing series, so the rung may sit on either comb: take the better of the two.
+        const onFiring = (0, audioSpectral_1.firingCombRatio)(samples, sampleRate, expected);
+        const onHalf = (0, audioSpectral_1.firingCombRatio)(samples, sampleRate, expected / 2);
+        comb = onFiring === null && onHalf === null ? null : Math.max(onFiring ?? 0, onHalf ?? 0);
+        if (comb !== null && comb >= exports.FIRING_COMB_PASS)
+            return [];
+        est = (0, audioSpectral_1.estimateFundamental)(samples, sampleRate, { fHi: Math.max(60, Math.min(1500, expected * 1.4)) });
+    }
+    catch {
+        return []; // a malformed/undecodable WAV is already named by judgeWav/measureWav
+    }
+    const combNote = comb === null ? '' : `; comb ratio ${comb.toFixed(2)} (energy on the firing series k×${expected.toFixed(0)} Hz, or its half-order series k×${(expected / 2).toFixed(0)} Hz, over the comb between them; a rung at its label measures >= ${exports.FIRING_COMB_PASS})`;
+    if (comb !== null && comb < exports.FIRING_COMB_OCTAVE_OFF) {
+        // As much energy between the comb's teeth as on them: the rung sits an octave (or more) below its label.
+        return [{ code: 'AUDIO_RUNG_PITCH_OCTAVE_OFF', level: 'error', path,
+                message: `${label} (${rpm} rpm): its energy sits between the teeth of the ${expected.toFixed(1)} Hz ${layout} firing comb and of its half-order comb${combNote}${est ? `; measured fundamental ${est.f0.toFixed(1)} Hz` : ''} — an octave or more off its label, or mislabelled`,
+                fix: `relabel the rung to the rpm its pitch really is, or correct sampleCylinderCount/strokes/crankLayout (expected ${expected.toFixed(0)} Hz: the ${meta.cylinderCount}-cyl/${meta.strokes}-stroke ${layout} firing fundamental for ${rpm} rpm)` }];
+    }
+    if (comb !== null) {
+        // Between the thresholds: the comb neither confirms nor refutes the label. Say so, never fail on the tracker alone.
+        return [{ code: 'AUDIO_RUNG_PITCH_OFF', level: 'warn', path,
+                message: `${label} (${rpm} rpm): ambiguous against the ${expected.toFixed(1)} Hz ${layout} firing fundamental${combNote}${est ? `; the periodicity tracker reads ${est.f0.toFixed(1)} Hz` : ''}`,
+                fix: `check the rung by ear and spectrogram against its ${rpm} rpm label (expected ${expected.toFixed(0)} Hz), and sampleCylinderCount/strokes/crankLayout` }];
+    }
+    if (est === null) {
+        return [{ code: 'AUDIO_RUNG_PITCH_UNVERIFIABLE', level: 'warn', path,
+                message: `${label} (${rpm} rpm): no clear harmonic comb, so its pitch cannot be verified against the ${expected.toFixed(0)} Hz ${layout} firing fundamental`,
+                fix: 're-export the rung as a clean steady-state loop so the comb estimator can lock a fundamental' }];
+    }
+    const ratio = est.f0 / expected;
+    const octaves = Math.log2(ratio);
+    const cents = Math.round(1200 * octaves);
+    if (Math.abs(octaves) >= 1) {
+        return [{ code: 'AUDIO_RUNG_PITCH_OCTAVE_OFF', level: 'error', path,
+                message: `${label} (${rpm} rpm): measured fundamental ${est.f0.toFixed(1)} Hz is ${cents >= 0 ? '+' : ''}${cents} cents (${ratio.toFixed(2)}x) from the ${expected.toFixed(1)} Hz ${layout} firing fundamental — ${octaves >= 0 ? 'an octave or more high' : 'an octave or more low'}`,
+                fix: `relabel the rung to the rpm its pitch really is, or correct sampleCylinderCount/strokes/crankLayout (expected ${expected.toFixed(0)} Hz: the ${meta.cylinderCount}-cyl/${meta.strokes}-stroke ${layout} firing fundamental for ${rpm} rpm)` }];
+    }
+    if (Math.abs(octaves) > 0.25) {
+        return [{ code: 'AUDIO_RUNG_PITCH_OFF', level: 'warn', path,
+                message: `${label} (${rpm} rpm): measured fundamental ${est.f0.toFixed(1)} Hz is ${cents >= 0 ? '+' : ''}${cents} cents (${ratio.toFixed(2)}x) from the ${expected.toFixed(1)} Hz ${layout} firing fundamental`,
+                fix: `relabel the rung to the rpm its pitch really is (expected ${expected.toFixed(0)} Hz), or correct sampleCylinderCount/strokes/crankLayout` }];
+    }
+    return [];
+}
+/**
+ * Every audio row the runtime would try to load, selected exactly as PortableVehicleAudioAdapter selects them.
+ * `includeUnconsumed` also returns the assets of `consumed: false` slots: they are part of the Package's runtime
+ * closure (the engine validator requires their url/checksum/bytes), so upload, provisioning and sealing need them even
+ * though the runtime does not play them today.
+ */
+function collectAudioRows(pkg, opts = {}) {
+    const rows = [];
+    const issues = [];
+    const audio = isRecord(pkg) && isRecord(pkg.audio) ? pkg.audio : undefined;
+    if (!audio)
+        return { rows, issues };
+    const bank = isRecord(audio.bank) ? audio.bank : undefined;
+    if (bank) {
+        const assets = Array.isArray(bank.assets) ? bank.assets : [];
+        const byName = new Map();
+        assets.forEach((row, index) => {
+            if (isRecord(row) && typeof row.name === 'string')
+                byName.set(row.name, { row, index });
+        });
+        const blends = isRecord(bank.blends) ? bank.blends : {};
+        const rungRpm = new Map();
+        for (const key of ['engineBlend', 'exhaustBlend']) {
+            const name = audio[key];
+            if (typeof name !== 'string')
+                continue;
+            const blend = blends[name];
+            if (!isRecord(blend) || !Array.isArray(blend.samples)) {
+                issues.push({ code: 'AUDIO_BLEND_MISSING', level: 'error', path: `audio.${key}`,
+                    message: `${key} names blend "${name}", which audio.bank.blends does not define`,
+                    fix: `add audio.bank.blends.${name} or point ${key} at an existing blend` });
+                continue;
+            }
+            for (const ladder of blend.samples) {
+                if (!Array.isArray(ladder))
+                    continue;
+                for (const rung of ladder) {
+                    if (!Array.isArray(rung) || typeof rung[0] !== 'string')
+                        continue;
+                    if (typeof rung[1] === 'number' && Number.isFinite(rung[1]) && rung[1] > 0)
+                        rungRpm.set(rung[0], rung[1]);
+                }
+            }
+        }
+        for (const name of rungRpm.keys()) {
+            const hit = byName.get(name);
+            if (!hit) {
+                issues.push({ code: 'AUDIO_BANK_SAMPLE_MISSING', level: 'error', path: 'audio.bank.assets',
+                    message: `blend rung "${name}" has no audio.bank.assets row with that name, so the ladder has a hole`,
+                    fix: `add a bank.assets row { name: "${name}", file, ... } or remove the rung` });
+                continue;
+            }
+            rows.push({ path: `audio.bank.assets[${hit.index}]`, use: 'bank', rpm: rungRpm.get(name), row: hit.row });
+        }
+    }
+    const slots = Array.isArray(audio.slots) ? audio.slots : [];
+    for (const slot of slots) {
+        if (!isRecord(slot) || typeof slot.slot !== 'string')
+            continue;
+        if (slot.consumed === false && !opts.includeUnconsumed)
+            continue;
+        const slotName = slot.slot;
+        const buffers = new Set(Array.isArray(slot.buffers) ? slot.buffers.filter((b) => typeof b === 'string') : []);
+        const assets = Array.isArray(slot.assets) ? slot.assets : [];
+        assets.forEach((row, index) => {
+            if (!isRecord(row))
+                return;
+            const path = `audio.slots[${slotName}].assets[${index}]`;
+            if (typeof row.name !== 'string' || !buffers.has(row.name)) {
+                issues.push({ code: 'AUDIO_SLOT_ASSET_UNREFERENCED', level: 'error', path,
+                    message: `slot ${slotName} ships asset "${String(row.name)}" but its buffers ${JSON.stringify([...buffers])} never name it, so the runtime never loads it`,
+                    fix: `put "${String(row.name)}" in audio.slots[${slotName}].buffers (or rename the asset to the buffer it plays)` });
+                return;
+            }
+            rows.push({ path, use: 'slot', slot: slotName, row });
+        });
+    }
+    // Engine and exhaust are two voices: the engine note behind the block and the exhaust note behind the car differ.
+    // A single shared blend (round 5 shipped engineBlend == exhaustBlend) reads as one thin voice, not a twin-turbo V8.
+    const engineBlend = typeof audio.engineBlend === 'string' ? audio.engineBlend : '';
+    const exhaustBlend = typeof audio.exhaustBlend === 'string' ? audio.exhaustBlend : '';
+    if (engineBlend && exhaustBlend) {
+        const blend = (name) => {
+            const blends = bank && isRecord(bank.blends) ? bank.blends : {};
+            const b = isRecord(blends[name]) ? blends[name] : undefined;
+            const files = new Set();
+            if (b && Array.isArray(b.samples)) {
+                for (const ladder of b.samples)
+                    if (Array.isArray(ladder))
+                        for (const rung of ladder)
+                            if (Array.isArray(rung) && typeof rung[0] === 'string')
+                                files.add(rung[0]);
+            }
+            return files;
+        };
+        const engineFiles = blend(engineBlend);
+        const exhaustFiles = blend(exhaustBlend);
+        const same = engineBlend === exhaustBlend
+            || (engineFiles.size > 0 && engineFiles.size === exhaustFiles.size && [...engineFiles].every((f) => exhaustFiles.has(f)));
+        if (same && (0, audioProvenance_1.blendIsSourced)(pkg, engineBlend) && (0, audioProvenance_1.blendIsSourced)(pkg, exhaustBlend)) {
+            // A sim mod that records engine and exhaust as ONE combined set (the mmbng 993: exhaust sampleName "0") is a
+            // real recording, not synthesis; doubling it adds nothing, so say how to drop the duplicate layer.
+            issues.push({ code: 'AUDIO_ENGINE_EXHAUST_SHARED_RECORDING', level: 'warn', path: 'audio.exhaustBlend',
+                message: `engineBlend "${engineBlend}" and exhaustBlend "${exhaustBlend}" play the same sourced recording on both layers (the source ships one combined engine+exhaust set)`,
+                fix: 'omit exhaustBlend and give the exhaustLadder slot a reason ("the source records engine and exhaust as one combined set; it plays on the engine layer") — `helix vehicle audio-import` writes it that way' });
+        }
+        else if (engineBlend === exhaustBlend) {
+            issues.push({ code: 'AUDIO_ENGINE_EXHAUST_SAME_BLEND', level: 'error', path: 'audio.exhaustBlend',
+                message: `engineBlend and exhaustBlend both name "${engineBlend}": one recording drives both layers`,
+                fix: 'take a distinct exhaust ladder from the sim mod if it has one; if the mod records one combined set, omit exhaustBlend and say so in the exhaustLadder slot reason' });
+        }
+        else if (same) {
+            issues.push({ code: 'AUDIO_ENGINE_EXHAUST_SAME_BLEND', level: 'error', path: 'audio.exhaustBlend',
+                message: `engineBlend "${engineBlend}" and exhaustBlend "${exhaustBlend}" resolve to the same rung set: one recording drives both layers`,
+                fix: 'take distinct engine and exhaust ladders from the sim mod, or omit exhaustBlend when the source records one combined set' });
+        }
+    }
+    return { rows, issues };
+}
+/** The adapter's own shape test (`normalizedAsset`): fields a row must carry for the runtime to even request it. */
+function runtimeRowIssues(r) {
+    const row = r.row;
+    const label = `${r.use === 'bank' ? 'bank sample' : `slot ${r.slot}`} "${String(row.name)}"`;
+    const missing = [];
+    if (typeof row.url !== 'string' || row.url.length === 0)
+        missing.push('url');
+    if (typeof row.checksumSha256 !== 'string' || !/^[a-f0-9]{64}$/i.test(row.checksumSha256))
+        missing.push('checksumSha256');
+    if (!Number.isSafeInteger(row.bytes) || Number(row.bytes) <= 0)
+        missing.push('bytes');
+    if (row.mediaType !== 'audio/wav')
+        missing.push('mediaType "audio/wav"');
+    if (missing.length === 0)
+        return [];
+    return [{ code: 'AUDIO_ROW_NOT_LOADABLE', level: 'error', path: r.path,
+            message: `${label} lacks ${missing.join(', ')}; the engine skips it without an error (silent ${r.use === 'bank' ? 'engine' : 'slot'})`,
+            fix: missing.includes('url')
+                ? 'upload each WAV as a verified Continuum object and record its public url, checksum and bytes before Package seal'
+                : 'fill the field from the exact WAV bytes the url serves' }];
+}
+/**
+ * Bare lowercase sha256 of a Continuum object id: `cid:sha256:<hex>` → `<hex>`, or a bare 64-hex sha unchanged.
+ * Undefined for anything that is neither (a malformed or absent cid/checksum), so the membership check can skip it.
+ */
+function sha256OfCid(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const hex = value.startsWith('cid:sha256:') ? value.slice('cid:sha256:'.length) : value;
+    return /^[a-f0-9]{64}$/i.test(hex) ? hex.toLowerCase() : undefined;
+}
+/**
+ * The sha256s a Package Version SEALS, normalized to bare hex. The closure is the manifest's `root` and every
+ * `variants[].object` — the same set the publisher enforces and the runtime resolves audio from. Accepts a Package
+ * Version manifest, a publication intent (`{ packageVersion, objects }`), or a publication receipt
+ * (`{ objectCids }`), so the check works both before sealing (what we are about to seal) and after (what was sealed).
+ */
+function sealedClosureSha256s(source) {
+    const shas = new Set();
+    const add = (value) => {
+        const sha = sha256OfCid(value);
+        if (sha)
+            shas.add(sha);
+    };
+    if (!isRecord(source))
+        return shas;
+    const version = isRecord(source.packageVersion) ? source.packageVersion : source;
+    if (isRecord(version.root))
+        add(version.root.cid);
+    for (const variant of Array.isArray(version.variants) ? version.variants : []) {
+        if (isRecord(variant) && isRecord(variant.object))
+            add(variant.object.cid);
+    }
+    for (const object of Array.isArray(source.objects) ? source.objects : []) {
+        if (isRecord(object) && isRecord(object.reference))
+            add(object.reference.cid);
+    }
+    for (const cid of Array.isArray(source.objectCids) ? source.objectCids : [])
+        add(cid);
+    return shas;
+}
+/**
+ * Membership: every loadable row's object must be sealed into the Package closure. The runtime resolves a vehicle's
+ * audio from the closure, not from an arbitrary public URL — a row whose cid (or the sha256 of its bytes) is not in
+ * the closure plays nothing and 404s, exactly as a missing url does, and it does so WITHOUT any error at the URL
+ * itself (the object is public; it is simply not one the Package owns). A missing reference is a hard error.
+ */
+/**
+ * The assets of `consumed: false` slots that still ship a recording (idle, intake, transmissionWhine, tyreSqueal on an
+ * audio-import package). The runtime does not play them today, but they are in the Package's closure and the engine's
+ * package validator requires each one to be a complete, loadable row — a broken one stops the car being presented.
+ * So the checks verify they load (file or url, digest, size, a decodable WAV) without judging them as played sounds.
+ */
+function unconsumedAudioRows(pkg) {
+    const played = new Set(collectAudioRows(pkg).rows.map((r) => r.path));
+    return collectAudioRows(pkg, { includeUnconsumed: true }).rows.filter((r) => !played.has(r.path));
+}
+function closureMembershipIssues(rows, closure) {
+    const issues = [];
+    for (const r of rows) {
+        const declared = typeof r.row.cid === 'string' && r.row.cid ? r.row.cid : r.row.checksumSha256;
+        const sha = sha256OfCid(declared);
+        if (!sha)
+            continue; // no cid and no usable sha256: AUDIO_ROW_NOT_LOADABLE / AUDIO_SOURCE_MISSING already names it
+        if (closure.has(sha))
+            continue;
+        const label = `${r.use === 'bank' ? 'bank sample' : `slot ${r.slot}`} "${String(r.row.name)}"`;
+        issues.push({ code: 'AUDIO_NOT_IN_CLOSURE', level: 'error', path: r.path,
+            message: `${label} references ${declared} (sha256 ${sha.slice(0, 12)}…), which is NOT a member of the sealed Package closure; the runtime loads a vehicle's audio from the closure and 404s this file`,
+            fix: 'seal this WAV into the package before publishing; a slot referencing an unsealed cid 404s at runtime (put the WAV beside the package so `vehicle publish` uploads and seals it, then re-publish — or add it to the Package closure)' });
+    }
+    return issues;
+}
+const sha256 = (bytes) => (0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex');
+/** Where a row's local file is: `file`, then `path`, then `name`, each beside the package and under `audio/`. */
+function localFileFor(row, dir) {
+    const names = [row.file, row.path, row.name].filter((v) => typeof v === 'string' && v.length > 0);
+    for (const name of names) {
+        for (const candidate of [(0, node_path_1.resolve)(dir, name), (0, node_path_1.join)(dir, 'audio', (0, node_path_1.basename)(name)), (0, node_path_1.join)(dir, (0, node_path_1.basename)(name))]) {
+            if (candidate.startsWith((0, node_path_1.resolve)(dir)) && (0, node_fs_1.existsSync)(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+/** Placeholder origin for local preflight; replace it with a verified public object URL before sealing. */
+exports.PENDING_AUDIO_ORIGIN = 'https://pending-upload.invalid';
+/**
+ * Fill each loadable row that has a LOCAL file but no url with the file's checksum/bytes/cid/mediaType and a
+ * placeholder url, so the engine's own package validator (which requires a complete runtime closure) can judge the
+ * rest of the package before anything is uploaded. Returns the copy and how many rows were filled.
+ */
+function provisionalAudio(pkg, dir) {
+    if (!isRecord(pkg))
+        return { pkg, filled: 0 };
+    const out = JSON.parse(JSON.stringify(pkg));
+    const { rows } = collectAudioRows(out, { includeUnconsumed: true });
+    let filled = 0;
+    for (const r of rows) {
+        if (typeof r.row.url === 'string' && r.row.url)
+            continue;
+        const file = localFileFor(r.row, dir);
+        if (!file)
+            continue;
+        const bytes = new Uint8Array((0, node_fs_1.readFileSync)(file));
+        const sha = sha256(bytes);
+        Object.assign(r.row, { url: `${exports.PENDING_AUDIO_ORIGIN}/content/sha256/${sha.slice(0, 2)}/${sha}`, checksumSha256: sha, bytes: bytes.length, cid: `cid:sha256:${sha}`, mediaType: 'audio/wav' });
+        filled += 1;
+    }
+    return { pkg: out, filled };
+}
+const defaultFetch = async (url) => {
+    const response = await fetch(url, { redirect: 'follow', signal: AbortSignal.timeout(60_000), headers: { 'user-agent': 'helix-cli audio-check' } });
+    return { status: response.status, bytes: response.ok ? new Uint8Array(await response.arrayBuffer()) : new Uint8Array() };
+};
+exports.defaultFetch = defaultFetch;
+function finish(mode, pkg, rows, issues, reference) {
+    const audio = isRecord(pkg) && isRecord(pkg.audio) ? pkg.audio : undefined;
+    // Provenance and the no-synthesis rule: a car without a recorded engine ladder (the runtime's synthesised fallback
+    // engine) is AUDIO_ENGINE_UNSOURCED, an error; it replaces the old AUDIO_FALLBACK_ENGINE warning.
+    const provenance = (0, audioProvenance_1.provenanceReport)(pkg);
+    issues.push(...provenance.issues);
+    const fallbackEngine = provenance.engineUnsourced || (!audio || !isRecord(audio.bank)) && audio?.drivetrain !== 'electric';
+    const errors = issues.filter((i) => i.level === 'error').length;
+    return { ok: errors === 0, mode, errors, warnings: issues.length - errors, fallbackEngine, rows, issues, ...(reference ? { reference } : {}), provenance: provenance.rows };
+}
+/**
+ * PRE-SEAL: every row that will be loaded must resolve to either a local WAV beside the Package or an already-public
+ * URL; local files are decoded and measured, and URLs are fetched. Exact object pins and public URLs are required
+ * before sealing, so these fields are optional only during local preflight.
+ */
+async function checkAudioLocal(pkg, dir, fetchImpl = exports.defaultFetch, closure, options = {}) {
+    const { rows, issues } = collectAudioRows(pkg);
+    const unconsumed = unconsumedAudioRows(pkg);
+    if (closure)
+        issues.push(...closureMembershipIssues([...rows, ...unconsumed], closure));
+    const meta = audioPitchMeta(pkg);
+    const reports = [];
+    const rungBytes = new Map();
+    const slotClips = [];
+    for (const r of rows) {
+        const name = String(r.row.name);
+        const label = `${r.use === 'bank' ? 'bank sample' : `slot ${r.slot}`} "${name}"`;
+        const file = localFileFor(r.row, dir);
+        if (file) {
+            const bytes = new Uint8Array((0, node_fs_1.readFileSync)(file));
+            const report = { path: r.path, use: r.use, slot: r.slot, name, source: 'local', file, bytes: bytes.length, checksumSha256: sha256(bytes) };
+            try {
+                report.measure = measureWav(bytes);
+                issues.push(...judgeWav(r.path, label, report.measure));
+                issues.push(...judgeClipDc(r.path, label, bytes, r.use));
+                if (r.slot === 'horn')
+                    issues.push(...judgeHornRow(r.path, label, bytes));
+                if (r.slot === 'revLimiter')
+                    issues.push(...judgeRevLimiterRow(r.path, label, bytes));
+                if (r.use === 'slot' && r.slot)
+                    slotClips.push({ use: 'slot', path: r.path, role: r.slot, name, label, bytes, source: sourcedRecordingKey(r.row) });
+                if (r.use === 'bank') {
+                    rungBytes.set(name, bytes);
+                    issues.push(...judgeRungSpectral(r.path, label, bytes));
+                    if (r.rpm !== undefined)
+                        issues.push(...judgeRungPitch(r.path, label, bytes, r.rpm, meta));
+                }
+            }
+            catch (error) {
+                issues.push({ code: 'AUDIO_NOT_WAV', level: 'error', path: r.path, message: `${label} (${file}): ${error.message}`,
+                    fix: 'only PCM WAV plays: ffmpeg -i in.mp3 -ac 1 -ar 48000 -c:a pcm_s16le out.wav' });
+            }
+            reports.push(report);
+            continue;
+        }
+        if (typeof r.row.url === 'string' && r.row.url) {
+            reports.push(await checkRemoteRow(r, label, fetchImpl, issues, meta, rungBytes, slotClips));
+            continue;
+        }
+        issues.push({ code: 'AUDIO_SOURCE_MISSING', level: 'error', path: r.path,
+            message: `${label} has neither a local file beside the package (looked for file/path/name in the package dir and audio/) nor a url`,
+            fix: `put ${typeof r.row.file === 'string' ? String(r.row.file) : `${name}.wav`} in the package dir (or audio/), or give the row the public url of a platform sample` });
+    }
+    for (const r of unconsumed) {
+        const name = String(r.row.name);
+        const label = `slot ${r.slot} "${name}" (consumed: false, still in the closure)`;
+        const file = localFileFor(r.row, dir);
+        if (file) {
+            const bytes = new Uint8Array((0, node_fs_1.readFileSync)(file));
+            const report = { path: r.path, use: r.use, slot: r.slot, name, source: 'local', file, bytes: bytes.length, checksumSha256: sha256(bytes) };
+            try {
+                report.measure = measureWav(bytes);
+            }
+            catch (error) {
+                issues.push({ code: 'AUDIO_NOT_WAV', level: 'error', path: r.path, message: `${label} (${file}): ${error.message}`,
+                    fix: 'only PCM WAV loads: ffmpeg -i in.mp3 -ac 1 -ar 48000 -c:a pcm_s16le out.wav' });
+            }
+            reports.push(report);
+        }
+        else if (typeof r.row.url === 'string' && r.row.url) {
+            reports.push(await checkRemoteRow(r, label, fetchImpl, issues, meta, undefined, undefined, { loadOnly: true }));
+        }
+        else {
+            issues.push({ code: 'AUDIO_SOURCE_MISSING', level: 'error', path: r.path,
+                message: `${label} has neither a local file beside the package nor a url; the engine's package validator refuses the car`,
+                fix: `put ${typeof r.row.file === 'string' ? String(r.row.file) : `${name}.wav`} in the package dir (or audio/), or empty the slot ({ consumed: false, buffers: [], reason })` });
+        }
+    }
+    issues.push(...judgeLadders(pkg, rungBytes));
+    const clips = [...slotClips, ...rungClips(pkg, rungBytes)];
+    issues.push(...judgeNearDuplicates(clips));
+    const ref = options.reference ? judgeAgainstReference(pkg, clips, options.reference) : undefined;
+    if (ref)
+        issues.push(...ref.issues);
+    return finish('local', pkg, reports, issues, ref?.rows);
+}
+async function checkRemoteRow(r, label, fetchImpl, issues, meta, rungBytes, slotClips, opts = {}) {
+    const url = String(r.row.url);
+    const report = { path: r.path, use: r.use, slot: r.slot, name: String(r.row.name), source: 'url', url };
+    let fetched;
+    try {
+        fetched = await fetchImpl(url);
+    }
+    catch (error) {
+        issues.push({ code: 'AUDIO_URL_UNREACHABLE', level: 'error', path: r.path, message: `${label}: ${url} could not be fetched (${error.message})`,
+            fix: 'use the public content url of a sealed public object (Package publication records it)' });
+        return report;
+    }
+    report.httpStatus = fetched.status;
+    if (fetched.status !== 200) {
+        issues.push({ code: 'AUDIO_URL_NOT_FOUND', level: 'error', path: r.path, message: `${label}: ${url} returned HTTP ${fetched.status}; the engine plays nothing`,
+            fix: 'the object is not public at that address: upload and verify its exact bytes, then seal a Package Version with the valid content URL' });
+        return report;
+    }
+    report.bytes = fetched.bytes.length;
+    report.checksumSha256 = sha256(fetched.bytes);
+    if (typeof r.row.checksumSha256 === 'string' && r.row.checksumSha256.toLowerCase() !== report.checksumSha256) {
+        issues.push({ code: 'AUDIO_CHECKSUM_MISMATCH', level: 'error', path: r.path,
+            message: `${label}: ${url} serves sha256 ${report.checksumSha256}, the row declares ${r.row.checksumSha256}; the engine rejects the body`,
+            fix: 'make checksumSha256 the digest of the exact bytes at the url' });
+    }
+    if (Number.isSafeInteger(r.row.bytes) && Number(r.row.bytes) !== fetched.bytes.length) {
+        issues.push({ code: 'AUDIO_BYTES_MISMATCH', level: 'error', path: r.path,
+            message: `${label}: ${url} serves ${fetched.bytes.length} bytes, the row declares ${String(r.row.bytes)}; the engine rejects the body`,
+            fix: 'make bytes the exact length of the file at the url' });
+    }
+    try {
+        report.measure = measureWav(fetched.bytes);
+        if (opts.loadOnly)
+            return report; // loads and decodes: all an unplayed closure member owes the runtime
+        issues.push(...judgeWav(r.path, label, report.measure));
+        issues.push(...judgeClipDc(r.path, label, fetched.bytes, r.use));
+        if (r.slot === 'horn')
+            issues.push(...judgeHornRow(r.path, label, fetched.bytes));
+        if (r.slot === 'revLimiter')
+            issues.push(...judgeRevLimiterRow(r.path, label, fetched.bytes));
+        if (r.use === 'slot' && r.slot)
+            slotClips?.push({ use: 'slot', path: r.path, role: r.slot, name: String(r.row.name), label, bytes: fetched.bytes, source: sourcedRecordingKey(r.row) });
+        if (r.use === 'bank') {
+            rungBytes?.set(String(r.row.name), fetched.bytes);
+            issues.push(...judgeRungSpectral(r.path, label, fetched.bytes));
+            if (r.rpm !== undefined)
+                issues.push(...judgeRungPitch(r.path, label, fetched.bytes, r.rpm, meta));
+        }
+    }
+    catch (error) {
+        issues.push({ code: 'AUDIO_NOT_WAV', level: 'error', path: r.path, message: `${label}: ${url}: ${error.message}`,
+            fix: 'only PCM WAV plays; publish the WAV, not an MP3/OGG' });
+    }
+    return report;
+}
+/**
+ * READ-BACK: the package as the runtime receives it. Every selected row must pass the adapter's shape test AND
+ * fetch 200 with the declared size and digest AND decode to an audible WAV. Identical urls are fetched once.
+ */
+async function checkAudioReadBack(pkg, fetchImpl = exports.defaultFetch, closure, options = {}) {
+    const { rows, issues } = collectAudioRows(pkg);
+    const unconsumed = unconsumedAudioRows(pkg);
+    if (closure)
+        issues.push(...closureMembershipIssues([...rows, ...unconsumed], closure));
+    const meta = audioPitchMeta(pkg);
+    const reports = [];
+    const rungBytes = new Map();
+    const slotClips = [];
+    const cache = new Map();
+    const cached = (url) => {
+        let hit = cache.get(url);
+        if (!hit) {
+            hit = fetchImpl(url);
+            cache.set(url, hit);
+        }
+        return hit;
+    };
+    for (const r of rows) {
+        const shape = runtimeRowIssues(r);
+        issues.push(...shape);
+        const label = `${r.use === 'bank' ? 'bank sample' : `slot ${r.slot}`} "${String(r.row.name)}"`;
+        if (typeof r.row.url !== 'string' || !r.row.url) {
+            reports.push({ path: r.path, use: r.use, slot: r.slot, name: String(r.row.name), source: 'url' });
+            continue;
+        }
+        reports.push(await checkRemoteRow(r, label, cached, issues, meta, rungBytes, slotClips));
+    }
+    for (const r of unconsumed) {
+        issues.push(...runtimeRowIssues(r));
+        const label = `slot ${r.slot} "${String(r.row.name)}" (consumed: false, still in the closure)`;
+        if (typeof r.row.url !== 'string' || !r.row.url) {
+            reports.push({ path: r.path, use: r.use, slot: r.slot, name: String(r.row.name), source: 'url' });
+            continue;
+        }
+        reports.push(await checkRemoteRow(r, label, cached, issues, meta, undefined, undefined, { loadOnly: true }));
+    }
+    issues.push(...judgeLadders(pkg, rungBytes));
+    const clips = [...slotClips, ...rungClips(pkg, rungBytes)];
+    issues.push(...judgeNearDuplicates(clips));
+    const ref = options.reference ? judgeAgainstReference(pkg, clips, options.reference) : undefined;
+    if (ref)
+        issues.push(...ref.issues);
+    return finish('read-back', pkg, reports, issues, ref?.rows);
+}
+function formatAudioReport(report) {
+    const lines = [];
+    for (const row of report.rows) {
+        const m = row.measure;
+        const where = row.source === 'local' ? row.file : row.url;
+        const level = m ? `${m.durationS.toFixed(2)} s ${m.sampleRate} Hz ${m.channels}ch peak ${m.peakDbfs} dBFS rms ${m.rmsDbfs} dBFS` : row.httpStatus ? `HTTP ${row.httpStatus}` : 'not fetched';
+        lines.push(`  ${row.use === 'bank' ? 'bank' : `slot ${row.slot}`}  ${row.name}  ${level}  ${where ?? ''}`);
+    }
+    for (const row of report.reference ?? []) {
+        lines.push(`  reference ${row.slot} (${row.candidate} vs ${row.references.join(', ')}): ${row.comparisons.map((c) => `${c.metric} x${c.ratio.toFixed(2)} (${c.candidate.toFixed(c.metric === 'roughness' ? 2 : 0)} vs ${c.reference.toFixed(c.metric === 'roughness' ? 2 : 0)}) ${c.level}`).join(', ')}`);
+    }
+    lines.push(...(0, audioProvenance_1.formatProvenance)(report.provenance ?? []));
+    for (const issue of report.issues) {
+        lines.push(`${issue.level === 'error' ? '✖' : '⚠'} [${issue.code}] ${issue.path}: ${issue.message}\n    fix: ${issue.fix}`);
+    }
+    lines.push(`${report.ok ? '✔' : '✖'} audio (${report.mode}): ${report.rows.length} sample${report.rows.length === 1 ? '' : 's'} checked, ${report.errors} error${report.errors === 1 ? '' : 's'}, ${report.warnings} warning${report.warnings === 1 ? '' : 's'}${report.fallbackEngine ? ' — no recorded engine (synthesised fallback)' : ''}`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=audio.js.map