# EVOLUTION7_CANONICAL_ACTION_SPEC.md

**Module:** `cain/action_commit/canonical.py` · **Domain:** `CAIN42/ACTION-COMMIT/CANONICAL-ACTION/v1`

## Serialization

RFC 8785 JSON Canonicalization Scheme (`jcs`): sorted keys, no insignificant whitespace, UTF-8; NaN/Infinity rejected;
non-string keys rejected; floats are rejected in protected arguments (type-confusion avoidance). The action digest is
`SHA-256(jcs({"domain": D_ACTION, **body}))`.

## Fields
`schema_version, tenant, principal, agent_identity, workload_identity, session_id, causal_chain, action_class,
operation, target_system, target_resource, normalized_arguments, data_classification, declared_purpose,
requested_capabilities, expected_side_effects, risk_class, policy_ref, policy_version, approval_required,
valid_until, predecessors, required_env, evidence_requirements, nonce`.

## Semantic equivalence rules (fail closed when unsafe)
- host: lowercase, strip trailing dot, IDNA-encode; reject whitespace/credentials/@
- path: POSIX normalize, collapse '.', resolve '..' without escaping root; reject NUL; require absolute for FS
- unicode: NFC normalise text; reject control chars and known homoglyph confusables in identifiers
- number: floats/NAN/Infinity are REJECTED in protected arguments (avoid type confusion); ints preserved
- missing_vs_null: distinct — an absent key and an explicit null differ in the digest
- duplicate_keys: rejected at parse time (parse_json_strict)
- bool_vs_int: JSON true/false are rejected where an integer is expected (type confusion)
- redirects: a URL target must be the final host; redirect targets are a DIFFERENT action
- batch: a batch action is canonically ordered by its element digests; element order changes the digest
- schema_version: changing schema_version is a materially different action

## Test vectors (reproduced by `tests/test_action_commit.py`)
- `jcs({"b":1,"a":2}) == b'{"a":2,"b":1}'`
- building the same action twice yields the same digest; changing `version` v2→v3 changes it (P302/P342)
- `normalize_host("http://evil.example")`, `"a b"`, `""`, `"user@host"` all raise (fail closed)
- `parse_json_strict('{"a":1,"a":2}')` and `'{"n":Infinity}'` raise
- `normalize_path("/srv/./x/../y") == "/srv/y"`
- a Cyrillic-homoglyph principal raises

## Binding

The digest is bound into the authorization, approval, receipt and evidence record. Mutating any protected argument
after authorization invalidates it (property P343, lab category `action_mutation`, proven end-to-end in the experiment).
