fhirpath-ts 0.0.0-bootstrap.0 → 0.2.0

package/src/analyzer/declarations.ts

@@ -0,0 +1,120 @@
+import { normalizeEnvKeys } from '../engine/context.ts'
+import type { ModelProvider } from '../model/provider.ts'
+import type { FhirpathTypeDeclaration, FhirpathTypeDeclarations } from '../typed/infer.ts'
+import { OBJECT_TYPE, toCollection, type TypedValue, typeLocalName } from '../values/typed-value.ts'
+
+/** A host variable in the analyzer's canonical collection form. */
+export interface AnalyzerVariable {
+  types?: string[]
+  single?: boolean
+  targets?: string[]
+}
+
+/** Internal variable state with the exact focus types used by runtime host-function dispatch. */
+export interface RuntimeAnalyzerVariable extends AnalyzerVariable {
+  exactTypes: string[]
+}
+
+export type AnalyzerVariableState = AnalyzerVariable | RuntimeAnalyzerVariable
+
+export function isRuntimeAnalyzerVariable(variable: AnalyzerVariableState): variable is RuntimeAnalyzerVariable {
+  return 'exactTypes' in variable
+}
+
+/** Convert one public type declaration into analyzer state. */
+export function analyzerVariable(declaration: FhirpathTypeDeclaration): AnalyzerVariable {
+  return {
+    types: typeof declaration.type === 'string' ? [declaration.type] : [...declaration.type],
+    single: declaration.collection === true ? false : true,
+    ...(declaration.targets !== undefined && {
+      targets: typeof declaration.targets === 'string' ? [declaration.targets] : [...declaration.targets],
+    }),
+  }
+}
+
+/** Convert one runtime collection while retaining the exact types used for host-function dispatch. */
+export function runtimeAnalyzerVariable(
+  collection: readonly TypedValue[],
+  model: ModelProvider | undefined,
+  declaration?: FhirpathTypeDeclaration
+): RuntimeAnalyzerVariable {
+  const inferred = analyzerVariableFromCollection(collection, model)
+  return {
+    ...(declaration === undefined ? inferred : analyzerVariable(declaration)),
+    exactTypes: collection.map(item => item.type),
+  }
+}
+
+function analyzerVariableFromCollection(
+  collection: readonly TypedValue[],
+  model: ModelProvider | undefined
+): AnalyzerVariable {
+  const inferred = collection.map(item => inferAnalyzerType(item.type, model))
+  const types = inferred.every(type => type !== undefined) ? [...new Set(inferred)] : undefined
+  return {
+    ...(types !== undefined && types.length > 0 && { types }),
+    single: collection.length <= 1,
+  }
+}
+
+function analyzerVariableFromValue(value: unknown, model: ModelProvider | undefined): AnalyzerVariable {
+  return analyzerVariableFromCollection(toCollection(value), model)
+}
+
+function inferAnalyzerType(type: string, model: ModelProvider | undefined): string | undefined {
+  if (type === OBJECT_TYPE) {
+    return undefined
+  }
+  return type.startsWith('System.') ? type : model?.resolveType(typeLocalName(type))
+}
+
+/** Declare every runtime value name and add explicit type information. */
+export function analyzerVariables(
+  values: object | undefined,
+  declarations: FhirpathTypeDeclarations | undefined
+): Record<string, AnalyzerVariable> {
+  return collectAnalyzerVariables(values, declarations, (_value, declaration) =>
+    declaration === undefined ? {} : analyzerVariable(declaration)
+  )
+}
+
+/** Infer safe types from environment values, with explicit declarations taking precedence. */
+export function analyzerEnvironmentVariables(
+  values: object | undefined,
+  declarations: FhirpathTypeDeclarations | undefined,
+  model: ModelProvider | undefined
+): Record<string, AnalyzerVariable> {
+  return collectAnalyzerVariables(values, declarations, (value, declaration) =>
+    declaration === undefined ? analyzerVariableFromValue(value, model) : analyzerVariable(declaration)
+  )
+}
+
+/** Runtime environment state, retaining actual dispatch types independently of declarations. */
+export function runtimeAnalyzerEnvironmentVariables(
+  values: object | undefined,
+  declarations: FhirpathTypeDeclarations | undefined,
+  model: ModelProvider | undefined
+): Record<string, AnalyzerVariableState> {
+  return collectAnalyzerVariables(values, declarations, (value, declaration) =>
+    runtimeAnalyzerVariable(toCollection(value), model, declaration)
+  )
+}
+
+function collectAnalyzerVariables(
+  values: object | undefined,
+  declarations: FhirpathTypeDeclarations | undefined,
+  inferValue: (value: unknown, declaration: FhirpathTypeDeclaration | undefined) => AnalyzerVariable
+): Record<string, AnalyzerVariable> {
+  const normalizedValues = normalizeEnvKeys(values as Readonly<Record<string, unknown>> | undefined)
+  const normalizedDeclarations = normalizeEnvKeys(declarations)
+  const variables: Record<string, AnalyzerVariable> = {}
+  for (const name of new Set([...Object.keys(normalizedValues), ...Object.keys(normalizedDeclarations)])) {
+    const declaration = normalizedDeclarations[name]
+    if (Object.hasOwn(normalizedValues, name)) {
+      variables[name] = inferValue(normalizedValues[name], declaration)
+    } else if (declaration !== undefined) {
+      variables[name] = analyzerVariable(declaration)
+    }
+  }
+  return variables
+}

package/src/analyzer/operator-rules.ts

@@ -0,0 +1,88 @@
+import type { BinaryOperator } from '../parser/ast.ts'
+import { commonValueKind } from '../values/type-compat.ts'
+import { type StaticStateLike, unionStates, withSingle } from './signatures.ts'
+
+export type OperatorResultRule =
+  | { kind: 'fixed'; types: readonly string[]; single: boolean }
+  | { kind: 'arithmetic' }
+  | { kind: 'union' }
+  | { kind: 'narrow' }
+
+const BOOLEAN = { kind: 'fixed', types: ['System.Boolean'], single: true } as const
+
+/** Result semantics for every runtime binary operator. */
+export const OPERATOR_RESULT_RULES = {
+  '*': { kind: 'arithmetic' },
+  '/': { kind: 'arithmetic' },
+  div: { kind: 'arithmetic' },
+  mod: { kind: 'arithmetic' },
+  '+': { kind: 'arithmetic' },
+  '-': { kind: 'arithmetic' },
+  '&': { kind: 'fixed', types: ['System.String'], single: true },
+  '|': { kind: 'union' },
+  '<': BOOLEAN,
+  '>': BOOLEAN,
+  '<=': BOOLEAN,
+  '>=': BOOLEAN,
+  '=': BOOLEAN,
+  '~': BOOLEAN,
+  '!=': BOOLEAN,
+  '!~': BOOLEAN,
+  in: BOOLEAN,
+  contains: BOOLEAN,
+  and: BOOLEAN,
+  or: BOOLEAN,
+  xor: BOOLEAN,
+  implies: BOOLEAN,
+} as const satisfies Record<BinaryOperator, OperatorResultRule>
+
+export const TYPE_OPERATOR_RESULT_RULES = {
+  is: BOOLEAN,
+  as: { kind: 'narrow' },
+} as const satisfies Record<'is' | 'as', OperatorResultRule>
+
+/** Interpret a binary rule after the analyzer has reported operand diagnostics. */
+export function applyOperatorResultRule(
+  operator: BinaryOperator,
+  left: StaticStateLike,
+  right: StaticStateLike
+): StaticStateLike {
+  const rule = OPERATOR_RESULT_RULES[operator]
+  switch (rule.kind) {
+    case 'fixed':
+      return { types: [...rule.types], single: rule.single }
+    case 'arithmetic': {
+      const leftKind = commonValueKind(left.types)
+      const rightKind = commonValueKind(right.types)
+      const quantity = (operator === '*' || operator === '/') && (leftKind === 'Quantity' || rightKind === 'Quantity')
+      return {
+        types: quantity ? ['System.Quantity'] : operator === '/' ? ['System.Decimal'] : (left.types ?? right.types),
+        single: true,
+      }
+    }
+    case 'union':
+      if (left.types?.length === 0) {
+        return right
+      }
+      if (right.types?.length === 0) {
+        return left
+      }
+      return withSingle(unionStates([left, right]), false)
+  }
+}
+
+/** Interpret a type-operator rule after the analyzer has validated its operand and target. */
+export function applyTypeOperatorResultRule(
+  operator: keyof typeof TYPE_OPERATOR_RESULT_RULES,
+  narrowedTypes: readonly string[] | undefined
+): StaticStateLike {
+  const rule = TYPE_OPERATOR_RESULT_RULES[operator]
+  switch (rule.kind) {
+    case 'fixed':
+      return { types: [...rule.types], single: rule.single }
+    case 'narrow':
+      return narrowedTypes === undefined
+        ? { types: undefined, single: undefined }
+        : { types: [...narrowedTypes], single: true }
+  }
+}

package/src/analyzer/signatures.ts

@@ -1,6 +1,6 @@
 import type { ValueKind } from '../values/type-compat.ts'
 
-interface StaticStateLike {
+export interface StaticStateLike {
   types: string[] | undefined
   /** True: at most one item. False: may hold several. Undefined: cardinality unknown. */
   single: boolean | undefined
@@ -35,7 +35,7 @@ export interface InputSpec {
   kind?: ValueKind
   singleton?: boolean
   /** Canonical or local model type names ('CodeableConcept', 'System.String'). */
-  types?: string[]
+  types?: readonly string[]
 }
 
 /**
@@ -46,26 +46,74 @@ export interface InputSpec {
  */
 export interface CustomFunctionSignature {
   input?: InputSpec
-  args?: ValueArgSpec[]
-  result?: { types?: string[]; single?: boolean }
+  args?: readonly ValueArgSpec[]
+  result?: { types?: readonly string[]; single?: boolean }
 }
 
+/**
+ * Declarative result rules shared by analyzer signatures and the generated
+ * type-level rule table. Keeping these as data prevents the two inference
+ * implementations from acquiring separate handwritten function semantics.
+ */
+export type ResultRule =
+  | { kind: 'fixed'; types?: readonly string[]; single?: boolean }
+  | { kind: 'input' }
+  | { kind: 'input-item' }
+  | { kind: 'argument'; index: number }
+  | { kind: 'union'; sources: readonly ('input' | number)[]; single: boolean | 'all' }
+  | { kind: 'arguments-union' }
+  | { kind: 'reference-targets' }
+  | { kind: 'unknown' }
+
 export interface FunctionSignature {
   input?: InputSpec
-  args?: ArgSpec[]
-  /**
-   * Result state from the input state and the analyzed argument states
-   * (undefined for `type-name` positions and missing optional arguments).
-   */
-  result: (input: StaticStateLike, args: readonly (StaticStateLike | undefined)[]) => StaticStateLike
+  args?: readonly ArgSpec[]
+  result: ResultRule
 }
 
-const BOOLEAN = (): StaticStateLike => ({ types: ['System.Boolean'], single: true })
-const INTEGER = (): StaticStateLike => ({ types: ['System.Integer'], single: true })
-const STRING = (): StaticStateLike => ({ types: ['System.String'], single: true })
-const DECIMAL = (): StaticStateLike => ({ types: ['System.Decimal'], single: true })
-const UNKNOWN = (): StaticStateLike => ({ types: undefined, single: undefined })
-const SAME = (input: StaticStateLike): StaticStateLike => input
+const BOOLEAN = { kind: 'fixed', types: ['System.Boolean'], single: true } as const satisfies ResultRule
+const INTEGER = { kind: 'fixed', types: ['System.Integer'], single: true } as const satisfies ResultRule
+const STRING = { kind: 'fixed', types: ['System.String'], single: true } as const satisfies ResultRule
+const DECIMAL = { kind: 'fixed', types: ['System.Decimal'], single: true } as const satisfies ResultRule
+const LONG = { kind: 'fixed', types: ['System.Long'], single: true } as const satisfies ResultRule
+const DATE = { kind: 'fixed', types: ['System.Date'], single: true } as const satisfies ResultRule
+const DATETIME = { kind: 'fixed', types: ['System.DateTime'], single: true } as const satisfies ResultRule
+const TIME = { kind: 'fixed', types: ['System.Time'], single: true } as const satisfies ResultRule
+const QUANTITY = { kind: 'fixed', types: ['System.Quantity'], single: true } as const satisfies ResultRule
+const UNKNOWN = { kind: 'unknown' } as const satisfies ResultRule
+const SAME = { kind: 'input' } as const satisfies ResultRule
+const ITEM = { kind: 'input-item' } as const satisfies ResultRule
+
+/** Interpret one declarative result rule for the runtime analyzer. */
+export function applyResultRule(
+  rule: ResultRule,
+  input: StaticStateLike,
+  args: readonly (StaticStateLike | undefined)[]
+): StaticStateLike {
+  switch (rule.kind) {
+    case 'fixed':
+      return { types: rule.types === undefined ? undefined : [...rule.types], single: rule.single }
+    case 'input':
+      return input
+    case 'input-item':
+      return withSingle(input, true)
+    case 'argument': {
+      const argument = args[rule.index] ?? { types: undefined, single: undefined }
+      return withSingle(argument, singleAnd(input.single, argument.single))
+    }
+    case 'union': {
+      const states = rule.sources.map(source => (source === 'input' ? input : args[source]))
+      const merged = unionStates(states)
+      return rule.single === 'all' ? merged : withSingle(merged, rule.single)
+    }
+    case 'arguments-union':
+      return unionStates([...args])
+    case 'reference-targets':
+      return { types: input.targets, single: input.single }
+    case 'unknown':
+      return { types: undefined, single: undefined }
+  }
+}
 
 /**
  * The input's candidate types and reference targets at a different cardinality
@@ -78,8 +126,6 @@ export function withSingle(input: StaticStateLike, single: boolean | undefined):
     : { types: input.types, single, targets: input.targets }
 }
 
-const ITEM = (input: StaticStateLike): StaticStateLike => withSingle(input, true)
-
 /**
  * The union of several alternative states (iif branches, coalesce arguments,
  * merged collections): all candidate types, single only when every alternative
@@ -101,14 +147,21 @@ export function unionStates(states: (StaticStateLike | undefined)[]): StaticStat
   return targets === undefined ? { types, single } : { types, single, targets }
 }
 
-const STRING_FN: FunctionSignature = { input: { kind: 'String', singleton: true }, args: ['String'], result: STRING }
-const MATH_FN: FunctionSignature = { input: { kind: 'Numeric', singleton: true }, result: DECIMAL }
+const STRING_FN = {
+  input: { kind: 'String', singleton: true },
+  args: ['String'],
+  result: STRING,
+} as const satisfies FunctionSignature
+const MATH_FN = {
+  input: { kind: 'Numeric', singleton: true },
+  result: DECIMAL,
+} as const satisfies FunctionSignature
 
 /**
  * What the analyzer knows about each function. Functions missing here still get
  * arity checks from the runtime registry; their results become unknown.
  */
-export const FUNCTION_SIGNATURES: Readonly<Record<string, FunctionSignature>> = {
+const FUNCTION_SIGNATURE_DEFINITIONS = {
   empty: { result: BOOLEAN },
   exists: { args: ['expression'], result: BOOLEAN },
   all: { args: ['expression'], result: BOOLEAN },
@@ -128,7 +181,7 @@ export const FUNCTION_SIGNATURES: Readonly<Record<string, FunctionSignature>> =
     args: ['expression'],
     // The projection's analyzed state, collection-ized: single only when both
     // the input and the projection body are single.
-    result: (input, args) => withSingle(args[0] ?? UNKNOWN(), singleAnd(input.single, args[0]?.single)),
+    result: { kind: 'argument', index: 0 },
   },
   repeat: { args: ['expression'], result: UNKNOWN },
   // ofType/as results narrow to the named type; the analyzer computes that with
@@ -144,12 +197,12 @@ export const FUNCTION_SIGNATURES: Readonly<Record<string, FunctionSignature>> =
   take: { args: ['Numeric'], result: SAME },
   intersect: { args: ['any'], result: SAME },
   exclude: { args: ['any'], result: SAME },
-  union: { args: ['any'], result: (input, args) => withSingle(unionStates([input, args[0]]), false) },
-  combine: { args: ['any'], result: (input, args) => withSingle(unionStates([input, args[0]]), false) },
+  union: { args: ['any'], result: { kind: 'union', sources: ['input', 0], single: false } },
+  combine: { args: ['any'], result: { kind: 'union', sources: ['input', 0], single: false } },
   iif: {
     args: ['condition', 'expression', 'expression'],
     // The union of the branch states; a missing else-branch contributes empty.
-    result: (_input, args) => unionStates([args[1], args[2] ?? { types: [], single: true }]),
+    result: { kind: 'union', sources: [1, 2], single: 'all' },
   },
   // not() takes anything a Boolean test accepts (0/1, single items), so no kind pin.
   not: { input: { singleton: true }, result: BOOLEAN },
@@ -158,7 +211,7 @@ export const FUNCTION_SIGNATURES: Readonly<Record<string, FunctionSignature>> =
   descendants: { result: UNKNOWN },
   // A reference resolves to its declared target types (Reference.targetProfile,
   // HAPI's TypeDetails.targets); an unconstrained reference stays unknown.
-  resolve: { result: input => ({ types: input.targets, single: input.single }) },
+  resolve: { result: { kind: 'reference-targets' } },
   extension: { args: ['String'], result: UNKNOWN },
   hasValue: { input: { singleton: true }, result: BOOLEAN },
   getValue: { input: { singleton: true }, result: UNKNOWN },
@@ -181,13 +234,13 @@ export const FUNCTION_SIGNATURES: Readonly<Record<string, FunctionSignature>> =
   replaceMatches: { input: { kind: 'String', singleton: true }, args: ['String', 'String'], result: STRING },
   toChars: {
     input: { kind: 'String', singleton: true },
-    result: () => ({ types: ['System.String'], single: false }),
+    result: { kind: 'fixed', types: ['System.String'], single: false },
   },
   trim: { input: { kind: 'String', singleton: true }, result: STRING },
   split: {
     input: { kind: 'String', singleton: true },
     args: ['String'],
-    result: () => ({ types: ['System.String'], single: false }),
+    result: { kind: 'fixed', types: ['System.String'], single: false },
   },
   join: { input: { kind: 'String' }, args: ['String'], result: STRING },
   encode: STRING_FN,
@@ -205,7 +258,9 @@ export const FUNCTION_SIGNATURES: Readonly<Record<string, FunctionSignature>> =
   sqrt: MATH_FN,
   log: { input: { kind: 'Numeric', singleton: true }, args: ['Numeric'], result: DECIMAL },
   power: { input: { kind: 'Numeric', singleton: true }, args: ['Numeric'], result: UNKNOWN },
-  aggregate: { args: ['expression', 'any'], result: UNKNOWN },
+  // Each iteration replaces the accumulator with the aggregator result. An
+  // empty input returns init, when supplied, so both arguments can contribute.
+  aggregate: { args: ['expression', 'any'], result: { kind: 'union', sources: [0, 1], single: 'all' } },
   sum: { input: { kind: 'Numeric' }, result: UNKNOWN },
   min: { input: { kind: 'Numeric' }, result: UNKNOWN },
   max: { input: { kind: 'Numeric' }, result: UNKNOWN },
@@ -214,16 +269,16 @@ export const FUNCTION_SIGNATURES: Readonly<Record<string, FunctionSignature>> =
 
   toBoolean: { input: { singleton: true }, result: BOOLEAN },
   toInteger: { input: { singleton: true }, result: INTEGER },
-  toLong: { input: { singleton: true }, result: () => ({ types: ['System.Long'], single: true }) },
+  toLong: { input: { singleton: true }, result: LONG },
   toDecimal: { input: { singleton: true }, result: DECIMAL },
   toString: { input: { singleton: true }, result: STRING },
-  toDate: { input: { singleton: true }, result: () => ({ types: ['System.Date'], single: true }) },
-  toDateTime: { input: { singleton: true }, result: () => ({ types: ['System.DateTime'], single: true }) },
-  toTime: { input: { singleton: true }, result: () => ({ types: ['System.Time'], single: true }) },
+  toDate: { input: { singleton: true }, result: DATE },
+  toDateTime: { input: { singleton: true }, result: DATETIME },
+  toTime: { input: { singleton: true }, result: TIME },
   toQuantity: {
     input: { singleton: true },
     args: ['String'],
-    result: () => ({ types: ['System.Quantity'], single: true }),
+    result: QUANTITY,
   },
   convertsToBoolean: { input: { singleton: true }, result: BOOLEAN },
   convertsToInteger: { input: { singleton: true }, result: BOOLEAN },
@@ -235,9 +290,9 @@ export const FUNCTION_SIGNATURES: Readonly<Record<string, FunctionSignature>> =
   convertsToTime: { input: { singleton: true }, result: BOOLEAN },
   convertsToQuantity: { input: { singleton: true }, args: ['String'], result: BOOLEAN },
 
-  now: { result: () => ({ types: ['System.DateTime'], single: true }) },
-  today: { result: () => ({ types: ['System.Date'], single: true }) },
-  timeOfDay: { result: () => ({ types: ['System.Time'], single: true }) },
+  now: { result: DATETIME },
+  today: { result: DATE },
+  timeOfDay: { result: TIME },
   yearOf: { input: { kind: 'Temporal', singleton: true }, result: INTEGER },
   monthOf: { input: { kind: 'Temporal', singleton: true }, result: INTEGER },
   dayOf: { input: { kind: 'Temporal', singleton: true }, result: INTEGER },
@@ -246,8 +301,8 @@ export const FUNCTION_SIGNATURES: Readonly<Record<string, FunctionSignature>> =
   secondOf: { input: { kind: 'Temporal', singleton: true }, result: INTEGER },
   millisecondOf: { input: { kind: 'Temporal', singleton: true }, result: INTEGER },
   timezoneOffsetOf: { input: { kind: 'Temporal', singleton: true }, result: DECIMAL },
-  dateOf: { input: { kind: 'Temporal', singleton: true }, result: () => ({ types: ['System.Date'], single: true }) },
-  timeOf: { input: { kind: 'Temporal', singleton: true }, result: () => ({ types: ['System.Time'], single: true }) },
+  dateOf: { input: { kind: 'Temporal', singleton: true }, result: DATE },
+  timeOf: { input: { kind: 'Temporal', singleton: true }, result: TIME },
   lowBoundary: { input: { singleton: true }, args: ['Numeric'], result: UNKNOWN },
   highBoundary: { input: { singleton: true }, args: ['Numeric'], result: UNKNOWN },
   precision: { input: { singleton: true }, result: INTEGER },
@@ -255,6 +310,9 @@ export const FUNCTION_SIGNATURES: Readonly<Record<string, FunctionSignature>> =
   // Variadic: the analyzer repeats the last arg spec for every position, so one
   // 'expression' entry covers all of coalesce's arguments. The result is the
   // first non-empty argument, hence the union of all of them.
-  coalesce: { args: ['expression'], result: (_input, args) => unionStates([...args]) },
+  coalesce: { args: ['expression'], result: { kind: 'arguments-union' } },
   type: { result: UNKNOWN },
-}
+} as const satisfies Readonly<Record<string, FunctionSignature>>
+
+export type FunctionSignatureName = keyof typeof FUNCTION_SIGNATURE_DEFINITIONS
+export const FUNCTION_SIGNATURES: Readonly<Record<string, FunctionSignature>> = FUNCTION_SIGNATURE_DEFINITIONS

package/src/api/compile.ts

@@ -18,9 +18,18 @@ import type { AstNode } from '../parser/ast.ts'
 import { parse } from '../parser/parser.ts'
 import { printExpression } from '../parser/printer.ts'
 import type { R4TypeOf } from '../r4/generated/type-maps.ts'
-import type { FhirpathInput, FhirpathResult, FhirpathResultIn, FhirTypeName } from '../typed/infer.ts'
+import type {
+  CheckedFhirpathOptionValues,
+  EmptyFhirpathTypeContext,
+  FhirpathInput,
+  FhirpathResultForContext,
+  FhirpathTypeContextOf,
+  FhirpathTypeDeclarations,
+  FhirTypeName,
+} from '../typed/infer.ts'
 import { toCollection, type TypedValue, unwrap } from '../values/typed-value.ts'
 import { LruCache } from './cache.ts'
+import { assertStrictExpression } from './strict.ts'
 
 /**
  * A native or expression-defined FHIRPath function. Native functions receive
@@ -36,12 +45,15 @@ export type SingleCustomFunction =
       criteria?: never
       /** Only an expression body reads `%name`; a native `fn` gets plain values. */
       env?: never
+      envTypes?: never
     })
   | {
       expression: AnyExpression
       signature?: CustomFunctionSignature
       /** Environment values available only while this expression body runs. */
       env?: Record<string, unknown>
+      /** Explicit types or refinements for this function-local environment. */
+      envTypes?: FhirpathTypeDeclarations
       /** Return one criteria Boolean. An empty body result becomes `false`. */
       criteria?: boolean
       fn?: never
@@ -57,6 +69,7 @@ export interface OverloadedCustomFunction {
   signature?: never
   criteria?: never
   env?: never
+  envTypes?: never
   minArity?: never
   maxArity?: never
 }
@@ -64,14 +77,20 @@ export interface OverloadedCustomFunction {
 export type CustomFunction = SingleCustomFunction | OverloadedCustomFunction
 
 export interface EvaluateOptions {
+  /** Run the static analyzer before evaluation and throw on every error diagnostic. Defaults to false. */
+  strict?: boolean
   /** Environment variables (`%name`), keyed with or without the leading `%`. */
   env?: Record<string, unknown>
+  /** Explicit types or refinements for environment values. */
+  envTypes?: FhirpathTypeDeclarations
   /**
    * FHIRPath bindings evaluated against the input in declaration order. They
    * keep FHIRPath types and may use `%context`, `env`, and earlier variables.
    * During projection they run once per row. A `TypedValue[]` binds directly.
    */
   vars?: Record<string, AnyExpression | readonly TypedValue[]>
+  /** Types for pre-resolved vars, or explicit overrides for expression vars. */
+  varTypes?: FhirpathTypeDeclarations
   model?: ModelProvider
   /** Clock for `now()`, `today()`, and `timeOfDay()`. Defaults to the current time. */
   now?: Date
@@ -91,6 +110,37 @@ export interface EvaluateOptions {
   regex?: RegexEngine
 }
 
+type CheckedOptionKeys<Options, Accepted> = string extends keyof Options
+  ? unknown
+  : keyof EvaluateOptions extends keyof Options
+    ? unknown
+    : Record<Exclude<keyof Options, keyof Accepted>, never>
+
+/**
+ * Keeps literal option declarations for inference and rejects unknown literal
+ * keys. Named extensions of the accepted options and index-signature records
+ * remain assignable.
+ */
+export type Declaring<Options extends object, Accepted extends EvaluateOptions = EvaluateOptions> = Accepted &
+  Options &
+  CheckedFhirpathOptionValues<Options> &
+  CheckedOptionKeys<Options, Accepted>
+
+/** Sentinel selecting built-in result inference instead of an explicit TResult. */
+export interface InferredExpressionResult {
+  readonly __inferredExpressionResult: unique symbol
+}
+
+/** The result of a compiled expression after applying its per-call static declarations. */
+export type CompiledExpressionResult<
+  Expr extends string,
+  TResult extends unknown[] | InferredExpressionResult,
+  Root extends string,
+  Options,
+> = TResult extends InferredExpressionResult
+  ? FhirpathResultForContext<Expr, Root, FhirpathTypeContextOf<Options>>
+  : Extract<TResult, unknown[]>
+
 /**
  * A parsed expression, reusable across inputs. Create via `compile()` or the
  * `fhirpath` tag: literal expressions carry inferred result and input types for
@@ -103,9 +153,10 @@ export interface EvaluateOptions {
 export class CompiledExpression<
   Expr extends string = string,
   TInput = FhirpathInput<Expr>,
-  TResult extends unknown[] = FhirpathResult<Expr>,
+  TResult extends unknown[] | InferredExpressionResult = InferredExpressionResult,
+  Root extends string = 'opaque',
 > {
-  readonly source: string
+  readonly source: Expr
   readonly ast: AstNode
 
   constructor(source: Expr) {
@@ -114,13 +165,17 @@ export class CompiledExpression<
   }
 
   /** Evaluate and unwrap results to plain JS values. */
-  evaluate(input?: TInput, options?: EvaluateOptions): TResult {
-    return this.evaluateTyped(input, options).map(unwrap) as TResult
+  evaluate<const Options extends object = EmptyFhirpathTypeContext>(
+    input?: TInput,
+    options?: Declaring<Options>
+  ): CompiledExpressionResult<Expr, TResult, Root, Options> {
+    return this.evaluateTyped(input, options).map(unwrap) as CompiledExpressionResult<Expr, TResult, Root, Options>
   }
 
   /** Evaluate keeping the internal typed representation (types, Decimal, Temporal). */
   evaluateTyped(input?: unknown, options?: EvaluateOptions): TypedValue[] {
     const root = toCollection(input)
+    assertStrictExpression(this.ast, root, options)
     return evaluateNode(this.ast, contextFactory(options)(root), root)
   }
 
@@ -139,12 +194,12 @@ export class CompiledExpression<
 export function compile<
   const Expr extends string,
   const Root extends FhirTypeName,
-  TResult extends unknown[] = FhirpathResultIn<Expr, Root>,
->(expression: Expr, inputType: Root): CompiledExpression<Expr, R4TypeOf[Root], TResult>
+  TResult extends unknown[] | InferredExpressionResult = InferredExpressionResult,
+>(expression: Expr, inputType: Root): CompiledExpression<Expr, R4TypeOf[Root], TResult, Root>
 export function compile<
   const Expr extends string,
   TInput = FhirpathInput<Expr>,
-  TResult extends unknown[] = FhirpathResult<Expr>,
+  TResult extends unknown[] | InferredExpressionResult = InferredExpressionResult,
 >(expression: Expr): CompiledExpression<Expr, TInput, TResult>
 export function compile(expression: string): CompiledExpression {
   // A declared input type is a compile-time and check-time declaration (see
@@ -152,9 +207,9 @@ export function compile(expression: string): CompiledExpression {
   return new CompiledExpression(expression)
 }
 
-/** An expression as text or already compiled, with any literal type. */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any literal-typed CompiledExpression
-export type AnyExpression = string | CompiledExpression<any>
+/** An expression as text or already compiled, with any literal, input, result, and root types. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts every CompiledExpression specialization
+export type AnyExpression = string | CompiledExpression<any, any, any, any>
 
 /** A pre-resolved `vars` value; Array.isArray alone cannot exclude readonly arrays for the checker. */
 function isResolvedCollection<T>(value: T | readonly TypedValue[]): value is readonly TypedValue[] {