Semantics & Execution Model

The semantics describe what the language means and how execution behaves in detail. This matters because Coldwave Script is designed for deterministic behavior: a program should behave the same way no matter when or where it runs.

Cycle‑Based Execution

+-----------+     +------------------+     +---------+
| Prefeed   | --> | Main Execution   | --> | Commit  |
+-----------+     +------------------+     +---------+

1. Prefeed — read inputs (IN), set initial values
2. Main Execution — execute code line by line, use temporary values (TMP)
3. Commit — write results from OUT segments to outputs

PROGRAM  
DIM T AS TON  
T(IN = TRUE, PT = T#500ms)  
PRINT T.Q  
END PROGRAM

Resume behavior: If the main program exceeds its cycle budget, execution is interrupted and the VM saves its state (program counter, call stack, bank selectors). In the next cycle, execution resumes from the saved state. During a resume cycle, the prefeed phase is skipped — the VM jumps directly to the saved program counter. This prevents re-initialization of values that were already computed before the interruption.

WCET & Determinism

WCET (Worst Case Execution Time) refers to the maximum time a program may require in the worst case.

Coldwave Script is designed to remain deterministic:

• No dynamic memory allocation in scripts
• Standard functions operate on bounded types (fixed max string length, fixed integer ranges, etc.)
• Loops must be constructed so the maximum iteration count is known from code (e.g., FOR with fixed bounds)
• EXIT and CONTINUE are permitted inside FOR and preserve the iteration bound derived from the TO expression. CONTINUE is rejected in DO/WHILE/UNTIL so the bound stays statically provable.

Example:

PROGRAM  
    DIM i AS INT  
    FOR i = 1 TO 10  
        PRINT i  
    NEXT i  
END PROGRAM

This loop runs exactly 10 iterations. Unbounded or infinite loops are not allowed and cause the VM to abort execution.

The precise WCET of a full program depends on the target system (CPU clock, implementation of runtime libraries), but due to the above constraints it can be estimated systematically.

Arithmetic Rules

Coldwave Script uses saturating arithmetic. Overflow is clamped to the upper bound, underflow to the lower bound or to 0 for unsigned types.

PROGRAM  
DIM a AS INT = 32760  
DIM b AS INT = 100  
PRINT a + b ' Output: 32767 (clamped)
END PROGRAM

Traps & Runtime Errors

Some error conditions can only be detected while the program is running. When one of them occurs, the VM traps: the current cycle stops immediately, execution halts, and the error is reported via telemetry to the Coldwave backend. Traps are deterministic — the same inputs always produce the same trap.

The most common traps are:

Condition	VM error	Notes
Division by zero	runtime trap	Guard with IF b <> 0 THEN ….
Array index out of bounds	VM_E_OOB_ARRAY	Index outside 1..N (or 0). See below for when this is caught earlier.
Cycle budget exhausted	VM_E_RUN_TIMEOUT	The program did not finish inside its WCET budget.
Watchdog tripped	VM_E_RUN_WATCHDOG	Wall‑clock watchdog; non‑deterministic overrun protection.

Static detection where possible

The compiler tries to catch trappable errors before the program runs. For array access this means:

• A constant index outside 1..N is rejected at compile time with SCRIPT_ERR_ARRAY_OOB_CONST.
• A FOR‑counter‑bounded index whose range provably escapes 1..N — including shifted forms like a[i + k] — is rejected at compile time with the same diagnostic.
• Any other out‑of‑bounds index is caught at runtime and produces VM_E_OOB_ARRAY.

The runtime trap is the safety net — the compile‑time checks are strictly additive and never produce false positives.

Exercises with Solutions

Exercise 1

Explain the execution cycle.

Solution: Prefeed → read inputs, Main → execute code, Commit → write outputs.

Exercise 2

Program a FOR loop from 1 to 5.

PROGRAM  
DIM i AS INT  
FOR i = 1 TO 5  
PRINT i  
NEXT i  
END PROGRAM

' Output: 1 2 3 4 5

Exercise 3

Overflow calculation (32760 + 100).

PROGRAM  
DIM a AS INT = 32760  
DIM b AS INT = 100  
PRINT a + b  
END PROGRAM

' Output: 32767 (clamped, saturating)

Summary

• Coldwave Script runs cyclically (Prefeed → Main → Commit).
• WCET ensures deterministic behavior.
• Banking separates variable contexts.
• Arithmetic is saturating and safe.
• Runtime traps (division by zero, array OOB, timeout, watchdog) stop the cycle deterministically; the compiler catches constant and FOR‑bounded array OOB ahead of time.
• Beginners need only the basics; experts can leverage full WCET and memory segment details.