@lemmabase/lemma-engine 0.8.15 → 0.8.17

package/README.md

@@ -30,7 +30,7 @@ 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);
+const response = engine.run(null, 'pricing', null, { quantity: 50, is_vip: false }, null);
 // response.results.unit_price → 16 eur
 // response.results.total      → 800 eur
 ```
@@ -114,10 +114,10 @@ A pre-wired Monaco adapter ships at `@lemmabase/lemma-engine/monaco`.
 | `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). Always includes embedded `lemma` / `spec si`. |
-| `format_repository(repo)` | Canonical Lemma source for a loaded repository, formatted from the in-engine AST. Use `"lemma"` for the embedded SI stdlib. |
+| `list()` | JSON array of `ResolvedRepository`: each has `repository` and `specs` (spec sets). Always includes embedded `lemma` / `spec units`. |
+| `format_repository(repo)` | Canonical Lemma source for a loaded repository, formatted from the in-engine AST. Use `"lemma"` for the embedded units stdlib. |
 | `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`. |
+| `run(repo, name, ruleNames, data, effective?, explain?)` | Evaluate. Omit/`null` `ruleNames` for all rules; pass a non-empty array to scope. `[]` errors. Returns a `Response`. |
 | `format(code, attribute?)` | Canonical formatting; throws `EngineError` on parse error. |
 
 Full TypeScript types are bundled - see `lemma.d.ts`.
@@ -139,12 +139,12 @@ In the browser, the registry must allow your origin (CORS). Use `https` or `http
 
 ## Status
 
-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).
+Lemma is pre-1.0. The WASM API is stable for most use cases, but breaking changes may occur between minor versions. Pin your dependency version and review the [changelog](https://github.com/lemma/lemma/blob/main/CHANGELOG.md) before upgrading.
 
 ## Related
 
 - [`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`](https://crates.io/crates/lemma): 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

package/lemma.bindings.d.ts

@@ -24,7 +24,7 @@ export class Engine {
      * Canonical Lemma source for `repository`, formatted from the in-engine AST (e.g. `"lemma"`).
      */
     format_repository(repository: string): string;
-    invert(_spec_name: string, _rule_name: string, _target_json: string, _provided_values_json: string): any;
+    invert(spec_name: string, rule_name: string, target_json: string, provided_values_json: string): any;
     /**
      * Same data as [`Engine::list`]: grouped [`ResolvedRepository`] JSON without planning.
      */
@@ -56,7 +56,7 @@ export class Engine {
      * `repository`: repository qualifier (`@org/pkg`), or `null`/empty for workspace (same as
      * [`Engine::run`] `repo: None`).
      */
-    run(repository: string | null | undefined, spec: string, rule_names: any, data_values: any, rule_result_units: any, effective?: string | null): any;
+    run(repository: string | null | undefined, spec: string, rule_names: any, data_values: any, effective?: string | null, explain?: boolean | null): any;
     /**
      * Planning schema for the spec ([`crate::planning::execution_plan::SpecSchema`]). Throws on error.
      *
@@ -137,9 +137,9 @@ export interface InitOutput {
     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, k: 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_11795: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_2721: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_11803: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_12158: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_2731: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_12161: (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;

package/lemma.bindings.js

@@ -80,22 +80,22 @@ export class Engine {
         }
     }
     /**
-     * @param {string} _spec_name
-     * @param {string} _rule_name
-     * @param {string} _target_json
-     * @param {string} _provided_values_json
+     * @param {string} spec_name
+     * @param {string} rule_name
+     * @param {string} target_json
+     * @param {string} provided_values_json
      * @returns {any}
      */
-    invert(_spec_name, _rule_name, _target_json, _provided_values_json) {
+    invert(spec_name, rule_name, target_json, provided_values_json) {
         try {
             const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-            const ptr0 = passStringToWasm0(_spec_name, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const ptr0 = passStringToWasm0(spec_name, wasm.__wbindgen_export, wasm.__wbindgen_export2);
             const len0 = WASM_VECTOR_LEN;
-            const ptr1 = passStringToWasm0(_rule_name, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const ptr1 = passStringToWasm0(rule_name, wasm.__wbindgen_export, wasm.__wbindgen_export2);
             const len1 = WASM_VECTOR_LEN;
-            const ptr2 = passStringToWasm0(_target_json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const ptr2 = passStringToWasm0(target_json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
             const len2 = WASM_VECTOR_LEN;
-            const ptr3 = passStringToWasm0(_provided_values_json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const ptr3 = passStringToWasm0(provided_values_json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
             const len3 = WASM_VECTOR_LEN;
             wasm.wasmengine_invert(retptr, this.__wbg_ptr, ptr0, len0, ptr1, len1, ptr2, len2, ptr3, len3);
             var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
@@ -212,11 +212,11 @@ export class Engine {
      * @param {string} spec
      * @param {any} rule_names
      * @param {any} data_values
-     * @param {any} rule_result_units
      * @param {string | null} [effective]
+     * @param {boolean | null} [explain]
      * @returns {any}
      */
-    run(repository, spec, rule_names, data_values, rule_result_units, effective) {
+    run(repository, spec, rule_names, data_values, effective, explain) {
         try {
             const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
             var ptr0 = isLikeNone(repository) ? 0 : passStringToWasm0(repository, wasm.__wbindgen_export, wasm.__wbindgen_export2);
@@ -225,7 +225,7 @@ export class Engine {
             const len1 = WASM_VECTOR_LEN;
             var ptr2 = isLikeNone(effective) ? 0 : passStringToWasm0(effective, wasm.__wbindgen_export, wasm.__wbindgen_export2);
             var len2 = WASM_VECTOR_LEN;
-            wasm.wasmengine_run(retptr, this.__wbg_ptr, ptr0, len0, ptr1, len1, addHeapObject(rule_names), addHeapObject(data_values), addHeapObject(rule_result_units), ptr2, len2);
+            wasm.wasmengine_run(retptr, this.__wbg_ptr, ptr0, len0, ptr1, len1, addHeapObject(rule_names), addHeapObject(data_values), ptr2, len2, isLikeNone(explain) ? 0xFFFFFF : explain ? 1 : 0);
             var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
             var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
             var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
@@ -715,7 +715,7 @@ function __wbg_get_imports() {
                     const a = state0.a;
                     state0.a = 0;
                     try {
-                        return __wasm_bindgen_func_elem_11803(a, state0.b, arg0, arg1);
+                        return __wasm_bindgen_func_elem_12161(a, state0.b, arg0, arg1);
                     } finally {
                         state0.a = a;
                     }
@@ -874,13 +874,13 @@ function __wbg_get_imports() {
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 1416, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_11795);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 1412, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_12158);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000002: function(arg0, arg1) {
             // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("IteratorResult<any>")], shim_idx: 7, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_2721);
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_2731);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000003: function(arg0) {
@@ -917,10 +917,10 @@ function __wbg_get_imports() {
     };
 }
 
-function __wasm_bindgen_func_elem_11795(arg0, arg1, arg2) {
+function __wasm_bindgen_func_elem_12158(arg0, arg1, arg2) {
     try {
         const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-        wasm.__wasm_bindgen_func_elem_11795(retptr, arg0, arg1, addHeapObject(arg2));
+        wasm.__wasm_bindgen_func_elem_12158(retptr, arg0, arg1, addHeapObject(arg2));
         var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
         var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
         if (r1) {
@@ -931,10 +931,10 @@ function __wasm_bindgen_func_elem_11795(arg0, arg1, arg2) {
     }
 }
 
-function __wasm_bindgen_func_elem_2721(arg0, arg1, arg2) {
+function __wasm_bindgen_func_elem_2731(arg0, arg1, arg2) {
     try {
         const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-        wasm.__wasm_bindgen_func_elem_2721(retptr, arg0, arg1, addHeapObject(arg2));
+        wasm.__wasm_bindgen_func_elem_2731(retptr, arg0, arg1, addHeapObject(arg2));
         var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
         var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
         if (r1) {
@@ -945,8 +945,8 @@ function __wasm_bindgen_func_elem_2721(arg0, arg1, arg2) {
     }
 }
 
-function __wasm_bindgen_func_elem_11803(arg0, arg1, arg2, arg3) {
-    wasm.__wasm_bindgen_func_elem_11803(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
+function __wasm_bindgen_func_elem_12161(arg0, arg1, arg2, arg3) {
+    wasm.__wasm_bindgen_func_elem_12161(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
 }
 
 

package/lemma.d.ts

@@ -35,7 +35,7 @@ declare module './lemma.bindings.js' {
     list(): ResolvedRepositoryJson[];
 
     /**
-     * Formatted Lemma source for a loaded repository (from in-engine AST). Use `"lemma"` for embedded SI stdlib.
+     * Formatted Lemma source for a loaded repository (from in-engine AST). Use `"lemma"` for embedded units stdlib.
      */
     format_repository(repository: string): string;
 
@@ -56,9 +56,9 @@ declare module './lemma.bindings.js' {
       spec: string,
       rule_names: string[] | string,
       data_values: Record<string, unknown>,
-      rule_result_units?: Record<string, string> | null,
       effective?: string | null,
-    ): any;
+      explain?: boolean,
+    ): EvaluationResponse;
   }
 }
 
@@ -207,6 +207,47 @@ export interface DataEntry {
   default?: LiteralValue;
 }
 
+/** Return shape of {@link Engine.run}. */
+export interface EvaluationResponse {
+  spec: string;
+  effective: string;
+  results: Record<string, RuleResult>;
+  data: EvaluationDataEntry[];
+}
+
+export interface RuleResult {
+  vetoed: boolean;
+  display?: string | null;
+  veto_reason?: string | null;
+  rule_type: string;
+  quantity?: Record<string, string> | null;
+  ratio?: Record<string, string> | null;
+  number?: string | null;
+  boolean?: boolean | null;
+  text?: string | null;
+  date?: unknown | null;
+  time?: unknown | null;
+  calendar?: { value: string; unit: string } | null;
+  range?: { from: RuleResultPayload; to: RuleResultPayload } | null;
+  explanation?: unknown | null;
+}
+
+export interface RuleResultPayload {
+  quantity?: Record<string, string> | null;
+  ratio?: Record<string, string> | null;
+  number?: string | null;
+  boolean?: boolean | null;
+  text?: string | null;
+  date?: unknown | null;
+  time?: unknown | null;
+  calendar?: { value: string; unit: string } | null;
+}
+
+export interface EvaluationDataEntry {
+  path: string;
+  value: unknown;
+}
+
 /** Return shape of {@link Engine.schema}. */
 export interface SpecSchema {
   spec: string;