@lemmabase/lemma-engine 0.8.12 → 0.8.13

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('pricing', [], { quantity: 50, is_vip: false }, null);
+const response = engine.run(null, 'pricing', [], { quantity: 50, is_vip: false }, null);
 // response.results.unit_price → 16 eur
 // response.results.total      → 800 eur
 ```
@@ -112,13 +112,30 @@ A pre-wired Monaco adapter ships at `@lemmabase/lemma-engine/monaco`.
 | Method | Description |
 |--------|-------------|
 | `load(code, attribute?)` | Parse and validate a `.lemma` spec set. Resolves on success; rejects with `EngineError[]`. |
-| `list()` | All loaded specs with metadata and an inlined `SpecSchema`. |
-| `schema(spec, effective?)` | `SpecSchema` for the spec at the given effective date. |
-| `run(spec, rules, data, effective?)` | Evaluate. `rules: []` runs everything; pass an array to filter. Returns a `Response`. |
+| `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
 
 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).

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_10686: (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_10704: (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;

package/lemma.bindings.js

@@ -11,6 +11,18 @@ export class Engine {
         const ptr = this.__destroy_into_raw();
         wasm.__wbg_engine_free(ptr, 0);
     }
+    /**
+     * 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.
+     * @param {string} name
+     * @returns {Promise<any>}
+     */
+    fetch(name) {
+        const ptr0 = passStringToWasm0(name, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmengine_fetch(this.__wbg_ptr, ptr0, len0);
+        return takeObject(ret);
+    }
     /**
      * Returns formatted source string on success; throws with error message on failure.
      * @param {string} code
@@ -67,17 +79,7 @@ export class Engine {
         }
     }
     /**
-     * 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.
      * @returns {any}
      */
     list() {
@@ -96,21 +98,54 @@ export class Engine {
         }
     }
     /**
-     * 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`).
-     *
-     * Breaking: previously rejected with an array of strings.
+     * Load Lemma source. Throws with an array of serialized errors
+     * (same shape as `EngineError` in `engine/packages/npm/lemma.d.ts`).
      * @param {string} code
      * @param {string} attribute
-     * @returns {Promise<any>}
      */
     load(code, attribute) {
-        const ptr0 = passStringToWasm0(code, wasm.__wbindgen_export, wasm.__wbindgen_export2);
-        const len0 = WASM_VECTOR_LEN;
-        const ptr1 = passStringToWasm0(attribute, wasm.__wbindgen_export, wasm.__wbindgen_export2);
-        const len1 = WASM_VECTOR_LEN;
-        const ret = wasm.wasmengine_load(this.__wbg_ptr, ptr0, len0, ptr1, len1);
-        return takeObject(ret);
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(code, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            const ptr1 = passStringToWasm0(attribute, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len1 = WASM_VECTOR_LEN;
+            wasm.wasmengine_load(retptr, this.__wbg_ptr, ptr0, len0, ptr1, len1);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            if (r1) {
+                throw takeObject(r0);
+            }
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+    /**
+     * Load multiple Lemma sources in one planning pass (same as [`Engine::load_batch`]).
+     *
+     * `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.
+     * @param {any} sources
+     * @param {string | null} [dependency]
+     */
+    load_batch(sources, dependency) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            var ptr0 = isLikeNone(dependency) ? 0 : passStringToWasm0(dependency, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            var len0 = WASM_VECTOR_LEN;
+            wasm.wasmengine_load_batch(retptr, this.__wbg_ptr, addHeapObject(sources), ptr0, len0);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            if (r1) {
+                throw takeObject(r0);
+            }
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
     }
     constructor() {
         const ret = wasm.wasmengine_new();
@@ -118,22 +153,47 @@ export class Engine {
         EngineFinalization.register(this, this.__wbg_ptr, this);
         return this;
     }
+    /**
+     * Loaded repositories (workspace and dependencies): `{ name, dependency }`.
+     * @returns {any}
+     */
+    repositories() {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.wasmengine_repositories(retptr, this.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            return takeObject(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * 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`).
+     * @param {string | null | undefined} repository
      * @param {string} spec
      * @param {any} rule_names
      * @param {any} data_values
      * @param {string | null} [effective]
      * @returns {any}
      */
-    run(spec, rule_names, data_values, effective) {
+    run(repository, spec, rule_names, data_values, effective) {
         try {
             const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-            const ptr0 = passStringToWasm0(spec, wasm.__wbindgen_export, wasm.__wbindgen_export2);
-            const len0 = WASM_VECTOR_LEN;
-            var ptr1 = isLikeNone(effective) ? 0 : passStringToWasm0(effective, wasm.__wbindgen_export, wasm.__wbindgen_export2);
-            var len1 = WASM_VECTOR_LEN;
-            wasm.wasmengine_run(retptr, this.__wbg_ptr, ptr0, len0, addHeapObject(rule_names), addHeapObject(data_values), ptr1, len1);
+            var ptr0 = isLikeNone(repository) ? 0 : passStringToWasm0(repository, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            var len0 = WASM_VECTOR_LEN;
+            const ptr1 = passStringToWasm0(spec, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            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), ptr2, len2);
             var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
             var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
             var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
@@ -147,18 +207,23 @@ export class Engine {
     }
     /**
      * Planning schema for the spec ([`crate::planning::execution_plan::SpecSchema`]). Throws on error.
+     *
+     * `repository`: qualifier string or `null`/empty for workspace ([`Engine::schema`]).
+     * @param {string | null | undefined} repository
      * @param {string} spec
      * @param {string | null} [effective]
      * @returns {any}
      */
-    schema(spec, effective) {
+    schema(repository, spec, effective) {
         try {
             const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-            const ptr0 = passStringToWasm0(spec, wasm.__wbindgen_export, wasm.__wbindgen_export2);
-            const len0 = WASM_VECTOR_LEN;
-            var ptr1 = isLikeNone(effective) ? 0 : passStringToWasm0(effective, wasm.__wbindgen_export, wasm.__wbindgen_export2);
-            var len1 = WASM_VECTOR_LEN;
-            wasm.wasmengine_schema(retptr, this.__wbg_ptr, ptr0, len0, ptr1, len1);
+            var ptr0 = isLikeNone(repository) ? 0 : passStringToWasm0(repository, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            var len0 = WASM_VECTOR_LEN;
+            const ptr1 = passStringToWasm0(spec, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            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_schema(retptr, this.__wbg_ptr, ptr0, len0, ptr1, len1, ptr2, len2);
             var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
             var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
             var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
@@ -618,7 +683,7 @@ function __wbg_get_imports() {
                     const a = state0.a;
                     state0.a = 0;
                     try {
-                        return __wasm_bindgen_func_elem_10704(a, state0.b, arg0, arg1);
+                        return __wasm_bindgen_func_elem_10848(a, state0.b, arg0, arg1);
                     } finally {
                         state0.a = a;
                     }
@@ -777,13 +842,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: 1306, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_10686);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 1343, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_10830);
             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_2761);
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_2759);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000003: function(arg0) {
@@ -820,10 +885,10 @@ function __wbg_get_imports() {
     };
 }
 
-function __wasm_bindgen_func_elem_10686(arg0, arg1, arg2) {
+function __wasm_bindgen_func_elem_10830(arg0, arg1, arg2) {
     try {
         const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-        wasm.__wasm_bindgen_func_elem_10686(retptr, arg0, arg1, addHeapObject(arg2));
+        wasm.__wasm_bindgen_func_elem_10830(retptr, arg0, arg1, addHeapObject(arg2));
         var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
         var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
         if (r1) {
@@ -834,10 +899,10 @@ function __wasm_bindgen_func_elem_10686(arg0, arg1, arg2) {
     }
 }
 
-function __wasm_bindgen_func_elem_2761(arg0, arg1, arg2) {
+function __wasm_bindgen_func_elem_2759(arg0, arg1, arg2) {
     try {
         const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-        wasm.__wasm_bindgen_func_elem_2761(retptr, arg0, arg1, addHeapObject(arg2));
+        wasm.__wasm_bindgen_func_elem_2759(retptr, arg0, arg1, addHeapObject(arg2));
         var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
         var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
         if (r1) {
@@ -848,8 +913,8 @@ function __wasm_bindgen_func_elem_2761(arg0, arg1, arg2) {
     }
 }
 
-function __wasm_bindgen_func_elem_10704(arg0, arg1, arg2, arg3) {
-    wasm.__wasm_bindgen_func_elem_10704(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
+function __wasm_bindgen_func_elem_10848(arg0, arg1, arg2, arg3) {
+    wasm.__wasm_bindgen_func_elem_10848(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
 }
 
 

package/lemma.d.ts

@@ -3,6 +3,59 @@ export { Engine, initSync } from './lemma.bindings.js';
 export declare function init(): Promise<void>;
 export declare function Lemma(): Promise<Engine>;
 
+/** Resolved shape of {@link Engine.fetch}. */
+export interface RegistryFetchResult {
+  source: string;
+  id: string;
+}
+
+declare module './lemma.bindings.js' {
+  interface Engine {
+    /**
+     * Load multiple Lemma sources in one planning pass. Object keys become error-reporting
+     * paths (`SourceType::Path`); use `""` for volatile/inline. Non-empty `dependency` tags
+     * the batch as that dependency id. Throws `EngineError[]` on failure.
+     */
+    load_batch(
+      sources: Record<string, string>,
+      dependency?: string | null,
+    ): void;
+
+    /**
+     * Download Lemma source from the registry for `name` (e.g. `@org/pkg`). Resolves with
+     * `{ source, id }`; does not load the engine. Rejects with `EngineError[]` like `load`.
+     */
+    fetch(name: string): Promise<RegistryFetchResult>;
+
+    /**
+     * JSON serialization of `Vec<ResolvedRepository>` from [`Engine::list`]:
+     * each item has `repository` ([`LemmaRepository`]) and `specs` (`LemmaSpecSet[]`),
+     * each set has `repository`, `name`, and `specs` (`LemmaSpec[]`).
+     */
+    list(): ResolvedRepositoryJson[];
+
+    /**
+     * `repository`: qualifier or `null`/omit for workspace — same as `Engine::schema` `repo`.
+     */
+    schema(
+      repository: string | null | undefined,
+      spec: string,
+      effective?: string | null,
+    ): SpecSchema;
+
+    /**
+     * `repository`: qualifier or `null`/omit for workspace — same as `Engine::run` `repo`.
+     */
+    run(
+      repository: string | null | undefined,
+      spec: string,
+      rule_names: string[] | string,
+      data_values: Record<string, unknown>,
+      effective?: string | null,
+    ): any;
+  }
+}
+
 /**
  * Source location attached to an {@link EngineError}. Line and column are
  * 1-based; `length` is the UTF-8 byte length of the offending span.
@@ -16,11 +69,12 @@ export interface EngineErrorSource {
 
 /**
  * Structured error thrown by {@link Engine.run}, {@link Engine.schema},
- * {@link Engine.format}, and rejected from {@link Engine.load} (as an array).
+ * {@link Engine.format}, {@link Engine.load}, and {@link Engine.load_batch}
+ * (as an array), and rejected from {@link Engine.fetch} (as an array).
  *
  * - `kind` classifies the failure ("parsing" for syntax, "validation" for
- *   semantic/planning including bad data values, "request" for bad API input,
- *   etc.).
+ *   semantic/planning including bad data values, "missing_repository" when a
+ *   referenced repo is not loaded, "request" for bad API input, etc.).
  * - `message` is the inner reason only. Callers that previously parsed
  *   `"Failed to parse data 'X' as Y: ..."` strings should now use `related_data`
  *   for attribution and `message` for the reason.
@@ -29,17 +83,26 @@ export interface EngineErrorSource {
  * - `source` points at the offending range in the original Lemma source.
  */
 export interface EngineError {
-  kind: "parsing" | "validation" | "inversion" | "registry" | "request" | "resource_limit";
+  kind:
+    | "parsing"
+    | "validation"
+    | "inversion"
+    | "registry"
+    | "missing_repository"
+    | "request"
+    | "resource_limit";
   message: string;
   related_data: string | null;
   spec: string | null;
   related_spec: string | null;
   source: EngineErrorSource | null;
   suggestion: string | null;
+  /** Present for `missing_repository` and `registry` errors (`@…` id). */
+  repository: string | null;
 }
 
 // ---------------------------------------------------------------------------
-// Schema envelope (return shape of Engine.schema and Engine.list entries)
+// Schema envelope (return shape of Engine.schema)
 // ---------------------------------------------------------------------------
 
 /** Literal value produced by `JSON.stringify` on a Lemma `LiteralValue`. */
@@ -103,9 +166,12 @@ export type LemmaType =
     | { kind: "veto"; message: string | null }
   );
 
-/** One input on a spec. `default` is omitted (not `null`) when absent. */
+/** One input declared in a spec. Omitted fields are absent (not `null`). */
 export interface DataEntry {
   type: LemmaType;
+  /** Literal bound in the source (`data x: literal`). */
+  bound_value?: LiteralValue;
+  /** `-> default ...` suggestion; omitted from `bound_value` until evaluation applies it. */
   default?: LiteralValue;
 }
 
@@ -117,11 +183,60 @@ export interface SpecSchema {
   meta: Record<string, unknown>;
 }
 
-/** One row of {@link Engine.list}. The schema is always inlined so callers
- *  never need a second `engine.schema(name, effective_from)` round-trip. */
-export interface SpecListEntry {
+/** JSON mirror of Rust `ResolvedRepository` (engine `list`). */
+export interface ResolvedRepositoryJson {
+  repository: LemmaRepositoryJson;
+  /** [`LemmaSpecSet`] list for this resolved repository. */
+  specs: LemmaSpecSetJson[];
+}
+
+/** JSON mirror of Rust `LemmaSpecSet` as serialized by the engine. */
+export interface LemmaSpecSetJson {
+  repository: LemmaRepositoryJson;
   name: string;
-  effective_from: string | null;
-  effective_to: string | null;
-  schema: SpecSchema;
+  /** Temporal versions, ascending `effective_from` (same order as `iter_specs`). */
+  specs: LemmaSpecJson[];
+}
+
+/** JSON mirror of Rust `LemmaRepository`. */
+export interface LemmaRepositoryJson {
+  name: string | null;
+  dependency: string | null;
+  start_line: number;
+  source_type: unknown;
+}
+
+/** JSON mirror of Rust `EffectiveDate` (externally tagged). */
+export type EffectiveDateJson =
+  | { Origin: null }
+  | { DateTimeValue: DateTimeValueJson };
+
+/** JSON mirror of Rust `DateTimeValue`. */
+export interface DateTimeValueJson {
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  second: number;
+  microsecond: number;
+  timezone: unknown;
+}
+
+/** JSON mirror of Rust `LemmaSpec` (full AST; deep nodes are engine-shaped). */
+export interface LemmaSpecJson {
+  name: string;
+  effective_from: EffectiveDateJson;
+  source_type: unknown;
+  start_line: number;
+  commentary: string | null;
+  data: unknown[];
+  rules: unknown[];
+  meta_fields: unknown[];
+}
+
+/** One entry of {@link Engine.repositories}. */
+export interface RepositoryEntry {
+  name: string | null;
+  dependency: string | null;
 }