Docs/Reference

Reference

Identity provenance and incremental checking

How Tama sources newly introduced identities without rereading unchanged prose and transcript bodies.

How Tama sources newly introduced identities without rereading unchanged prose and transcript bodies.

block-identity-literals refuses an email address, a UUID, or an identifier that flattens an address when nothing issued it. It reads only the lines a write adds — the + lines of a hashline section or patch, an edit's replacement, a new file's content — never the lines the file already holds: an identity already on the page was sourced by the write that put it there. A value passes when the harness issued it as the name of a stored transcript (a session id: OMP names each session's transcript under ~/.omp/agent/sessions after it), when a file the written path's own git checkout already tracks carries it (a product's published identifier — a journey version id in a seed, a row id — asked of git grep, which reads only the index), when an artifact outside any conversation carries it (a token cache, a cloud profile, the machine registry), when the operator used it in two or more stored sessions, or when identity_provenance.json records his verbatim quote declaring it. The transcript names and the checkout are asked first, so a write that names a session or an identifier the repository already holds does not wait on a read of every transcript on the machine; an untracked file beside the write counts for nothing. A path outside any checkout (no folder above it holds .git) is not searched. Inside a checkout, a git grep that cannot start, ends on a signal, or writes an error sources nothing while the other sources decide; a value none of them settles is then the gate's own failure, never a missing provenance: <path>: cannot establish provenance for <value>: the written file's checkout could not be searched: git grep in <folder> ended with <status>: <git's error>. The values none of those sources carries are looked up in the stored sessions together, in one walk per written file that reads each transcript's index once and ends when every value has two sessions. A word shaped like a flattened address that is part of an angle-bracket placeholder — a usage line's <gh-owner-name> argument — is read as the placeholder it is and never searched for. Any other value is refused naming it and saying which source was missing: the UUID <value> has no provenance -- no artifact carries it and no stored user message contains it. IDENTITY_TRANSCRIPT_ROOT, IDENTITY_ARTIFACT_ROOTS and IDENTITY_PROVENANCE_FILE move the three stores. The real tests are tests/identity-literals/session_ids.rs, tests/identity-literals/tracked_ids.rs, tests/identity-literals/placeholders.rs and tests/identity-literals/whole_file.rs (cargo test -p tama-cli --test identity_literals_session_ids --test identity_literals_tracked_ids --test identity_literals_placeholders --test identity_literals_whole_file), the second against a real git checkout it creates. The last copies the real long page named by TAMA_TEST_PROSE_FILE, then edits beside an untouched unsourced id. It requires TAMA_TEST_SOURCE_REVISION and retains the candidate, binary and page digests, page byte count, commands, durations and actual decisions under the ignored build directory; it never edits the original page.

When transcript content is required, hook subprocesses share per-file identity snapshots under Tama's state directory in identity-mentions. Each snapshot is bound to the source file's device, inode, byte length, modification time and metadata-change time, plus the identity extractor. Unchanged files are not reopened for their transcript bodies. A per-file OS lock gives a changed file one reader across sessions, and completed shards are atomically published so another hook can reuse them. There is no clock-based expiry. Removed, replaced, appended or permission-changed files do not retain their old provenance verdict. Only actual user-message identity tokens count; assistant messages are not independent operator evidence.

The shared index applies the transcript-name reader's artifact boundary: a directory beside a JSONL transcript with the same stem is not traversed. Its artifacts and subagent files cannot count as another independent user session. This avoids reopening artifact subtrees during each metadata walk; the real journey verifies both a nested user-shaped artifact and malformed artifact content while genuine independent transcript evidence still passes.

A read, parse or publication failure names its path and operation and refuses the write as unavailable provenance, rather than claiming the identity was invented. Cold or changed reads announce czekam; a contending hook announces its lock wait. These source mechanisms require actual cross-process qualification before an installed runtime is claimed to avoid repeated scans.

The explicit identity-provenance register follows the same diagnostic boundary: a genuinely absent file means no declarations, while an unreadable existing path names the failed read, exact path and filesystem cause and refuses the write. A warmed transcript index does not conceal that register failure. The real mention journey replaces its isolated register with a directory and checks the observed cause, then removes it to verify the documented absent-register state.

TAMA_TEST_SOURCE_REVISION=<full-candidate-revision> cargo test -p tama-cli --test identity_literals_mentions runs the actual hook in separate processes against isolated persisted transcripts. It retains the candidate and binary digest, commands and outcomes, covering a warm shared index, assistant exclusion, equal-size/equal-time replacement, deletion, malformed records and permission loss.