Package com.tnsai.accountability

Record Class AgentLiabilityRecord

java.lang.Object
java.lang.Record
com.tnsai.accountability.AgentLiabilityRecord
Record Components:
agentId - stable id from AgentPrincipal.id()
agentVersion - version stamp from AgentPrincipal.version(); changes when the agent's behaviour changes
invokedAt - wall-clock instant the action started
action - typed descriptor — see Action
scope - the AuthorityScope in force at invocation
liability - severity tier — see LiabilityClass
correlationId - shared id linking this record to broader observability (an OTel trace id, an LLMCallLog entry, the wider transaction)
outcome - post-action result hash or error message; empty when the action is still in flight
signature - optional cryptographic signature; populated when the issuing AgentPrincipalProvider is signing each record
public record AgentLiabilityRecord(String agentId, String agentVersion, Instant invokedAt, Action action, AuthorityScope scope, LiabilityClass liability, String correlationId, Optional<String> outcome, Optional<byte[]> signature) extends Record
Append-only audit record produced for every agent action (TNS-298). Pairs a verifiable agent identity with the action it took, the scope it had, and the outcome.

Append-only contract

Records are immutable after creation — no edits, no deletes. The LiabilitySink stores them as a write-once log; auditors trust that a record they read today is identical to the one written at invokedAt. Implementations that can't enforce this (e.g. an in-memory sink) document the limitation explicitly.

Identity vs. observability

The framework already ships rich observability (LLMCallLog, OpenTelemetry spans, hook events). This record is the accountability view — short, audit-friendly, signed when possible. Auditors join it with observability data via correlationId when they need full call detail.
Since:
0.10.0 (TNS-298)

  • Constructor Details

    • AgentLiabilityRecord

      public AgentLiabilityRecord(String agentId, String agentVersion, Instant invokedAt, Action action, AuthorityScope scope, LiabilityClass liability, String correlationId, Optional<String> outcome, Optional<byte[]> signature)
      Creates an instance of a AgentLiabilityRecord record class.
      Parameters:
      agentId - the value for the agentId record component
      agentVersion - the value for the agentVersion record component
      invokedAt - the value for the invokedAt record component
      action - the value for the action record component
      scope - the value for the scope record component
      liability - the value for the liability record component
      correlationId - the value for the correlationId record component
      outcome - the value for the outcome record component
      signature - the value for the signature record component

  • Method Details

    • withSuccess

      public AgentLiabilityRecord withSuccess(String resultHash)
      Build a successful-outcome record. Convenience for the common "the action ran, here's the result hash" path.

    • withFailure

      public AgentLiabilityRecord withFailure(Throwable t)
      Build a failure-outcome record. Convenience for "the action failed, here's the error class + message" path. Auditors get a record either way — failures are the most important signal.

    • signatureCopy

      public Optional<byte[]> signatureCopy()
      Defensive copy of the signature bytes — mutations to the returned array don't affect the underlying record.
      Returns:
      empty when no signature was attached

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with Objects::equals(Object,Object).
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • agentId

      public String agentId()
      Returns the value of the agentId record component.
      Returns:
      the value of the agentId record component

    • agentVersion

      public String agentVersion()
      Returns the value of the agentVersion record component.
      Returns:
      the value of the agentVersion record component

    • invokedAt

      public Instant invokedAt()
      Returns the value of the invokedAt record component.
      Returns:
      the value of the invokedAt record component

    • action

      public Action action()
      Returns the value of the action record component.
      Returns:
      the value of the action record component

    • scope

      public AuthorityScope scope()
      Returns the value of the scope record component.
      Returns:
      the value of the scope record component

    • liability

      public LiabilityClass liability()
      Returns the value of the liability record component.
      Returns:
      the value of the liability record component

    • correlationId

      public String correlationId()
      Returns the value of the correlationId record component.
      Returns:
      the value of the correlationId record component

    • outcome

      public Optional<String> outcome()
      Returns the value of the outcome record component.
      Returns:
      the value of the outcome record component

    • signature

      public Optional<byte[]> signature()
      Returns the value of the signature record component.
      Returns:
      the value of the signature record component