Action Reference: A Deterministic Identifier for Agent Actions

3.1. Preimage Fields

The preimage is a JSON object containing exactly four fields:¶

The four fields are REQUIRED. No additional fields enter the preimage. Optional fields in the receipt envelope (Section 4) do not affect the action_ref value.¶

3.2. Serialization

The four fields MUST be serialized using RFC 8785 JSON Canonicalization Scheme (JCS) before hashing:¶

• Keys in lexicographic Unicode code point order: action_type, agent_id, scope, timestamp.¶
• No whitespace between tokens.¶
• UTF-8 encoded.¶
• Values are JSON strings (standard JSON escaping only).¶

The resulting JCS payload for a conformant implementation will sort keys in this order: action_type < agent_id < scope < timestamp.¶

Implementations using the simple json.dumps approach (Python, Node.js) produce RFC 8785-compatible bytes for inputs within the safe band: ASCII-only field values, conformant RFC 3339 timestamps, no surrogate-pair Unicode. For inputs outside this band, implementations MUST use an RFC 8785-compliant library.¶

3.3. Hash Function

action_ref = SHA-256(JCS(preimage)), encoded as lowercase hexadecimal.¶

The output is a 64-character lowercase hex string (256 bits / 32 bytes). Uppercase hex is non-conformant.¶

3.4. Timestamp Format

The timestamp field MUST conform to the following format constraints:¶

• Timezone: "Z" suffix only. "+00:00" or any other offset representation is non-conformant.¶
• Fractional precision: exactly 3 digits (milliseconds). No trailing zero suppression. ".000" is conformant; ".0" is not.¶
• Template: YYYY-MM-DDTHH:MM:SS.mmmZ — one valid byte sequence per instant.¶

These constraints close the [RFC3339] underspecification surface. RFC 3339 admits multiple lexically distinct encodings of the same instant that produce different SHA-256 digests under JCS. This specification closes that surface at the format level.¶

Implementations holding epoch-millisecond integers MUST convert to the conformant RFC 3339 string before hashing. Implementations that hash the epoch-ms integer directly are not conformant.¶

The W3C CG ai-agent-protocol discussion (issue #34) established epoch-millisecond integer as an application-layer representation. This specification uses the RFC 3339 string form in the preimage. The two representations are not interchangeable in the preimage — they produce different digests.¶

3.5. Derivation Example

The following example is byte-verified in the conformance suite (vector "nexus-oracle-signal"):¶

Input:
  agent_id    = "nexus-agent-xa12.onrender.com"
  action_type = "oracle.signal"
  scope       = "BTC"
  timestamp   = "2025-05-18T11:40:31.000Z"

JCS payload:
  {"action_type":"oracle.signal","agent_id":"nexus-agent-xa12.on
  render.com","scope":"BTC","timestamp":"2025-05-18T11:40:31.000Z"}

SHA-256:
  fdd7f810499f06be24355ca8e2bfb8c4b965cc80c838f41fa074683443d89f5a

4.1. Required Fields

Implementations that emit a receipt referencing this specification SHOULD include the following fields to ensure long-lived verifiability:¶

{
  "packet_version": "1.0",
  "action_ref": "<sha256 hex>",
  "hash_algo": "sha256",
  "preimage_format": "jcs-rfc8785-v1",
  "preimage": {
    "agent_id": "...",
    "action_type": "...",
    "scope": "...",
    "timestamp": "2026-05-15T10:00:00.123Z"
  }
}

packet_version:

Forward-compatibility anchor. v1 verifiers can explicitly reject unknown versions rather than fail silently.¶

hash_algo:

Makes receipts self-describing. If a future implementation switches hash functions, receipts issued before the change remain replayable.¶

preimage_format:

Unambiguously identifies the serialization. Any verifier can recompute action_ref from the preimage fields using RFC 8785 without trusting the emitter.¶

4.2. Optional Fields for Rotation Auditability

The canonical receipt envelope v1.0 records state at the moment the action was claimed. It does not record whether that state was still valid when the action was admitted for execution. Two failure modes this gap creates:¶

1. Trust tier degradation: an agent moves from TRUSTED to WATCH between claim and execution. The anchor records the claim-time state. A verifier replaying the receipt cannot determine from the receipt alone whether the agent was still trusted when the action was admitted.¶
2. Policy rotation: the counterparty policy changes between issuance and execution. A counterparty_policy_hash field proves which policy was referenced at claim time, but does not prove whether that policy was still current at admission.¶

Three optional fields close this gap:¶

policy_version (string, OPTIONAL):

Identifies which version of the governing policy was in force when the action was admitted. Distinct from counterparty_policy_hash, which proves which policy was referenced — policy_version proves whether it was still current at execution time.¶

authority_verified_at_ms (integer, OPTIONAL):

Unix timestamp in milliseconds at which the delegation authority was verified at issuance. Records when the acting agent's authority was confirmed before the action was admitted.¶

revocation_check_at_ms (integer, OPTIONAL):

Unix timestamp in milliseconds of the last non-revocation check performed before execution. Establishes a maximum window of credential exposure. A receipt without this field cannot prove the agent's credentials were valid immediately before the action was admitted.¶

A verifier that requires post-rotation auditability SHOULD treat a receipt missing either field as unauditable for the rotation window — not as invalid.¶

The millisecond precision for revocation_check_at_ms is REQUIRED. Credential checks in live multi-agent systems happen at sub-second granularity. Systems that only have second-precision timestamps SHOULD multiply by 1000 and document the precision loss.¶

Note: the three optional fields in this section correspond to the "freshness" verification layer described in discussions on the agntcy/identity repository (issue #165). A verifier confirming offline signature integrity (integrity), checking that the executed scope sat within the delegated scope (authority), and establishing the key validity window at decision time (freshness) needs all three layers. The fields in this section address the freshness layer; the authorization_ref in Section 5 addresses the authority layer.¶

5.1. Layer Model

action_ref is the correlation key across a three-record trail:¶

1. Pre-execution record: the commitment before the action is taken. Contains the action_ref preimage fields and authorization_ref.¶
2. Decision record: the authorization event. Contains authorization_ref as its identifier and action_ref as the correlation key.¶
3. Receipt: the post-execution record. Contains action_ref and authorization_ref; verifier checks both against the pre-execution record.¶

A conformant verifier runs four independent checks across the trail:¶

A trail that passes the first three checks but fails the fourth proves that execution proceeded under a different approval than the one recorded in the pre-execution entry.¶

5.2. authorization_ref Derivation

authorization_ref is the identifier for the Decision record:¶

authorization_ref = SHA-256(JCS({
  "action_ref":       "<sha256 hex>",
  "authorized_scope": "<scope string>",
  "decision_ts":      <epoch-ms integer>,
  "policy_id":        "<policy identifier>"
}))

JCS lexicographic key order: action_ref, authorized_scope, decision_ts, policy_id. Note: decision_ts is an epoch-millisecond integer, not an RFC 3339 string.¶

Invariants:¶

• action_ref is embedded in the preimage. A verifier can confirm the decision was not reused across action instances.¶
• Recomputable without operator cooperation from the four decision record fields.¶
• MUST appear in both the pre-execution record and the receipt.¶
• The signer of the Decision record MUST be independent of the actor/executor whose action it authorizes. A party recomputing and certifying an existing signed record after the fact (referee role) does not satisfy this — the signer of record must be independent BEFORE the outcome is final, not verifying it afterward.¶

5.3. Canonical Linking Key

The same action_ref is computable from artifacts produced by independent systems using the same four-field derivation:¶

• A Mycelium TrailRecord (preimage fields published in each record).¶
• A Nobulex covenant receipt (action_type as semantic label + timestamp + agent_id + scope).¶
• A SafeAgent claim (joint spec argentum-core issue #7).¶
• A CrewAI idempotency key (crewAI PR #5822 — key derivation converges on this primitive from the retry-deduplication direction).¶
• NEXUS oracle receipts (implements canonical envelope v1.0).¶

Any verifier holding one artifact can validate against another without trusting either system.¶

8.1. Instrumentation Point

The correct instrumentation point is the authorization gate's evaluation operation: the component that receives the intent tuple, applies policy, and returns a decision (allow, deny, warn, escalate, or transform).¶

Implementations MUST NOT derive action_ref at the invoking agent's span level. Agent-level instrumentation does not have access to the complete intent tuple (agent_id, action_type, scope, timestamp) as presented to the gate. A hash computed from partial or reconstructed inputs is not conformant and will not verify against independently derived values.¶

The gate SHOULD derive action_ref before returning the verdict, so that the value is available for inclusion in the evaluation record at the moment of decision. The derivation requires no network call or external state: it is a local SHA-256 of the JCS-serialized preimage.¶

8.2. Attribute Placement

When the gate's evaluation operation is recorded as a telemetry span or structured event, action_ref SHOULD be included as a string attribute. The gate sets this attribute from the preimage fields, not from the returned decision object or any downstream record.¶

Downstream components that reference the same action (e.g., a payment receipt, an audit log entry, or a screening record) MAY carry action_ref as a correlation attribute. When a downstream span includes action_ref, the value MUST be the 64-character lowercase hex string derived by the gate for that evaluation. Re-deriving the value from a different preimage is not permitted: only the gate holds the authoritative preimage at decision time.¶

8.3. Cross-Producer Correlation

Because action_ref is derived deterministically from a fixed preimage, independent components that participate in the same authorized action can produce the same value without coordination. A policy gate, a screening component, and an audit service each derive the same action_ref from the same four fields, independently and without shared session state.¶

This property enables a verifier to correlate telemetry records across producers without trusting any single emitter. A monitoring system that receives evaluation events from multiple authorization components can join them on action_ref without relying on an operator-provided correlation key. The join is verifiable: any party holding the preimage fields can recompute the key and confirm the association.¶

When multiple components record the same action_ref in the same telemetry pipeline, the set of matching records constitutes an independently verifiable trace of the action across system boundaries.¶

9.1. Replay Attack Surface

action_ref is deterministic: the same four preimage field values always produce the same identifier. This is a design property — it enables cross-system correlation without operator trust. The implication is that action_ref alone does not prevent replay.¶

Replay protection requires the receipt to carry:¶

• authorization_ref (Section 5.2): binds the identifier to a specific authorization decision. A replayed action_ref with a different authorization decision will fail check 4.¶
• signing-trust-ref-v1: an operator-independent signature over the full receipt envelope. An attacker cannot substitute a different receipt without invalidating the signature.¶

A verifier that checks action_ref alone (without authorization_ref and signature) cannot detect replay. This specification requires both fields for complete replay resistance.¶

9.2. Scope Injection

If scope is not validated at emission time, an adversary can inject a scope string that differs from the actual intent. The action_ref will be a valid hash of the injected scope, not of the actual action. Verifiers SHOULD require that scope is provided by the executing agent, not derived or transformed by an intermediary system.¶

9.3. Timestamp Manipulation

A non-conformant timestamp (wrong precision, wrong timezone suffix, epoch-ms instead of RFC 3339 string) produces a different digest. This can be used to generate action_refs that appear valid but cannot be independently recomputed by a conformant verifier. Implementations MUST validate timestamp format at emission time, not only at verification time.¶

9.4. Operator-Independence Guarantee

The operator-independence property holds only if:¶

1. The four preimage fields are disclosed to verifiers.¶
2. The hash function and serialization are public and deterministic.¶
3. No field in the preimage is derived from an operator-controlled system without disclosure.¶

An emitter that uses a non-public agent_id (e.g., a UUID assigned by an internal sequencer and not disclosed) breaks the verifiability property: a verifier cannot recompute action_ref without retrieving the agent_id from the operator. Implementations MUST use stable, publicly disclosed agent identifiers.¶

The operator-independence property can be satisfied in two distinct ways, and implementers SHOULD state which one applies. In the internally-consistent case, the verifier's own recomputation of action_ref from the disclosed preimage fields is sufficient: the digest either matches or it does not, and no party external to the emitter and the verifier needs to attest to anything. In the externally-witnessed case, byte recomputation alone does not close the loop — the property also depends on a step that could not have been skipped or backdated by the operator, such as a timestamp or inclusion proof from a system the operator does not control (e.g. an on-chain anchor, or a SCITT receipt as described in Section 10). This is not an additional preimage field: it is a statement about how conformance to this section is established, not about what is hashed.¶

A.1. Positive Conformance Vector

Vector: nexus-oracle-signal (action-ref-v1-baseline)

agent_id    = "nexus-agent-xa12.onrender.com"
action_type = "oracle.signal"
scope       = "BTC"
timestamp   = "2025-05-18T11:40:31.000Z"

JCS payload (UTF-8):
{"action_type":"oracle.signal","agent_id":"nexus-agent-xa12.on
render.com","scope":"BTC","timestamp":"2025-05-18T11:40:31.000Z"}

action_ref:
fdd7f810499f06be24355ca8e2bfb8c4b965cc80c838f41fa074683443d89f5a

A.2. Negative Conformance Vector — Epoch-Integer Timestamp

Vector: neg-b01-epoch-integer (recompute-drift-v1)

Same action as A.1, but timestamp hashed as epoch-ms integer
instead of RFC 3339 string. Produces a different digest.

Non-conformant preimage (epoch-ms as integer — DO NOT USE):
{"action_type":"oracle.signal","agent_id":"nexus-agent-xa12.on
render.com","scope":"BTC","timestamp":1747568431000}

A verifier recomputing from the RFC 3339 string will obtain
a different hash and correctly reject the receipt.

A.3. authorization_ref Vector

Vector: step_2b_authorization_ref (guardrail-provider-v1)

action_ref       = "104812928eb50e0e1ad28f379f8ade03ea0f479ac7abd1b
                    bf9205e9317665c7f"
authorized_scope = "autogen:guardrail"
decision_ts      = 1749513600000
policy_id        = "guardrail-policy-v1"

JCS payload:
{"action_ref":"104812928eb50e0e1ad28f379f8ade03ea0f479ac7abd1bbf920
5e9317665c7f","authorized_scope":"autogen:guardrail","decision_ts":
1749513600000,"policy_id":"guardrail-policy-v1"}

authorization_ref:
b9f8494a4a5943687d105769556be2963271e37f2216d2afd279e5b260261327