16 Record what happened and why

A record is useful when it lets someone answer a question that would otherwise remain uncertain. What was requested? Which interface was used? What response was returned? Which decision authorized a change? What state was actually observed afterward?

Puma's interest in ledgers and information graphs grows from these questions. The ambition is broader than logging errors. It includes preserving the relationship between intent, decisions, execution, and evidence so later agents and people can inspect it.

The first design task is deciding what the record can honestly claim.

Separate observation from interpretation

Suppose an agent calls an acquisition operation and receives a timeout. An observer can record the request and response. It cannot infer from that exchange alone that acquisition failed, that publication did not occur, or that the caller was wrong to make the request.

Those conclusions require other evidence. A later state lookup may show publication completed. A policy engine may report that the operation was unauthorized. A reviewer may conclude that the requested identity did not match the intended resource. These should be attributable additions, not retroactive replacements for the observed interaction.

Puma's proposed recorder design makes this distinction important: recording communication does not require the observer to decide whether an operation was malformed or semantically valid. If an interface supplies information about what should be retained, that is a separate contract. The proposal also keeps observer reporting out of the evaluated agent's input, so the act of recording does not silently become additional feedback. This is a stated design requirement, not a claim that every recorder implementation already has it.

A minimal event can be enough

For the running example, a useful record might contain an event identity, time, actor identity, operation identity, target resource, relevant revision, and a reference to the request or result. A state observation should identify what was observed and when. A decision record should identify its authority and the alternatives or consequences it preserves.

Do not add fields simply because a graph can store them. Each field creates collection, retention, interpretation, and migration obligations. A record of every byte may be expensive and may retain information nobody needs.

The W3C provenance model offers vocabulary for entities, activities, agents, derivation, and attribution. It can help distinguish relationships without prescribing one storage design. A vocabulary is not evidence that the resulting graph is complete or useful for a particular development task. PROV Data Model.

Reasons are claims too

A person or model may explain why a choice was made. Preserve that explanation as an attributed account. Do not assume it captures every influence on the decision.

Research on reasoning faithfulness shows that model explanations can omit information that influenced answers in the studied settings. Those experiments do not establish a universal omission rate for coding agents. They do justify keeping a generated rationale distinct from the observable interaction and resulting state. Reasoning Models Do Not Always Say What They Think.

This distinction makes records more useful, not less. A reviewer can compare an asserted reason with the available evidence and identify a mismatch. If the record treats rationale as unquestionable truth, it prevents that comparison.

Preserve the question across changing representations

An interface version can change field names or available operations. A plan can be superseded. A source artifact can move. If the record only stores mutable labels, later readers may reconstruct the wrong context.

Stable identities and revision references help, but they should be used where they support a real reconstruction need. Not every transient observation requires a permanent globally meaningful identifier. The design should balance traceability with the cost of maintaining identity across the system.

A ledger also needs to distinguish correction from erasure. A later observation may resolve an uncertain outcome without making the original uncertainty disappear. Keeping both lets someone understand what was knowable at the time and why the next action was reasonable.

Test the record by asking a difficult question

Take one completed operation and try to reconstruct it using only the retained evidence. Which request led to it? What authority applied? Which implementation revision ran? What result was observed? What remains unknowable?

Then remove one event from the exercise. Can the record detect the gap, or does it silently imply continuity? A long log that cannot expose missing coverage may be less trustworthy than a short record that states its limits.

The purpose of provenance is not to make every decision look justified afterward. It is to preserve enough context that a later reader can understand, challenge, and improve the work.