@lemmabase/lemma-engine 0.8.22 → 0.9.1

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 → labeled sources (key insertion order); `[label, code][]` → labeled sources (array order)
+     * 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,43 +28,70 @@ 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[];
+    list(): ResolvedRepository[];
 
     /**
-     * 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}.
      */
-    format_repository(repository: string): string;
+    show(
+      repository: string | null | undefined,
+      spec: string,
+      effective?: string | null,
+    ): Show;
 
     /**
-     * `repository`: qualifier or `null`/omit for workspace — same as `Engine::schema` `repo`.
+     * Formatted canonical Lemma source. Omit `spec` for whole-repository text.
      */
-    schema(
+    source(
       repository: string | null | undefined,
-      spec: string,
+      spec?: string | null,
       effective?: string | null,
-    ): SpecSchema;
+    ): string;
 
     /**
-     * `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.
+     * Remove a temporal spec slice. `effective`: ISO datetime or omit for now.
      */
-    run(
+    remove(
       repository: string | null | undefined,
       spec: string,
-      rule_names: string[] | string,
-      data_values: Record<string, unknown>,
       effective?: string | null,
-      explain?: boolean,
-    ): EvaluationResponse;
+    ): void;
+
+    /** Resource limits configured for this engine. */
+    limits(): ResourceLimits;
+
+    /**
+     * 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;
+
+    /**
+     * Evaluate a spec. Pass integers as numbers, decimals as strings in `data`.
+     */
+    run(options: RunOptions): Response;
   }
 }
 
+/** Options for {@link Engine.run}. */
+export interface RunOptions {
+  /** Spec name (required). */
+  spec: string;
+  /** Repository qualifier (e.g. `@org/repo`), or omit for workspace. */
+  repository?: string | null;
+  /** ISO datetime for temporal resolution, or omit for now. */
+  effective?: string | null;
+  /** Input data values. Pass integers as numbers, decimals as strings. */
+  data?: Record<string, unknown>;
+  /** Rule names to evaluate, or omit for all rules. */
+  rules?: string[] | string | null;
+  /** Include explanation tree in response. */
+  explain?: boolean;
+}
+
 /**
  * Source location attached to an {@link EngineError}. Line and column are
  * 1-based; `length` is the UTF-8 byte length of the offending span.
@@ -78,8 +104,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
@@ -109,68 +135,129 @@ export interface EngineError {
   suggestion: string | null;
   /** Present for `missing_repository` and `registry` errors (`@…` id). */
   repository: string | null;
+  /** Present only for `kind: "registry"`. */
+  registry_kind:
+    | "not_found"
+    | "unauthorized"
+    | "network_error"
+    | "server_error"
+    | "other"
+    | null;
+  /** Present only for `kind: "request"`. */
+  request_kind: "spec_not_found" | "rule_not_found" | "invalid_request" | null;
+  /** Present only for `kind: "resource_limit"`. */
+  limit_name: string | null;
+  limit_value: string | null;
+  actual_value: string | null;
 }
 
 // ---------------------------------------------------------------------------
-// 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;
+/**
+ * API value fields shared by `RuleResult` (flattened into its top-level fields),
+ * `ShowData.prefilled`, `ShowData.suggestion`, and range endpoints.
+ * A `None` field is absent (not `null`) per Rust `skip_serializing_if`.
+ * When present: always `display`, plus exactly one typed field.
+ */
+export interface RuleResultValueEndpoint {
+  /** Engine-rendered string (`LiteralValue::display_value`). */
+  display?: string;
+  /** All declared measure units, keyed by unit name. */
+  measure?: Record<string, string>;
+  /** All declared ratio units, keyed by unit name. */
+  ratio?: Record<string, string>;
+  number?: string;
+  boolean?: boolean;
+  text?: string;
+  date?: string;
+  time?: string;
+  calendar?: { value: string; unit: string };
+}
+
+/**
+ * API value shared by `RuleResult` (flattened into its top-level fields),
+ * `ShowData.prefilled`, and `ShowData.suggestion`. When present: always `display`,
+ * plus exactly one typed field for a non-range value; `range` is set instead for a
+ * range value. A range endpoint (`range.from`/`range.to`) never itself carries a
+ * `range` field.
+ */
+export interface RuleResultValue extends RuleResultValueEndpoint {
+  range?: { from: RuleResultValueEndpoint; to: RuleResultValueEndpoint };
+}
+
+/** Where a custom type's extension chain is rooted: local to this spec, or imported. */
+export type TypeDefiningSpec = { kind: "local" } | { kind: "import" };
 
-/** Extension classification serialized on every {@link LemmaType}. */
 export type TypeExtends =
-  | "primitive"
+  | { kind: "primitive" }
   | {
+      kind: "custom";
       parent: string;
       family: string;
-      defining_spec: unknown;
+      defining_spec: TypeDefiningSpec;
     };
 
-export interface UnitDef {
+/** A unit-scoped bound (Measure/DateRange/TimeRange/MeasureRange minimum/maximum/lower/upper). */
+export interface NamedBound {
+  value: string;
+  unit: string;
+}
+
+export interface MeasureUnit {
   name: string;
   factor: { numer: string; denom: string };
-  minimum?: string | null;
-  maximum?: string | null;
-  default?: string | null;
+  /** (measure_ref, exponent) pairs from a compound unit declaration (e.g. meter/second). */
+  derived_measure_factors: [string, number][];
+  decomposition: Record<string, number>;
+  minimum?: string;
+  maximum?: string;
+  suggestion?: string;
 }
 
-export interface RatioUnitDef {
+export interface RatioUnit {
   name: string;
   value: { numer: string; denom: string };
-  minimum?: string | null;
-  maximum?: string | null;
-  default?: string | null;
+  minimum?: string;
+  maximum?: string;
+  suggestion?: string;
 }
 
-/** Discriminated union over the 10 Lemma type kinds. Field `kind` is the
- *  serde tag; kind-specific fields sit at the top level next to `kind`,
- *  `name`, and `extends`. */
+/**
+ * Discriminated union over the 12 Lemma type kinds reachable at the API boundary.
+ * Field `kind` is the serde tag; kind-specific fields sit at the top level next to
+ * `kind`, `name`, and `extends`. The `veto`/`undetermined` `TypeSpecification`
+ * variants are internal sentinels that never reach a successfully planned API
+ * response and are intentionally excluded.
+ */
 export type LemmaType =
   & { name: string | null; extends: TypeExtends }
   & (
     | { kind: "boolean"; help: string }
     | {
         kind: "measure";
-        minimum: string | null;
-        maximum: string | null;
+        minimum: NamedBound | null;
+        maximum: NamedBound | null;
         decimals: number | null;
-        units: UnitDef[];
+        units: MeasureUnit[];
+        traits: ("duration" | "calendar")[];
+        decomposition: Record<string, number> | null;
         help: string;
       }
     | {
-        kind: "measure range";
+        kind: "number";
         minimum: string | null;
         maximum: string | null;
         decimals: number | null;
-        units: UnitDef[];
         help: string;
       }
     | {
-        kind: "number";
+        kind: "numberrange";
+        lower: string | null;
+        upper: string | null;
         minimum: string | null;
         maximum: string | null;
-        decimals: number | null;
         help: string;
       }
     | {
@@ -178,139 +265,209 @@ export type LemmaType =
         minimum: string | null;
         maximum: string | null;
         decimals: number | null;
-        units: RatioUnitDef[];
+        units: RatioUnit[];
         help: string;
       }
     | {
-        kind: "ratio range";
+        kind: "ratiorange";
+        lower: string | null;
+        upper: string | null;
         minimum: string | null;
         maximum: string | null;
-        decimals: number | null;
-        units: RatioUnitDef[];
+        units: RatioUnit[];
         help: string;
       }
     | {
         kind: "text";
-        minimum: number | null;
-        maximum: number | null;
         length: number | null;
         options: string[];
         help: string;
       }
     | { kind: "date"; minimum: string | null; maximum: string | null; help: string }
+    | {
+        kind: "daterange";
+        lower: string | null;
+        upper: string | null;
+        minimum: NamedBound | null;
+        maximum: NamedBound | null;
+        help: string;
+      }
     | { kind: "time"; minimum: string | null; maximum: string | null; help: string }
-    | { kind: "veto"; message: string | null }
+    | {
+        kind: "timerange";
+        lower: string | null;
+        upper: string | null;
+        minimum: NamedBound | null;
+        maximum: NamedBound | null;
+        help: string;
+      }
+    | {
+        kind: "measurerange";
+        lower: NamedBound | null;
+        upper: NamedBound | null;
+        minimum: NamedBound | null;
+        maximum: NamedBound | null;
+        units: MeasureUnit[];
+        decomposition: Record<string, number> | null;
+        help: string;
+      }
   );
 
 /** One input declared in a spec. Omitted fields are absent (not `null`). */
-export interface DataEntry {
+export interface ShowData {
   type: LemmaType;
   /** Spec literal or literal `with` binding; UIs may skip review. */
-  prefilled?: LiteralValue;
-  /** Caller overlay when schema was built with supplied values. */
-  supplied?: LiteralValue;
-  /** `-> default ...` suggestion; prompt with prefill in interactive UIs. */
-  default?: LiteralValue;
+  prefilled?: RuleResultValue;
+  /** `-> suggest ...` suggestion; prompt with prefill in interactive UIs. */
+  suggestion?: RuleResultValue;
+  /** Local rule names that transitively need this data (planning time). */
+  needed_by_rules: string[];
 }
 
 /** Return shape of {@link Engine.run}. */
-export interface EvaluationResponse {
+export interface Response {
   spec: string;
   effective: string;
+  /** Declared temporal window of the resolved spec version actually evaluated. */
+  spec_effective_from?: string;
+  spec_effective_to?: string;
   results: Record<string, RuleResult>;
-  data: EvaluationDataEntry[];
 }
 
-export interface RuleResult {
+/**
+ * A rule's result. Fields of `RuleResultValue` are flattened directly onto this
+ * object (the Rust side uses `#[serde(flatten)]`), so a measure result's map appears
+ * at `result.measure`, not nested under a `value` key.
+ */
+export type RuleResult = RuleResultValue & {
   vetoed: boolean;
-  display?: string | null;
-  veto_reason?: string | null;
+  veto_reason?: string;
   rule_type: string;
-  measure?: 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;
+  /** Input keys still unbound for this rule (run-data-aware; same keys as Show.data). */
+  missing_data?: string[];
+  /** Present when `run(..., explain: true)`. Shape: documentation/schemas/api.v1.json (`RuleResult.explanation`). */
+  explanation?: Explanation;
+};
+
+/** One evaluated unless condition, stated as a fact. */
+export interface Cause {
+  condition: string;
+  value: string;
+  children?: ExplanationNode[];
+}
+
+export interface ConversionStep {
+  role: "outcome" | "rule" | "source";
+  text: string;
 }
 
-export interface RuleResultPayload {
-  measure?: 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;
+/** Nested explanation tree node (tagged by `type`). */
+export type ExplanationNode =
+  | {
+      type: "rule";
+      name: string;
+      result: string;
+      body: string;
+      causes?: Cause[];
+      children?: ExplanationNode[];
+    }
+  | {
+      type: "compose";
+      expression: string;
+      operands: ExplanationNode[];
+    }
+  | {
+      type: "data";
+      name: string;
+      display: string;
+    }
+  | {
+      type: "data_unused";
+      name: string;
+    }
+  | {
+      type: "conversion";
+      expression: string;
+      steps: ConversionStep[];
+      operands: ExplanationNode[];
+    }
+  | {
+      type: "veto";
+      message?: string;
+    };
+
+/** Root and nested rule explanation (same shape). */
+export interface Explanation {
+  type: "rule";
+  name: string;
+  result: string;
+  body: string;
+  causes?: Cause[];
+  children?: ExplanationNode[];
 }
 
-export interface EvaluationDataEntry {
-  path: string;
-  value: unknown;
+/** Half-open `[effective_from, effective_to)` for one loaded temporal row. */
+export interface ShowVersion {
+  effective_from?: string;
+  effective_to?: string;
 }
 
-/** Return shape of {@link Engine.schema}. */
-export interface SpecSchema {
+/** Provenance of a loaded source. Externally tagged; the unit `Volatile` variant
+ *  is the bare string `"volatile"`. */
+export type SourceType = "volatile" | { path: string } | { dependency: string };
+
+/** Parsed literal value (meta field value). Externally tagged. */
+export type LiteralValue =
+  | { number: string }
+  | { number_with_unit: [string, string] }
+  | { text: string }
+  | { date: string }
+  | { time: string }
+  | { boolean: "true" | "false" | "yes" | "no" }
+  | { range: [LiteralValue, LiteralValue] };
+
+/** Spec `meta` field value. Externally tagged. */
+export type MetaValue = { literal: LiteralValue } | { unquoted: string };
+
+/** Return shape of {@link Engine.show}. */
+export interface Show {
   spec: string;
-  data: Record<string, DataEntry>;
+  commentary?: string;
+  effective_from?: string;
+  effective_to?: string;
+  start_line: number;
+  source_type?: SourceType;
+  versions?: ShowVersion[];
+  data: Record<string, ShowData>;
   /** 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[];
+  meta: Record<string, MetaValue>;
 }
 
-/** JSON mirror of Rust `LemmaSpecSet` as serialized by the engine. */
-export interface LemmaSpecSetJson {
-  repository: LemmaRepositoryJson;
+/** Slim listed spec row (engine `list`). */
+export interface ListedSpec {
   name: string;
-  /** 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;
+  effective_from?: string;
+  effective_to?: string;
 }
 
-/** 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;
+/** Rust `ResolvedRepository` (engine `list`). */
+export interface ResolvedRepository {
+  /** Absent for the local workspace group (only real repositories carry a name). */
+  repository?: string;
+  specs: ListedSpec[];
 }
 
-/** 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[];
+/** Rust `ResourceLimits`. */
+export interface ResourceLimits {
+  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;
 }