feat(compat): count AAC tolerance separately

.github/workflows/github-shapes.yml

@@ -14,6 +14,13 @@ on:
       - scripts/install-oracle-ffmpeg.sh
       - scripts/install-x264.sh
       - scripts/oracle*
+      - scripts/aac_pcm_eligibility.py
+      - scripts/aac_pns.py
+      - scripts/aac-pns-requirements.txt
+      - docs/design/aac-pcm-eligibility.md
+      - docs/design/aac-pns-eligibility.md
+      - docs/compat/audio-decoder-eligibility.json
+      - tools/compat-corpus/tests/test_github_shapes_aac.py
   workflow_dispatch:
     inputs:
       commit:
@@ -71,10 +78,14 @@ jobs:
           sudo apt-get install -y --no-install-recommends libdav1d-dev libvpx-dev libopus-dev nasm pkg-config
           scripts/install-oracle-ffmpeg.sh "$RUNNER_TEMP/oracle"
           scripts/install-x264.sh "$RUNNER_TEMP/oracle"
+          python3 -m venv "$RUNNER_TEMP/aac-python"
+          "$RUNNER_TEMP/aac-python/bin/pip" install --quiet --only-binary=:all: --require-hashes -r scripts/aac-pns-requirements.txt
+          echo "$RUNNER_TEMP/aac-python/bin" >> "$GITHUB_PATH"
       - name: Build the full feature set
         run: |
           set -euo pipefail
           cargo build --release --locked -p coreav-cli --features release-full
+          cargo build --locked --release -p coreav-aac --features diagnostics --example pns_diagnostic
           python3 - <<'PY'
           import hashlib, json, os
           from pathlib import Path
@@ -91,6 +102,7 @@ jobs:
           python3 tools/compat-corpus/github_shapes.py run --commit "$COMMIT" \
             --build-record "$RUNNER_TEMP/shape-build.json" \
             --coreav "$PWD/target/release/coreav" --ffmpeg "$RUNNER_TEMP/oracle/ffmpeg" \
+            --pns-diagnostic "$PWD/target/release/examples/pns_diagnostic" \
             --ffprobe "$RUNNER_TEMP/oracle/ffprobe" --x264 "$RUNNER_TEMP/oracle/x264" \
             --bundle "$RUNNER_TEMP/shape-evidence" --scratch "$RUNNER_TEMP/shape-replay" \
             --summary "$RUNNER_TEMP/shape-summary.json"
@@ -104,3 +116,33 @@ jobs:
             ${{ runner.temp }}/shape-build.json
           if-no-files-found: error
           retention-days: 30
+  aac-controls:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    env:
+      OPENBLAS_NUM_THREADS: '1'
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+      - name: Install the pinned oracle and transform dependency
+        run: |
+          set -euo pipefail
+          scripts/install-oracle-ffmpeg.sh "$RUNNER_TEMP/aac-oracle"
+          python3 -m venv "$RUNNER_TEMP/aac-python"
+          "$RUNNER_TEMP/aac-python/bin/pip" install --quiet --only-binary=:all: --require-hashes -r scripts/aac-pns-requirements.txt
+          echo "$RUNNER_TEMP/aac-python/bin" >> "$GITHUB_PATH"
+      - name: Build the AAC command and opt-in diagnostic
+        run: |
+          cargo build --locked --release -p coreav-cli --features aac
+          cargo build --locked --release -p coreav-aac --features diagnostics --example pns_diagnostic
+      - name: Check independent AAC command controls
+        env:
+          COREAV_SHAPES_ORACLE: ${{ runner.temp }}/aac-oracle
+          COREAV_SHAPES_COREAV: ${{ github.workspace }}/target/release/coreav
+          COREAV_SHAPES_AAC_DIAGNOSTIC: ${{ github.workspace }}/target/release/examples/pns_diagnostic
+        run: |
+          python3 -I -m unittest discover -s tools/compat-corpus/tests -p test_github_shapes_aac.py
+          python3 -I -m unittest discover -s scripts/tests -p test_aac_pns.py
+          python3 -I -m unittest discover -s scripts/tests -p test_aac_pcm_eligibility.py

docs/agents/compat-corpus.md

@@ -4,6 +4,7 @@ Corpus exclusions, compatibility workflows, fixture comparisons, the HEVC confor
 
 | Rule | Enforced by |
 |---|---|
+| AAC compatibility binds each measured PCM payload to its own fully qualified decoder output, and no AAC-decoded PNS output earns exact credit | `github_shapes_aac` reuses the complete registered qualification, checks same-command WAV framing and scans every stored packet before AAC-decoded exact credit. Generated raw/WAV, PNS, payload/framing mutation, sibling-copy, encoded-PNS and separate-accounting controls in `test_github_shapes_aac.py` enforce the boundary. One qualification owner prevents tolerance drift; external process outputs and PNS content still require runtime proof rather than declared codec types |
 | New concat output qualification stays outside the registered frozen harness module graph | `ffmpeg_concat` and `ffmpeg_aac_filter` own the non-frozen comparator, while `test_the_harness_driver_and_its_path_modules_are_frozen` rejects an unregistered path module in `tests/ffmpeg.rs`. Separate test targets preserve the existing source registry without expanding frozen measurement material; a Rust module type cannot enforce that provenance boundary |
 | avc1 compatibility requires known presentation timestamps and positive durations for every presented video and audio frame in every output, without relaxing the exact category | `exact_frame_timeline` in `decoded_output.compare` owns compatibility-only validation; `avc1_carriage` and the runner's final output checks require it. Generated missing-video-time, nonpositive-duration, copied and encoded audio, and multi-output regressions in `test_github_shapes.py` enforce the boundary. External probe fields require runtime checks, not declared stream types |
 | HEVC oracle comparisons describe the base reconstruction, not optional enhancement-decoder output | `HEVC_DECODE_INPUT` owns `-export_side_data +enhancements` for frame probing, whole-output hashes, picture hashes and numeric diagnostics. Command regressions require the shared option before input on every decoded-pixel path; original geometry, complete-output and published-MD5 checks remain unchanged. A native type cannot govern external decoder options |

docs/design/github-shapes-200.md

@@ -65,7 +65,7 @@ Unlike V2's lossy quality predicates, this measurement requires exact decoded eq
 
 The headline is `counted shapes / 200`. The weighted headline is the sum of repository counts for counted shapes divided by 1,470. It is the covered share of the top-200 repository-shape pairs, not 200 unique repositories and not 44% of real executions. Also report the numerator over all 3,338 sample pairs, explicitly as a lower-bound sample presence share. There is no bar, required count, release verdict or performance claim.
 
-Each shape receives exactly one result in this order: `uninstantiable`, `reference_failed`, `timeout`, `refused`, `failed`, `unexpected_program`, `no_oracle`, `different`, `compatible_avc1`, or `counted`. The separately registered `compatible_avc1` outcome below is a miss for the exact headline. Break out both shape counts and repository weights for every miss class and both tools. A malformed fallback log, wrong oracle, changed registration, changed fixture or binary, or missing/duplicate result makes the record incomplete rather than reducing a denominator.
+Each shape receives exactly one result in this order: `uninstantiable`, `reference_failed`, `timeout`, `refused`, `failed`, `unexpected_program`, `no_oracle`, `different`, `compatible_avc1`, `compatible_aac`, or `counted`. The separately registered compatibility outcomes below are misses for the exact headline. Break out both shape counts and repository weights for every miss class and both tools. A malformed fallback log, wrong oracle, changed registration, changed fixture or binary, or missing/duplicate result makes the record incomplete rather than reducing a denominator.
 
 An acquisition bundle retains generated fixtures, commands, binary identities, complete stdout, output files, fallback and program logs, and per-command process outcomes. The manifest binds evidence and method files by SHA-256. Replay verifies these identities, regenerates the commands from the frozen set, checks the complete roster and reapplies the output comparisons with the pinned oracle. It does not trust stored pass booleans or summary totals. Replacing a result label cannot create coverage. Artifacts use only generated media and relative names. Summaries contain closed reason labels, not arbitrary process diagnostics or machine paths.
 
@@ -79,6 +79,28 @@ An acquisition bundle retains generated fixtures, commands, binary identities, c
 
 No commands-v1, commands-0.1.0, judging policy, known-divergence record, held-out input, existing bar, tolerance, baseline or V1 to V3 record changes.
 
+## Separate AAC compatibility registration
+
+Registered on 2026-11-06 before implementation or decoder comparison. The maintainer requested that qualified AAC decode-tolerance commands count as compatible, separately from exact output, following coreav-dev/coreav#433. The new `compatible_aac` result never increases `counted`, `counted_pairs`, `top_200_pair_share` or `whole_sample_presence_lower_bound`. PNS is never exact. Frozen results, gate records, published numbers, population, fixtures and command assignments do not change. A new measurement result requires a separate later submission.
+
+### Predicate and scope
+
+Reuse the complete [AAC PCM qualification](aac-pcm-eligibility.md) and its [PNS extension](aac-pns-eligibility.md), including the existing production preflight. This section adds AAC scope separately; the avc1 registration's statement that it does not admit AAC tolerance describes only that registration. There is no new tolerance. No-PNS PCM requires complete finite F32 samples within 2^-16 and actual S16 samples within one LSB. PNS requires independently checked per-band energies within 0.1 dB for both decoders, the registered deterministic-bin and non-PNS projection bars, each decoder's actual S16 packing against its own F32, and exact metadata-predicted presentation intervals. Cross-decoder pointwise comparison of complete PNS waveforms is neither required nor sufficient.
+
+Only a single seekable MP4 input with one explicit mono or stereo AAC-LC audio track and a single audio-only output can qualify. Source video may be present but cannot be output. Retain the qualification's bounded nonfragmented timelines, complete packet scan, clean decoding, window-history rules and excluded PNS tool combinations. Output is raw F32, raw S16 or S16 WAV, with native rate and channel count. Explicit `-ar` and `-ac` must be identities. Permit only the existing default audio selection, optional input `-threads 1`, output `-vn`, `-c:a`, `-f`, `-ar` and `-ac`. The complete reference mapping must show AAC decoding to the corresponding PCM encoder, including when encoder selection is implicit. No seek, trim, filter, mixing, other encode, copied stream, multiple input or multiple output is qualified.
+
+The candidate ranks within this scope are 5, 13, 33, 43, 53, 57, 67, 72, 77, 89, 98, 139, 168 and 174. These are candidates, not observed passes. Ranks 15 and 188 use input pipes, which the existing seekable-input qualification does not cover. Rank 44 writes PCM in MP4, whose complete framing is not qualified. F32 WAV, other containers and unsupported or specification-undecidable presentations remain out. Do not infer qualification from a rank or codec label.
+
+The exact-credit guard follows AAC decoding in the reference mapping, not the output codec. Every non-copy output decoded from AAC needs a successful complete stored-packet diagnostic scan showing no PNS before exact credit. Unknown scans and PNS in unqualified output forms are `different`. This can only lower exact credit; it does not qualify an encoded output or alter its native path. Copied AAC keeps its existing packet and decoded predicates. The scan never reads a judged input before merge.
+
+### Implementation and verification order
+
+1. Commit this plan first. Implement only measurement tooling, qualification-output export, generated controls and workflow wiring. Do not change native decoding, MP3 or any frozen artifact.
+2. For an eligible command, rerun the existing complete qualification with the same bound CoreAV, pinned FFmpeg 9.0.2 and opt-in diagnostic binaries. Export the qualified raw outputs for both arms without changing acceptance. Require each measured payload to equal its own arm's qualified payload byte for byte. This binds actual outputs to the numerical proof and exact count, priming and channel order. A content-admission flag or stored pass label cannot substitute for this proof.
+3. Require everything outside the AAC PCM payload to be exact. Raw outputs have no framing. For S16 WAV require valid complete extents, sample fields and byte-identical framing and metadata, with payloads equal to their respective qualified raw outputs. File-output stdout must be empty, with no undeclared files or external encoder starts. A framing or payload mutation fails even if separate qualification passes. Compare WAV framing against the same-command reference output, not the qualification's metadata-discard control. Keep the exact decoded comparator first. Only a decoded-sample mismatch may use tolerance; other mismatches remain misses. Before exact credit for AAC-decoded PCM, a successful complete diagnostic scan must establish that no packet contains PNS. Unknown diagnostics fail closed. Even accidentally equal PNS samples require full qualification and receive only compatible credit. Qualification failures remain `different`, not `no_oracle`.
+4. Keep existing non-AAC exact and avc1 behavior. Report the AAC category and its repository weights separately. Replay requalifies the bound input and checks actual output bytes, rather than trusting labels. Bind diagnostic build command, binary digest, qualification dependencies and method files to the acquisition manifest. Historical manifests cannot be rejudged under the new method.
+5. Before merge, run only independent generated controls and fake-executable or pure-accounting tests. Cover no-PNS and separable PNS, both PCM widths, raw file and stdout, S16 WAV file and stdout, identity options, unsupported profiles or timelines or PNS tools, count drift, nonfinite samples, changed payloads, metadata and framing, and separate shape and weighted accounting. Use the verified pinned oracle and unchanged transform controls. Do not execute judged commands, the judged fixture generator, held-out inputs or retained judged outputs with this predicate before merge.
+
 ## Separate avc1 compatibility registration
 
 Registered on 2026-11-06 before implementation or execution of this predicate. The maintainer permits a separate `compatible_avc1` outcome for copied H.264 parameter-set carriage. Like the separate [AAC decode-tolerance qualification](aac-pcm-eligibility.md), it never increases an exact-output count. The existing `counted` predicate, frozen exact results, published numbers, population, fixtures and gate records stay unchanged. This registration does not admit AAC tolerance into this measurement.

scripts/aac_pcm_eligibility.py

@@ -148,7 +148,7 @@ def presentation_interval(metadata, listing):
     return skip, count
 
 
-def check(coreav, oracle, source, work, diagnostic):
+def check(coreav, oracle, source, work, diagnostic, capture=None):
     with tempfile.TemporaryDirectory(prefix='aac-diagnostic-', dir=work) as path:
         directory = Path(path)
         captured = run([diagnostic, source, directory])
@@ -158,13 +158,13 @@ def check(coreav, oracle, source, work, diagnostic):
             noise = sum(len(channel['noise']) for frame in metadata['frames'] for channel in frame['channels'])
             if noise and not metadata['unsafe']:
                 pns = pns_check(oracle, source, directory, metadata)
-        row = check_output(coreav, oracle, source, work, metadata, pns)
+        row = check_output(coreav, oracle, source, work, metadata, pns, capture)
         if captured.returncode:
             row['diagnostic_refusal'] = captured.stderr.decode()[-500:].strip()
         return row
 
 
-def check_output(coreav, oracle, source, work, metadata, pns):
+def check_output(coreav, oracle, source, work, metadata, pns, capture=None):
     row = {'sha256': hashlib.sha256(source.read_bytes()).hexdigest(), 'formats': {}}
     probe = run([oracle / 'ffprobe', '-v', 'error', '-select_streams', 'a:0',
                  '-show_entries', 'stream=sample_rate,channels,profile', '-of', 'json', source])
@@ -274,6 +274,8 @@ def check_output(coreav, oracle, source, work, metadata, pns):
             compare_wav(wave_file.read_bytes(), pin_file.read_bytes(), actual.stdout,
                         reference.stdout, row['channels'], row['rate'])
         row['formats'][fmt] = result
+        if capture is not None:
+            capture[fmt] = (actual.stdout, reference.stdout)
     row['status'] = 'ineligible' if refusal else 'pass'
     if refusal:
         row['reason'] = refusal