provevi.events

The format of an evidence event.

Each event is one line of canonical JSON. Each line holds the SHA-256 of the line before it, in prev, so a changed, removed or reordered line breaks the chain. provevi owns this format; provrun decides what each event means.

canonical

source

canonical(obj: Any) -> str

The canonical JSON of a value: sorted keys, no spaces, ASCII only.

Parameter	Type	Default	Description
`obj`	Any	required	A value JSON can hold; any other value is written as its str
returns	str		Its JSON with sorted keys, no spaces and ASCII only

sha256_bytes

source

sha256_bytes(data: bytes) -> str

The SHA-256 of some bytes, as hex: how provevi names payloads and chains events.

Parameter	Type	Default	Description
`data`	bytes	required	The bytes to hash
returns	str		Their SHA-256, as 64 lowercase hex digits

now

source

now() -> str

The time of an event: UTC, to the microsecond, ending in Z.

Parameter	Type	Default	Description
returns	str		Such as `2026-10-31T16:40:32.123456Z`

class EvidenceEvent

source

EvidenceEvent(run_id: str, seq: int, time: str, type: str, component: str, actor: str, refs: tuple[str, ...] = (), data: dict = <factory>, payload: str | None = None, confidence: str = 'observed', prev: str | None = None)

One evidence event: one line of a run’s evidence, chained to the line before it by prev.

Parameter	Type	Default	Description
`run_id`	str	required	The run that the event belongs to
`seq`	int	required	The event’s position in the run, from 0
`time`	str	required	The UTC time the event was written, as `now` gives it
`type`	str	required	What happened, such as `run_created` or `model_called`; provrun decides the types
`component`	str	required	The part of provrun that wrote the event: a class such as `RunContext`, `agent`, or a name such as `tool:grep`
`actor`	str	required	The user or the service identity of the run
`refs`	tuple[str, …]	`()`	The logical URIs that the event is about, pinned or not
`data`	dict	`<factory>`	Small facts, such as a model name or a token count
`payload`	str \| None	`None`	The SHA-256 of a large payload stored apart from the event, or `None`
`confidence`	str	`'observed'`	How far a reader can trust the event: one of `CONFIDENCE`
`prev`	str \| None	`None`	The SHA-256 of the line of the event before it; `None` for the first

EvidenceEvent.line

source

EvidenceEvent.line() -> str

The canonical JSON line of the event; its hash is the next event’s prev.

Parameter	Type	Default	Description
returns	str		One line of canonical JSON, with no newline

EvidenceEvent.from_line

source

EvidenceEvent.from_line(line: str) -> EvidenceEvent

Read the event that one line holds.

Raises ValueError or TypeError if the line is not an event with fields of the right types.

Parameter	Type	Default	Description
`line`	str	required	One line of a run’s `events.jsonl`
returns	EvidenceEvent		The event the line holds