lemma 0.9.2

A pure, declarative language for business rules.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238

---
nav_title: Lemma CLI
nav_order: 20
---

# Lemma CLI

See [Installation](../installation.md) for install options.

## Commands

### `lemma run`: evaluate a spec

```bash
lemma run [[repo] spec] [name=value ...] [--prefix PATH] [--rules=RULES] [options]
```

**Syntax:**
- Positionals: optional repository qualifier (e.g. `@iso/countries`), then spec name (see `lemma run --help`)
- `spec --rules=rule`: evaluate one rule
- `spec --rules=rule1,rule2`: evaluate specific rules (comma-separated)
- No arguments with `-i`: interactive mode

**Options:**
- `--prefix <path>`: workspace directory or `.lemma` file (default: current directory)
- `--rules <rules>`: comma-separated rule names (omit to evaluate all)
- `--json`: output results as JSON (default: human-readable table). Each rule result may include `missing_data` (unbound input keys). Types, prefilled values, and suggestions come from `lemma show`, not from evaluate JSON.
- `-x, --explain`: include explanation trees (human: reasoning tables; JSON: per-rule `explanation` objects matching [`api.v1.json`](../schemas/api.v1.json)). Human output prints **Missing data** when any requested rule lists unbound keys.
- `-i, --interactive`: guided spec/rule/data selection
- `--effective <datetime>`: evaluate at effective datetime (e.g. `2025`, `2025-03`, `2025-03-04`)

**Examples:**

```bash
lemma run pricing
lemma run pricing --rules=total,tax
lemma run --prefix ./policies nl/tax/net_salary --rules=net_salary -x
lemma run pricing quantity=10 is_vip=true
lemma run pricing --json
lemma run pricing -x
lemma run pricing --effective 2025-01-01
lemma run -i
lemma run '@iso/countries' alpha2
```

### `lemma show`: spec interface (data types, constraints, and rules)

Shows data inputs with types and constraints (minimum, maximum, units, decimals, text options), prefilled values, suggestions, and rule result types. Lemma source text is available via `Engine::source` (API) only.

`show` lists data that is statically reachable from rules after normalize (all remaining unless arms; no caller run bindings). Run-data-aware pruning for a concrete `run` is per-rule `results.*.missing_data`; static types and suggestions are on `show` only.

```bash
lemma show [[repo] spec] [--prefix PATH] [--effective <datetime>] [--json]
```

**Options:**
- `[repo]`: optional repository qualifier (e.g. `@iso/countries`)
- `[spec]`: spec name (omit when workspace has a single spec)
- `--prefix <path>`: workspace directory or `.lemma` file (default: current directory)
- `--effective <datetime>`: effective datetime for temporal specs
- `--json`: output as JSON (default: human-readable table)

**Examples:**

```bash
lemma show pricing
lemma show --prefix ./policies net_salary
lemma show --prefix tax.lemma calculator
lemma show '@iso/countries' alpha2
lemma show pricing --json
```

### `lemma list`: list loaded specs by repository

Lists every loaded spec, grouped by repository. Local specs (no repository qualifier) are printed unindented; named repositories (including embedded `lemma`) appear as headers with indented spec names.

```bash
lemma list [--prefix PATH] [--json]
```

**Options:**
- `--prefix <path>`: workspace directory or `.lemma` file (default: current directory)
- `--json`: output `Engine::list()` JSON — array of `{ "repository", "specs" }` where each spec is a `ListedSpec` (`name`, optional `effective_from` / `effective_to`). Human text lists unique spec names only.

**Examples:**

```bash
lemma list
lemma list --prefix ./project
lemma list --json
```

### `lemma fetch`: fetch registry dependencies

Resolves `@...` references and downloads specs from the registry.

```bash
lemma fetch [--prefix PATH] --all
lemma fetch [--prefix PATH] <dependency> -f
```

**Options:**
- `--prefix <path>`: workspace directory or `.lemma` file (default: current directory)
- `-a, --all`: fetch all @... references in the workspace
- `-f, --force`: overwrite existing specs when content has changed on the registry

### `lemma format`: format .lemma files

```bash
lemma format [paths...] [--check] [--stdout]
```

**Options:**
- `--check`: check formatting without modifying (exit 1 if any file would change)
- `--stdout`: write formatted output to stdout

### `lemma server`: start HTTP server

```bash
lemma server [--prefix PATH] [--host <host>] [-p <port>] [--watch] [--explanations] [--eval-timeout SECONDS] [--cors]
```

**Options:**
- `--prefix <path>`: workspace directory or `.lemma` file (default: current directory)
- `--host <host>`: bind address (default: `127.0.0.1`)
- `-p, --port <port>`: port (default: `8012`)
- `--watch`: live-reload on `.lemma` file changes
- `--explanations`: enable explanation generation (clients send `x-explanations` header; JSON shape [`api.v1.json`](../schemas/api.v1.json))
- `--eval-timeout <second>`: wall-clock timeout for a single evaluation request (default: `10`)
- `--cors`: allow cross-origin browser requests from any origin (off by default)

**Routes:**

| Method | Route | Description |
|--------|-------|-------------|
| GET | `/` | List all specs |
| GET | `/{spec}` | Show spec interface (data, rules, versions) |
| POST | `/{spec}` | Evaluate (data as JSON or form body) |
| GET/POST | `/{spec}/{rules}` | Evaluate specific rules (comma-separated) |
| GET | `/openapi.json` | OpenAPI 3.1 specification |
| GET | `/docs` | Interactive API documentation (Scalar) |
| GET | `/health` | Health check |

**Example:**

```bash
lemma server --prefix ./policies --watch

curl "http://localhost:8012/pricing?quantity=10&is_member=true"

curl -X POST http://localhost:8012/pricing \
  -H "Content-Type: application/json" \
  -d '{"quantity": 10, "is_member": true}'
```

### `lemma lsp`: start language server

Starts the Language Server Protocol server over stdio for editor integration (diagnostics, formatting, semantic tokens). The VS Code/Cursor extension invokes this automatically; a globally installed `lemma` CLI is the only requirement.

```bash
lemma lsp
```

### `lemma mcp`: start MCP server

AI assistant integration via Model Context Protocol over stdio.

```bash
lemma mcp [--prefix PATH] [--admin] [--request-timeout SECONDS]
```

**Options:**
- `--prefix <path>`: workspace directory or `.lemma` file (default: current directory)
- `--admin`: enable admin tools (read-only by default)
- `--request-timeout <second>`: wall-clock timeout for a single request (default: `10`)

**Tools (default):**
- `evaluate` — evaluate rules in a spec (always includes explanation trees; unlike CLI/HTTP/WASM, there is no opt-out). Measure/ratio results include every declared unit.
- `list` — list loaded specs by repository
- `show` — return the JSON Show for a spec (data and rules, including units)
- `check` — parse and plan a batch of labeled Lemma sources (ephemeral engine, does not mutate server state); returns success confirmation or structured diagnostics
- `guide` — return a section of the embedded authoring guide (`syntax`, `data`, `rules`, `units`, `veto`, `composition`, `anti_patterns`)

**Resources:** `lemma://guide`, `lemma://guide/{topic}`, `lemma://examples/{name}` (curated examples under `cli/documentation/examples/`).

**Tools (with `--admin`):**
- `add_spec` — load Lemma source into the engine (structured diagnostics on failure)
- `source` — return formatted Lemma source for a repository or spec

## Workspace

A workspace is a directory containing `.lemma` files. Commands that load specs use `--prefix` to select the workspace (default: current directory). Every `.lemma` file is loaded recursively from that directory, plus any registry deps from the global cache.

```
policies/
  pricing.lemma
  shipping.lemma
  tax.lemma
```

## Resource Limits

Resource limits control parse-time and planning-time budgets. These are security boundaries that prevent unbounded resource consumption from untrusted input.

| Limit | Default | Purpose |
|-------|---------|---------|
| `max_sources` | 4096 | Maximum source files in one engine |
| `max_loaded_bytes` | 50 MB | Total source text across all files |
| `max_source_size_bytes` | 5 MB | Single source file size |
| `max_expression_depth` | 7 | AST nesting depth |
| `max_expression_count` | 65,536 | Expression nodes per source (parser) |
| `max_normalized_expression_nodes` | 30,000 | Unique normal-form cells reachable from one rule root after normalize |
| `max_normal_form_depth` | 4096 | Nesting depth of a rule's normalized NormalForm DAG |
| `max_data_value_bytes` | 1 KB | Single data value size |
| `max_spec_dependency_depth` | 32 | `uses` chain depth |
| `max_dag_specs` | 4096 | Total specs in dependency DAG |

`max_expression_depth` and `max_spec_dependency_depth` bound recursion during parsing and planning. Raising these beyond the defaults requires stack analysis for your deployment.

## API Defaults

**Effective datetime**: when no `--effective` flag or `Accept-Datetime` header is provided, the engine uses the current instant to select the temporal version of the root spec.

**Accept-Datetime (HTTP)**: clients send `Accept-Datetime` with the same formats as `--effective`: `YYYY`, `YYYY-MM`, `YYYY-MM-DD`, or an ISO 8601 datetime. Empty or omitted → now. Invalid values are a bad request. Responses include `Vary: Accept-Datetime`. When the resolved spec row has an `effective_from`, the server also sets `Memento-Datetime` to that instant.

**Explanations**: disabled by default in CLI (`lemma run`), HTTP, and WASM. Use `--explain` (CLI), `--explanations` (server) + `x-explanations` (client), or `explain: true` (SDK) to opt in. MCP `evaluate` always sets `explain: true` (no opt-out). Evaluate JSON has no top-level `data` array: unbound inputs are per-rule `missing_data`; types and suggestions come from `lemma show`. When explanations are enabled, each `results.<rule>.explanation` is a rule node (`"type":"rule"`, `"name"`, `"result"`, `"body"`, optional `"causes"` / `"children"`) per [`api.v1.json`](../schemas/api.v1.json) — bound data uses `"type":"data"`, unused cause paths `"type":"data_unused"`.

## See Also

- [Learn guide](../learn/readme.md)
- [Installation](../installation.md)
- [Language reference](readme.md)
- [API schema](../schemas/api.v1.json) (Show, Response, list, errors, `RuleResult.explanation` / `ExplanationNode`)
- [LemmaBase](registry.md)
- [Engine test coverage](coverage/engine.md)
- [CLI test coverage](coverage/cli.md)
- [CLI benchmarks](benchmarks/cli.md)
- [Engine benchmarks](benchmarks/engine.md)