fhirpath-ts 0.1.0 → 0.2.1

package/src/api/engine.ts

@@ -1,6 +1,13 @@
 import { mergeEnvKeys } from '../engine/context.ts'
 import type { R4TypeOf } from '../r4/generated/type-maps.ts'
-import type { FhirpathInput, FhirpathResult } from '../typed/infer.ts'
+import type {
+  EmptyFhirpathTypeContext,
+  FhirpathInput,
+  FhirpathResultForContext,
+  FhirpathRootOf,
+  FhirpathTypeContextOf,
+  MergeFhirpathTypeContexts,
+} from '../typed/infer.ts'
 import { criteriaBoolean } from '../values/collection.ts'
 import type { TypedValue } from '../values/typed-value.ts'
 import { type BundleLike, isBundle, normalizeInput, toSubjects } from './bundle.ts'
@@ -10,6 +17,7 @@ import {
   type Compiler,
   createCachedCompiler,
   type CustomFunction,
+  type Declaring,
   type EvaluateOptions,
   type SingleCustomFunction,
 } from './compile.ts'
@@ -30,6 +38,47 @@ export type EngineInput<Expr extends string = string> = FhirpathInput<Expr> | re
 /** Per-call options that declare a result type when inference returns `unknown`. Runtime code ignores `type`. */
 export type TypedEvaluateOptions<T extends keyof R4TypeOf> = EvaluateOptions & { type: T }
 
+/** Literal text or a compatible compiled expression accepted by engine evaluation methods. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- engine methods infer their own input and result
+export type EngineExpression<Expr extends string> = Expr | CompiledExpression<Expr, any, any, any>
+
+/**
+ * evaluate() reaches this shape through normalizeInput(), while project()
+ * reaches it through toSubjects(). A bare Bundle is expression-dependent or
+ * expands to heterogeneous entries, so it stays opaque; an array keeps each
+ * item raw, including a Bundle deliberately wrapped as `[bundle]`.
+ */
+export type EngineInputRoot<Input> = Input extends readonly (infer Item)[]
+  ? FhirpathRootOf<Item>
+  : Input extends { readonly resourceType: 'Bundle' }
+    ? 'opaque'
+    : FhirpathRootOf<Input>
+
+/** The inferred result returned by an engine or bound expression call. */
+export type EngineResult<Expr extends string, Input, Defaults, Options> = FhirpathResultForContext<
+  Expr,
+  EngineInputRoot<Input>,
+  MergeFhirpathTypeContexts<FhirpathTypeContextOf<Defaults>, FhirpathTypeContextOf<Options>>
+>
+
+/** The merged static declarations visible while project() evaluates a row. */
+export type EngineProjectionContext<Defaults, Options> = MergeFhirpathTypeContexts<
+  MergeFhirpathTypeContexts<FhirpathTypeContextOf<Defaults>, FhirpathTypeContextOf<Options>>,
+  {
+    env: {
+      rowIndex: { type: 'System.Integer' }
+      rowTotal: { type: 'System.Integer' }
+    }
+  }
+>
+
+/** The inferred row returned by project(), including its built-in row variables. */
+export type EngineProjection<Columns extends ProjectionColumns, Input, Defaults, Options> = Projection<
+  Columns,
+  EngineInputRoot<Input>,
+  EngineProjectionContext<Defaults, Options>
+>
+
 /** Engines created during the current recording session. */
 let session: FhirPathEngine[] | undefined
 
@@ -81,7 +130,7 @@ export interface EngineOptions extends EvaluateOptions {
  * replace defaults, while `env`, `vars`, and `functions` merge by name. Keep an
  * engine for reuse because its parse cache is private to that instance.
  */
-export class FhirPathEngine {
+export class FhirPathEngine<const Defaults extends EngineOptions = EmptyFhirpathTypeContext> {
   /** The per-call options bound at construction; engine-only settings are not part of them. */
   readonly defaults: EvaluateOptions
   /**
@@ -92,24 +141,29 @@ export class FhirPathEngine {
   readonly dtos: readonly DtoClass[]
   private readonly compileCached: Compiler
 
-  constructor({ cacheSize, resourceDtos, ...defaults }: EngineOptions = {}) {
+  constructor(options: Declaring<Defaults, EngineOptions> = {} as Declaring<Defaults, EngineOptions>) {
+    const { cacheSize, resourceDtos, ...defaults } = options
     this.compileCached = createCachedCompiler(cacheSize)
     this.dtos = resourceDtos ?? []
-    this.defaults = this.precompiled(withDtos(defaults, this.dtos, this.compileCached))
+    this.defaults = this.precompiled(withDtos(defaults as EvaluateOptions, this.dtos, this.compileCached))
     recordEngine(this)
   }
 
   /** Compile (LRU-cached by expression text) and evaluate in one call; typed like `compile().evaluate()`. */
   evaluate<const Expr extends string, T extends keyof R4TypeOf>(
-    expression: Expr | CompiledExpression<Expr>,
+    expression: EngineExpression<Expr>,
     input: EngineInput<Expr> | undefined,
     options: TypedEvaluateOptions<T>
   ): R4TypeOf[T][]
-  evaluate<const Expr extends string>(
-    expression: Expr | CompiledExpression<Expr>,
-    input?: EngineInput<Expr>,
-    options?: EvaluateOptions
-  ): FhirpathResult<Expr>
+  evaluate<
+    const Expr extends string,
+    const Input extends EngineInput<Expr> | undefined = undefined,
+    const Options extends object = EmptyFhirpathTypeContext,
+  >(
+    expression: EngineExpression<Expr>,
+    input?: Input,
+    options?: Declaring<Options>
+  ): EngineResult<Expr, Input, Defaults, Options>
   evaluate(expression: AnyExpression, input?: unknown, options?: EvaluateOptions): unknown[] {
     const compiled = this.compileCached(expression)
     const merged = this.merged(options)
@@ -124,21 +178,25 @@ export class FhirPathEngine {
   }
 
   /** Parse once for reuse, with this engine's defaults bound. Does not touch the parse cache. */
-  compile<const Expr extends string>(expression: Expr): BoundExpression<Expr> {
+  compile<const Expr extends string>(expression: Expr): BoundExpression<Expr, Defaults> {
     return new BoundExpression(this, new CompiledExpression(expression))
   }
 
   /** The first result, or undefined when the expression comes up empty. */
   first<const Expr extends string, T extends keyof R4TypeOf>(
-    expression: Expr | CompiledExpression<Expr>,
+    expression: EngineExpression<Expr>,
     input: EngineInput<Expr> | undefined,
     options: TypedEvaluateOptions<T>
   ): R4TypeOf[T] | undefined
-  first<const Expr extends string>(
-    expression: Expr | CompiledExpression<Expr>,
-    input?: EngineInput<Expr>,
-    options?: EvaluateOptions
-  ): FhirpathResult<Expr>[number] | undefined
+  first<
+    const Expr extends string,
+    const Input extends EngineInput<Expr> | undefined = undefined,
+    const Options extends object = EmptyFhirpathTypeContext,
+  >(
+    expression: EngineExpression<Expr>,
+    input?: Input,
+    options?: Declaring<Options>
+  ): EngineResult<Expr, Input, Defaults, Options>[number] | undefined
   first(expression: AnyExpression, input?: unknown, options?: EvaluateOptions): unknown {
     return this.evaluate(expression, input, options)[0]
   }
@@ -180,16 +238,16 @@ export class FhirPathEngine {
     options?: EvaluateOptions
   ): InstanceType<C>[]
   project<C extends DtoClass>(input: unknown, dto: C, options?: EvaluateOptions): InstanceType<C>
-  project<const Columns extends ProjectionColumns>(
-    input: readonly unknown[] | BundleLike,
-    columns: Columns,
-    options?: EvaluateOptions
-  ): Projection<Columns>[]
-  project<const Columns extends ProjectionColumns>(
-    input: unknown,
-    columns: Columns,
-    options?: EvaluateOptions
-  ): Projection<Columns>
+  project<
+    const Input extends readonly unknown[] | BundleLike,
+    const Columns extends ProjectionColumns,
+    const Options extends object = EmptyFhirpathTypeContext,
+  >(input: Input, columns: Columns, options?: Declaring<Options>): EngineProjection<Columns, Input, Defaults, Options>[]
+  project<
+    const Input,
+    const Columns extends ProjectionColumns,
+    const Options extends object = EmptyFhirpathTypeContext,
+  >(input: Input, columns: Columns, options?: Declaring<Options>): EngineProjection<Columns, Input, Defaults, Options>
   project(input: unknown, columns: ProjectionColumns | DtoClass, options?: EvaluateOptions): unknown {
     if (typeof columns === 'function') {
       assertInputMatchesDto(input, columns)
@@ -282,16 +340,16 @@ export class FhirPathEngine {
 }
 
 /** A compiled expression carrying an engine's defaults, so `evaluate(input)` needs nothing else. */
-export class BoundExpression<Expr extends string = string> {
+export class BoundExpression<Expr extends string = string, Defaults extends EngineOptions = EmptyFhirpathTypeContext> {
   readonly expression: CompiledExpression<Expr>
-  private readonly engine: FhirPathEngine
+  private readonly engine: FhirPathEngine<Defaults>
 
-  constructor(engine: FhirPathEngine, expression: CompiledExpression<Expr>) {
+  constructor(engine: FhirPathEngine<Defaults>, expression: CompiledExpression<Expr>) {
     this.engine = engine
     this.expression = expression
   }
 
-  get source(): string {
+  get source(): Expr {
     return this.expression.source
   }
 
@@ -299,7 +357,10 @@ export class BoundExpression<Expr extends string = string> {
     input: EngineInput<Expr> | undefined,
     options: TypedEvaluateOptions<T>
   ): R4TypeOf[T][]
-  evaluate(input?: EngineInput<Expr>, options?: EvaluateOptions): FhirpathResult<Expr>
+  evaluate<
+    const Input extends EngineInput<Expr> | undefined = undefined,
+    const Options extends object = EmptyFhirpathTypeContext,
+  >(input?: Input, options?: Declaring<Options>): EngineResult<Expr, Input, Defaults, Options>
   evaluate(input?: EngineInput<Expr>, options?: EvaluateOptions): unknown {
     return this.engine.evaluate(this.expression, input, options)
   }
@@ -312,7 +373,10 @@ export class BoundExpression<Expr extends string = string> {
     input: EngineInput<Expr> | undefined,
     options: TypedEvaluateOptions<T>
   ): R4TypeOf[T] | undefined
-  first(input?: EngineInput<Expr>, options?: EvaluateOptions): FhirpathResult<Expr>[number] | undefined
+  first<
+    const Input extends EngineInput<Expr> | undefined = undefined,
+    const Options extends object = EmptyFhirpathTypeContext,
+  >(input?: Input, options?: Declaring<Options>): EngineResult<Expr, Input, Defaults, Options>[number] | undefined
   first(input?: EngineInput<Expr>, options?: EvaluateOptions): unknown {
     return this.engine.first(this.expression, input, options)
   }

package/src/api/project.ts

@@ -2,11 +2,12 @@ import { type EvaluationContext, forkVariables } from '../engine/context.ts'
 import { evaluateNode } from '../engine/evaluator.ts'
 import { FhirPathRuntimeError } from '../errors.ts'
 import type { R4TypeOf } from '../r4/generated/type-maps.ts'
-import type { FhirpathResultIn } from '../typed/infer.ts'
+import type { EmptyFhirpathTypeContext, FhirpathResultForContext } from '../typed/infer.ts'
 import { criteriaBoolean } from '../values/collection.ts'
 import { toCollection, type TypedValue, unwrap } from '../values/typed-value.ts'
 import { toSubjects } from './bundle.ts'
 import { type Compiler, contextFactory, type EvaluateOptions } from './compile.ts'
+import { assertStrictExpression } from './strict.ts'
 
 /**
  * One `project()` column. A string or `{ path }` returns one optional value.
@@ -38,7 +39,9 @@ type ColumnPath<Column> = Column extends string
     : never
 
 /** Infers the values after the selected conversion, or from the path when no conversion is set. */
-type ColumnValues<Column, Root extends string> = Column extends { as: (value: never) => infer R }
+type ColumnValues<Column, Root extends string, Context extends object> = Column extends {
+  as: (value: never) => infer R
+}
   ? R[]
   : Column extends { as: 'Date' }
     ? Date[]
@@ -52,25 +55,30 @@ type ColumnValues<Column, Root extends string> = Column extends { as: (value: ne
           ? V[]
           : Column extends { type: infer T extends keyof R4TypeOf }
             ? R4TypeOf[T][]
-            : FhirpathResultIn<ColumnPath<Column>, Root>
+            : FhirpathResultForContext<ColumnPath<Column>, Root, Context>
 
 /** A column's output type. A default replaces `undefined`; a collection returns every value. */
 export type ColumnResult<
   Column extends string | { path: string } | { test: string },
   Root extends string = 'opaque',
+  Context extends object = EmptyFhirpathTypeContext,
 > = Column extends {
   test: string
 }
   ? boolean
   : Column extends { collection: true }
-    ? ColumnValues<Column, Root>
+    ? ColumnValues<Column, Root, Context>
     : Column extends { default: infer D }
-      ? ColumnValues<Column, Root>[number] | D
-      : ColumnValues<Column, Root>[number] | undefined
+      ? ColumnValues<Column, Root, Context>[number] | D
+      : ColumnValues<Column, Root, Context>[number] | undefined
 
 /** The row shape `project()` produces: each column's type inferred from its expression. */
-export type Projection<Columns extends ProjectionColumns, Root extends string = 'opaque'> = {
-  -readonly [K in keyof Columns]: ColumnResult<Columns[K], Root>
+export type Projection<
+  Columns extends ProjectionColumns,
+  Root extends string = 'opaque',
+  Context extends object = EmptyFhirpathTypeContext,
+> = {
+  -readonly [K in keyof Columns]: ColumnResult<Columns[K], Root, Context>
 }
 
 /** The `as: 'Date'` coercion; a value that is not a parseable date string becomes empty. */
@@ -183,6 +191,11 @@ function assertShaperOptions(name: string, spec: Extract<ProjectionColumn, { pat
  */
 type ColumnReader = (root: TypedValue[], context: EvaluationContext, at: RowPosition) => unknown
 
+interface PlannedColumn {
+  ast: ReturnType<Compiler>['ast']
+  read: ColumnReader
+}
+
 /** Where a row sits in the batch, for the errors that need to point at one of many. */
 interface RowPosition {
   index: number
@@ -199,32 +212,38 @@ function inRow({ index, total }: RowPosition): string {
 }
 
 /** Take the column union apart once, at plan time; rows only run the result. */
-function planColumn(name: string, column: ProjectionColumn, compile: Compiler): ColumnReader {
+function planColumn(name: string, column: ProjectionColumn, compile: Compiler): PlannedColumn {
   if (typeof column !== 'string' && 'test' in column) {
     const criteria = compile(column.test)
-    return (root, context) => criteriaBoolean(evaluateNode(criteria.ast, forkVariables(context), root))
+    return {
+      ast: criteria.ast,
+      read: (root, context) => criteriaBoolean(evaluateNode(criteria.ast, forkVariables(context), root)),
+    }
   }
   const spec: Extract<ProjectionColumn, { path: string }> = typeof column === 'string' ? { path: column } : column
   assertShaperOptions(name, spec)
   const expression = compile(spec.path)
   const applyAs = coercion(spec)
   const empty = 'default' in spec ? spec.default : undefined
-  return (root, context, at) => {
-    const values = evaluateNode(expression.ast, forkVariables(context), root).map(unwrap)
-    if (spec.collection === true) {
-      return applyAs(values)
-    }
-    // The scalar-column rule counts the expression's values, before any `as`
-    // coercion or `choices` miss drops them. One row of a batch can be the only
-    // one that breaks it, so the message says which — `%rowIndex` numbering,
-    // the same the columns see.
-    if (values.length > 1) {
-      throw new FhirPathRuntimeError(
-        `project(): column '${name}' yielded ${values.length} values${inRow(at)}; append first() or set collection: true`
-      )
-    }
-    const coerced = applyAs(values)
-    return coerced.length > 0 ? coerced[0] : empty
+  return {
+    ast: expression.ast,
+    read: (root, context, at) => {
+      const values = evaluateNode(expression.ast, forkVariables(context), root).map(unwrap)
+      if (spec.collection === true) {
+        return applyAs(values)
+      }
+      // The scalar-column rule counts the expression's values, before any `as`
+      // coercion or `choices` miss drops them. One row of a batch can be the only
+      // one that breaks it, so the message says which — `%rowIndex` numbering,
+      // the same the columns see.
+      if (values.length > 1) {
+        throw new FhirPathRuntimeError(
+          `project(): column '${name}' yielded ${values.length} values${inRow(at)}; append first() or set collection: true`
+        )
+      }
+      const coerced = applyAs(values)
+      return coerced.length > 0 ? coerced[0] : empty
+    },
   }
 }
 
@@ -239,16 +258,21 @@ export function projectRows(
   options: EvaluateOptions,
   compile: Compiler
 ): Record<string, unknown>[] {
-  const readers = Object.entries(columns).map(([name, column]) => [name, planColumn(name, column, compile)] as const)
+  const planned = Object.entries(columns).map(([name, column]) => [name, planColumn(name, column, compile)] as const)
   const makeContext = contextFactory(options)
   const subjects = toSubjects(input)
   return subjects.map((subject, index) => {
     const root = toCollection(subject.value)
     const at: RowPosition = { index, total: subjects.length }
-    const context = makeContext(root, { rowIndex: index, rowTotal: subjects.length })
+    const rowEnv = { rowIndex: index, rowTotal: subjects.length }
+    const strictOptions = options.strict === true ? { ...options, env: { ...options.env, ...rowEnv } } : options
+    for (const [, column] of planned) {
+      assertStrictExpression(column.ast, root, strictOptions)
+    }
+    const context = makeContext(root, rowEnv)
     const row: Record<string, unknown> = {}
-    for (const [name, read] of readers) {
-      row[name] = read(root, context, at)
+    for (const [name, column] of planned) {
+      row[name] = column.read(root, context, at)
     }
     return row
   })

package/src/api/strict.ts

@@ -0,0 +1,112 @@
+import {
+  type AnalyzerDiagnostic,
+  type AnalyzerRoot,
+  analyzeRuntimeAstDetailed,
+  type RuntimeAnalyzeOptions,
+} from '../analyzer/analyze.ts'
+import {
+  analyzerVariable,
+  type AnalyzerVariableState,
+  runtimeAnalyzerEnvironmentVariables,
+  runtimeAnalyzerVariable,
+} from '../analyzer/declarations.ts'
+import { normalizeEnvKeys } from '../engine/context.ts'
+import { FhirPathTypeError } from '../errors.ts'
+import type { ModelProvider } from '../model/provider.ts'
+import type { AstNode } from '../parser/ast.ts'
+import { parse } from '../parser/parser.ts'
+import type { TypedValue } from '../values/typed-value.ts'
+import type { AnyExpression, EvaluateOptions } from './compile.ts'
+
+interface StrictFinding {
+  diagnostic: AnalyzerDiagnostic
+  subject?: string
+}
+
+/** Reject every error-severity analyzer finding before strict evaluation begins. */
+export function assertStrictExpression(ast: AstNode, root: TypedValue[], options: EvaluateOptions | undefined): void {
+  if (options?.strict !== true) {
+    return
+  }
+
+  const model = options.model
+  const analyzerRoot = runtimeRoot(root, model)
+  const variables: Record<string, AnalyzerVariableState> = runtimeAnalyzerEnvironmentVariables(
+    options.env,
+    options.envTypes,
+    model
+  )
+  const declarations = normalizeEnvKeys(options.varTypes)
+  const findings: StrictFinding[] = []
+
+  for (const [name, value] of Object.entries(normalizeEnvKeys(options.vars))) {
+    const declaration = declarations[name]
+    if (isResolvedCollection(value)) {
+      variables[name] = runtimeAnalyzerVariable(value, model, declaration)
+      continue
+    }
+
+    const details = analyzeRuntimeAstDetailed(astOf(value), analyzerOptions(options, variables), analyzerRoot)
+    findings.push(
+      ...details.diagnostics
+        .filter(diagnostic => diagnostic.severity === 'error')
+        .map(diagnostic => ({ diagnostic, subject: `vars.${name}` }))
+    )
+    variables[name] =
+      declaration === undefined
+        ? {
+            ...(details.result.types !== undefined && { types: details.result.types }),
+            ...(details.result.single !== undefined && { single: details.result.single }),
+          }
+        : analyzerVariable(declaration)
+  }
+
+  for (const [name, declaration] of Object.entries(declarations)) {
+    variables[name] ??= analyzerVariable(declaration)
+  }
+
+  const details = analyzeRuntimeAstDetailed(ast, analyzerOptions(options, variables), analyzerRoot)
+  findings.push(
+    ...details.diagnostics.filter(diagnostic => diagnostic.severity === 'error').map(diagnostic => ({ diagnostic }))
+  )
+
+  if (findings.length > 0) {
+    throw new FhirPathTypeError(formatFindings(findings))
+  }
+}
+
+function analyzerOptions(
+  options: EvaluateOptions,
+  variables: Record<string, AnalyzerVariableState>
+): RuntimeAnalyzeOptions {
+  return {
+    ...(options.model !== undefined && { model: options.model }),
+    ...(options.functions !== undefined && { functions: options.functions }),
+    variables,
+  }
+}
+
+function runtimeRoot(root: TypedValue[], model: ModelProvider | undefined): AnalyzerRoot {
+  const variable = runtimeAnalyzerVariable(root, model)
+  return {
+    types: variable.types,
+    single: variable.single,
+    exactTypes: variable.exactTypes,
+  }
+}
+
+function isResolvedCollection(value: AnyExpression | readonly TypedValue[]): value is readonly TypedValue[] {
+  return Array.isArray(value)
+}
+
+function astOf(expression: AnyExpression): AstNode {
+  return typeof expression === 'string' ? parse(expression) : expression.ast
+}
+
+function formatFindings(findings: StrictFinding[]): string {
+  const lines = findings.map(({ diagnostic, subject }) => {
+    const prefix = subject === undefined ? '' : `${subject}: `
+    return `- [${diagnostic.code}] ${prefix}${diagnostic.message} (line ${diagnostic.span.line}, column ${diagnostic.span.column})`
+  })
+  return `Strict evaluation failed:\n${lines.join('\n')}`
+}

package/src/api/tagged.ts

@@ -1,7 +1,7 @@
 import { FhirPathError } from '../errors.ts'
 import type { R4TypeOf } from '../r4/generated/type-maps.ts'
-import type { FhirpathInput, FhirpathResult, FhirpathResultIn, FhirTypeName } from '../typed/infer.ts'
-import { CompiledExpression } from './compile.ts'
+import type { FhirpathInput, FhirTypeName } from '../typed/infer.ts'
+import { CompiledExpression, type InferredExpressionResult } from './compile.ts'
 
 /**
  * Compiles a FHIRPath expression. The call form infers supported literal
@@ -13,12 +13,12 @@ import { CompiledExpression } from './compile.ts'
 export function fhirpath<
   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 fhirpath<
   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 fhirpath(strings: TemplateStringsArray, ...substitutions: never[]): CompiledExpression
 export function fhirpath(input: string | TemplateStringsArray, ...rest: unknown[]): CompiledExpression {

package/src/cli/dto-check.ts

@@ -79,9 +79,10 @@ function analyzeFor(dto: DtoClass, engines: readonly FhirPathEngine[]): DtoDiagn
 }
 
 /**
- * Every engine's context as one: the union of their registered functions and env
- * names. The first engine's `model` stands for all of them — a project binds one
- * FHIR version, and an unregistered DTO names no engine that could pick another.
+ * Every engine's context as one: the union of their registered functions,
+ * environment declarations, and vars. The first engine's `model` stands for
+ * all of them — a project binds one FHIR version, and an unregistered DTO names
+ * no engine that could pick another.
  */
 function merged(engines: readonly FhirPathEngine[]): AnalyzedContext {
   return {
@@ -89,6 +90,9 @@ function merged(engines: readonly FhirPathEngine[]): AnalyzedContext {
       ...engines[0]?.defaults,
       functions: Object.assign({}, ...engines.map(engine => engine.defaults.functions)),
       env: Object.assign({}, ...engines.map(engine => engine.defaults.env)),
+      envTypes: Object.assign({}, ...engines.map(engine => engine.defaults.envTypes)),
+      vars: Object.assign({}, ...engines.map(engine => engine.defaults.vars)),
+      varTypes: Object.assign({}, ...engines.map(engine => engine.defaults.varTypes)),
     },
   }
 }

package/src/engine/context.ts

@@ -157,16 +157,21 @@ export const BUILTIN_ENV_VARIABLE_NAMES: ReadonlySet<string> = new Set([
   'rootResource',
 ])
 
+/** The canonical key used for environment and variable maps. */
+export function bareEnvironmentName(name: string): string {
+  return name.startsWith('%') ? name.slice(1) : name
+}
+
 /**
  * Env records accept variable names with or without the leading `%`
  * (`{ '%loinc': … }` or `{ loinc: … }`). Normalize to bare names — the form the
  * context binds — so code that merges or overrides env records treats both
  * spellings as one namespace. Later entries win on the same bare name.
  */
-export function normalizeEnvKeys<T>(env: Record<string, T> | undefined): Record<string, T> {
+export function normalizeEnvKeys<T>(env: Readonly<Record<string, T>> | undefined): Record<string, T> {
   const normalized: Record<string, T> = {}
   for (const [name, value] of Object.entries(env ?? {})) {
-    normalized[name.startsWith('%') ? name.slice(1) : name] = value
+    normalized[bareEnvironmentName(name)] = value
   }
   return normalized
 }

package/src/engine/navigation.ts

@@ -1,6 +1,6 @@
-import { FhirPathTypeError } from '../errors.ts'
 import { readModelProperty } from '../fhir/model-navigation.ts'
-import { OBJECT_TYPE, toTypedValue, type TypedValue } from '../values/typed-value.ts'
+import { rootTypeMatches } from '../values/type-compat.ts'
+import { toTypedValue, type TypedValue } from '../values/typed-value.ts'
 import type { EvaluationContext } from './context.ts'
 
 /**
@@ -11,22 +11,15 @@ import type { EvaluationContext } from './context.ts'
 export function navigateIdentifier(context: EvaluationContext, name: string, input: TypedValue[]): TypedValue[] {
   const results: TypedValue[] = []
   for (const item of input) {
-    if (matchesTypeName(context, item, name)) {
+    if (rootTypeMatches(context.model, item.type, name)) {
       results.push(item)
     } else if (context.model && item.type.startsWith(`${context.model.namespace}.`)) {
       const modelRead = readModelProperty(context.model, item, name)
       if (modelRead === undefined) {
-        // Choice elements go by stem name; a suffixed key like Observation.valueQuantity
-        // is the one unknown-element shape the official suites require to error at
-        // runtime. Everything else is the static analyzer's job (spec §11) — plain
-        // unknown elements navigate to empty, and types the model has never heard of
-        // (custom resourceTypes) read like raw JSON.
-        // See: https://hl7.org/fhirpath/en/index.html#type-safety-and-strict-evaluation
-        if (isChoiceKeyMisuse(context, item.type, name)) {
-          throw new FhirPathTypeError(
-            `Element '${name}' is not defined on ${item.type}; choice elements use their stem name`
-          )
-        }
+        // Unknown model elements navigate to empty. Strict evaluation runs the
+        // analyzer before reaching this point, including for choice-key misuse.
+        // Types the model has never heard of (custom resourceTypes) still read
+        // like raw JSON.
         if (
           name === 'resourceType' ||
           (context.model.listElements !== undefined && context.model.listElements(item.type) === undefined)
@@ -46,44 +39,6 @@ export function navigateIdentifier(context: EvaluationContext, name: string, inp
   return results
 }
 
-/** True for `valueQuantity`-style keys whose stem is a choice element of the type. */
-function isChoiceKeyMisuse(context: EvaluationContext, type: string, name: string): boolean {
-  const model = context.model as NonNullable<EvaluationContext['model']>
-  for (let position = 1; position < name.length; position++) {
-    if (!/[A-Z]/.test(name[position] as string)) {
-      continue
-    }
-    const stem = name.slice(0, position)
-    if (model.getElement(type, stem)?.isChoice === true) {
-      return true
-    }
-  }
-  return false
-}
-
-function matchesTypeName(context: EvaluationContext, item: TypedValue, name: string): boolean {
-  // Only the namespace strips off: the backbone type FHIR.ValueSet.expansion.contains
-  // must not answer to the element name 'contains'. Lowercase primitive type names
-  // (FHIR.code) never self-match either — `children().code` means the element.
-  if (!/^[A-Z]/.test(name)) {
-    // Lowercase names are always elements: `children().code` never filters by the
-    // primitive type FHIR.code.
-    return false
-  }
-  const separator = item.type.indexOf('.')
-  const local = separator === -1 ? item.type : item.type.slice(separator + 1)
-  if (local === name && item.type !== OBJECT_TYPE) {
-    return true
-  }
-  if (context.model) {
-    const canonical = context.model.resolveType(name)
-    if (canonical !== undefined) {
-      return context.model.isSubtypeOf(item.type, canonical)
-    }
-  }
-  return false
-}
-
 /** Read one child element from a complex value, flattening arrays. Missing → empty. */
 export function getProperty(item: TypedValue, name: string): TypedValue[] {
   const value = item.value