Ess.

Ess 0.2 · pseudo-code for LLM interpreters

Pseudo-code that says !how sure it is.

Write it like notes. Every line carries a mark for what must hold, what's only a hint, and what's still open. A model can then turn it into real code without guessing, and tell you what it decided.

slugify.ess

    

Five marks, one scale of freedom

Ordinary pseudo-code never says how firm it is. "Sort the users" could be a strict rule or a placeholder, so an interpreter guesses, and guesses drift. Ess puts the firmness on the page.

!

must

Satisfy exactly. Turn it into a check or a test. Never trade it for anything.

! timeout after 5s
no mark

step

Do what the line says. The interpreter picks the mechanism.

lowercase the title
~

roughly

A hint. It can be improved on, and any change in behavior gets reported.

~ 3 times with backoff
?

open

Not decided yet. The interpreter chooses, implements it, and says what it chose.

? in memory | on disk
#

note

Context for people. Never a requirement.

# é becomes e

When two lines disagree, the stronger one wins and the conflict is reported: ! › eg › step › ~ › style.

One rule for reading a line

A mark governs the text after it, up to the next mark or #. Whatever comes before the first mark is a plain step. The same rule holds in terms, fields and parameters.

call the payments API stepDo it; choose how. ! timeout after 5s mustExactly 5 seconds, and tested. ~ retry once roughlyA sensible default; may change, with a note. # upstream is flakynoteWhy, for the reader.

Examples are tests. Every eg, test and invariant line becomes an executable check in the generated code.

Terms fix vocabulary. term Slug = … means every later "Slug" is exactly that, so the rest of the file can stay short.

Decisions are reported. The interpreter returns code, tests, and a report of its decisions, deviations, conflicts and coverage.

Lowering, line by line

Real output from the repository. wc and shortener were lowered blind, by a model that saw only the interpreter prompt and the .ess file. Point at a line on either side to see where it went.

slugify.essEss
slugify.pyPython

Point at a line to trace it.

Write at any altitude

One line can stand for a whole function. Twenty lines can pin down every step. It's the same language either way: more detail just means less freedom. Write at the highest level that still pins down what matters.

one linecontractevery step
freedom
musts
tests

dedupe.ess

Tested blind, then tightened

To check that Ess can be interpreted from its prompt alone, three separate runs each got the prompt and one input, and nothing else. Their guesses became version 0.2.

RunOutputTestsResult
Lower wc.essGo command-line tool11 passSame output as GNU wc on files, totals, flags, a missing file and input with no final newline.
Lower shortener.essTypeScript + Hono service22 passIncludes 50 concurrent hits. Create, redirect, stats, 404 and 400 checked by hand with curl.
Lift slugify.pyEss, from code–Recovered every example and both invariants, and flagged two real bugs as ?.
Lift · code → Ess

The blind lift marked as accidental that "a—b" became "ab", and that max_len was never checked.

Reduce · edit the Ess

Both became ! lines and eg lines in slugify.ess. Nearly 40 guesses across all three runs reshaped the spec.

Lower · Ess → code

The reference was regenerated against the tighter source. All tests pass, now including "a—b" → "a-b".

When lifting the lowered code gives back the same Ess, you've reached a fixed point: the source is down to its essentials.

Run it

Give any LLM INTERPRETER.md as its instructions, or use the bundled command-line tool, which calls Claude and writes the files out.

shell

        

Read the report first. Every decision you want to keep becomes a ! or an eg; then lower again.

Quick reference

ess 0.2
version, always first
target · use · style
language, allowed dependencies, preferences
term W = …
fixed vocabulary
shape S
data, with field?: type = default
fn f(a: T) -> U
behavior; fail makes it fallible
on <trigger>
http routes, cli, schedules, queues
eg a -> b
an example that becomes a test
test · invariant
scenarios and properties
let each if give
structure, where prose would be ambiguous
`code` · ...
verbatim escape hatch · "the obvious rest"