Canonical Action Representation (CAR)

To get deterministic, auditable decisions, every action must have a stable identity: the same logical action must always produce the same hash. That is what Canonical Action Representation (CAR) and canonicalization are for. The normative definition is in the Faramesh Core Specification v1.0 (DOI: 10.5281/zenodo.18371591) §4 (CAR fields, canonicalization rules, canonical serialization) and §5 (request_hash, hash stability). This document summarizes the concept, schema, normalization, and use in provenance and replay.

Why canonicalize?

• Audit integrity — Logs and Merkle chains refer to actions by hash. If the same action could produce different hashes (e.g. key order, whitespace, float formatting), you couldn’t deduplicate or prove “this decision was for that action.”

• Replay — Re-evaluating a historical decision requires feeding the same action (or its hash) back into the policy engine. Same canonical form ⇒ same hash ⇒ deterministic replay.

• Permits and provenance — When a permit or a Decision Provenance Record (DPR) references an action, it uses the canonical hash so the binding is unambiguous.

So: one logical action ⇒ one canonical form ⇒ one hash.

CAR schema (Core Spec §4)

The Faramesh Core Spec v1.0 defines CAR as a JSON object with exactly these top-level keys (in canonical form):

• agent_id (string)

• tool (string)

• operation (string)

• params (object)

• context (object; default {} if missing)

No derived fields (id, timestamps, status, hashes, etc.) are included in CAR. Params and context are recursively key-sorted for canonical serialization. The spec also defines key normalization (e.g. alias op → operation; if both present the server MUST reject with 400), type normalization (params and context must be objects), and string trimming for agent_id, tool, operation.

Canonicalization rules

To get a single canonical form:

1. Field ordering — Serialize with keys in lexicographic order (e.g. JSON object keys sorted).

2. No whitespace — No extra spaces or newlines between tokens (compact JSON).

3. Encoding — UTF-8, no BOM.

4. Normalization by type:

   • Paths — Resolve . and .., expand ~, normalize separators to /, collapse repeated slashes.

   • Domains — Lowercase, strip trailing dot, default ports (80/443) removed.

   • Floats — Deterministic format (e.g. no exponent for integers, fixed precision); 1.0 and 1.00 must map to the same representation.

   • Timestamps — ISO 8601 UTC with fixed millisecond format.

   • Arrays — Sorted lexicographically if they contribute to identity; deduplicated where required by spec.

Details can vary by implementation; the important point is that the algorithm is fixed and deterministic so that hashes are stable across time and environments.

Hashing procedure

1. Prepare — Remove any “hash” field from the CAR (it’s output, not input).

2. Normalize — Apply the rules above to every field that participates in identity.

3. Serialize — Produce a single string (e.g. canonical JSON with sorted keys, no extra whitespace).

4. Hash — SHA-256 of the string; often stored as sha256:<hex>.

The result is the request_hash (Horizon/API) or car_hash (Guard/OpenClaw). Same input ⇒ same hash.

Identity vs metadata

Some implementations hash only identity fields (tool, operation, target, params, scope, risk tags) so that the same “what” always has the same hash even if agent_id or session_id changes. Others include all fields for simplicity. Faramesh’s behavior is documented in the API and SDK; the principle is: whatever is included in the canonical form must be deterministic and consistently normalized.

Use in provenance and replay

• Provenance — Decision Provenance Records (DPR) store the canonical_action_hash (or equivalent) so each decision is tied to a unique action identity. The Merkle chain and proof API use this.

• Replay — POST /v1/replay (or equivalent) takes a canonical hash (and optionally policy/state overrides) and re-runs the decision. Same hash ⇒ same canonical action ⇒ comparable outcome.

So CAR and canonicalization are the foundation for both audit and replay.

Summary

• CAR = a normalized, structured representation of an action so it has a single identity.

• Canonicalization = deterministic rules (field order, path/domain/float/timestamp normalization) so the same action always yields the same serialized form.

• Hash = SHA-256 of that form (e.g. request_hash / car_hash), used in logs, permits, DPRs, and replay.

• Provenance and replay depend on this so decisions are verifiable and re-evaluable.

For the full Guard v1 CAR schema and detailed normalization tables, see the Guard spec (CAR-schema.json, canonicalization.md) where applicable. For how the execution gate uses this, see Execution gate and Cryptographic provenance.