@lemmabase/lemma-engine 0.9.8 → 0.9.10

package/lemma.d.ts

@@ -3,8 +3,8 @@ 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 {
+/** Resolved shape of {@link Engine.install}. */
+export interface RepositoryInstallResult {
   source: string;
   id: string;
 }
@@ -13,12 +13,14 @@ declare module './lemma.bindings.js' {
   namespace Engine {
     /** Create engine with named limit overrides. Unknown keys throw. */
     function withLimits(limits: Record<string, number>): Engine;
+    /** Restore an engine from {@link Engine.snapshot} bytes. */
+    function fromSnapshot(bytes: Uint8Array): Engine;
   }
 
   interface Engine {
     /**
      * Load Lemma source(s).
-     * - string → volatile workspace source
+     * - string → volatile source in the default repository
      * - object → labeled sources (key insertion order); `[label, code][]` → labeled sources (array order)
      * Throws `EngineError[]` on failure. `null`/`undefined` rejected.
      */
@@ -26,14 +28,15 @@ declare module './lemma.bindings.js' {
     load(sources: Record<string, string> | Array<[string, string]>): 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`.
+     * Download Lemma source from LemmaBase for `name` (e.g. `@org/pkg`). Resolves with
+     * `{ source, id }`; does not load the engine and does not write `lemma_deps/`.
+     * Rejects with `EngineError[]` like `load`.
      */
-    fetch(name: string): Promise<RegistryFetchResult>;
+    install(name: string): Promise<RepositoryInstallResult>;
 
     /**
      * JSON serialization of `Vec<ResolvedRepository>` from [`Engine::list`]:
-     * each item has `repository` (name or null for workspace) and `specs`
+     * each item has `repository` (name, or omitted for the default repository) and `specs`
      * (`ListedSpec` rows: name, effective_from, effective_to).
      */
     list(): ResolvedRepository[];
@@ -66,13 +69,11 @@ declare module './lemma.bindings.js' {
     ): void;
 
     /**
-     * Replace a temporal spec slice with new source (atomic remove + load).
+     * Replace identities in `code` (atomic upsert; Path/Dependency prune siblings).
      * `attribute` is the source label (path or `@owner/repo`); omit for volatile.
      */
     update(
       repository: string | null | undefined,
-      spec: string,
-      effective: string | null | undefined,
       code: string,
       attribute?: string | null,
     ): void;
@@ -80,6 +81,12 @@ declare module './lemma.bindings.js' {
     /** Resource limits configured for this engine. */
     limits(): ResourceLimits;
 
+    /**
+     * Persist parsed specs + plans + limits as opaque bytes.
+     * Restore with {@link Engine.fromSnapshot}.
+     */
+    snapshot(): Uint8Array;
+
     /**
      * Canonical formatting of Lemma source. Throws `EngineError` on parse error.
      * `attribute` is an optional path label used in error messages.
@@ -102,7 +109,7 @@ declare module './lemma.bindings.js' {
 export interface RunOptions {
   /** Spec name (required). */
   spec: string;
-  /** Repository qualifier (e.g. `@org/repo`), or omit for workspace. */
+  /** Repository qualifier (e.g. `@org/repo`), or omit for the default repository. */
   repository?: string | null;
   /** ISO datetime for temporal resolution, or omit for now. */
   effective?: string | null;
@@ -127,8 +134,8 @@ export interface EngineErrorSource {
 
 /**
  * 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).
+ * {@link Engine.load}, and {@link Engine.install}
+ * (as an array), and rejected from {@link Engine.install} (as an array).
  *
  * - `kind` classifies the failure ("parsing" for syntax, "validation" for
  *   semantic/planning including bad data values, "missing_repository" when a
@@ -179,7 +186,7 @@ export interface EngineError {
 
 /**
  * API value fields shared by `RuleResult` (flattened into its top-level fields),
- * `ShowData.prefilled`, `ShowData.suggestion`, and range endpoints.
+ * `ShowData.fill`, `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.
  */
@@ -200,7 +207,7 @@ export interface RuleResultValueEndpoint {
 
 /**
  * API value shared by `RuleResult` (flattened into its top-level fields),
- * `ShowData.prefilled`, and `ShowData.suggestion`. When present: always `display`,
+ * `ShowData.fill`, 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.
@@ -339,10 +346,10 @@ export type LemmaType =
 export interface ShowData {
   type: LemmaType;
   /** Spec literal or literal `with` binding; UIs may skip review. */
-  prefilled?: RuleResultValue;
+  fill?: RuleResultValue;
   /** `-> suggest ...` suggestion; prompt with prefill in interactive UIs. */
   suggestion?: RuleResultValue;
-  /** Local rule names that transitively need this data (planning time). */
+  /** Local rule names that transitively need this data after normalize. Empty = reuse catalog only. */
   needed_by_rules: string[];
 }
 
@@ -365,7 +372,7 @@ export type RuleResult = RuleResultValue & {
   vetoed: boolean;
   veto_reason?: string;
   rule_type: string;
-  /** Input keys still unbound for this rule (run-data-aware; same keys as Show.data). */
+  /** Input keys still unbound for this rule (run-data-aware; subset of Show.data with non-empty needed_by_rules). */
   missing_data?: string[];
   /** Present when `run(..., explain: true)`. Shape: engine/schemas/api.v1.json (`RuleResult.explanation`). */
   explanation?: Explanation;
@@ -438,7 +445,7 @@ export interface ShowVersion {
  *  is the bare string `"volatile"`. */
 export type SourceType = "volatile" | { path: string } | { dependency: string };
 
-/** Parsed literal value (meta field value). Externally tagged. */
+/** Parsed literal value. Externally tagged. */
 export type LiteralValue =
   | { number: string }
   | { number_with_unit: [string, string] }
@@ -448,8 +455,111 @@ export type LiteralValue =
   | { boolean: "true" | "false" | "yes" | "no" }
   | { range: [LiteralValue, LiteralValue] };
 
-/** Spec `meta` field value. Externally tagged. */
-export type MetaValue = { literal: LiteralValue } | { unquoted: string };
+/** Conversion target on a Show `as` expression. */
+export type ShowConversionTarget =
+  | {
+      type:
+        | "boolean"
+        | "measure"
+        | "measure_range"
+        | "number"
+        | "number_range"
+        | "ratio"
+        | "ratio_range"
+        | "text"
+        | "date"
+        | "date_range"
+        | "time"
+        | "time_range";
+    }
+  | { unit: { unit_name: string } };
+
+/** Resolved expression on a Show rule branch (tagged by `type`). */
+export type ShowExpression =
+  | ({ type: "literal" } & RuleResultValue)
+  | { type: "data"; name: string }
+  | { type: "rule"; name: string }
+  | { type: "and"; left: ShowExpression; right: ShowExpression }
+  | { type: "not"; operand: ShowExpression }
+  | {
+      type: "arithmetic";
+      op: "add" | "subtract" | "multiply" | "divide" | "modulo" | "power";
+      left: ShowExpression;
+      right: ShowExpression;
+    }
+  | {
+      type: "comparison";
+      op:
+        | "greater_than"
+        | "less_than"
+        | "greater_than_or_equal"
+        | "less_than_or_equal"
+        | "is"
+        | "is_not";
+      left: ShowExpression;
+      right: ShowExpression;
+    }
+  | {
+      type: "unit_conversion";
+      operand: ShowExpression;
+      target: ShowConversionTarget;
+    }
+  | {
+      type: "math";
+      op:
+        | "sqrt"
+        | "sin"
+        | "cos"
+        | "tan"
+        | "asin"
+        | "acos"
+        | "atan"
+        | "log"
+        | "exp"
+        | "abs"
+        | "floor"
+        | "ceil"
+        | "round";
+      operand: ShowExpression;
+    }
+  | { type: "veto"; message?: string }
+  | { type: "now" }
+  | {
+      type: "date_relative";
+      kind: "in_past" | "in_future";
+      operand: ShowExpression;
+    }
+  | {
+      type: "date_calendar";
+      kind: "current" | "past" | "future" | "not_in";
+      unit: "year" | "month" | "week";
+      operand: ShowExpression;
+    }
+  | { type: "range_literal"; from: ShowExpression; to: ShowExpression }
+  | {
+      type: "past_future_range";
+      kind: "in_past" | "in_future";
+      operand: ShowExpression;
+    }
+  | {
+      type: "range_containment";
+      value: ShowExpression;
+      range: ShowExpression;
+    }
+  | { type: "is_veto"; operand: ShowExpression };
+
+/** One arm of a rule's flat last-match table. Default arm omits condition. */
+export interface ShowBranch {
+  condition?: ShowExpression;
+  result: ShowExpression;
+}
+
+/** Local rule on Show: result type, branches, stored depends_on_rules. */
+export interface ShowRule {
+  type: LemmaType;
+  branches: ShowBranch[];
+  depends_on_rules: string[];
+}
 
 /** Return shape of {@link Engine.show}. */
 export interface Show {
@@ -461,9 +571,9 @@ export interface Show {
   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, MetaValue>;
+  /** Local rule graph; measure/ratio units live under `type.units`. */
+  rules: Record<string, ShowRule>;
+  meta: Record<string, LiteralValue>;
 }
 
 /** Slim listed spec row (engine `list`). */
@@ -475,7 +585,7 @@ export interface ListedSpec {
 
 /** Rust `ResolvedRepository` (engine `list`). */
 export interface ResolvedRepository {
-  /** Absent for the local workspace group (only real repositories carry a name). */
+  /** Absent for the default unnamed repository (only named repositories carry a name). */
   repository?: string;
   specs: ListedSpec[];
 }