Identity

Two clients that disagree on identity do not share a brain at all. So identity is the part of the protocol this SDK implements rather than delegates, and the part the paper leaves open that an SDK cannot.

Canonical serialization

The canonical form is JCS (RFC 8785), tagged in every envelope so it stays versionable:

from boltzmann.identity.serialization import SERIALIZATION_ID

SERIALIZATION_ID
# 'jcs/1'

Chosen over a binary encoding because a block is a small record and the protocol targets several languages: a canonical form a human can read and grep beats compactness here. Canonicalization erases the order a mapping was built in, which is what makes block_id a function of the content and nothing else:

a = SemanticBlock(kind=SemanticKind.FACT, label="x", statement="y")
b = SemanticBlock(statement="y", label="x", kind=SemanticKind.FACT)

a.block_id == b.block_id   # True

Values a payload refuses

Floats and unsafe integers are refused inside a payload. A float fails at construction, not at commit.

from boltzmann.exceptions import NonDeterministicValueError
from boltzmann.identity.serialization import MAX_SAFE_INTEGER

MAX_SAFE_INTEGER   # 2**53 - 1

JCS defines float serialization through ECMAScript rules that are hard to reproduce identically across languages, and integers outside the IEEE-754 safe range lose precision in any double-backed JSON parser. Either divergence would mean two conforming clients computing different block_id values for the same knowledge — which is the one failure the protocol cannot tolerate. If you need a number with a fraction, store it as a string or as a scaled integer and say which in the payload.

Three levels of hashes are three types

None is a str, and none is interchangeable with another.

Type	Answers	Computed over
`BlockId`	Is this the same knowledge?	A block’s canonical serialization
`MerkleRoot`	Is this the same version?	A module’s composition
`OciDigest`	Do I already have these bytes?	A published blob or manifest

from boltzmann import BlockId, MerkleRoot, OciDigest

block_id = BlockId.of(canonical_bytes)
block_id.algorithm     # 'sha256'
block_id.hex
block_id.short         # 'sha256:47ab4fe22b2d' -- for logs and error messages
block_id.raw           # the raw digest bytes, as Merkle hashing consumes them

Offering one level where another is expected is refused, not coerced:

from boltzmann.exceptions import DigestKindError

BlockId.parse("sha256:...")     # fine
BlockId.parse(some_merkle_root) # DigestKindError

That distinction matters in practice. Two clients that packed the same blocks with different gzip settings have different layer digests and the same Merkle root: the OciDigest says the bytes differ, the MerkleRoot says the knowledge does not.

Hashing primitives

from boltzmann.identity.hashing import ALGORITHM, LEAF_PREFIX, NODE_PREFIX, hash_leaf, hash_node

ALGORITHM       # 'sha256'
LEAF_PREFIX     # b'\x00'
NODE_PREFIX     # b'\x01'

The domain-separating prefixes are what stop a leaf hash from being replayed as an internal node — see Merkle DAGs.

Timestamps

from boltzmann import utc_timestamp

utc_timestamp()

One function, always UTC, so two clients recording the same event do not disagree about when it happened because of a local timezone.

Actor identifiers

A provenance record names who performed an operation, and a provenance record is a block: the identifier enters the payload, the payload enters the envelope, and the envelope is what block_id is computed over. So an identifier two parties spell differently is two names for one fact — the same silent divergence canonical serialization exists to prevent, arriving through a field nobody had canonicalized. Two forms, and no third:

from boltzmann.identity import actor_id_form, is_actor_id, parse_actor_id

actor_id_form("alex@alquimia.ai")         # ActorIdForm.ADDRESS
actor_id_form("anthropic/claude-code")    # ActorIdForm.NAMESPACED
actor_id_form("curator")                  # None

Form	Names
`alex@alquimia.ai`	A person, by an address they already hold
`github.com/alexfiorenza`	A person known only by a handle, or an organization
`anthropic/claude-code`	A runtime
`anthropic/fable-5`	A model
`gaussia/nightly-ingest`	A pipeline or a service

The namespace carries whoever made or vouches for the name, so nothing repeats it as a separate field. No scheme prefix is stored: mailto: is ceremony around a value people already write correctly, and a URL invites exactly the questions a canonical form must leave closed — a trailing slash, a default port, a percent-encoded octet. An implementation exporting to a format that requires URIs derives one at that boundary.

Refused, never normalized. Alex@Example.org raises ActorIdError rather than being lowered. Rewriting it would mint a block_id the caller neither asked for nor can predict — and therefore one they cannot search for either.

The check is asymmetric on purpose, and the second half is the easy one to lose:

brain = Brain.open("./my-brain", actor=Actor(id="curator", kind=ActorKind.HUMAN))
# ActorIdError: ... it names nothing off this machine

Actor(id="curator", kind=ActorKind.HUMAN)   # fine: this is how old records decode

Every provenance record ever written decodes through Actor, so a validator on the type would make every brain that predates this rule unreadable — punishing readers for a writer’s old habit. Enforcement attaches where an identifier is being chosen: opening a brain, and the request models. What is already published still reads.

Getting started

Core concepts

Guides

Canonical serialization

Values a payload refuses

Three levels of hashes are three types

Hashing primitives

Timestamps

Actor identifiers

​Canonical serialization

​Values a payload refuses

​Three levels of hashes are three types

​Hashing primitives

​Timestamps

​Actor identifiers

Canonical serialization

Values a payload refuses

Three levels of hashes are three types

Hashing primitives

Timestamps

Actor identifiers