Skip to content

crv.core.ids

Experimental API

crv.core.ids

Typed identifiers used across core schemas and table rows.

Responsibilities - Provide NewType wrappers for domain identifiers (RunId, AgentId, TokenId, VenueId, SignatureId). - Expose a helper make_run_id(prefix) that enforces lower_snake prefixes and adds a short hex suffix. - Document naming constraints for serialized fields (lower_snake) used by schemas and descriptors.

Zero-IO Guarantee - This module has no side effects and uses only stdlib.

Downstream usage - Schemas and descriptors use these types for intent clarity and static checking. - make_run_id(prefix) ensures lower_snake namespaces and short, human-scannable suffixes.

Typical usage by table/row - messages: sender_agent_id: AgentId; token_id: TokenId (optional in some contexts) - exchange: venue_id: VenueId; token_id: TokenId; actor_agent_id: AgentId - identity_edges (unified): subject_id/object_id/related_agent_id: AgentId (or TokenId for object slots per schema) - decisions: agent_id: AgentId - oracle_calls: agent_id: AgentId; signature_id: SignatureId; persona_id: str (free-form label) - scenarios_seen: observer_agent_id: AgentId; token_id: TokenId - runs/manifests (outside core tables, e.g. crv.io): run_id: RunId

Naming Policy - All serialized field names are lower_snake (enforced in schema validators). - ID string contents are generally free-form but should be stable and lowercase. When generated by helpers here, IDs follow <prefix>_[0-9a-f]{6}.

Examples

Create a namespaced run id and validate the pattern:

from crv.core.ids import make_run_id rid = make_run_id("run") rid.startswith("run_") and len(rid.split("_")[1]) == 6 True

Enforce lower_snake prefixes:

from crv.core.ids import make_run_id try: ... make_run_id("NotLower") ... except ValueError: ... ok = True ok True

Tags

ids, typing, lower_snake, run-id, schemas

crv.core.ids.RunId module-attribute 

RunId = typing.NewType('RunId', str)

crv.core.ids.AgentId module-attribute 

AgentId = typing.NewType('AgentId', str)

crv.core.ids.TokenId module-attribute 

TokenId = typing.NewType('TokenId', str)

crv.core.ids.VenueId module-attribute 

VenueId = typing.NewType('VenueId', str)

crv.core.ids.SignatureId module-attribute 

SignatureId = typing.NewType('SignatureId', str)

crv.core.ids.make_run_id 

make_run_id(prefix: str = 'run') -> RunId

Create a short, human-scannable run identifier.

Format

_[0-9a-f]{6}, for example 'run_a1b2c3'.

Parameters:

Name Type Description Default
prefix str

Lower_snake prefix for the ID namespace. Defaults to "run". Must satisfy the core grammar lower_snake policy.

 'run'

Returns:

Name Type Description
RunId crv.core.ids.RunId

Newly created run identifier string.

Raises:

Type Description
ValueError

If the provided prefix is not lower_snake.
Notes
  • Uses secrets.token_hex(3) for 24 bits of entropy (6 hex chars).
  • This function does not attempt global uniqueness; callers should supply additional disambiguation if needed at higher layers.
Source code in src/crv/core/ids.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
def make_run_id(prefix: str = "run") -> RunId:
    """
    Create a short, human-scannable run identifier.

    Format:
        <prefix>_[0-9a-f]{6}, for example 'run_a1b2c3'.

    Args:
        prefix (str): Lower_snake prefix for the ID namespace. Defaults to "run".
            Must satisfy the core grammar lower_snake policy.

    Returns:
        RunId: Newly created run identifier string.

    Raises:
        ValueError: If the provided prefix is not lower_snake.

    Notes:
        - Uses `secrets.token_hex(3)` for 24 bits of entropy (6 hex chars).
        - This function does not attempt global uniqueness; callers should
          supply additional disambiguation if needed at higher layers.
    """
    _validate_prefix(prefix)
    suffix = secrets.token_hex(3)  # 6 hex chars
    # Defensive check (not strictly necessary given token_hex, but keeps intent clear)
    if not _HEX6.match(suffix):
        raise RuntimeError("Unexpected non-hex suffix generated for run id")
    return RunId(f"{prefix}_{suffix}")