ADR-298: The invocation history binds a check to its proposal
- Status
-
Accepted
- Date
-
2026-11-15
- Amends
-
ADR-216 (a history entry may carry a keyed digest of the call's arguments and of the record state the call observed) and ADR-297 (a page metadata write is bound to a passed check of its proposal instead of a read and an unchanged
tstamp) - Authors
-
Netresearch DTT GmbH
Context
A tool invocation rule sees the earlier calls of its run through
Tool (ADR-216): tool, outcome and target
per entry. That is enough for "a read ran before the write". It is not enough
for "the check ran on exactly this proposal, and the record is still what the
check saw": the history does not say with which arguments a call ran, nor what
it observed. A model can check one variant and write another, or check, wait
while an editor changes the record, and write; a rule cannot tell either from
a correct sequence.
Time does not close the second gap. A TYPO3 record's tstamp is the
EXEC_ of the request or process that wrote it, its start and not the
moment of the write, so a writer that started before the check and wrote
after it leaves an older stamp than the check.
The history is persisted inside the sealed suspended state of a run
(ADR-114), next to the pending calls, and
Tool is @api.
Decision
An entry may carry arguments and state. Both are digests:
v1: followed by the hex HMAC-SHA256 of a canonical form, keyed with the
installation's encryption key (SYS/) joined with a purpose
string of nr-llm, the construction TYPO3's Hash uses. Each field
has its own purpose string (nr_ and
nr_), so an arguments digest never equals a
state digest of the same value. PHP's hash_ computes it,
because TYPO3 13.4's Hash offers SHA-1 only. An empty encryption
key gives no digest.
argumentsis the digest of the call's final arguments, after any input a human typed (ADR-216 item 5). The runtime fills it at everyappendwhose arguments can be encoded.() stateis the digest of a record state a tool observed: the canonical form of an object with the table, the uid, and the listed fields as a map from field name to value (so their order does not matter). Only anokresult carries one;withon an error result is ignored, asObserved State () withis.Write Target ()
One public class, Invocation, computes both.
arguments returns the digest of an arguments map, or null
when it cannot be encoded. observe reads
the record as the workspace of the run shows it (ADR-260,
the workspace the writing tools write into), takes exactly the listed
fields, writes each value as a string (null stays null), and returns
an Observed. It returns null, and so no digest, when that
workspace shows no such row (deleted, a version of another workspace, a
table without versioning seen from a draft workspace), the table is unknown,
the field list is empty, or a listed field is not a database column of the
table. It reads with the deleted restriction only, so a hidden record has a
state. Observed holds the digest and the field values it was
computed from, as the public readonly properties digest and
values; its constructor is @internal and refuses anything but the
v1: format, so tools take one from observe. A tool reports it through
Tool, kept as the public
readonly property observed and carried by every Tool
wither, and the runtime copies its digest into the entry.
A rule computes arguments of the call in front of it and
observe of the same record and fields now, and compares both with the
most recent ok entry of the check tool, so a later check of another
variant replaces an earlier one. Equal means the same final arguments and
the same fields as the run's workspace shows them. When either returns
null at that moment, the rule refuses. Which fields count is the tool's
and rule's shared declaration: the fields the check judged, not tstamp, which a
hook moves without a relevant change (the same reason
ADR-184 gives).
Canonical form, version 1. The JSON encoding of the value, where an
array that is not a list has its keys sorted as strings
(ksort) and stays an object, and a list keeps its order.
Slashes and Unicode are not escaped, integers and numeric strings stay apart,
floats are written with serialize_, and a float without a
fraction whose magnitude is below 2^53 is written as an integer (-0. as
0): a suspended state does not keep the fraction, so 1. and 1
must not differ across a resume. PHP writes larger integral floats up to
about 1e17 without a fraction as well, so they share the digest of the
equal integer, as they do after a resume; every other float keeps its JSON
float form. Whether an array is a list is decided before its keys are sorted. A
value that cannot be encoded (JSON_) gets no digest. A new
canonical form is a new version prefix.
What a digest is for. The history already lies in a sealed store next to the arguments themselves, so keying adds no secrecy there. It keeps a digest meaningless outside its installation and useless for guessing short values should it ever leave that store, at the cost of one HMAC per entry.
The stored format stays compatible. Both keys are optional, and an
entry without a digest omits the key; it is never stored as null. An
entry stored before this change has neither; a rule that needs a digest
treats a missing one as not matching and refuses. A present key must match
^v1:; any other value, an unknown version included, makes
the whole history unreadable and incomplete, as a malformed entry does today.
A runtime before this change drops both keys when it rebuilds the entries,
which again fails closed.
The public surface grows additively. Tool
gains two optional trailing ?string parameters (null omits the
key), an entry's array shape gains the two optional keys, Tool
gains with and the property
observed, and
Invocation and Observed are public, so that a tool and a
rule, in nr-llm or outside it, compute the same digests.
A check tool judges the values of the Observed it reports and
reads the record no second time, so its verdict and its digest describe the
same snapshot. A record changed and changed back between two reads cannot
make a check pass on values it never judged. A
binding rule does not require a complete history
(requires is false): an incomplete history after a
retry still holds the check the model makes next.
A binding rule is asked when the call runs. Its answer depends on the
history, which before the approval card does not hold the calls of the same
turn, so it does not implement Pre
(ADR-293). The write runs after the check of the same
turn and is compared then; in a run with a pinned process the check may
already have run before the card, which changes nothing for the rule.
The first users are a check tool and the contract rule of the A2A page
metadata skill: a write of the skill must be preceded by a successful check
of exactly its arguments, and the record must still be in the state that
check observed. The check tool takes exactly the write tool's arguments, so
the same map can be checked and written. A check whose verdict is negative
reports failed, so only a passed check counts.
Consequences
- ●● A rule can require that a check ran on the very proposal being written and that the record has not changed since; checking one variant and writing another, and writing over a changed record, are refused before the write runs. No clock is compared. A change between the rule's comparison and the write itself is not seen, as with ADR-184.
- ◑ The refusal comes after the approval: an editor can approve a write that is then refused, and nothing is written. After an ADR-184 re-ask the second approval can be refused the same way.
- ◑ Old suspended states keep resuming; their entries have no digest, so a binding rule refuses until the model checks again.
- ◑ Rotating the encryption key, or changing the canonical form, invalidates the digests of waiting runs; a binding rule asks for a new check, the conservative direction.
- ◑ The tool and the rule must declare the same fields; the shared class makes the read and the digest identical, not the choice of fields. A field outside the list can change without being noticed, as with ADR-184.
Net Score: 0
Alternatives considered
Store the arguments. Rejected: ADR-216 item 7 keeps policy metadata from copying arguments, and a second copy in the history serves no rule better than a digest.
Compare clocks. Rejected: a record's tstamp is the writer's start
time, so "changed after the check" cannot be told from it.
A plain SHA-256. Rejected for the reasons above; it would also make digests comparable across installations.
Bind through the target only. Rejected: a target names the record, not the values; two variants for the same record share it.