Rendered from docs/spec/15-the-recorder-contract.md in the Headwater corpus. Every document on this half of the site is typed by the taxonomy the descriptor names: corpus.json.

The recorder contract

Spec 5 names a component that no part of this repository holds. A recorder drives a probe session, observes it from outside, and writes a transcript of what it saw. It is the one part of the measurement layer that reaches the network. So it is not a crate of this engine, and no verb here writes a transcript.

A person who writes a recorder reads this part. Everything below is a contract that engine/crates/probe/src/intake.rs enforces, and engine/crates/probe/tests/contract.rs holds this text to the constants that carry the four closed key sets. A key added to the engine and not to the table below fails that test.

A recorder is a driver and a transform, and the channel between them is the condition

HW-DR-0059 admits a second shape of recorder. A driver starts the session and reads what the harness emits. A transform filters that stream into a transcript. The driver reaches the network and the transform reaches nothing, so the sentence above describes the driver.

A harness already tags each block of its own session log by type, and the model states no tag on any block. So a filter that keeps the tool calls and their results reads no account the model wrote of its own process. That filter is an outside observation on one condition. The log has to reach the transform through a channel that the model has no handle on.

A file on a filesystem the session reaches is not such a channel. On the host that runs this repository, every process of one user can write the live log of a session. A Bash call of that session is one of those processes. The standard output of the harness process is such a channel, because the session holds no handle on the parent's pipe. claude -p --output-format stream-json, read by the driver from that stream, is the channel the first recorder reads. A recorder that reads the log from disk states nothing about who wrote a line of it. The transcript it produces is a self-report that no key set can detect.

Both parts sit outside this engine. The transform is the second half of one component, and it stands on the path from a live session to a transcript. That is the position the paragraph above keeps out of the engine.

The values a session log omits, and the step that derives each one

A harness log carries the calls and not the rest of the contract below. Each value the log omits is derived after the session by a named step. The list is prose rather than a table, because the four tables of this part are the four closed key sets and engine/crates/probe/tests/contract.rs counts them.

  • result on a call is the content digest of the document, in the form headwater probe plan prints, and never the bytes returned.
  • path on a produced artifact comes first from the log's own write calls, and then from any path the driver names. The next section states the rule.
  • cites on a produced artifact is every identifier of this corpus that appears in the artifact.
  • findings on a produced artifact is every rule that reported over the artifact. Both are computed the same way for every probe, and neither reads a probe.
  • The six identity members are lock, tree, selection, read_set, seed and harness, copied from the plan.
  • served_version and cost_cents are derived from the provider metadata of the run, because a usage record carries token counts and not cents.

A session reads its workspace and nothing else of the host

A probe measures what the workspace gives a session. A session that can read outside its workspace measures the host instead. In the 2026-09-30 batch, 118 of 658 sessions named a path outside the workspace. 58 of 658 named a source of this repository that their arm did not give them. 17 of those 58 named a copy of this repository on the host. The evaluation of that batch derives these figures. The committed transcripts and #1467 state 44, because that count read only two channels. So the driver confines each session, and it refuses a session that it cannot confine.

What the file system of the session holds

tools/probe/probe-record.sh runs the harness under bwrap. The file system of the session holds these items and no other:

  • /usr and /etc, read-only, with /bin, /lib and their siblings as the host has them.
  • A private /proc, /dev and /tmp.
  • The workspace, read-write, at its own path.
  • The harness binary, read-only, at a path of its own.
  • The egress proxy, read-only, and the directory of its socket, read-only. The next sections say why.
  • The log directory of the run, read-write, because the intent hook writes there.
  • A configuration directory of the session, read-write.
  • The target of /etc/resolv.conf, read-only, when that file links to a path outside /etc and /usr, as it does under systemd-resolved. No name resolves inside the session, because the session has no network of its own.

So the file system of the session holds no copy of this repository on the host. It also holds no other tree of the batch and no part of the home directory. The network is a separate channel, and the one route to the network says what it holds and what stays open.

The environment of the session

The driver clears the environment. Then it sets these variables in the session, and no other:

  • PATH, set to /usr/local/bin:/usr/bin:/bin.
  • HOME, set to the configuration directory of the session.
  • CLAUDE_CONFIG_DIR, set to the configuration directory of the session.
  • TMPDIR, set to /tmp.
  • HTTPS_PROXY, set to the egress proxy.
  • HTTP_PROXY, set to the egress proxy.
  • https_proxy, set to the egress proxy.
  • http_proxy, set to the egress proxy.
  • ANTHROPIC_BASE_URL, set to the egress proxy.
  • CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, set to 1.
  • HEADWATER_PROBE_SESSION, set to the identifier of the session.
  • HEADWATER_SHADOW_LOG_DIR, set to the log directory of the run.
  • LANG, copied from the host when the host sets it.
  • ANTHROPIC_API_KEY, copied from the host when the host sets it.

ANTHROPIC_API_KEY is a credential of the host. When the host sets it, it gets into the session. The other credential of the host in the session is the copy in the configuration directory, which the next section describes. tools/probe/probe-record-fixtures.sh compares this list and the list of the file system with the code of the driver, in both directions.

The configuration the session runs under

The configuration directory starts empty. The driver copies the credentials of the host into it, and it removes that copy when the session ends. HOME and CLAUDE_CONFIG_DIR both name this directory. So no user CLAUDE.md, skill, plugin, setting or auto-memory of the host loads.

The driver also passes --setting-sources project,local. The present arm still loads the hooks and skills of the workspace, because they are what a campaign measures. Every arm runs in the permission mode dontAsk, with one list of allowed tools, and with WebSearch and WebFetch denied.

The batches of 2026-09-28 and 2026-09-30 ran under bypassPermissions and the configuration of the host. A rate from a batch under this contract does not compare with a rate from those batches. Each transcript states this in its prose.

The init line is the check

The first system line of the session log, with subtype init, states what the session loaded. The driver refuses the transcript with exit 12 when that line shows one of these items:

  • The permission mode bypassPermissions.
  • A plugin whose path is not builtin.
  • An MCP server that the .mcp.json of the workspace does not declare.
  • A skill whose name is a skill directory of the host, or a skill that carries a plugin namespace.
  • A memory path outside the configuration directory.

A log with no init line is refused too, because it does not state what loaded. This refusal comes after the session, so that session has spent. The transcript also counts the paths outside the workspace that the session named, because a session cannot see a refusal from outside.

What a host must provide

A recording host must provide these four items:

  • bwrap, with user namespaces and network namespaces that an unprivileged user can create. Without them, the driver exits 12 before any harness call, so nothing is spent. No variable turns the confinement off.
  • python3 in /usr, because the egress proxy and its forwarder are Python. Without it, the driver exits 12 before any harness call.
  • Credentials for the harness, in .credentials.json of the user configuration of the host. An OAuth access token in that file must stay valid for the full session, because the session cannot refresh it. When the token expires during a session, the harness stops with an authentication error.
  • A batch directory outside $HOME. tools/probe/campaign.sh refuses an output directory under it.

The one route to the network

The session has no network of its own. The driver runs it with --unshare-net, so its network namespace holds a loopback interface and nothing else. The loopback of the host is not in it. In the 2026-09-30 batch, the network was shared, and sessions reached GitHub with gh api and curl. The confinement now refuses each direct connection of this kind. Other sessions of that batch reached GitHub with WebSearch or WebFetch, and the driver now denies those two tools to the session.

The one route out is tools/probe/egress-proxy.py. The driver starts it on the host before the session and stops it after the session. It listens on a unix socket in a directory that the driver binds into the session. In the session, the same file forwards 127.0.0.1:3128 to that socket, and HTTPS_PROXY names that port. ANTHROPIC_BASE_URL names the same port in plain HTTP. So the harness sends each call to the provider API as a request that the proxy can read. The driver also sets CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, so the harness asks for no telemetry host or update host.

The proxy opens no tunnel. It refuses each CONNECT, to any host, because the proxy cannot read the contents of a tunnel. It sends a request to one host only, the provider API at api.anthropic.com on port 443. Before it connects, it reads the full request, and it refuses the request when one of these conditions is true:

  • The request names a host or a port other than the forwarder of the session.
  • The head of the request holds a control character other than a tab or the \r\n at the end of a line. Such a character can add a line to the head that the proxy sends to the API.
  • The method is not POST, or the path is not /v1/messages or /v1/messages/count_tokens.
  • The proxy cannot read the body. The body has a Transfer-Encoding or a Content-Encoding, or it has no single Content-Length in ASCII digits. Or the body is larger than 32 MiB, or it is not a JSON object.
  • An object of the body names a key two times. The proxy reads the last value, and a parser at the API can read the first value.
  • An entry of tools has a type that starts with web_search_, web_fetch_ or mcp_.
  • The body has an mcp_servers key.
  • An object at any depth of the body has a source with the type url.

With the last three conditions, a request asks the provider to get data from another host for the session. These are its web search, its web fetch, its MCP connector, and a document or an image at a URL. Each refusal gets a 403 status and one log line that names the refused item. The proxy forwards every other request over TLS, and it verifies the certificate and the host name of the API. The host, the paths and the rules are in the source of the proxy, and no variable or argument changes them. A switch that changes them would open the channel again.

The rule refuses named tool types and does not permit only a list of known types. The harness claude 2.1.288 names some server tools of its own, for example tool_search_tool_regex and advisor_20260301. A campaign session can send these tools, and one measured session is not sufficient evidence for a closed list of types.

These rules come from a measurement on 2026-10-03 with claude 2.1.288 and one haiku session that answered a prompt. The harness sent one call through the base URL in plain HTTP with an OAuth credential. The call was POST /v1/messages?beta=true with a Content-Length body and 23 tools, and no tool had a type. The harness also sent three CONNECT requests to api.anthropic.com. A proxy refused all three, and the session answered the prompt. In a second measurement, a curl call in a session with no network held the credential and went through this proxy. The proxy refused a request for web_search_20250305 and a request for web_fetch_20250910 with 403. It also refused a CONNECT to each of the two provider hosts. It forwarded an ordinary request, and the API answered it with 200.

The host platform.claude.com also answers POST /v1/messages, and the harness refreshes an OAuth credential there through a tunnel only. The harness accepts no other address for that host. So the proxy refuses that host too, and a session cannot refresh its credential. The section above states what this requires from the host.

The transcript states this confinement and names the host that the proxy forwards to. It also states each connection that the proxy allowed and each connection that it refused, with the host and the count. It states each request to the provider API that the proxy refused, with the refused item and the count. When the harness fails, the driver prints the same counts with exit 10. A session fails there when the proxy refuses a host that the harness needs. If the proxy does not start, the driver exits 12 before any harness call.

The prompt is the task section, and the answer is the final line

Two values cross the boundary between a probe document and a session. The driver sends one in and it reads one out. This part fixes both, and tools/probe/probe-record.sh is the recorder of this repository that implements them.

The prompt is the body of the probe's ## Task section, word for word. Where the task holds ### Phrasing <n> subsections, the prompt is the body of the one phrasing that the session draws, without its heading (HW-DR-0112). The driver copies that body and sends it as the whole of the session's first turn. No other section of the probe document is in the prompt or in the workspace, because the session runs in a sealed workspace. tools/probe/seal.sh removes the probe shelves from the workspace, and every file that names the probe. A file outside docs/ stays only if folds: in .headwater/probe.yml declares it. A fold names the probe by path or title and states no answer. The seal also removes each answer key that .headwater/probe.yml declares for the probe: a document that an earlier session wrote in answer to the task, and every line elsewhere that names that document. The driver refuses a workspace in which a file still names the probe or an answer key. Before #1229 both arms kept every probe, and one session read its own probe file and then answered. An expectation, a worked example and a paragraph of rationale are for the person who reads the probe. So a paragraph of commentary under the ## Task heading is prompt rather than commentary. It reaches the model, it changes what headwater route scores, and the probe then measures a task that nobody wrote.

The answer is the final line of the final message, compared as a set of words. The driver takes the last line of the final message that is not empty. It trims the space around that line and removes its format. Format is Markdown emphasis or a backtick that wraps the whole line, and a run of trailing punctuation. It then folds the case and splits the line into words at each run of space. It splits each declared answer in the same way. The answer is a value only where the line holds the words of one answer that the probe declares under answers, in any order. An extra word or a missing word gives no value. The driver writes the declared form of that answer. Every other message records answer: null. The recorder reads the whole set and never the expected values. So a wrong word of the set is recorded as that word, and the grader then finds it wrong. A message that states the reasoning and then puts the word on a line of its own carries that word. A message whose last line is a sentence carries no answer. Where the line is one word that matches no answer, the driver reads it as a spelling of a declared identifier. One document of the corpus holds that identifier. Its path, file name, slug or file number names the identifier. A spelling that names two declared answers names neither, so a file number that two answers share gives no value. The driver writes the word and nothing else, so the transcript holds no prose. A driver that searched for the word inside a sentence would read the session rather than observe it, and spec 5 puts that reading outside a recorder. So a probe with a closed answer set states the output form in its own task text.

The whole message was the rule until #980. The pilot of 2026-09-28 found that 7 of 27 sessions wrote one sentence of reasoning and then the word on its own line. The arms did this at different rates, so the rule graded the format and moved the rates unevenly. The owner ruled on #980 the same day that the final line is the answer.

The line was compared as one value until #1384. The status probe declares answers of two words, such as current HW-DR-0052. In the pilot of 2026-09-29, the present arm gave the answer in 10 of 10 sessions and the absent arm in 8 of 10. One absent-arm session ended with HW-DR-0052 current, as #1384 records, and that line states the same two facts in the other order. The rule of one value recorded no answer for it, so the rule graded the order of the words and not their content. The set rule recovers that session, and the absent arm then reads 9 of 10. The other miss ended with 0052 current HW-DR-0052, which has an extra word, and it stays no answer.

Format was content until #1881. Phase B of the additive campaign recorded **HW-DR-0090**, `HW-DR-0090`, the path docs/decisions/0090-….md, its slug and the bare 0090 as no answer. Each one names the record that the review probe expects. The prompt says "the identifier" and does not say which form. In scenario 6 the intent hook showed the path and the file number, and never the HW- identifier. So the rule graded the spelling and not the record. In one cell it read 0 of 24 sessions as correct, and all 24 named the right record. The owner ruled on 2026-11-13 that the driver removes the format and resolves a spelling against the corpus. A line that is a sentence still gives no value.

The engine fixes six members of the identity, and the recorder supplies the rest

headwater probe plan composes a selection and prints the six members of the run identity that exist before any session starts. They are the lock, the corpus tree, the selection, the read set, the seed and the harness version. The plan also prints the probes selected, the task of each one, and the documents each one examines. It prints the read set that the digest covers, one line for each document.

The recorder copies those six into the transcript without change. It supplies the four that belong to the run: the model, the served version, the wall-clock time and the realized cost. It supplies the tier and the arm, which the plan states and which a reader of the transcript alone would otherwise have to guess.

A model name is not a pin. The recorder writes the served version where the provider exposes one, and it writes the name as a name where no version is exposed.

A transcript is two fenced blocks under two headings

The probe_transcript kind requires a Run identity section and an Events section. Under each heading the recorder writes one fenced yaml block. Prose around the blocks is what a person wrote about the run, and no verb of this engine reads a word of it.

The blocks carry four closed key sets. A key outside a set refuses the whole file. That refusal enforces the rule that a transcript holds no model prose. An omission that nothing tests is a request rather than a rule. A transcript with a reasoning key beside the tool calls returns the self-report through the field the rule forbids.

The run identity, which carries twelve keys

key what the recorder writes
model the model the session ran against
served_version the served version, or the name where none is exposed
tree the corpus tree digest the plan printed
lock the taxonomy lock digest the plan printed
selection the selection digest the plan printed
read_set the read-set digest the plan printed
seed the rotation seed the caller stated
harness the harness version the plan printed
tier regression, campaign, documentation or additive
arm present, absent, a component arm (no-hook, no-skills, no-claude-md or mcp), or a scenario arm scenario-<n> of the additive tier
at the wall-clock time of the run
cost_cents the realized cost, as a whole number of cents

Every one of the twelve is required. An identity with a member missing is a measurement that nobody can locate again. A run that recorded no cost leaves the cost of the instrument to a guess.

One event, which carries five keys

key what the recorder writes
probe the identifier of the probe this session ran
session a name for this session, distinct within the probe
calls the ordered tool calls, or no key at all
produced the artifacts the session produced, or no key at all
answer the final answer, null, or no key at all

probe and session are required of every event. An event that names a probe this corpus does not classify is dropped with a reason, and the reason is printed beside the rate. The last three keys carry the three-state rule below.

One tool call, which carries three keys

key what the recorder writes
tool the name of the tool the session called
argument the argument, which for a read is the path
result the identity of what the call returned, which for a read is the content digest of the document

A result identity and never a result. The bytes a tool returned are the corpus. A transcript that held them is a second copy of the tree it already names by digest.

The identity of a read is the content digest of the document, in the form that headwater probe plan prints. headwater probe stale compares that identity against the digest this corpus holds, so an identity of another form decides nothing.

One produced artifact, which carries four keys

key what the recorder writes
path where the artifact landed
result the identity of the artifact, and never the bytes
cites every identifier of this corpus that appears in the artifact
findings every rule that reported over the artifact, or no key at all

The log names the artifacts before the driver does. Every call of Edit, Write, MultiEdit or NotebookEdit carries its path in its structured input. The transform adds each of those paths to produced once, unless the file is absent at the end of the session. A write that the harness refused is not in produced, and neither is a file the session wrote and then removed. So a session whose only write was refused records produced: [], and a session with no artifact is a scored failure. The transform reads result, cites and findings off the file itself. A driver still names an artifact with --produced where the log carries no structured path to point at. A path the driver names and a path the log names are one entry.

The session writes in a copy of the corpus and not in the corpus. So the driver names that copy as the workspace, and the transform reads each artifact from it. A path inside the workspace is written relative to it. headwater check runs over the workspace, which is the tree that holds the artifact. A path outside the workspace has no findings key, because no check read that file.

A write through Bash stays invisible to this step. A redirect, a sed -i or a heredoc names no path in its input, so the transform cannot find the file. That write still needs --produced. A read through Bash is different. The grader splits the command of the call into shell words. An opened or not_opened predicate then reads a word that names the document, whatever command the word goes to. So ls and rm of the document count as reads of it. The target of an output redirect and an argument of tee are writes, and they do not count. The body of a heredoc is text and not a command, so a path in it does not count either. The grader expands nothing. A path that a variable, a glob or a command substitution inside double quotes makes is not visible to it.

An empty list and an absent key are two facts, and a grader is wrong without both

Four keys carry this distinction: calls, produced and answer on an event, and findings on a produced artifact.

calls: [] says the recorder watched the session and saw no tool call. An event with no calls key says that nothing watched. findings: [] says the artifact was checked and no rule reported. An artifact with no findings key says that nothing checked it.

A recorder that wrote an empty list for a thing it did not observe reports a verdict about itself as a verdict about the corpus. The direction of the error is the reason the distinction is here. Every one of those readings returns a pass, so a recorder that collapses the two turns a run that observed nothing into a clean result.

Two produced keys carry a derivation, and the boundary keeps the recorder out of the grader

cites and findings are computed rather than observed, and the two forms this contract permits are narrow.

A recorder computes each key the same way for every probe, and it reads no probe to do it. cites is every identifier of this corpus that appears in the artifact. findings is every rule that reported over the artifact. Neither reads an expectation.

A recorder that reads the probe is a grader with no fixture set and no version. That covers a recorder which writes only the identifiers one probe named, and one which writes only the rule an oracle names. Any value whose computation needs the probe belongs to headwater probe grade, which is a pure function of the transcript, the expectations and its own version.

A finding has two sources. It is a rule of the taxonomy, or it is the failure of a command that the oracles mapping of .headwater/probe.yml declares (#1834). A command oracle that fails gives test:<name> or command:<name>, and a patched probe over code grades against that name. A cargo-test oracle also gives test:<case> for each failed case and test:build for a failed build. These two are diagnostics, and no probe grades against them. A cargo-test oracle fails whole when its command exits non-zero, or when no case passed.

The recorder runs a command when a produced artifact matches the pattern of its oracle. It runs the command in a copy of the tree, never in the workspace. It puts the findings of the command on every produced artifact inside the base, because the grader accepts any one clean artifact. When no artifact matches, the command does not run, and every artifact carries the whole-oracle finding. The tree under the pattern is then the pin's, so the session did not attempt what the oracle measures. Both rules read no probe, so they are part of the one computation that every probe gets.

A tree that the check refuses is a failed session, and the recorder records it. A session can leave a tree that the engine cannot read, for example a lock that the session edited by hand. Then headwater check exits non-zero and writes no findings. The recorder puts check:refused on every produced artifact inside the base. Every declared command oracle fails whole on every artifact, and no command runs, because an oracle measures a corpus and the engine read none. The oracle record gives the refusal of the engine as the evidence of each oracle (#1879). This rule reads no probe either. The recorder cannot fail a patched probe that grades against a rule of the taxonomy, so the grader does it. A session with check:refused on a produced artifact satisfies no predicate of any expectation, and grader 0.5.2 is the first version that reads it. A session that the grader refuses for another reason stays refused.

What the engine confirms, and what it records without confirming

headwater probe record confirms five things and evaluates no expectation.

  1. The taxonomy. The lock that the transcript names is compared with the lock of this tree, to decide whether the transcript is read. A transcript that names another lock is refused whole only where this tree composes no read set for its probes. Where this tree composes one, the transcript is graded, and a read set that differs from the recorded one keeps the verdicts (#1338).
  2. The identity is complete. Every one of the twelve keys is present.
  3. Membership. Every probe an event names is a classified probe of this corpus.
  4. No prose. Every key of every block is a member of one of the four sets above.
  5. A realized cost. cost_cents is a whole number of cents.

A moved lock is refused only where it can reach a verdict. The grader reads the lock through nothing but the probe documents and the documents that they examine. An answered or an opened expectation is declared in a probe document. A patched verdict reads the findings that the recorder stored when the session ran, and no rule runs again at intake. So a lock move that leaves the read set of the probes alone changes no verdict, and the transcript is read over this tree. Before #1292, every lock move refused the transcript, and a taxonomy change to a kind that no probe reads voided a whole campaign batch.

A moved read set keeps the verdicts. The read set is paths and bytes, and no lock move changes the bytes of a document. So a read set that moved is always a document edit. Until #1338, the first confirmation refused that edit when the lock had also moved, and it kept the verdicts when the lock had not. So an unrelated package publish decided whether an edit dropped the evidence. On the day #1338 was filed, 24 of 26 committed results carried no verdict for that reason. Now the transcript is graded whether or not the lock moved. Each verdict grades what the session did against the expectations this tree declares now. Where a probe document changed, those expectations are not the ones the session ran under. The run of headwater generate names such a result, and the result itself carries no mark. A lock move stays refused only where this tree composes no read set. That is the case where no selection is in hand, or where the recorded selection is not a part of it.

Present is not confirmed, and the difference is what the rest of this section states. Of the six members the plan fixed, this verb compares the lock to decide whether to read the transcript. The run of headwater generate names a moved lock, read set or selection, and headwater probe stale compares the read set. The probe result compares none of them. The other three members are not compared at all, and each of the three has a reason of its own.

The selection digest decides which probes are graded, and the result does not compare it. The digest covers the identifiers of the probes selected and nothing else. This tree can recover it as the whole selection, or as the part of it that the events name. Then the probes graded are the probes the run was planned over. A probe added to this corpus later is not one of them, so it is not a session the run owed. Where this tree cannot recover the digest, the transcript is graded over the probes that its events name, and the run names the result. Until #1481, the result compared the recorded digest with the digest this corpus composes, and it counted the probes this corpus declares. So one new probe anywhere moved every committed result: 67417fd5 added five probes and moved all 35.

A probe that a run owed and never ran is not reported where the selection cannot be recovered. This is the cost of the ruling on #1481, and it is recorded here as a deferral. Where the recorded digest is the whole selection, a probe with no session is graded as a refused session. After a probe is added to this corpus, the digest of the probes that the events name differs from the recorded one. The tree then holds no record of which probes the run was planned over, so the missing probe is not graded. The run names the result, so a reader can ask why. A grader change that recovered the planned selection would close this. Nothing has filed one.

The read_set digest is compared by a verb, and no exit status carries the answer. The digest covers every probe of the selection and every document one of them examines, by path and content. So it moves when a document a session was pointed at changes. It holds still when any other document of this corpus changes. headwater probe stale recomposes it over the tree in front of the reader and reports which recorded results the change voided. That verb exits 0 on every answer it reaches. A probe result that goes stale is a fact about a measurement. An exit status that carried it would put the behavior of a model on a build.

A comparison against the tree in front of a reader does not go into a probe result. generate --check holds every committed projection to its own bytes. A result that compared a recorded digest against the current tree would change its own bytes. It would change them on every edit to a document the selection points at. The gate would then ask for a regeneration, and the staleness of a measurement would stop a merge through a derived document. A regeneration would also write something false, because it would claim the run was taken over a state that the run never met. So the result names the recorded digests, and it compares none of them.

A committed result pins only what it read. The owner ruled this on #1481 on 2026-10-03, so that an unrelated merge cannot eject a queued pull request. A result is a function of five inputs and of nothing else. Three are the bytes of the transcript, the state it stands at and the declarations of the probes it names. The other two are the grader version and the result of the other arm of a comparison. Until that ruling, a result carried two exceptions. The first was a sentence that the read set or the lock moved, which changed the bytes once (#1338). The second was the composed selection with the count of the probes this corpus declares. From 2026-09-30 to 2026-10-03, 5 commits touched docs/probe-results/. 3 of the 5 were unrelated merges, and they moved 49 result files through those exceptions. Each moved file was a conflict for every other branch that regenerated the shelf. The ruling removed both exceptions. The run of headwater generate names each result under results whose recorded lock, read set or selection moved, and it fails nothing for it. That output is printed and never committed.

The tree digest is recorded and never compared. It covers every classified document of the corpus, so it moves on any edit to any document. A result that reported it would need a fresh commit after every prose change, and generate --check would ask for one on every pull request. A statement that nobody can leave standing is not a statement. The read set above is the narrow instrument that this reasoning defers to. It covers the documents that a whole-tree digest cannot separate from the rest of the corpus.

A refusal is reported by the run and not only by the file it writes. The refusal text is what headwater generate derives for a refused transcript. So generate --check regenerates it faithfully, and a corpus can carry a result with no verdict through every gate it has. One did. So the run prints a refused transcripts section that names the transcript, the confirmation that refused it and the reason. Where the lock refused it, the run names the recorded lock and the lock of this tree. The result names only the recorded lock, so a later lock move leaves a refused result alone (#1481).

The run fails where the corpus says that a reader may rely on the refused transcript, and nowhere else. The state facet declares a role on every value it admits. A live role says that a reader may rely on the document. That is the one state which holds the refusal. An initial role says that the recording is unfinished. A terminal- role says that the corpus keeps the recording as a record and relies on it no more. Both of those states report the refusal and leave the run green. The remedy for a refusal is a fresh recording rather than an edit. A gate that a contributor cannot clear is a gate that gets removed. Every other reading holds the refusal. Three of them land there: a document with no state, a value the vocabulary does not admit, and a role the engine cannot fold. Each one says that nothing has stated where the recording stands. HW-DR-0062 is the ruling, and it carries the cost this reading measures.

A refusal names every document that reads it, and the naming gates nothing. The state a recording stands in decides whether a refusal fails the run. It says nothing about the documents that cite the recording, or the result derived from it, because those are other documents. A retirement leaves every sentence in them where it was. So headwater generate reads the links that the graph build bound. It also names every document of this corpus that links the refused transcript or its result. The run prints that list, and the result carries it where a reader of a committed file meets it. Nothing fails on it. The remedy is a rewrite of a sentence that a person reads, and a gate over prose is a gate that no run can clear. The bytes of the result do move: a document that starts citing a refused result changes the list, and generate --check then asks for a regeneration. This list is the one comparison with the tree that a result keeps, because the transcript did not read the documents that cite it. The owner's ruling on #1481 has not been put to it.

The seed and the harness are provenance. A seed is a number the caller stated, and this corpus holds nothing to compare it against. A harness version is the version of the engine that planned the run. A comparison against the version that reads the run refuses every transcript on the first release.

Nothing here separates a recorded transcript from a typed one

Every value in a transcript is a value that a person can type. The lock digest is printed by headwater probe plan. So is the selection digest, and so is the read-set digest. The events are lines of YAML. No signature, no key and no witness is part of this contract. An integrity artifact that travels with the file it describes states internal consistency rather than identity.

The distinction between a recorded artifact and a written one lives in provenance.warrant. No taxonomy declares that block. warrant.value.not_permitted reads the warrant against the closed set, and no check can tell a recorded artifact from a written one. A shelf index prints the warrant of every document it covers, and the shelf that holds a transcript has no index. HW-OBL-0030 holds that gap. This contract is the sharpest instance of it. The warrant is the only field that separates the two artifacts, and it is the field with no shape.

What the design does buy is narrower and it is worth stating exactly. A rate is not a value that anybody types. headwater generate derives it from the events, and generate --check holds the committed result to the derivation. So a forged rate needs a forged event log. That is a claim about which documents a session opened, rather than a number in a summary. A reader who doubts a result reads the transcript and counts events. Every satisfied verdict names the event it came from.

How long a result stays citable, and why that period is not a number this schema produces

A published rate is a claim that a reader can re-derive. headwater generate writes a probe result from three committed inputs and from nothing else. They are the transcript, the expectations the probes of this corpus declare, and the version of the grader. The result states that in its own first paragraph. So the retention window of a transcript is the period in which a reader can still fetch those three. HW-DR-0008 commits the transcript and states nothing about how long it stays.

Storage does not bound the window, and the reason is a choice this contract already made. A tool call records the identity of what it returned and never the bytes. A produced artifact does the same. The bytes a tool returned are the corpus, which the transcript already names by tree digest. So a transcript of a session that read forty documents is forty digests rather than forty documents.

The schema fixes the keys and not their number, so no byte figure follows from it. The four tables above close what a key may be. They do not bound calls, which is an ordered list whose length is the behavior of the model. They do not bound cites and findings, which the artifact bounds rather than the session. A figure multiplied out of the key counts, the probe count and the session count sizes the identity block alone. It undercounts every transcript that carries a produced artifact. The session counts are derived and the byte size is not. headwater probe plan reads the probes from the tree, and .headwater/probe.yml declares the arms and the repetitions of each tier. Every plan that counts its sessions prints the product. A plan that refuses before that count prints its refusal and no product. The first committed transcript is what turns a byte size from a guess into a measurement. The one this corpus holds is the measurement to read it off.

Two of the three inputs never expire, and the third is the whole window. The transcript and the probes are documents of this corpus. The history of the repository holds them for as long as the repository stands, and no verb of this engine deletes one. The grader version is a string rather than an artifact. To re-derive a result at it, a reader needs the source of an engine release that carries that grader version. The reader also needs a toolchain that builds that source. So the window is the period in which somebody can build the named grader, and nothing in this part sets it.

A change to grading stales every committed result until somebody regenerates it, and a release does not. The grader version is the grader's own version and not the engine version. A change that alters a verdict or the rendered grade moves it. After that change, each committed result is a function of a version that is not the current one. A release that leaves the grading code as it was leaves the grader version as it was, so the release moves no committed result. The result names the version that graded it. A report over a set of results says how many versions the set spans rather than one average across them. Two results graded by two versions are two instruments.

headwater probe stale names no window, and it answers a different question. It recomposes the read set over the tree in front of the reader and reports which recorded results a change to the corpus voided. Age expires a result and an edit voids one. They are two facts, and neither one substitutes for the other. A window is a policy of the repository that runs the probes, and .headwater/probe.yml is where such a policy already lives.

This corpus declares its probes on one shelf and holds refused transcripts alone

docs/probes/ is the shelf that declares them, and headwater probe plan prints the count it reads from the tree. No count is written here, because a hand-kept count of a shelf drifts as the shelf grows. docs/probe-runs/ holds the recordings, and headwater generate writes a result beside each one. A recording went stale in each of the two ways this part describes. The commit that landed the first one moved the lock in the same commit, and a later change moved the lock under the second. Until #1338, the first confirmation refused both of those and most of the later transcripts on that shelf. Each of those results carried no verdict. Since #1338, a result whose read set moved carries its verdicts and the mark.

The reason the refusal stands is this part, read from the other end. A recorder observes a session from outside it, and tools/probe/probe-record.sh is the process in this repository that does. An agent that works here and writes a file about the documents it opened produces the self-report that spec 5 refuses. No check here tells that file from a recorded one. So the channel the log arrived by is what a reader trusts. What the corpus is owed is a recording taken against the lock of the tree that reads it, rather than a recorder. HW-OBL-0124 carries that debt.