aontu 0.51.0 → 0.52.0

package/src/lang.ts

@@ -102,6 +102,13 @@ import { PrefFuncVal } from './val/PrefFuncVal'
 import { CloseFuncVal } from './val/CloseFuncVal'
 import { OpenFuncVal } from './val/OpenFuncVal'
 import { SuperFuncVal } from './val/SuperFuncVal'
+import {
+  MinConstraintVal,
+  MaxConstraintVal,
+  AboveConstraintVal,
+  BelowConstraintVal,
+  NeqConstraintVal,
+} from './val/ConstraintVal'
 
 
 const asPlugin = (p: unknown): Plugin => p as Plugin
@@ -120,7 +127,11 @@ const asPlugin = (p: unknown): Plugin => p as Plugin
 // not part of the literal, so the text has to be rebuilt here to keep
 // `src` meaning "how this value is spelled" (see bigVal).
 function negsrc(src: string): string {
-  return '' === src ? '' : src.startsWith('-') ? src.slice(1) : '-' + src
+  // src is never empty here: it is a BIG_LITERAL_RE match (at minimum
+  // the two chars `0d`) or an already-negated spelling. Computed exact
+  // values do carry src '', but they are built at unify time, long
+  // after this parse-time opmap.
+  return src.startsWith('-') ? src.slice(1) : '-' + src
 }
 
 
@@ -151,6 +162,12 @@ let AontuJsonic: Plugin = function AontuLang(jsonic: Jsonic) {
   // docs/reference-language.md; go/lang.go sets the same). Clear the
   // underlying jsonic comment markers entirely, then define # directly,
   // so the comment set is hash-only regardless of those defaults.
+  let dotRef = (r: Rule, ctx: JsonicContext, terms: any, prefix: boolean) => {
+    terms = dropUnfilled(terms)
+    if (0 === terms.length) return incompleteNil(r, ctx)
+    return addsite(new RefVal({ peg: terms, prefix }), r, ctx)
+  }
+
   jsonic.options({ comment: { def: null } })
   jsonic.options({
     comment: {
@@ -266,7 +283,8 @@ let AontuJsonic: Plugin = function AontuLang(jsonic: Jsonic) {
     v.site.row = null == r.o0 ? -1 : r.o0.rI
     v.site.col = null == r.o0 ? -1 : r.o0.cI
     v.site.url = ctx.meta.multisource ? ctx.meta.multisource.path : ''
-    v.path = r.k ? [...(r.k.path || [])] : []
+    // A keyed rule always carries a path array; a keyless one has none.
+    v.path = r.k ? [...r.k.path] : []
 
     return v
   }
@@ -392,6 +410,16 @@ help isolate the syntax error.`,
     close: CloseFuncVal,
     open: OpenFuncVal,
     super: SuperFuncVal,
+
+    // The constraint algebra's Band A atoms (G1 phase 1;
+    // docs/reference-language.md, "The constraint algebra"): bounds
+    // and exclusion enter through the function registry — the
+    // established extension point — with zero grammar change.
+    min: MinConstraintVal,
+    max: MaxConstraintVal,
+    above: AboveConstraintVal,
+    below: BelowConstraintVal,
+    neq: NeqConstraintVal,
   }
 
 
@@ -412,17 +440,14 @@ help isolate the syntax error.`,
     'disjunct-infix': (r: Rule, ctx: JsonicContext, _op: Op, terms: any) =>
       addsite(new DisjunctVal({ peg: dropUnfilled(terms) }), r, ctx),
 
-    'dot-prefix': (r: Rule, ctx: JsonicContext, _op: Op, terms: any) => {
-      terms = dropUnfilled(terms)
-      if (0 === terms.length) return incompleteNil(r, ctx)
-      return addsite(new RefVal({ peg: terms, prefix: true }), r, ctx)
-    },
+    // `.a` (prefix) and `a.b` (infix) build the same reference; only the
+    // prefix flag differs, and both need the same missing-operand guard,
+    // so they share one builder.
+    'dot-prefix': (r: Rule, ctx: JsonicContext, _op: Op, terms: any) =>
+      dotRef(r, ctx, terms, true),
 
-    'dot-infix': (r: Rule, ctx: JsonicContext, _op: Op, terms: any) => {
-      terms = dropUnfilled(terms)
-      if (0 === terms.length) return incompleteNil(r, ctx)
-      return addsite(new RefVal({ peg: terms }), r, ctx)
-    },
+    'dot-infix': (r: Rule, ctx: JsonicContext, _op: Op, terms: any) =>
+      dotRef(r, ctx, terms, false),
 
     'star-prefix': (r: Rule, ctx: JsonicContext, _op: Op, terms: any) => {
       if (null == terms[0]) return incompleteNil(r, ctx)
@@ -809,18 +834,10 @@ help isolate the syntax error.`,
           }
         }
 
-        if (ao.___merge) {
-          let aop = [...ao]
-          delete (aop as any).___merge
-
-          // TODO: needs addpath?
-          let aopv = new ListVal({ peg: aop })
-          aopv.optionalKeys = optionalKeys
-
-          r.node =
-            addsite(new ConjunctVal({ peg: [aopv, ...ao.___merge] }), r, ctx)
-        }
-        else {
+        // No ___merge arm here: the deferred map.merge that writes it
+        // only ever fires for a `pair` rule, whose parent is always a
+        // `map` rule with a plain-object node — never a list.
+        {
           r.node = addsite(new ListVal({ peg: ao }), r, ctx)
           r.node.optionalKeys = optionalKeys
         }
@@ -1000,7 +1017,10 @@ function makeModelResolver(options: any) {
     jsonic: Tabnas
   ) {
 
-    let path = 'string' === typeof spec ? spec : spec?.peg
+    // The aontu val rule's ac has already wrapped every raw string node
+    // as a StringVal, so spec is a Val here (or a raw object from a
+    // .json/.js include, whose peg is undefined -> not found).
+    let path = spec?.peg
 
     // A bare `@` with no path (`a:@`) has nothing to resolve; report
     // not-found instead of crashing in the underlying resolvers.
@@ -1042,6 +1062,34 @@ function makeModelResolver(options: any) {
 // the aontu val rule conversions (mirrors asVal in go/lang.go; like
 // there, source text is unavailable, so an integral number is an
 // integer).
+// The targeted parse hint for CUE-trained authors and models: `>` and
+// `<` are not Aontu operators (the op-chars reservation stands), and an
+// agent that emits `number > 0` should be redirected to the bound
+// atoms, not left with a bare "unexpected character". Appended to a
+// parse error's message when the source carries an unquoted `<` or
+// `>`; the Go twin is opCharHint in go/lang.go, byte-identical text.
+function opCharHint(src: string): string {
+  let q = ''
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i]
+    if ('' !== q) {
+      if (c === q && '\\' !== src[i - 1]) {
+        q = ''
+      }
+      continue
+    }
+    if ('"' === c || '\'' === c || '`' === c) {
+      q = c
+    }
+    else if ('<' === c || '>' === c) {
+      return '\nThe > and < characters are not Aontu operators: write the ' +
+        'bound functions min(x), max(x), above(x), below(x) instead.'
+    }
+  }
+  return ''
+}
+
+
 function rawToVal(n: any): Val {
   if (null == n) {
     return new NullVal({ peg: null })
@@ -1164,7 +1212,7 @@ class Lang {
           why: 'parse',
           err: new NilVal({
             why: 'syntax',
-            msg: e.message,
+            msg: e.message + opCharHint(src),
             err: e,
           })
         })
@@ -1176,7 +1224,7 @@ class Lang {
 
     return val
   }
-}
+} /* node:coverage ignore next 6 */
 
 export {
   Lang,

package/src/lsp-server.ts

@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
 // Aontu Language Server (stdio).
@@ -85,25 +84,28 @@ class FrameCodec {
 }
 
 
-function main() {
+// The streams and exit are injectable (defaulting to real stdio) so the
+// full wiring is unit-testable — the same shape as the Go server's
+// serve(in, out, logw).
+function main(
+  stdin: NodeJS.ReadableStream = process.stdin,
+  write: (chunk: Buffer) => void = (chunk) => void process.stdout.write(chunk),
+  exit: (code: number) => void = (code) => process.exit(code),
+): FrameCodec {
   const handler = new LspHandler()
-  const codec = new FrameCodec(
-    handler,
-    (chunk) => process.stdout.write(chunk),
-    (code) => process.exit(code),
-  )
-
-  process.stdin.on('data', (chunk: Buffer) => codec.push(chunk))
-  process.stdin.on('end', () => codec.end())
-}
+  const codec = new FrameCodec(handler, write, exit)
 
+  stdin.on('data', (chunk: Buffer) => codec.push(chunk))
+  stdin.on('end', () => codec.end())
+  return codec
+} /* node:coverage ignore next 11 */
 
-// Only auto-run when invoked as a program, not when imported by tests.
-if (require.main === module) {
-  main()
-}
+
+// No require.main guard here: bin/aontu-lsp.js is the executable entry
+// and calls main() itself, so this module stays import-only.
 
 
 export {
   FrameCodec,
+  main,
 }

package/src/lsp.ts

@@ -78,8 +78,9 @@ function computeDiagnostics(
   const aontu = new Aontu()
 
   let root: any
+  let ac: any
   try {
-    const ac = aontu.ctx({ collect: true })
+    ac = aontu.ctx({ collect: true })
     if (opts?.vars) {
       Object.assign(ac.vars, opts.vars)
     }
@@ -92,7 +93,21 @@ function computeDiagnostics(
   }
 
   const nils: any[] = []
-  walkNils(root, nils, new Set())
+  const seen = new Set()
+  walkNils(root, nils, seen)
+
+  // Errors recorded on the context but not present in the tree — e.g. a
+  // budget_passes exhaustion nil, which is about the whole evaluation
+  // rather than any node — would otherwise be invisible here, and the
+  // trust contract forbids silent truncation (docs/trust.md clause 2).
+  // Tree nils are already on ctx.err too, so dedup by identity; the
+  // transient disjunct-trial sentinel never surfaces.
+  for (const e of ac.err) {
+    if (e?.isNil && '|:trial-nil' !== e.why && !seen.has(e)) {
+      seen.add(e)
+      nils.push(e)
+    }
+  }
 
   return nils.map(nilToDiagnostic)
 }
@@ -277,8 +292,8 @@ function collectHoverCandidates(
   if (seen.has(v)) return
   seen.add(v)
 
-  const row = v.site?.row ?? -1
-  const col = v.site?.col ?? -1
+  const row = v.site.row
+  const col = v.site.col
   let canon = ''
   try { canon = v.canon } catch { canon = '' }
   // Hover targets concrete values (scalars, kinds, refs, …), not
@@ -305,8 +320,9 @@ function collectHoverCandidates(
 
 
 function hoverMarkdown(val: any): string {
-  let canon = ''
-  try { canon = val.canon } catch { canon = '' }
+  // No try needed: a Val only becomes a hover candidate after
+  // collectHoverCandidates read this same getter successfully.
+  const canon = val.canon
   return '```aontu\n' + canon + '\n```\n\n' + '*' + valKind(val) + '*'
 }
 
@@ -315,8 +331,7 @@ function hoverMarkdown(val: any): string {
 function valKind(val: any): string {
   if (val.isNil) return 'error'
   if (val.isScalarKind) return 'type'
-  if (val.isMap) return 'map'
-  if (val.isList) return 'list'
+  if (val.isConstraint) return 'constraint'
   if (val.isRef) return 'reference'
   if (val.isInteger) return 'integer'
   // NumberVal is the binary64 leaf, whose kind keyword is `float`;
@@ -343,11 +358,11 @@ type CompletionItem = {
 const COMPLETION_FUNCTION = 3
 const COMPLETION_KEYWORD = 14
 
-// The twelve built-in functions. Kept in sync with the engine by
+// The seventeen built-in functions. Kept in sync with the engine by
 // `lsp.test.ts`, which asserts each is recognised and no others are.
 const BUILTIN_FUNCS = [
-  'close', 'copy', 'hide', 'key', 'lower', 'move',
-  'open', 'path', 'pref', 'super', 'type', 'upper',
+  'above', 'below', 'close', 'copy', 'hide', 'key', 'lower', 'max',
+  'min', 'move', 'neq', 'open', 'path', 'pref', 'super', 'type', 'upper',
 ]
 
 // Scalar-kind and literal keywords.
@@ -464,7 +479,7 @@ class LspHandler {
   private publish(uri: string): OutMessage {
     return publishDiagnosticsMsg(uri, computeDiagnostics(this.docs.get(uri) ?? ''))
   }
-}
+} /* node:coverage ignore next 28 */
 
 
 export {

package/src/site.ts

@@ -20,7 +20,7 @@ class Site {
     this.col = site?.col ?? -1
     this.url = site?.url ?? ''
   }
-}
+} /* node:coverage ignore next 6 */
 
 
 export {

package/src/type.ts

@@ -50,7 +50,7 @@ type ValList = Val[]
 type ErrContext = {
   src?: string,
   fs?: FST
-}
+} /* node:coverage ignore next 20 */
 
 export type {
   Val,

package/src/unify.ts

@@ -205,6 +205,30 @@ function update(x: Val, _y: Val) {
 }
 
 
+// The still-refining paths named by a budget_passes error: the first
+// `max` non-done nodes of the residue, as `$.dotted.paths`. Depth-first
+// over bag children only -- this feeds an error message, not a report,
+// so a small deterministic sample beats completeness.
+function residuePaths(v: Val, max: number): string[] {
+  const out: string[] = []
+  const visit = (n: any, isroot: boolean) => {
+    if (null == n || max <= out.length) {
+      return
+    }
+    if (!isroot && !n.done) {
+      out.push('$' + (0 < (n.path?.length ?? 0) ? '.' + n.path.join('.') : ''))
+    }
+    if (n.isMap || n.isList) {
+      for (const k in n.peg) {
+        visit(n.peg[k], false)
+      }
+    }
+  }
+  visit(v, true)
+  return out
+}
+
+
 class Unify {
   root: Val
   res: Val
@@ -264,6 +288,7 @@ class Unify {
 
       // NOTE: if true === res.done already, then this loop never needs to run.
       let maxcc = 9 // 99
+      let prevCanon: string | undefined = undefined
       for (; this.cc < maxcc && DONE !== res.dc; this.cc++) {
         // console.log('CC', this.cc, res.canon)
         uctx.cc = this.cc
@@ -274,15 +299,41 @@ class Unify {
           break
         }
 
+        // Snapshot the second-to-last pass's result, so exhaustion can
+        // tell "still refining" from "stable residue" below. Only paid
+        // by models still unresolved this late.
+        if (this.cc === maxcc - 2 && DONE !== res.dc) {
+          prevCanon = res.canon
+        }
+
         uctx = uctx.clone({ root: res })
       }
 
+      // The pass budget is spent AND the final pass still made
+      // progress: the model was cut off while converging, and no other
+      // error explains why. Silent truncation would surface later as
+      // ordinary incompleteness, so exhaustion is a semantic error of
+      // its own (class budget, docs/trust.md clause 2) -- retrying with
+      // a larger budget is a valid response to THIS code and useless
+      // for path_cycle or no_path. A STABLE residue (the final pass
+      // changed nothing -- e.g. a stuck `1+true`) is not a budget
+      // failure: it is ordinary incompleteness and stays silent here,
+      // surfacing at generate exactly as before.
+      if (maxcc <= this.cc && DONE !== res.dc && 0 === uctx.err.length
+        && undefined !== prevCanon && prevCanon !== res.canon) {
+        makeNilErr(uctx, 'budget_passes', undefined, undefined, 'resolve', {
+          budget: 'passes',
+          limit: maxcc,
+          paths: residuePaths(res, 4).join(' ') || '$',
+        })
+      }
+
       uctx.explain && explainClose(te, res)
     }
 
     this.res = res
   }
-}
+} /* node:coverage ignore next 9 */
 
 
 

package/src/utility.ts

@@ -84,6 +84,8 @@ function walk(
 
   // Container Vals (Map etc) have peg = plain {} or []
   if (null != child && !child.isVal) {
+    // A ListVal's array peg is an object too, and for-in yields its
+    // indices as string keys, so this one loop covers both bag shapes.
     if ('object' === typeof child) {
       for (let ckey in child) {
         if (child[ckey] && child[ckey].isVal) {
@@ -92,14 +94,6 @@ function walk(
         }
       }
     }
-    else if (Array.isArray(child)) {
-      for (let i = 0; i < child.length; i++) {
-        if (child[i] && child[i].isVal) {
-          child[i] = walk(
-            child[i], before, after, maxdepth, i, out, [...(path || []), '' + i])
-        }
-      }
-    }
   }
 
   out = null == after ? out : after(key, out, parent, path || [])
@@ -194,7 +188,7 @@ function items(o: any) {
   else {
     return []
   }
-}
+} /* node:coverage ignore next 15 */
 
 
 export {

package/src/val/BagVal.ts

@@ -178,7 +178,7 @@ abstract class BagVal extends FeatureVal {
     return out
   }
 
-}
+} /* node:coverage ignore next 6 */
 
 
 export {

package/src/val/BigDecimalVal.ts

@@ -70,7 +70,7 @@ class BigDecimalVal extends ScalarVal {
     let out: Val = this
 
     if (null != peer) {
-      if (peer.isScalarKind) {
+      if (peer.isScalarKind || (peer as any).isConstraint) {
         out = peer.unify(this, te ? ctx.clone({ explain: ec(te, 'KND') }) : ctx)
       }
       else if (
@@ -109,7 +109,7 @@ class BigDecimalVal extends ScalarVal {
   get canon() {
     return this.peg.canon()
   }
-}
+} /* node:coverage ignore next 6 */
 
 
 export {

package/src/val/BigIntegerVal.ts

@@ -67,7 +67,7 @@ class BigIntegerVal extends ScalarVal {
     let out: Val = this
 
     if (null != peer) {
-      if (peer.isScalarKind) {
+      if (peer.isScalarKind || (peer as any).isConstraint) {
         out = peer.unify(this, te ? ctx.clone({ explain: ec(te, 'KND') }) : ctx)
       }
       else if (
@@ -102,7 +102,7 @@ class BigIntegerVal extends ScalarVal {
     const neg = this.peg < 0n
     return (neg ? '-0d' : '0d') + (neg ? -this.peg : this.peg).toString()
   }
-}
+} /* node:coverage ignore next 6 */
 
 
 export {

package/src/val/BooleanVal.ts

@@ -24,7 +24,7 @@ class BooleanVal extends ScalarVal {
   unify(peer: Val, ctx: AontuContext): Val {
     return super.unify(peer, ctx)
   }
-}
+} /* node:coverage ignore next 6 */
 
 
 export {

package/src/val/CloseFuncVal.ts

@@ -53,7 +53,7 @@ class CloseFuncVal extends FuncBaseVal {
     return argval
   }
 
-}
+} /* node:coverage ignore next 6 */
 
 
 export {

package/src/val/ConjunctVal.ts

@@ -279,7 +279,7 @@ function norm(terms: Val[]): Val[] {
 
 
   return expand
-}
+} /* node:coverage ignore next 7 */
 
 
 export {