Reference
Identity provenance and incremental checking
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.