# SLeeLa Opcode Running Helpers — Grouping · Conditional-Reactive · Warming
**Family:** `lib/opcodes/running`
**Revision:** 0.1
**Builds on:** `lib/opcodes` (one class per VM opcode) and `lib/opcodes/governance`
**Native bridge:** `native/include/sleela_opcode.h`, `native/src/sleela_opcode.cpp`
These classes are additional, suggested ways of **running** opcodes beyond a flat
`SLOpcodeStream`: cohesive **grouping**, a **conditional-reactive** layer that
reacts to program state, and **warming** that readies hot paths before they run.
They are composable with the governance series (Registrar / Listener / Event
Observer) — governance decides *whether* a program may run; these helpers shape
*how* its opcodes are organised and triggered.
## Grouping
A program is rarely one flat run; it is clusters of opcodes that belong together.
| Class | Role |
|---|---|
| `SLOpcodeGroup` | a named, ordered group of opcodes run as one unit — a loop body, critical section, handshake. Can `run()` directly, `warm()`, or `emitInto()` a stream. |
| `SLOpcodeGroupSet` | an ordered collection of groups (setup → work → teardown): `warmAll()`, `byName()`, flatten `emitInto()` a stream, or `run()` group-by-group. |
Grouping lets a developer reason about and gate opcodes in meaningful clusters
instead of a single long sequence, while order is still preserved inside each
group and across the set.
## Conditional-reactive
The reactive layer watches the running program and reacts to conditions by
grouping, warming, gating, or skipping opcodes.
| Class | Role |
|---|---|
| `SLOpcodeCondition` | a named predicate over a VM signal (ip, lock depth, call depth, open sockets, warning count, stream index) compared with `EQ`/`NE`/`LT`/`LE`/`GT`/`GE`. |
| `SLOpcodeConditionalReactive` | binds a condition (trigger) to a group (subject) and a reaction; edge-sensitive so it fires on the condition's rising edge. |
| `SLOpcodeReactorBank` | a bank of reactives ticked at each stream index; `driveStream()` runs a stream while ticking reactives around every opcode. |
**Reactions** a conditional-reactive can perform when its condition first holds:
- **WARM** — pre-warm the subject group so a hot path is ready before it is reached.
- **RUN** — run the subject group now, inline, as a reactive sub-sequence.
- **GATE** — admit the subject group only now that the condition holds (gated inclusion).
- **SKIP** — hold the subject group back (do not run it) while the condition holds.
Because reactives are edge-sensitive, they react once per rising edge and can be
`rearm()`ed for reuse. The bank's `admits()`/reaction logic lets a driver decide,
per group, whether it should run given the current conditions.
## Warming
`SLOpcodeWarmer` readies opcodes ahead of execution so the first fire of a hot
path has no cold-start cost: it `arm()`s each opcode in SLeeLa and asks the VM to
pre-stage the fetch via the native bridge. It can warm one opcode (`warmOne`), a
whole group (`warmGroup`), or an entire set (`warmSet`), and keeps a tally so the
reactive layer can tell whether a path is warm before gating it in. Warming never
executes an opcode.
## Native bridge additions
Two primitives were added to the opcode bridge for this sub-family:
- `sleela_opcode_signal(frame, signal, index)` — observe a well-known VM signal
(`SIG_IP`, `SIG_LOCK_DEPTH`, `SIG_CALL_DEPTH`, `SIG_OPEN_SOCKETS`,
`SIG_WARN_COUNT`, `SIG_INDEX`) for `SLOpcodeCondition`.
- `sleela_opcode_prestage(frame, code)` — warm (ready) an opcode without
executing it, for `SLOpcodeWarmer`.
The authoritative counters and fetch/decode live in `/impl/core`; this bridge
exposes deterministic reference values so the grouping and reactive layers can be
exercised in isolation.
```sh
cd native
make test # builds + self-tests audio, opcode (incl. signal/prestage), and governance bridges
```
## Classes
| Class | Kind |
|---|---|
| `SLOpcodeGroup` | grouping |
| `SLOpcodeGroupSet` | grouping |
| `SLOpcodeCondition` | conditional-reactive trigger |
| `SLOpcodeConditionalReactive` | conditional-reactive |
| `SLOpcodeWarmer` | warming |
| `SLOpcodeReactorBank` | conditional-reactive dispatch |
**Max Rupplin — MEARVK LLC — 2026**