@coldsmirk/abacus-core 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -1,6 +1,5 @@
 import { InitInput } from "@gorules/zen-engine-wasm";
 
-//#region src/engine/intellisense.d.ts
 /**
  * How an expression editor interprets its document:
  *
@@ -37,19 +36,22 @@ type ExpressionType = "Any" | "Null" | "Bool" | "String" | "Number" | "Date" | {
   Object: Record<string, ExpressionType>;
 };
 /**
- * A single syntax / type diagnostic, positioned by character offset.
+ * A single syntax / type diagnostic, positioned by UTF-16 code-unit offset
+ * (the coordinate system of JS strings and CodeMirror documents).
  */
 interface ExpressionDiagnostic {
   /**
-   * Start offset in the source.
+   * Start offset in the source (UTF-16 code units).
    */
   from: number;
   /**
-   * End offset in the source.
+   * End offset in the source (UTF-16 code units).
    */
   to: number;
   /**
-   * Human-readable error message.
+   * Human-readable error message, verbatim from the engine. Any position it
+   * quotes in prose (e.g. `... at (8, 8)`) is the engine's own UTF-8 byte
+   * coordinate — `from` / `to` carry the converted offsets.
    */
   message: string;
   /**
@@ -132,8 +134,6 @@ declare function satisfiesType(actual: ExpressionType, expected: ExpressionType)
  * engine has not loaded yet.
  */
 declare function satisfiesTypeSync(actual: ExpressionType, expected: ExpressionType): boolean;
-//#endregion
-//#region src/engine/errors.d.ts
 /**
  * Error raised when the ZEN engine fails to load or an expression cannot be
  * evaluated. The original failure is preserved on {@link cause} and the
@@ -151,8 +151,6 @@ declare class ExpressionError extends Error {
 declare class ExpressionNotReadyError extends ExpressionError {
   constructor(message?: string);
 }
-//#endregion
-//#region src/engine/loader.d.ts
 /**
  * The data an expression reads from. Property paths in the expression (e.g.
  * `customer.name`) resolve against this object.
@@ -255,13 +253,20 @@ declare function getEngineError(): ExpressionError | null;
 declare function getEngineSync(): ExpressionEngine;
 /**
  * Reset the engine singleton — drops the loaded engine, the cached type context,
- * the latched error, and the configured wasm input. Mainly for tests, but also the
- * way to re-run {@link configureEngine} after a load (configure throws once the
- * engine has started loading).
+ * the latched error, and the configured wasm input, and orphans any in-flight
+ * load: its later settlement is discarded instead of clobbering the new state,
+ * and the next {@link loadEngine} waits for it to settle before initializing
+ * (the upstream wasm initializer tolerates no concurrent calls — see lastLoad).
+ * Mainly for tests, and the way to re-run {@link configureEngine} after a
+ * **failed** load (configure throws once the engine has started loading).
+ *
+ * A different `wasmInput` cannot take effect once the wasm module has
+ * initialized successfully: the ESM module cache keeps the instantiated module
+ * for the lifetime of the JS realm, and its initializer ignores a new input
+ * after success. Reset-and-reconfigure is therefore a retry primitive for load
+ * failures, not a live wasm-swap.
  */
 declare function resetEngine(): void;
-//#endregion
-//#region src/condition/types.d.ts
 /**
  * Structural shapes for the visual condition model compiled to ZEN. They mirror
  * the condition types used in the form and flow editors so a host can map those
@@ -356,18 +361,33 @@ type BranchSelection = {
   matched: false;
   branchId: string | null;
 };
-//#endregion
-//#region src/condition/compile.d.ts
+/**
+ * Whether a finite number compiles into a ZEN literal that behaves identically
+ * to the same JS number supplied in an evaluation context. Two requirements
+ * fold into this: the literal must be inside ZEN's decimal domain (a 96-bit
+ * mantissa scaled by at most 10^-28 — an out-of-domain literal fails to PARSE
+ * and poisons the whole compiled expression), and the engine's own context
+ * conversion of the number must land on the exact same decimal — otherwise
+ * `field == value` compiled from a value silently evaluates false against a
+ * context holding that very value (the engine converts context f64s lossily;
+ * see internal/zen-decimal.ts). Used by {@link toZenLiteral}, by
+ * {@link liftConditionTree} — which must accept exactly the numbers the
+ * compiler can emit — and by UI layers deciding whether a user-entered number
+ * survives compilation.
+ */
+declare function isZenRepresentableNumber(value: number): boolean;
 /**
  * Serialize a JavaScript value into a ZEN literal. Nullish becomes `null`;
  * numbers / booleans / bigints are emitted verbatim; strings are quoted via
  * {@link encodeZenString}; arrays become `[a, b, ...]`.
  *
  * Throws {@link ExpressionError} for a value with no faithful ZEN
- * representation — an object, symbol, or function, or a string containing both
- * quote styles. Callers that need a sentinel instead of a throw go through
- * {@link compileCondition}, which degrades such a value to a non-compiling
- * (null) condition.
+ * representation — an object, symbol, or function, a string containing both
+ * quote styles, a number failing {@link isZenRepresentableNumber} (outside
+ * ZEN's decimal domain, or held differently by the engine's context
+ * conversion), or a bigint outside the decimal domain. Callers that need a
+ * sentinel instead of a throw go through {@link compileCondition}, which
+ * degrades such a value to a non-compiling (null) condition.
  */
 declare function toZenLiteral(value: unknown): string;
 /**
@@ -405,10 +425,8 @@ declare function selectBranchWith(branches: readonly ConditionBranchInput[], con
  * first use. See {@link selectBranchWith} for the selection semantics.
  */
 declare function selectBranch(branches: readonly ConditionBranchInput[], context: ExpressionContext): Promise<BranchSelection>;
-//#endregion
-//#region src/condition/tree-types.d.ts
 /**
- * The visual condition **tree** model: an arbitrarily nested and/or tree of typed
+ * The visual condition **tree** model: a bounded and/or tree of typed
  * comparison rules that {@link compileConditionTree} serializes to a single ZEN
  * boolean expression and {@link liftConditionTree} reconstructs from one. It is a
  * distinct, self-contained shape from the compiler's flat {@link ConditionInput} —
@@ -417,6 +435,11 @@ declare function selectBranch(branches: readonly ConditionBranchInput[], context
  * leaf: a {@link ConditionTreeRule} lowers to a field {@link ConditionInput} so the
  * operator vocabulary, literal encoding, and injection guard have one owner.
  */
+/**
+ * Maximum number of nested group edges below a condition tree's root group.
+ * The root is depth 0, so a group at depth 64 is valid and one at 65 is not.
+ */
+declare const MAX_CONDITION_TREE_DEPTH = 64;
 /**
  * A scalar operand: the value types ZEN compares against and that survive the
  * compile/lift round-trip (strings, numbers, booleans). Objects and null are not
@@ -460,18 +483,40 @@ type ConditionTreeOperator = typeof CONDITION_TREE_OPERATORS[number];
  */
 interface ConditionTreeRule {
   kind: "rule";
+  /**
+   * Stable node identity for list rendering (React keys). Ignored by the
+   * compiler; {@link liftConditionTree} and the builder's creation paths assign
+   * one, and edits carry it through, so a node keeps its identity for as long
+   * as it exists. Optional so hand-built trees for headless compilation need
+   * not supply it.
+   */
+  id?: string;
   left: string;
   operator: ConditionTreeOperator;
   right?: ConditionTreeValue;
+  /**
+   * The element type intended for a membership (`in` / `not_in`) operand while
+   * `right` is an **empty** array — an empty array cannot say whether the tags
+   * to come are numbers, and a builder toggle has to live in the tree for the
+   * component to stay fully controlled (a same-value form reset must also reset
+   * this). Ignored by the compiler, never produced by
+   * {@link liftConditionTree}, and irrelevant once `right` has elements (their
+   * actual type wins).
+   */
+  rightElementType?: "string" | "number";
 }
 /**
  * A boolean group joining its `items` with `op`. Items are leaf rules or nested
- * groups, making the model an arbitrarily deep and/or tree. The root of a lifted
- * condition is always a group, so callers can treat {@link ConditionTreeGroup} as
- * the tree's entry type.
+ * groups, up to {@link MAX_CONDITION_TREE_DEPTH} nested group edges below the root.
+ * The root of a lifted condition is always a group, so callers can treat
+ * {@link ConditionTreeGroup} as the tree's entry type.
  */
 interface ConditionTreeGroup {
   kind: "group";
+  /**
+   * Stable node identity for list rendering — see {@link ConditionTreeRule.id}.
+   */
+  id?: string;
   op: "and" | "or";
   items: readonly ConditionTreeNode[];
 }
@@ -479,25 +524,37 @@ interface ConditionTreeGroup {
  * A node in the condition tree: a nested group or a leaf rule.
  */
 type ConditionTreeNode = ConditionTreeGroup | ConditionTreeRule;
-//#endregion
-//#region src/condition/compile-tree.d.ts
+/**
+ * A fresh {@link ConditionTreeRule.id | node id}, unique within the process —
+ * exactly the guarantee a React key needs. A tagged counter, not a UUID: node
+ * identity is a UI concern with no persistence or cross-process meaning.
+ */
+declare function newConditionNodeId(): string;
+/**
+ * A fresh empty and-group — the canonical "no condition yet" tree, e.g. a
+ * form's initial value for a condition-builder field. It compiles to `""`.
+ */
+declare function emptyConditionGroup(): ConditionTreeGroup;
 /**
  * Compile a condition tree to a canonical ZEN expression, or `""` when no rule in
  * the tree is compilable (see the module note for the drop semantics).
  */
 declare function compileConditionTree(tree: ConditionTreeGroup): string;
-//#endregion
-//#region src/condition/lift-tree.d.ts
 /**
  * Lift a ZEN expression to a condition tree, or `null` when it is not in the
  * canonical form {@link compileConditionTree} produces (the consumer then keeps the
  * raw expression). Groups nested deeper than 64 parenthesized levels are refused as
- * non-canonical rather than risking parser-stack overflow on adversarial input. The
- * returned root is always a group.
+ * non-canonical rather than risking parser-stack overflow on adversarial input, and
+ * number literals must be canonical (see `parseCanonicalNumber`). The returned root
+ * is always a group, and every node carries a fresh {@link ConditionTreeRule.id}.
  */
 declare function liftConditionTree(expression: string): ConditionTreeGroup | null;
-//#endregion
-//#region src/engine/evaluate.d.ts
+/**
+ * Return `tree` with every node carrying a stable UI id. The shared structural
+ * policy is checked before recursive normalization, so invalid external data fails
+ * with an {@link ExpressionError} instead of a native stack overflow.
+ */
+declare function ensureConditionNodeIds(tree: ConditionTreeGroup): ConditionTreeGroup;
 /**
  * Evaluate a standard ZEN expression, loading the engine on first use.
  *
@@ -521,8 +578,6 @@ declare function evaluateSync<T = unknown>(expression: string, context?: Express
  * {@link ExpressionNotReadyError} when the engine has not loaded yet.
  */
 declare function evaluateUnarySync(expression: string, context?: ExpressionContext): boolean;
-//#endregion
-//#region src/engine/messages.d.ts
 /**
  * The locales the library ships with out of the box.
  */
@@ -608,8 +663,6 @@ declare function configureExpressionMessages({
  * The active {@link ExpressionMessages} catalog (English by default).
  */
 declare function getExpressionMessages(): ExpressionMessages;
-//#endregion
-//#region src/engine/template.d.ts
 /**
  * One `{{ expression }}` hole located in a template document. `from` / `to` are
  * the character offsets of the inner expression itself — the text between the
@@ -676,5 +729,4 @@ declare function getTemplateDiagnosticsSync(source: string): ExpressionDiagnosti
  * Async {@link getTemplateDiagnosticsSync}, loading the engine on first use.
  */
 declare function getTemplateDiagnostics(source: string): Promise<ExpressionDiagnostic[]>;
-//#endregion
-export { type BranchSelection, type BuiltInExpressionLocale, CONDITION_OPERATORS, CONDITION_TREE_OPERATORS, type ConditionBranchInput, type ConditionGroupInput, type ConditionInput, type ConditionOperator, type ConditionOperatorArity, type ConditionScalar, type ConditionTreeGroup, type ConditionTreeNode, type ConditionTreeOperator, type ConditionTreeRule, type ConditionTreeValue, type ConfigureMessagesOptions, type ExpressionAnalysis, type ExpressionCompletion, type ExpressionConditionInput, type ExpressionContext, type ExpressionDiagnostic, type ExpressionEngine, ExpressionError, type ExpressionLocale, type ExpressionMessages, type ExpressionMode, ExpressionNotReadyError, type ExpressionType, type ExpressionTypeSpan, type FieldConditionInput, type LoadEngineOptions, type TemplateHole, analyzeTemplate, analyzeTemplateSync, analyzeTypes, analyzeTypesSync, compileBranch, compileCondition, compileConditionTree, compileGroup, conditionOperatorArity, configureEngine, configureExpressionMessages, enMessages, evaluate, evaluateSync, evaluateUnary, evaluateUnarySync, getCompletionItems, getCompletionItemsSync, getDiagnostics, getDiagnosticsSync, getEngineError, getEngineSync, getExpressionMessages, getTemplateDiagnostics, getTemplateDiagnosticsSync, isEngineReady, liftConditionTree, loadEngine, parseTemplateHoles, registerExpressionLocale, resetEngine, satisfiesType, satisfiesTypeSync, selectBranch, selectBranchWith, templateHoleAt, toZenLiteral, zhCNMessages };
+export { type BranchSelection, type BuiltInExpressionLocale, CONDITION_OPERATORS, CONDITION_TREE_OPERATORS, type ConditionBranchInput, type ConditionGroupInput, type ConditionInput, type ConditionOperator, type ConditionOperatorArity, type ConditionScalar, type ConditionTreeGroup, type ConditionTreeNode, type ConditionTreeOperator, type ConditionTreeRule, type ConditionTreeValue, type ConfigureMessagesOptions, type ExpressionAnalysis, type ExpressionCompletion, type ExpressionConditionInput, type ExpressionContext, type ExpressionDiagnostic, type ExpressionEngine, ExpressionError, type ExpressionLocale, type ExpressionMessages, type ExpressionMode, ExpressionNotReadyError, type ExpressionType, type ExpressionTypeSpan, type FieldConditionInput, type LoadEngineOptions, MAX_CONDITION_TREE_DEPTH, type TemplateHole, analyzeTemplate, analyzeTemplateSync, analyzeTypes, analyzeTypesSync, compileBranch, compileCondition, compileConditionTree, compileGroup, conditionOperatorArity, configureEngine, configureExpressionMessages, emptyConditionGroup, enMessages, ensureConditionNodeIds, evaluate, evaluateSync, evaluateUnary, evaluateUnarySync, getCompletionItems, getCompletionItemsSync, getDiagnostics, getDiagnosticsSync, getEngineError, getEngineSync, getExpressionMessages, getTemplateDiagnostics, getTemplateDiagnosticsSync, isEngineReady, isZenRepresentableNumber, liftConditionTree, loadEngine, newConditionNodeId, parseTemplateHoles, registerExpressionLocale, resetEngine, satisfiesType, satisfiesTypeSync, selectBranch, selectBranchWith, templateHoleAt, toZenLiteral, zhCNMessages };

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 import { InitInput } from "@gorules/zen-engine-wasm";
 
-//#region src/engine/intellisense.d.ts
 /**
  * How an expression editor interprets its document:
  *
@@ -37,19 +36,22 @@ type ExpressionType = "Any" | "Null" | "Bool" | "String" | "Number" | "Date" | {
   Object: Record<string, ExpressionType>;
 };
 /**
- * A single syntax / type diagnostic, positioned by character offset.
+ * A single syntax / type diagnostic, positioned by UTF-16 code-unit offset
+ * (the coordinate system of JS strings and CodeMirror documents).
  */
 interface ExpressionDiagnostic {
   /**
-   * Start offset in the source.
+   * Start offset in the source (UTF-16 code units).
    */
   from: number;
   /**
-   * End offset in the source.
+   * End offset in the source (UTF-16 code units).
    */
   to: number;
   /**
-   * Human-readable error message.
+   * Human-readable error message, verbatim from the engine. Any position it
+   * quotes in prose (e.g. `... at (8, 8)`) is the engine's own UTF-8 byte
+   * coordinate — `from` / `to` carry the converted offsets.
    */
   message: string;
   /**
@@ -132,8 +134,6 @@ declare function satisfiesType(actual: ExpressionType, expected: ExpressionType)
  * engine has not loaded yet.
  */
 declare function satisfiesTypeSync(actual: ExpressionType, expected: ExpressionType): boolean;
-//#endregion
-//#region src/engine/errors.d.ts
 /**
  * Error raised when the ZEN engine fails to load or an expression cannot be
  * evaluated. The original failure is preserved on {@link cause} and the
@@ -151,8 +151,6 @@ declare class ExpressionError extends Error {
 declare class ExpressionNotReadyError extends ExpressionError {
   constructor(message?: string);
 }
-//#endregion
-//#region src/engine/loader.d.ts
 /**
  * The data an expression reads from. Property paths in the expression (e.g.
  * `customer.name`) resolve against this object.
@@ -255,13 +253,20 @@ declare function getEngineError(): ExpressionError | null;
 declare function getEngineSync(): ExpressionEngine;
 /**
  * Reset the engine singleton — drops the loaded engine, the cached type context,
- * the latched error, and the configured wasm input. Mainly for tests, but also the
- * way to re-run {@link configureEngine} after a load (configure throws once the
- * engine has started loading).
+ * the latched error, and the configured wasm input, and orphans any in-flight
+ * load: its later settlement is discarded instead of clobbering the new state,
+ * and the next {@link loadEngine} waits for it to settle before initializing
+ * (the upstream wasm initializer tolerates no concurrent calls — see lastLoad).
+ * Mainly for tests, and the way to re-run {@link configureEngine} after a
+ * **failed** load (configure throws once the engine has started loading).
+ *
+ * A different `wasmInput` cannot take effect once the wasm module has
+ * initialized successfully: the ESM module cache keeps the instantiated module
+ * for the lifetime of the JS realm, and its initializer ignores a new input
+ * after success. Reset-and-reconfigure is therefore a retry primitive for load
+ * failures, not a live wasm-swap.
  */
 declare function resetEngine(): void;
-//#endregion
-//#region src/condition/types.d.ts
 /**
  * Structural shapes for the visual condition model compiled to ZEN. They mirror
  * the condition types used in the form and flow editors so a host can map those
@@ -356,18 +361,33 @@ type BranchSelection = {
   matched: false;
   branchId: string | null;
 };
-//#endregion
-//#region src/condition/compile.d.ts
+/**
+ * Whether a finite number compiles into a ZEN literal that behaves identically
+ * to the same JS number supplied in an evaluation context. Two requirements
+ * fold into this: the literal must be inside ZEN's decimal domain (a 96-bit
+ * mantissa scaled by at most 10^-28 — an out-of-domain literal fails to PARSE
+ * and poisons the whole compiled expression), and the engine's own context
+ * conversion of the number must land on the exact same decimal — otherwise
+ * `field == value` compiled from a value silently evaluates false against a
+ * context holding that very value (the engine converts context f64s lossily;
+ * see internal/zen-decimal.ts). Used by {@link toZenLiteral}, by
+ * {@link liftConditionTree} — which must accept exactly the numbers the
+ * compiler can emit — and by UI layers deciding whether a user-entered number
+ * survives compilation.
+ */
+declare function isZenRepresentableNumber(value: number): boolean;
 /**
  * Serialize a JavaScript value into a ZEN literal. Nullish becomes `null`;
  * numbers / booleans / bigints are emitted verbatim; strings are quoted via
  * {@link encodeZenString}; arrays become `[a, b, ...]`.
  *
  * Throws {@link ExpressionError} for a value with no faithful ZEN
- * representation — an object, symbol, or function, or a string containing both
- * quote styles. Callers that need a sentinel instead of a throw go through
- * {@link compileCondition}, which degrades such a value to a non-compiling
- * (null) condition.
+ * representation — an object, symbol, or function, a string containing both
+ * quote styles, a number failing {@link isZenRepresentableNumber} (outside
+ * ZEN's decimal domain, or held differently by the engine's context
+ * conversion), or a bigint outside the decimal domain. Callers that need a
+ * sentinel instead of a throw go through {@link compileCondition}, which
+ * degrades such a value to a non-compiling (null) condition.
  */
 declare function toZenLiteral(value: unknown): string;
 /**
@@ -405,10 +425,8 @@ declare function selectBranchWith(branches: readonly ConditionBranchInput[], con
  * first use. See {@link selectBranchWith} for the selection semantics.
  */
 declare function selectBranch(branches: readonly ConditionBranchInput[], context: ExpressionContext): Promise<BranchSelection>;
-//#endregion
-//#region src/condition/tree-types.d.ts
 /**
- * The visual condition **tree** model: an arbitrarily nested and/or tree of typed
+ * The visual condition **tree** model: a bounded and/or tree of typed
  * comparison rules that {@link compileConditionTree} serializes to a single ZEN
  * boolean expression and {@link liftConditionTree} reconstructs from one. It is a
  * distinct, self-contained shape from the compiler's flat {@link ConditionInput} —
@@ -417,6 +435,11 @@ declare function selectBranch(branches: readonly ConditionBranchInput[], context
  * leaf: a {@link ConditionTreeRule} lowers to a field {@link ConditionInput} so the
  * operator vocabulary, literal encoding, and injection guard have one owner.
  */
+/**
+ * Maximum number of nested group edges below a condition tree's root group.
+ * The root is depth 0, so a group at depth 64 is valid and one at 65 is not.
+ */
+declare const MAX_CONDITION_TREE_DEPTH = 64;
 /**
  * A scalar operand: the value types ZEN compares against and that survive the
  * compile/lift round-trip (strings, numbers, booleans). Objects and null are not
@@ -460,18 +483,40 @@ type ConditionTreeOperator = typeof CONDITION_TREE_OPERATORS[number];
  */
 interface ConditionTreeRule {
   kind: "rule";
+  /**
+   * Stable node identity for list rendering (React keys). Ignored by the
+   * compiler; {@link liftConditionTree} and the builder's creation paths assign
+   * one, and edits carry it through, so a node keeps its identity for as long
+   * as it exists. Optional so hand-built trees for headless compilation need
+   * not supply it.
+   */
+  id?: string;
   left: string;
   operator: ConditionTreeOperator;
   right?: ConditionTreeValue;
+  /**
+   * The element type intended for a membership (`in` / `not_in`) operand while
+   * `right` is an **empty** array — an empty array cannot say whether the tags
+   * to come are numbers, and a builder toggle has to live in the tree for the
+   * component to stay fully controlled (a same-value form reset must also reset
+   * this). Ignored by the compiler, never produced by
+   * {@link liftConditionTree}, and irrelevant once `right` has elements (their
+   * actual type wins).
+   */
+  rightElementType?: "string" | "number";
 }
 /**
  * A boolean group joining its `items` with `op`. Items are leaf rules or nested
- * groups, making the model an arbitrarily deep and/or tree. The root of a lifted
- * condition is always a group, so callers can treat {@link ConditionTreeGroup} as
- * the tree's entry type.
+ * groups, up to {@link MAX_CONDITION_TREE_DEPTH} nested group edges below the root.
+ * The root of a lifted condition is always a group, so callers can treat
+ * {@link ConditionTreeGroup} as the tree's entry type.
  */
 interface ConditionTreeGroup {
   kind: "group";
+  /**
+   * Stable node identity for list rendering — see {@link ConditionTreeRule.id}.
+   */
+  id?: string;
   op: "and" | "or";
   items: readonly ConditionTreeNode[];
 }
@@ -479,25 +524,37 @@ interface ConditionTreeGroup {
  * A node in the condition tree: a nested group or a leaf rule.
  */
 type ConditionTreeNode = ConditionTreeGroup | ConditionTreeRule;
-//#endregion
-//#region src/condition/compile-tree.d.ts
+/**
+ * A fresh {@link ConditionTreeRule.id | node id}, unique within the process —
+ * exactly the guarantee a React key needs. A tagged counter, not a UUID: node
+ * identity is a UI concern with no persistence or cross-process meaning.
+ */
+declare function newConditionNodeId(): string;
+/**
+ * A fresh empty and-group — the canonical "no condition yet" tree, e.g. a
+ * form's initial value for a condition-builder field. It compiles to `""`.
+ */
+declare function emptyConditionGroup(): ConditionTreeGroup;
 /**
  * Compile a condition tree to a canonical ZEN expression, or `""` when no rule in
  * the tree is compilable (see the module note for the drop semantics).
  */
 declare function compileConditionTree(tree: ConditionTreeGroup): string;
-//#endregion
-//#region src/condition/lift-tree.d.ts
 /**
  * Lift a ZEN expression to a condition tree, or `null` when it is not in the
  * canonical form {@link compileConditionTree} produces (the consumer then keeps the
  * raw expression). Groups nested deeper than 64 parenthesized levels are refused as
- * non-canonical rather than risking parser-stack overflow on adversarial input. The
- * returned root is always a group.
+ * non-canonical rather than risking parser-stack overflow on adversarial input, and
+ * number literals must be canonical (see `parseCanonicalNumber`). The returned root
+ * is always a group, and every node carries a fresh {@link ConditionTreeRule.id}.
  */
 declare function liftConditionTree(expression: string): ConditionTreeGroup | null;
-//#endregion
-//#region src/engine/evaluate.d.ts
+/**
+ * Return `tree` with every node carrying a stable UI id. The shared structural
+ * policy is checked before recursive normalization, so invalid external data fails
+ * with an {@link ExpressionError} instead of a native stack overflow.
+ */
+declare function ensureConditionNodeIds(tree: ConditionTreeGroup): ConditionTreeGroup;
 /**
  * Evaluate a standard ZEN expression, loading the engine on first use.
  *
@@ -521,8 +578,6 @@ declare function evaluateSync<T = unknown>(expression: string, context?: Express
  * {@link ExpressionNotReadyError} when the engine has not loaded yet.
  */
 declare function evaluateUnarySync(expression: string, context?: ExpressionContext): boolean;
-//#endregion
-//#region src/engine/messages.d.ts
 /**
  * The locales the library ships with out of the box.
  */
@@ -608,8 +663,6 @@ declare function configureExpressionMessages({
  * The active {@link ExpressionMessages} catalog (English by default).
  */
 declare function getExpressionMessages(): ExpressionMessages;
-//#endregion
-//#region src/engine/template.d.ts
 /**
  * One `{{ expression }}` hole located in a template document. `from` / `to` are
  * the character offsets of the inner expression itself — the text between the
@@ -676,5 +729,4 @@ declare function getTemplateDiagnosticsSync(source: string): ExpressionDiagnosti
  * Async {@link getTemplateDiagnosticsSync}, loading the engine on first use.
  */
 declare function getTemplateDiagnostics(source: string): Promise<ExpressionDiagnostic[]>;
-//#endregion
-export { type BranchSelection, type BuiltInExpressionLocale, CONDITION_OPERATORS, CONDITION_TREE_OPERATORS, type ConditionBranchInput, type ConditionGroupInput, type ConditionInput, type ConditionOperator, type ConditionOperatorArity, type ConditionScalar, type ConditionTreeGroup, type ConditionTreeNode, type ConditionTreeOperator, type ConditionTreeRule, type ConditionTreeValue, type ConfigureMessagesOptions, type ExpressionAnalysis, type ExpressionCompletion, type ExpressionConditionInput, type ExpressionContext, type ExpressionDiagnostic, type ExpressionEngine, ExpressionError, type ExpressionLocale, type ExpressionMessages, type ExpressionMode, ExpressionNotReadyError, type ExpressionType, type ExpressionTypeSpan, type FieldConditionInput, type LoadEngineOptions, type TemplateHole, analyzeTemplate, analyzeTemplateSync, analyzeTypes, analyzeTypesSync, compileBranch, compileCondition, compileConditionTree, compileGroup, conditionOperatorArity, configureEngine, configureExpressionMessages, enMessages, evaluate, evaluateSync, evaluateUnary, evaluateUnarySync, getCompletionItems, getCompletionItemsSync, getDiagnostics, getDiagnosticsSync, getEngineError, getEngineSync, getExpressionMessages, getTemplateDiagnostics, getTemplateDiagnosticsSync, isEngineReady, liftConditionTree, loadEngine, parseTemplateHoles, registerExpressionLocale, resetEngine, satisfiesType, satisfiesTypeSync, selectBranch, selectBranchWith, templateHoleAt, toZenLiteral, zhCNMessages };
+export { type BranchSelection, type BuiltInExpressionLocale, CONDITION_OPERATORS, CONDITION_TREE_OPERATORS, type ConditionBranchInput, type ConditionGroupInput, type ConditionInput, type ConditionOperator, type ConditionOperatorArity, type ConditionScalar, type ConditionTreeGroup, type ConditionTreeNode, type ConditionTreeOperator, type ConditionTreeRule, type ConditionTreeValue, type ConfigureMessagesOptions, type ExpressionAnalysis, type ExpressionCompletion, type ExpressionConditionInput, type ExpressionContext, type ExpressionDiagnostic, type ExpressionEngine, ExpressionError, type ExpressionLocale, type ExpressionMessages, type ExpressionMode, ExpressionNotReadyError, type ExpressionType, type ExpressionTypeSpan, type FieldConditionInput, type LoadEngineOptions, MAX_CONDITION_TREE_DEPTH, type TemplateHole, analyzeTemplate, analyzeTemplateSync, analyzeTypes, analyzeTypesSync, compileBranch, compileCondition, compileConditionTree, compileGroup, conditionOperatorArity, configureEngine, configureExpressionMessages, emptyConditionGroup, enMessages, ensureConditionNodeIds, evaluate, evaluateSync, evaluateUnary, evaluateUnarySync, getCompletionItems, getCompletionItemsSync, getDiagnostics, getDiagnosticsSync, getEngineError, getEngineSync, getExpressionMessages, getTemplateDiagnostics, getTemplateDiagnosticsSync, isEngineReady, isZenRepresentableNumber, liftConditionTree, loadEngine, newConditionNodeId, parseTemplateHoles, registerExpressionLocale, resetEngine, satisfiesType, satisfiesTypeSync, selectBranch, selectBranchWith, templateHoleAt, toZenLiteral, zhCNMessages };