@paradoc/expr 0.3.0

package/README.md

@@ -0,0 +1,113 @@
+<p align="center">
+  <a href="https://paradoc.dev?utm_source=github&utm_medium=expr" target="_blank" rel="noopener noreferrer">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://assets.paradoc.dev/logo-400x400.png" type="image/png">
+      <img src="https://assets.paradoc.dev/logo-400x400.png" height="64" alt="Paradoc logo">
+    </picture>
+  </a>
+  <br />
+</p>
+
+<h1 align="center">@paradoc/expr</h1>
+
+<div align="center">
+
+[![Paradoc documentation](https://img.shields.io/badge/Documentation-Paradoc-red.svg)](https://docs.paradoc.dev?utm_source=github&utm_medium=expr)
+[![Follow on Twitter](https://img.shields.io/twitter/follow/paradochq?style=social)](https://twitter.com/intent/follow?screen_name=paradochq)
+
+</div>
+
+[Paradoc](https://paradoc.dev?utm_source=github&utm_medium=expr) is **documents as code**. It lets developers and AI agents define, validate, and render business documents using typed, composable schemas. This eliminates template drift, broken mappings, and brittle glue code, while giving AI systems a reliable document layer they can safely read, reason over, and generate against in production workflows.
+
+## Package overview
+
+The purpose-built expression language for Paradoc artifacts. One typed AST is shared by an evaluator and an artifact-aware checker, so authoring-time type checking and runtime evaluation can never disagree. Its scope is logic inside a single artifact: field and section visibility, required, computed defs, validation rules, and payment amounts.
+
+- 🧮 **Exact decimal arithmetic** - money math with no floating-point drift
+- 📅 **Temporal types** - date, datetime, time, and duration, with a host-injected `today()` / `now()` clock
+- 🔎 **Authoring-time checker** - catches unknown references, type mismatches, and non-boolean gates before a form ever runs
+- 🧩 **One registry, two consumers** - the evaluator and the checker share a single function registry, so they never drift apart
+- 🛡️ **Null-safe** - missing values read as `null` instead of throwing, and `null` is first-class
+
+## Installation
+
+```bash
+npm install @paradoc/expr
+```
+
+The same surface is re-exported through `@paradoc/sdk` under an `expr` namespace, so SDK users reach it without a separate dependency:
+
+```typescript
+// Direct import.
+import { check, parse, evaluateExpression, Decimal } from "@paradoc/expr";
+
+// Or via the SDK namespace.
+import { expr } from "@paradoc/sdk";
+expr.check(/* ... */);
+```
+
+## Usage
+
+Evaluate a source string against a context. It returns a result and never throws on a bad expression; values are tagged (`{ kind, value }`):
+
+```typescript
+import { evaluateExpression, createContext } from "@paradoc/expr";
+
+const ctx = createContext({ fields: { age: 25 } });
+
+const result = evaluateExpression("fields.age >= 18", ctx);
+// { success: true, value: { kind: "boolean", value: true } }
+```
+
+Type-check an expression at authoring time. This is what an editor lints with as an author edits a `visible` or computed expression:
+
+```typescript
+import { check, createTypeEnv, T } from "@paradoc/expr";
+
+const env = createTypeEnv({
+  "fields.age": T.number,
+  "fields.country": T.string,
+});
+
+check("fields.age >= 18", env);
+// { type: { kind: "boolean" }, diagnostics: [] }
+
+// An unknown reference is caught before the form ever runs.
+check("fields.age + fields.unknownField", env);
+// diagnostics: [{ severity: "error", code: "unknown-identifier",
+//   message: "Unknown reference: fields.unknownField", span: { ... } }]
+```
+
+Money math is exact, never floating point:
+
+```typescript
+import { Decimal } from "@paradoc/expr";
+
+Decimal.fromString("0.1").add(Decimal.fromString("0.2")).toString();
+// "0.3"  (not 0.30000000000000004)
+
+Decimal.fromString("19.95").mul(Decimal.fromInt(3)).toString();
+// "59.85"
+```
+
+The expression language itself (operators, functions, temporal types) is documented at [docs.paradoc.dev](https://docs.paradoc.dev/concepts/logic). `@paradoc/expr` is a boolean and value expression language, not a flow, routing, or form-selection language.
+
+## Changelog
+
+View the [Changelog](https://github.com/paradoc-dev/paradoc/blob/main/packages/expr/CHANGELOG.md) for updates.
+
+## Related packages
+
+- [`@paradoc/core`](../core) - Runtime and builders; consumes this engine for artifact logic
+- [`@paradoc/sdk`](../sdk) - Complete framework; re-exports this as the `expr` namespace
+- [`@paradoc/types`](../types) - TypeScript utilities and types
+
+## Contributing
+
+We're open to all community contributions! If you'd like to contribute in any way, please read our [contribution guidelines](https://github.com/paradoc-dev/paradoc/blob/main/CONTRIBUTING.md) and [code of conduct](https://github.com/paradoc-dev/paradoc/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+This project is licensed under the MIT license.
+
+See [LICENSE](https://github.com/paradoc-dev/paradoc/blob/main/LICENSE) for more information.

package/dist/index.d.ts

@@ -0,0 +1,513 @@
+/**
+ * Core shared types for @paradoc/expr: source spans, the expression type
+ * system, and diagnostics. Consumed by the parser, evaluator, and checker.
+ */
+/** A 0-based byte offset plus 1-based line/column into the source string. */
+interface Position {
+    readonly offset: number;
+    readonly line: number;
+    readonly column: number;
+}
+/** A source span `[start, end)` over the original expression text. */
+interface Span {
+    readonly start: Position;
+    readonly end: Position;
+}
+/** Primitive (non-parameterized) type kinds in the language. */
+type PrimitiveTypeKind = 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'time' | 'duration' | 'money' | 'object' | 'null' | 'unknown';
+/** A type in the language. Arrays carry their element type (`array<T>`). */
+type ExprType = {
+    readonly kind: PrimitiveTypeKind;
+} | {
+    readonly kind: 'array';
+    readonly element: ExprType;
+};
+/** Terse constructors, e.g. `T.array(T.string)`. */
+declare const T: {
+    readonly string: ExprType;
+    readonly number: ExprType;
+    readonly boolean: ExprType;
+    readonly date: ExprType;
+    readonly datetime: ExprType;
+    readonly time: ExprType;
+    readonly duration: ExprType;
+    readonly money: ExprType;
+    readonly object: ExprType;
+    readonly null: ExprType;
+    readonly unknown: ExprType;
+    readonly array: (element: ExprType) => ExprType;
+};
+/** Human-readable rendering, e.g. `array<string>`. */
+declare function formatType(t: ExprType): string;
+/** Structural type equality. */
+declare function typesEqual(a: ExprType, b: ExprType): boolean;
+/** Diagnostic severity. Errors block authoring; warnings inform. */
+type Severity = 'error' | 'warning';
+/** Stable diagnostic codes. Extended as the checker grows. */
+type DiagnosticCode = 'syntax' | 'unknown-identifier' | 'unknown-function' | 'type-mismatch' | 'arity' | 'non-boolean-gate' | 'circular-defs' | 'forbidden-operator' | 'non-deterministic' | 'division-by-zero';
+interface Diagnostic {
+    readonly severity: Severity;
+    readonly code: DiagnosticCode;
+    readonly message: string;
+    readonly span: Span;
+}
+
+/**
+ * The typed AST produced by the parser and consumed by both the evaluator and
+ * the checker. Every node carries a source `span` so diagnostics can point at
+ * exact positions.
+ *
+ * Numeric literals keep their raw lexeme (`value: string`) so the evaluator can
+ * parse them into exact decimals without an intermediate float that would lose
+ * precision.
+ */
+
+interface NodeBase {
+    readonly span: Span;
+}
+interface NumberLiteral extends NodeBase {
+    readonly kind: 'NumberLiteral';
+    /** Raw lexeme, parsed to exact decimal by the evaluator. */
+    readonly value: string;
+}
+interface StringLiteral extends NodeBase {
+    readonly kind: 'StringLiteral';
+    readonly value: string;
+}
+interface BooleanLiteral extends NodeBase {
+    readonly kind: 'BooleanLiteral';
+    readonly value: boolean;
+}
+interface NullLiteral extends NodeBase {
+    readonly kind: 'NullLiteral';
+}
+interface ArrayLiteral extends NodeBase {
+    readonly kind: 'ArrayLiteral';
+    readonly elements: readonly Expr[];
+}
+/** A bare reference: a defs key, or a context root such as `fields`. */
+interface Identifier extends NodeBase {
+    readonly kind: 'Identifier';
+    readonly name: string;
+}
+/** Dotted member access `object.property`. Null-safe at evaluation. */
+interface Member extends NodeBase {
+    readonly kind: 'Member';
+    readonly object: Expr;
+    readonly property: string;
+}
+/** Indexed access `object[index]`. Reserved; not an author surface in v1. */
+interface Index extends NodeBase {
+    readonly kind: 'Index';
+    readonly object: Expr;
+    readonly index: Expr;
+}
+type UnaryOp = 'not' | 'neg';
+interface Unary extends NodeBase {
+    readonly kind: 'Unary';
+    readonly op: UnaryOp;
+    readonly operand: Expr;
+}
+type ArithmeticOp = '+' | '-' | '*' | '/' | '%';
+type ComparisonOp = '==' | '!=' | '<' | '<=' | '>' | '>=';
+/** `+` is polymorphic: numeric add or string concat, resolved by operand type. */
+type BinaryOp = ArithmeticOp | ComparisonOp;
+interface Binary extends NodeBase {
+    readonly kind: 'Binary';
+    readonly op: BinaryOp;
+    readonly left: Expr;
+    readonly right: Expr;
+}
+type LogicalOp = 'and' | 'or';
+interface Logical extends NodeBase {
+    readonly kind: 'Logical';
+    readonly op: LogicalOp;
+    readonly left: Expr;
+    readonly right: Expr;
+}
+/** `element in collection` / `element not in collection`. */
+interface Membership extends NodeBase {
+    readonly kind: 'Membership';
+    readonly negated: boolean;
+    readonly element: Expr;
+    readonly collection: Expr;
+}
+/** Ternary `test ? consequent : alternate`. */
+interface Conditional extends NodeBase {
+    readonly kind: 'Conditional';
+    readonly test: Expr;
+    readonly consequent: Expr;
+    readonly alternate: Expr;
+}
+/** A function call by name. Functions are not first-class values. */
+interface Call extends NodeBase {
+    readonly kind: 'Call';
+    readonly callee: string;
+    readonly args: readonly Expr[];
+}
+type Expr = NumberLiteral | StringLiteral | BooleanLiteral | NullLiteral | ArrayLiteral | Identifier | Member | Index | Unary | Binary | Logical | Membership | Conditional | Call;
+type ExprKind = Expr['kind'];
+
+/**
+ * Pure-data grammar configuration consumed by the parser. Declares the keyword
+ * set and the operator precedence / associativity table. No logic lives here;
+ * the parser (config-declares, packages-execute) reads this to drive parsing.
+ */
+/** Reserved words that are never parsed as identifiers. */
+declare const KEYWORDS: readonly ["and", "or", "not", "in", "true", "false", "null"];
+type Keyword = (typeof KEYWORDS)[number];
+type Associativity = 'left' | 'right';
+interface OperatorInfo {
+    readonly token: string;
+    readonly precedence: number;
+    readonly associativity: Associativity;
+}
+/**
+ * Binary, logical, and membership operators by binding power (higher binds
+ * tighter). Precedence ladder, loosest to tightest:
+ *   or < and < equality < comparison < membership < additive < multiplicative.
+ * Unary operators bind tighter than any binary; the ternary `? :` is the
+ * loosest construct and is handled directly by the parser.
+ *
+ * `not in` is lexed as the `in` operator with a preceding `not`; the parser
+ * folds it into a negated Membership node.
+ */
+declare const BINARY_OPERATORS: readonly OperatorInfo[];
+/** Prefix unary operators. `!` is an alias for `not`. */
+declare const UNARY_OPERATORS: readonly ["not", "!", "-"];
+/**
+ * Operators the language deliberately rejects, mapped to the message the
+ * checker surfaces. `=` is assignment (a `==` typo); `||` / `&&` are the
+ * dropped overloaded forms.
+ */
+declare const FORBIDDEN_OPERATORS: Readonly<Record<string, string>>;
+/** Fast membership lookup for the lexer/parser. */
+declare const KEYWORD_SET: ReadonlySet<string>;
+declare const BINARY_OPERATOR_TOKENS: ReadonlySet<string>;
+
+/**
+ * The function registry: the single source of truth for the language's
+ * callable functions. Both the evaluator and the checker read it, so the
+ * design-time and runtime function vocabularies cannot drift (the class of
+ * "type-checks green, throws at runtime" bug is structurally impossible).
+ *
+ * This module declares only SIGNATURES (names, parameter types, return types,
+ * flags). The evaluator binds runtime implementations to these names; a
+ * conformance test asserts the two sets are identical.
+ */
+
+/**
+ * How a function's return type is determined. Most are `fixed`; `commonOfArgs`
+ * (coalesce) and `elementOf` (reserved for collection ops) depend on argument
+ * types and are resolved by the checker.
+ */
+type ReturnSpec = {
+    readonly kind: 'fixed';
+    readonly type: ExprType;
+} | {
+    readonly kind: 'commonOfArgs';
+} | {
+    readonly kind: 'elementOf';
+    readonly arg: number;
+};
+interface ParamSpec {
+    readonly name: string;
+    /** Expected type; `unknown` accepts any argument. */
+    readonly type: ExprType;
+    readonly optional?: boolean;
+}
+type FnCategory = 'string' | 'number' | 'date' | 'collection' | 'domain' | 'logical';
+interface FnSignature {
+    readonly name: string;
+    readonly category: FnCategory;
+    readonly params: readonly ParamSpec[];
+    /** The final parameter may repeat (e.g. `min`, `max`, `coalesce`). */
+    readonly variadic?: boolean;
+    readonly returns: ReturnSpec;
+    /**
+     * Requires host-provided context at evaluation: `today`/`now` need the
+     * as-of timestamp; the party/witness functions need the party context.
+     */
+    readonly hostInjected?: boolean;
+    /** All registered functions must be deterministic; non-determinism is rejected. */
+    readonly deterministic: boolean;
+}
+/**
+ * The default registry. Collection aggregates (`any`/`all`/`none`/`sum`/`join`)
+ * are intentionally absent until a repeating-group field type exists; see
+ * _docs/plans/paradoc-expr/language-spec.md.
+ */
+declare const DEFAULT_SIGNATURES: readonly FnSignature[];
+/** A resolved registry: name -> signature, with helpers. */
+interface Registry {
+    readonly signatures: ReadonlyMap<string, FnSignature>;
+    has(name: string): boolean;
+    get(name: string): FnSignature | undefined;
+    names(): readonly string[];
+}
+/**
+ * Build a registry from the default signatures plus any host-provided
+ * extensions (e.g. additional domain functions). Later entries override
+ * earlier ones by name.
+ */
+declare function buildRegistry(extra?: readonly FnSignature[]): Registry;
+
+/**
+ * Recursive-descent / precedence-climbing parser. Consumes the token stream and
+ * the pure-data grammar config to produce the typed AST. Reports a single,
+ * positioned syntax error (good messages over multi-error recovery for v1),
+ * including helpful diagnostics for the deliberately rejected operators.
+ */
+
+interface ParseResult {
+    readonly ast: Expr | null;
+    readonly errors: readonly Diagnostic[];
+}
+/** Parse an expression string into an AST, collecting a syntax error if any. */
+declare function parse(source: string): ParseResult;
+/** Parse, throwing on the first error. Convenience for callers that expect valid input. */
+declare function parseOrThrow(source: string): Expr;
+
+/**
+ * Tokenizer. Turns an expression string into a flat token stream with a source
+ * span on every token. Forbidden operators (`=`, `||`, `&&`) are lexed as
+ * operator tokens so the parser can report them with a helpful message rather
+ * than a bare "unexpected character".
+ */
+
+type TokenType = 'number' | 'string' | 'identifier' | 'keyword' | 'operator' | 'lparen' | 'rparen' | 'lbracket' | 'rbracket' | 'comma' | 'dot' | 'question' | 'colon' | 'eof';
+interface Token {
+    readonly type: TokenType;
+    readonly value: string;
+    readonly span: Span;
+}
+declare class LexError extends Error {
+    readonly position: Position;
+    constructor(message: string, position: Position);
+}
+declare function tokenize(source: string): Token[];
+
+/**
+ * Static reference extraction. Walks an AST and returns the set of value
+ * references it depends on, as dotted paths rooted at a bare identifier
+ * (`fields.age`, `fields.unitPrice.amount`, `isAdult`).
+ *
+ * This is the load-bearing guarantee behind the dependency-aware fill state in
+ * @paradoc/core: gate expressions must expose their field/defs references
+ * completely and cheaply. `fullyStatic` is false when a reference path passes
+ * through a dynamic segment (an index expression), which the DAG cannot resolve
+ * statically; such expressions must be rejected or handled explicitly upstream.
+ */
+
+interface References {
+    /** Dotted paths rooted at an identifier, sorted and de-duplicated. */
+    readonly paths: readonly string[];
+    /** False if any reference path passes through a dynamic (index) segment. */
+    readonly fullyStatic: boolean;
+}
+declare function extractReferences(ast: Expr): References;
+
+/**
+ * Exact-decimal arithmetic, in-house, backed by `bigint`. No floating point is
+ * ever used, so `19.95 * 3` is exactly `59.85` and money/percentage math is
+ * exact. A value is `n / 10^scale` with `scale >= 0`.
+ *
+ * Rounding defaults to half-up (commercial rounding). Division is computed to a
+ * bounded number of decimal places and then trimmed of trailing zeros.
+ */
+type RoundingMode = 'half-up' | 'down' | 'floor' | 'ceil';
+declare class DivisionByZeroError extends Error {
+    constructor();
+}
+declare class Decimal {
+    readonly n: bigint;
+    readonly scale: number;
+    private constructor();
+    static fromString(s: string): Decimal;
+    static fromInt(i: bigint | number): Decimal;
+    static readonly ZERO: Decimal;
+    /** Bring two decimals to a common scale, returning aligned magnitudes. */
+    private static align;
+    add(b: Decimal): Decimal;
+    sub(b: Decimal): Decimal;
+    mul(b: Decimal): Decimal;
+    div(b: Decimal, rm?: RoundingMode): Decimal;
+    mod(b: Decimal): Decimal;
+    neg(): Decimal;
+    abs(): Decimal;
+    /** -1, 0, or 1. */
+    cmp(b: Decimal): number;
+    eq(b: Decimal): boolean;
+    lt(b: Decimal): boolean;
+    lte(b: Decimal): boolean;
+    gt(b: Decimal): boolean;
+    gte(b: Decimal): boolean;
+    isZero(): boolean;
+    /** Round to `digits` decimal places (default 0). Negative/fractional
+     * digits are clamped to a valid non-negative integer scale. */
+    round(digits?: number, rm?: RoundingMode): Decimal;
+    floor(): Decimal;
+    ceil(): Decimal;
+    private toScale;
+    /** Remove trailing fractional zeros, keeping the value identical. */
+    private trim;
+    toString(): string;
+    /** Lossy conversion to a JS number, for interop only. */
+    toNumber(): number;
+    toJSON(): string;
+}
+
+/**
+ * Runtime values. The evaluator works over this tagged union. Money is just an
+ * `object` with `amount` (number) and `currency` (string); temporal values are
+ * ISO strings. Neither needs a dedicated runtime kind: the type system tracks
+ * those distinctions, and the date functions parse the strings as needed.
+ */
+
+type Value = {
+    readonly kind: 'number';
+    readonly value: Decimal;
+} | {
+    readonly kind: 'string';
+    readonly value: string;
+} | {
+    readonly kind: 'boolean';
+    readonly value: boolean;
+} | {
+    readonly kind: 'null';
+} | {
+    readonly kind: 'array';
+    readonly value: readonly Value[];
+} | {
+    readonly kind: 'object';
+    readonly value: ReadonlyMap<string, Value>;
+};
+declare const NULL: Value;
+declare const Values: {
+    readonly number: (d: Decimal) => Value;
+    readonly num: (s: string) => Value;
+    readonly string: (s: string) => Value;
+    readonly boolean: (b: boolean) => Value;
+    readonly null: {
+        readonly kind: "null";
+    };
+    readonly array: (v: readonly Value[]) => Value;
+    readonly object: (entries: Iterable<readonly [string, Value]>) => Value;
+};
+/**
+ * Coerce a plain host JS value into a `Value`. Numbers become exact decimals;
+ * objects and arrays convert deeply. Money/temporal are not auto-detected (a
+ * money field arrives as `{ amount, currency }`, a date as an ISO string).
+ */
+declare function toValue(js: unknown): Value;
+/** Boolean coercion for gate contexts and ternary/logical tests. */
+declare function truthy(v: Value): boolean;
+/** String rendering, used by polymorphic `+` concatenation and display. */
+declare function valueToString(v: Value): string;
+/** Equality for `==` / `!=`. No cross-type coercion: `'1' != 1`. */
+declare function valueEquals(a: Value, b: Value): boolean;
+
+/** Runtime evaluation errors. The top-level wrapper maps these to results. */
+type EvalErrorCode = 'division-by-zero' | 'type-error' | 'unknown-identifier' | 'unknown-function' | 'arity' | 'missing-clock';
+declare class EvaluationError extends Error {
+    readonly code: EvalErrorCode;
+    constructor(code: EvalErrorCode, message: string);
+}
+
+/**
+ * The evaluation context: how the evaluator resolves bare references, reads the
+ * host-supplied "as of" clock for `today()`/`now()`, and dispatches
+ * host-injected domain functions (the party/witness predicates).
+ */
+
+/** The as-of timestamps for `today()`/`now()`, stored with the submission so a
+ * re-evaluation is reproducible. Never read from the wall clock. */
+interface AsOf {
+    /** ISO date, `YYYY-MM-DD`. */
+    readonly date: string;
+    /** ISO datetime. */
+    readonly datetime: string;
+}
+type HostFunction = (args: readonly Value[]) => Value;
+interface EvaluationContext {
+    /** Resolve a top-level identifier (e.g. `fields`, a defs key) or undefined. */
+    lookup(name: string): Value | undefined;
+    readonly asOf?: AsOf;
+    /** Host-injected functions (party/witness predicates), by name. */
+    readonly hostFunctions?: Readonly<Record<string, HostFunction>>;
+}
+interface ContextOptions {
+    readonly asOf?: AsOf;
+    readonly hostFunctions?: Readonly<Record<string, HostFunction>>;
+}
+/** Build a context from a plain host data object (e.g. `{ fields, ...defs }`). */
+declare function createContext(data: Record<string, unknown>, opts?: ContextOptions): EvaluationContext;
+
+/**
+ * Built-in function implementations, keyed by the same names the registry
+ * declares. The evaluator dispatches here; the party/witness domain functions
+ * are NOT here (they are host-injected via the context). A conformance test
+ * asserts these keys match the registry's non-domain functions exactly.
+ */
+
+type Impl = (args: readonly Value[], ctx: EvaluationContext) => Value;
+declare const BUILTIN_IMPLS: Readonly<Record<string, Impl>>;
+
+/**
+ * The tree-walking evaluator. Null-safe member access, polymorphic `+`,
+ * exact-decimal arithmetic, short-circuiting logic, membership, ternary, and
+ * function dispatch (host-injected functions first, then builtins).
+ */
+
+declare function evaluate(node: Expr, ctx: EvaluationContext): Value;
+type EvalResult = {
+    readonly success: true;
+    readonly value: Value;
+} | {
+    readonly success: false;
+    readonly error: string;
+    readonly code?: EvalErrorCode;
+    readonly diagnostics?: readonly Diagnostic[];
+};
+/** Parse and evaluate a source expression, capturing errors as a result. */
+declare function evaluateExpression(source: string, ctx: EvaluationContext): EvalResult;
+/**
+ * Evaluate an expression in a boolean gate context, returning `defaultValue`
+ * when it is undefined or fails (the default-on-failure gate semantics). A
+ * boolean literal short-circuits without parsing.
+ */
+declare function evaluateBoolean(condExpr: boolean | string | undefined, ctx: EvaluationContext, defaultValue: boolean): boolean;
+
+/**
+ * The artifact-aware checker. Infers the type of an expression against a
+ * host-supplied type environment (which maps reference paths and defs keys to
+ * types) and the function registry, emitting positioned diagnostics. This is
+ * what an authoring editor lints with.
+ *
+ * @paradoc/expr stays decoupled from the artifact schema: the host (e.g.
+ * @paradoc/core) builds the TypeEnv from real field definitions.
+ */
+
+interface TypeEnv {
+    /** Type of a reference path (`fields.age`, `isAdult`), or undefined if unknown. */
+    resolve(path: string): ExprType | undefined;
+    readonly registry: Registry;
+}
+interface CheckResult {
+    readonly type: ExprType;
+    readonly diagnostics: readonly Diagnostic[];
+}
+/** Build a simple TypeEnv from a path->type map (host adapters build richer ones). */
+declare function createTypeEnv(paths: Record<string, ExprType>, registry?: Registry): TypeEnv;
+/** Infer the type of a parsed expression, collecting diagnostics. */
+declare function checkAst(ast: Expr, env: TypeEnv): CheckResult;
+/** Parse and check a source expression. Syntax errors short-circuit type checks. */
+declare function check(source: string, env: TypeEnv): CheckResult;
+/**
+ * Check an expression used in a boolean gate (visible/required/include/rule):
+ * everything `check` does, plus a non-boolean-gate error when the result is not
+ * boolean (boolean literals are allowed as a degenerate gate).
+ */
+declare function checkBooleanGate(source: string, env: TypeEnv): CheckResult;
+
+export { type ArithmeticOp, type ArrayLiteral, type AsOf, type Associativity, BINARY_OPERATORS, BINARY_OPERATOR_TOKENS, BUILTIN_IMPLS, type Binary, type BinaryOp, type BooleanLiteral, type Call, type CheckResult, type ComparisonOp, type Conditional, type ContextOptions, DEFAULT_SIGNATURES, Decimal, type Diagnostic, type DiagnosticCode, DivisionByZeroError, type EvalErrorCode, type EvalResult, type EvaluationContext, EvaluationError, type Expr, type ExprKind, type ExprType, FORBIDDEN_OPERATORS, type FnCategory, type FnSignature, type HostFunction, type Identifier, type Impl, type Index, KEYWORDS, KEYWORD_SET, type Keyword, LexError, type Logical, type LogicalOp, type Member, type Membership, NULL, type NullLiteral, type NumberLiteral, type OperatorInfo, type ParamSpec, type ParseResult, type Position, type PrimitiveTypeKind, type References, type Registry, type ReturnSpec, type RoundingMode, type Severity, type Span, type StringLiteral, T, type Token, type TokenType, type TypeEnv, UNARY_OPERATORS, type Unary, type UnaryOp, type Value, Values, buildRegistry, check, checkAst, checkBooleanGate, createContext, createTypeEnv, evaluate, evaluateBoolean, evaluateExpression, extractReferences, formatType, parse, parseOrThrow, toValue, tokenize, truthy, typesEqual, valueEquals, valueToString };