v1.2.7

Replay Adapter Development

A vendor-neutral implementation guide for adapters that support AIGP execution replay at a declared runtime boundary.

Purpose & Prerequisites

This page is for engineers building an adapter for LangGraph, OpenAI Agents SDK, Google ADK, or another agent runtime. It explains the implementation contractβ€”not the Causal Audit user workflow. Read Execution Replay Architecture first for the control-plane model, then use this page to build and test the runtime-owned part.

Start with one declared boundary

A useful adapter does not need to intercept every runtime surface. Begin with a boundary you can actually observe and replace safely, such as one framework tool dispatcher. Declare custom nodes, direct SDK calls, hosted tools, and any other uncontrolled surface as unsupported.

You need all of the following before advertising execution replay:

  • A stable way to capture historical tool-call identity and safe evidence references.
  • A runtime-owned private store for raw arguments and evidence content.
  • A framework hook that can return recorded evidence without calling the original tool.
  • An independently installable plugin package using the public Plugin API.
  • Tests for successful, rejected, concurrent, and incomplete paths.

Adapter Architecture

Observed runtime execution
  β†’ capture bounded ToolCall evidence
  β†’ store private snapshot in runtime environment
  β†’ receive frozen plan from replay worker
  β†’ intercept declared framework boundary
  β†’ resolve planned evidence in memory
  β†’ materialise private evidence locally
  β†’ return trace + attestation to AIGP

Keep these responsibilities separate. The control plane creates the replay manifest, intervention, and frozen plan. Your adapter resolves its opaque runtime reference, intercepts only the boundary it declares, and materialises private evidence locally. The replay worker validates your bounded report; it does not enter your runtime or execute an original tool.

Conceptual adapter flow: only the adapter's declared runtime boundary is intercepted, and the resolver returns an outcome rather than calling the original tool.

Plugin API Integration

Install the public package. An external adapter must not import AIGP OSS services, repositories, or persistence models.

python -m pip install 'bhanuj-governance-plugin-api==1.2.0rc1'

Register the independently installed plugin through the canonical entry-point group:

# pyproject.toml
[project.entry-points."bhanuj.governance.plugins"]
my-runtime = "my_runtime.plugin:plugin"

A replay adapter implements the public ReplayExecutionAdapterprotocol. The host selects it by the versioned contribution nameadapter_id/adapter_version.

from bhanuj_governance_plugin_api import (
    ReplayExecutionAdapter,
    ReplayExecutionContext,
    ReplayExecutionResult,
)


class MyRuntimeReplayAdapter(ReplayExecutionAdapter):
    @property
    def name(self) -> str:
        return "my-runtime/v2"

    def validate_configuration(self, source_execution: object, configuration: object) -> None:
        # Reject a source or configuration this adapter cannot safely handle.
        ...

    def replay(
        self,
        source_execution: object,
        configuration: object,
        context: ReplayExecutionContext,
    ) -> ReplayExecutionResult:
        plan = context.execution_replay_resolution_plan
        if plan is None:
            raise ValueError("Execution replay requires a frozen resolution plan.")
        # Resolve the runtime-owned snapshot and run only the declared boundary.
        ...

Preserve reference replay compatibility

Execution replay is opt-in. Do not replace an existing reference replay adapter with a new incompatible path. Keep the legacy adapter identity available, then introduce a separate versioned execution-replay identity when the semantics differ.

Execution Capture

Capture historical calls while the original runtime executes. A future replay can only resolve what you captured and bound to the source execution. Do not infer a tool call from a graph node or a model message; record a tool call only when the runtime actually reaches the tool boundary.

For every replayable call, retain these bounded values in the control-plane record:

  • Runtime call ID, graph or subgraph scope, tool symbol, schema version, and occurrence.
  • Canonical argument fingerprint with its algorithm, canonicalization, and key version.
  • Dependency and retry links when the framework exposes them.
  • Private evidence reference, response digest, and result-schema identity.

Use the public canonicalization helper. New persisted fingerprints containing sensitive or low-entropy arguments should use the tenant- and project-scoped HMAC algorithm rather than a plain hash.

from bhanuj_governance_plugin_api import (
    ToolArgumentDigestAlgorithm,
    create_tool_argument_digest,
)

argument_digest = create_tool_argument_digest(
    runtime_arguments,
    algorithm=ToolArgumentDigestAlgorithm.HMAC_SHA256_JSON_V1,
    organization_id=organization_id,
    project_id=project_id,
    key_version="v1",
    key_provider=runtime_owned_key_provider,
)

The key provider stays inside your runtime. Only the digest algorithm and non-secret key version cross the Plugin API boundary.

Snapshot Management

Your runtime owns the private snapshot. It may contain raw arguments, recorded evidence, replacement evidence, and framework state needed to reach the declared boundary. AIGP receives only its opaque replay reference, integrity bindings, evidence references, and digests.

RequirementResponsibility
Tenant bindingBind the snapshot to organization, project, source execution, manifest hash, and adapter identity.
IntegrityVerify the selected private evidence against the frozen digest before returning it.
AccessExpose private content only to the runtime process that performs the declared replay boundary.
RetentionDefine your own retention, deletion, recovery, and backup policy. AIGP does not manage snapshot content.

Resolution Plan

The worker supplies an immutable EvidenceResolutionPlan inReplayExecutionContext.execution_replay_resolution_plan. Do not rebuild it from a snapshot, append to it, or change it while replaying. Its canonical digest binds the tenant, source execution, replay manifest, capability, planned calls, and evidence bindings.

A ReplayToolCall identity includes scope, tool symbol, tool-schema version, argument digest, occurrence, retry relationship, and dependencies. It deliberately excludes scheduler timing: independent calls may arrive in another order, while repeated calls remain distinguishable.

Tool Interception

Hook the narrowest framework surface that receives native tool calls. Replace the original implementation with a resolver-backed function at replay time; do not register the historical tool as a fallback. The resolver returns only a selected evidence reference and digest. Your private evidence store materialises the content after that successful selection.

from bhanuj_governance_plugin_api import (
    ExecutionReplayResolver,
    ReplayResolutionOutcome,
)

resolver = ExecutionReplayResolver(plan, intervention_binding)
resolution = resolver.resolve(
    attempted_call,
    intervention_digest=intervention_binding.intervention_digest,
)
if resolution.outcome not in {
    ReplayResolutionOutcome.RESOLVED_RECORDED,
    ReplayResolutionOutcome.RESOLVED_INTERVENTION,
}:
    raise RuntimeError(f"Replay call failed closed: {resolution.reason_code}")

content = private_evidence_store.materialize(
    resolution.selected_evidence_reference,
    resolution.selected_response_digest,
)

The resolver never invokes tools, fetches private evidence, contacts a provider, or mutates the plan. The adapter supplies those framework-specific pieces inside its own boundary.

This boundary applies to the framework surface an adapter explicitly supports. It does not claim interception of custom nodes, direct provider calls, or hosted tools.

Controlled Intervention

The existing intervention policy authorizes the evidence change. TheReplayInterventionBinding narrows that approval for the resolver: it binds one replacement reference and digest to one planned call, one manifest, and one resolution-plan digest. It does not transform evidence or create a new tool call.

Apply the replacement only when the bound target call is resolved, and only once. If the target is never reached, finalization is incomplete. If a different call requests the intervention digest, fail closed with an intervention mismatch.

Parallelism & Subgraphs

Declare support conservatively. Async tools, concurrent execution, retries, and subgraphs are independent capability flags. Setting one to truedoes not imply the others.

  • Resolve matching, dependency validation, and plan consumption as one protected operation.
  • Allow dependency-free calls to resolve in either order when the framework schedules them in parallel.
  • Reject a dependent call until every declared predecessor is consumed.
  • Represent retries explicitly; a retry must retain the original canonical tool identity.
  • Use distinct scope IDs for nested graphs only when your adapter can capture and replay that scope reliably.

Optional does not mean unsupported forever

A useful first adapter can set subgraphs or concurrency to false. Add them only with matching capture, interception, and conformance tests.

Divergence Handling

The resolver returns stable, bounded reason codes. Convert them into safe runtime failures; do not log raw arguments or substitute an original tool call.

ConditionRepresentative ReasonResponse
Unknown callUNOBSERVED_TOOL_CALLStop the supported replay boundary; never invoke the original tool.
Identity or argument mismatchTOOL_IDENTITY_MISMATCH or ARGUMENT_DIGEST_MISMATCHRecord bounded divergence and fail the replay.
Duplicate or premature callDUPLICATE_TOOL_CALL or DEPENDENCY_VIOLATIONDo not consume evidence twice or bypass the dependency graph.
Invalid replacementINTERVENTION_MISMATCHDo not choose alternate evidence outside the frozen binding.
Unfinished sessionINCOMPLETE summaryReturn the incomplete trace; do not attest success.

Attestation & Validation

Finalize the resolver session, build a typed ReplayExecutionTrace, and return a typed ReplayExecutionAttestation with the replay result. The attestation binds the manifest, plan digest, intervention digest, Phase 1 safety digest, trace digest, declared and exercised boundaries, and resolution counts.

return ReplayExecutionResult(
    execution_status="COMPLETED",
    final_state={"causal_audit_outcome_score": outcome_score},
    artifact_refs=(outcome_reference,),
    runtime_parameters={"evidence_only": True},
    metadata={"evidence_only_replay_safety": safety_metadata},
    execution_replay_trace=trace,
    execution_replay_attestation=attestation,
)

The worker reconstructs the expected plan from frozen configuration. It validates every returned identity, evidence selection, intervention target, digest, count, coverage declaration, and blocking divergence. It accepts only a complete resolver summary in which every planned call was consumed and the intervention was applied exactly once. complete=True alone never passes this check.

Conformance Testing

Run these tests before declaring execution replay capability:

TestExpected evidence
Recorded pathA declared call returns digest-verified recorded evidence; the original implementation counter remains zero.
Intervention pathThe bound call returns only the approved replacement and records exactly one intervention.
Mismatch pathUnknown tool, arguments, occurrence, retry, or dependency fails closed without original-tool execution.
Concurrency pathIndependent calls resolve safely; duplicate concurrent calls cannot consume the same evidence twice.
Completion pathMissing planned calls or a missing intervention produce an incomplete result, not a successful attestation.
Worker rejection pathMissing or inconsistent trace, attestation, safety metadata, coverage, or digest reaches the existing replay failure path.
CapabilityRef Adapter v1LangGraph ToolNodeNew Adapter
Precomputed-score reference replaySupportedNot its purposeOptional
Actual tool interceptionNoDeclared ToolNode onlyDeclare exact boundary
Historical evidence substitutionReference-score basedRecorded evidenceRequired for tool replay
Async and parallel callsNot applicableSupportedCapability-dependent
Custom-node interceptionNoNoNever assume
Trace and worker validationReference contractExecution replay contractRequired when declared

Security Boundaries

Execution replay is not sandboxing. An adapter cannot claim control over arbitrary custom nodes, direct HTTP, database, SDK, subprocess, or provider-hosted tool calls unless it explicitly intercepts and attests to each declared boundary. A private snapshot store also does not authorize production access or make an unsafe tool safe.

  • Never include raw private evidence in trace, attestation, diagnostics, fixtures, or logs.
  • Never treat a manifest hash, snapshot digest, or adapter report as independent proof of external state.
  • Use replay IDs as idempotency keys in the runtime-owned environment.
  • Fail when tenant, adapter identity, manifest, snapshot integrity, or declared boundary does not match.
  • State unsupported surfaces plainly in capability metadata and public documentation.

Packaging & Compatibility

Version the adapter identity and Plugin API contract deliberately. Build and test your wheel and source distribution independently of the OSS monorepo; verify public imports, entry-point discovery, and resolver tests in a clean environment. Do not package internal AIGP services, persistence models, credentials, local snapshots, or framework-development overlays.

Keep compatibility evidence with the release: supported Plugin API version, adapter version, declared framework boundary, known unsupported surfaces, and conformance-test results. A runtime may add a new execution-replay adapter version without changing legacy reference replay behaviour.

For a concrete implementation, follow the LangGraph ToolNode Evidence Replay guide. For lifecycle and result semantics, return to Execution Replay Architecture and Controlled Replay Framework.