# The `.sldocument` Format — Ordered, Top-Down SLeeLa Documents
**Family:** `lib/sldocument`
**Format extension:** `.sldocument`
**Format version:** `1.0`
**Compiles with:** standard SLeeLa source (`.sleela`) via the SLeeLa Compiler
**Native bridge:** `native/include/sleela_sldocument.h`, `native/src/sleela_sldocument.cpp`
An `.sldocument` is an **ordered document**: its code runs **top-down**, step by
step, and it is compiled **against and with standard SLeeLa source**. Each step
is a method, and that method generally returns **a single binary item** that is
"**veritable and kind**" — a verified truth of the right kind.
These documents suit tasks more sophisticated than scripting in bash, and clear
**national-program** work where the order is already established, so the author
moves in assumed flow and architecture rather than writing control plumbing.
## Where it sits among SLeeLa source forms
| Form | Extension | Shape | Use |
|---|---|---|---|
| SLeeLa program | `.sleela` | classes of fields and methods | the general language |
| Sleela Script | `.sleela-script` | dynamic procedural script | short automation, glue |
| **SLeeLa Document** | **`.sldocument`** | **ordered top-down steps** | **settled, ordered flows** |
A document is not a replacement for `.sleela`; it is a *conductor* over compiled
SLeeLa methods, giving an established order a first-class, readable home.
## Document structure
```
#sldocument 1.0
document "title"
with source "companion/One.sleela"
with source "companion/Two.sleela"
// steps, top-down
first_step()
@function("role")
second_step()
@order(3)
third_step()
final_step()
```
- `#sldocument 1.0` — the format version line (required, first line).
- `document "title"` — the document's name.
- `with source "..."` — a companion `.sleela` source compiled alongside, so step
methods resolve to ordinary compiled SLeeLa.
- the remainder is the **ordered step list**.
## Steps, naming, and annotations
Each step is a method invocation. How a step is named and ordered follows one of
three annotation forms (`SLDocumentAnnotation`):
| Form | Meaning |
|---|---|
| *bare method name* | the method name **is** the step name; its order is its **textual (top-down) position** |
| `@order(n)` | an **explicit** 1-based position; governs over textual order |
| `@function("role")` | annotates the step's **declared role/function**; does **not** change order |
When `@order` is present it governs; otherwise textual order governs. A clean
document resolves to a settled `1..N` sequence (the compiler validates there are
no gaps or duplicate `@order` values).
## The single binary return — veritable and kind
Each step usually returns one binary item, modeled by `SLVeritable`:
- **veritable** — the binary truth: did the step hold? (`bit()` is `1` or `0`)
- **kind** — is the result well-formed and benign (the right *kind* of value)?
A value is **sound** only when it is **veritable AND kind**. A step that returns
a true-but-ill-formed result is *veritable but not kind*, and the document does
not treat it as a clean pass. Logical composition (`and`, `or`) propagates
kindness, so a fault never hides behind a true bit.
## Running a document
`SLDocument.run()` runs top-down:
1. steps are **arranged by effective order** (explicit `@order`, else top-down);
2. each step is **invoked in order**, and its single binary veritable value is
recorded in `SLDocumentResult`;
3. by default the document **stops at the first unsound step** (fail-closed) —
an ordered program should not proceed past a broken step. `permitContinue()`
relaxes this to record every step.
`SLDocumentResult.finalBit()` is the document's final binary item (the last
step's bit, which in an established order is the final result of the flow), and
`sound()` holds only when every recorded step was sound. `firstFault()` points
to exactly where an ordered national program broke.
## Compiling with standard SLeeLa source
`SLDocumentCompiler` drives the normal SLeeLa Compiler path with document
semantics:
1. register companion `.sleela` sources (`withSource`) so step symbols resolve;
2. lower each annotated step to a VM-invocable method entry;
3. `validateOrder()` — confirm a clean `1..N` sequence (no gaps/duplicates);
4. `compile()` yields a VM frame handle the document runs against;
5. `compileAndRun()` compiles and runs in one call.
The authoritative compilation remains the SLeeLa Compiler (`lib/compiler`,
`impl/frontend`); this class is the document-aware front end to it.
## A compile choice from the SLeeLa compiler
`.sldocument` is a selectable **compile choice**, not a separate toolchain. The
compiler family exposes it through two classes in `lib/compiler`:
- **`SLSourceForm`** — names each SLeeLa source form and its extension:
`SLEELA` (`.sleela`), `SLDOCUMENT` (`.sldocument`), `SLSCRIPT`
(`.sleela-script`). It can infer the form from a file name (the longer
`.sldocument` extension is matched before `.sleela`).
- **`SLCompileChoice`** — records which form to compile, either explicitly
(`choose(path, SLSourceForm.SLDOCUMENT)`) or by inferring it from the path
(`chooseFromPath`). `compile()` then routes a document through the
document-aware path and a program through the ordinary `.sleela` path. The
choice is fail-closed: an unrecognised extension is surfaced as a diagnostic,
never guessed.
This slots into the compiler selection model
(`language → family → version → producer → source form → IR/object → target`):
`.sldocument` is one of the recognised **source forms**. The extension is also
registered in `lib/compiler/LANGUAGE.FORMAT.REFERENCE.md`.
## Naming conventions — comparing `.sleela` and `.sldocument`
The two forms name things differently: a `.sleela` program names **every**
method, while a `.sldocument` **may leave steps anonymous** (identified only by
order or `@function` role). That is fine while a document runs — but if an
engineer converts a `.sldocument` to a `.sleela` **for safekeeping**, every step
must become a named method.
- **`SLDocumentNaming`** is the convention authority. It gives each step a stable,
legal `.sleela` method name, deterministically:
1. keep an explicit method name (sanitized to a legal identifier);
2. else derive from a `@function` role (`"reconcile accounts"` →
`reconcileAccounts`);
3. else synthesize from the ordered position (`@order(3)` or textual position
3 → `step003`), which is stable and collision-resistant.
- **`SLSourceNameComparison`** pairs each document step with the `.sleela` method
name it *would* have, flagging which names had to be **synthesized** and
whether any two steps **collide**. `convertible()` is true only when there are
no collisions.
- **`SLDocumentConverter`** performs the conversion: it `plan()`s the names,
refuses to proceed on a collision (fail-closed), and emits a `.sleela` class
whose methods are the named steps plus a `run()` that calls them in the same
top-down order — preserving the single-binary / veritable-and-kind contract.
`convertToFile(doc, "Kept.sleela")` writes the kept program.
So an anonymous ordered document round-trips into a fully named program for
archival, review, or further hand-editing, without losing its established order.
## Classes
| Class | Role |
|---|---|
| `SLDocument` | the ordered document; runs steps top-down |
| `SLDocumentStep` | one annotated/ordered step method |
| `SLDocumentAnnotation` | the `@order` / `@function` / bare-method vocabulary |
| `SLVeritable` | the single binary veritable-and-kind return value |
| `SLDocumentResult` | the ordered collection of step values |
| `SLDocumentCompiler` | compiles the document with standard SLeeLa source |
| `SLDocumentNaming` | names anonymous steps for `.sleela` conversion |
| `SLSourceNameComparison` | compares `.sleela` vs `.sldocument` step naming |
| `SLDocumentConverter` | converts a `.sldocument` to a `.sleela` for safekeeping |
| `SLSourceForm` *(lib/compiler)* | the source-form / extension catalogue |
| `SLCompileChoice` *(lib/compiler)* | selects `.sldocument` vs `.sleela` to compile |
## Example
See [`examples/national-ledger.sldocument`](examples/national-ledger.sldocument):
a settled four-step national-ledger close (verify → reconcile → post to the
national register → finalize), compiled with its companion `.sleela` sources.
## Native bridge
- `sleela_sldocument_compile(title, version, companions)` — compile with companion sources; returns a frame handle.
- `sleela_sldocument_invoke(frame, method, order)` — invoke one step; returns the single binary veritable item (1/0).
- `sleela_sldocument_kind(frame, method)` — report whether the step's value is kind (well-formed/benign).
- `sleela_compile_choice(path, form)` — compile a chosen source form (`.sldocument` or `.sleela`); returns a frame handle.
- `sleela_sldocument_synth_name(prefix, order, …)` — synthesize a stable name (`step003`) for an anonymous step.
- `sleela_sldocument_sanitize_identifier(raw, …)` — make a string a legal SLeeLa identifier.
- `sleela_sldocument_camel_from_role(role, …)` — role → camelCase (`reconcileAccounts`).
- `sleela_sldocument_emit_sleela(class, title, steps, …)` — emit the `.sleela` class for a converted document.
- `sleela_sldocument_write(path, source)` — write the converted `.sleela` for safekeeping.
```sh
cd native
make test # builds + self-tests audio, opcode, governance, and sldocument bridges
```
**Max Rupplin — MEARVK LLC — 2026**