feat(trace): add TRACE v0.2 trust record data model and session mapping (#3086)

[Imran Siddique (imran-siddique)]

Summary

Implements the data model layer for TRACE v0.2 Trust Records (ADR-0032, step 1 of 5). No signing, sinks, or wire transport yet -- those land in steps 2-5.

• trace_model.py -- TraceModelConfig, TraceSession, TrustRecord dataclasses + session_to_trust_record() mapping function
• appraisal.status -- set to "contraindicated" when any entry has outcome=="denied" or event_type in {"policy_violation", "tool_blocked"}; "affirming" otherwise
• tool_transcript.hash -- RFC 8785 JCS-canonical JSON hash per TRACE spec (sha256: prefix)
• PolicyInterceptor -- optional policy_bundle_hash param stored at load time; sink reads it at session close
• GovernedCallable -- computes _policy_bundle_hash from raw bundle bytes at policy load time
• governance/__init__.py -- exports the four new public symbols

Acceptance criteria

• TrustRecord dataclass with all 11 required TRACE v0.2 fields
• session_to_trust_record(session, config) -> dict mapping function
• PolicyInterceptor stores policy_bundle_hash at load time
• subject derived from session.agent_did (e.g. did:mesh:spiffe://...) -- no SPIFFE config needed (ADR-0032 v0.2)
• Unit tests: golden-path mapping, deny decision sets appraisal.status = "contraindicated", call_count counts only tool_invocation entries, transcript hash is deterministic

Test plan

• pytest agent-governance-python/agent-mesh/tests/governance/test_trace_model.py -v passes (10 test cases)
• No regressions in existing governance tests

References

• ADR-0032
• Closes [TRACE] TRACE model and field mapping (ADR-0032, step 1/5) #3086
• Next: [TRACE] EAT/JWT signing (ADR-0032, step 2/5) #3087 (signing step)

🤖 Generated with Claude Code

[github-actions]

🤖 AI Agent: code-reviewer — View details

AI-generated review output. Treat it as untrusted analysis and verify before acting.

TL;DR: 0 blockers, 1 warning. The implementation is solid, but a minor improvement is suggested for test coverage.

#	Sev	Issue	Where
1	Warn	Test coverage for edge cases is limited	test_trace_model.py

Action items:

• None.

Warnings:

#	Issue	Where	Follow-up?
1	Test coverage for edge cases is limited	test_trace_model.py	Fine as follow-up PR

No issues found. Clean change.

[github-actions]

🤖 AI Agent: breaking-change-detector — API Compatibility

AI-generated review output. Treat it as untrusted analysis and verify before acting.

API Compatibility

Severity	Change	Impact
High	Added TraceModelConfig, TraceSession, TrustRecord, and session_to_trust_record to the public API in governance/__init__.py.	Existing code relying on __all__ for imports may encounter issues if these new symbols conflict with existing ones.
High	Added _policy_bundle_hash attribute to PolicyInterceptor class in govern.py.	This change may break existing code if it relies on the internal structure of PolicyInterceptor or if it subclasses this class and does not account for the new attribute.
High	Modified the PolicyInterceptor constructor to compute and store _policy_bundle_hash.	This could affect any code that relies on the previous behavior of the constructor.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[github-actions]

🤖 AI Agent: test-generator — `agentmesh/governance/trace_model.py`

AI-generated review output. Treat it as untrusted analysis and verify before acting.

agentmesh/governance/trace_model.py

• test_empty_entries_iat_is_zero -- Validate that iat is set to zero when there are no audit entries.
• test_jcs_hash_deterministic -- Ensure _jcs_hash produces consistent hashes for identical input.
• test_invalid_audit_entry_handling -- Verify behavior when audit_entries contain invalid or malformed data.
• test_missing_required_fields -- Confirm error handling when required fields in TraceSession or TraceModelConfig are missing.

agentmesh/governance/govern.py

• test_policy_bundle_hash_computation -- Validate that _policy_bundle_hash is correctly computed for all policy input types.
• test_empty_policy_bundle -- Ensure _policy_bundle_hash is empty when no policy bundle is provided.
• test_invalid_policy_type -- Confirm TypeError is raised for unsupported policy types.

[github-actions]

🤖 AI Agent: security-scanner — View details

AI-generated review output. Treat it as untrusted analysis and verify before acting.

No security issues found.

[github-actions]

🤖 AI Agent: docs-sync-checker — Docs Sync

AI-generated review output. Treat it as untrusted analysis and verify before acting.

Docs Sync

• TraceModelConfig, TraceSession, TrustRecord, and session_to_trust_record() in trace_model.py -- missing docstrings
• README.md -- no updates for new TRACE v0.2 Trust Record model and session mapping
• CHANGELOG.md -- missing entry for new TRACE v0.2 Trust Record data model and session mapping changes

[github-actions]

PR Review Summary

Check	Status	Details
🔍 Code Review	⚠️ Missing	No current-run comment
🛡️ Security Scan	⚠️ Missing	No current-run comment
🔄 Breaking Changes	⚠️ Missing	No current-run comment
📝 Docs Sync	⚠️ Missing	No current-run comment
🧪 Test Coverage	⚠️ Missing	No current-run comment

Verdict: ⚠️ AI review incomplete; ready for human review

AI review comments are untrusted advisory output. The summary reports workflow-generated completion status only, not model-authored pass/fail claims.