# evm.executions

Contextual PROGRAM execution associations.

Canonical HTML: <https://determica.com/docs/tables/evm-executions>

- Kind: Table
- Layer: program_execution
- Category: Simulation
- Tags: Program, Execution, Public

## Contract and lifecycle

**Grain:** One contextual candidate association per execution_id. Identifying tuples: (execution_id) and the physical UNIQUE tuple (run_id, candidate_key).

**Lifecycle:** run publishes this immutable row set atomically with its owning run. Statement failure or caller rollback publishes no durable prefix; direct DML is unsupported because it can corrupt the documented invariants.

**Status and NULLs:** Interpret nullable payloads only through their owning status fields. Defensive poisoned and engine_error outcomes mean the engine refused to claim a trustworthy normal result; broad view nullability also covers owner alternatives and left-joined evidence.

### Join guidance

- Join evm.runs on run_id.
- Join every execution_* public view on execution_id.
- execution_artifact_hash is reusable across contextual execution_id values when complete.

### Effect semantics

- Access flags describe attempted EVM access, not committed state change.
- Effect facts retain attempted evidence and final committed, reverted, discarded, or poisoned disposition.
- execution_state_deltas contains committed checkpoint transitions only; observation-call effects are excluded from execution_effect_summary.

## Columns

### Identity and ownership

Contextual keys and reusable identities that establish row ownership.

- `run_id` (UUID; required) — Owning invocation
- `execution_id` (UUID; required; primary key) — Contextual execution id
- `candidate_key` (VARCHAR; required) — Caller candidate key
- `execution_artifact_hash` (BYTES32; nullable) — Reusable artifact identity

### Chain context

Pinned chain, block, profile, and revision context.

- `chain_id` (UBIGINT; nullable) — EVM chain id
- `anchor_block_number` (UBIGINT; nullable) — Pinned anchor number
- `anchor_block_hash` (BYTES32; nullable) — Pinned anchor hash
- `anchor_canonicality_at_run` (VARCHAR; nullable) — Canonicality at execution
- `chain_profile` (VARCHAR; nullable) — Chain profile
- `chain_profile_version` (UINTEGER; nullable) — Chain profile version
- `evm_revision` (VARCHAR; nullable) — Selected EVM revision
- `chain_rules_root` (BYTES32; nullable) — Frozen rules root
- `base_state_identity_hash` (BYTES32; nullable) — Immutable base identity

### Ordering and cardinality

Stable indexes and counts used to reconstruct deterministic order.

- `step_count` (UBIGINT; required) — Program step count
- `executed_step_count` (UBIGINT; required) — Attempted step count

### Payload and evidence

Operation-specific inputs, outputs, and authenticated evidence.

- `total_evm_execution_gas` (UBIGINT; nullable) — Attempted-prefix execution gas
- `total_transaction_gas_estimate` (UBIGINT; nullable) — Attempted-prefix transaction gas
- `physical_strategy` (VARCHAR; required) — Physical strategy
- `scheduler_kind` (VARCHAR; required) — Scheduler kind
- `engine_semantics` (VARCHAR; required) — Execution semantics identifier
- `evidence_semantics` (VARCHAR; required) — Evidence semantics identifier

### Status and disposition

Outcome vocabulary and NULL-controlling disposition fields.

- `status` (VARCHAR; required) — Candidate status
- `error_code` (VARCHAR; nullable) — Stable error code
- `execution_closure_status` (VARCHAR; required) — Executed-prefix closure
- `fact_completeness` (VARCHAR; required) — Selected fact completeness
- `observation_status` (VARCHAR; required) — Observation lifecycle status
- `transaction_gas_status` (VARCHAR; required) — Aggregate gas completeness
- `terminal_state_available` (BOOLEAN; required; default: false) — Terminal checkpoint is readable
- `cache_status` (VARCHAR; required) — Artifact cache status

### Effects

Attempted and final effect facts or aggregates.

- `worker_count` (UINTEGER; required; default: 0) — Effective workers

### Commitments

Hashes and roots authenticating specifications, facts, state, or results.

- `candidate_request_hash` (BYTES32; required) — Canonical request commitment
- `assumption_root` (BYTES32; nullable) — Semantic assumption commitment
- `program_body_root` (BYTES32; nullable) — Ordered executable body commitment
- `program_root` (BYTES32; nullable) — Frozen PROGRAM commitment
- `execution_facts_root` (BYTES32; nullable) — Selected facts commitment
- `terminal_overlay_root` (BYTES32; nullable) — Terminal visible overlay commitment
- `terminal_state_identity_hash` (BYTES32; nullable) — Terminal checkpoint identity
- `observation_spec_root` (BYTES32; nullable) — Observation specification commitment
- `observation_result_root` (BYTES32; nullable) — Observation result commitment
- `execution_result_root` (BYTES32; required) — Contextual execution result commitment

### Timestamps

Contextual publication times that are excluded from reusable semantic identity.

- `created_at` (TIMESTAMP; required) — Context association time

## Linked joins

- `run_id` → [evm.runs](/docs/tables/evm-runs.md) (`run_id`) — Invocation that atomically published this contextual candidate execution.

## Related public objects

- [evm.execution_accesses](/docs/tables/evm-execution-accesses.md) — downstream
- [evm.execution_asset_claims](/docs/tables/evm-execution-asset-claims.md) — downstream
- [evm.execution_assumptions](/docs/tables/evm-execution-assumptions.md) — downstream
- [evm.execution_attempts](/docs/tables/evm-execution-attempts.md) — downstream
- [evm.execution_blockhash_reads](/docs/tables/evm-execution-blockhash-reads.md) — downstream
- [evm.execution_checkpoints](/docs/tables/evm-execution-checkpoints.md) — downstream
- [evm.execution_creates](/docs/tables/evm-execution-creates.md) — downstream
- [evm.execution_effect_summary](/docs/tables/evm-execution-effect-summary.md) — downstream
- [evm.execution_frames](/docs/tables/evm-execution-frames.md) — downstream
- [evm.execution_logs](/docs/tables/evm-execution-logs.md) — downstream
- [evm.execution_observation_facts](/docs/tables/evm-execution-observation-facts.md) — downstream
- [evm.execution_observation_pairs](/docs/tables/evm-execution-observation-pairs.md) — downstream
- [evm.execution_observations](/docs/tables/evm-execution-observations.md) — downstream
- [evm.execution_selfdestructs](/docs/tables/evm-execution-selfdestructs.md) — downstream
- [evm.execution_state_deltas](/docs/tables/evm-execution-state-deltas.md) — downstream
- [evm.execution_state_reads](/docs/tables/evm-execution-state-reads.md) — downstream
- [evm.execution_state_writes](/docs/tables/evm-execution-state-writes.md) — downstream
- [evm.execution_steps](/docs/tables/evm-execution-steps.md) — downstream
- [evm.execution_transient_accesses](/docs/tables/evm-execution-transient-accesses.md) — downstream
- [evm.runs](/docs/tables/evm-runs.md) — upstream

## Verified queries

### Confirm fixture coverage

Confirm that this object has rows owned by the stable seven-candidate public fixture.

```sql
SELECT 'evm.executions'::VARCHAR AS object_name, CASE WHEN count(*) > 0 THEN 'PASS' ELSE 'FAIL' END::VARCHAR AS status FROM evm."executions" e WHERE e.candidate_key IN ('complete-effects', 'later-revert', 'ordered-logs', 'create', 'selfdestruct', 'blockhash', 'transient-access');
```

### Check candidate ownership

Diagnose whether this object remains linked to at least one stable fixture candidate through public keys.

```sql
SELECT 'evm.executions'::VARCHAR AS object_name, CASE WHEN count(DISTINCT e.candidate_key) > 0 THEN 'PASS' ELSE 'FAIL' END::VARCHAR AS status FROM evm."executions" e WHERE e.candidate_key IN ('complete-effects', 'later-revert', 'ordered-logs', 'create', 'selfdestruct', 'blockhash', 'transient-access');
```