Part 2 — Modeling  ::  Chapter 11

2.7 Provenance Models: What Happened, and What Evidence Records It?

When an autonomous system changes a user's artifact, completion is not the only fact worth preserving. Engineers and users may need to know what changed, which operation changed it, and why. A provenance model represents that history as structured evidence rather than prose reconstructed after the fact.

MODEL CARD

Attribution model · Provenance

Figure 2.7-1 draws a reduced provenance model: a run contains operations, and each operation names a target, a mutation, the pass responsible, and the evidence it left. This is not a trace of every function call — that would reproduce implementation history rather than model it. The representation selects the events that matter to engineering explanation and audit.

DocAble's attribution provenance model: a run of operations, each with recorded fields A run contains operations. Each operation records its target, mutation, responsible pass, and retained evidence. This structured record carries the provenance model. A small secondary line shows the uses derived from it: audit, debugging, and changelog. The model is primary; the derived uses are secondary. THE PROVENANCE MODEL RUN one run, many operations OPERATION* each records target mutation pass evidence derived uses (secondary) audit · debugging · changelog The structured record carries the provenance model; audit, debugging, and changelog are derived from it, not maintained apart.
Figure 2.7-1. Attribution provenance model. A run contains consequential operations; each operation records its target, mutation, responsible pass, and retained evidence. Audit and explanation can be derived from this shared history.

From those events the system derives its other views. A human-facing explanation is not maintained as an independent account of what the system did; it is derived from the structured action record. Record once; derive the explanations. That architecture reduces a familiar source of inconsistency — implementation changing while the documentation describing it follows a separate path.

2.7.1 Provenance Is Modeled History

Recording history is not the same as modeling it. An execution offers far more than an engineer wants to keep — function calls, allocations, retries, intermediate values, model requests, filesystem operations — and capturing all of it produces no useful provenance model. Provenance begins when the engineer chooses which events deserve stable identities for explanation and audit. For DocAble that boundary sits at the consequential mutation: the edit record states what changed, its target, and the evidence the operation left, and suppresses most of the computation that produced it. That reduction makes the history useful for audit and replay rather than merely exhaustive.

The choice of grain is therefore part of the model. Pitch it too coarse and distinct consequential changes collapse into an opaque "document modified" event. Pitch it too fine and the record becomes another execution trace an engineer or agent must reconstruct into meaning. The useful grain answers the engineering questions the model exists for: what changed, why, and can this be reproduced?

2.7.2 A Record Can Be Executable Without Becoming the Implementation

DocAble's edit record has an unusual property for a provenance model: it runs. During a remediation session the PDF path records document mutations as typed PdfEdit values in a per-session log — roughly thirty variants covering the changes the editor can make. A replay engine applies that same sequence to an open document deterministically, so the record that explains a completed remediation can also reproduce it.

Executability does not make the record a complete behavioral model of the remediation system. It still omits the reasoning, analyses, control decisions, retries, and computations that produced those edits. The record says which consequential mutations happened, not why the system chose them.

Record and replay separate three questions that are easy to conflate. The computation graph asks what computations may compose. The provenance record says which consequential mutations did occur. Replay adds a third: given that realized history, reproduce its effects. No one of these representations subsumes the others.

The two representations are not joined today. A PdfEdit's node identifier names a PDF structure element, not a computation-graph node, so a shared field name does not connect them. For a TypedPatchProducer, though, the runtime edits are the realized output of a modeled computation. Attributing those records to the producing computation identity would let one execution record be read against the static graph. DocAble keeps that design option open without taking it.

Figure 2.7-2 sets the two representations side by side.

Computation structure versus realized history Two reductions of the same remediation system, side by side. Left: the static computation graph — named passes joined by a typed data edge and a typed control gate, modeling what computations may compose. Right: one session's edit record — a run that emits a sequence of typed PdfEdit operations, recording what mutations did occur. A dashed link between them marks that they are not joined today; a shared computation identity would join them, and the join is added when a question needs it. Computation graph what computations may compose Edit record what mutations one run did emit Analyze pass Remediate pass Route gate DATA_FLOW CONTROL_GATE Session run PdfEdit · SetAltText PdfEdit · TagFigure PdfEdit · SetReadingOrder not joined today static structure realized history
Figure 2.7-2. Computation structure versus realized history. The computation graph models declared computations and their typed composition; the per-session edit record logs the consequential mutations one run actually produced. They remain separate reductions today. A shared computation identity could join runtime edits to the static model when an engineering question requires that relation, without collapsing the two representations into one.

There is an important limit, and it is worth stating precisely. A provenance model does not guarantee that every consequential operation actually records its attribution. That is an Alignment question. DocAble addresses it separately, by requiring typed mutation verbs to emit attribution records and checking that obligation structurally; Part III examines that mechanism. Part II models the evidence the operation should leave; Part III asks what mechanism, if any, gives that obligation authority.

The next and final chapter of this Part steps back from any single model to ask how the six fit together as a system.

© James C. Davis, 2026–present