---
title: "ADR-298: The invocation history binds a check to its proposal"
manual: "LLM Foundation"
version: "main"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-llm:adr-298@main"
source: "Adr/Adr298TheInvocationHistoryBindsACheckToItsProposal.rst"
rendered: "2026-11-18T02:03:14+00:00"
---

# ADR-298: The invocation history binds a check to its proposal {#adr-298}

-   *Status:* Accepted
-   *Date:* 2026-11-15
-   *Amends:*

    [ADR-216](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-216@main) (a history entry may carry a keyed digest
    of the call's arguments and of the record state the call observed)
    and [ADR-297](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-297@main) (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 {#context}

A tool invocation rule sees the earlier calls of its run through
`ToolInvocationHistory` ([ADR-216](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-216@main)): 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_TIME` 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](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-114@main)), next to the pending calls, and
`ToolInvocationHistory` is `@api`.

## Decision {#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/encryptionKey`) joined with a purpose
string of nr-llm, the construction TYPO3's `HashService` uses. Each field
has its own purpose string (`nr_llm.history.arguments` and
`nr_llm.history.state`), so an `arguments` digest never equals a
`state` digest of the same value. PHP's `hash_hmac()` computes it,
because TYPO3 13.4's `HashService` offers SHA-1 only. An empty encryption
key gives no digest.

-   `arguments` is the digest of the call's final arguments, after any input
    a human typed ([ADR-216](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-216@main) item 5). The runtime fills it at
    every `append()` whose arguments can be encoded.
-   `state` is 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 an `ok`
    result carries one; `withObservedState()` on an error result is ignored,
    as `withWriteTarget()` is.

**One public class,** `InvocationDigests`, **computes both.**
`arguments(array)` returns the digest of an arguments map, or `null`
when it cannot be encoded. `observe(table, uid, fields, execution)` reads
the record as the workspace of the run shows it ([ADR-260](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-260@main),
the workspace the writing tools write into), takes exactly the listed
fields, writes each value as a string (`null` stays `null`), and returns
an `ObservedState`. 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. `ObservedState` 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
`ToolResult::withObservedState(ObservedState)`, kept as the public
readonly property `observedState` and carried by every `ToolResult`
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](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-184@main) 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(SORT_STRING)`) 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_precision -1`, and a float without a
fraction whose magnitude is below 2^53 is written as an integer (`-0.0` as
`0`): a suspended state does not keep the fraction, so `1.0` 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_THROW_ON_ERROR`) 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:[0-9a-f]{64}\z`; 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.** `ToolInvocationHistory::append()`
gains two optional trailing `?string` parameters (`null` omits the
key), an entry's array shape gains the two optional keys, `ToolResult`
gains `withObservedState(ObservedState)` and the property
`observedState`, and
`InvocationDigests` and `ObservedState` 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 `ObservedState` 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
(`requiresCompleteHistory()` 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 `PreApprovalInvocationRuleInterface`
([ADR-293](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-293@main)). 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 {#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](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-184@main).
-   ◑ 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](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-184@main).

Net Score: 0

## Alternatives considered {#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.
