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.¶

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. 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.¶

8.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.¶

8.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.¶

8.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.¶

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