Execution Replay Architecture
How a replay adapter proves that its supported execution boundary used the frozen evidence plan, without exposing private evidence or claiming control over an entire workflow.
Conceptual architecture: the adapter owns declared runtime interception and private evidence materialisation; AIGP owns frozen replay semantics and acceptance validation.
Purpose & Boundary
Execution replay is an opt-in contract for runtime adapters that can return recorded evidence at a declared execution boundary. It is used when a Causal Audit needs more than a reference replay: it needs evidence that the supported calls matched a frozen plan and that the approved intervention was applied as requested.
A bounded guarantee
Execution replay does not mean AIGP can intercept an arbitrary agent workflow. The guarantee applies only to the boundaries named by the adapter's capability declaration. A tool interceptor is not, by itself, a sandbox or proof that custom code, direct provider calls, or hosted tools were controlled.This is a reusable architecture, not a LangGraph specification. A framework adapter can implement it only if it can make its supported boundary explicit, preserve private evidence in its own environment, and return the typed evidence needed for the worker to validate the result.
Architecture
Frozen replay manifest + intervention binding → evidence resolution plan → adapter intercepts its declared boundary → resolver returns recorded evidence or one approved replacement → adapter returns trace + attestation → replay worker validates returned evidence → Causal Audit accepts or fails the result
| Part | Owns | Does not own |
|---|---|---|
| Plugin API contracts | Versioned capability, plan, tool identity, resolution, trace, and attestation shapes. | A framework-specific interceptor or private evidence access. |
| Runtime adapter | Its declared interception boundary, private evidence lookup, and typed execution report. | Expanding the declared boundary after the replay begins. |
| Evidence resolver | Matching, dependency checks, atomic consumption, divergence recording, and intervention selection. | Executing an original production tool. |
| Replay worker | Comparing returned evidence with the frozen configuration before accepting a result. | Trusting an adapter's completion flag without verification. |
Capability Declaration
An adapter declares execution replay through a versioned capability. The declaration names supported execution boundaries and unsupported surfaces, identifies supported argument-digest algorithms and trace limits, and states whether the adapter supports asynchronous, concurrent, retry, or subgraph execution. For evidence-only replay it also declares that recorded evidence is used, unobserved calls fail, and no original-tool fallback is available.
This declaration is a compatibility contract. It tells AIGP what the adapter is prepared to prove; it does not turn an unsupported surface into a safe one. A reference replay adapter can remain useful without declaring execution replay.
Frozen Resolution Plan
Before work begins, the control plane freezes an immutable evidence resolution plan and binds it to the replay manifest and approved intervention. The plan is a checklist of the historical calls that may be resolved during this replay.
Each planned call carries bounded identity data:
- A stable planned-call ID and occurrence number.
- A canonical tool identity: scope, symbol, and schema version.
- A canonical argument digest, not the raw arguments.
- Dependency call IDs, where ordering matters.
- A durable evidence reference and digest.
The intervention binding identifies one planned call and its approved alternate evidence. It is not a new tool invocation. If that target is never reached, the session is incomplete rather than silently successful.
Resolution & Divergence
When the adapter reaches a declared boundary, it supplies the observed tool identity and canonical argument digest to the resolver. In one protected operation, the resolver matches the call, checks dependencies, consumes the matching planned call, selects recorded or approved replacement evidence, and records the outcome. This makes concurrent duplicate attempts unable to consume the same planned evidence twice.
| Situation | Resolver result |
|---|---|
| Matching planned call | Returns recorded evidence, or the one frozen approved replacement. |
| Duplicate concurrent call | Only one attempt can consume the planned call; the other diverges. |
| Missing planned call or intervention | Finalization reports an incomplete session; it cannot produce a successful execution replay attestation. |
At the declared boundary, a replayed tool call receives recorded evidence, one approved replacement, or a fail-closed divergence. Private evidence stays in the adapter environment.
Trace & Worker Validation
A resolver summary is necessary evidence, but it is not an acceptance decision. The adapter returns a bounded execution trace and attestation. The replay worker validates them against the frozen manifest, resolution plan, intervention binding, declared boundary coverage, and evidence-only safety declaration.
Before accepting an execution replay result, the worker checks that:
- Returned tool identities and consumed calls match the frozen plan.
- All required planned calls are accounted for and the trace is internally consistent.
- The authorised intervention was applied exactly once to its bound target.
- Trace and attestation digests match the returned evidence.
- Coverage and safety declarations are compatible with the requested replay.
Completion is not acceptance
A field such ascomplete: true is an adapter report, not proof. Missing, failed, incomplete, or inconsistent evidence follows the existing replay failure path and does not produce a successful Causal Audit attestation.Private Evidence
The control plane receives only the references, schema identifiers, canonical argument fingerprints, digests, and bounded reports needed to validate the contract. Private prompts, raw tool arguments, raw tool results, credentials, and replacement content remain with the runtime's evidence store.
An adapter must resolve private evidence using its own tenant and project access rules. A digest confirms that the returned evidence matches the frozen reference; it does not disclose the content or grant the control plane access to it.
Adapter Conformance
A new framework adapter should preserve existing reference replay compatibility and introduce execution replay only as an explicit, versioned capability. It should test both successful and rejected paths before advertising a boundary.
- Declare only boundaries the adapter can actually intercept.
- Bind the frozen plan, intervention, evidence, trace, and attestation to the same tenant and replay manifest.
- Reject unknown, mismatched, duplicate, and dependency-invalid calls without executing a fallback tool.
- Test asynchronous and concurrent resolution where the framework supports it.
- Return no raw private evidence in trace, diagnostics, fixtures, or logs.
- Document unsupported surfaces and the runtime's isolation limits.
Read Agent Runtime Integration for the ingestion contract, Replay Manifests for eligibility, and Controlled Replay Framework for the durable lifecycle. Adapter authors should use Replay Adapter Development for the implementation specification. The LangGraph ToolNode guide is one concrete, bounded implementation.
