fix: project operation-aware rule rationale by result

[basauth]

Summary

Correct operation-aware per-rule evidence projection so that TraceRuleEvidence.reason_code and TraceRuleEvidence.explanation reflect each rule’s actual evaluation result rather than being copied unconditionally from the authored policy rule.

This change aligns basis-core with the evidence-provenance semantics established in:

basis-architecture/docs/architecture/operation-aware-evidence-provenance-semantics.md

It addresses one of the implementation mismatches discovered while developing the canonical end-to-end conformance coverage for the operation-aware authorization path.

Motivation

The existing trace assembly behavior copied a policy rule’s authored reason_code and explanation into TraceRuleEvidence regardless of whether that rule:

• matched;

• did not match;

• was skipped;

• encountered an evaluation error.

That behavior could incorrectly make a non-matching rule appear to have satisfied its authored authorization rationale.

The corrected projection semantics are:

Rule result | Evidence projection -- | -- matched | Preserve the authored reason_code and explanation exactly not_matched | Set reason_code and explanation to null skipped | Set reason_code and explanation to null error | Do not copy authored allow/deny rationale; use governed error evidence when available

The current evaluation pipeline does not provide separate governed rule-level error rationale, so error evidence currently projects null values rather than reusing authored policy text.

Changes

Trace assembly

• Added explicit projection logic based on the typed RuleResult.

• Replaced unconditional copying of authored rule rationale.

• Preserved deterministic, side-effect-free trace assembly.

• Preserved authored text exactly for matched rules.

Test coverage

Added focused tests proving:

• matched ALLOW rules preserve authored rationale;

• matched DENY rules preserve authored rationale;

• matched ALLOW evidence remains present when a matched DENY rule wins through deny precedence;

• non-matching ALLOW rules omit authored rationale;

• non-matching DENY rules omit authored rationale;

• skipped rules omit authored rationale;

• error rules never receive authored success or denial rationale;

• projection behavior is exhaustive and deterministic;

• rule ordering remains unchanged.

Updated canonical-shape tests to verify:

• matched evidence remains complete under deny precedence;

• default-deny evidence does not project rationale from a non-matching rule;

• aggregate outcomes and aggregate reason codes remain unchanged;

• top-level explanation behavior remains unchanged;

• bundle identity remains unchanged.

Roadmap

Updated the operation-aware implementation plan to record:

• the evidence-provenance reconciliation status;

• publication of corrected canonical fixtures in basis-schemas v0.2.2;

• completion of the basis-core rule-evidence projection correction;

• the remaining requirement to vendor and activate v0.2.2 before resuming the canonical-conformance PR.

Architectural Integrity

This PR does not change:

• rule matching;

• condition evaluation;

• condition operators;

• bundle applicability;

• candidate selection;

• deny precedence;

• default-deny behavior;

• NOT_APPLICABLE behavior;

• failure-reason classification;

• aggregate reason-code selection;

• top-level explanation behavior;

• bundle identity;

• response assembly;

• AuditEvidence assembly;

• enforcement disposition;

• public Python package exports;

• v0.1 authorization behavior.

No vendored schema fixtures, snapshot helpers, dependencies, or package metadata were changed.

Validation

• Focused trace and canonical-shape tests: 296 passed

• Operation-aware suite: 3082 passed, 86 skipped

• Full repository suite: 3846 passed, 86 skipped

• ruff check .: passed

• ruff format --check src tests: passed

• mypy src: passed

• git diff --check: passed

Files Changed

docs/implementation/basis-core-v0.2-operation-aware-plan.md
src/basis_core/evaluation/operation_aware/trace_assembly.py
tests/operation_aware/test_engine_canonical_shapes.py
tests/operation_aware/test_trace_assembly.py

Follow-Up

After this PR merges, the remaining prerequisite before resuming canonical end-to-end conformance is to vendor and activate the released basis-schemas v0.2.2 compatibility snapshot in basis-core.

The canonical-conformance PR and subsequent roadmap work remain separate.