@lemmabase/lemma-engine 0.8.11 → 0.8.13

package/README.md

@@ -1,8 +1,50 @@
 # @lemmabase/lemma-engine
 
-Embeddable Lemma engine (WebAssembly).
+> [Lemma](https://github.com/lemma/lemma) is a declarative language for business rules. **This package is the engine, compiled to WebAssembly** - runs in the browser, on Node, Bun, Deno, Cloudflare Workers, Vercel Edge, etc.
 
-npm `description` / `keywords` / `homepage`: edit **`NPM_BRANDING`** in `build.js` (not Cargo).
+Pricing tiers, tax brackets, leave entitlement, eligibility checks, discount stacks: the rules that change, that auditors ask about, that legal writes in PDFs and engineers re-implement in operational code... Lemma is a language built specifically for your business rules. It is readable by stakeholders, executable anywhere, and impossible to drift out of sync.
+
+```lemma
+spec pricing 2026-01-01
+
+data money: scale
+  -> unit eur 1.00
+  -> decimals 2
+
+data quantity : number
+data is_vip   : false
+
+rule unit_price:
+  20 eur
+  unless quantity >= 10 then 18 eur
+  unless quantity >= 50 then 16 eur
+  unless is_vip         then 15 eur
+
+rule total:
+  unit_price * quantity
+```
+
+```javascript
+import { Lemma } from '@lemmabase/lemma-engine';
+
+const engine = await Lemma();
+await engine.load(pricing, 'pricing.lemma');
+
+const response = engine.run(null, 'pricing', [], { quantity: 50, is_vip: false }, null);
+// response.results.unit_price → 16 eur
+// response.results.total      → 800 eur
+```
+
+The `Response` carries every rule's value (or `veto` if no result could be computed), the input snapshot, and the source location of every rule that fired, allowing you to render an audit trail in your UI.
+
+## Why use it from JavaScript?
+
+- **Deterministic.** `(spec, data, effective_date) → result`. No DB, no clock, no ambient state. Same inputs → same outputs, every time.
+- **Explainable.** The `Response` tells you which rules contributed and why; pair it with the [CLI](https://github.com/lemma/lemma) for a full reasoning trace.
+- **Time-aware.** Multiple versions of the same spec coexist. Pass an `effective` date and the engine resolves the version in force on that day.
+- **Statically checked.** Type errors, missing data, cycles, scale-family mismatches - all caught at `load()` time. Bad specs never reach `run()`.
+- **Runs anywhere V8 does.** ~2 MB WASM, no native binary, no postinstall script.
+- **Editor in a tab.** Includes an in-process language server and a Monaco adapter, so you can build a real Lemma editor experience client-side - diagnostics, completion, formatting... even without setting up a server.
 
 ## Install
 
@@ -10,7 +52,7 @@ npm `description` / `keywords` / `homepage`: edit **`NPM_BRANDING`** in `build.j
 npm install @lemmabase/lemma-engine
 ```
 
-## Browser / bundler
+## Browser
 
 ```javascript
 import { Lemma } from '@lemmabase/lemma-engine';
@@ -18,39 +60,35 @@ import { Lemma } from '@lemmabase/lemma-engine';
 const engine = await Lemma();
 ```
 
-`Lemma()` initializes WASM once and returns an `Engine`. Serve over **http(s)** (not `file://`). For manual init: `init()` then `new Engine()`.
+`Lemma()` initializes the WASM module once and returns an `Engine`. Serve over **http(s)**, not `file://`. For manual control: `init()` then `new Engine()`.
 
-If your bundler outputs IIFE (or otherwise breaks `import.meta.url`), use:
+If your bundler emits IIFE, can't resolve `import.meta.url`, or refuses to ship `lemma_bg.wasm` as a separate asset, use the inlined entry - it embeds the wasm bytes in the JS bundle:
 
 ```javascript
 import { Lemma } from '@lemmabase/lemma-engine/iife';
-
-const engine = await Lemma();
 ```
 
-This entry embeds WASM bytes and avoids external wasm URL handling.
-
-## esbuild auto-handler
-
-If you use esbuild JS API, plugin rewrites root import to `/iife` automatically:
+esbuild users get an auto-rewriting plugin:
 
 ```javascript
 import { lemmaEngineEsbuildPlugin } from '@lemmabase/lemma-engine/esbuild';
+
+esbuild.build({ /* ... */ plugins: [lemmaEngineEsbuildPlugin()] });
 ```
 
 ## Node
 
+Identical to the browser path:
+
 ```javascript
 import { Lemma } from '@lemmabase/lemma-engine';
 
 const engine = await Lemma();
 ```
 
-Or with a preloaded buffer (e.g. no async fetch): `initSync({ module })` then `new Engine()`.
+For zero-fetch startup with a preloaded module: `initSync({ module })` then `new Engine()`.
 
-## LSP (browser streams)
-
-Call `init()` first. Use `LspClient`; `start()` uses the bundled LSP (no need to pass `serve`/`ServerConfig`). Optional: `start(serve, ServerConfig)` to override.
+## In-process LSP + Monaco
 
 ```javascript
 import { init } from '@lemmabase/lemma-engine';
@@ -60,23 +98,55 @@ await init();
 const client = new LspClient(monaco);
 await client.start();
 await client.initialize();
-client.onDiagnostics((uri, diagnostics) => { /* ... */ });
-client.didOpen(uri, 'lemma', 1, documentText);
+
+client.onDiagnostics((uri, diagnostics) => { /* render */ });
+client.didOpen('file:///pricing.lemma', 'lemma', 1, source);
 ```
 
-## API (`Engine`)
+A pre-wired Monaco adapter ships at `@lemmabase/lemma-engine/monaco`.
+
+## API
+
+`Engine` (returned by `Lemma()` or `new Engine()`):
+
+| Method | Description |
+|--------|-------------|
+| `load(code, attribute?)` | Parse and validate a `.lemma` spec set. Resolves on success; rejects with `EngineError[]`. |
+| `load_batch(sources, dependency?)` | Load many sources in one planning pass (see `lemma.d.ts`). |
+| `fetch(name)` | Download registry source only; resolves with `{ source, id }`. Does not load. Rejects with `EngineError[]`. |
+| `list()` | JSON array of `ResolvedRepository`: each has `repository` and `specs` (spec sets). Each set has `name`, `repository`, and `specs` — temporal versions as full `LemmaSpec` objects (`effective_from`, `start_line`, `source_type`, …). |
+| `schema(repo, name, effective?)` | `SpecSchema`; `repo` null for workspace. |
+| `run(repo, name, ruleNames, data, effective?)` | Evaluate. `rules: []` runs everything; pass an array to filter. Returns a `Response`. |
+| `format(code, attribute?)` | Canonical formatting; throws `EngineError` on parse error. |
+
+Full TypeScript types are bundled - see `lemma.d.ts`.
+
+### Registry dependencies
+
+Specs that reference `uses … @org/pkg` need that package available. `fetch` only downloads; call `load_batch` to load the dependency, then load your workspace:
+
+```javascript
+import { Lemma } from '@lemmabase/lemma-engine';
+
+const engine = await Lemma();
+const { source, id } = await engine.fetch('@lemma/std');
+await engine.load_batch({ '': source }, id);
+await engine.load(sourceThatUsesStd, 'app.lemma');
+```
+
+In the browser, the registry must allow your origin (CORS). Use `https` or `http://localhost` when using `fetch`.
+
+## Status
 
-| Method | |
-|--------|--|
-| `load(code, attribute)` | Promise; reject → `string[]` |
-| `list()` | Spec entries |
-| `schema(spec, effective?)` | `SpecSchema` |
-| `run(spec, rules, data, effective?)` | `Response` |
-| `format(code, attribute?)` | string or throw |
+Lemma is in early development. Expect breaking changes between minor versions; **don't put it in front of paying customers yet**. Production-readiness tracking lives in the [main repo](https://github.com/lemma/lemma).
 
-## Build (maintainers)
+## Related
 
-`node build.js`: wasm-pack → `lemma.bindings.js` + `lemma_bg.wasm` → copy checked-in `lemma-entry.js` / `lsp-entry.js` / `*.d.ts` into `dist/`. Do not edit generated bindings by hand.
+- [`lemmabase.com`](https://lemmabase.com): public database for Lemma Specs
+- [`lemma-cli`](https://crates.io/crates/lemma-cli): REPL, HTTP server, MCP server, formatter
+- [`lemma-engine`](https://crates.io/crates/lemma-engine): same engine as a Rust crate
+- [`lemma_engine` on Hex](https://hex.pm/packages/lemma_engine): Elixir bindings via Rustler
+- VS Code / Cursor extension: search "Lemma Language" in the marketplace
 
 ## License
 

package/lemma.bindings.d.ts

@@ -11,41 +11,54 @@ type ReadableStreamType = "bytes";
 export class Engine {
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Download Lemma source for a registry identifier via [`crate::registry::LemmaBase`]. Returns `{ source, id }`.
+     * Does not load this [`WasmEngine`]; call [`Self::load_batch`], etc., yourself.
+     */
+    fetch(name: string): Promise<any>;
     /**
      * Returns formatted source string on success; throws with error message on failure.
      */
     format(code: string, attribute?: string | null): any;
     invert(_spec_name: string, _rule_name: string, _target_json: string, _provided_values_json: string): any;
     /**
-     * Loaded specs, each paired with its planning schema.
-     *
-     * Each entry has `{ name, effective_from, effective_to, schema }`. The
-     * pair describes a half-open `[effective_from, effective_to)` validity
-     * range; `effective_from` is `null` when the first version has no
-     * declared start, and `effective_to` is `null` for the latest version of
-     * a name (no successor). Order matches [`Engine::list_specs_with_ranges`].
-     *
-     * `schema` is the same envelope returned by [`WasmEngine::schema`] for
-     * `(name, effective_from)`; shipping it inline saves the N+1 round-trip
-     * every consumer (playground, dashboards, docs) was doing.
+     * Same data as [`Engine::list`]: grouped [`ResolvedRepository`] JSON without planning.
      */
     list(): any;
     /**
-     * Load Lemma source. Resolves with `undefined` on success; rejects with an array of
-     * serialized errors (same shape as `EngineError` in `engine/packages/npm/lemma.d.ts`).
+     * Load Lemma source. Throws with an array of serialized errors
+     * (same shape as `EngineError` in `engine/packages/npm/lemma.d.ts`).
+     */
+    load(code: string, attribute: string): void;
+    /**
+     * Load multiple Lemma sources in one planning pass (same as [`Engine::load_batch`]).
      *
-     * Breaking: previously rejected with an array of strings.
+     * `sources` is a plain object mapping path labels to source text. Labels become
+     * [`SourceType::Path`]; use `""` as a key for [`SourceType::Volatile`].
+     *
+     * `dependency`: when non-empty after trim, sources are tagged as that dependency id.
+     *
+     * Throws with an array of `JsError` on failure.
      */
-    load(code: string, attribute: string): Promise<any>;
+    load_batch(sources: any, dependency?: string | null): void;
     constructor();
+    /**
+     * Loaded repositories (workspace and dependencies): `{ name, dependency }`.
+     */
+    repositories(): any;
     /**
      * Evaluate spec. Returns [`crate::evaluation::Response`] as a JS object. Throws on planning/runtime error.
+     *
+     * `repository`: repository qualifier (`@org/pkg`), or `null`/empty for workspace (same as
+     * [`Engine::run`] `repo: None`).
      */
-    run(spec: string, rule_names: any, data_values: any, effective?: string | null): any;
+    run(repository: string | null | undefined, spec: string, rule_names: any, data_values: any, effective?: string | null): any;
     /**
      * Planning schema for the spec ([`crate::planning::execution_plan::SpecSchema`]). Throws on error.
+     *
+     * `repository`: qualifier string or `null`/empty for workspace ([`Engine::schema`]).
      */
-    schema(spec: string, effective?: string | null): any;
+    schema(repository: string | null | undefined, spec: string, effective?: string | null): any;
 }
 
 export class IntoUnderlyingByteSource {
@@ -109,16 +122,19 @@ export interface InitOutput {
     readonly intounderlyingsource_cancel: (a: number) => void;
     readonly intounderlyingsource_pull: (a: number, b: number) => number;
     readonly __wbg_engine_free: (a: number, b: number) => void;
+    readonly wasmengine_fetch: (a: number, b: number, c: number) => number;
     readonly wasmengine_format: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly wasmengine_invert: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => void;
     readonly wasmengine_list: (a: number, b: number) => void;
-    readonly wasmengine_load: (a: number, b: number, c: number, d: number, e: number) => number;
+    readonly wasmengine_load: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly wasmengine_load_batch: (a: number, b: number, c: number, d: number, e: number) => void;
     readonly wasmengine_new: () => number;
-    readonly wasmengine_run: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
-    readonly wasmengine_schema: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
-    readonly __wasm_bindgen_func_elem_10702: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_2761: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_10709: (a: number, b: number, c: number, d: number) => void;
+    readonly wasmengine_repositories: (a: number, b: number) => void;
+    readonly wasmengine_run: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => void;
+    readonly wasmengine_schema: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
+    readonly __wasm_bindgen_func_elem_10830: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_2759: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_10848: (a: number, b: number, c: number, d: number) => void;
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_export3: (a: number) => void;