@lemmabase/lemma-engine 0.8.21 → 0.9.0

package/lemma.d.ts

@@ -12,14 +12,13 @@ export interface RegistryFetchResult {
 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 Lemma source(s).
+     * - string → volatile workspace source
+     * - object or `[label, code][]` → labeled sources in one planning pass
+     * Throws `EngineError[]` on failure. `null`/`undefined` rejected.
      */
-    load_batch(
-      sources: Record<string, string>,
-      dependency?: string | null,
-    ): void;
+    load(code: string): void;
+    load(sources: Record<string, string> | Array<[string, string]>): void;
 
     /**
      * Download Lemma source from the registry for `name` (e.g. `@org/pkg`). Resolves with
@@ -29,38 +28,56 @@ declare module './lemma.bindings.js' {
 
     /**
      * JSON serialization of `Vec<ResolvedRepository>` from [`Engine::list`]:
-     * each item has `repository` ([`LemmaRepository`]) and `specs` (`LemmaSpecSet[]`),
-     * each set has `repository`, `name`, and `specs` (`LemmaSpec[]`).
+     * each item has `repository` (name or null for workspace) and `specs`
+     * (`ListedSpec` rows: name, effective_from, effective_to).
      */
     list(): ResolvedRepositoryJson[];
 
     /**
-     * Formatted Lemma source for a loaded repository (from in-engine AST). Use `"lemma"` for embedded units stdlib.
+     * Spec interface and temporal window at `effective`. Lemma text is {@link Engine.source}.
+     */
+    show(
+      repository: string | null | undefined,
+      spec: string,
+      effective?: string | null,
+    ): Show;
+
+    /**
+     * Formatted canonical Lemma source. Omit `spec` for whole-repository text.
      */
-    format_repository(repository: string): string;
+    source(
+      repository: string | null | undefined,
+      spec?: string | null,
+      effective?: string | null,
+    ): string;
 
     /**
-     * `repository`: qualifier or `null`/omit for workspace — same as `Engine::schema` `repo`.
+     * Remove a temporal spec slice. `effective`: ISO datetime or omit for now.
      */
-    schema(
+    remove(
       repository: string | null | undefined,
       spec: string,
       effective?: string | null,
-    ): SpecSchema;
+    ): void;
+
+    /** Resource limits configured for this engine. */
+    limits(): ResourceLimitsJson;
 
     /**
-     * `repository`: qualifier or `null`/omit for workspace — same as `Engine::run` `repo`.
-     *
-     * `data_values`: pass integers as numbers, decimals as strings (e.g.
-     * `{ quantity: 42, rate: "0.075" }`). Non-integer numbers are rejected
-     * to prevent silent precision loss from IEEE 754 doubles.
+     * Canonical formatting of Lemma source. Throws `EngineError` on parse error.
+     * `attribute` is an optional path label used in error messages.
+     */
+    format(code: string, attribute?: string | null): string;
+
+    /**
+     * `data_values`: pass integers as numbers, decimals as strings.
      */
     run(
       repository: string | null | undefined,
       spec: string,
-      rule_names: string[] | string,
-      data_values: Record<string, unknown>,
-      effective?: string | null,
+      effective: string | null | undefined,
+      data_values?: Record<string, unknown>,
+      rule_names?: string[] | string | null,
       explain?: boolean,
     ): EvaluationResponse;
   }
@@ -78,8 +95,8 @@ export interface EngineErrorSource {
 }
 
 /**
- * Structured error thrown by {@link Engine.run}, {@link Engine.schema},
- * {@link Engine.format}, {@link Engine.load}, and {@link Engine.load_batch}
+ * Structured error thrown by {@link Engine.run}, {@link Engine.show},
+ * {@link Engine.load}, and {@link Engine.fetch}
  * (as an array), and rejected from {@link Engine.fetch} (as an array).
  *
  * - `kind` classifies the failure ("parsing" for syntax, "validation" for
@@ -112,13 +129,20 @@ export interface EngineError {
 }
 
 // ---------------------------------------------------------------------------
-// Schema envelope (return shape of Engine.schema)
+// Show envelope (return shape of Engine.show)
 // ---------------------------------------------------------------------------
 
-/** Literal value produced by `JSON.stringify` on a Lemma `LiteralValue`. */
-export type LiteralValue = unknown;
+/** Literal value on API wire (`suggestion`, `prefilled`, committed `value`). Canonical plan storage omits `measure` / `ratio` maps. */
+export interface WireLiteralValue {
+  value: unknown;
+  lemma_type: LemmaType;
+  display_value: string;
+  /** All declared measure units when the type has unit definitions. */
+  measure?: Record<string, string>;
+  /** All declared ratio units when the type has unit definitions. */
+  ratio?: Record<string, string>;
+}
 
-/** Extension classification serialized on every {@link LemmaType}. */
 export type TypeExtends =
   | "primitive"
   | {
@@ -132,7 +156,7 @@ export interface UnitDef {
   factor: { numer: string; denom: string };
   minimum?: string | null;
   maximum?: string | null;
-  default?: string | null;
+  suggestion?: string | null;
 }
 
 export interface RatioUnitDef {
@@ -140,7 +164,7 @@ export interface RatioUnitDef {
   value: { numer: string; denom: string };
   minimum?: string | null;
   maximum?: string | null;
-  default?: string | null;
+  suggestion?: string | null;
 }
 
 /** Discriminated union over the 10 Lemma type kinds. Field `kind` is the
@@ -205,10 +229,12 @@ export type LemmaType =
 /** 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;
+  /** Spec literal or literal `with` binding; UIs may skip review. */
+  prefilled?: WireLiteralValue;
+  /** `-> suggest ...` suggestion; prompt with prefill in interactive UIs. */
+  suggestion?: WireLiteralValue;
+  /** Local rule names that transitively need this data (planning time). */
+  needed_by_rules: string[];
 }
 
 /** Return shape of {@link Engine.run}. */
@@ -216,7 +242,6 @@ export interface EvaluationResponse {
   spec: string;
   effective: string;
   results: Record<string, RuleResult>;
-  data: EvaluationDataEntry[];
 }
 
 export interface RuleResult {
@@ -224,6 +249,8 @@ export interface RuleResult {
   display?: string | null;
   veto_reason?: string | null;
   rule_type: string;
+  /** Input keys still unbound for this rule (overlay-aware; same keys as Show.data). */
+  missing_data?: string[];
   measure?: Record<string, string> | null;
   ratio?: Record<string, string> | null;
   number?: string | null;
@@ -233,7 +260,69 @@ export interface RuleResult {
   time?: unknown | null;
   calendar?: { value: string; unit: string } | null;
   range?: { from: RuleResultPayload; to: RuleResultPayload } | null;
-  explanation?: unknown | null;
+  /** Present when `run(..., explain: true)`. Shape: documentation/schemas/explanation.v1.json */
+  explanation?: Explanation | null;
+}
+
+/** One evaluated unless condition, stated as a fact. */
+export interface ExplanationCause {
+  condition: string;
+  value: string;
+  children?: ExplanationNode[];
+}
+
+export interface ExplanationConversionStep {
+  role: "outcome" | "rule" | "source";
+  text: string;
+}
+
+/** Nested explanation tree node (tagged by `type`). */
+export type ExplanationNode =
+  | {
+      type: "rule";
+      name: string;
+      result: string;
+      body: string;
+      causes?: ExplanationCause[];
+      children?: ExplanationNode[];
+    }
+  | {
+      type: "compose";
+      expression: string;
+      operands: ExplanationNode[];
+    }
+  | {
+      type: "data";
+      name: string;
+      display: string;
+    }
+  | {
+      type: "data_unused";
+      name: string;
+    }
+  | {
+      type: "conversion";
+      expression: string;
+      steps: ExplanationConversionStep[];
+      operands: ExplanationNode[];
+    }
+  | {
+      type: "veto";
+      message?: string;
+    }
+  | {
+      type: "unit_equivalence";
+      text: string;
+    };
+
+/** Root and nested rule explanation (same shape). */
+export interface Explanation {
+  type: "rule";
+  name: string;
+  result: string;
+  body: string;
+  causes?: ExplanationCause[];
+  children?: ExplanationNode[];
 }
 
 export interface RuleResultPayload {
@@ -247,48 +336,40 @@ export interface RuleResultPayload {
   calendar?: { value: string; unit: string } | null;
 }
 
-export interface EvaluationDataEntry {
-  path: string;
-  value: unknown;
+/** Half-open `[effective_from, effective_to)` for one loaded temporal row. */
+export interface ShowVersion {
+  effective_from?: string | null;
+  effective_to?: string | null;
 }
 
-/** Return shape of {@link Engine.schema}. */
-export interface SpecSchema {
+/** Return shape of {@link Engine.show}. */
+export interface Show {
   spec: string;
+  commentary?: string | null;
+  effective_from?: string | null;
+  effective_to?: string | null;
+  start_line: number;
+  source_type?: string | null;
+  versions?: ShowVersion[];
   data: Record<string, DataEntry>;
   /** Rule result types; measure and ratio entries expose `units[]` like their data counterparts. */
   rules: Record<string, LemmaType>;
   meta: Record<string, unknown>;
 }
 
-/** 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;
+/** JSON mirror of slim listed spec row (engine `list`). */
+export interface ListedSpecJson {
   name: string;
-  /** Temporal versions, ascending `effective_from` (same order as `iter_specs`). */
-  specs: LemmaSpecJson[];
+  effective_from?: DateTimeValueJson | null;
+  effective_to?: DateTimeValueJson | null;
 }
 
-/** JSON mirror of Rust `LemmaRepository`. */
-export interface LemmaRepositoryJson {
-  name: string | null;
-  dependency: string | null;
-  start_line: number;
-  source_type: unknown;
+/** JSON mirror of Rust `ResolvedRepository` (engine `list`). */
+export interface ResolvedRepositoryJson {
+  repository: string | null;
+  specs: ListedSpecJson[];
 }
 
-/** JSON mirror of Rust `EffectiveDate` (externally tagged). */
-export type EffectiveDateJson =
-  | { Origin: null }
-  | { DateTimeValue: DateTimeValueJson };
-
 /** JSON mirror of Rust `DateTimeValue`. */
 export interface DateTimeValueJson {
   year: number;
@@ -301,14 +382,16 @@ export interface DateTimeValueJson {
   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[];
+/** JSON mirror of Rust `ResourceLimits`. */
+export interface ResourceLimitsJson {
+  max_source_size_bytes: number;
+  max_expression_depth: number;
+  max_expression_count: number;
+  max_data_value_bytes: number;
+  max_loaded_bytes: number;
+  max_sources: number;
+  max_normalized_expression_nodes: number;
+  max_spec_dependency_depth: number;
+  max_dag_specs: number;
+  max_normal_form_depth: number;
 }