fix(governance): require reconstructable PR queue source commit provenance

[seonghobae]

Closes #1146.

Scope

This PR is now the main-based landing lane for PR-queue source provenance. Its former parent #998 has merged, and the branch has been non-destructively reconciled onto current protected main; it no longer carries the parent DIF/release delta as an effective PR diff.

scripts/build_pr_queue_governance.py::_source_commit() previously failed open:

• non-timeout Git failures returned "unknown";
• arbitrary stdout was accepted as the source commit.

That allowed governance evidence to cite a non-reconstructable source. The current implementation preserves the bounded Git deadline, fails closed with package-owned RuntimeError for lookup failures, and accepts only canonical lowercase full SHA-1 (40 hex) or SHA-256 (64 hex) object identities. Empty, abbreviated, uppercase, non-hexadecimal, undersized, and oversized output is rejected before evidence emission.

Focused RED-first coverage preserves timeout handling, non-zero/missing-executable failures, malformed identities, canonical SHA-1/SHA-256 compatibility, offline snapshot behavior, and build-level source propagation. The governed changelog links and summarizes the supply-chain provenance research basis.

Fresh integration boundary

Decision-time protected main: bdd2638151be6f6f7341f246b453467ea62b5114. Exact current head: 2b4f859dcc0af180fc79c383dc7631be17e8234f. The branch is 6 commits ahead / 0 behind current main, open, non-Draft, and mergeable.

Exact-head Security Scan, CodeQL, and SAST Semgrep are terminal success; CI is still queued. Review conversations currently associated with the effective governance diff are resolved. Independent approving reviews and the complete protected-central coverage/review/package/fuzz/SBOM/provenance/dependency evidence are still required before merge.

No force update, destructive rebase, gate weakening, review dismissal, self-approval, or numerical psychometric change is used.

[coderabbitai]

📝 Walkthrough

Walkthrough

The pull request hardens observed-score DIF control validation, requires canonical Git source provenance for PR queue governance, adds regression coverage, wires the DIF safety layer into package exports, and records related release notes.

Changes

DIF control safety

Layer / File(s)	Summary
DIF control validation and documentation python/fast_mlsirm/_dif_control_safety.py, CHANGELOG.md, docs/changelog.d/958-logistic-dif-control-boundary.md, docs/doctoring/logistic-dif-control-safety.md	DIF scalar controls are validated without caller conversion hooks, normalized to native types, checked against native domains, and forwarded through idempotent wrappers.
DIF package wiring python/fast_mlsirm/__init__.py	Package initialization installs the wrappers and updates legacy DIF aliases.
DIF boundary regression coverage tests/test_logistic_dif_control_callback_safety.py, tests/test_logistic_dif_native_domain_compatibility.py	Tests cover hostile inputs, validation order, NumPy scalars, native limits, aliases, and installer idempotence.

PR queue provenance

Layer / File(s)	Summary
Canonical source commit resolution scripts/build_pr_queue_governance.py, docs/changelog.d/1146-pr-queue-source-commit-provenance.md	_source_commit now raises stable RuntimeError values for Git failures and invalid output and accepts only full lowercase SHA-1 or SHA-256 identities.
Source commit regression coverage tests/test_pr_queue_governance.py, tests/test_pr_queue_governance_git_timeout.py	Tests isolate Git access and cover operational failures, malformed identities, timeout behavior, and canonical SHA outputs.

Additional release notes

Layer / File(s)	Summary
Additional changelog entries CHANGELOG.md	The changelog records multilevel trend and AR(1) functionality, a hierarchical longitudinal Rasch estimator, and S-X² scalar-control hardening.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Merge Risk: 🔵 Low · up to 0c085

The change makes PR source provenance fail closed and accepts only canonical full commit identities, with the supplied tests passing. It is mergeable with owner awareness that the changelog citation should include a clickable DOI resolver link.

🚥 Pre-merge checks | ✅ 2 | ❌ 3

❌ Failed checks (3 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The governance implementation meets the provenance requirements in [#1146], including bounded Git execution, stable RuntimeError failures, canonical lowercase SHA-1/SHA-256 validation, and focused reg…	Remove unrelated DIF production code, DIF documentation, DIF tests, and changes to tests/test_pr_queue_governance.py. Retain only the governance source helper, tests/test_pr_queue_governance_git_timeout.py, and the #1146 changelog fragment,…
Out of Scope Changes check	⚠️ Warning	The PR includes changes unrelated to [#1146], including python/fast_mlsirm/_dif_control_safety.py, python/fast_mlsirm/init.py, DIF regression tests, docs/doctoring/logistic-dif-control-safety.md, …	Split the DIF control-safety implementation, documentation, and tests into a separate pull request. Remove those files and unrelated test changes from this pull request.
Docstring Coverage	⚠️ Warning	Docstring coverage is 53.85% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 65 functions across 7 files. (4 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: requiring reconstructable PR queue source commit provenance through governance validation.

Full details: Linked Issues check

Explanation

The governance implementation meets the provenance requirements in [#1146], including bounded Git execution, stable RuntimeError failures, canonical lowercase SHA-1/SHA-256 validation, and focused regression coverage. However, the PR also includes unrelated psychometric changes and exceeds the issue's stated three-file scope.

Resolution

Remove unrelated DIF production code, DIF documentation, DIF tests, and changes to tests/test_pr_queue_governance.py. Retain only the governance source helper, tests/test_pr_queue_governance_git_timeout.py, and the #1146 changelog fragment, unless the issue scope is explicitly expanded.

Full details: Out of Scope Changes check

Explanation

The PR includes changes unrelated to [#1146], including python/fast_mlsirm/_dif_control_safety.py, python/fast_mlsirm/init.py, DIF regression tests, docs/doctoring/logistic-dif-control-safety.md, and docs/changelog.d/958-logistic-dif-control-boundary.md. These changes violate the stated governance-only scope.

Full details: Docstring Coverage

Explanation

Docstring coverage is 53.85% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 65 functions across 7 files. (4 skipped: 4 unsupported.)

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/pr-queue-source-commit-provenance

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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