Package com.tnsai.accountability

Interface ReputationLedger

All Known Implementing Classes:

InMemoryReputationLedger

public interface ReputationLedger

Reputation oracle derived from AgentLiabilityRecord history (TNS-298). Surfaces "is this agent trustworthy?" to gating logic (multi-agent orchestrators, payment brokers, scope issuers) without forcing the caller to walk audit records every time.

Implementations

• InMemoryReputationLedger — derives directly from a LiabilitySink on every query; default, fine for fleets with manageable record volume.
• External impls cache scores against a TTL or maintain a streaming aggregate; the SPI is narrow on purpose.

Score policy

Each implementation owns its weighting policy — what counts as a "miss" (out-of-scope action? failed outcome? both?) and how LiabilityClass weighs into the aggregate. The framework's default ledger uses simple "pass / fail" counting with class-weighted misses. Custom ledgers swap in domain-specific scoring (insurance underwriters use a different model than internal multi-agent orchestrators).

Since:

0.10.0 (TNS-298)

Method Summary

Modifier and Type	Method	Description
List<AgentLiabilityRecord>	historyOf(String agentId, Duration window)	Records that contributed to scoreOf(java.lang.String), scoped to the trailing window.
ReputationScore	scoreOf(String agentId)	Aggregate reputation for agentId.

Method Details

scoreOf

ReputationScore scoreOf(String agentId)

Aggregate reputation for agentId. Returns ReputationScore.unknown(java.lang.String, java.time.Instant) for agents the ledger has no records on (innocent-until-proven default).

Throws:

NullPointerException - if agentId is null

historyOf

List<AgentLiabilityRecord> historyOf(String agentId,
 Duration window)

Records that contributed to scoreOf(java.lang.String), scoped to the trailing window. Useful for "show me what dropped this agent's score in the last hour" operator queries; auditors typically prefer the underlying LiabilitySink.query(com.tnsai.accountability.AuditQuery) directly for unbounded ranges.

Throws:

NullPointerException - if any arg is null

IllegalArgumentException - if window is non-positive