aontu 0.52.1 → 0.54.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (310) hide show
  1. package/README.md +88 -0
  2. package/bin/aontu-mcp.js +4 -0
  3. package/dist/agentsmd.d.ts +16 -0
  4. package/dist/agentsmd.js +107 -0
  5. package/dist/agentsmd.js.map +1 -0
  6. package/dist/aontu.d.ts +15 -3
  7. package/dist/aontu.js +126 -5
  8. package/dist/aontu.js.map +1 -1
  9. package/dist/cli.d.ts +45 -1
  10. package/dist/cli.js +2845 -69
  11. package/dist/cli.js.map +1 -1
  12. package/dist/ctx.d.ts +18 -0
  13. package/dist/ctx.js +44 -0
  14. package/dist/ctx.js.map +1 -1
  15. package/dist/diff.d.ts +22 -0
  16. package/dist/diff.js +141 -0
  17. package/dist/diff.js.map +1 -0
  18. package/dist/err.d.ts +3 -1
  19. package/dist/err.js +45 -8
  20. package/dist/err.js.map +1 -1
  21. package/dist/graph.d.ts +13 -0
  22. package/dist/graph.js +110 -0
  23. package/dist/graph.js.map +1 -0
  24. package/dist/hcanon.d.ts +3 -0
  25. package/dist/hcanon.js +145 -0
  26. package/dist/hcanon.js.map +1 -0
  27. package/dist/hints.js +235 -8
  28. package/dist/hints.js.map +1 -1
  29. package/dist/jsonschema.d.ts +20 -0
  30. package/dist/jsonschema.js +425 -0
  31. package/dist/jsonschema.js.map +1 -0
  32. package/dist/lang.js +955 -110
  33. package/dist/lang.js.map +1 -1
  34. package/dist/lsp.d.ts +9 -2
  35. package/dist/lsp.js +343 -48
  36. package/dist/lsp.js.map +1 -1
  37. package/dist/mcp-server.d.ts +20 -0
  38. package/dist/mcp-server.js +147 -0
  39. package/dist/mcp-server.js.map +1 -0
  40. package/dist/mcp.d.ts +42 -0
  41. package/dist/mcp.js +941 -0
  42. package/dist/mcp.js.map +1 -0
  43. package/dist/mod-tool.d.ts +58 -0
  44. package/dist/mod-tool.js +532 -0
  45. package/dist/mod-tool.js.map +1 -0
  46. package/dist/mod.d.ts +35 -0
  47. package/dist/mod.js +345 -0
  48. package/dist/mod.js.map +1 -0
  49. package/dist/patch.d.ts +49 -0
  50. package/dist/patch.js +506 -0
  51. package/dist/patch.js.map +1 -0
  52. package/dist/provenance.d.ts +41 -0
  53. package/dist/provenance.js +336 -0
  54. package/dist/provenance.js.map +1 -0
  55. package/dist/query.d.ts +27 -0
  56. package/dist/query.js +294 -0
  57. package/dist/query.js.map +1 -0
  58. package/dist/reach.d.ts +15 -0
  59. package/dist/reach.js +168 -0
  60. package/dist/reach.js.map +1 -0
  61. package/dist/relation.d.ts +23 -0
  62. package/dist/relation.js +230 -0
  63. package/dist/relation.js.map +1 -0
  64. package/dist/report-sarif.d.ts +14 -0
  65. package/dist/report-sarif.js +102 -0
  66. package/dist/report-sarif.js.map +1 -0
  67. package/dist/sig.d.ts +25 -0
  68. package/dist/sig.js +277 -0
  69. package/dist/sig.js.map +1 -0
  70. package/dist/sigdecl.d.ts +2 -0
  71. package/dist/sigdecl.js +11 -0
  72. package/dist/sigdecl.js.map +1 -0
  73. package/dist/siggate.d.ts +4 -0
  74. package/dist/siggate.js +90 -0
  75. package/dist/siggate.js.map +1 -0
  76. package/dist/site.d.ts +4 -0
  77. package/dist/site.js +31 -0
  78. package/dist/site.js.map +1 -1
  79. package/dist/std.d.ts +1 -0
  80. package/dist/std.js +129 -0
  81. package/dist/std.js.map +1 -0
  82. package/dist/subsume.d.ts +39 -0
  83. package/dist/subsume.js +573 -0
  84. package/dist/subsume.js.map +1 -0
  85. package/dist/trim.d.ts +19 -0
  86. package/dist/trim.js +155 -0
  87. package/dist/trim.js.map +1 -0
  88. package/dist/tsconfig.tsbuildinfo +1 -1
  89. package/dist/type.d.ts +17 -1
  90. package/dist/type.js.map +1 -1
  91. package/dist/unify.d.ts +2 -1
  92. package/dist/unify.js +234 -38
  93. package/dist/unify.js.map +1 -1
  94. package/dist/utility.d.ts +8 -1
  95. package/dist/utility.js +68 -1
  96. package/dist/utility.js.map +1 -1
  97. package/dist/val/AggFuncVal.d.ts +44 -0
  98. package/dist/val/AggFuncVal.js +364 -0
  99. package/dist/val/AggFuncVal.js.map +1 -0
  100. package/dist/val/ArithFuncVal.d.ts +31 -0
  101. package/dist/val/ArithFuncVal.js +62 -0
  102. package/dist/val/ArithFuncVal.js.map +1 -0
  103. package/dist/val/BagVal.d.ts +7 -0
  104. package/dist/val/BagVal.js +150 -11
  105. package/dist/val/BagVal.js.map +1 -1
  106. package/dist/val/CloseFuncVal.js +9 -1
  107. package/dist/val/CloseFuncVal.js.map +1 -1
  108. package/dist/val/ConjunctVal.d.ts +1 -1
  109. package/dist/val/ConjunctVal.js +19 -0
  110. package/dist/val/ConjunctVal.js.map +1 -1
  111. package/dist/val/ConstraintVal.d.ts +7 -1
  112. package/dist/val/ConstraintVal.js +523 -45
  113. package/dist/val/ConstraintVal.js.map +1 -1
  114. package/dist/val/ContainerKindVal.d.ts +35 -0
  115. package/dist/val/ContainerKindVal.js +99 -0
  116. package/dist/val/ContainerKindVal.js.map +1 -0
  117. package/dist/val/CopyFuncVal.d.ts +1 -2
  118. package/dist/val/CopyFuncVal.js.map +1 -1
  119. package/dist/val/Decimal.d.ts +1 -0
  120. package/dist/val/Decimal.js +13 -0
  121. package/dist/val/Decimal.js.map +1 -1
  122. package/dist/val/DeprecateFuncVal.d.ts +11 -0
  123. package/dist/val/DeprecateFuncVal.js +47 -0
  124. package/dist/val/DeprecateFuncVal.js.map +1 -0
  125. package/dist/val/DisjunctVal.d.ts +1 -2
  126. package/dist/val/DisjunctVal.js +269 -53
  127. package/dist/val/DisjunctVal.js.map +1 -1
  128. package/dist/val/EachFuncVal.d.ts +15 -0
  129. package/dist/val/EachFuncVal.js +75 -0
  130. package/dist/val/EachFuncVal.js.map +1 -0
  131. package/dist/val/ExpectVal.js +62 -4
  132. package/dist/val/ExpectVal.js.map +1 -1
  133. package/dist/val/FeatureVal.js +1 -1
  134. package/dist/val/FeatureVal.js.map +1 -1
  135. package/dist/val/FilterFuncVal.d.ts +15 -0
  136. package/dist/val/FilterFuncVal.js +91 -0
  137. package/dist/val/FilterFuncVal.js.map +1 -0
  138. package/dist/val/FuncBaseVal.d.ts +7 -1
  139. package/dist/val/FuncBaseVal.js +183 -2
  140. package/dist/val/FuncBaseVal.js.map +1 -1
  141. package/dist/val/GraphAtomVal.d.ts +39 -0
  142. package/dist/val/GraphAtomVal.js +184 -0
  143. package/dist/val/GraphAtomVal.js.map +1 -0
  144. package/dist/val/HideFuncVal.js.map +1 -1
  145. package/dist/val/JunctionVal.js +24 -1
  146. package/dist/val/JunctionVal.js.map +1 -1
  147. package/dist/val/KeyFuncVal.d.ts +1 -1
  148. package/dist/val/KeyFuncVal.js +38 -30
  149. package/dist/val/KeyFuncVal.js.map +1 -1
  150. package/dist/val/ListVal.js +94 -14
  151. package/dist/val/ListVal.js.map +1 -1
  152. package/dist/val/LowerFuncVal.js.map +1 -1
  153. package/dist/val/MapVal.d.ts +1 -0
  154. package/dist/val/MapVal.js +146 -14
  155. package/dist/val/MapVal.js.map +1 -1
  156. package/dist/val/MatchFuncVal.d.ts +15 -0
  157. package/dist/val/MatchFuncVal.js +107 -0
  158. package/dist/val/MatchFuncVal.js.map +1 -0
  159. package/dist/val/MoveFuncVal.js.map +1 -1
  160. package/dist/val/NilVal.js +24 -0
  161. package/dist/val/NilVal.js.map +1 -1
  162. package/dist/val/OpBaseVal.d.ts +1 -1
  163. package/dist/val/OpBaseVal.js +19 -1
  164. package/dist/val/OpBaseVal.js.map +1 -1
  165. package/dist/val/OpenFuncVal.js +4 -1
  166. package/dist/val/OpenFuncVal.js.map +1 -1
  167. package/dist/val/PackFuncVal.d.ts +15 -0
  168. package/dist/val/PackFuncVal.js +108 -0
  169. package/dist/val/PackFuncVal.js.map +1 -0
  170. package/dist/val/PathFuncVal.d.ts +2 -2
  171. package/dist/val/PathFuncVal.js +75 -16
  172. package/dist/val/PathFuncVal.js.map +1 -1
  173. package/dist/val/PathVal.d.ts +25 -0
  174. package/dist/val/PathVal.js +150 -0
  175. package/dist/val/PathVal.js.map +1 -0
  176. package/dist/val/PlaceVal.d.ts +13 -0
  177. package/dist/val/PlaceVal.js +131 -0
  178. package/dist/val/PlaceVal.js.map +1 -0
  179. package/dist/val/PlusOpVal.d.ts +2 -1
  180. package/dist/val/PlusOpVal.js +61 -37
  181. package/dist/val/PlusOpVal.js.map +1 -1
  182. package/dist/val/PrefFuncVal.js.map +1 -1
  183. package/dist/val/PrefVal.d.ts +4 -2
  184. package/dist/val/PrefVal.js +223 -41
  185. package/dist/val/PrefVal.js.map +1 -1
  186. package/dist/val/RecurseVal.d.ts +19 -0
  187. package/dist/val/RecurseVal.js +217 -0
  188. package/dist/val/RecurseVal.js.map +1 -0
  189. package/dist/val/RefVal.d.ts +3 -2
  190. package/dist/val/RefVal.js +181 -66
  191. package/dist/val/RefVal.js.map +1 -1
  192. package/dist/val/ReferFuncVal.d.ts +59 -0
  193. package/dist/val/ReferFuncVal.js +604 -0
  194. package/dist/val/ReferFuncVal.js.map +1 -0
  195. package/dist/val/ScalarKindVal.d.ts +4 -3
  196. package/dist/val/ScalarKindVal.js +12 -12
  197. package/dist/val/ScalarKindVal.js.map +1 -1
  198. package/dist/val/SuperFuncVal.d.ts +4 -2
  199. package/dist/val/SuperFuncVal.js +118 -14
  200. package/dist/val/SuperFuncVal.js.map +1 -1
  201. package/dist/val/TopVal.d.ts +1 -1
  202. package/dist/val/TopVal.js.map +1 -1
  203. package/dist/val/TypeFuncVal.js.map +1 -1
  204. package/dist/val/UpperFuncVal.js.map +1 -1
  205. package/dist/val/Val.d.ts +7 -1
  206. package/dist/val/Val.js +170 -2
  207. package/dist/val/Val.js.map +1 -1
  208. package/dist/val/VarVal.js.map +1 -1
  209. package/dist/val/arith.d.ts +6 -0
  210. package/dist/val/arith.js +173 -0
  211. package/dist/val/arith.js.map +1 -0
  212. package/dist/vet.d.ts +45 -0
  213. package/dist/vet.js +802 -0
  214. package/dist/vet.js.map +1 -0
  215. package/dist/view.d.ts +85 -0
  216. package/dist/view.js +1948 -0
  217. package/dist/view.js.map +1 -0
  218. package/dist/walk.d.ts +2 -0
  219. package/dist/walk.js +91 -0
  220. package/dist/walk.js.map +1 -0
  221. package/grammar/aontu.gbnf +138 -0
  222. package/grammar/aontu.lark +118 -0
  223. package/grammar/aontu.tmLanguage.json +184 -0
  224. package/package.json +30 -8
  225. package/skill/SKILL.md +37 -0
  226. package/skill/error-codes.md +62 -0
  227. package/skill/examples.md +99 -0
  228. package/skill/grammar-card.md +56 -0
  229. package/src/agentsmd.ts +135 -0
  230. package/src/aontu.ts +166 -5
  231. package/src/cli.ts +3324 -72
  232. package/src/ctx.ts +93 -1
  233. package/src/diff.ts +198 -0
  234. package/src/err.ts +50 -8
  235. package/src/graph.ts +185 -0
  236. package/src/hcanon.ts +167 -0
  237. package/src/hints.ts +291 -8
  238. package/src/jsonschema.ts +552 -0
  239. package/src/lang.ts +1049 -110
  240. package/src/lsp.ts +351 -49
  241. package/src/mcp-server.ts +187 -0
  242. package/src/mcp.ts +1130 -0
  243. package/src/mod-tool.ts +718 -0
  244. package/src/mod.ts +453 -0
  245. package/src/patch.ts +628 -0
  246. package/src/provenance.ts +437 -0
  247. package/src/query.ts +381 -0
  248. package/src/reach.ts +213 -0
  249. package/src/relation.ts +298 -0
  250. package/src/report-sarif.ts +137 -0
  251. package/src/sig.ts +345 -0
  252. package/src/sigdecl.ts +11 -0
  253. package/src/siggate.ts +144 -0
  254. package/src/site.ts +36 -1
  255. package/src/std.ts +131 -0
  256. package/src/subsume.ts +739 -0
  257. package/src/trim.ts +195 -0
  258. package/src/tsconfig.json +10 -4
  259. package/src/type.ts +51 -2
  260. package/src/unify.ts +253 -38
  261. package/src/utility.ts +79 -1
  262. package/src/val/AggFuncVal.ts +546 -0
  263. package/src/val/ArithFuncVal.ts +108 -0
  264. package/src/val/BagVal.ts +158 -12
  265. package/src/val/CloseFuncVal.ts +9 -1
  266. package/src/val/ConjunctVal.ts +20 -0
  267. package/src/val/ConstraintVal.ts +576 -48
  268. package/src/val/ContainerKindVal.ts +158 -0
  269. package/src/val/CopyFuncVal.ts +0 -1
  270. package/src/val/Decimal.ts +15 -0
  271. package/src/val/DeprecateFuncVal.ts +84 -0
  272. package/src/val/DisjunctVal.ts +282 -59
  273. package/src/val/EachFuncVal.ts +133 -0
  274. package/src/val/ExpectVal.ts +65 -8
  275. package/src/val/FeatureVal.ts +1 -1
  276. package/src/val/FilterFuncVal.ts +154 -0
  277. package/src/val/FuncBaseVal.ts +206 -2
  278. package/src/val/GraphAtomVal.ts +264 -0
  279. package/src/val/HideFuncVal.ts +0 -2
  280. package/src/val/JunctionVal.ts +24 -1
  281. package/src/val/KeyFuncVal.ts +39 -35
  282. package/src/val/ListVal.ts +101 -15
  283. package/src/val/LowerFuncVal.ts +0 -1
  284. package/src/val/MapVal.ts +153 -14
  285. package/src/val/MatchFuncVal.ts +176 -0
  286. package/src/val/MoveFuncVal.ts +0 -2
  287. package/src/val/NilVal.ts +25 -0
  288. package/src/val/OpBaseVal.ts +20 -1
  289. package/src/val/OpenFuncVal.ts +4 -2
  290. package/src/val/PackFuncVal.ts +175 -0
  291. package/src/val/PathFuncVal.ts +107 -20
  292. package/src/val/PathVal.ts +221 -0
  293. package/src/val/PlaceVal.ts +193 -0
  294. package/src/val/PlusOpVal.ts +67 -39
  295. package/src/val/PrefFuncVal.ts +0 -1
  296. package/src/val/PrefVal.ts +251 -60
  297. package/src/val/RecurseVal.ts +285 -0
  298. package/src/val/RefVal.ts +183 -78
  299. package/src/val/ReferFuncVal.ts +732 -0
  300. package/src/val/ScalarKindVal.ts +12 -13
  301. package/src/val/SuperFuncVal.ts +137 -13
  302. package/src/val/TopVal.ts +1 -2
  303. package/src/val/TypeFuncVal.ts +0 -2
  304. package/src/val/UpperFuncVal.ts +0 -1
  305. package/src/val/Val.ts +216 -4
  306. package/src/val/VarVal.ts +0 -1
  307. package/src/val/arith.ts +319 -0
  308. package/src/vet.ts +1025 -0
  309. package/src/view.ts +2563 -0
  310. package/src/walk.ts +99 -0
@@ -0,0 +1,546 @@
1
+ /* Copyright (c) 2025 Richard Rodger, MIT License */
2
+
3
+ // AGGREGATION, PROJECTION AND THE STRING FOLD: `sum(d)`, `least(d)`,
4
+ // `greatest(d)`, `pick(d, k)` and `join(d, sep?)`.
5
+ //
6
+ // The review's finding I: "No aggregation. `length()` counts but
7
+ // nothing sums: an invoice total, a fleet-wide resource budget, a quota
8
+ // roll-up -- all inexpressible." Use case 10 had to write totals by
9
+ // hand and spot-check them with `must()`, which is a model asserting
10
+ // what it should be able to COMPUTE.
11
+ //
12
+ // total: sum($.lines) # an invoice total
13
+ // cheapest: least($.quotes) # ... and the extremes
14
+ // peak: greatest($.hourly)
15
+ //
16
+ // A FOLD OVER A FINITE, SETTLED BAG IS AS TOTAL AS `each`. There is no
17
+ // recursion here and no user-supplied step: the bag is the one the
18
+ // model already holds, the operation is fixed, and the walk visits each
19
+ // child exactly once. That is the whole reason these are built-ins
20
+ // rather than a `fold` combinator -- a fold takes a function, and a
21
+ // language with no user functions has none to take.
22
+ //
23
+ // THE NAMES ARE `least` AND `greatest`, NOT `min` AND `max`, because
24
+ // those two are already the constraint atoms for a LOWER and UPPER
25
+ // BOUND (`min(3)` means "at least 3"). An aggregate over a bag and a
26
+ // bound on a value are different things and must not share a spelling;
27
+ // least and greatest are the lattice's own words for the extremes of a
28
+ // set, which is exactly what these compute.
29
+ //
30
+ // `sum` FOLDS WITH `add`, so the number tower's whole law comes with it
31
+ // (arith.ts): the exact ladder, R5 contagion, the refusal to mix a
32
+ // binary float with an exact leaf, and the refusal to store a result
33
+ // that will not fit. A bag of integers sums to an integer; one integer
34
+ // float among them makes the total a float; `0d` operands keep it
35
+ // exact. And `sum([])` is `0` -- addition has an identity, which is
36
+ // what makes the empty case answerable.
37
+ //
38
+ // `least`/`greatest` have NO identity to answer an empty bag with: the
39
+ // least element of nothing is not a value, it is a question with no
40
+ // answer, so an empty bag is a located `aggregate_empty` rather than an
41
+ // invented zero or infinity. They compare with the tower's EXACT
42
+ // comparator (numcmp), so an integer and a bigdecimal in one bag order
43
+ // correctly rather than through binary64, and the winner is returned
44
+ // with its own kind intact.
45
+
46
+ import type {
47
+ Val,
48
+ ValSpec,
49
+ } from '../type'
50
+
51
+ import {
52
+ AontuContext,
53
+ } from '../ctx'
54
+
55
+ import { makeNilErr } from '../err'
56
+ import { IntegerVal } from './IntegerVal'
57
+ import { ListVal } from './ListVal'
58
+ import { StringVal } from './StringVal'
59
+ import { FuncBaseVal } from './FuncBaseVal'
60
+ import { arith } from './arith'
61
+ import { cmpNumeric } from './numcmp'
62
+ import { cmpCodePoint } from '../keyorder'
63
+ import { plusText } from './PlusOpVal'
64
+
65
+
66
+ type AggOp = 'sum' | 'least' | 'greatest'
67
+
68
+
69
+ // The children of a bag, in the order the aggregate sees them: source
70
+ // order for a list, sorted-key order for a map -- `each`'s order, and
71
+ // for the same reason (a map has no order of its own, so the language
72
+ // picks one and states it).
73
+ function bagChildren(data: any): Val[] | undefined {
74
+ if (true === data?.isList) {
75
+ return data.peg as Val[]
76
+ }
77
+ if (true === data?.isMap) {
78
+ // THE ONE MAP-KEY ORDER (../keyorder.ts), not a bare `.sort()`:
79
+ // JavaScript compares by UTF-16 code unit, so an astral key's
80
+ // leading surrogate sorts BELOW U+E000-U+FFFF and `pick` answered
81
+ // in a different order from `each`, from canon, and from Go --
82
+ // which sorts UTF-8 bytes, i.e. code points. `pick` is the
83
+ // order-preserving projection, so that was one model producing two
84
+ // different generated files (BUGS.md 62).
85
+ return Object.keys(data.peg).sort(cmpCodePoint).map((k: string) => data.peg[k])
86
+ }
87
+ return undefined
88
+ }
89
+
90
+
91
+ class AggFuncVal extends FuncBaseVal {
92
+ isAggFunc = true
93
+
94
+ // THE STAGING RULE (G8 phase 0). A total over a bag that is still
95
+ // being merged into is a total of the wrong bag -- the same reason
96
+ // `filter` and `each` wait.
97
+ staged = true
98
+
99
+ op: AggOp
100
+
101
+ constructor(
102
+ spec: ValSpec,
103
+ ctx: AontuContext | undefined,
104
+ op: AggOp
105
+ ) {
106
+ super(spec, ctx)
107
+ this.op = op
108
+ }
109
+
110
+
111
+ // NO `make` OVERRIDE, matching the other STAGED funcs (pack, each,
112
+ // filter, match): a staged call returns `residuate` before `unify`
113
+ // ever reaches the rebuild branch, so an override there would be
114
+ // unreachable code pretending to be a contract. The base's `make`
115
+ // raises `func:<name>` if that ever stops being true, which is the
116
+ // loud answer rather than a value that silently lost its operation.
117
+
118
+ funcname() {
119
+ return this.op
120
+ }
121
+
122
+
123
+ // The base does not drive the argument: `unify` drives it by hand,
124
+ // because a staged func must advance what it is waiting on every
125
+ // pass rather than only on the pass it fires.
126
+ prepare(_ctx: AontuContext, _args: Val[]) {
127
+ return null
128
+ }
129
+
130
+
131
+ unify(peer: Val, ctx: AontuContext): Val {
132
+ const ready = this.driveStagedArgs(ctx, 1)
133
+
134
+ if (!ready || !ctx.settle) {
135
+ return this.residuate(peer, ctx)
136
+ }
137
+
138
+ return super.unify(peer, ctx)
139
+ }
140
+
141
+
142
+ resolve(ctx: AontuContext, args: Val[]) {
143
+ const children = bagChildren(args?.[0])
144
+
145
+ if (undefined === children) {
146
+ return this.place(makeNilErr(ctx, 'aggregate_data', this, undefined,
147
+ this.op))
148
+ }
149
+
150
+ if ('sum' === this.op) {
151
+ // Zero is addition's identity, so an empty bag has an answer and
152
+ // it is an integer -- the narrowest kind, which the first real
153
+ // operand then widens under R5 exactly as `add(0, x)` would.
154
+ let total: Val = new IntegerVal({ peg: 0 })
155
+ for (const child of children) {
156
+ total = arith(ctx, 'add', this, total, child, this.op)
157
+ // A refusal inside the fold IS the answer: adding on past a
158
+ // non-numeric child or an overflow would report the wrong
159
+ // reason, or none.
160
+ if (true === (total as any).isNil) {
161
+ return this.place(total)
162
+ }
163
+ }
164
+ return this.place(total)
165
+ }
166
+
167
+ if (0 === children.length) {
168
+ return this.place(makeNilErr(ctx, 'aggregate_empty', this, undefined,
169
+ this.op))
170
+ }
171
+
172
+ const want = 'least' === this.op ? -1 : 1
173
+ let best: any = undefined
174
+ for (const child of children) {
175
+ const c: any = unpref(child)
176
+ if (!(c?.isVal && c.isScalar && 'string' !== typeof c.peg &&
177
+ 'boolean' !== typeof c.peg && !c.isNull)) {
178
+ return this.place(makeNilErr(ctx, 'invalid-arg', this, undefined,
179
+ this.op))
180
+ }
181
+ // The EXACT comparator (numcmp), never binary64: a bigdecimal and
182
+ // an integer in one bag must order by their values and not by
183
+ // whatever their float images happen to be.
184
+ if (undefined === best || want === cmpNumeric(c, best)) {
185
+ best = c
186
+ }
187
+ }
188
+ // The winner is returned as itself, so it keeps its own kind: the
189
+ // least of a bag of bigdecimals is a bigdecimal.
190
+ return this.place(best.clone(ctx))
191
+ }
192
+ }
193
+
194
+
195
+ // A pref child contributes its preferred value, and therefore that
196
+ // value's kind too -- the rule `+` and the arithmetic family apply to
197
+ // operands, applied here to bag members.
198
+ function unpref(v: any): any {
199
+ while (v?.isPref) {
200
+ v = v.peg
201
+ }
202
+ return v
203
+ }
204
+
205
+
206
+ // PROJECTION: `pick(d, k)` -- one element per child of `d`, being that
207
+ // child's `k`.
208
+ //
209
+ // The other half of the review's finding I: "`_.field` is unspellable,
210
+ // `filter` cannot see into lists, `unique()`-by-field is reserved but
211
+ // absent -- so 'no two services share a port' and 'unique event ids'
212
+ // cannot be said." Without it the aggregates above cannot reach the
213
+ // case that motivated them, because `sum` needs a bag of NUMBERS and a
214
+ // model holds a bag of RECORDS:
215
+ //
216
+ // total: sum(pick($.lines, amountCents))
217
+ //
218
+ // IT IS NOT `each` WITH A CLEVER TEMPLATE. `each(d, t)` MEETS each
219
+ // child with `t`, and a meet cannot select: `each($.lines, _.amount)`
220
+ // asks for a child that is simultaneously the whole record and one of
221
+ // its fields, which is why every spelling of it answers `no_path`.
222
+ // Selection is a different operation and gets its own verb.
223
+ //
224
+ // A CHILD MISSING THE KEY IS AN ERROR, not a silently shorter list.
225
+ // Skipping would make `sum(pick(...))` quietly total the wrong set of
226
+ // records -- the failure mode an aggregate exists to prevent -- so the
227
+ // refusal names the child (`pick_key`).
228
+ class PickFuncVal extends FuncBaseVal {
229
+ isPickFunc = true
230
+
231
+ // The bag must settle before it is projected, exactly as it must
232
+ // before it is folded.
233
+ staged = true
234
+
235
+ constructor(
236
+ spec: ValSpec,
237
+ ctx?: AontuContext
238
+ ) {
239
+ super(spec, ctx)
240
+ }
241
+
242
+
243
+ funcname() {
244
+ return 'pick'
245
+ }
246
+
247
+
248
+ // The base drives neither argument: the DATA is driven by hand below
249
+ // (a staged func must advance what it waits on every pass), and the
250
+ // KEY is a bare word, which the parser has already made a string.
251
+ prepare(_ctx: AontuContext, _args: Val[]) {
252
+ return null
253
+ }
254
+
255
+
256
+ unify(peer: Val, ctx: AontuContext): Val {
257
+ const ready = this.driveStagedArgs(ctx, 1)
258
+
259
+ if (!ready || !ctx.settle) {
260
+ return this.residuate(peer, ctx)
261
+ }
262
+
263
+ return super.unify(peer, ctx)
264
+ }
265
+
266
+
267
+ resolve(ctx: AontuContext, args: Val[]) {
268
+ const children = bagChildren(args?.[0])
269
+ const key: any = args?.[1]
270
+
271
+ if (undefined === children) {
272
+ return this.place(makeNilErr(ctx, 'aggregate_data', this, undefined,
273
+ 'pick'))
274
+ }
275
+
276
+ // The key is a STRING for a map child and the decimal spelling of an
277
+ // index for a list child -- the same rule a reference segment
278
+ // follows, so `pick(d, 0)` and `$.d.0.x` agree about what `0` names.
279
+ const name = null == key?.peg ? undefined :
280
+ 'string' === typeof key.peg ? key.peg :
281
+ 'number' === typeof key.peg && key.isInteger ? String(key.peg) :
282
+ undefined
283
+
284
+ if (undefined === name) {
285
+ return this.place(makeNilErr(ctx, 'invalid-arg', this, undefined,
286
+ 'pick'))
287
+ }
288
+
289
+ const peg: Val[] = []
290
+ for (const child of children) {
291
+ const c: any = child
292
+ const got =
293
+ true === c?.isMap ? c.peg[name] :
294
+ true === c?.isList ? c.peg[Number(name)] :
295
+ undefined
296
+ if (null == got) {
297
+ return this.place(makeNilErr(ctx, 'pick_key', this, undefined, 'pick',
298
+ { key: name }))
299
+ }
300
+ peg.push(got.clone(ctx.descend(String(peg.length))))
301
+ }
302
+ return this.place(new ListVal({ peg }, ctx))
303
+ }
304
+ }
305
+
306
+
307
+
308
+ // THE FOLD TO A STRING: `join(coll, sep?)` -- G9 phase 2.
309
+ //
310
+ // The one primitive between a model and a generated file. A spread can
311
+ // put a separator AFTER each element; putting one BETWEEN N elements is
312
+ // a reduction over strings, and the language had none: `sum` is numeric,
313
+ // `+` does not reduce a list, and indexed concatenation needs the arity
314
+ // known in advance. So a generated SQL column list carried a trailing
315
+ // comma and did not parse (use-cases/15-code-generation).
316
+ //
317
+ // IT FOLDS WITH `+` SEEDED WITH `""`, exactly as `sum` folds with `add`
318
+ // seeded with `0`. That is not a figure of speech: the members are
319
+ // rendered by `plusText`, which IS the function `+`'s string branch
320
+ // calls, so the language keeps exactly one answer to "how does a number
321
+ // become text" and the two cannot drift. `join(coll)` is therefore
322
+ // concatenation and no `concat` is needed; `join(coll, "\n")` is lines
323
+ // and no `lines` is needed. ONE BUILTIN, NOT A FAMILY.
324
+ //
325
+ // `split`/`words` is the inverse -- an input-PARSING operation with no
326
+ // generation use -- and is deliberately absent.
327
+ //
328
+ // EMPTY IS `""`, concatenation's identity, the exact parallel of
329
+ // `sum([]) == 0` and the opposite of `least([])`: a fold with an
330
+ // identity can answer the empty bag, and one without has to refuse it.
331
+ //
332
+ // MEMBERS ARE VALIDATED BEFORE THE FOLD, which is the whole reason this
333
+ // is not three lines. `+` with a string on the left RESIDUATES on a
334
+ // container or a null rather than refusing (`"" + {b:1}` and `"x" +
335
+ // null` both reach generation as `mapval_no_gen`), so folding blindly
336
+ // would turn a bad member into a useless late error pointing at the
337
+ // wrong thing. The three verdicts below are that check.
338
+ type MemberVerdict = 'text' | 'never' | 'notyet'
339
+
340
+
341
+ // Which of the three a value is.
342
+ //
343
+ // `text` -- `+` would take it, so the fold can.
344
+ //
345
+ // `never` -- a SETTLED value that will never become text: a map, a
346
+ // list, a null. This is `join_member`, class `conflict`, and it names
347
+ // the member rather than the call, because "one of these is not a
348
+ // string" is only actionable if you are told which.
349
+ //
350
+ // `notyet` -- an unresolved kind, a top, a stable residue. NOT a join
351
+ // failure at all: the call stays residual and generation reports
352
+ // `mapval_no_gen`, class `incomplete`, exactly as docs/trust.md
353
+ // requires ("a stable residue ... is ordinary incompleteness"). Getting
354
+ // this split wrong in either direction is the defect that matters here:
355
+ // refusing a residue makes `join` unusable inside a schema, and
356
+ // deferring on a map makes a real error arrive as a shrug.
357
+ function memberVerdict(v: any): MemberVerdict {
358
+ const u = unpref(v)
359
+ if (undefined !== plusText(u)) {
360
+ return 'text'
361
+ }
362
+ if (true === u?.isMap || true === u?.isList || true === u?.isNull) {
363
+ return 'never'
364
+ }
365
+ return 'notyet'
366
+ }
367
+
368
+
369
+ // The separator is a STRING or it is nothing.
370
+ //
371
+ // A number would render perfectly well through `+`, and is still
372
+ // refused: the separator is not a member of the fold, it is the
373
+ // parameter naming the text between members, and `join(x, 5)` is far
374
+ // likelier a mistake than an intent to separate with "5". `pick`'s key
375
+ // argument draws the same line for the same reason. This is the
376
+ // direction that can be loosened later without breaking a document;
377
+ // the other direction cannot.
378
+ function sepVerdict(v: any): MemberVerdict {
379
+ const u = unpref(v)
380
+ if (u?.isVal && u.isScalar) {
381
+ return 'string' === typeof u.peg ? 'text' : 'never'
382
+ }
383
+ if (true === u?.isMap || true === u?.isList || true === u?.isNull) {
384
+ return 'never'
385
+ }
386
+ return 'notyet'
387
+ }
388
+
389
+
390
+ class JoinFuncVal extends FuncBaseVal {
391
+ isJoinFunc = true
392
+
393
+ // The bag must settle before it is folded, exactly as it must before
394
+ // it is summed or projected.
395
+ staged = true
396
+
397
+ constructor(
398
+ spec: ValSpec,
399
+ ctx?: AontuContext
400
+ ) {
401
+ super(spec, ctx)
402
+ }
403
+
404
+
405
+ // A `make` OVERRIDE, WHERE ITS AggFuncVal SIBLINGS HAVE NONE, and the
406
+ // difference is worth stating because it is not arbitrary. `sum`,
407
+ // `pick` and the rest are staged and nothing more: they residuate
408
+ // before `unify` reaches the rebuild branch, so a `make` there would
409
+ // be unreachable code pretending to be a contract, and the base's
410
+ // `func:<name>` refusal is the loud answer if that ever changes.
411
+ //
412
+ // `join` is the first builtin that is BOTH staged AND defers its
413
+ // resolution (see `deferResolve`). A deferred call has settled
414
+ // arguments, so it does reach the rebuild branch, and without this it
415
+ // raised `func:join` on the first document with an unresolved member
416
+ // — where the Go port residuated and reported `mapval_no_gen`.
417
+ // Opposite answers on `join($.m, ",")` with `m: [string]`, caught by
418
+ // running both engines rather than by either test suite. `super` and
419
+ // bare `id`, the two other deferring calls, each carry the same
420
+ // override for the same reason.
421
+ make(_ctx: AontuContext, spec: ValSpec): Val {
422
+ return new JoinFuncVal(spec)
423
+ }
424
+
425
+
426
+ funcname() {
427
+ return 'join'
428
+ }
429
+
430
+
431
+ // The base does not drive: `unify` drives by hand, because a staged
432
+ // func must advance what it is waiting on every pass rather than only
433
+ // on the pass it fires.
434
+ prepare(_ctx: AontuContext, _args: Val[]) {
435
+ return null
436
+ }
437
+
438
+
439
+ unify(peer: Val, ctx: AontuContext): Val {
440
+ // BOTH arguments, unlike `pick`, which drives only its bag: `pick`'s
441
+ // key is a bare word the parser has already made a string, while a
442
+ // separator is an ordinary expression and `join($.rows, $.sep)` has
443
+ // to wait for it.
444
+ const ready = this.driveStagedArgs(ctx, 2)
445
+
446
+ if (!ready || !ctx.settle) {
447
+ return this.residuate(peer, ctx)
448
+ }
449
+
450
+ return super.unify(peer, ctx)
451
+ }
452
+
453
+
454
+ // The `notyet` half of the verdict, taken before `resolve` runs: with
455
+ // arguments settled but a member still a kind, the call rides the
456
+ // ordinary args-not-done path and residuates, which is what makes an
457
+ // unresolved member ordinary incompleteness rather than a refusal.
458
+ deferResolve(_ctx: AontuContext, args?: Val[]): boolean {
459
+ const children = bagChildren(args?.[0])
460
+ if (undefined === children) {
461
+ // Not a bag at all: let `resolve` say so rather than waiting for
462
+ // a settling that has already happened.
463
+ return false
464
+ }
465
+ const sep = args?.[1]
466
+ if (undefined !== sep && 'notyet' === sepVerdict(sep)) {
467
+ return true
468
+ }
469
+ return children.some((c) => 'notyet' === memberVerdict(c))
470
+ }
471
+
472
+
473
+ resolve(ctx: AontuContext, args: Val[]) {
474
+ const children = bagChildren(args?.[0])
475
+
476
+ if (undefined === children) {
477
+ return this.place(makeNilErr(ctx, 'aggregate_data', this, undefined,
478
+ 'join'))
479
+ }
480
+
481
+ // Arity is [1,2], so a second argument is present or the separator
482
+ // is the empty string -- which makes `join(coll)` concatenation.
483
+ // The separator's SHAPE is settled before resolve runs: the
484
+ // signature gate refuses every concrete non-string
485
+ // (docs/design/SIGNATURES.0.md; join(d: map|list, sep?: string)),
486
+ // and deferResolve holds the call while sepVerdict answers notyet
487
+ // -- so a present separator here is text.
488
+ let sep = ''
489
+ if (1 < args.length) {
490
+ sep = unpref(args[1]).peg
491
+ }
492
+
493
+ // NO NIL-MEMBER GUARD, WHERE `sum` HAS ONE, and the difference is
494
+ // the fold's shape rather than an oversight. `sum` folds with
495
+ // `arith`, which MINTS a nil part-way through — a non-numeric child
496
+ // or an overflow — so it has to stop and return it. `join` folds
497
+ // already-unified values, and a nil among a list's elements
498
+ // collapses the list before this call resolves: `join([least([])],
499
+ // ",")` reports `aggregate_empty` at the member's own path,
500
+ // `$.o.0`, and never reaches here. A guard was written, the
501
+ // ADR-002 gate found it unexecuted, and probing confirmed no
502
+ // spelling reaches it, so it is removed rather than excused.
503
+ const parts: string[] = []
504
+ for (const child of children) {
505
+ const u: any = unpref(child)
506
+ const text = plusText(u)
507
+ if (undefined === text) {
508
+ return this.place(makeNilErr(ctx, 'join_member', this, undefined,
509
+ 'join', { member: String(u?.canon) }))
510
+ }
511
+ parts.push(text)
512
+ }
513
+
514
+ // Every part is already a string, so this IS the `+` fold seeded
515
+ // with `""` -- written as one concatenation because a loop of `+`
516
+ // over settled strings cannot differ from it, and because the Go
517
+ // twin's strings.Join must produce the same bytes.
518
+ return this.place(new StringVal({ peg: parts.join(sep) }))
519
+ }
520
+ }
521
+
522
+
523
+ // The three the registry names. Each is its operation and nothing else.
524
+ class SumFuncVal extends AggFuncVal {
525
+ constructor(spec: ValSpec, ctx?: AontuContext) { super(spec, ctx, 'sum') }
526
+ }
527
+
528
+ class LeastFuncVal extends AggFuncVal {
529
+ constructor(spec: ValSpec, ctx?: AontuContext) { super(spec, ctx, 'least') }
530
+ }
531
+
532
+ class GreatestFuncVal extends AggFuncVal {
533
+ constructor(spec: ValSpec, ctx?: AontuContext) {
534
+ super(spec, ctx, 'greatest')
535
+ }
536
+ } /* node:coverage ignore next 10 */
537
+
538
+
539
+ export {
540
+ AggFuncVal,
541
+ JoinFuncVal,
542
+ PickFuncVal,
543
+ SumFuncVal,
544
+ LeastFuncVal,
545
+ GreatestFuncVal,
546
+ }
@@ -0,0 +1,108 @@
1
+ /* Copyright (c) 2025 Richard Rodger, MIT License */
2
+
3
+
4
+ import type {
5
+ Val,
6
+ ValSpec,
7
+ } from '../type'
8
+
9
+ import {
10
+ AontuContext,
11
+ } from '../ctx'
12
+
13
+ import { FuncBaseVal } from './FuncBaseVal'
14
+ import { arith } from './arith'
15
+ import type { ArithOp } from './arith'
16
+
17
+
18
+ // ONE CLASS FOR SIX FUNCTIONS, because every rule they obey is a rule
19
+ // about arithmetic rather than about any one operation (see arith.ts).
20
+ // Six near-identical classes would be six places for the exact ladder,
21
+ // the zero divisor and the storage contract to drift apart, and the
22
+ // number tower's whole point is that they cannot.
23
+ //
24
+ // The op is carried on the instance and answered by `funcname()`, which
25
+ // is what canon renders and what an error names. The six one-line
26
+ // subclasses below exist only because the parser's registry constructs
27
+ // with `new funcval({peg: args})` and has nowhere to put a name; every
28
+ // line of behaviour is here.
29
+ class ArithFuncVal extends FuncBaseVal {
30
+ isArithFunc = true
31
+
32
+ // The operation this call performs. Carried on the instance because
33
+ // `make` rebuilds the value during residuation and must rebuild the
34
+ // SAME function.
35
+ op: ArithOp
36
+
37
+ constructor(
38
+ spec: ValSpec,
39
+ ctx: AontuContext | undefined,
40
+ op: ArithOp
41
+ ) {
42
+ super(spec, ctx)
43
+ this.op = op
44
+ }
45
+
46
+
47
+ // Rebuilt as its own class, carrying its own op: residuation must not
48
+ // turn a `sub` into a bare arithmetic call with no operation.
49
+ make(_ctx: AontuContext, spec: ValSpec): Val {
50
+ return new (this.constructor as any)(spec, undefined, this.op)
51
+ }
52
+
53
+ funcname() {
54
+ return this.op
55
+ }
56
+
57
+
58
+ resolve(ctx: AontuContext | undefined, args: Val[]) {
59
+ return this.place(arith(ctx, this.op, this, args?.[0], args?.[1]))
60
+ }
61
+
62
+
63
+ // NO superior() OVERRIDE, deliberately. An arithmetic call could only
64
+ // advertise a kind once both its operands were concrete scalars -- and
65
+ // at that point it has RESOLVED, so what `super()` sees is the result,
66
+ // whose own superior is already the right answer:
67
+ // `super(mul(2,3))` is `integer` and `super(mul(2,1.5))` is `float`,
68
+ // through the value rather than through a promise about it. The
69
+ // override was written and then removed as unreachable; the same is
70
+ // true of FuncVal.superior in the Go port.
71
+ }
72
+
73
+
74
+ // The six the registry names. Each is its operation and nothing else.
75
+ class AddFuncVal extends ArithFuncVal {
76
+ constructor(spec: ValSpec, ctx?: AontuContext) { super(spec, ctx, 'add') }
77
+ }
78
+
79
+ class SubFuncVal extends ArithFuncVal {
80
+ constructor(spec: ValSpec, ctx?: AontuContext) { super(spec, ctx, 'sub') }
81
+ }
82
+
83
+ class MulFuncVal extends ArithFuncVal {
84
+ constructor(spec: ValSpec, ctx?: AontuContext) { super(spec, ctx, 'mul') }
85
+ }
86
+
87
+ class DivFuncVal extends ArithFuncVal {
88
+ constructor(spec: ValSpec, ctx?: AontuContext) { super(spec, ctx, 'div') }
89
+ }
90
+
91
+ class ModFuncVal extends ArithFuncVal {
92
+ constructor(spec: ValSpec, ctx?: AontuContext) { super(spec, ctx, 'mod') }
93
+ }
94
+
95
+ class RemFuncVal extends ArithFuncVal {
96
+ constructor(spec: ValSpec, ctx?: AontuContext) { super(spec, ctx, 'rem') }
97
+ } /* node:coverage ignore next 11 */
98
+
99
+
100
+ export {
101
+ ArithFuncVal,
102
+ AddFuncVal,
103
+ SubFuncVal,
104
+ MulFuncVal,
105
+ DivFuncVal,
106
+ ModFuncVal,
107
+ RemFuncVal,
108
+ }