# evm.execution_observations

One row per expanded observation point. observation_index supplies canonical point ordering and disambiguates checkpoints sharing one byte-exact logical key.

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

- Kind: View
- Layer: execution_read_model
- Category: Simulation
- Tags: Program, Execution, Public, View

## Contract and lifecycle

**Grain:** One expanded observation point per (execution_id, observation_index); byte-exact observation_key may identify multiple distinct checkpoints.

**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.executions on execution_id for candidate and run context.
- Use attempt_id to deduplicate physical facts expanded across contextual owners.
- For program owners use step_index; for observation-call owners use observation_index and observation_key.

### 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.

- `execution_id` (UUID; nullable) — Contextual execution association identity; do not use it as reusable artifact identity.
- `observation_key` (VARCHAR; nullable) — Byte-exact observation key
- `attempt_id` (UUID; nullable) — Call attempt identity

### Chain context

Pinned chain, block, profile, and revision context.

- `chain_id` (UBIGINT; nullable) — EVM chain identifier frozen for the owning execution.
- `chain_profile` (VARCHAR; nullable) — Named chain-rules profile frozen for the owning execution.

### Ordering and cardinality

Stable indexes and counts used to reconstruct deterministic order.

- `observation_index` (UINTEGER; nullable) — Expanded observation point ordinal
- `after_step_index` (UINTEGER; nullable) — Selected step for after_step

### Payload and evidence

Operation-specific inputs, outputs, and authenticated evidence.

- `checkpoint_kind` (VARCHAR; nullable) — pre, terminal, or after_step
- `read_kind` (VARCHAR; nullable) — Canonical READ kind
- `subject_address` (ADDRESS; nullable) — Account or contract whose value is described
- `asset_kind` (VARCHAR; nullable) — Definite asset kind
- `asset_address` (ADDRESS; nullable) — Asset or contract address associated with the read
- `source_kind` (VARCHAR; nullable) — Observation evidence source
- `raw_call_key` (BYTES32; nullable) — Raw call cache key
- `decode_key` (BYTES32; nullable) — ABI decode cache key
- `value_kind` (VARCHAR; nullable) — Typed EVM value discriminator
- `abi_type` (VARCHAR; nullable) — Canonical ABI type
- `raw_value` (BYTES; nullable) — Exact raw EVM value
- `boolean_value` (BOOLEAN; nullable) — Boolean scalar value
- `address_value` (ADDRESS; nullable) — Address scalar value
- `uint256_value` (UINT256; nullable) — Unsigned typed value
- `int256_value` (INT256; nullable) — Signed typed value
- `bytes_value` (BYTES; nullable) — Byte-string typed value
- `varchar_value` (VARCHAR; nullable) — String scalar value
- `evm_execution_gas` (UBIGINT; nullable) — Gas consumed by EVM execution when a complete measurement is available.
- `return_data` (BYTES; nullable) — Successful return bytes when the attempt produced them; otherwise NULL.
- `revert_data` (BYTES; nullable) — EVM revert bytes when the attempt reverted with data; otherwise NULL.
- `decoded_json` (JSON; nullable) — Decoded observation result when decoding succeeded; otherwise NULL.

### Status and disposition

Outcome vocabulary and NULL-controlling disposition fields.

- `observation_status` (VARCHAR; nullable) — Observation result status
- `observation_error_code` (VARCHAR; nullable) — Stable failure code
- `raw_cache_status` (VARCHAR; nullable) — miss, hit, or not_applicable
- `decode_cache_status` (VARCHAR; nullable) — miss, hit, or not_applicable
- `evm_status` (VARCHAR; nullable) — Physical attempt outcome: success, revert, or failure.
- `evm_error_code` (VARCHAR; nullable) — Stable EVM failure code when evm_status is not success; otherwise NULL.

### Commitments

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

- `observation_spec_root` (BYTES32; nullable) — Canonical scheduling specification
- `read_root` (BYTES32; nullable) — Canonical READ specification
- `checkpoint_state_identity_hash` (BYTES32; nullable) — Selected retained checkpoint
- `source_evidence_root` (BYTES32; nullable) — Authenticated source evidence
- `raw_result_root` (BYTES32; nullable) — Raw result commitment
- `decode_result_root` (BYTES32; nullable) — Decoded result commitment
- `output_schema_root` (BYTES32; nullable) — Commitment to the decoded observation output schema; NULL without decoded output.

### Timestamps

Contextual publication times that are excluded from reusable semantic identity.

- `created_at` (TIMESTAMP; nullable) — Observation result creation time

## Linked joins

- `execution_id` → [evm.executions](/docs/tables/evm-executions.md) (`execution_id`) — Contextual execution that exposes this public row.

## Related public objects

- [evm.executions](/docs/tables/evm-executions.md) — upstream

## Verified queries

### Confirm fixture coverage

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

```sql
SELECT 'evm.execution_observations'::VARCHAR AS object_name, CASE WHEN count(*) > 0 THEN 'PASS' ELSE 'FAIL' END::VARCHAR AS status FROM evm."execution_observations" o JOIN evm.executions e USING (execution_id) 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.execution_observations'::VARCHAR AS object_name, CASE WHEN count(DISTINCT e.candidate_key) > 0 THEN 'PASS' ELSE 'FAIL' END::VARCHAR AS status FROM evm."execution_observations" o JOIN evm.executions e USING (execution_id) WHERE e.candidate_key IN ('complete-effects', 'later-revert', 'ordered-logs', 'create', 'selfdestruct', 'blockhash', 'transient-access');
```