From 6f1522e1165381192eb113e951f835c35ca6345a Mon Sep 17 00:00:00 2001 From: Gunwoo Kim Date: Sat, 7 Nov 2026 23:25:51 +0900 Subject: [PATCH 1/6] chore(hevc): retain complete function profiles Signed-off-by: Gunwoo Kim --- scripts/hevc_reference.py | 2 +- scripts/tests/test_reference_hevc.py | 18 ++++++++++++++++++ 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/scripts/hevc_reference.py b/scripts/hevc_reference.py index aaf890193..364ddbcc9 100644 --- a/scripts/hevc_reference.py +++ b/scripts/hevc_reference.py @@ -191,7 +191,7 @@ def profile(args, source, record, directory): function=symbol)) if not hot: raise ValueError('profile_symbols_missing') - record['hotspots'] = hot[:15] + record['hotspots'] = hot def fetch(entry, directory, budget): diff --git a/scripts/tests/test_reference_hevc.py b/scripts/tests/test_reference_hevc.py index 1b6915c09..d22193a5b 100644 --- a/scripts/tests/test_reference_hevc.py +++ b/scripts/tests/test_reference_hevc.py @@ -130,6 +130,24 @@ def child(command, **kwargs): self.assertEqual(record['instructions'], 10000) self.assertEqual(record['hotspots'][0]['percent'], 1.0) + def test_profile_retains_functions_after_the_first_fifteen(self): + with tempfile.TemporaryDirectory() as temp: + directory = pathlib.Path(temp) + record = dict(id='c00', frames=2) + args = type('Args', (), dict(native=pathlib.Path('/native')))() + + def child(command, **kwargs): + if command[0] == 'valgrind': + (directory / 'c00.callgrind').write_text('events: Ir\nsummary: 10000\n') + return b'{"pictures":2,"decoded_pictures":2,"bins":42}', {} + return ''.join(f' 100 ( 1.00%) decoder.rs:coreav_hevc::function_{i}\n' + for i in range(20)).encode(), {} + + with patch.object(reference, 'command', side_effect=child): + reference.profile(args, pathlib.Path('/input'), record, directory) + self.assertEqual(len(record['hotspots']), 20) + self.assertEqual(record['hotspots'][-1]['function'], 'coreav_hevc::function_19') + def test_summary_takes_per_file_medians_before_depth_median(self): rows = [] for native, one, default in ((10, 2, 1), (6, 3, 2)): From 46f9b0cc7df24769261a7d439061bb18524cfded Mon Sep 17 00:00:00 2001 From: Gunwoo Kim Date: Sat, 7 Nov 2026 23:26:21 +0900 Subject: [PATCH 2/6] chore(hevc): include the full profile tail Signed-off-by: Gunwoo Kim --- scripts/hevc_reference.py | 2 +- scripts/tests/test_reference_hevc.py | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/hevc_reference.py b/scripts/hevc_reference.py index 364ddbcc9..cb0d72a67 100644 --- a/scripts/hevc_reference.py +++ b/scripts/hevc_reference.py @@ -181,7 +181,7 @@ def profile(args, source, record, directory): totals = re.search(r'^summary: (.+)$', text, re.M)[1].split() record['instructions'] = int(totals[events.index('Ir')]) annotation, _ = command(['callgrind_annotate', '--auto=no', '--inclusive=no', '--show=Ir', - '--threshold=95', output]) + '--threshold=100', output]) hot = [] for line in annotation.decode().splitlines(): match = re.match(r'^\s*([\d,]+)\s+\(\s*([\d.]+)%\)\s+.*?:((?:coreav_| Date: Sun, 8 Nov 2026 05:43:34 +0900 Subject: [PATCH 3/6] docs(hevc): plan eight-bit residual reconstruction Signed-off-by: Gunwoo Kim --- docs/design/hevc-inverse-reconstruction.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 docs/design/hevc-inverse-reconstruction.md diff --git a/docs/design/hevc-inverse-reconstruction.md b/docs/design/hevc-inverse-reconstruction.md new file mode 100644 index 000000000..b47417113 --- /dev/null +++ b/docs/design/hevc-inverse-reconstruction.md @@ -0,0 +1,11 @@ +# Eight-bit HEVC residual reconstruction + +This change stays inside the opt-in HEVC kernel crate. The first target is prediction-plus-residual clipping, defined by ITU-T H.265 V11 (01/2026), equation 8-325. It leaves dequantization, inverse DCT/DST, transform skip, parsing, filtering and ten-bit reconstruction unchanged. + +The checked `Block` types already prove every active row's extent, including a short final row without trailing padding. The eight-bit path borrows each row as a fixed array for sizes 4, 8, 16 and 32 instead of repeating checked coordinate arithmetic for every sample. A complete prediction-domain validation pass still precedes every output write. Invalid sizes and prediction samples retain the same errors, and padding is neither read nor written. + +For prediction `p` in 0 through 255 and any signed 32-bit residual `r`, `clip(p + r, 0, 255)` equals `clip(saturating_add(p, r), 0, 255)`. Negative overflow cannot occur because `p` is nonnegative. Positive overflow already implies an output of 255, so saturation cannot change the clipped result. This allows safe signed 32-bit arithmetic without narrowing the residual domain or adding an unsafe exception. + +Fixed-size rows and safe arithmetic come before explicit SIMD. The existing ten-bit implementation remains the reference for a separate follow-up; no ten-bit vector path is added here. Scratch allocation and its accounting do not change. + +Verification compares every prediction value with extreme and boundary residuals using independent 64-bit addition, covers independent strides and a minimally sized last row, and retains the existing all-size reconstruction and no-partial-write tests. Conformance outputs must remain bit-exact. Reference comparisons build explicit baseline and candidate commits in one Actions job, verify pixels before timing, rotate repeated calls, and retain complete function-level instruction profiles. These are reference figures without a judged speed threshold. From 1c922a4ae5893dea2aa02e8fdc281bc93a36a9e5 Mon Sep 17 00:00:00 2001 From: Gunwoo Kim Date: Sun, 8 Nov 2026 05:49:03 +0900 Subject: [PATCH 4/6] perf(hevc): simplify eight-bit residual clipping Signed-off-by: Gunwoo Kim --- .github/workflows/hevc-inverse-reference.yml | 104 ++++++++++++++++++ crates/coreav-kernels-hevc/src/inverse.rs | 49 +++++++++ .../coreav-kernels-hevc/src/inverse/tests.rs | 83 ++++++++++++++ scripts/hevc_inverse_reference.py | 99 +++++++++++++++++ scripts/tests/test_hevc_inverse_reference.py | 71 ++++++++++++ 5 files changed, 406 insertions(+) create mode 100644 .github/workflows/hevc-inverse-reference.yml create mode 100644 crates/coreav-kernels-hevc/src/inverse/tests.rs create mode 100644 scripts/hevc_inverse_reference.py create mode 100644 scripts/tests/test_hevc_inverse_reference.py diff --git a/.github/workflows/hevc-inverse-reference.yml b/.github/workflows/hevc-inverse-reference.yml new file mode 100644 index 000000000..c72187537 --- /dev/null +++ b/.github/workflows/hevc-inverse-reference.yml @@ -0,0 +1,104 @@ +name: hevc-inverse-reference +run-name: HEVC inverse reference ${{ inputs.candidate }} +# workflow-check: not required + +on: + workflow_dispatch: + inputs: + baseline: + description: Exact baseline decoder commit + required: true + type: string + candidate: + description: Exact candidate decoder commit + required: true + type: string + only: + description: Comma-separated reference input IDs + required: true + type: string + +permissions: + contents: read + +jobs: + inverse-reference: + runs-on: ubuntu-24.04 + timeout-minutes: 60 + env: + BASELINE: ${{ inputs.baseline }} + CANDIDATE: ${{ inputs.candidate }} + ONLY: ${{ inputs.only }} + steps: + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 + with: + persist-credentials: false + path: driver + - name: Check reference boundaries + run: | + python3 -m unittest discover -s driver/scripts/tests -p test_reference_hevc.py + python3 -m unittest discover -s driver/scripts/tests -p test_hevc_inverse_reference.py + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 + with: + persist-credentials: false + ref: ${{ env.BASELINE }} + path: baseline + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 + with: + persist-credentials: false + ref: ${{ env.CANDIDATE }} + path: candidate + - name: Admit exact repository commits before builds and credentials + run: | + set -euo pipefail + for arm in baseline candidate; do + sha="$BASELINE" + if [ "$arm" = candidate ]; then sha="$CANDIDATE"; fi + test "$(git -C "$arm" rev-parse HEAD)" = "$sha" + git -C "$arm" fetch --quiet --unshallow --no-tags origin '+refs/heads/*:refs/remotes/origin/*' + test -n "$(git -C "$arm" branch -r --contains "$sha")" + done + - uses: dtolnay/rust-toolchain@686976e191b89faba57d3206551f0f330d8cb249 + with: + toolchain: stable + - name: Build and test explicit decoder arms + run: | + set -euo pipefail + for arm in baseline candidate; do + cp driver/bench/hevc-reference/decode.rs "$arm/crates/coreav-hevc/examples/reference.rs" + (cd "$arm" && CARGO_PROFILE_RELEASE_DEBUG=1 cargo build --locked --release -p coreav-hevc --features native-hevc --example reference) + done + cd candidate + cargo test --locked -p coreav-kernels-hevc --features native-hevc + cargo test --locked -p coreav-kernels-hevc --features native-hevc,scalar + cargo clippy --locked -p coreav-kernels-hevc --all-targets --features native-hevc -- -D warnings + rustc -Vv > "$RUNNER_TEMP/compiler.txt" + - name: Install profiling tools + run: sudo apt-get update -qq && sudo apt-get install -y valgrind + - name: Install the qualified pinned oracle + env: + R2_ENDPOINT: ${{ secrets.COREAV_CORPUS_R2_ENDPOINT }} + R2_ACCESS_KEY_ID: ${{ secrets.COREAV_CORPUS_R2_ACCESS_KEY_ID }} + R2_SECRET_ACCESS_KEY: ${{ secrets.COREAV_CORPUS_R2_SECRET_ACCESS_KEY }} + R2_BUCKET: ${{ vars.COREAV_CORPUS_R2_BUCKET }} + run: driver/scripts/install-oracle-ffmpeg.sh "$RUNNER_TEMP/oracle" + - name: Verify pixels before rotated same-host reference calls + env: + R2_ENDPOINT: ${{ secrets.COREAV_CORPUS_R2_ENDPOINT }} + R2_ACCESS_KEY_ID: ${{ secrets.COREAV_CORPUS_R2_ACCESS_KEY_ID }} + R2_SECRET_ACCESS_KEY: ${{ secrets.COREAV_CORPUS_R2_SECRET_ACCESS_KEY }} + R2_BUCKET: ${{ vars.COREAV_CORPUS_R2_BUCKET }} + run: | + python3 -I driver/scripts/hevc_inverse_reference.py \ + --baseline "$PWD/baseline/target/release/examples/reference" --baseline-sha "$BASELINE" \ + --candidate "$PWD/candidate/target/release/examples/reference" --candidate-sha "$CANDIDATE" \ + --oracle-bin "$RUNNER_TEMP/oracle" --out "$RUNNER_TEMP/reference" --only "$ONLY" + - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 + if: always() + with: + name: hevc-inverse-reference-${{ env.CANDIDATE }} + path: | + ${{ runner.temp }}/reference/results.json + ${{ runner.temp }}/compiler.txt + if-no-files-found: error + retention-days: 30 diff --git a/crates/coreav-kernels-hevc/src/inverse.rs b/crates/coreav-kernels-hevc/src/inverse.rs index cb303c3d6..c0aa79ec6 100644 --- a/crates/coreav-kernels-hevc/src/inverse.rs +++ b/crates/coreav-kernels-hevc/src/inverse.rs @@ -226,6 +226,14 @@ pub fn add_residual( return Err(Error::BlockSize); } let n = prediction.size.side(); + if depth.bits() == 8 { + return match n { + 4 => add_eight::<4>(prediction, residual, output), + 8 => add_eight::<8>(prediction, residual, output), + 16 => add_eight::<16>(prediction, residual, output), + _ => add_eight::<32>(prediction, residual, output), + }; + } for y in 0..n { for x in 0..n { if prediction.at(x, y)? > depth.max_sample() { @@ -244,3 +252,44 @@ pub fn add_residual( } Ok(()) } + +fn add_eight( + prediction: Block<'_, u16>, + residual: Block<'_, i32>, + output: BlockMut<'_, u16>, +) -> Result<(), Error> { + for y in 0..N { + let row = prediction + .data + .get(y * prediction.stride..) + .and_then(<[u16]>::first_chunk::) + .ok_or(Error::Buffer)?; + if row.iter().any(|&sample| sample > 255) { + return Err(Error::Sample); + } + } + for y in 0..N { + let prediction = prediction + .data + .get(y * prediction.stride..) + .and_then(<[u16]>::first_chunk::) + .ok_or(Error::Buffer)?; + let residual = residual + .data + .get(y * residual.stride..) + .and_then(<[i32]>::first_chunk::) + .ok_or(Error::Buffer)?; + let output = output + .data + .get_mut(y * output.stride..) + .and_then(<[u16]>::first_chunk_mut::) + .ok_or(Error::Buffer)?; + for ((&prediction, &residual), sample) in prediction.iter().zip(residual).zip(output) { + *sample = residual.saturating_add(i32::from(prediction)).clamp(0, 255) as u16; + } + } + Ok(()) +} + +#[cfg(test)] +mod tests; diff --git a/crates/coreav-kernels-hevc/src/inverse/tests.rs b/crates/coreav-kernels-hevc/src/inverse/tests.rs new file mode 100644 index 000000000..64c1a7286 --- /dev/null +++ b/crates/coreav-kernels-hevc/src/inverse/tests.rs @@ -0,0 +1,83 @@ +#![allow(clippy::indexing_slicing, clippy::unwrap_used)] + +use super::*; +use crate::BlockSize; + +#[test] +fn eight_bit_add_preserves_the_full_residual_domain_and_short_last_rows() { + let residuals = [ + i32::MIN, + i32::MIN + 255, + -32768, + -256, + -255, + -1, + 0, + 1, + 254, + 255, + 256, + 32767, + i32::MAX - 255, + i32::MAX, + ]; + for n in [4, 8, 16, 32] { + let size = BlockSize::new(n).unwrap(); + for p in 0..=255u16 { + let mut prediction = std::vec![u16::MAX; (n - 1) * (n + 1) + n]; + let mut residual = std::vec![i32::MIN; (n - 1) * (n + 2) + n]; + let mut output = std::vec![u16::MAX; (n - 1) * (n + 3) + n]; + for offset in 0..residuals.len() { + for y in 0..n { + for x in 0..n { + prediction[y * (n + 1) + x] = p; + residual[y * (n + 2) + x] = + residuals[(y * n + x + offset) % residuals.len()]; + } + } + add_residual( + BitDepth::new(8).unwrap(), + Block::new(&prediction, n + 1, size).unwrap(), + Block::new(&residual, n + 2, size).unwrap(), + BlockMut::new(&mut output, n + 3, size).unwrap(), + ) + .unwrap(); + for y in 0..n { + for x in 0..n { + assert_eq!( + output[y * (n + 3) + x], + (i64::from(p) + i64::from(residual[y * (n + 2) + x])).clamp(0, 255) + as u16 + ); + } + if y + 1 < n { + assert_eq!(&output[y * (n + 3) + n..(y + 1) * (n + 3)], &[u16::MAX; 3]); + } + } + } + } + } +} + +#[test] +fn every_invalid_eight_bit_prediction_position_preserves_the_whole_output() { + for n in [4, 8, 16, 32] { + let size = BlockSize::new(n).unwrap(); + let residual = std::vec![0; n * n]; + for invalid in 0..n * n { + let mut prediction = std::vec![255; n * n]; + prediction[invalid] = 256; + let mut output = std::vec![1234; n * n]; + assert_eq!( + add_residual( + BitDepth::new(8).unwrap(), + Block::new(&prediction, n, size).unwrap(), + Block::new(&residual, n, size).unwrap(), + BlockMut::new(&mut output, n, size).unwrap(), + ), + Err(Error::Sample) + ); + assert!(output.iter().all(|&sample| sample == 1234)); + } + } +} diff --git a/scripts/hevc_inverse_reference.py b/scripts/hevc_inverse_reference.py new file mode 100644 index 000000000..d8a43d7c9 --- /dev/null +++ b/scripts/hevc_inverse_reference.py @@ -0,0 +1,99 @@ +#!/usr/bin/env python3 +"""Compare explicit HEVC reconstruction commits on one reference host.""" + +import argparse +import json +import pathlib +import platform +import re +import sys +import tempfile + +sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent)) +import hevc_reference as reference + + +def compare(baseline, candidate, oracle, source, repeats): + expected = reference.verify(baseline, oracle, source) + if reference.verify(candidate, oracle, source) != expected: + raise ValueError('candidate_output_identity') + commands = { + 'baseline': [baseline, source, 'decode'], + 'candidate': [candidate, source, 'decode'], + 'ffmpeg_one': reference.ffmpeg_command(oracle.ffmpeg, source, True, + ['-progress', 'pipe:1', '-f', 'null', '-']), + } + arms = tuple(commands) + for arm in arms: + stdout, _ = reference.command(commands[arm]) + reference.check_work('coreav' if arm != 'ffmpeg_one' else arm, stdout, expected['frames']) + calls = [] + for repeat in range(repeats): + offset = repeat % len(arms) + for arm in arms[offset:] + arms[:offset]: + stdout, receipt = reference.command(commands[arm]) + reference.check_work('coreav' if arm != 'ffmpeg_one' else arm, stdout, expected['frames']) + calls.append(dict(arm=arm, repeat=repeat, **receipt)) + return dict(**expected, calls=calls) + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + for arm in ('baseline', 'candidate'): + parser.add_argument('--' + arm, type=pathlib.Path, required=True) + parser.add_argument('--' + arm + '-sha', required=True) + parser.add_argument('--oracle-bin', type=pathlib.Path, required=True) + parser.add_argument('--out', type=pathlib.Path, required=True) + parser.add_argument('--only', required=True) + parser.add_argument('--frames', type=int, default=32, choices=range(1, 65)) + parser.add_argument('--repeats', type=int, default=5, choices=range(5, 10)) + args = parser.parse_args() + for sha in (args.baseline_sha, args.candidate_sha): + if re.fullmatch('[0-9a-f]{40}', sha) is None: + parser.error('full_commit_sha_required') + args.only = set(args.only.split(',')) + if not args.only or args.only - {f'd{i:02}' for i in range(26)} - {f'c{i:02}' for i in range(4)}: + parser.error('unknown_reference_input') + oracle = reference.test_oracle.require(args.oracle_bin / 'ffmpeg', args.oracle_bin / 'ffprobe') + args.out.mkdir(parents=True, exist_ok=True) + report = dict(complete=False, baseline=args.baseline_sha, candidate=args.candidate_sha, + baseline_binary_sha256=reference.conformance.digest(args.baseline), + candidate_binary_sha256=reference.conformance.digest(args.candidate), + oracle=reference.oracle_pin.load()['BUILD'], selected_ids=sorted(args.only), + frames_cap=args.frames, repeats=args.repeats, files=[], + host=dict(cpu=next(line.split(':', 1)[1].strip() + for line in pathlib.Path('/proc/cpuinfo').read_text().splitlines() + if line.startswith('model name')), kernel=platform.release())) + pool = reference.round_files.pool() + pool.limits.max_requests = 4000 + pool.limits.max_bytes = 32 << 30 + try: + with tempfile.TemporaryDirectory(prefix='hevc-inverse-') as temp: + directory = pathlib.Path(temp) + for identity, source, original_sha in reference.inputs(args, oracle, directory, pool): + row = dict(id=identity, source_sha256=original_sha, + input_sha256=reference.conformance.digest(source), + **compare(args.baseline, args.candidate, oracle, source, args.repeats)) + report['files'].append(row) + if identity == 'c00': + small = directory / 'profile.hevc' + reference.command([oracle.ffmpeg, '-hide_banner', '-loglevel', 'error', '-nostdin', + '-i', source, '-frames:v', '2', '-c:v', 'copy', '-f', 'hevc', '-y', small]) + for arm in ('baseline', 'candidate'): + binary = getattr(args, arm) + profile = dict(id=arm, **reference.verify(binary, oracle, small)) + reference.profile(argparse.Namespace(native=binary), small, profile, directory) + row[arm + '_profile'] = profile + report['r2_requests'] = pool.limits.requests + (args.out / 'results.json').write_text(json.dumps(report, indent=2) + '\n') + if {row['id'] for row in report['files']} != args.only: + raise ValueError('incomplete_input_selection') + report['complete'] = True + finally: + report['r2_requests'] = pool.limits.requests + pool.close() + (args.out / 'results.json').write_text(json.dumps(report, indent=2) + '\n') + + +if __name__ == '__main__': + main() diff --git a/scripts/tests/test_hevc_inverse_reference.py b/scripts/tests/test_hevc_inverse_reference.py new file mode 100644 index 000000000..3c6c53715 --- /dev/null +++ b/scripts/tests/test_hevc_inverse_reference.py @@ -0,0 +1,71 @@ +import pathlib +import sys +import unittest +from unittest.mock import patch + +SCRIPTS = pathlib.Path(__file__).resolve().parents[1] +sys.path.insert(0, str(SCRIPTS)) +import hevc_inverse_reference as inverse + + +class InverseReference(unittest.TestCase): + def setUp(self): + self.oracle = inverse.reference.test_oracle.Oracle( + pathlib.Path('/qualified/ffmpeg'), pathlib.Path('/qualified/ffprobe')) + self.expected = dict(depth=8, frames=2, output_md5='same') + + def test_pixel_verification_precedes_every_call_and_rotates_all_three_arms(self): + order = [] + + def verify(binary, oracle, source): + self.assertEqual(oracle, self.oracle) + order.append(str(binary)) + return self.expected + + def command(args): + self.assertEqual(order, ['/baseline', '/candidate']) + stdout = b'frame=2\n' if args[0] == self.oracle.ffmpeg else \ + b'{"pictures":2,"decoded_pictures":2,"bins":42}' + return stdout, dict(wall=1.0, user=0.5, system=0.1) + + with patch.object(inverse.reference, 'verify', side_effect=verify), \ + patch.object(inverse.reference, 'command', side_effect=command): + row = inverse.compare('/baseline', '/candidate', self.oracle, '/input', 5) + self.assertEqual(row['output_md5'], 'same') + self.assertEqual(len(row['calls']), 15) + self.assertEqual([c['arm'] for c in row['calls'][:9]], [ + 'baseline', 'candidate', 'ffmpeg_one', + 'candidate', 'ffmpeg_one', 'baseline', + 'ffmpeg_one', 'baseline', 'candidate']) + self.assertEqual({c['repeat'] for c in row['calls']}, set(range(5))) + + def test_output_mismatch_prevents_timing(self): + with patch.object(inverse.reference, 'verify', side_effect=[self.expected, + dict(self.expected, output_md5='changed')]), \ + patch.object(inverse.reference, 'command') as command: + with self.assertRaisesRegex(ValueError, 'candidate_output_identity'): + inverse.compare('/baseline', '/candidate', self.oracle, '/input', 5) + command.assert_not_called() + + def test_missing_decode_work_is_fatal_even_when_process_succeeds(self): + with patch.object(inverse.reference, 'verify', return_value=self.expected), \ + patch.object(inverse.reference, 'command', return_value=( + b'{"pictures":1,"decoded_pictures":1,"bins":42}', {})): + with self.assertRaisesRegex(ValueError, 'native_work'): + inverse.compare('/baseline', '/candidate', self.oracle, '/input', 5) + + def test_workflow_admits_both_exact_arms_before_builds_or_credentials(self): + text = (SCRIPTS.parent / '.github/workflows/hevc-inverse-reference.yml').read_text() + admission = text.index('Admit exact repository commits') + self.assertLess(text.index('path: baseline'), admission) + self.assertLess(text.index('path: candidate'), admission) + self.assertLess(admission, text.index('cargo build')) + self.assertLess(admission, text.index('secrets.')) + self.assertIn('for arm in baseline candidate', text) + self.assertIn('branch -r --contains "$sha"', text) + self.assertIn('vars.COREAV_CORPUS_R2_BUCKET', text) + self.assertNotIn('secrets.COREAV_CORPUS_R2_BUCKET', text) + + +if __name__ == '__main__': + unittest.main() From d7703563513bae94fe985650fb7f75ba534acd0b Mon Sep 17 00:00:00 2001 From: Gunwoo Kim Date: Sun, 8 Nov 2026 05:50:14 +0900 Subject: [PATCH 5/6] ci(hevc): route inverse comparisons through dispatch Signed-off-by: Gunwoo Kim --- .github/workflows/hevc-inverse-reference.yml | 11 +++++++++++ .github/workflows/hevc-reference.yml | 15 +++++++++++++++ scripts/hevc_inverse_reference.py | 3 ++- scripts/tests/test_hevc_inverse_reference.py | 10 ++++++++++ 4 files changed, 38 insertions(+), 1 deletion(-) diff --git a/.github/workflows/hevc-inverse-reference.yml b/.github/workflows/hevc-inverse-reference.yml index c72187537..8cfdd6e71 100644 --- a/.github/workflows/hevc-inverse-reference.yml +++ b/.github/workflows/hevc-inverse-reference.yml @@ -3,6 +3,17 @@ run-name: HEVC inverse reference ${{ inputs.candidate }} # workflow-check: not required on: + workflow_call: + inputs: + baseline: + required: true + type: string + candidate: + required: true + type: string + only: + required: true + type: string workflow_dispatch: inputs: baseline: diff --git a/.github/workflows/hevc-reference.yml b/.github/workflows/hevc-reference.yml index 606fa0644..93e0e1b48 100644 --- a/.github/workflows/hevc-reference.yml +++ b/.github/workflows/hevc-reference.yml @@ -5,6 +5,11 @@ run-name: HEVC reference ${{ inputs.candidate }} on: workflow_dispatch: inputs: + baseline: + description: Optional exact baseline for a same-host inverse comparison + required: false + default: '' + type: string candidate: description: Exact decoder commit required: true @@ -24,7 +29,17 @@ permissions: contents: read jobs: + inverse-comparison: + if: inputs.baseline != '' + uses: ./.github/workflows/hevc-inverse-reference.yml + with: + baseline: ${{ inputs.baseline }} + candidate: ${{ inputs.candidate }} + only: ${{ inputs.only }} + secrets: inherit + reference: + if: inputs.baseline == '' runs-on: ubuntu-24.04 timeout-minutes: 150 env: diff --git a/scripts/hevc_inverse_reference.py b/scripts/hevc_inverse_reference.py index d8a43d7c9..33d34673e 100644 --- a/scripts/hevc_inverse_reference.py +++ b/scripts/hevc_inverse_reference.py @@ -11,6 +11,7 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent)) import hevc_reference as reference +import test_oracle def compare(baseline, candidate, oracle, source, repeats): @@ -54,7 +55,7 @@ def main(): args.only = set(args.only.split(',')) if not args.only or args.only - {f'd{i:02}' for i in range(26)} - {f'c{i:02}' for i in range(4)}: parser.error('unknown_reference_input') - oracle = reference.test_oracle.require(args.oracle_bin / 'ffmpeg', args.oracle_bin / 'ffprobe') + oracle = test_oracle.require(args.oracle_bin / 'ffmpeg', args.oracle_bin / 'ffprobe') args.out.mkdir(parents=True, exist_ok=True) report = dict(complete=False, baseline=args.baseline_sha, candidate=args.candidate_sha, baseline_binary_sha256=reference.conformance.digest(args.baseline), diff --git a/scripts/tests/test_hevc_inverse_reference.py b/scripts/tests/test_hevc_inverse_reference.py index 3c6c53715..34514e201 100644 --- a/scripts/tests/test_hevc_inverse_reference.py +++ b/scripts/tests/test_hevc_inverse_reference.py @@ -66,6 +66,16 @@ def test_workflow_admits_both_exact_arms_before_builds_or_credentials(self): self.assertIn('vars.COREAV_CORPUS_R2_BUCKET', text) self.assertNotIn('secrets.COREAV_CORPUS_R2_BUCKET', text) + def test_existing_dispatch_routes_only_an_explicit_baseline_to_the_comparison(self): + text = (SCRIPTS.parent / '.github/workflows/hevc-reference.yml').read_text() + self.assertIn("if: inputs.baseline != ''", text) + self.assertIn("if: inputs.baseline == ''", text) + self.assertIn('uses: ./.github/workflows/hevc-inverse-reference.yml', text) + for name in ('baseline', 'candidate', 'only'): + self.assertIn(name + ': ${{ inputs.' + name + ' }}', text) + reusable = (SCRIPTS.parent / '.github/workflows/hevc-inverse-reference.yml').read_text() + self.assertIn(' workflow_call:', reusable) + if __name__ == '__main__': unittest.main() From 2983e12e7a66fef90c28f343fb71119ad2e7ccd6 Mon Sep 17 00:00:00 2001 From: Gunwoo Kim Date: Sun, 8 Nov 2026 12:47:46 +0900 Subject: [PATCH 6/6] ci(hevc): reject invalid comparison inputs early Signed-off-by: Gunwoo Kim --- .github/workflows/hevc-inverse-reference.yml | 8 +++++++ docs/agents/ci.md | 1 + scripts/tests/test_hevc_inverse_reference.py | 24 ++++++++++++++++++++ 3 files changed, 33 insertions(+) diff --git a/.github/workflows/hevc-inverse-reference.yml b/.github/workflows/hevc-inverse-reference.yml index 8cfdd6e71..c2169d541 100644 --- a/.github/workflows/hevc-inverse-reference.yml +++ b/.github/workflows/hevc-inverse-reference.yml @@ -41,6 +41,14 @@ jobs: CANDIDATE: ${{ inputs.candidate }} ONLY: ${{ inputs.only }} steps: + - name: Validate dispatch inputs + run: | + set -euo pipefail + [[ "$BASELINE" =~ ^[0-9a-f]{40}$ ]] + [[ "$CANDIDATE" =~ ^[0-9a-f]{40}$ ]] + input='(c0[0-3]|d(0[0-9]|1[0-9]|2[0-5]))' + pattern="^${input}(,${input})*$" + [[ "$ONLY" =~ $pattern ]] - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 with: persist-credentials: false diff --git a/docs/agents/ci.md b/docs/agents/ci.md index 86bea1acf..2975af654 100644 --- a/docs/agents/ci.md +++ b/docs/agents/ci.md @@ -39,6 +39,7 @@ List development caches with `docker volume ls --filter name=coreav-dev-`. After | Rule | Enforced by | |---|---| +| The inverse HEVC comparison rejects malformed commit identities and an empty or unknown input selection before checkout, build or credential use, while the ordinary reference route keeps its optional selection | `test_dispatch_rejects_invalid_inputs_before_checkout_or_build` executes the workflow's actual shell validation for invalid values and all admitted IDs; `test_existing_dispatch_routes_only_an_explicit_baseline_to_the_comparison` preserves the ordinary route. Validation precedes checkout, where the Python owner is not available; workflow inputs are external strings, so Rust types cannot admit them | | A development image verifies its Rust bootstrap before executing it | `scripts/dev/Dockerfile` selects versioned rustup-init binaries and committed architecture-specific SHA-256 values; `test_corrupt_bootstrap_is_not_executed` executes its shell step with a corrupt download for both architectures and requires checksum failure without execution. The compiler toolchain remains owned by `rust-toolchain.toml` | | Local Linux development commands mount only their linked worktree and named Cargo caches, without writable Git pointers, host credentials or default runtime networking | `scripts/dev-container.py` owns the Docker argument list and explicit build inputs; `test_dev_container.py` checks the read-only `.git` overlay, primary-checkout refusal, mounts, non-root identity, limits, network opt-in, argument forwarding, build context, and refusal outside the worktree. Keep secrets outside the mounted worktree; arbitrary file contents cannot be classified by a path check | | A credentialed manual workflow that builds a dispatched commit admits only commits on this repository's branches, so pull-request code from forks never runs beside corpus credentials | The HEVC reference workflow's admission step refuses a candidate no branch contains before the build and every credentialed step; `test_candidate_must_be_on_a_branch_before_it_builds_or_sees_credentials` pins that order. Writers already hold the repository's secrets, so this closes the only path that widens access. Workflow step order cannot be encoded in Rust types | diff --git a/scripts/tests/test_hevc_inverse_reference.py b/scripts/tests/test_hevc_inverse_reference.py index 34514e201..40ec3b37d 100644 --- a/scripts/tests/test_hevc_inverse_reference.py +++ b/scripts/tests/test_hevc_inverse_reference.py @@ -1,5 +1,8 @@ import pathlib +import os +import subprocess import sys +import textwrap import unittest from unittest.mock import patch @@ -76,6 +79,27 @@ def test_existing_dispatch_routes_only_an_explicit_baseline_to_the_comparison(se reusable = (SCRIPTS.parent / '.github/workflows/hevc-inverse-reference.yml').read_text() self.assertIn(' workflow_call:', reusable) + def test_dispatch_rejects_invalid_inputs_before_checkout_or_build(self): + text = (SCRIPTS.parent / '.github/workflows/hevc-inverse-reference.yml').read_text() + validation = text.index(' - name: Validate dispatch inputs') + self.assertLess(validation, text.index('actions/checkout@')) + self.assertLess(validation, text.index('cargo build')) + self.assertLess(validation, text.index('secrets.')) + script = text[validation:].split(' run: |\n', 1)[1].split(' - uses:', 1)[0] + script = textwrap.dedent(script) + valid = dict(BASELINE='a' * 40, CANDIDATE='b' * 40, ONLY='c00,d25') + for name, value in [('BASELINE', 'a' * 39), ('CANDIDATE', 'g' * 40), + ('ONLY', ''), ('ONLY', 'c04'), ('ONLY', 'd26'), + ('ONLY', 'c00,'), ('ONLY', 'c00, d01')]: + with self.subTest(name=name, value=value): + result = subprocess.run(['bash', '-c', script], capture_output=True, + env={**os.environ, **valid, name: value}, timeout=5) + self.assertNotEqual(result.returncode, 0) + for only in [f'c{i:02}' for i in range(4)] + [f'd{i:02}' for i in range(26)] + ['c00,d25,c00']: + result = subprocess.run(['bash', '-c', script], capture_output=True, + env={**os.environ, **valid, 'ONLY': only}, timeout=5) + self.assertEqual(result.returncode, 0, only) + if __name__ == '__main__': unittest.main()