feat(collector): committed provenance, authored reuse, changed-op manifest, fail-closed audit (AIC-1502)

[Arsene12358]

PR 3 of 4 of the Collector V3: op-centric collector management project (Linear: AIC-1502), implementing design §5, §6.3, and §8. Stacked on #1371 (base yimingl/aic-1501-family-layout-reorg); retargets when the stack merges. This PR declares an approved cross-module contract change per .claude/rules/collector/layer_permissions.md: collector finalize + aic-core loader + tools + one new workflow, coordinated.

What this does

Every table in the perf tree now carries committed provenance, reuse is authored instead of implied, and change tracking + enforcement are wired into CI:

• collection_meta.yaml (design §5): collector finalize writes it flat beside staged parquet — producing runtime (framework/version/image/digest from the manifest), per-table collector_ref (repo SHA), collector_hash (content hash over an authored closure: the op's module + a fixed shared core + its case files, collector/hash_closures.yaml, 34/34 registry modules covered by a two-direction CI-riding gate), case_plan_hash (attested from the run's checkpoint case ids), rows, status: complete|partial (derived from checkpoint failures). The external promotion step carries the sidecar with the parquet; the CI audit makes forgetting it impossible.
• reuse.yaml (design §6.3): replaces SHARED_LAYER_REUSE.txt. The tree conversion (via the reviewed tools/perf_database/migrate_markers.py, plan/execute/verify, idempotent): 255 markers → per-table declarations with derived effective donors (newest sibling under the legacy ordering — behavior-preserving; every reason field discloses the mechanical derivation), 27 comm-family markers dropped without declarations (design §6.5 rule 5 — comm never participates in sibling reuse), 7 INCOMPLETE.txt → status: partial sidecars, and 527 pre-V3 dirs backfilled with provenance: legacy sidecars (design §5 legacy tier, amended this PR) so the sidecar-coverage gate is total over the tree. Zero legacy markers remain. Discovery parity held through every data commit: 10 systems / 89 (backend, version) pairs, byte-identical.
• tools/perf_database/changed_ops.py (design §8): diffs two revisions per (framework, family) on three GPU-free signals — manifest pin, closure hash (revision-pure: even SHARED_CORE is ast-read from each revision), case-input files — emitting the locked manifest schema consumed by the evidence resolver (PR 4), the CI gate (AIC-1214), and the support-matrix healer. Fail-closed: unknown ops, VersionRoute shapes (unsupported → raise), and pre-V3 baselines (dedicated exit code 3, mapped to a neutral skip in CI) never pass silently.
• tools/perf_database/audit_collector_data.py + .github/workflows/collector-audit.yml: six fail-closed rules on every PR touching data/collector/tools — sidecar coverage, reuse validity (donors must exist with real data, same backend), comm exclusion, family placement, manifest resolution, no legacy markers. All six pass on the real tree as committed. Evidence gating against the changed-ops manifest remains AIC-1214 scope (the workflow uploads it as an artifact).
• Loader + 7 consumers read the structured files yaml-first with legacy .txt fallback for one transition window (once-per-tree deprecation warnings), including a 4-way predicate-parity test pinning the one deliberate divergence (hot-path leniency in operations/base.py).

⚠️ Maintainer sign-off requested: runtime gate extension

Populating provenance required capturing the resolved CollectorRuntime in collect_vllm/collect_trtllm — which means require_collector_runtime's exact-version fail-closed gate now applies to vLLM and TRT-LLM runs (previously sglang-only), including the vLLM XPU path which was fully ungated before. A container whose installed framework version differs from the manifest pin now hard-fails with instructions to use the pinned image. This is design §4's uniform enforcement and is zero-behavior-change against the committed manifest, but it is a real new failure path for out-of-pin containers: please confirm explicitly in review.

Migration notes for reviewers

• 12 reuse.yaml files (17 entries), all under l40s, declare tables that also exist as parquet in the declaring dir (identification predicate: self-overlap between declared table and local data). Their original marker text asserted channel-3 (cross-framework) intent; the conversion is by marker type, per the migration algorithm. Inert in this PR (declarations are not yet consumed for ordering) and safe under §6.1 (primary always wins), but PR 4 must re-derive or drop these before its ordering flip treats declarations as reviewed evidence — they deviate from §6.3's "a declared-reuse dir contains no parquet of its own".
• The 527-dir status: complete backfill makes explicit what the absence of INCOMPLETE.txt already meant implicitly; every backfilled sidecar is honestly tagged provenance: legacy (no fabricated hashes). Strict mode (PR 4) treats legacy as warn-not-fail for one release.
• Known gaps, documented in-code: XPU registries are invisible to provenance/change tracking (AIC-1509 filed); VersionRoute registry entries unsupported by the manifest tool (raises).

Test plan

uv run pytest tests/unit -m unit -n 2 green (collector suite 469, tools 221, sdk incl. 22 discovery + 8 parity tests; the finalize-glue writer has dedicated coverage incl. the legacy-tier merge guard) · real-tree audit: all six rules OK, exit 0 · changed_ops --base HEAD --head HEAD: 30 pairs unchanged; --base <pre-V3>: exit 3 with the documented message · discovery parity 10/89 unchanged across all four data commits · every fix wave re-reviewed.

🤖 Generated with Claude Code

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: e5228ed4-7994-4652-8003-55d30193bfc7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• ✅ Review completed - (🔄 Check again to review again)

---

_{Comment @coderabbitai help to get the list of available commands.}

[Arsene12358]

Merge protocol (stacked PR): please do not merge this PR until its base PR has merged to main and GitHub has auto-retargeted this one to main (the repo's delete-branch-on-merge triggers that automatically). Merging it as-is would fold this PR into its base PR's branch instead of main. After each upstream merge I'll rebase this branch onto main (squash-merge cascade) — the diff you review is unaffected. Merge order: #1370 → #1371 → #1372.

[Arsene12358]

CI fix pushed (branch rebased onto the updated #1371 base, new head 2b73e491): in addition to the base-branch fixes, this branch adds src/aiconfigurator_core/systems/data/**/*.yaml to the core wheel's maturin includes — the reuse.yaml/collection_meta.yaml sidecars this PR introduces were not being packaged, which would have made installed-wheel behavior silently diverge from repo behavior. The wheel-layer check now probes a sidecar and a reuse declaration explicitly.

[Arsene12358]

CI fixes pushed (head cf0dc28e, rebased onto the updated #1371 branch — cascade per the stack protocol):

• Validate PR title: retitled to single-scope feat(collector) (the title-check action cannot parse comma-separated scopes; see refactor(sdk): family-first perf-data layout with dual-read transition (AIC-1501) #1371 comment for details).
• copyright-checks: the check covers .yaml and flagged exactly the 762 sidecars this PR introduces (534 collection_meta.yaml + 228 reuse.yaml). All 762 now carry the repo-standard SPDX header (YAML comments are invisible to yaml.safe_load, so loader/audit parsing is byte-for-byte unchanged — real-tree audit still 6/6 OK), and both writers emit the header going forward so quarterly collections and backfill re-runs stay compliant: collector/provenance.py::write_collection_meta and the tools/perf_database/migrate_markers.py renderers. Renderer tests pin the header with startswith assertions (the yaml round-trips are comment-blind).
• Build and Test (unit): inherits the git-less-container test fix from refactor(sdk): family-first perf-data layout with dual-read transition (AIC-1501) #1371.

[Arsene12358]

Round 2 (head b0eb31f7, cascade rebase onto #1371): the remaining unit failure was test_changed_ops.py erroring on the git-less test container (FileNotFoundError: 'git' — the tool diffs real git revisions, so its tests legitimately need a git binary; test_migrate_markers.py's execute-path tests were next in line). Fixed at the root on #1371: the test Docker stage now installs git. No changes to this PR's own commits beyond the rebase.

[Arsene12358]

Round 3 (head 18e70d29): with git in the test image, 2211 tests passed and one remained — test_real_repo_base_equals_head_is_all_unchanged, the real-repo integration smoke test, fails in the container because /workspace is a source COPY without .git (git rev-parse HEAD → exit 128). That one test is now gated on the checkout actually being a git worktree; the 27 synthetic-repo changed_ops tests all run in CI. Verified locally both ways (28 passed in a real checkout; the probe returns skip in a git-less tree).