lmg — the grid-authoring language

Write a Leumas programming grid as text and run it. Safe mode, no bridge required — it works from the CLI, the API and the Playground alike.

GRID "pricing"

LAYER default
  A1 variable 1200
  A2 variable 0.08
  B1 code $A1 * (1 + $A2)
  C1 conditional $B1 > 1000 ? "high" : "low"
  D1 template "tier {{ $C1 }} at {{ $B1 }}"

RUN B1, C1, D1
GRAPH

grid "pricing" — 1 layer(s), 5 cell(s)
default.B1 = 1296
default.C1 = high
default.D1 = tier high at 1296
--- dependency order ---
  default.A1
  default.A2
  default.B1  ← default.A1, default.A2
  default.C1  ← default.B1
  default.D1  ← default.C1, default.B1

---

What a grid actually is

Not a spreadsheet. A grid is layers of cells, and a cell is an action. A1 is not a number in a box; it is a variable action that produces one. B1 is a code action. There are ~21 cell types.

Cells reference each other with $refs, and @leumas/grids owns everything hard about that: it resolves refs concurrently, memoises so asking twice costs one run, checks for cycles, and evaluates code cells in a node:vm sandbox with no process, require or fetch.

lmg writes no evaluator. It is a syntax for that document, and the document it produces is the same shape the Studio grid editor persists.

---

Syntax

# starts a comment — except inside a do … end body, which is taken verbatim. A # in a code cell is JavaScript, and eating it would corrupt exactly the cells most likely to have one.

Cell refs are uppercase letters then digits (A1, B12, AA3) — that is the ref grammar @leumas/grids defines, not a choice made here. Cells declared before any LAYER go into a layer called default.

The one parsing rule

After <REF> <type>:

• if the rest of the line starts with --, it is parsed as flags and nothing else;
• otherwise the entire rest of the line is the cell's primary field, -- and all.

So B1 code $A1 - -2 means what it looks like, and B1 json --input=$A1 --op=get --path=name also means what it looks like. Nothing has to guess.

Flag values are JSON-coerced (--limit=5 is the number 5, --keys=["a"] is an array), and a bare --flag is true.

---

$refs

RUN targets are different: a bare RUN B1 has no owning layer, so it resolves to the layer that declares B1. If two layers declare it, lmg refuses and asks you to qualify it rather than picking one.

---

Cell types

Every type in allCellAdapters is available. The ones with a bare-rest-of-line form:

Any other type still works — name its fields with flags. A type with no bare form is an error rather than a guess, because a wrong guess runs.

conditional sugar

C1 conditional $B1 > 1000 ? "high" : "low"

desugars to --condition="$B1 > 1000" --trueResult=high --falseResult=low. The explicit flags are accepted too. ? and : inside quotes are ignored, so conditional $A1 = "who? me:" ? "yes" : "no" splits where you expect.

template slots take $refs, not bare names

D1 template "tier {{ $C1 }} at {{ $B1 | fixed:2 }}"

{{ C1 }} without the $ is not a ref — it renders the literal text C1. Helpers after | come from the template adapter: upper, lower, json, fixed:n, default:x.

---

[critical] The network gate

Two cell types make outbound requests: endpoint and url. Every other LMX mode that can reach the network (lmnet) is admin-gated behind LMX_ENABLE_NET, so lmg — a free mode — cannot be the open door to the same reach.

Without LMX_ENABLE_NET=1 those two adapters are replaced, not removed, and fail with:

"endpoint" cells reach the network — set LMX_ENABLE_NET=1 to allow them.

Removed, they would read as "unknown cell type", which sends the author hunting for a typo instead of at the policy.

The privileged lmx, adapter and exec cell types that leumas-api injects into its own grids domain are also out of reach here: a free script must not reach the ecosystem through a cell when it cannot reach it through adapter().

---

One implementation detail worth knowing

lmg writes each cell's options into specialConfig, and a code cell's source into a top-level code field — not into props.

Every adapter merges props over specialConfig, so either would execute correctly. But buildDependencyGraph reads only code and specialConfig. A props-authored grid therefore runs perfectly and reports an empty dependency graph — GRAPH prints every cell with no edges, and nothing in the output says it is lying. Writing specialConfig also makes an lmg grid identical to one the Studio editor produced.

---

What it deliberately cannot do

• Open or save a stored grid. Inline grids only, so there is no ownership question and no write

path around /api/grids and its PassNode meter.

• Reach the ecosystem. No lmx/adapter/exec cells.
• Reach the network without the flag.

---

Running it

leumas-lmx ./pricing.lmg

curl -s -X POST localhost:3000/api/lmx/run \
  -H 'content-type: application/json' \
  -d '{"mode":"lmg","source":"LAYER default\n  A1 variable 4\n  B1 code $A1 * 3\nRUN B1"}'

Bundled examples: shared/engines/lmx/src/scripts/demo.lmg, shared/engines/lmx/src/scripts/pricing-model.lmg. Tests: shared/engines/lmx/src/test/lmg.test.js. Guard: pnpm smoke:lmx.