@cavelang/solver 0.35.0 → 0.36.1

package/src/canonical-owned.ts

@@ -0,0 +1,186 @@
+import { createHash } from 'node:crypto'
+import type { Limits } from './adapter.ts'
+import * as Exact from './exact.ts'
+import type { Expression, Model, Rational } from './model.ts'
+import { model as validate } from './validate.ts'
+
+type Json = null | boolean | number | string | readonly Json[] | { readonly [key: string]: Json }
+
+const compareText = (left: string, right: string): number => left < right ? -1 : left > right ? 1 : 0
+
+const exact = (value: Rational): Json => Exact.rational(value)
+
+const canonicalNode = (input: Expression, resolved: WeakMap<Expression, Json>): Json => {
+  switch (input.kind) {
+    case 'literal':
+      if (input.sort === 'int') return { kind: input.kind, sort: input.sort, value: String(Exact.integer(input.value)) }
+      if (input.sort === 'real') return { kind: input.kind, sort: input.sort, value: exact(input.value) }
+      if (input.sort === 'enum') return { kind: input.kind, sort: input.sort, domain: input.domain, value: input.value }
+      return { kind: input.kind, sort: input.sort, value: input.value }
+    case 'variable': return { kind: input.kind, id: input.id }
+    case 'not':
+    case 'negate': return { kind: input.kind, value: resolved.get(input.value)! }
+    case 'and':
+    case 'or':
+    case 'add':
+    case 'multiply': {
+      const operands = input.operands.map(value => resolved.get(value)!)
+        .sort(compareCanonical)
+      return { kind: input.kind, operands }
+    }
+    case 'implies':
+    case 'subtract':
+    case 'divide':
+    case 'lt':
+    case 'lte':
+    case 'gt':
+    case 'gte':
+      return { kind: input.kind, left: resolved.get(input.left)!, right: resolved.get(input.right)! }
+    case 'eq':
+    case 'neq': {
+      const operands = [resolved.get(input.left)!, resolved.get(input.right)!]
+        .sort(compareCanonical)
+      return { kind: input.kind, left: operands[0]!, right: operands[1]! }
+    }
+    case 'if':
+      return { kind: input.kind, condition: resolved.get(input.condition)!, then: resolved.get(input.then)!, else: resolved.get(input.else)! }
+  }
+}
+
+const expression = (input: Expression, resolved: WeakMap<Expression, Json>): Json => {
+  const stack: { node: Expression, after: boolean }[] = [{ node: input, after: false }]
+  while (stack.length > 0) {
+    const { node, after } = stack.pop()!
+    if (resolved.has(node)) continue
+    if (after) {
+      resolved.set(node, canonicalNode(node, resolved))
+      continue
+    }
+    stack.push({ node, after: true })
+    const push = (value: Expression): void => { stack.push({ node: value, after: false }) }
+    switch (node.kind) {
+      case 'literal': case 'variable': break
+      case 'not': case 'negate': push(node.value); break
+      case 'and': case 'or': case 'add': case 'multiply':
+        for (let index = node.operands.length - 1; index >= 0; index--) push(node.operands[index]!)
+        break
+      case 'if': push(node.else); push(node.then); push(node.condition); break
+      default: push(node.right); push(node.left)
+    }
+  }
+  return resolved.get(input)!
+}
+
+function* tokens(value: Json): Generator<string> {
+  const stack: ({ value: Json } | { text: string })[] = [{ value }]
+  while (stack.length > 0) {
+    const item = stack.pop()!
+    if ('text' in item) { yield item.text; continue }
+    const current = item.value
+    if (current === null || typeof current !== 'object') { yield JSON.stringify(current); continue }
+    if (Array.isArray(current)) {
+      yield '['
+      stack.push({ text: ']' })
+      for (let index = current.length - 1; index >= 0; index--) {
+        stack.push({ value: current[index]! })
+        if (index > 0) stack.push({ text: ',' })
+      }
+    } else {
+      const record = current as Readonly<Record<string, Json>>
+      const keys = Object.keys(record).sort()
+      yield '{'
+      stack.push({ text: '}' })
+      for (let index = keys.length - 1; index >= 0; index--) {
+        const key = keys[index]!
+        stack.push({ value: record[key]! }, { text: `${JSON.stringify(key)}:` })
+        if (index > 0) stack.push({ text: ',' })
+      }
+    }
+  }
+}
+
+/** Keep complete JSON tokens together so UTF-8 encoding never splits a surrogate pair. */
+function* chunks(value: Json): Generator<string> {
+  let pending: string[] = []
+  let length = 0
+  for (const token of tokens(value)) {
+    pending.push(token)
+    length += token.length
+    if (length >= 65536) {
+      yield pending.join('')
+      pending = []
+      length = 0
+    }
+  }
+  if (pending.length > 0) yield pending.join('')
+}
+
+const stableStringify = (value: Json): string => [...chunks(value)].join('')
+
+/** Compare canonical text lazily instead of materializing each entire subtree. */
+const compareCanonical = (left: Json, right: Json): number => {
+  if (left === right) return 0
+  const leftTokens = tokens(left)
+  const rightTokens = tokens(right)
+  let a = leftTokens.next()
+  let b = rightTokens.next()
+  let at = 0
+  let bt = 0
+  while (!a.done && !b.done) {
+    const length = Math.min(a.value.length - at, b.value.length - bt)
+    const order = compareText(a.value.slice(at, at + length), b.value.slice(bt, bt + length))
+    if (order !== 0) return order
+    at += length
+    bt += length
+    if (at === a.value.length) { a = leftTokens.next(); at = 0 }
+    if (bt === b.value.length) { b = rightTokens.next(); bt = 0 }
+  }
+  return a.done ? (b.done ? 0 : -1) : 1
+}
+
+const byId = <T extends { readonly id: string }>(values: readonly T[]): readonly T[] =>
+  [...values].sort((left, right) => compareText(left.id, right.id))
+
+/** Private entrypoint: the caller owns the captured model and resolved limits. */
+const canonicalOwned = (input: Model, limits: Limits): Json => {
+  validate(input, limits)
+  const resolved = new WeakMap<Expression, Json>()
+  const canonical: Json = {
+    schema: input.schema,
+    enums: byId(input.enums ?? []).map(domain => ({ id: domain.id, values: [...domain.values].sort() })),
+    variables: byId(input.variables).map((variable): Json => {
+      switch (variable.sort) {
+        case 'bool': return { id: variable.id, sort: variable.sort }
+        case 'int': return { id: variable.id, sort: variable.sort, min: String(Exact.integer(variable.min)), max: String(Exact.integer(variable.max)) }
+        case 'real': return {
+          id: variable.id,
+          sort: variable.sort,
+          ...(variable.min === undefined ? {} : { min: exact(variable.min) }),
+          ...(variable.max === undefined ? {} : { max: exact(variable.max) })
+        }
+        case 'enum': return { id: variable.id, sort: variable.sort, domain: variable.domain }
+      }
+    }),
+    constraints: byId(input.constraints).map(constraint => ({ id: constraint.id, expression: expression(constraint.expression, resolved) })),
+    softConstraints: byId(input.softConstraints ?? []).map(constraint => ({
+      id: constraint.id,
+      expression: expression(constraint.expression, resolved),
+      weight: exact(constraint.weight)
+    })),
+    objectives: (input.objectives ?? []).map(objective => ({
+      id: objective.id,
+      direction: objective.direction,
+      expression: expression(objective.expression, resolved)
+    }))
+  }
+  return canonical
+}
+
+export const serializeOwned = (input: Model, limits: Limits): string =>
+  stableStringify(canonicalOwned(input, limits))
+
+export const digestOwned = (input: Model, limits: Limits): string => {
+  const hash = createHash('sha256')
+  for (const chunk of chunks(canonicalOwned(input, limits))) hash.update(chunk)
+  return `sha256:${hash.digest('hex')}`
+}

package/src/canonical.ts

@@ -1,94 +1,18 @@
-import { createHash } from 'node:crypto'
-import * as Exact from './exact.ts'
-import type { Expression, Model, Rational } from './model.ts'
-import { model as validate } from './validate.ts'
-
-type Json = null | boolean | number | string | readonly Json[] | { readonly [key: string]: Json }
-
-const compareText = (left: string, right: string): number => left < right ? -1 : left > right ? 1 : 0
-
-const exact = (value: Rational): Json => Exact.rational(value)
-
-const expression = (input: Expression): Json => {
-  switch (input.kind) {
-    case 'literal':
-      if (input.sort === 'int') return { kind: input.kind, sort: input.sort, value: String(Exact.integer(input.value)) }
-      if (input.sort === 'real') return { kind: input.kind, sort: input.sort, value: exact(input.value) }
-      if (input.sort === 'enum') return { kind: input.kind, sort: input.sort, domain: input.domain, value: input.value }
-      return { kind: input.kind, sort: input.sort, value: input.value }
-    case 'variable': return { kind: input.kind, id: input.id }
-    case 'not':
-    case 'negate': return { kind: input.kind, value: expression(input.value) }
-    case 'and':
-    case 'or':
-    case 'add':
-    case 'multiply': {
-      const operands = input.operands.map(expression)
-        .sort((left, right) => compareText(stableStringify(left), stableStringify(right)))
-      return { kind: input.kind, operands }
-    }
-    case 'implies':
-    case 'subtract':
-    case 'divide':
-    case 'lt':
-    case 'lte':
-    case 'gt':
-    case 'gte':
-      return { kind: input.kind, left: expression(input.left), right: expression(input.right) }
-    case 'eq':
-    case 'neq': {
-      const operands = [expression(input.left), expression(input.right)]
-        .sort((left, right) => compareText(stableStringify(left), stableStringify(right)))
-      return { kind: input.kind, left: operands[0]!, right: operands[1]! }
-    }
-    case 'if':
-      return { kind: input.kind, condition: expression(input.condition), then: expression(input.then), else: expression(input.else) }
-  }
-}
-
-const stableStringify = (value: Json): string => {
-  if (value === null || typeof value !== 'object') return JSON.stringify(value)
-  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`
-  const record = value as Readonly<Record<string, Json>>
-  return `{${Object.keys(record).sort().map(key => `${JSON.stringify(key)}:${stableStringify(record[key]!)}`).join(',')}}`
-}
-
-const byId = <T extends { readonly id: string }>(values: readonly T[]): readonly T[] =>
-  [...values].sort((left, right) => compareText(left.id, right.id))
+import { clone } from './clone.ts'
+import type { Limits } from './adapter.ts'
+import type { Model } from './model.ts'
+import { mergeLimits, model as validate } from './validate.ts'
+import { digestOwned, serializeOwned } from './canonical-owned.ts'
 
 /** Canonical semantic JSON. Descriptions and evidence links are deliberately not identity. */
-export const serialize = (input: Model): string => {
-  validate(input)
-  const canonical: Json = {
-    schema: input.schema,
-    enums: byId(input.enums ?? []).map(domain => ({ id: domain.id, values: [...domain.values].sort() })),
-    variables: byId(input.variables).map((variable): Json => {
-      switch (variable.sort) {
-        case 'bool': return { id: variable.id, sort: variable.sort }
-        case 'int': return { id: variable.id, sort: variable.sort, min: String(Exact.integer(variable.min)), max: String(Exact.integer(variable.max)) }
-        case 'real': return {
-          id: variable.id,
-          sort: variable.sort,
-          ...(variable.min === undefined ? {} : { min: exact(variable.min) }),
-          ...(variable.max === undefined ? {} : { max: exact(variable.max) })
-        }
-        case 'enum': return { id: variable.id, sort: variable.sort, domain: variable.domain }
-      }
-    }),
-    constraints: byId(input.constraints).map(constraint => ({ id: constraint.id, expression: expression(constraint.expression) })),
-    softConstraints: byId(input.softConstraints ?? []).map(constraint => ({
-      id: constraint.id,
-      expression: expression(constraint.expression),
-      weight: exact(constraint.weight)
-    })),
-    objectives: (input.objectives ?? []).map(objective => ({
-      id: objective.id,
-      direction: objective.direction,
-      expression: expression(objective.expression)
-    }))
-  }
-  return stableStringify(canonical)
+export const serialize = (input: Model, limits: Partial<Limits> = {}): string => {
+  const resolved = mergeLimits(limits)
+  validate(input, resolved)
+  return serializeOwned(clone(input), resolved)
 }
 
-export const digest = (input: Model): string =>
-  `sha256:${createHash('sha256').update(serialize(input)).digest('hex')}`
+export const digest = (input: Model, limits: Partial<Limits> = {}): string => {
+  const resolved = mergeLimits(limits)
+  validate(input, resolved)
+  return digestOwned(clone(input), resolved)
+}

package/src/capability.ts

@@ -13,40 +13,42 @@ export class UnsupportedModelError extends Error {
   }
 }
 
-const walk = (expression: Expression, visit: (expression: Expression) => void): void => {
-  visit(expression)
+const children = (expression: Expression): readonly Expression[] => {
   switch (expression.kind) {
-    case 'literal':
-    case 'variable': return
-    case 'not':
-    case 'negate': walk(expression.value, visit); return
-    case 'and':
-    case 'or':
-    case 'add':
-    case 'multiply': expression.operands.forEach(operand => walk(operand, visit)); return
-    case 'if':
-      walk(expression.condition, visit)
-      walk(expression.then, visit)
-      walk(expression.else, visit)
-      return
-    default:
-      walk(expression.left, visit)
-      walk(expression.right, visit)
+    case 'literal': case 'variable': return []
+    case 'not': case 'negate': return [expression.value]
+    case 'and': case 'or': case 'add': case 'multiply': return expression.operands
+    case 'if': return [expression.condition, expression.then, expression.else]
+    default: return [expression.left, expression.right]
   }
 }
 
-const hasNonlinearArithmetic = (expression: Expression): boolean => {
-  let nonlinear = false
-  const containsVariable = (candidate: Expression): boolean => {
-    let found = false
-    walk(candidate, node => { if (node.kind === 'variable') found = true })
-    return found
+const walk = (
+  expression: Expression,
+  visit: (expression: Expression) => void,
+  finish: (expression: Expression) => void
+): void => {
+  const active = new WeakSet<Expression>()
+  const complete = new WeakSet<Expression>()
+  const stack: { node: Expression, after: boolean }[] = [{ node: expression, after: false }]
+  while (stack.length > 0) {
+    const { node, after } = stack.pop()!
+    if (after) {
+      finish(node)
+      active.delete(node)
+      complete.add(node)
+      continue
+    }
+    if (active.has(node)) throw new TypeError('capability discovery received a cyclic expression')
+    if (complete.has(node)) continue
+    active.add(node)
+    visit(node)
+    stack.push({ node, after: true })
+    const operands = children(node)
+    for (let index = operands.length - 1; index >= 0; index--) {
+      stack.push({ node: operands[index]!, after: false })
+    }
   }
-  walk(expression, node => {
-    if (node.kind === 'multiply' && node.operands.filter(containsVariable).length > 1) nonlinear = true
-    if (node.kind === 'divide' && containsVariable(node.right)) nonlinear = true
-  })
-  return nonlinear
 }
 
 export const required = (model: Model, unsatCore = false): ReadonlySet<Capability> => {
@@ -67,13 +69,22 @@ export const required = (model: Model, unsatCore = false): ReadonlySet<Capabilit
     ...(model.objectives ?? []).map(objective => objective.expression)
   ]
   for (const expression of expressions) {
+    const containsVariable = new WeakMap<Expression, boolean>()
+    let nonlinear = false
     walk(expression, node => {
       if (node.kind === 'literal' && node.sort === 'int') result.add('integers')
       if (node.kind === 'literal' && node.sort === 'real') result.add('rationals')
+      // Portable division returns an exact real even when both operands are integers.
+      if (node.kind === 'divide') result.add('rationals')
       if (node.kind === 'literal' && node.sort === 'enum') result.add('finite-enums')
       if (node.kind === 'if') result.add('conditionals')
+    }, node => {
+      const operands = children(node)
+      if (node.kind === 'multiply' && operands.filter(value => containsVariable.get(value)).length > 1) nonlinear = true
+      if (node.kind === 'divide' && containsVariable.get(node.right)) nonlinear = true
+      containsVariable.set(node, node.kind === 'variable' || operands.some(value => containsVariable.get(value)))
     })
-    if (hasNonlinearArithmetic(expression)) result.add('nonlinear-arithmetic')
+    if (nonlinear) result.add('nonlinear-arithmetic')
   }
   return result
 }

package/src/clone.ts

@@ -0,0 +1,47 @@
+import { types } from 'node:util'
+
+/** Inspect descriptors without evaluating accessors or touching proxy traps. */
+const portable = (input: unknown): boolean => {
+  const pending: unknown[] = [input]
+  const seen = new WeakSet<object>()
+  while (pending.length > 0) {
+    const value = pending.pop()
+    if (typeof value === 'function' || typeof value === 'symbol') return false
+    if (value === null || typeof value !== 'object' || seen.has(value)) continue
+    if (types.isProxy(value)) return false
+    seen.add(value)
+    const prototype = Object.getPrototypeOf(value)
+    if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) return false
+    for (const key of Object.keys(value)) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key)!
+      if (!Object.hasOwn(descriptor, 'value')) return false
+      pending.push(descriptor.value)
+    }
+  }
+  return true
+}
+
+/** Copy portable records/arrays without native structured-clone recursion. */
+export const clone = <T>(input: T): T => {
+  if (!portable(input)) return structuredClone(input)
+  const copies = new WeakMap<object, object>()
+  const pending: { source: object, target: object }[] = []
+  const allocate = (value: unknown): unknown => {
+    if (value === null || typeof value !== 'object') return value
+    const previous = copies.get(value)
+    if (previous !== undefined) return previous
+    const target: object = Array.isArray(value) ? new Array(value.length) : {}
+    copies.set(value, target)
+    pending.push({ source: value, target })
+    return target
+  }
+  const result = allocate(input)
+  while (pending.length > 0) {
+    const { source, target } = pending.pop()!
+    for (const key of Object.keys(source)) {
+      const copied = allocate((source as Record<string, unknown>)[key])
+      Object.defineProperty(target, key, { value: copied, enumerable: true, writable: true, configurable: true })
+    }
+  }
+  return result as T
+}

package/src/constant-sign.ts

@@ -0,0 +1,59 @@
+import type { Expression } from './model.ts'
+import * as Exact from './exact.ts'
+import { evaluate } from './evaluate-expression.ts'
+
+export type Sign = -1 | 0 | 1 | undefined
+const addSigns = (left: Sign, right: Sign): Sign =>
+  left === undefined || right === undefined ? undefined : left === 0 ? right : right === 0 || left === right ? left : undefined
+
+/** Prove a constant's sign without constructing large rational intermediates. */
+function* signSteps(expression: Expression, literal: (value: Expression) => Exact.Normalized): Generator<Expression, Sign, Sign> {
+  switch (expression.kind) {
+    case 'literal': {
+      if (expression.sort !== 'int' && expression.sort !== 'real') return undefined
+      const value = literal(expression)
+      return value.numerator === '0' ? 0 : value.numerator.startsWith('-') ? -1 : 1
+    }
+    case 'negate': {
+      const sign = yield expression.value
+      return sign === undefined ? undefined : -sign as Sign
+    }
+    case 'add': {
+      let sign: Sign = 0
+      for (const operand of expression.operands) {
+        sign = addSigns(sign, yield operand)
+        if (sign === undefined) return undefined
+      }
+      return sign
+    }
+    case 'subtract': {
+      const left = yield expression.left
+      const right = yield expression.right
+      return addSigns(left, right === undefined ? undefined : -right as Sign)
+    }
+    case 'multiply': {
+      let sign: Sign = 1
+      for (const operand of expression.operands) {
+        const part = yield operand
+        sign = sign === undefined || part === undefined ? undefined : sign * part as Sign
+      }
+      return sign
+    }
+    case 'divide': {
+      const left = yield expression.left
+      const right = yield expression.right
+      return left === undefined || right === undefined || right === 0 ? undefined : left * right as Sign
+    }
+    default: return undefined
+  }
+}
+
+export const constantSign = (
+  expression: Expression,
+  cache: WeakMap<Expression, Sign>,
+  literal: (value: Expression) => Exact.Normalized = value => {
+    if (value.kind === 'literal' && value.sort === 'int') return Exact.rational(String(Exact.integer(value.value)))
+    if (value.kind === 'literal' && value.sort === 'real') return Exact.rational(value.value)
+    throw new TypeError('expected a numeric literal')
+  }
+): Sign => evaluate(expression, value => signSteps(value, literal), cache)

package/src/context.ts

@@ -0,0 +1,114 @@
+import type { Context } from './explain.ts'
+import { clone } from './clone.ts'
+
+const validateJson = (root: unknown, path: string): void => {
+  const active = new WeakSet<object>()
+  const completed = new WeakSet<object>()
+  const stack: { value: unknown, path: string, leave?: boolean }[] = [{ value: root, path }]
+  while (stack.length > 0) {
+    const frame = stack.pop()!
+    const value = frame.value
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') continue
+    if (typeof value === 'number' && Number.isFinite(value)) continue
+    if (typeof value !== 'object' || value === null) throw new TypeError(`${frame.path} must be a finite JSON value`)
+    if (frame.leave) { active.delete(value); completed.add(value); continue }
+    if (active.has(value)) throw new TypeError(`${frame.path} contains a JSON cycle`)
+    if (completed.has(value)) continue
+    if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) throw new TypeError(`${frame.path} must be a plain JSON object or array`)
+    if (typeof (value as { toJSON?: unknown }).toJSON === 'function') throw new TypeError(`${frame.path} must not use a custom JSON serializer`)
+    active.add(value)
+    stack.push({ ...frame, leave: true })
+    if (Array.isArray(value)) {
+      for (let index = value.length - 1; index >= 0; index--) {
+        if (!Object.hasOwn(value, index)) throw new TypeError(`${frame.path}[${index}] must not be a sparse JSON array entry`)
+        stack.push({ value: value[index], path: `${frame.path}[${index}]` })
+      }
+    } else {
+      for (const [key, child] of Object.entries(value)) {
+        if (child !== undefined) stack.push({ value: child, path: `${frame.path}.${key}` })
+      }
+    }
+  }
+}
+
+/** Serialize validated input values without depending on the engine's stack limit. */
+export const stringifyInput = (value: unknown): string => {
+  validateJson(value, 'explanation input value')
+  value = clone(value)
+  validateJson(value, 'explanation input value')
+  const output: string[] = []
+  const stack: ({ value: unknown } | { text: string })[] = [{ value }]
+  while (stack.length > 0) {
+    const frame = stack.pop()!
+    if ('text' in frame) { output.push(frame.text); continue }
+    const current = frame.value
+    if (current === null || typeof current !== 'object') {
+      output.push(JSON.stringify(current))
+      continue
+    }
+    if (Array.isArray(current)) {
+      output.push('[')
+      stack.push({ text: ']' })
+      for (let index = current.length - 1; index >= 0; index--) {
+        stack.push({ value: current[index] })
+        if (index > 0) stack.push({ text: ',' })
+      }
+    } else {
+      const entries = Object.entries(current).filter(([, child]) => child !== undefined)
+      output.push('{')
+      stack.push({ text: '}' })
+      for (let index = entries.length - 1; index >= 0; index--) {
+        const [key, child] = entries[index]!
+        stack.push({ value: child }, { text: `${JSON.stringify(key)}:` })
+        if (index > 0) stack.push({ text: ',' })
+      }
+    }
+  }
+  return output.join('')
+}
+
+/** Validate explanation metadata and bindings without resolving external IDs. */
+export const validateContext = (context: Context): void => {
+  if (context === null || typeof context !== 'object' || Array.isArray(context)) throw new TypeError('explanation context must be an object')
+  const nonempty = (value: unknown, path: string): void => {
+    if (typeof value !== 'string' || value.length === 0) throw new TypeError(`${path} must be a nonempty string`)
+  }
+  if (context.modelDigest !== undefined) nonempty(context.modelDigest, 'explanation modelDigest')
+  if (context.scenario !== undefined) {
+    const scenario = context.scenario
+    if (scenario === null || typeof scenario !== 'object' || Array.isArray(scenario)) throw new TypeError('explanation scenario must be an object')
+    for (const key of ['id', 'inputDigest', 'overlayDigest'] as const) nonempty(scenario[key], `explanation scenario.${key}`)
+  }
+  if (context.snapshot !== undefined) {
+    const snapshot = context.snapshot
+    if (snapshot === null || typeof snapshot !== 'object' || Array.isArray(snapshot)) throw new TypeError('explanation snapshot must be an object')
+    if (snapshot.transactionTime !== null) nonempty(snapshot.transactionTime, 'explanation snapshot.transactionTime')
+    if (snapshot.validTime !== undefined) nonempty(snapshot.validTime, 'explanation snapshot.validTime')
+    if (snapshot.aliases !== undefined && snapshot.aliases !== 'exact' && snapshot.aliases !== 'closure') throw new TypeError('explanation snapshot.aliases must be exact or closure')
+    if (snapshot.resolution !== undefined && snapshot.resolution !== 'coexisting' && snapshot.resolution !== 'winner') throw new TypeError('explanation snapshot.resolution must be coexisting or winner')
+    const confidence = snapshot.minimumConfidence
+    if (confidence !== undefined && (typeof confidence !== 'number' || !Number.isFinite(confidence) || confidence < 0 || confidence > 1)) throw new TypeError('explanation snapshot.minimumConfidence must be a finite number from 0 to 1')
+  }
+  if (context.inputs === undefined) return
+  if (!Array.isArray(context.inputs)) throw new TypeError('explanation inputs must be an array')
+  const ids = new Set<string>()
+  for (let index = 0; index < context.inputs.length; index++) {
+    const input = context.inputs[index]
+    const path = `explanation inputs[${index}]`
+    if (!Object.hasOwn(context.inputs, index) || input === null || typeof input !== 'object' || Array.isArray(input)) throw new TypeError(`${path} must be an input object`)
+    if (typeof input.id !== 'string' || input.id.length === 0) throw new TypeError(`${path}.id must be a nonempty string`)
+    if (ids.has(input.id)) throw new TypeError(`${path}.id duplicates ${JSON.stringify(input.id)}`)
+    ids.add(input.id)
+    for (const key of ['value', 'authoredValue'] as const) {
+      if (input[key] !== undefined) validateJson(input[key], `${path}.${key}`)
+    }
+    if (input.query !== undefined && typeof input.query !== 'string') throw new TypeError(`${path}.query must be a string`)
+    for (const key of ['evidenceRowIds', 'scenarioClaimIds'] as const) {
+      const values = input[key]
+      if (!Array.isArray(values)) throw new TypeError(`${path}.${key} must be an array`)
+      for (let item = 0; item < values.length; item++) {
+        if (!Object.hasOwn(values, item) || typeof values[item] !== 'string' || values[item].length === 0) throw new TypeError(`${path}.${key}[${item}] must be a nonempty string`)
+      }
+    }
+  }
+}

package/src/diagnostic-text.ts

@@ -0,0 +1,4 @@
+/** Keep malformed-input diagnostics small while retaining both ends and exact size. */
+export const diagnosticText = (input: string, quoteShort = true): string => input.length <= 160
+  ? (quoteShort ? JSON.stringify(input) : input)
+  : `${JSON.stringify(input.slice(0, 80))}…${JSON.stringify(input.slice(-80))} (${input.length} UTF-16 code units)`

package/src/evaluate-expression.ts

@@ -0,0 +1,21 @@
+import type { Expression } from './model.ts'
+
+/** Evaluate a captured expression with an explicit stack and caller-owned cache. */
+export const evaluate = <T>(expression: Expression, steps: (value: Expression) => Generator<Expression, T, T>, cache: WeakMap<Expression, T>): T => {
+  if (cache.has(expression)) return cache.get(expression)!
+  const stack = [{ expression, iterator: steps(expression) }]
+  let step = stack[0]!.iterator.next()
+  while (true) {
+    if (step.done) {
+      cache.set(stack.pop()!.expression, step.value)
+      if (stack.length === 0) return step.value
+      step = stack[stack.length - 1]!.iterator.next(step.value)
+    } else if (cache.has(step.value)) {
+      step = stack[stack.length - 1]!.iterator.next(cache.get(step.value)!)
+    } else {
+      const child = { expression: step.value, iterator: steps(step.value) }
+      stack.push(child)
+      step = child.iterator.next()
+    }
+  }
+}