Session records and the three provenance tiers

A session is the run record behind a change: the originating prompt and the ordered turns — tool calls, reasoning, outputs, human feedback — that produced it. It is the raw what, distinct from the rationale, which is the distilled why. Either is useful without the other.

TOVIO stores run records in three tiers, and the difference between them is the single most important thing on this page. They are not quality levels; they are different claims.

The three tiers

Which tier a record belongs to is answerable without decoding it. The discriminant is where the address sits — which commit field, which object kind — never a flag inside the record. That is deliberate: a boolean inside an object is something a producer can get wrong or a reader can forget to check.

A commit may carry at most one run record. Two would leave every reader unable to say whether the record is attested, and that ambiguity is the exact thing the design exists to prevent.

Every surface says which one you are looking at

An observed record is labelled UNATTESTED and self-reported wherever it appears — human output, JSON, agent-facing reads, graphs. A backfilled one is labelled as link-asserted rather than proven. On machine surfaces the attestation state is an explicit field, never something you infer from a missing key. A surface that named the originating runtime without the class label would be wrong, not merely unpolished.

Reading a record

tovio log --session <chg:>

tovio blame --session

log --session renders one change's run record instead of the log. blame --session surfaces the run record behind each attributed line, which is the one you want when the question is "why is this line like this". A record sealed to a protected policy is decrypted for a policy recipient and shown as a locked marker otherwise — never any plaintext to a reader who is not cleared.

Controlling observed capture

Observed capture is on by default, and it runs on every command that writes a commit — commit, and also resolve and land. There is no flag to turn it on because there is nothing to turn on.

tovio commit -m "..." --session-from claude-code

tovio commit -m "..." --session-from <path>

tovio commit -m "..." --no-session

--session-from names a runtime — claude-code, codex, or open-transcript — or a file path, instead of letting discovery find one. open-transcript is the published neutral format: any runtime or wrapper that writes it into the well-known drop directory is captured with no bespoke adapter, which is the point of publishing a format rather than chasing a dozen private ones.

The same effect comes from the TOVIO_OBSERVED_TRANSCRIPT environment variable or the provenance.observed_from configuration key. All three count as naming a transcript explicitly, and that changes how failures behave — see below, and see the article on capture refusals.

--no-session is the per-command opt-out. The durable one is configuration:

tovio config set provenance.observed_capture off

tovio config set provenance.observed_capture prompt

tovio config set provenance.observed_capture full

Policy tightens and a flag never loosens. An organization can pin the setting in the versioned policy manifest, and a pin to off cannot be re-enabled locally. A value that is present but unparseable resolves to off; absence resolves to the default. Silence and unreadability are deliberately opposite.

The transcript is checked before it is stored

Several gates run before any observed object is written:

• Secret scanning is mandatory, not best-effort. Every byte that would be stored is scanned after normalization, including the pre-truncation text of any turn that was shortened, so a credential straddling a truncation boundary cannot slip through. A finding blocks the write. A scan that fails, or a ruleset that is unreadable or reports zero rules, counts as a finding.
• The transcript must belong to this repository. Runtimes derive a per-project directory name from the working-directory path, and that encoding is lossy — several distinct paths can collide on one name. The transcript's self-reported working directory is verified against the repository, because attaching another project's session as this commit's provenance is a confidentiality failure whose failure mode is silent.
• A discovered transcript older than the parent commit is not attached, or every subsequent commit would re-attach the same stale record.
• The assembled record must fit the object-size ceiling. A sealed record is measured after its spilled content is folded back inline, so a protected-touching commit reaches the bound far sooner than a clear one.

Whether a failed gate costs you the commit

This is the part worth reading twice, because it depends on whether anyone asked for the capture.

• Discovered — nobody named a transcript. Every failure here drops the session and the commit lands. A secret finding warns loudly, because you need to know your transcript holds a credential; the rest is silent, since a commit from a plain shell must never complain about a transcript nobody wanted.
• Explicit — you named one, with --session-from, TOVIO_OBSERVED_TRANSCRIPT, or provenance.observed_from. A failure is surfaced and the command is refused. Nothing partial is left behind — the capture is prepared before anything is written — but the commit did not happen. Re-run with --no-session to proceed without it. Silence would be the wrong answer here: you asked, and a quiet skip would leave you believing provenance was recorded.
• The object-size ceiling is the exception in the other direction: it is a warning either way. Provenance never blocks committed work over a record that is merely too big.
• One failure refuses regardless: a record that touches two or more protected policies with no reader in common cannot be sealed to anyone, and storing it in the clear is the one outcome this tier may never produce.

Backfill, and what it is honestly worth

tovio agent backfill <target> --session-from <path>

Associates an existing transcript with a change that has no run record. The result is labelled backfilled (link asserted, not proven) everywhere it appears, and a signed audit entry records who asserted the association.

It establishes who claimed the link and that the claim is unaltered since. It does not establish that the transcript produced the change — nothing can, retroactively. It is refused if the change already has a record, if the repository has no signing identity to sign the assertion with, or if the change touched a protected path, since a backfilled record has no sealed form and clear transcript text next to protected content is the one outcome the tier exists to avoid.

Sealing

A record whose change touched a protected path is stored sealed, encrypted to the recipients the touched policies have in common. A sealed record is fully self-contained — nothing lives outside it by reference — because a provenance record that can be silently half-present is worse than none.