Eulisp Documentation

Eulisp is a small, expression-based language where programs describe effects as data, and the runtime (Ω) decides how and when to execute them safely.

Programs do not “do things” directly. They declare effects. Execution authority lives outside the language.

Eulisp is built around three core ideas:

• Effects are data
• Control flow is forbidden inside effect declarations
• All execution authority lives outside the language

You construct a dependency graph of effect descriptions. Ω (the Governor) later admits, orders, executes, and records them.

This guide is for:

• complete beginners (including people who have never programmed)
• people who want practical copy-paste examples
• contributors who want a quick mental model before reading dev docs

For runtime internals, see docs/dev-docs.org.

An eulisp program goes through four stages:

• Parsing Source code → S-expressions.
• Elaboration Syntax → AST. Ethical and structural constraints are enforced here.
• Evaluation (Pure) Expressions evaluate. Effects are collected, not executed.
• Governance & Execution Governor decides:
  • which effects are admissible
  • when they can run
  • whether dependencies are satisfied

Then it executes them and records them in a ledger.

(effect main ()
(print "Hello from Eulisp"))

What happens:

• main describes one print effect.
• Governor executes it.
• You see output.

Effects are created using primitives like:

(print "hello")
(write-file "out.txt" "data")
(read-file "out.txt")
(done "finished")
(sleep 1000)

These do not perform IO immediately. They return structured values of type EffectDescription. Effects may be:

• stored
• returned
• composed
• placed in lists

At the end of evaluation, all effects reachable from main are collected.

; file artifact with optional dependencies
(emit-artifact "artifact.txt" "content")
(emit-artifact "artifact.txt" "content" (list dep-id))

; read realized result of an effect
(result some-effect)

A Practical File Example

(effect main ()
((lambda (template templateRead0)
((lambda (templateRead)
(list
template
templateRead
(emit-artifact
"todo-today.txt"
(concat
"# Daily Checklist\n\n"
(result templateRead)
"\nGenerated by eulisp.\n")
(list (hash templateRead)))
(done "demo complete")))
(depend (hash template) templateRead0)))
(emit-artifact
"todo-template.txt"
"- [ ] Review priorities\n- [ ] Ship one thing\n")
(read-file "todo-template.txt")))

Dependencies are explicit and manual.

(depend
(hash first-effect)
second-effect)

Meaning second-effect may run only after first-effect succeeds. Multiple dependencies:

(depend (list h1 h2 h3) effect)

You can declaratively build effect graphs:

(let (effects
(map sleep (list 100 200 300)))
(depend
(map hash effects)
(print "all done")))

No loops. No runtime branching. Just graph construction.

Every effect has a cryptographic identity: SHA256(canonical encoding of EffectDescription)

(hash (print "hello"))

Properties:

• identical descriptions → identical IDs
• IDs are 256-bit SHA digests
• identity is content-addressed
• no counters
• no runtime integers
• runtime result does not affect identity

Ω is not part of the language syntax. It is the runtime authority.

Responsibilities:

• admit or reject effects
• enforce idempotence (via SHA256 identity)
• resolve dependencies
• execute effects in parallel waves
• record an immutable ledger
• verify outcomes
• detect cycles and unresolved deadlocks
• pre-validate dependency graph

The ledger is:

• append-only
• deterministic (sorted by EffectID)
• persisted in sqlite

Each entry stores:

• pass number
• decision
• outcome
• structured result

Runtime logs are structured.

Modes:

• default → pretty structured logs
• --json-logs → JSON log lines
• --silent → hide system logs (user print and done still visible)

Example JSON log:

{"timestamp":"...","level":"info","event":"effect.print","message":"hello"}

Common flags:

• --ledger
• --print-ledger
• --clear-ledger
• --debug
• --print-graph
• --json-logs
• --silent