lashlang/rlm

Values

null, booleans, numbers, strings, lists, records, projected host values, result wrappers, async handles, and immutable Image handles. Lists and records are value-shaped and copy-on-write at mutation roots.

Statements

Simple and path assignment, bare expression statements, call, print, if/else, for, break, continue, parallel, cancel, and submit.

Expressions

Literals, variables, builtin calls, tool calls, start call, await, field/index access, unary operators, binary operators, ternaries, result unwrap with ?, and Type { ... } literals.

Effects

All external work crosses ToolHost. Synchronous calls return wrapper records, background starts return handles, await resolves handles, and print creates model-visible observations.

REPL state

Variables persist across fenced blocks in the active RLM execution state. Read-only host bindings projected through ProjectedBindings are already in scope (e.g., history) and should be used directly instead of reconstructed from prompt prose.

Completion

submit ends the program and turn. call continue_as { task: ..., seed: { ... } } is a host tool (not a keyword) that ends the current trajectory and queues a fresh-window successor session. In schema-constrained runs, a bad submitted shape produces a runtime nudge asking the model to fix the value and submit again from another fenced block.

```lashlang
text = (call read_file { path: "Cargo.toml" })?
print { chars: len(text), head: slice(text, 0, 1200) }
```

A typical handoff packs the concrete state the successor needs and ends the block. Computed expressions default to global state on the successor; values rooted at a projected binding (like input.prompt) stay projected.

```lashlang
findings = []
for path in (call glob { pattern: "src/**/*.rs" })? {
  text = (call read_file { path: path })?
  if contains(text, "TODO") {
    findings = push(findings, { path: path, chars: len(text) })
  }
}
call continue_as {
  task: "summarize the TODO audit and propose a follow-up plan",
  seed: { problem: input.prompt, findings: findings }
}
```

Literals

Use null, true, false, numbers, strings, lists like [a, b], and records like { name: "lash", "with space": 1 }. Record insertion order is preserved for display and serialization.

Strings

"..." supports \n, \r, \t, \", and \\. """...""" is multiline with escapes. r"""...""" and r'''...''' preserve content exactly for patches, JSON, scripts, Markdown, and heredocs.

Fields and indexes

value.field reads record and image fields. value[index] reads lists and records; record indexes are string-coerced and missing keys read as null. List indexes support negative offsets for reads and slices.

Images

Image values expose .id, .label, .size, .width, and .height. Image fields are immutable. len(image) is invalid; use image.size.

Supported targets

name = expr, record.field = value, record[key] = value, list[i] = value, and nested forms like state.groups[g].count = count + 1.

Rules

Record field/index assignment inserts or replaces fields. List assignment replaces an existing integer index only. Assigning through a missing nested record key or image field is an error.

counts = {}
for group in groups {
  current = counts[group]
  counts[group] = (current == null ? 0 : current) + 1
}
submit counts

if / else

Conditionals use statement blocks. else if parses as an else block containing another if.

for

for item in iterable { ... } iterates lists. Non-list iteration is a runtime error. range is the usual integer-loop helper.

break / continue

break exits the nearest loop through the iterator cleanup path. continue skips to the next iteration. They are rejected outside loops and cannot cross parallel branch boundaries.

submit

submit value ends the whole program or turn. submit inside a loop is not a loop control statement, and submit inside parallel is rejected.

A short walkthrough that exercises iteration, else if chains, break/continue, and format. Loop variables are scoped to the loop body and the prior binding of label is restored on break.

nums = [1, 2, 3, 4, 5, 6]
seen = []
total = 0
for n in nums {
  if n == 2 {
    continue
  }
  if n > 4 {
    break
  }
  seen = push(seen, n)
  total = total + n
}
if total > 10 {
  label = "large"
} else if total > 5 {
  label = "medium"
} else {
  label = "small"
}
submit format("seen={} total={} label={}", join(seen, ","), total, label)

ProjectedBindings

Map of names to ProjectedValues the host hands the executor at the start of each fenced block. RLM rebuilds it from RlmGlobalsPatch + the live history projection.

ProjectedValue

Either a scalar FlowValue or a custom Arc<dyn ProjectedHostValue> for non-trivial shapes (lazy field access, length, indexing).

ProjectedHostValue

Trait that lets the host serve get_field, get_index, len, render, and materialize queries on demand (returning a ProjectedRead for field/index reads) so large host-side structures need not be cloned into Lashlang values.

Reserved names

history and any host-projected globals are reserved. Attempting name = ... over a projected name raises `name` is a read-only projected binding. The host-side seed channel (continue_as / spawn_agent seed:) can land projected entries that lashlang code then sees as read-only.

Tool arguments

RLM serializes projected values with an internal {"__projected__": ...} marker, then its before-tool hook materializes those markers before ordinary tools validate or execute. Tool implementations should parse ToolCall.args as plain JSON. The only preserved markers are root entries under seed: for projection-aware RLM control tools such as continue_as and RLM spawn_agent, where the marker means "re-project this value in the successor".

call

call tool { arg: expr } returns { ok: true, value: ... } or { ok: false, error: "..." }. Use ? for ordinary happy-path calls and keep the wrapper for retries or expected failures.

start call

start call tool { ... } returns a handle directly. Monitors and subagents are long-lived handle-producing tools; generic async tool starts use the same shape.

await

await handle resolves one handle. await [h1, h2] resolves a list and returns wrapper records in order; await { a: h1, b: h2 } resolves a record of handles and returns a record of wrappers. (await handle)? unwraps the resolved result.

cancel

cancel handle asks the host to stop background work. Cancellation is best-effort and uses the same handle identity exposed by list_async_handles.

Use ? for the happy path and inspect the wrapper when failures are expected. Mixing both styles in one block keeps fatal errors fail-fast while letting probes branch on outcome.

// Fail-fast: the block aborts if the file can't be read.
manifest = (call read_file { path: "Cargo.toml" })?
lines = split(manifest, "\n")

// Inspect-the-wrapper: we expect this read might miss.
optional = call read_file { path: "CHANGELOG.md" }
notes = optional.ok ? slice(optional.value, 0, 200) : format("no changelog: {}", optional.error)

// Iterate over a glob and skip files that fail to read.
items = []
for path in (call glob { pattern: "src/**/*.rs" })? {
  hit = call read_file { path: path }
  if !hit.ok {
    continue
  }
  items = push(items, { path: path, chars: len(hit.value) })
}
submit { line_count: len(lines), notes: notes, items: items }

Background work uses start call; results come back as wrappers when you await. await over a list returns wrappers in order; over a record it returns wrappers keyed by name. The unwrap operator ? applies to (await h) just like to (call ...).

// Kick off two long-running subagents in the background.
left = start call spawn_agent {
  agent_name: "audit_a",
  task: "audit module a",
  capability: "explore"
}
right = start call spawn_agent {
  agent_name: "audit_b",
  task: "audit module b",
  capability: "explore"
}

// Resolve both concurrently as a record of wrappers.
results = await { a: left, b: right }
if !results.a.ok {
  submit { error: results.a.error }
}
submit {
  a: results.a.value,
  b: results.b.ok ? results.b.value : null
}

Named branches

parallel { first: call ... second: call ... } returns a record when used as an expression. Named branches are preferred because results can be read as results.first.

Positional branches

parallel { call ..., call ... } (or with newlines as separators) returns a list when used as an expression. Bare expressions inside a parallel block contribute values to that list.

a = start call spawn_agent { agent_name: "one", task: "Read file A", capability: "explore" }
b = start call spawn_agent { agent_name: "two", task: "Read file B", capability: "explore" }
results = parallel { one: (await a)?, two: (await b)? }
submit { a: results.one, b: results.two }

Shapes

Scalars: str, int, float, bool, dict, any, null. Collections: list[shape], enum["a", "b"], nested Type { ... }, named refs, and unions with |.

Optional vs nullable

email: str? means the field may be absent, but if present it must be a string. email: str | null means the field is required and may be null.

Nested objects

Nested record shapes must use the Type keyword: profile: Type { name: str }. A bare { name: str } is a record value form and is rejected in type positions.

Contract boundary

Tools such as llm_query and spawn_agent can expose output schemas derived from these shapes, but Lashlang v1 keeps this as contract truthfulness rather than model-authored generics.

Payload = Type {
  id: str,
  score: float | null,
  tags: list[str],
  status: enum["new", "done"],
  note: str?
}
validated = validate(candidate, Payload)

Type literals can be passed directly to tools that accept output schemas, and they double as runtime guards on JSON parsed from untrusted text. Validation errors carry a JSON-pointer-style path to the bad field.

Package = Type {
  name: str,
  version: str,
  labels: list[str],
  meta: Type {
    pages: int,
    published: int
  }
}

raw = (call read_file { path: "package.json" })?
parsed = json_parse(raw)
package = validate(parsed, Package)

// Constrain a subagent's output shape via the same Type literal.
result = (call spawn_agent {
  agent_name: "summarizer",
  task: format("summarize {} v{}", package.name, package.version),
  capability: "summarize",
  output: Type { headline: str, bullets: list[str] }
})?

submit { package: package, summary: result }

An end-to-end fanout-and-merge program. It enumerates candidate files, kicks off per-file analyses in parallel, awaits them as a record, builds a histogram with nested path assignment, and either finishes the trajectory or hands the partial work to a successor when the budget would be exceeded.

```lashlang
paths = (call glob { pattern: "lash/src/**/*.rs" })?
if empty(paths) {
  submit { reviewed: 0, by_owner: {} }
}

// Fan out: one subagent per file, capped at the first eight to keep
// the parallel batch small.
batch = slice(paths, null, 8)
handles = {}
for path in batch {
  handles[path] = start call spawn_agent {
    agent_name: format("review:{}", path),
    task: format("review {} for TODOs and panics", path),
    capability: "explore",
    output: Type { owner: str, todos: int, panics: int }
  }
}

// Resolve the whole record concurrently, then collapse into a histogram.
resolved = await handles
by_owner = {}
errors = []
for path in keys(resolved) {
  wrapper = resolved[path]
  if !wrapper.ok {
    errors = push(errors, { path: path, error: wrapper.error })
    continue
  }
  report = wrapper.value
  current = by_owner[report.owner]
  by_owner[report.owner] = {
    todos: (current == null ? 0 : current.todos) + report.todos,
    panics: (current == null ? 0 : current.panics) + report.panics
  }
}

// Hand off the rest if we only got through a slice; otherwise submit.
if len(paths) > len(batch) {
  call continue_as {
    task: "continue the review over the remaining files",
    seed: { remaining: slice(paths, 8, null), by_owner: by_owner, errors: errors }
  }
}
submit { reviewed: len(batch), by_owner: by_owner, errors: errors }
```

print(image)

Collects image values recursively, registers their attachment refs, and sends provider-visible LlmContentBlock::Image content alongside descriptor text.

submit(image)

Serializes metadata only, using a JSON-compatible descriptor with id, label, size, width, and height. It does not embed base64 data.

1. Parser

   lexer.rs tokenizes strings (including r"""...""" / r'''...''' raws), // comments, operators, and keywords. parser.rs builds Program, Stmt, Expr, assignment targets, parallel branches, and type expressions.

2. Compiler

   runtime/compiler.rs lowers the AST into a Chunk of Instructions (defined in runtime/instruction.rs), folds static type literals, compiles assignment paths, loop cleanup jumps, builtin calls (specialized to Instruction::Len, Range, Push, FormatCompiled, ValidateCompiled, etc.), and optimized parallel call sets. cache.rs reuses compiled programs across fenced blocks via an LRU.

3. VM

   runtime/vm.rs walks the compiled Chunk, stores globals in state.rs's State, records assignment conflicts inside parallel branches, calls host effects through host.rs's ToolHost, and consults the ProjectedBindings defined in value.rs for any name not present in State. ops.rs holds value coercions and builtin bodies; access.rs handles field/index reads and path assignment; format.rs and json.rs own format(...) and json_parse/serialization helpers. entry_points.rs wires the public compile_source / execute_compiled* / profile_compiled* surface re-exported from the crate root.

4. Profiling

   examples/perf.rs, examples/profile.rs, and Scenario::ALL (in examples/bench_support/mod.rs) cover whole-language performance sweeps, including compiler and builtin hot paths. ProfileReport aggregates per-instruction and per-builtin counts/times.