> ## Documentation Index
> Fetch the complete documentation index at: https://docs.the40thieves.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Write provenance

> A signed, hash-chained record of every committed mutating tool call, what each field is trusted for, how to verify the chain, and how to query one note's history.

Every mutating tool call that commits writes one **provenance record** to `cache.db`. A record
says which tool ran against which vault, which paths the call named and what their bytes hashed to
before and after, when, and who the server believes called. Records are chained per vault and
signed with the auth registry's EdDSA key, so a record that is later edited, reordered or removed
fails `reliquary-tc provenance verify`.

Records hold **hashes and attribution only**: never note content, never prompts. They are written
by the dispatch pipeline itself (one choke point for every mutating tool, derived from the tool
registry, so a new mutating tool is covered by construction). Settling an already completed write is
**fail-open**: a fault cannot undo or turn that committed write into an error. The multi-note
`commit_wiki_page` pending row is deliberately **fail-closed**, because it is recorded before the
first rename: if that row cannot be stored, the staged files are discarded and the write is refused.
A fault is not silent; see [Recording faults](#recording-faults).

## What is trusted

Every attribution field sits in exactly one of three groups, so a reader never has to guess.

| Group | Fields | Trust |
| - | - | - |
| `verified` | `host`, `server_version`, `transport`; `principal` and `persona` **only when a bearer token was cryptographically verified** (`auth.mode: jwt` or `oidc`); `session_id` | Established by the server. A client cannot influence them. |
| `unauthenticated` | `principal` label seen on stdio or under `auth.mode: none` | The server saw a label; nobody proved it. Kept apart from `verified` so it cannot pass for it. |
| `self_reported` | MCP `clientInfo` name and version; the request `_meta` block `io.reliquary-tc/provenance` with `model`, `project`, `agent`, `machine` | **Whatever the client said.** A client can lie about its model, project, agent or machine; nothing here is checked. |

A client names itself in the request `_meta`:

```json theme={null}
{ "_meta": { "io.reliquary-tc/provenance": { "model": "claude-sonnet-5-5", "project": "notes-sync" } } }
```

Values are strings only and length-bounded; an oversized or non-string value is dropped rather than
truncated. Treat `self_reported` as a label for humans and audit triage, never as an access
decision.

What a record does **not** claim:

* **Paths are the paths the call named.** Side effects the tool performs elsewhere, such as backlink
  rewrites in other notes, are not listed.
* **Digests** are a sha256 of the file's bytes, or `absent` (no file there) or `unhashable`
  (directory, symlink, unreadable, or over the size cap). A symlink pointing outside the vault is
  never followed: it records `unhashable`. Beyond 500 paths per call the rest are counted in
  `paths_omitted`, not listed.
* **The `after` digest is bound to the write where the tool reports it.** Tools that rewrite one
  note (`write_note`, `append_note`, `patch_note`, `update_frontmatter`, the tag tools) return the
  sha256 of the content they wrote, and that value is recorded, not a later read of the disk. For
  `commit_wiki_page` supplies the digest of every file in its batch through the pending-write path,
  so its settling `ok` row uses those same written digests instead of re-reading disk. For every
  other tool the file is hashed after the handler returns, and the opened file descriptor is
  checked to be the very file the vault-containment check vetted (same device and inode, with the
  path re-resolved after the open), so a directory swapped for an outside symlink in that window
  records `unhashable` instead of the outside file's hash. **Residual:** for those other tools
  (move, copy, delete, bulk and structured-document tools) a writer that replaces the file inside
  the vault between the handler returning and the digest being taken would have its bytes recorded
  as that call's `after`. The attribution is still the caller's; the digest is then "what the file
  held just after the call".
* **Failed and denied calls are not recorded.** The exception is a call that threw after a named
  path had already changed: it is recorded with `outcome: "error"`.
* **A multi-note commit writes a `pending` record first.** `commit_wiki_page` replaces several notes
  in one call and cannot be crash-atomic, so just before its first rename it appends a record with
  `outcome: "pending"` listing each named path with the digest it holds now (`before`) and the digest
  it is about to write (`after`). The normal `ok` / `error` record follows when the call settles (an
  `error` record is then written even if nothing changed). A `pending` record with nothing after it
  means the process died mid-commit: compare each path's `after` with the file. If the pending row
  cannot be appended, the batch fails closed before its first rename.

## Signing

A record is signed with the auth registry's **active EdDSA key**. The registry exists for
`auth.mode: jwt` / `oidc` servers on the HTTP transport; create the key with:

```bash theme={null}
reliquary-tc auth rotate-key --alg EdDSA
```

Records written without such a key are stored **unsigned**. That is the case for a **stdio-only
deployment, which has no registry and is therefore chain-only**: the hash chain still catches a
single edited or removed record, but anyone who can write `cache.db` could rewrite the whole chain
and re-hash it. An HS256 or ES256 active key is never used for provenance (HS256 is a shared secret:
anyone able to verify could forge), so those deployments are also unsigned.

Key rotation does not orphan history: verification accepts every registry key in any state, so a
record signed by a since-retired key still verifies for as long as it is kept.

A signed **head row** per vault pins the last record's sequence number and hash. Without it a
removed *last* record would leave a perfectly valid shorter chain; with it, removal is a
`head_mismatch`.

### The head is validated before it is extended

The head is what makes a deleted prefix or tail detectable, so the server never trusts a head it
finds on disk. Before a new record extends it, and before retention re-anchors it, the head must
pass four checks: it exists whenever records do; it pins the real last record (or its own prune
anchor when none remain); its prune anchor equals the first surviving record's `prev` and sequence;
and its signature, if it had one, still verifies under a registry key (any state). Only a head that
passes is re-signed.

If it fails, the server does **not** re-sign it and does **not** overwrite it. The write is still
recorded, chained from the real last record and stamped with `integrity.head_fault` naming the
failed check, so `provenance verify` reports `head_untrusted` for it (never hidden by
`--allow-unsigned`) on top of the bad head itself. The failure is also logged to stderr, counted in
`reliquary_tc_provenance_faults_total{kind="head_untrusted"}`, and fails the doctor check. Retention
skips a vault whose head fails validation and logs why. The chain then stays failed until the
operator restores `cache.db` from a trusted backup or archives it: re-baselining it silently would
be exactly the laundering this prevents. A signer outage over a signed head records nothing for
that write (counted as `omitted`) instead of writing an unsigned head over a signed one.

**What a writer of `cache.db` without the signing key can and cannot do.** It can delete or edit
rows, forge `pruned_*` or `head_*`, and strip signatures; every one of those fails verification and
is no longer papered over by the next write. It cannot produce a head that verifies, because the
head signature covers every head field. It can still delete **everything** (all records and the
head row) and restart the chain at seq 1: with no external anchor that is indistinguishable from a
vault that was never written to. It can also hide a stripped, unsigned chain from `--allow-unsigned`
(see above), and a deployment with no EdDSA key is chain-only and can be rewritten wholesale. If
the auth registry database is lost, an old signed head names a key nobody holds, so the chain reports
`head_unknown_kid` and new records are stamped `head_untrusted` until the registry is restored.

## Verifying

```bash theme={null}
reliquary-tc provenance verify                      # every vault with a chain
reliquary-tc provenance verify --vault notes --json
reliquary-tc provenance verify --allow-unsigned
```

The command is read-only, opens `cache.db` and the registry read-only, and exits **1** when any
chain fails. For each vault it prints the record count, how many are signed and unsigned, and every
problem (`hash_mismatch`, `seq_gap`, `chain_break`, `head_mismatch`, `head_untrusted`, `unknown_kid`, `bad_signature`,
and the head variants). If the auth registry was initialised but `<cacheDir>/auth.db` is lost, it refuses and
says so: with no keys every signature would read as tampered when the truth is that nothing can be
checked.

**`--allow-unsigned`** accepts records that carry no signature. Without it an unsigned record is a
**failure**, deliberately: if unsigned were acceptable, an attacker could strip every signature and
rewrite the chain. Pass the flag for stdio-only or pre-EdDSA deployments where chain-only integrity
is what you have; a record that *has* a signature is always checked, flag or not.

`reliquary-tc doctor` runs the same verification as the **provenance chain** check: it fails on any
sign of tampering, warns when records exist without signatures, the chain cannot be read, or a
recording fault is on file, and notes (without warning) a fresh install that has no EdDSA key yet.

## Querying one note's history

`get_provenance` answers "who changed this note, and when" for a single path:

```json theme={null}
{ "vault": "notes", "path": "projects/plan.md", "limit": 20, "include_verification": true }
```

Records come back **newest first** (by sequence number). `limit` is 1 to 200 (default 50); when more
remain, `next_cursor` is an opaque, signed cursor to pass as `cursor` for the next page of the same
request. It is bound to the caller, the tool and the exact arguments and it expires, like the other
paged reads; a cursor the server did not issue for this request (a made-up number, another request's
cursor) is an `invalid_input` error. `since` and
`until` are epoch milliseconds, inclusive. Each record has the tool, `outcome`, `ts`, the sha256
`before` and `after` of the queried path, `seq`, the record `hash`, every readable path the call
named (`paths_truncated` when the call named more than the record lists), and the attribution in the same three groups as the stored record. They are returned
**separately and never merged**: `verified` is what the server established, `unauthenticated` is a
label the server saw and nobody proved, and `self_reported` is what the client said about itself
(`model`, `project`, `agent`, `machine`, `client`) and can be false. Decide nothing from
`self_reported`. `response_format: "concise"` keeps the grouped attribution (without `host`,
`server_version`, `transport` and `machine`) and drops the full path list and the record hash.

**Who may call it.** The tool requires `read:provenance` **in addition to** `read:notes`. A record
names the principal and session of whoever wrote, which is audit data and not part of being allowed
to read a note, so it is its own grant (`read:*` and `*` include it, as for any scope). Anyone who
holds it sees the principal, persona and session of **other** principals for the paths they can read;
there is no finer per-principal gate.

**Access control.** The query uses the same read check as search and the link tools, against the ACL
of the vault being queried:

* A path the caller cannot read answers with the same `not_found` error, with the same message and
  details, as a path that was never written. The tool declares no central path check on purpose: that
  would answer `acl_denied`, which says the note exists. With `since`, `until` or `cursor`, both give
  an empty page.
* A record that names several paths (a move, a copy, a bulk call) lists **only the paths the caller
  can read**. A path they cannot read is left out with no placeholder and no count, and a record
  keeps only its readable entries. Nothing derived from a left-out path is returned either: when a
  record had a path left out, its `hash` is a hash of the view the caller can see, not the stored
  record hash (which covers the hidden path, so it would let a caller test a guess at it), and it
  never carries `paths_truncated`. A record with nothing left out returns its stored hash.
* A vault's records and its ACL never serve another vault.

**Moves.** A record lists a move as a `[from, to]` pair. When the newest `move_note`,
`bulk_move_notes` or `move_attachment` record moved a file onto the queried path, the history of
the source path is part of the result (`previous_paths`, and each record's `path` says which path it
matched), and the walk repeats for that source, up to 32 moves. The walk stops at a source the
caller cannot read, so it never learns the source existed. A move record is followed **only if it
verifies** (the same per-record check as `include_verification`, run whether or not it was
asked for). A move that fails it (an edited body, a bad or missing signature, an indexed column that
disagrees, or no key registry to check a signed record with) is not followed: the result carries
`lineage_incomplete` with the `reason` (a verify problem code, `unverifiable`, or `max_hops`) and the
`seq` of that record, and neither the earlier paths nor their records are returned. Without a key
registry (stdio-only) unsigned records are the norm and are followed. Records from before the file arrived at a
path (a previous occupant it overwrote) are not part of its history. The pass stops once a page is full, so `previous_paths` lists the earlier paths reached up to the
last record returned; a later page reaches further back. Moves are **not** followed
forwards: the old path shows its history up to the move, not what became of the file. Renames done by
other means (a tool that only deletes and creates) are plain writes, so they are not linked.

**Verification.** With `include_verification`, each record carries `verification`:
`signature` is `valid` only when the signature verifies **and** the body still hashes to the signed hash and agrees with its indexed columns; a record whose content was edited is `invalid` (a chain break is `chain_link`, and does not change `signature`). Otherwise it is `unknown_key`, `unsigned`, or `unverifiable` (no key registry,
for instance a stdio-only deployment, or an unreadable one: signatures cannot be checked, which is
not evidence of tampering); `chain_link` is `ok` or `broken`; `problems` lists the codes
`provenance verify` uses; `ok` is true only for a valid signature with no problem. This reuses the
verifier's own per-record check, so the two cannot disagree about one record. It does **not** prove
the chain is complete: a removed later record or a forged head is only visible to
`reliquary-tc provenance verify`. The query reads `cache.db`, as `verify` does, so a writer of that
file can forge records but not signatures (see the limits above).

**Limits.** A record stores the paths the call named, up to 500 per call (see `paths_omitted`): a
note beyond that cap in a bulk call has no record that names it. The records have no path index (a
stored path is the spelling the call named, which only normalizes in code, so an index column would
need a backfill SQL cannot do), so a query is **one newest-first pass** over the vault's chain with a
text prefilter on the file name, following moves in the same pass. The pass examines at most
`provenance.query.maxScanRows` rows (default 100000; about half a second at the worst measured, on a
loaded 4-core host, for a 100000-row chain with no match). A longer chain is read newest-first and
the result carries `scan_truncated: true`: older history was not examined. A path whose only history
lies beyond the budget answers `not_found`, like a path with none (an unreadable path must look the
same). Raise the budget for a long-retention vault, or bound the chain with `retentionDays`; `provenance verify`
is not bounded by it. Each page restarts the pass from the newest record, so a deep page costs what the
first one does.

## Recording faults

Because settlement is fail-open after a write has committed, a write whose final record could not be stored (a dropped
table, a sequence collision, a signer outage over a signed head) would otherwise look like "no
write happened", and the chain would still verify. Each such fault is therefore made visible three
ways: a `[provenance]` line on stderr, the `reliquary_tc_provenance_faults_total` counter (labels
`vault`, `tool`, `kind` of `omitted` or `head_untrusted`), and a `provenance_fault` row in
`event_log`, which is what `reliquary-tc doctor` (a separate process) reads to warn "N committed
writes left no record". The doctor warning ages out with `event_log` retention; the counter resets
with the process. The pending-row exception fails before any write, as described above.

## Optional stamps

The record in `cache.db` is the source of truth. Two **optional** stamps copy a little of it to
where a human will see it. Both are **off by default**; with them off, every note and every commit
message is byte for byte what the caller sent. Neither stamp holds anything the record does not
already hold, and neither ever contains the host id. Both need `provenance.enabled`.

### Commit trailers

`provenance.stamp.gitTrailers: true` makes the `git_commit` tool append trailers to the message it
sends to the Git bridge:

```text theme={null}
snapshot

Reliquary-TC-Session: 7f3c0e
Reliquary-TC-Principal: alice
Reliquary-TC-Model: claude-sonnet-5-5 (self-reported)
Reliquary-TC-Provenance-Seq: notes:41-44
```

* **Trust is in the text.** `Reliquary-TC-Principal` is the principal a bearer token proved
  (`auth.mode: jwt` or `oidc`), or the word `unverified` (stdio, `auth.mode: none`). The model is a
  client's own claim and is always followed by `(self-reported)`. A value is one line: control
  characters, including a newline in a claimed model, are replaced by a space, so a client cannot
  end its own trailer and start another.
* **Which writes.** The server asks the bridge what is staged, then keeps each staged note whose
  bytes *right now* equal what a record says that write left (`after`). A note a human edited since
  is not attributed to the agent, a deletion is not attributed at all, and a path no record names is
  ignored. A repo that sits above the vault (`Vault/a.md` in Git, `a.md` in the vault) still
  matches. Only the newest 2000 records of the vault are searched. A commit that includes no
  recorded write gets **no trailers**, and so does a commit whose staged list could not be read:
  the commit itself is never failed or delayed by stamping.
* **`Reliquary-TC-Provenance-Seq: <vault>:<from>-<to>`** bounds the matching records. Other records
  can sit between the two numbers (a write to a note that is not in this commit); the range says
  where to look, the digests say which.
* **One value per writer.** If the commit holds writes from several sessions, principals or models,
  each distinct value gets its own trailer line (at most 10 of a kind; more adds
  `Reliquary-TC-Truncated`).
* **Your message is kept.** Trailers go at the end, after a blank line, or into the message's
  existing trailer block (`Signed-off-by: ...`) the way `git interpret-trailers` would. The one
  exception: a `Reliquary-TC-*` trailer **you wrote** in the final trailer block is removed when
  this stamp is on, so that a trailer under the prefix is always the server's. The server does not
  run `git` on the vault to do any of this.
* The tool result gains `stamped_trailers` (the lines that were added) when there were any.

**What a trailer does not prove.** Trailers live in the commit message, which anyone who can
rewrite history can change; the signed chain is what proves the record. The session id is the
server's own, but the model is only what the client said.

### Frontmatter stamp

`provenance.stamp.frontmatter: true` writes one key into a note an agent **creates**:

```yaml theme={null}
obsidian_tc_provenance:
  session: 7f3c0e
  principal: alice
  model_self_reported: claude-sonnet-5-5
  seq: 41
```

* **Creations only:** `write_note` when the note did not exist (`create`, or `upsert` of a new
  note), `commit_capture`, `commit_wiki_page` for the new page it creates (never for an overwrite or a
  patched note; the page's frontmatter is checked against the wiki's `SCHEMA.md` with the stamp in it,
  so a property vocabulary that does not declare the stamp key gets a `schema` problem), and
  `execute_template` when the target did not exist before the call.
  `write_note` over an existing note, `append_note` (including `create_if_missing`), `patch_note`,
  `update_frontmatter`, `execute_template` with `overwrite` and every other tool never stamp.
* **Human frontmatter is never modified.** The key is added with the vault's own line-preserving
  frontmatter writer, so every other key, comment and scalar keeps its exact source bytes. A note
  whose frontmatter is not valid YAML is written unstamped. The one thing replaced is a value the
  *caller* put under the stamp key in a note it is creating, so a forged stamp cannot pass as the
  server's.
* **Fields:** `session` (when the call had one), `principal` (verified, else `unverified`),
  `model_self_reported` (when the client claimed one) and `seq`. `seq` is where the write's own
  record is expected to land: one past the newest record of the vault when the note was written.
  It is exact when writes to a vault do not overlap and **never above** the real number otherwise;
  the authoritative link is the record whose path and `after` digest match the note.
* **Verification is unaffected.** The stamp is part of the bytes written, so the recorded `after`
  digest is the digest of the stamped note, and `provenance verify` passes exactly as before.
* **A stamp is a label, not proof.** Anyone who can edit the file can edit the stamp. Check a stamped
  note against the chain, not the other way round.
* `execute_template` stamps after Templater has written the note, so the note exists unstamped for
  an instant and a stamp failure leaves Templater's output as it was.

## Configuration

```json theme={null}
{
  "provenance": {
    "enabled": true,
    "host": { "mode": "hashed" },
    "retentionDays": 365,
    "query": { "maxScanRows": 100000 },
    "stamp": { "gitTrailers": false, "frontmatter": false, "frontmatterKey": "obsidian_tc_provenance" }
  }
}
```

* `enabled` defaults to `true`; `false` records nothing.
* `host.mode` is `"hashed"` (default, a stable digest of the machine's hostname) or `"label"`,
  which records `host.label` verbatim and requires it.
* `retentionDays` is absent by default, which keeps records forever.
* `query.maxScanRows` (1000 to 10000000, default 100000) is the most rows one `get_provenance` call
  examines.
* `stamp.gitTrailers` and `stamp.frontmatter` default to `false`; `stamp.frontmatterKey` names the
  key (letters, digits, `_` and `-`, up to 64 characters). Setting either stamp while `enabled` is
  `false` is a configuration error.

A hashed host id lets records correlate across restarts without naming the machine.

## Renaming a vault

The vault id is part of every signed record, so a vault rename does not re-key provenance: the old
chain stays under the old id and still verifies (`provenance verify --vault <old-id>`), and new
records start a new chain under the new id.

## Retention

`provenance.retentionDays` is **unset by default**: this is an audit trail and pruning it is an
explicit decision. When set, the maintenance sweep removes each vault's records older than the
window as one contiguous prefix and moves a **signed prune anchor** (in the head row) up to the last
record dropped. The surviving chain therefore still verifies. Removing any record that is not part
of the oldest prefix, or dropping a prefix without a matching signed anchor, still fails
verification. Records are chosen for deletion by their `ts` column, which is not itself signed, so
before deleting anything the sweep verifies every record it is about to drop (its hash, its columns
against the signed body, its link and sequence, its signature). A chain that fails this (an edited
`ts`, a rewritten body) is left exactly as found, no anchor is signed, and the sweep logs the failing
record; `provenance verify` keeps reporting the original problem instead of a clean, shorter chain.
A sweep that has no signer available leaves a signed chain alone rather than
downgrading its head to unsigned. The sweep reports the count as `provenance`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.