regorus/docs/rvm/instruction-set.md

# RVM Instruction Set Reference

This reference captures every opcode emitted by the compiler and executed by
`RegoVM`. Each instruction is defined in `src/rvm/instructions/mod.rs` and
implemented by the dispatcher tree in `src/rvm/vm/dispatch.rs` plus specialised
submodules (`arithmetic.rs`, `loops.rs`, `functions.rs`, `rules.rs`,
`comprehension.rs`, `virtual_data.rs`).

Use this guide to understand operand semantics, parameter tables, and runtime
side effects.

---

## Reading the tables

- **Operands**: registers (`rX`), literals (`litY`), parameter indices (`pZ`) and
  immediate values.
- **Parameters**: links into `InstructionData` (`src/rvm/instructions/params.rs`).
  The compiler stores complex metadata here; instructions reference it by index.
- **Outcome**: mentioned in prose where relevant (`Continue`, `Return`, `Break`,
  `Suspend`).

---

## Load and Move instructions

| Mnemonic   | Operands                    | Behaviour                                            |
| :--------- | :-------------------------- | :--------------------------------------------------- |
| `Load`     | `dest=rD, literal_idx=litN` | Copies literal `N` into register `D`.                |
| `LoadTrue` | `dest=rD`                   | Stores boolean `true`.                               |
| `LoadFalse`| `dest=rD`                   | Stores boolean `false`.                              |
| `LoadNull` | `dest=rD`                   | Stores `Value::Null`.                                |
| `LoadBool` | `dest=rD, value`            | Stores inline boolean literal.                       |
| `LoadData` | `dest=rD`                   | Stores the VM's `data` value.                        |
| `LoadInput`| `dest=rD`                   | Stores the VM's `input` value.                       |
| `Move`     | `dest=rD, src=rS`           | Copies register `S` into register `D`.               |

Out-of-range literal indices raise `VmError::LiteralIndexOutOfBounds`. Registers
must have been allocated by the current frame.

---

## Arithmetic and comparison instructions

| Mnemonic | Operands                | Behaviour                                                     |
| :------- | :---------------------- | :------------------------------------------------------------ |
| `Add`    | `dest, left, right`     | Numeric addition; undefined operands trigger loop condition checks. |
| `Sub`    | `dest, left, right`     | Numeric subtraction.                                          |
| `Mul`    | `dest, left, right`     | Numeric multiplication.                                       |
| `Div`    | `dest, left, right`     | Numeric division with runtime checks (division by zero errors). |
| `Mod`    | `dest, left, right`     | Modulo.                                                       |
| `Eq`     | `dest, left, right`     | Equality comparison resulting in `Value::Bool`.               |
| `Ne`     | `dest, left, right`     | Inequality.                                                   |
| `Lt`/`Le`/`Gt`/`Ge` | `dest, left, right` | Ordering comparisons.                                         |
| `And`    | `dest, left, right`     | Logical conjunction (truthiness semantics).                   |
| `Or`     | `dest, left, right`     | Logical disjunction.                                          |
| `Not`    | `dest, operand`         | Logical negation.                                             |
| `AssertCondition` | `condition`    | Fails current loop/rule when the condition is falsey.         |
| `AssertNotUndefined` | `register`  | Fails when register holds `Value::Undefined`.                 |

`handle_condition` routes through `loops.rs` to propagate failures to loop and
comprehension contexts. Outside loops it aborts the current rule.

---

## Collection and indexing instructions

| Mnemonic                   | Operands / Params             | Behaviour                                                   |
| :------------------------- | :---------------------------- | :---------------------------------------------------------- |
| `ObjectSet`                | `obj, key, value`             | Mutates object in `obj` with key/value from registers.      |
| `ObjectCreate`             | `params_index=pN`             | Builds object from literal template and register entries.   |
| `ArrayNew`                 | `dest`                        | Creates empty array.                                        |
| `ArrayPush`                | `arr, value`                  | Appends to array.                                           |
| `ArrayCreate`              | `params_index=pN`             | Builds array from register list; undefined element ⇒ result undefined. |
| `SetNew`                   | `dest`                        | Creates empty set.                                          |
| `SetAdd`                   | `set, value`                  | Adds element to set.                                        |
| `SetCreate`                | `params_index=pN`             | Builds set from register list; undefined element ⇒ result undefined. |
| `Index`                    | `dest, container, key`        | Indexes container with runtime key.                         |
| `IndexLiteral`             | `dest, container, literal_idx`| Indexes container using literal stored in program.          |
| `ChainedIndex`             | `params_index=pN`             | Resolves multi-hop path from root register.                 |
| `Contains`                 | `dest, collection, value`     | Checks membership; returns `Value::Bool`.                   |
| `Count`                    | `dest, collection`            | Returns length or `Value::Undefined` for unsupported types. |
| `VirtualDataDocumentLookup`| `params_index=pN`             | Evaluates `data` path, invoking rules lazily.               |

Parameter structures:

- `ObjectCreateParams` reuses arrays of literal key/value pairs and register
  pairs. Literal keys must be sorted to match template order.
- `ArrayCreateParams` and `SetCreateParams` store register lists. The VM checks
  all referenced registers for `Value::Undefined` before constructing the
  collection.
- `VirtualDataDocumentLookupParams` and `ChainedIndexParams` encode `Vec<LiteralOrRegister>`
  path components. `LiteralOrRegister` is defined in `src/rvm/instructions/types.rs`.

---

## Loop instructions

Loops use dedicated parameter tables (`LoopStartParams`) and the `LoopMode`
enum.

| Mnemonic    | Operands / Params        | Behaviour                                                      |
| :---------- | :----------------------- | :------------------------------------------------------------- |
| `LoopStart` | `params_index=pN`        | Initialises loop context and decides first body iteration.     |
| `LoopNext`  | `body_start`, `loop_end` | Finalises iteration, updates accumulators, advances to next element. |

`LoopMode` values:

- `Any`: succeed on first passing iteration, short-circuit on success.
- `Every`: fail on first failing iteration.
- `ForEach`: evaluate all iterations, typically for comprehensions or complete
  rules.

`LoopStartParams` fields:

- `collection`: source register.
- `key_reg` / `value_reg`: iteration registers (for arrays, key is index).
- `result_reg`: accumulator storing loop outcome (`bool` for quantifiers).
- `body_start` / `loop_end`: PCs identifying loop boundaries.

The dispatcher converts `LoopStartParams` into a VM-specific `LoopParams` used by
both execution modes. In suspendable mode, loops own their own `ExecutionFrame`.

---

## Comprehension instructions

| Mnemonic             | Operands / Params       | Behaviour                                          |
| :------------------- | :---------------------- | :------------------------------------------------- |
| `ComprehensionBegin` | `params_index=pN`       | Allocates collection builder and iteration context. |
| `ComprehensionYield` | `value_reg`, `key_reg?` | Emits value (and optional key) into builder.        |
| `ComprehensionEnd`   | —                       | Finalises collection and stores result.             |

`ComprehensionBeginParams` captures:

- `mode: ComprehensionMode` (Set, Array, Object)
- `collection_reg`: source register for iteration
- `result_reg`: register that will hold the final collection
- `key_reg` / `value_reg`: iteration registers
- `body_start` / `comprehension_end`: branch targets

Comprehensions manage their own stack (`ComprehensionContext`) to maintain
ordering guarantees (arrays), uniqueness (sets) or key/value pairing (objects).

---

## Call and return instructions

| Mnemonic              | Operands / Params         | Behaviour                                       |
| :-------------------- | :------------------------ | :---------------------------------------------- |
| `BuiltinCall`         | `params_index=pN`         | Invokes builtin via resolved function pointer.  |
| `FunctionCall`        | `params_index=pN`         | Invokes function rule.                           |
| `CallRule`            | `dest, rule_index`        | Requests rule evaluation with caching.           |
| `RuleInit`            | `result_reg, rule_index`  | Prepares rule accumulator and cache state.       |
| `Return`              | `value_reg`               | Returns value from current function body.        |
| `RuleReturn`          | —                         | Finalises rule evaluation frame.                 |
| `DestructuringSuccess`| —                         | Signals successful destructuring, breaks rule block. |

Parameter tables:

- `BuiltinCallParams` / `FunctionCallParams` store destination register, index
  into builtin table / rule index, argument count and up to eight argument
  register numbers.
- The VM dynamically resizes registers when a callee requires a larger window
  using program metadata (`max_rule_window_size`).

---

## Host interaction

| Mnemonic   | Operands          | Behaviour                                |
| :--------- | :---------------- | :--------------------------------------- |
| `HostAwait`| `dest, arg, id`   | Yields control to host with payload value. |

- Run-to-completion: consumes a response from `host_await_responses` keyed by
  the identifier register. Missing responses raise `VmError::HostAwaitResponseMissing`.
- Suspendable: emits `InstructionOutcome::Suspend` with `SuspendReason::HostAwait`.
  The host must resume with a value that will be written into `dest`.

### Registered host-await builtins

The compiler can be configured with a list of function names that map directly
to `HostAwait` instructions. This allows policy authors to write natural
function calls (e.g. `lookup(input.account_id)`) instead of the raw
`__builtin_host_await(payload, identifier)` builtin.

Registration is done at compile time via `Compiler::compile_from_policy_with_host_await`:

```rust
let builtins = [("lookup", 1), ("persist", 1)];
let program = Compiler::compile_from_policy_with_host_await(
    &compiled_policy, &entry_points, &builtins,
)?;
```

Each registered name is a `(name, arg_count)` pair. When the compiler
encounters a call to a registered name, it emits a `HostAwait` instruction
with:
- `arg` = the first argument register
- `id` = a register loaded with a string literal containing the function name

Both the explicit `__builtin_host_await(arg, id)` call and a registered
builtin call produce the **same `HostAwait` bytecode instruction**. The only
difference is how the `id` register is populated: explicit calls take it from
the second user-supplied argument, while registered calls auto-generate a
`Load` instruction for the function name string. The VM cannot distinguish
between the two at runtime.

**Resolution order** in `determine_call_target()`:
1. `__builtin_host_await` (magic 2-argument form)
2. Registered host-await builtins (matched by **bare** function name only)
3. User-defined functions (matched by package-qualified path)
4. Standard builtins (matched by bare function name)

Registered names shadow both user-defined functions and standard builtins.
This means `time.parse_duration_ns` can be overridden to route through the
host instead of the built-in Rust implementation.

**Only unqualified calls are intercepted.** Registration matches a call by
the name *as written in the policy*. A bare call — `lookup(x)` — is
intercepted and compiled to a `HostAwait`. A package-qualified call —
`data.pkg.lookup(x)` — is **not** intercepted; it is resolved normally, as
if the name were never registered.

```rego
# "lookup" is registered as a host-await builtin.

package other
import rego.v1
lookup(k) := k            # an ordinary rule that happens to share the name

package demo
import rego.v1
a := lookup(input.k)             # intercepted     -> HostAwait
b := data.other.lookup(input.k)  # NOT intercepted -> calls other.lookup
```

The qualified form is resolved exactly as it would be without registration:
if a rule exists at that path it is called, otherwise compilation fails with
`Unknown function`. (A standard builtin like `count` has no qualified form at
all, so `data.pkg.count(x)` is always an `Unknown function` error, registered
or not.)

**Argument handling**: The `HostAwait` instruction carries a single `arg`
register. Registered builtins must use `arg_count: 1`; the compiler rejects
`arg_count > 1` at registration time. To pass multiple values, use object
packing: `lookup({"user": x, "resource": y})`.

---

## Halt instruction

| Mnemonic | Behaviour                         | Notes |
| :------- | :-------------------------------- | :---- |
| `Halt`   | Terminates execution immediately. | Used during debugging or emitted for guard rails. |

When encountered during run-to-completion execution, `Halt` returns the current
value in register `0`.

---

## Parameter data overview

`InstructionData` (`src/rvm/instructions/params.rs`) collects all complex
parameter types. Each `add_*` method returns a `u16` index suitable for storing
inside instructions. The VM retrieves tables via `get_*` accessors.

| Struct                   | Field                                     | Purpose                                                                    |
| :----------------------- | :---------------------------------------- | :------------------------------------------------------------------------- |
| `LoopStartParams`        | `mode`                                    | Loop semantics (`Any`, `Every`, `ForEach`).                                |
|                          | `collection`                              | Register holding the iterable collection.                                 |
|                          | `key_reg` / `value_reg`                   | Registers populated with the current key/value each iteration.             |
|                          | `result_reg`                              | Accumulator for loop outcome (`bool` for quantifiers).                     |
|                          | `body_start` / `loop_end`                 | Instruction pointers delimiting the loop body and exit.                    |
| `BuiltinCallParams`      | `dest`                                    | Register that receives the builtin result.                                 |
|                          | `builtin_index`                           | Slot into `builtin_info_table` for dispatch.                               |
|                          | `num_args`                                | Count of argument registers actually populated.                            |
|                          | `args[8]`                                 | Up to eight registers supplying builtin arguments.                         |
| `FunctionCallParams`     | `dest`                                    | Register that receives the function rule result.                           |
|                          | `func_rule_index`                         | Rule index for the target function definition.                             |
|                          | `num_args`                                | Number of argument registers provided.                                     |
|                          | `args[8]`                                 | Argument register numbers (unused slots ignored).                          |
| `ObjectCreateParams`     | `dest`                                    | Destination register for the constructed object.                           |
|                          | `template_literal_idx`                    | Literal template containing all expected keys.                             |
|                          | `literal_key_fields: Vec<(u16, u8)>`      | Mapping of literal-key indices to value registers.                         |
|                          | `fields: Vec<(u8, u8)>`                   | Dynamic key/value register pairs for non-literal keys.                     |
| `ArrayCreateParams`      | `dest`                                    | Destination register for the array literal.                               |
|                          | `elements: Vec<u8>`                       | Registers providing array elements (order preserved).                      |
| `SetCreateParams`        | `dest`                                    | Destination register for the set literal.                                 |
|                          | `elements: Vec<u8>`                       | Registers providing set members (duplicates dropped at runtime).           |
| `VirtualDataDocumentLookupParams` | `dest`                           | Destination register for lookup result.                                   |
|                          | `path_components: Vec<LiteralOrRegister>` | Ordered path traversal steps; mix of literals and register-based keys.     |
| `ChainedIndexParams`     | `dest`                                    | Destination register for resolved value.                                   |
|                          | `root`                                    | Register containing the root object/collection.                            |
|                          | `path_components: Vec<LiteralOrRegister>` | Path components applied relative to the root register.                     |
| `ComprehensionBeginParams` | `mode`                                  | Comprehension output type (array, set, object).                            |
|                          | `collection_reg`                          | Source collection register for iteration.                                  |
|                          | `result_reg`                              | Register receiving the final collection.                                   |
|                          | `key_reg` / `value_reg`                   | Iteration registers (keys optional for arrays/sets).                       |
|                          | `body_start` / `comprehension_end`        | Instruction pointers framing comprehension body and exit.                  |

All parameter structs derive `Serialize`/`Deserialize` and can be stored inside
artifacts. Some contain `Vec` fields; the compiler is responsible for ensuring
indices remain valid and stable across serialization boundaries.

---