Execution Replay Contract

Blueprint records enough structured execution data to explain a request after it completes and to correlate the state, evidence, events, and effects produced by that request. This page documents the replay surface implemented by the current protocol and PostgreSQL executor.

The durable envelope

One ActionRequest produces one ActionRecord. A request can contain several commands, and the record keeps each command's outcome inside the same envelope.

Record data	What it preserves
ActionReplayContext	Blueprint revision, runtime version, scope key, durable sequence, recorded time, and metadata
ActionCommandRecord	command id, request id, status, commit id, results, and failures
ActionRuleRecord	evaluated rule, outcome, and explanation data
ActionSnapshotRecord	named policy, configuration, master-data, or entity snapshot used by the decision
ActionDomainEventRecord	declared event name, entity/facet, stream key, stream sequence, payload, and occurrence time
ActionEvidenceRecord	evidence requirement, source, retention ref, value/object ref, digest, media facts, verification flag, and capture time
ActionEffectRecord	effect kind, target, state, idempotency key, attempts, timestamps, and failure data
ActionIntegrityRecord	invariant/check result linked to the action
ActionResult / ActionFailure	typed business outputs and failures

The wire types remain domain-neutral. A pharmaceutical release, an equipment activation, and an IAM grant change use the same envelope.

Revision identity

ActionReplayContext.blueprintRevision pins the name:version of the Blueprint used for the decision. runtimeVersion identifies the runtime build when the host supplies it. The record therefore explains which declaration and runtime interpreted the request.

Entity history is separate but correlated:

• EntityVersioning.versions records immutable save snapshots;
• EntityVersioning.revisions(...) adds governed business revisions;
• action command records and event rows retain entity ids and stream identity;
• optimistic expectedVersion prevents a stale command from committing.

Authoritative ordering

Client clocks are descriptive, not authoritative. The durable executor assigns ordering facts while persisting the transaction:

• the action replay context carries the durable action sequence;
• protocol frames carry request-local sequence;
• domain event rows carry a global event sequence;
• entity event streams carry (stream_key, stream_sequence) uniqueness;
• recordedAt and event occurredAt remain available for display.

Two events with the same timestamp are therefore ordered by sequence rather than timestamp alone.

Atomic persistence

The PostgreSQL executor writes the business mutation and its execution ledger in one database transaction. The runtime schema includes action requests, commands, plans, records, rules, results, failures, snapshots, evidence, integrity checks, events, and effects.

If validation, authorization, a blocking rule, a required evidence check, an invariant, optimistic concurrency, or persistence fails, the transaction does not leave a successful business mutation without its record.

Declared events

Action.emits declares the event facts an action produces. During execution:

1. the runtime resolves the declared event;
2. required event fields are materialized from the committed action context;
3. a missing required event payload blocks commit;
4. the event persists in action_events with action/command lineage;
5. stream and global sequences make the event order stable.

Events are facts projected from committed work. They do not replace the entity tables or the action ledger as a second source of truth.

Evidence and electronic signatures

Required evidence is checked before commit and persisted as ActionEvidenceRecord. A record can retain inline structured value data or an object reference plus digest, MIME type, size, source, retention ref, and verification state.

When an AuditEnvelope requires a signature, the authentication authority can issue a one-time BlueprintElectronicSignatureAssertion. The assertion binds:

• signer id and display name;
• the action digest and human meaning;
• authentication and expiry times;
• a one-time ElectronicSignatureProof consumed by the action server.

The action request carries only the proof needed by the target server. The server verifier validates it before the signed action executes.

Effects and delivery

Each planned effect becomes an ActionEffectRecord. The record includes the effect kind, target, state, idempotency key, attempt count, timing, and failure payload. Outbox delivery updates this state without repeating the committed domain mutation.

The supported effect vocabulary includes database, audit, action-record, query-record, outbox, realtime, dry-run, and custom effects. Dry-run execution uses the same planning vocabulary and marks effects as non-applying.

Idempotent resume

Requests and commands can carry idempotency keys. Before executing a resumed request, the database executor looks for a completed record with the same key. When found, it returns that record instead of applying the action again.

Outbox effects carry their own idempotency keys and attempt state. Request idempotency prevents duplicate business execution; effect idempotency prevents duplicate delivery work.

Query records

Reads use the same protocol ledger. QueryRecord stores the incoming request, actor/scope context, named projection, typed query expression, and typed ProjectionResult. This makes the data read before or after an action inspectable without turning queries into actions.

Explanation workflow

To explain a completed request:

1. load its ActionRecord;
2. read replay.blueprintRevision and scope/sequence facts;
3. inspect command and rule records in order;
4. inspect snapshots and evidence used by the decision;
5. inspect results, failures, and integrity records;
6. follow event stream ids and effect lineage to downstream work.

Studio and the Blueprint Inspector render these exact protocol records. Payload views preserve the wire JSON while summary views use human titles and formatted values.

Verification

The current conformance coverage verifies:

• revision pins and protocol serialization;
• request, command, event, and stream ordering fields;
• required evidence and snapshot persistence;
• declared event materialization and commit blocking;
• runtime effect serialization and persistence;
• idempotent request resume;
• runtime table and index generation;
• PostgreSQL persistence through the protocol executor.

The contract is intentionally record-based: only facts present in the current protocol and persistence model are described here.