# run

Executes candidate EVM programs sequentially against exact CLIENT state, then atomically publishes compact receipts and auditable local evidence. It never submits transactions or mutates the connected chain.

Canonical HTML: <https://determica.com/docs/functions/run>

- Kind: table function
- Category: [Simulation](/docs/category/simulation.md)
- Tags: Program Compiler, Execution, Evidence, Client, Simulate

Executes candidate EVM programs sequentially against exact CLIENT state, then atomically publishes compact receipts and auditable local evidence. It never submits transactions or mutates the connected chain.

## Overload 1: run(CLIENT)

```sql
run(CLIENT)
```

- Kind: table
- Execution context: Existing simulation
- Behavior: Execute Program Relation
- Execution modes: Live Client, Pinned Client, Execution Client
- Input shape: Relation
- Planning contract: Bind Time Schema
- Cardinality: Zero Or More
- Determinism: Deterministic For Exact State
- Return shape: Table
- Schema stability: Fixed
- Stability: Stable
- Side effects: local_evidence_write, optional_network_io

### Requirements

- exact_client_state
- unique_candidate_keys
- non_empty_program
- rpc
- existing_simulation

### Risks

- incomplete_hydration
- safety_limits
- future_chain_state_divergence

### Inputs

- `candidates` (CLIENT; required; positional)

### Relation input

The relation contains exactly client CLIENT, candidate_key VARCHAR, program PROGRAM, and optional observations OBSERVATION[], in any column order and with no extra columns.

### Relation columns

- `client` (CLIENT) — Live, pinned, or execution CLIENT that identifies the state. Determica may use an attached TRANSPORT to fetch missing state. Required
- `candidate_key` (VARCHAR) — Required 1-1024-byte valid UTF-8 key without NUL; byte-exact unique across the relation. Required
- `program` (PROGRAM) — Non-empty typed PROGRAM whose steps execute sequentially until the first failure. Required
- `observations` (OBSERVATION[]) — Optional keyed isolated reads at pre, retained post-step, or terminal checkpoints. Optional

```sql
SELECT client, candidate_key, program, observations FROM candidate_programs
```

### Result columns

One 18-column receipt per candidate

Returns input-order receipts while public evm.execution_* relations retain detailed attempts, checkpoints, observations, hydration evidence, state effects, and successful reusable artifacts.

- `run_id` (UUID) — Random UUID for this published run invocation; it is not a stable replay identity.
- `execution_id` (UUID) — Random UUID for this candidate execution attempt; join it to public evm.execution_* evidence.
- `candidate_key` (VARCHAR) — Byte-exact, input-order-preserving candidate key supplied by the relation.
- `candidate_request_hash` (BYTES32) — Stable hash of the candidate key, pinned client identity, program root, and requested observations.
- `chain_id` (UBIGINT) — EVM chain identifier carried by the candidate CLIENT, or NULL before client resolution.
- `chain_profile` (VARCHAR) — Execution-rules profile carried by the candidate CLIENT, or NULL before client resolution.
- `execution_artifact_hash` (BYTES32) — Stable reusable artifact identity for a successful complete execution; NULL for failed or incomplete programs.
- `status` (VARCHAR) — Candidate outcome: success, revert, out_of_gas, invalid, unsupported, state_unavailable, poisoned, or engine_error.
- `error_code` (VARCHAR) — Stable machine-readable failure code; NULL only when no failure requires interpretation.
- `execution_closure_status` (VARCHAR) — Execution closure: not_started, incomplete, or complete.
- `fact_completeness` (VARCHAR) — Whether the published execution facts are complete or incomplete for the retained prefix.
- `observation_status` (VARCHAR) — Observation aggregate: not_requested, complete, partial, or failed.
- `total_evm_execution_gas` (UBIGINT) — Measured EVM execution gas for the executed prefix; this excludes transaction intrinsic gas and observation gas.
- `total_transaction_gas_estimate` (UBIGINT) — Determica intrinsic, refund, and calldata-floor gas calculation for the executed prefix; not an RPC submission estimate.
- `transaction_gas_status` (VARCHAR) — Transaction-gas aggregate: not_started, incomplete, complete_executed_prefix, or complete_program.
- `terminal_state_available` (BOOLEAN) — True only when a successful complete reusable terminal state was retained for this execution.
- `execution_result_root` (BYTES32) — Stable commitment to the complete run receipt and published result semantics.
- `cache_status` (VARCHAR) — Execution reuse status: miss, invocation_local_hit, or durable_hit.

One 18-column receipt per candidate. Returns input-order receipts while public evm.execution_* relations retain detailed attempts, checkpoints, observations, hydration evidence, state effects, and successful reusable artifacts.

### Examples

_Requires Existing Simulation · Needs run · RPC required_

```sql
WITH actors AS (
  SELECT
    '0x1000000000000000000000000000000000000001'::ADDRESS AS sender,
    '0x2000000000000000000000000000000000000002'::ADDRESS AS writer,
    '0x3000000000000000000000000000000000000003'::ADDRESS AS second_target,
    '0x0000000000000000000000000000000000000000000000000000000000000000'::BYTES32 AS slot_zero
),
candidates(candidate_key) AS (
  VALUES ('pass'::VARCHAR), ('later-revert'::VARCHAR)
),
requests AS (
  SELECT
    pin(
      client(http_transport(
        'http://127.0.0.1:4106'::VARCHAR,
        31337::UBIGINT,
        '{"retry_count":0,"timeout_ms":1000}'::JSON
      )),
      19000000::UBIGINT,
      true
    ) AS client,
    candidate_key,
    program(
      [
        -- Give the sender enough native balance for step zero's value transfer.
        assume_native_balance(sender, 1000000::UINT256, 'funds step value transfer'::VARCHAR),
        assume_nonce(sender, 0::UBIGINT, 'step sender nonce'::VARCHAR),
        assume_no_code(sender, 'step sender is an EOA'::VARCHAR),
        assume_native_balance(writer, 0::UINT256, 'receives step value'::VARCHAR),
        assume_nonce(writer, 0::UBIGINT, 'writer call target nonce'::VARCHAR),
        -- Set the writer's code and initial storage slot for step zero.
        assume_code(writer, '0x60003560005500'::BYTES, 'stores calldata word in slot zero'::VARCHAR),
        assume_storage(writer, slot_zero, slot_zero, 'slot zero starts clear'::VARCHAR),
        assume_native_balance(second_target, 0::UINT256, 'second target starts empty'::VARCHAR),
        assume_nonce(second_target, 0::UBIGINT, 'second target nonce'::VARCHAR),
        assume_code(
          second_target,
          CASE candidate_key WHEN 'pass' THEN '0x00'::BYTES ELSE '0x60006000fd'::BYTES END,
          'step one either stops or deliberately reverts'::VARCHAR
        )
      ],
      [
        execute_call(
          sender,
          writer,
          '0x000000000000000000000000000000000000000000000000000000000000002a'::BYTES,
          1::UINT256,
          100000::UBIGINT
        ),
        execute_contract(
          sender,
          second_target,
          0::UINT256,
          100000::UBIGINT,
          call_context(
            1::UINT256,
            [{address: writer, storage_keys: [slot_zero]}],
            []::BYTES32[]
          ),
          '[{"type":"function","name":"set","inputs":[{"name":"value","type":"uint256"}],"outputs":[]}]'::JSON,
          'set'::VARCHAR,
          7::UINT256
        )
      ]
    ) AS program,
    [
      observe('writer.slot.pre'::VARCHAR, storage_at(writer, slot_zero), 'pre'::VARCHAR),
      observe_after_step('writer.slot.after.0'::VARCHAR, 0::UINTEGER, storage_at(writer, slot_zero)),
      observe('writer.balance.terminal'::VARCHAR, native_balance(writer), 'terminal'::VARCHAR)
    ] AS observations
  FROM candidates
  CROSS JOIN actors
)
SELECT
  candidate_key,
  status,
  transaction_gas_status,
  terminal_state_available,
  cache_status
FROM run((SELECT client, candidate_key, program, observations FROM requests))
ORDER BY candidate_key;
-- => [{"candidate_key":"later-revert","status":"revert","transaction_gas_status":"complete_executed_prefix","terminal_state_available":"false","cache_status":"miss"},{"candidate_key":"pass","status":"success","transaction_gas_status":"complete_program","terminal_state_available":"true","cache_status":"miss"}]
```

## Guidance

### Behavior and consumption

Candidate keys are validated globally before execution and remain byte-exact and input-order preserving. An empty relation returns no receipts and publishes no run. Steps execute sequentially and stop after the first non-success; earlier successful checkpoints remain observable after a later failure.

- Explicit assumptions preempt hydration at the same coordinate; duplicate assumption coordinates are rejected.
- Successful step deltas supersede earlier state for later steps.
- Missing state comes only from retained execution state, verified local evidence/cache, or hash-pinned RPC authority.
- Pre observations use the initial snapshot; after_step(N) uses that retained post-checkpoint; terminal uses the latest retained executed-prefix snapshot.
- Observations execute in isolated child overlays and modify neither PROGRAM state nor PROGRAM gas.

### Same-statement evidence reads

When one SQL statement both invokes run and scans an evm.execution_* relation populated by that invocation, wrap run in WITH executions AS MATERIALIZED (SELECT * FROM run(...)). Materialization ensures publication completes before downstream observation scans initialize.

- An ordinary CTE does not guarantee same-statement visibility.
- Direct receipt reads and evm.execution_* scans in later statements do not require materialization.

### Validation and failure timing

The relation shape and SQL types bind before execution. Candidate keys and duplicates are checked for the whole input before any candidate executes. Constructor content validation occurs when its scalar expression executes. Duplicate keys abort the statement before publication.

- status is success, revert, out_of_gas, invalid, unsupported, state_unavailable, poisoned, or engine_error.
- poisoned and engine_error are defensive or fault-injection outcomes, not ordinary authored-program results.
- error_code is the stable machine-readable interpretation; do not branch on human error text.

### Determinism, network, and side effects

run never mutates the connected chain. It may hydrate missing state only through retained state, verified local evidence/cache, or hash-pinned RPC authority. Receipts, attempts, observations, hydration evidence, and successful artifacts publish atomically with the SQL statement and caller transaction.

- execution_closure_status: not_started, incomplete, complete.
- observation_status: not_requested, complete, partial, failed.
- transaction_gas_status: not_started, incomplete, complete_executed_prefix, complete_program.
- cache_status: miss, invocation_local_hit, durable_hit.
- EVM gas is measured execution gas; transaction gas is Determica's intrinsic/refund/floor calculation, not an RPC submission estimate.

### Use and do not use

Use run to compare authored candidates at one explicit state boundary and audit every retained effect. Do not treat success as a guarantee of future onchain success, submit credentials in authored SQL, or interpret a failed program as a reusable terminal artifact or execution CLIENT.

- Only successful complete artifacts can yield invocation_local_hit or durable_hit.
- program roots, candidate request hashes, execution artifact hashes, random run/execution UUIDs, and replay status are distinct identities.

## Related functions

- [assume_native_balance](/docs/functions/assume_native_balance.md) — See Also
- [call_context](/docs/functions/call_context.md) — See Also
- [execute_call](/docs/functions/execute_call.md) — See Also
- [program](/docs/functions/program.md) — See Also
- [observe](/docs/functions/observe.md) — See Also