@cavelang/solver 0.27.14

package/src/adapter.ts

@@ -0,0 +1,110 @@
+import type { Assignment, Model, Rational, Value } from './model.ts'
+
+export const capabilities = [
+  'booleans',
+  'integers',
+  'rationals',
+  'finite-enums',
+  'conditionals',
+  'nonlinear-arithmetic',
+  'optimization',
+  'lexicographic-objectives',
+  'soft-constraints',
+  'unsat-cores'
+] as const
+
+export type Capability = typeof capabilities[number]
+
+export type Limits = {
+  readonly timeoutMs: number
+  /** Backend working-memory ceiling. Adapters must reject or isolate when they cannot enforce it. */
+  readonly maxMemoryBytes: number
+  readonly maxVariables: number
+  readonly maxConstraints: number
+  readonly maxObjectives: number
+  readonly maxEnumValues: number
+  readonly maxExpressionNodes: number
+  readonly maxExpressionDepth: number
+  readonly maxOutputBytes: number
+}
+
+export const defaultLimits: Limits = Object.freeze({
+  timeoutMs: 10_000,
+  maxMemoryBytes: 512 * 1024 * 1024,
+  maxVariables: 1_000,
+  maxConstraints: 5_000,
+  maxObjectives: 16,
+  maxEnumValues: 1_000,
+  maxExpressionNodes: 100_000,
+  maxExpressionDepth: 128,
+  maxOutputBytes: 1_000_000
+})
+
+export type Backend = {
+  readonly name: string
+  readonly version: string
+}
+
+export type Diagnostic = {
+  readonly level: 'info' | 'warning' | 'error'
+  readonly code: string
+  readonly message: string
+}
+
+type CommonResult = {
+  readonly backend: Backend
+  readonly diagnostics: readonly Diagnostic[]
+  readonly elapsedMs: number
+}
+
+export type ObjectiveValue = {
+  readonly objectiveId: string
+  readonly value: Value
+  readonly bound?: Value
+}
+
+export type UnknownReason = {
+  readonly kind: 'timeout' | 'resource-limit' | 'cancelled' | 'backend-error' | 'indeterminate'
+  readonly message: string
+  readonly limit?: keyof Limits
+}
+
+export type Result = CommonResult & (
+  | { readonly status: 'satisfied', readonly assignment: Assignment }
+  | {
+    readonly status: 'optimal'
+    readonly assignment: Assignment
+    readonly objectives: readonly ObjectiveValue[]
+    readonly optimalityProved: true
+  }
+  | {
+    readonly status: 'unsatisfied'
+    readonly core?: readonly string[]
+    readonly infeasibilityProved: true
+  }
+  | { readonly status: 'unknown', readonly reason: UnknownReason }
+)
+
+export type Options = {
+  readonly limits?: Partial<Limits>
+  readonly unsatCore?: boolean
+}
+
+export type Request = {
+  readonly limits: Limits
+  readonly unsatCore: boolean
+}
+
+export type SolverAdapter = {
+  readonly backend: Backend
+  readonly capabilities: ReadonlySet<Capability>
+  readonly solve: (model: Model, request: Request) => Promise<Result>
+}
+
+export type t = SolverAdapter
+
+/** Utility type for adapters that report exact objective bounds. */
+export type ExactBound = {
+  readonly value: Rational
+  readonly bound?: Rational
+}

package/src/canonical.ts

@@ -0,0 +1,94 @@
+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))
+
+/** 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 digest = (input: Model): string =>
+  `sha256:${createHash('sha256').update(serialize(input)).digest('hex')}`

package/src/capability.ts

@@ -0,0 +1,82 @@
+import type { Capability, SolverAdapter } from './adapter.ts'
+import type { Expression, Model } from './model.ts'
+
+export class UnsupportedModelError extends Error {
+  readonly backend: string
+  readonly missing: readonly Capability[]
+
+  constructor(backend: string, missing: readonly Capability[]) {
+    super(`solver backend ${JSON.stringify(backend)} lacks capabilities: ${missing.join(', ')}`)
+    this.name = 'UnsupportedModelError'
+    this.backend = backend
+    this.missing = missing
+  }
+}
+
+const walk = (expression: Expression, visit: (expression: Expression) => void): void => {
+  visit(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)
+  }
+}
+
+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
+  }
+  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> => {
+  const result = new Set<Capability>(['booleans'])
+  if (model.variables.some(variable => variable.sort === 'int')) result.add('integers')
+  if (model.variables.some(variable => variable.sort === 'real')) result.add('rationals')
+  if ((model.enums?.length ?? 0) > 0 || model.variables.some(variable => variable.sort === 'enum')) result.add('finite-enums')
+  if ((model.softConstraints?.length ?? 0) > 0) {
+    result.add('soft-constraints')
+    result.add('rationals')
+  }
+  if ((model.objectives?.length ?? 0) > 0) result.add('optimization')
+  if ((model.objectives?.length ?? 0) > 1) result.add('lexicographic-objectives')
+  if (unsatCore) result.add('unsat-cores')
+  const expressions = [
+    ...model.constraints.map(constraint => constraint.expression),
+    ...(model.softConstraints ?? []).map(constraint => constraint.expression),
+    ...(model.objectives ?? []).map(objective => objective.expression)
+  ]
+  for (const expression of expressions) {
+    walk(expression, node => {
+      if (node.kind === 'literal' && node.sort === 'int') result.add('integers')
+      if (node.kind === 'literal' && node.sort === 'real') result.add('rationals')
+      if (node.kind === 'literal' && node.sort === 'enum') result.add('finite-enums')
+      if (node.kind === 'if') result.add('conditionals')
+    })
+    if (hasNonlinearArithmetic(expression)) result.add('nonlinear-arithmetic')
+  }
+  return result
+}
+
+export const missing = (adapter: SolverAdapter, model: Model, unsatCore = false): readonly Capability[] =>
+  [...required(model, unsatCore)].filter(capability => !adapter.capabilities.has(capability)).sort()

package/src/exact.ts

@@ -0,0 +1,85 @@
+import type { Integer, Rational } from './model.ts'
+
+export type Normalized = {
+  readonly numerator: string
+  readonly denominator: string
+}
+
+const integerPattern = /^[+-]?\d+$/
+const decimalPattern = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/
+
+const gcd = (left: bigint, right: bigint): bigint => {
+  let a = left < 0n ? -left : left
+  let b = right < 0n ? -right : right
+  while (b !== 0n) {
+    const remainder = a % b
+    a = b
+    b = remainder
+  }
+  return a
+}
+
+export const integer = (input: Integer): bigint => {
+  if (typeof input === 'number') {
+    if (!Number.isSafeInteger(input)) {
+      throw new TypeError(`expected a safe integer, received ${String(input)}`)
+    }
+    return BigInt(input)
+  }
+  if (!integerPattern.test(input)) {
+    throw new TypeError(`expected an integer string, received ${JSON.stringify(input)}`)
+  }
+  return BigInt(input)
+}
+
+const decimal = (input: string): readonly [bigint, bigint] => {
+  if (!decimalPattern.test(input)) {
+    throw new TypeError(`expected an exact decimal string, received ${JSON.stringify(input)}`)
+  }
+  const [coefficient = '', exponentText] = input.toLowerCase().split('e')
+  const exponent = exponentText === undefined ? 0 : Number(exponentText)
+  if (!Number.isSafeInteger(exponent)) {
+    throw new TypeError(`decimal exponent is outside the supported range: ${JSON.stringify(input)}`)
+  }
+  const negative = coefficient.startsWith('-')
+  const unsigned = coefficient.replace(/^[+-]/, '')
+  const [whole = '', fraction = ''] = unsigned.split('.')
+  const digits = `${whole === '' ? '0' : whole}${fraction}`
+  const scale = fraction.length - exponent
+  const signed = BigInt(digits === '' ? '0' : digits) * (negative ? -1n : 1n)
+  return scale <= 0
+    ? [signed * (10n ** BigInt(-scale)), 1n]
+    : [signed, 10n ** BigInt(scale)]
+}
+
+export const rational = (input: Rational): Normalized => {
+  let numerator: bigint
+  let denominator: bigint
+  if (typeof input === 'string') {
+    ;[numerator, denominator] = decimal(input)
+  } else {
+    numerator = integer(input.numerator)
+    denominator = integer(input.denominator)
+  }
+  if (denominator === 0n) {
+    throw new TypeError('rational denominator must not be zero')
+  }
+  if (denominator < 0n) {
+    numerator = -numerator
+    denominator = -denominator
+  }
+  const divisor = gcd(numerator, denominator)
+  return {
+    numerator: String(numerator / divisor),
+    denominator: String(denominator / divisor)
+  }
+}
+
+export const compare = (left: Rational, right: Rational): -1 | 0 | 1 => {
+  const a = rational(left)
+  const b = rational(right)
+  const difference = BigInt(a.numerator) * BigInt(b.denominator) - BigInt(b.numerator) * BigInt(a.denominator)
+  return difference < 0n ? -1 : difference > 0n ? 1 : 0
+}
+
+export const isZero = (input: Rational): boolean => rational(input).numerator === '0'

package/src/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Solver-neutral formal reasoning contracts for CAVE.
+ *
+ * This package contains no solver implementation and never imports Z3 or
+ * another backend. Adapters receive only validated portable model data.
+ */
+
+export * as Adapter from './adapter.ts'
+export * as Canonical from './canonical.ts'
+export * as Capability from './capability.ts'
+export * as Exact from './exact.ts'
+export * as Linear from './linear.ts'
+export * as Model from './model.ts'
+export * as Solve from './solve.ts'
+export * as Validate from './validate.ts'

package/src/linear.ts

@@ -0,0 +1,58 @@
+import type { Expression, Model } from './model.ts'
+import { model as validate } from './validate.ts'
+
+export type Analysis = {
+  readonly linear: boolean
+  readonly problems: readonly string[]
+}
+
+type Affine = { readonly linear: boolean, readonly constant: boolean }
+
+const affine = (expression: Expression): 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 'add': {
+      const parts = expression.operands.map(affine)
+      return { linear: parts.every(part => part.linear), constant: parts.every(part => part.constant) }
+    }
+    case 'subtract': {
+      const left = affine(expression.left)
+      const right = affine(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) }
+    }
+    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 }
+    }
+    default: return { linear: false, constant: false }
+  }
+}
+
+const constraintIsLinear = (expression: Expression): 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)
+  const problems: string[] = []
+  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`)
+  })
+  ;(input.objectives ?? []).forEach(objective => {
+    if (!affine(objective.expression).linear) problems.push(`objective ${objective.id} is not linear`)
+  })
+  return { linear: problems.length === 0, problems }
+}

package/src/model.ts

@@ -0,0 +1,80 @@
+/** Portable model schema understood by solver adapters. */
+export const schema = 'cave.solver/model@1' as const
+
+export type Integer = string | number
+
+/** Exact rational input. Decimal strings are parsed without using `number`. */
+export type Rational = string | {
+  readonly numerator: Integer
+  readonly denominator: Integer
+}
+
+export type EnumDomain = {
+  readonly id: string
+  readonly values: readonly string[]
+  readonly description?: string
+}
+
+export type Variable =
+  | { readonly id: string, readonly sort: 'bool', readonly description?: string }
+  | { readonly id: string, readonly sort: 'int', readonly min: Integer, readonly max: Integer, readonly description?: string }
+  | { readonly id: string, readonly sort: 'real', readonly min?: Rational, readonly max?: Rational, readonly description?: string }
+  | { readonly id: string, readonly sort: 'enum', readonly domain: string, readonly description?: string }
+
+export type Literal =
+  | { readonly kind: 'literal', readonly sort: 'bool', readonly value: boolean }
+  | { readonly kind: 'literal', readonly sort: 'int', readonly value: Integer }
+  | { readonly kind: 'literal', readonly sort: 'real', readonly value: Rational }
+  | { readonly kind: 'literal', readonly sort: 'enum', readonly domain: string, readonly value: string }
+
+export type Expression =
+  | Literal
+  | { readonly kind: 'variable', readonly id: string }
+  | { readonly kind: 'not', readonly value: Expression }
+  | { readonly kind: 'and' | 'or', readonly operands: readonly Expression[] }
+  | { readonly kind: 'implies', readonly left: Expression, readonly right: Expression }
+  | { readonly kind: 'eq' | 'neq' | 'lt' | 'lte' | 'gt' | 'gte', readonly left: Expression, readonly right: Expression }
+  | { readonly kind: 'add' | 'multiply', readonly operands: readonly Expression[] }
+  | { readonly kind: 'subtract' | 'divide', readonly left: Expression, readonly right: Expression }
+  | { readonly kind: 'negate', readonly value: Expression }
+  | { readonly kind: 'if', readonly condition: Expression, readonly then: Expression, readonly else: Expression }
+
+export type HardConstraint = {
+  readonly id: string
+  readonly expression: Expression
+  readonly description?: string
+  readonly evidenceRowIds?: readonly string[]
+}
+
+export type SoftConstraint = HardConstraint & {
+  /** Deliberate preference weight; never inferred from CAVE confidence. */
+  readonly weight: Rational
+}
+
+export type Objective = {
+  readonly id: string
+  readonly direction: 'minimize' | 'maximize'
+  readonly expression: Expression
+  readonly description?: string
+  readonly evidenceRowIds?: readonly string[]
+}
+
+export type Model = {
+  readonly schema: typeof schema
+  readonly enums?: readonly EnumDomain[]
+  readonly variables: readonly Variable[]
+  readonly constraints: readonly HardConstraint[]
+  readonly softConstraints?: readonly SoftConstraint[]
+  /** Objective order is semantic and means lexicographic priority. */
+  readonly objectives?: readonly Objective[]
+}
+
+export type t = Model
+
+export type Value =
+  | { readonly sort: 'bool', readonly value: boolean }
+  | { readonly sort: 'int', readonly value: string }
+  | { readonly sort: 'real', readonly numerator: string, readonly denominator: string }
+  | { readonly sort: 'enum', readonly domain: string, readonly value: string }
+
+export type Assignment = Readonly<Record<string, Value>>

package/src/solve.ts

@@ -0,0 +1,13 @@
+import type { Options, Result, SolverAdapter } from './adapter.ts'
+import * as Capability from './capability.ts'
+import type { Model } from './model.ts'
+import * as Validate from './validate.ts'
+
+/** Validates and negotiates a model before crossing the adapter boundary. */
+export const run = async (adapter: SolverAdapter, model: Model, options: Options = {}): Promise<Result> => {
+  const limits = Validate.mergeLimits(options.limits)
+  Validate.model(model, limits)
+  const missing = Capability.missing(adapter, model, options.unsatCore ?? false)
+  if (missing.length > 0) throw new Capability.UnsupportedModelError(adapter.backend.name, missing)
+  return adapter.solve(model, { limits, unsatCore: options.unsatCore ?? false })
+}