Skip to content

fix(baseline): centralize reconciliation semantics - #64

Merged
stacknil merged 5 commits into
mainfrom
stacknil/baseline-reconciliation
Aug 16, 2026
Merged

stacknil merged 5 commits into
mainfrom
stacknil/baseline-reconciliation

Conversation

@stacknil

Copy link
Copy Markdown
Owner

Summary

  • Introduce reconcile_baseline() as the sole semantic core for baseline matching, classification, current-finding consumption, and suppression decisions.
  • Make apply_baseline(), prune_baseline(), and audit_baseline() projection/compatibility adapters over the same reconciliation result.
  • Lock fail-closed ambiguity, exact-fingerprint priority, single consumption, digest equivalence, permutation invariance, and rule-version classification with cross-adapter tests.

Why

The previous baseline paths evaluated overlapping matching rules independently. In ambiguous relocation and many-baseline-to-one-current cases, that could suppress or retain findings without a unique assignment, and audit could count one current finding more than once.

Baseline machinery must never make a current finding disappear when the match is uncertain.

Design decision

Baseline Reconciliation is the authoritative domain abstraction. It resolves matching globally in decreasing strength: exact fingerprint, comparable content/location, rule-location, then legacy identity. A current finding can be consumed once. Ambiguous candidates are blocked from weaker matching but remain visible and unmatched.

Classification and suppression remain separate. rule_changed is exposed by audit while remaining suppressible; changed, stale, and ambiguous are not suppressible.

How to validate

PYTHONPATH=src python -m pytest -q
python -m ruff check .
python tests/validate_pre_commit_provider.py
actionlint
python -m build
python -m twine check dist/*

Local results:

  • 188 pytest tests passed.
  • Ruff and actionlint passed.
  • All four isolated pre-commit provider consumer hook variants passed.
  • sdist and wheel built; Twine metadata checks passed.
  • Wheel inspection confirmed repo_sentinel/baseline_matching.py is packaged.

Main risk

The intended compatibility change is stricter handling when multiple baseline entries claim the same current finding. Those entries now classify as ambiguous; apply keeps the current finding visible, prune does not retain it, and audit exposes each candidate set. This may surface findings that older matching suppressed.

Compatibility impact

  • Existing public apply_baseline, prune_baseline, and audit_baseline signatures and audit schema remain intact.
  • Reliable active, relocated, and rule_changed matches retain their suppression behavior.
  • Raw tokens and redacted SHA-256 evidence remain equivalent for content identity.
  • Stable sorting makes results independent of input order.

Rollback path

Revert the three commits in this PR. No baseline schema migration, persisted-data rewrite, release artifact, or external service change is involved.

Review state

Draft by policy because this changes baseline/security-boundary behavior. Do not merge until CI passes and the required delayed review window has elapsed.

@stacknil

stacknil commented Aug 15, 2026 •

Copy link
Copy Markdown
Owner Author

Post-CI final diff review

Reviewed all 6 changed files and all 5 commits against the refreshed origin/main after the latest required checks passed. The Ubuntu Ruff failure introduced by the pairwise-surface cleanup was an import-order issue; commit c101e57 fixes it, and the replacement Ubuntu/Windows Python 3.11-3.14 matrices are green.

  • Design decision: reconcile_baseline() is the only matching semantic core; apply, prune, and audit only project its decisions, and the legacy public pairwise helpers have been removed.
  • Main risk: fail-closed many-to-one or one-to-many reconciliation intentionally surfaces findings that older baseline matching could suppress or retain.
  • Compatibility impact: adapter signatures and audit schema are unchanged; reliable active, relocated, and rule-changed matches preserve suppression, including raw/redacted digest equivalence. The removed pairwise helpers were an internal bypass of the new global contract.
  • Rollback path: revert the five commits in this PR; there is no schema migration or persisted-data rewrite.

Final evidence: all latest GitHub checks pass, origin/main...HEAD is whitespace-clean, the branch is 5 commits ahead and 0 behind, and no bot/reviewer comments are outstanding. Additional state/performance hardening is isolated in stacked draft PR #65. This PR remains draft for the delayed security-boundary review window.

@stacknil
stacknil marked this pull request as ready for review August 16, 2026 14:52
@stacknil
stacknil merged commit 95bda2e into main Aug 16, 2026
23 checks passed
@stacknil
stacknil deleted the stacknil/baseline-reconciliation branch August 16, 2026 14:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant