ilo 26.5.0

ilo - the token-minimal programming language AI agents write
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

# Debugging ilo programs

## `ilo trace` — JSON-line value snapshots

`ilo trace <file.ilo> [func] [args...]` runs a program through the
tree-walking interpreter and emits one JSON line to stdout after every
statement executes.  This gives agents (and humans) a machine-readable
execution trace they can pipe into `jq`, store in a file, or compare
across runs.

```
ilo trace examples/trace-demo.ilo add 3 4
```

Output (one JSON object per line, pretty-printed here for readability):

```json
{"schemaVersion":1,"line":2,"stmt":"a = + x y","bindings":{"a":7,"x":3,"y":4},"result":7}
{"schemaVersion":1,"line":3,"stmt":"b = * a 2","bindings":{"a":7,"b":14,"x":3,"y":4},"result":14}
{"schemaVersion":1,"line":4,"stmt":"b","bindings":{"a":7,"b":14,"x":3,"y":4},"result":14}
```

### Event schema (schemaVersion 1)

| Field           | Type    | Description |
|-----------------|---------|-------------|
| `schemaVersion` | integer | Always `1`. Increment if the schema changes incompatibly. |
| `line`          | integer | 1-based source line number of the statement. |
| `stmt`          | string  | Source text of that line (trimmed). |
| `bindings`      | object  | All variable bindings visible in scope after the statement. |
| `result`        | any     | Value produced by the statement (`null` for statements with no value). For `let` assignments this is the assigned value; for expression statements it is the expression value. |

### Consuming traces with jq

```sh
# Show only lines where a binding changes to a number > 10
ilo trace prog.ilo | jq 'select(.result > 10)'

# Extract all result values in order
ilo trace prog.ilo | jq -r '.result'

# Show what bindings looked like at line 5
ilo trace prog.ilo | jq 'select(.line == 5) | .bindings'
```

### Notes

- `ilo trace` always uses the **tree-walking interpreter**.  The VM and
  JIT engines do not yet support tracing.
- Traces can be large for programs with loops.  Pipe through `head` or
  use `jq 'first(…)'` to limit output while iterating.
- Functions called by the entry function are also traced.  Each
  statement in every called function body emits its own event.
- The `bindings` object reflects the innermost scope at the point of
  the statement.  If the same name appears in multiple nested scopes,
  the innermost binding is shown.
- `FnRef` and `Closure` values cannot be serialised to JSON; they
  appear as `null` in `bindings` and `result`.

### v1 limitations / follow-ups

- Expression-level granularity (sub-statement snapshots) is not yet
  supported.
- Watchpoints and conditional breakpoints are not yet supported.
- DAP (Debug Adapter Protocol) integration is not yet supported.
- The VM / JIT trace path is not yet implemented.