Skip to content

crv.core.hashing

Experimental API

crv.core.hashing

Canonical JSON serialization and hashing helpers for core schemas.

Provides a single canonical JSON policy and SHA-256 helpers to ensure stable, order-insensitive serialization and hashing across runs and consumers. This module is zero-IO and uses only the Python standard library.

Notes
  • Canonical JSON:
    • sort_keys=True
    • separators=(",", ":")
    • ensure_ascii=False
  • Hashing is performed over the UTF-8 encoded canonical JSON string.
  • Used by core/tests/downstream packages to keep identifiers stable.
References
  • specs: src/crv/core/.specs/spec-0.1.md, spec-0.2.md

crv.core.hashing.json_dumps_canonical 

json_dumps_canonical(obj: typing.Any) -> str

Serialize an object to a canonical JSON string.

Parameters:

Name Type Description Default
obj typing.Any

JSON-serializable object.

 required

Returns:

Name Type Description
str str

Canonical JSON string with sort_keys=True, compact separators,
str

and ensure_ascii=False.
Notes

This function assumes the input is JSON-serializable and does not perform coercion of unsupported types.

Source code in src/crv/core/hashing.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
def json_dumps_canonical(obj: Any) -> str:
    """
    Serialize an object to a canonical JSON string.

    Args:
        obj (Any): JSON-serializable object.

    Returns:
        str: Canonical JSON string with sort_keys=True, compact separators,
        and ensure_ascii=False.

    Notes:
        This function assumes the input is JSON-serializable and does not perform
        coercion of unsupported types.
    """
    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)

crv.core.hashing.hash_row 

hash_row(row: collections.abc.Mapping[str, typing.Any]) -> str

Compute a stable hash for a row-like mapping by hashing its canonical JSON.

Parameters:

Name Type Description Default
row collections.abc.Mapping[str, typing.Any]

Row mapping (e.g., dict) to hash.

 required

Returns:

Name Type Description
str str

SHA-256 hex digest over the canonical JSON serialization.
Notes

Re-ordering keys in the mapping does not change the result.

Source code in src/crv/core/hashing.py 
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def hash_row(row: Mapping[str, Any]) -> str:
    """
    Compute a stable hash for a row-like mapping by hashing its canonical JSON.

    Args:
        row (Mapping[str, Any]): Row mapping (e.g., dict) to hash.

    Returns:
        str: SHA-256 hex digest over the canonical JSON serialization.

    Notes:
        Re-ordering keys in the mapping does not change the result.
    """
    return _sha256_hexdigest(json_dumps_canonical(dict(row)))

crv.core.hashing.hash_context 

hash_context(ctx_json: collections.abc.Mapping[str, typing.Any]) -> str

Hash a context-like mapping using canonical JSON and SHA-256 policy.

Parameters:

Name Type Description Default
ctx_json collections.abc.Mapping[str, typing.Any]

Context mapping to hash.

 required

Returns:

Name Type Description
str str

SHA-256 hex digest over the canonical JSON serialization.
Source code in src/crv/core/hashing.py 
76
77
78
79
80
81
82
83
84
85
86
def hash_context(ctx_json: Mapping[str, Any]) -> str:
    """
    Hash a context-like mapping using canonical JSON and SHA-256 policy.

    Args:
        ctx_json (Mapping[str, Any]): Context mapping to hash.

    Returns:
        str: SHA-256 hex digest over the canonical JSON serialization.
    """
    return _sha256_hexdigest(json_dumps_canonical(dict(ctx_json)))

crv.core.hashing.hash_state 

hash_state(agent_state: collections.abc.Mapping[str, typing.Any]) -> str

Hash an agent state mapping using canonical JSON and SHA-256 policy.

Parameters:

Name Type Description Default
agent_state collections.abc.Mapping[str, typing.Any]

Agent state mapping to hash.

 required

Returns:

Name Type Description
str str

SHA-256 hex digest over the canonical JSON serialization.

Examples:

>>> from crv.core.hashing import hash_state
>>> hash_state({"a": 1}) == hash_state({"a": 1})
True
Source code in src/crv/core/hashing.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
def hash_state(agent_state: Mapping[str, Any]) -> str:
    """
    Hash an agent state mapping using canonical JSON and SHA-256 policy.

    Args:
        agent_state (Mapping[str, Any]): Agent state mapping to hash.

    Returns:
        str: SHA-256 hex digest over the canonical JSON serialization.

    Examples:
        >>> from crv.core.hashing import hash_state
        >>> hash_state({"a": 1}) == hash_state({"a": 1})
        True
    """
    return _sha256_hexdigest(json_dumps_canonical(dict(agent_state)))