@cavelang/solver 0.35.0 → 0.36.0

package/src/expression-key.ts

@@ -0,0 +1,45 @@
+import type { Expression } from './model.ts'
+
+/** Ordered syntax identity for an already captured, validated expression.
+ * Unlike model canonicalization, this preserves operand order and literal
+ * representation because local evaluation can fail before later operands run.
+ * The string-ID table must share the evaluation cache's report lifetime.
+ */
+export const expressionKey = (expression: Expression, strings: Map<string, number>): string => {
+  const intern = (value: string): number => {
+    let id = strings.get(value)
+    if (id === undefined) {
+      id = strings.size
+      strings.set(value, id)
+    }
+    return id
+  }
+  const parts: string[] = []
+  const pending = [expression]
+  while (pending.length > 0) {
+    const node = pending.pop()!
+    switch (node.kind) {
+      case 'literal': {
+        const value = node.sort === 'enum' ? intern(node.value) : node.sort === 'real' && typeof node.value === 'object'
+          ? [node.value.numerator, node.value.denominator] : node.value
+        parts.push(JSON.stringify([node.kind, node.sort, node.sort === 'enum' ? intern(node.domain) : null, value]))
+        break
+      }
+      case 'variable': {
+        parts.push(JSON.stringify([node.kind, intern(node.id)]))
+        break
+      }
+      case 'not': case 'negate':
+        parts.push(node.kind); pending.push(node.value); break
+      case 'and': case 'or': case 'add': case 'multiply':
+        parts.push(JSON.stringify([node.kind, node.operands.length]))
+        for (let index = node.operands.length - 1; index >= 0; index--) pending.push(node.operands[index]!)
+        break
+      case 'if':
+        parts.push(node.kind); pending.push(node.else, node.then, node.condition); break
+      default:
+        parts.push(node.kind); pending.push(node.right, node.left)
+    }
+  }
+  return parts.join('\n')
+}

package/src/fraction-product.ts

@@ -0,0 +1,10 @@
+import { gcd } from './integer-gcd.ts'
+/** Cancel across factors before allocating a rational product's intermediates. */
+export const product = (a: bigint, b: bigint, c: bigint, d: bigint): readonly [bigint, bigint] => {
+  // Leave zero-denominator diagnostics to the caller's existing normalizer.
+  if (b === 0n || d === 0n) return [0n, 0n]
+  if (a === 0n || c === 0n) return [0n, 1n]
+  const left = gcd(a, d)
+  const right = gcd(c, b)
+  return [(a / left) * (c / right), (b / right) * (d / left)]
+}

package/src/fraction-sum.ts

@@ -0,0 +1,20 @@
+const probeThreshold = 1n << 1024n
+
+/** Avoid repeated large denominator factors when a short Euclidean probe finds them. */
+export const sum = (a: bigint, b: bigint, c: bigint, d: bigint): readonly [bigint, bigint] => {
+  if (b === d) return [a + c, b]
+  let x = b < 0n ? -b : b
+  let y = d < 0n ? -d : d
+  if (x >= probeThreshold && y >= probeThreshold) {
+    if (x < y) [x, y] = [y, x]
+    // A full GCD can cost more than the products it avoids for coprime inputs.
+    // An unfinished probe leaves the ordinary exact addition unchanged.
+    for (let step = 0; step < 6 && y !== 0n; step++) [x, y] = [y, x % y]
+    if (y === 0n && x > 1n) {
+      const leftScale = d / x
+      const rightScale = b / x
+      return [a * leftScale + c * rightScale, b * leftScale]
+    }
+  }
+  return [a * d + c * b, b * d]
+}

package/src/integer-gcd.ts

@@ -0,0 +1,47 @@
+const batchThreshold = 1n << 1024n
+
+/** Exact nonnegative GCD, with Lehmer batches for large operands. */
+export const gcd = (left: bigint, right: bigint): bigint => {
+  let a = left < 0n ? -left : left
+  let b = right < 0n ? -right : right
+  if (a < b) [a, b] = [b, a]
+  while (b !== 0n) {
+    if (a === b) return a
+    if (b < batchThreshold) {
+      while (b !== 0n) {
+        const remainder = a % b
+        a = b
+        b = remainder
+      }
+      return a
+    }
+    {
+      // Hex length gives a cheap common shift retaining at most 64 leading bits.
+      const shift = BigInt(Math.max(0, a.toString(16).length * 4 - 64))
+      let x = a >> shift
+      let y = b >> shift
+      let A = 1n, B = 0n, C = 0n, D = 1n
+      for (let step = 0; step < 64 && x >= y && y > 0n && y + C > 0n && y + D > 0n; step++) {
+        const q = (x + A) / (y + C)
+        if (q <= 0n || q !== (x + B) / (y + D)) break
+        ;[A, B, C, D] = [C, D, A - q * C, B - q * D]
+        ;[x, y] = [y, x - q * y]
+      }
+      if (B !== 0n) {
+        const nextA = A * a + B * b
+        const nextB = C * a + D * b
+        // Each matrix step has determinant -1, preserving the GCD exactly.
+        // Check full-width progress before accepting the approximate batch.
+        if (nextA >= nextB && nextB >= 0n && nextA < a && nextB < b) {
+          a = nextA
+          b = nextB
+          continue
+        }
+      }
+    }
+    const remainder = a % b
+    a = b
+    b = remainder
+  }
+  return a
+}

package/src/linear.ts

@@ -1,5 +1,13 @@
+import { evaluate } from './evaluate-expression.ts'
+import { constantSign, type Sign } from './constant-sign.ts'
+import { balancedReduce } from './balanced-reduce.ts'
+import { sum } from './fraction-sum.ts'
+import { product } from './fraction-product.ts'
+import { clone } from './clone.ts'
 import type { Expression, Model } from './model.ts'
-import { model as validate } from './validate.ts'
+import type { Limits } from './adapter.ts'
+import { mergeLimits, model as validate } from './validate.ts'
+import * as Exact from './exact.ts'
 
 export type Analysis = {
   readonly linear: boolean
@@ -8,48 +16,106 @@ export type Analysis = {
 
 type Affine = { readonly linear: boolean, readonly constant: boolean }
 
-const affine = (expression: Expression): Affine => {
+const combine = (left: Exact.Normalized, right: Exact.Normalized, kind: 'add' | 'subtract' | 'multiply' | 'divide'): Exact.Normalized => {
+  const a = BigInt(left.numerator)
+  const b = BigInt(left.denominator)
+  const c = BigInt(right.numerator)
+  const d = BigInt(right.denominator)
+  const [numerator, denominator] = kind === 'add' ? sum(a, b, c, d)
+    : kind === 'subtract' ? sum(a, b, -c, d)
+      : kind === 'multiply' ? product(a, b, c, d) : product(a, b, d, c)
+  return Exact.fromBigInts(numerator, denominator)
+}
+
+/** Called only for numeric constant expressions already classified as affine. */
+function* constantSteps(expression: Expression): Generator<Expression, Exact.Normalized, Exact.Normalized> {
+  switch (expression.kind) {
+    case 'literal':
+      if (expression.sort === 'int') return Exact.rational(String(Exact.integer(expression.value)))
+      if (expression.sort === 'real') return Exact.rational(expression.value)
+      break
+    case 'negate': return combine(Exact.rational('0'), (yield expression.value), 'subtract')
+    case 'add':
+    case 'multiply': {
+      const values: Exact.Normalized[] = []
+      for (const value of expression.operands) values.push(yield value)
+      if (expression.kind === 'add') return balancedReduce(values, (left, right) => combine(left, right, 'add'))
+      let numerator = 1n, denominator = 1n
+      for (const value of values) {
+        [numerator, denominator] = product(numerator, denominator, BigInt(value.numerator), BigInt(value.denominator))
+      }
+      return Exact.fromBigInts(numerator, denominator)
+    }
+    case 'subtract':
+    case 'divide': return combine((yield expression.left), (yield expression.right), expression.kind)
+  }
+  throw new TypeError('expected an affine numeric constant')
+}
+
+function* affineSteps(expression: Expression, constants: WeakMap<Expression, Exact.Normalized>, signs: WeakMap<Expression, Sign>): Generator<Expression, Affine, Affine> {
   switch (expression.kind) {
     case 'literal': return { linear: expression.sort === 'int' || expression.sort === 'real', constant: true }
     case 'variable': return { linear: true, constant: false }
-    case 'negate': return affine(expression.value)
+    case 'negate': return (yield expression.value)
     case 'add': {
-      const parts = expression.operands.map(affine)
-      return { linear: parts.every(part => part.linear), constant: parts.every(part => part.constant) }
+      let linear = true, constant = true
+      for (const value of expression.operands) {
+        const part = yield value
+        linear = linear && part.linear
+        constant = constant && part.constant
+      }
+      return { linear, constant }
     }
     case 'subtract': {
-      const left = affine(expression.left)
-      const right = affine(expression.right)
+      const left = (yield expression.left)
+      const right = (yield expression.right)
       return { linear: left.linear && right.linear, constant: left.constant && right.constant }
     }
     case 'multiply': {
-      const parts = expression.operands.map(affine)
-      return { linear: parts.every(part => part.linear) && parts.filter(part => !part.constant).length <= 1, constant: parts.every(part => part.constant) }
+      let linear = true, variableParts = 0
+      for (const value of expression.operands) {
+        const part = yield value
+        linear = linear && part.linear
+        if (!part.constant) variableParts++
+      }
+      return { linear: linear && variableParts <= 1, constant: variableParts === 0 }
     }
     case 'divide': {
-      const left = affine(expression.left)
-      const right = affine(expression.right)
-      return { linear: left.linear && right.linear && right.constant, constant: left.constant && right.constant }
+      const left = (yield expression.left)
+      const right = (yield expression.right)
+      let linear = false
+      if (left.linear && right.linear && right.constant) {
+        const sign = constantSign(expression.right, signs, value => evaluate(value, constantSteps, constants))
+        linear = sign === undefined ? !Exact.isZero(evaluate(expression.right, constantSteps, constants)) : sign !== 0
+      }
+      return { linear, constant: left.constant && right.constant }
     }
     default: return { linear: false, constant: false }
   }
 }
 
-const constraintIsLinear = (expression: Expression): boolean => {
+const constraintIsLinear = (expression: Expression, affine: (value: Expression) => Affine): boolean => {
   if (expression.kind !== 'eq' && expression.kind !== 'lte' && expression.kind !== 'gte') return false
   return affine(expression.left).linear && affine(expression.right).linear
 }
 
 /** Recognizes the portable LP/MIP subset without consulting a backend AST. */
-export const model = (input: Model): Analysis => {
-  validate(input)
+export const model = (input: Model, limits: Partial<Limits> = {}): Analysis => {
+  limits = mergeLimits(limits)
+  validate(input, limits)
+  input = clone(input)
+  validate(input, limits)
   const problems: string[] = []
+  const constants = new WeakMap<Expression, Exact.Normalized>()
+  const classifications = new WeakMap<Expression, Affine>()
+  const signs = new WeakMap<Expression, Sign>()
+  const affine = (value: Expression): Affine => evaluate(value, expression => affineSteps(expression, constants, signs), classifications)
   if (input.variables.some(variable => variable.sort === 'bool' || variable.sort === 'enum')) {
     problems.push('Boolean and enum variables are outside the linear subset')
   }
   if ((input.softConstraints?.length ?? 0) > 0) problems.push('soft constraints are outside the linear subset')
   input.constraints.forEach(constraint => {
-    if (!constraintIsLinear(constraint.expression)) problems.push(`constraint ${constraint.id} is not a non-strict linear comparison`)
+    if (!constraintIsLinear(constraint.expression, affine)) problems.push(`constraint ${constraint.id} is not a non-strict linear comparison`)
   })
   ;(input.objectives ?? []).forEach(objective => {
     if (!affine(objective.expression).linear) problems.push(`objective ${objective.id} is not linear`)

package/src/numeric-size.ts

@@ -0,0 +1,26 @@
+/** Estimate pre-reduction decimal digits without constructing a BigInt. */
+const integerDigits = (value: unknown): number => {
+  if (typeof value === 'number') return Number.isSafeInteger(value) ? String(Math.abs(value)).length : 0
+  if (typeof value !== 'string' || !/^[+-]?\d+$/.test(value)) return 0
+  return value.length - (/^[+-]/.test(value) ? 1 : 0)
+}
+
+export const numericDigits = (value: unknown, sort: 'int' | 'real'): number => {
+  if (sort === 'int') return integerDigits(value)
+  if (typeof value !== 'string') {
+    if (value === null || typeof value !== 'object') return 0
+    const pair = value as { numerator?: unknown, denominator?: unknown }
+    return integerDigits(pair.numerator) + integerDigits(pair.denominator)
+  }
+  const match = /^([+-]?)(\d+(?:\.\d*)?|\.\d+)(?:[eE]([+-]?\d+))?$/.exec(value)
+  if (match === null) return 0
+  const coefficient = match[2]!
+  const digits = coefficient.replace('.', '')
+  const exponent = match[3] === undefined ? 0 : Number(match[3])
+  if (!Number.isSafeInteger(exponent)) return 0 // Exact reports invalid exponent syntax.
+  // Zero never constructs a power of ten, but reading its coefficient still counts.
+  if (!/[1-9]/.test(digits)) return digits.length + 1
+  const dot = coefficient.indexOf('.')
+  const scale = (dot === -1 ? 0 : coefficient.length - dot - 1) - exponent
+  return digits.length + Math.max(0, -scale) + (scale > 0 ? scale + 1 : 1)
+}

package/src/options.ts

@@ -0,0 +1,18 @@
+import { diagnosticText } from './diagnostic-text.ts'
+import { mergeLimits } from './validate.ts'
+import type { Options } from './adapter.ts'
+
+/** Validate option names and capture supplied fields before applying defaults. */
+export const validateOptions = (options: Options): Options => {
+  if (options === null || typeof options !== 'object' || Array.isArray(options)) {
+    throw new TypeError('solver options must be an object')
+  }
+  for (const key of Object.keys(options)) {
+    if (key !== 'limits' && key !== 'unsatCore') throw new TypeError(`unknown solver option ${diagnosticText(key)}`)
+  }
+  const unsatCore = options.unsatCore
+  if (unsatCore !== undefined && typeof unsatCore !== 'boolean') {
+    throw new TypeError('solver option unsatCore must be a Boolean')
+  }
+  return { unsatCore, limits: mergeLimits(options.limits) }
+}

package/src/result.ts

@@ -0,0 +1,28 @@
+import type { Result } from './adapter.ts'
+import { clone } from './clone.ts'
+import { resultMetadata, unknownReason } from './validate.ts'
+
+/** Capture the reported outcome before checking the adapter's proof contract. */
+export const captureResult = (input: Result): Result => {
+  const result = clone(input)
+  if (result === null || typeof result !== 'object' || Array.isArray(result)) {
+    throw new TypeError('solver result must be an object')
+  }
+  switch (result.status) {
+    case 'optimal':
+      if (result.optimalityProved !== true) throw new TypeError('optimal solver result requires optimalityProved: true')
+      break
+    case 'unsatisfied':
+      if (result.infeasibilityProved !== true) throw new TypeError('unsatisfied solver result requires infeasibilityProved: true')
+      break
+    case 'satisfied':
+      break
+    case 'unknown':
+      unknownReason(result.reason)
+      break
+    default:
+      throw new TypeError('solver result status must be satisfied, optimal, unsatisfied or unknown')
+  }
+  resultMetadata(result)
+  return result
+}

package/src/solve.ts

@@ -1,19 +1,41 @@
+import { captureResult } from './result.ts'
+import { validateContext } from './context.ts'
+import { clone } from './clone.ts'
 import type { Options, Result, SolverAdapter } from './adapter.ts'
 import * as Capability from './capability.ts'
+import * as Canonical from './canonical.ts'
 import * as Explain from './explain.ts'
 import type { Model } from './model.ts'
 import * as Validate from './validate.ts'
+import { validateOptions } from './options.ts'
+
+const freeze = <T>(value: T): T => {
+  const pending: unknown[] = [value]
+  const seen = new Set<object>()
+  while (pending.length > 0) {
+    const next = pending.pop()
+    if (next === null || typeof next !== 'object' || seen.has(next)) continue
+    seen.add(next)
+    for (const child of Object.values(next)) pending.push(child)
+    Object.freeze(next)
+  }
+  return value
+}
 
 const prepared = (adapter: SolverAdapter, model: Model, options: Options): {
   readonly limits: ReturnType<typeof Validate.mergeLimits>
+  readonly model: Model
   readonly run: () => Promise<Result>
 } => {
-  const limits = Validate.mergeLimits(options.limits)
+  options = validateOptions(options)
+  const limits = Object.freeze(Validate.mergeLimits(options.limits))
+  model = clone(model)
   Validate.model(model, limits)
+  model = freeze(model)
   const unsatCore = options.unsatCore ?? false
   const missing = Capability.missing(adapter, model, unsatCore)
   if (missing.length > 0) throw new Capability.UnsupportedModelError(adapter.backend.name, missing)
-  return { limits, run: () => adapter.solve(model, { limits, unsatCore }) }
+  return { model, limits, run: async () => captureResult(await adapter.solve(model, { limits, unsatCore })) }
 }
 
 /** Validates and negotiates a model before crossing the adapter boundary. */
@@ -29,5 +51,14 @@ export const runWithExplanation = async (
   context: Explain.Context = {}
 ): Promise<Explain.Report> => {
   const solve = prepared(adapter, model, options)
-  return Explain.report(model, await solve.run(), solve.limits, context)
+  validateContext(context)
+  const snapshot = clone(context)
+  validateContext(snapshot)
+  if (snapshot.modelDigest !== undefined) {
+    const digest = Canonical.digest(solve.model, solve.limits)
+    if (snapshot.modelDigest !== digest) {
+      throw new TypeError(`scenario model digest ${snapshot.modelDigest} does not match ${digest}`)
+    }
+  }
+  return Explain.report(solve.model, await solve.run(), solve.limits, snapshot)
 }