feat: add operation-aware audit evidence model

[basauth]

Summary

Implement the operation-aware AuditEvidence model published by basis-schemas v0.2.1.

AuditEvidence is the bounded kernel-side evidence record associated with one operation-aware authorization evaluation.

This PR adds the model and contract validation only. It does not add assembly, persistence, enforcement, or gateway behavior.

Architecture

The model is implemented under:

src/basis_core/audit/operation_aware/audit_evidence.py

The audit layer legally consumes:

domain
decisions

The model reuses:

• OperationAwareEvaluationStatus
• OperationAwareDecisionOutcome
• OperationAwareFailureReason
• ReasonCode
• IdentityEvidenceReference
• AdapterEvidenceReference

The audit package does not import:

evaluation
policy
enforcement
adapters

A recursive import-boundary test now explicitly protects the audit → evaluation prohibition.

Model Responsibilities

AuditEvidence records bounded kernel evidence including:

• caller-supplied evidence identity;
• request identity;
• evaluation status;
• required-nullable outcome;
• required-nullable failure reason;
• optional bundle identity;
• contract-bounded matched rule identifiers;
• optional typed identity-evidence reference;
• optional typed adapter-evidence reference;
• caller-supplied recording timestamp.

The model does not contain:

• a complete request;
• policy rules or bundles;
• raw identity claims;
• tokens or credentials;
• raw protocol payloads;
• trace details;
• gateway enforcement facts;
• arbitrary metadata;
• persistence state.

Evaluation-State Invariants

Completed evaluations require:

evaluation_status = completed
outcome = allow | deny | not_applicable
failure_reason = null

Failed evaluations require:

evaluation_status = failed
outcome = null
failure_reason = a governed non-null failure value

Contradictory states are rejected.

A failed evaluation is not converted into an authorization denial.

Recorded Timestamp

recorded_at is:

• required;
• timezone-aware;
• supplied by the caller;
• deterministic;
• never generated through a clock or default factory.

The model introduces no time, UUID, randomness, filesystem, network, or process-state dependency.

Matched Rules

matched_rule_ids is validated according to the published contract.

When supplied, it is:

• non-empty;
• unique;
• bounded;
• order preserving.

The model does not calculate, sort, or derive rule identifiers.

Assembly remains later work.

Evidence References

Identity and adapter evidence use the existing typed reference models.

The audit record never embeds:

• raw JWTs;
• cookies;
• passwords;
• full claim sets;
• device credentials;
• BACnet packets;
• Modbus frames;
• OPC UA values;
• unredacted adapter payloads.

Unknown and out-of-contract fields are rejected.

Serialization

The model uses composable wrapped serialization so required-nullable contract keys remain present under:

exclude_none=True

Coverage includes:

• direct dictionary serialization;
• direct JSON serialization;
• nested dictionary serialization;
• nested JSON serialization;
• explicit include;
• explicit exclude.

Explicit caller exclusions remain authoritative and excluded fields are not reintroduced.

Contract Conformance

The model validates every published AuditEvidence example in the vendored basis-schemas v0.2.1 contract:

valid examples:   6 accepted
invalid examples: 20 rejected

All five canonical expected audit-evidence artifacts also construct successfully:

• allow basic;
• deny precedence;
• default deny;
• not applicable;
• invalid policy bundle.

The invalid-policy-bundle artifact correctly uses:

failure_reason = policy_validation_failure

No replacement reason code is invented.

Compatibility

This PR does not modify:

• v0.1 AuditEvent;
• v0.1 AuditWriter;
• OperationAwareDecisionResponse;
• EvaluationTrace;
• OperationAwareEvaluationEngine;
• policy behavior;
• response or audit assembly;
• enforcement behavior;
• vendored schemas or fixtures;
• stable public exports.

No persistence API, writer protocol, storage backend, or delivery mechanism is added.

Roadmap Boundary

This PR implements only the AuditEvidence model.

Remaining work stays separate:

PR 31:
    response and audit-evidence assembly

PR 32:
    response, trace, and audit agreement tests

PR 35:
    public API stabilization

Validation

• focused AuditEvidence tests: 221 passed
• published valid examples: 6 passed
• published invalid examples: 20 passed
• canonical expected audit artifacts: 5 passed
• full repository suite: 3,540 passed, 86 skipped
• Ruff lint: passed
• Ruff formatting: passed
• mypy strict validation: passed
• git diff --check: passed