aontu 0.62.0 → 0.63.0

package/src/val/BigIntegerVal.ts

@@ -21,18 +21,6 @@ import {
 } from '../utility'
 
 
-// The unbounded exact integer leaf of the number tower, reached only by
-// a `0d` literal with no fraction and no exponent (`0d5`, `-0d5`,
-// `0d123456789012345678901234567890`) or by direct construction.
-//
-// Its peg is a native bigint: exact at any magnitude, immutable, and
-// compared by VALUE with `===` (D2 -- two separately built bigints
-// holding the same number are `===`, which is exactly the property the
-// Go port has to reproduce by hand for `*big.Int`).
-//
-// `biginteger` is DISJOINT from `integer`: `5 & 0d5` is an error, since
-// a successful meet would have to pick one of the two kinds and either
-// choice makes `&` asymmetric in kind.
 class BigIntegerVal extends ScalarVal {
   isBigInteger = true
 
@@ -42,10 +30,6 @@ class BigIntegerVal extends ScalarVal {
     spec: ValSpec,
     ctx?: AontuContext
   ) {
-    // Exact-input construction (D8): a bigint, or the digits as text. A
-    // JS `number` is deliberately NOT accepted -- it has already been
-    // rounded before this library could inspect it, so an exact value
-    // above 2^53 could never arrive that way intact.
     let peg = spec.peg
     if ('string' === typeof peg) {
       if (!/^[-+]?[0-9]+$/.test(peg)) {

package/src/val/CloseFuncVal.ts

@@ -46,16 +46,7 @@ class CloseFuncVal extends FuncBaseVal {
     }
 
     if (argval.isMap || argval.isList) {
-      // The in-place write is safe BECAUSE of the per-destination
-      // instantiation rule (ADR-005): everywhere a close() call is
-      // multiplied — a pack/each template, a spread constraint — the
-      // clone now owns its argument (`dup`), so `closed` lands on that
-      // instance alone. Cloning the bag here instead was tried and
-      // rejected: the re-path it implies corrupts the source
-      // attribution of children inside nested spread templates (the
-      // 06-k8s use case's env findings named the wrong path).
       (argval as BagVal).closed = true
-      // console.log('CLOSED', argval.canon)
     }
 
     return argval

package/src/val/CmpFuncVal.ts

@@ -1,97 +1,5 @@
 /* Copyright (c) 2026 Richard Rodger, MIT License */
 
-// THE COMPONENT PRIMITIVES -- SPIKE (docs/design/JOSTRACA.0.md).
-//
-// `Folder`, `File` and `Content` are the first three of jostraca's
-// component set, spelled as aontu functions and keeping jostraca's
-// own capitalisation. They are the authoring surface an aontu
-// document uses to say what FILES it produces:
-//
-//   out: folder("src", [
-//     file("main.ts", [
-//       content("export const x = 1")
-//     ])
-//   ])
-//
-// WHAT THIS REPLACES. `aontu:code` (ts/src/std.ts, test/spec/
-// aontu-code.tsv) is a hand-written vocabulary an author fills in as
-// DATA -- `aontu: Code: units: [{path, lang, decls}]` -- and `aontu
-// render` folds that instance into bytes. The instance is checked by
-// unification against the vocabulary, which is the good half; the bad
-// half is that an author writes a schema instance rather than a
-// generator, the vocabulary owns every construct the renderer will
-// ever emit, and nothing in it corresponds to a component someone can
-// already write in jostraca. These primitives take the other road:
-// the CALL is the construct, the call's own resolve is where the
-// shape is refused, and the value it lands is a jostraca component
-// tree that jostraca's build phase already knows how to walk.
-//
-// THE VALUE IS AN ORDINARY MAP, which is the whole reason this can be
-// a spike at all. A component call resolves to
-//
-//   {cmp: "Folder", props: {name: "src"}, children: [...]}
-//
-// so nothing downstream needs new machinery: `generate()` emits the
-// tree as JSON, `canon` renders the calls back, references and
-// spreads reach into a tree as they reach into any map, and `each()`
-// over model data drops straight into a `children` list -- which is
-// the point, and is why the second argument must BE a list rather
-// than accepting a bare node as a convenience. `each($.fields,
-// content(...))` is already the list; a one-child special case would
-// make `file(n, each(...))` and `file(n, [each(...)])` both legal and
-// different.
-//
-// CHILDREN FLATTEN, for the same reason. A generator's output lands
-// in the MIDDLE of a written list --
-//
-//   file("planet.ts", [
-//     content("export interface Planet {"),
-//     each($.fields, content("  " + _ + ": string")),
-//     content("}")
-//   ])
-//
-// -- and that list therefore holds two nodes and a LIST OF NODES. A
-// list is not a node and could only be an error otherwise, so
-// splicing is the total rule and nesting is not: children are
-// flattened to any depth before the containment grammar is checked.
-// This is the finding the spike's worked example produced; every
-// component system that takes children arrives at it.
-//
-// THE NODE MAP IS CLOSED and its `props` map is not. The three keys
-// are the vocabulary and a fourth is a mistake, so a typo in
-// `folder(...) & {childrn: []}` is refused where every other mistake
-// in an aontu document is refused. Props are the COMPONENT's business
-// -- jostraca's File already reads `mode` and `exclude`, and a
-// component the spike does not implement will read its own -- so they
-// pass through, and only the one prop each primitive cannot work
-// without is checked here.
-//
-// THE CONTAINMENT GRAMMAR IS CHECKED AT THE CALL. A Folder holds
-// folders and files, a File holds content, and Content holds nothing.
-// Unification cannot state that on its own -- a node is a map, and
-// every node map unifies with every other -- so the constructor
-// states it, at the site the author wrote, which is the argument for
-// making these functions rather than another vocabulary.
-//
-// NOT STAGED, deliberately. A component call answers from its
-// arguments alone: it has no dependence on WHERE it sits (unlike
-// `key()`) and it reads no bag that a sibling may still merge into
-// (unlike `pack`/`each`). A children list BUILT by one of
-// those combinators still waits, because the combinator residuates
-// and the enclosing call is not `pegdone` until it fires -- so the
-// ordinary args-done gate is the correct one and the staging rule
-// costs nothing here.
-//
-// SPIKE SCOPE. TypeScript only; no Go port yet, and so:
-// deliberately absent from `test/spec/signature.tsv`, from
-// `BUILTIN_FUNCS` (ts/src/lsp.ts) and from the `grammar/` files, all
-// three of which are pinned in cross-port parity and would go red on
-// a TS-only change. Argument arity and shape are therefore refused
-// HERE rather than by the parse-time arity table or the signature
-// gate, both of which read the declaration this spike does not have.
-// Failures are `invalid-arg` for the same reason -- a new code needs
-// a row in test/spec/errcodes.tsv and an entry in BOTH ports' code
-// tables (AGENTS.md, "The shared test suite").
 
 import type {
   Val,
@@ -110,43 +18,23 @@ import { StringVal } from './StringVal'
 import { FuncBaseVal } from './FuncBaseVal'
 
 
-// The component names this spike serves, each with the children it
-// admits and the one prop it cannot work without. Adding a fourth
-// primitive is an entry here plus the two-line subclass below.
 type CmpDef = {
-  // The jostraca component this call builds. CAPITALISED, because it
-  // names a component in the other project's exported set and the
-  // bridge looks it up by that name -- while the aontu FUNCTION is
-  // lower case, like every other builtin in this language. The two
-  // spellings say what they are: `file(...)` is aontu, `"File"` is
-  // jostraca's.
   cmp: string
   // The children this component admits, by aontu function name. Empty
   // means a leaf: any child at all is a mistake.
   children: string[]
-  // The prop a bare string argument fills. ABSENT means the component
-  // has no one-string spelling and its spec must be a map: `listitems`
-  // is driven by a LIST, and there is no sensible string to promote.
   text?: string
   // Whether that prop is required. `project`'s folder is the one that
-  // is not: jostraca defaults it to `.`, and the data path must not be
+  // is not: Jostraca defaults it to `.`, and the data path must not be
   // stricter than the component it drives.
   req: boolean
   // A prop that must be present and must be a list.
   bag?: string
 }
 
-// EIGHT OF JOSTRACA'S TEN COMPONENTS. `Copy` and `List` are missing and
-// cannot be added under these rules: `copy` and `list` are already
-// aontu builtins with settled, unrelated meanings -- `copy(v)` copies a
-// VALUE and `list()` is the list container kind, both declared in
-// test/spec/signature.tsv and implemented in both ports. Lower-casing
-// jostraca's names onto them would either shadow landed language
-// surface or make one name mean two things by arity, and neither is a
-// trade a spike gets to make. See docs/design/JOSTRACA.0.md.
 const CMP_DEF: Record<string, CmpDef> = {
   // The output root. Its `folder` is refused an absolute path or a
-  // `..` segment on the jostraca side, where the tree is data.
+  // `..` segment on the Jostraca side, where the tree is data.
   project: {
     cmp: 'Project', text: 'folder', req: false,
     children: ['project', 'folder', 'file', 'copyfiles'],
@@ -159,8 +47,6 @@ const CMP_DEF: Record<string, CmpDef> = {
     cmp: 'File', text: 'name', req: true,
     children: ['content', 'line', 'fragment', 'inject', 'listitems', 'copyfiles'],
   },
-  // A span of text, exactly as written. `FileOp` joins a file's spans
-  // with the empty string, so a `content` carries its own terminator.
   content: {
     cmp: 'Content', text: 'src', req: true,
     children: [],
@@ -190,30 +76,12 @@ const CMP_DEF: Record<string, CmpDef> = {
     cmp: 'CopyFiles', text: 'from', req: true,
     children: [],
   },
-  // `List` under a name that says what it does: it renders its children
-  // ONCE PER ELEMENT of `item`, binding jostraca's `{item}` and
-  // `{item.path}` macros, and adds a trailing blank line unless
-  // `line: false`.
-  //
-  // IT IS THE ONE COMPONENT THE AONTU SIDE ALREADY SUBSUMES, and a
-  // generator should reach for `each()` first. `each($.rows, content(...))`
-  // repeats in the MODEL, so the repetition is finished before the tree
-  // exists and every produced node is data a document can reference,
-  // vet and diff. `listitems` defers it into jostraca's define phase behind
-  // a string macro aontu cannot see into -- which is the layer this
-  // spike exists to remove. It is here so the component set is
-  // complete, not because it is the better spelling.
   listitems: {
     cmp: 'ListItems', req: true, bag: 'item',
     children: ['content', 'line', 'fragment'],
   },
 }
 
-// The component name a value carries, when the value is a node this
-// vocabulary built. Read structurally rather than by class, because a
-// node reaches a children list as a MAP -- through a reference, a
-// `each()` instance, a spread -- long after the call that made it has
-// resolved away.
 const BY_CMP: Record<string, string> = {}
 for (const fname of Object.keys(CMP_DEF)) {
   BY_CMP[CMP_DEF[fname].cmp] = fname
@@ -232,7 +100,6 @@ function nodeCmp(v: any): string | undefined {
 }
 
 
-// A prop's text, when the prop is a concrete string.
 function propText(props: any, key: string): string | undefined {
   const v: any = props?.peg?.[key]
   return (true === v?.isScalar && 'string' === typeof v.peg) ? v.peg : undefined
@@ -243,7 +110,7 @@ class CmpFuncVal extends FuncBaseVal {
   isCmpFunc = true
 
   // The component this call builds: the function's own name, which is
-  // also the `cmp` key of the node and the jostraca component the
+  // also the `cmp` key of the node and the Jostraca component the
   // bridge looks up.
   cmp: string
 
@@ -264,24 +131,8 @@ class CmpFuncVal extends FuncBaseVal {
 
   resolve(ctx: AontuContext, args: Val[]): Val {
     const def: CmpDef = CMP_DEF[this.cmp]
-    const leaf = 0 === def.children.length
-
-    // ARITY, refused here (see the spike-scope note above): a leaf
-    // takes its spec alone, a container takes a spec and an optional
-    // children list.
-    // A component whose text prop is OPTIONAL may be called with
-    // nothing at all: `project()` is the defaulted root, as
-    // `project({})` is on the other side. Everything else needs its
-    // spec.
-    if (args.length < (def.req ? 1 : 0) || args.length > (leaf ? 1 : 2)) {
-      return makeNilErr(ctx, 'invalid-arg', this, undefined, 'arity')
-    }
 
-    // THE SPEC IS A STRING OR A PROPS MAP. The string spelling fills
-    // the one prop the component cannot work without, so the common
-    // case reads as the component does -- `file("main.ts", ...)` --
-    // and the map spelling is there the moment a second prop is
-    // wanted: `file({name: "run.sh", mode: 0o755}, ...)`.
+    // Arity is checked at parse (funcArity); args[0] can be undefined.
     const spec: any = args[0]
     let props: Val
     if (undefined === spec) {
@@ -300,8 +151,6 @@ class CmpFuncVal extends FuncBaseVal {
       return makeNilErr(ctx, 'invalid-arg', this, spec, 'spec')
     }
 
-    // The one prop that is not the component's own business: without
-    // it there is no file to write and no content to write into one.
     if (undefined !== def.text) {
       const text = propText(props, def.text)
       if (def.req && (undefined === text || '' === text)) {
@@ -323,10 +172,6 @@ class CmpFuncVal extends FuncBaseVal {
       }
     }
 
-    // THE CHILDREN, flattened, then the containment grammar. Absent
-    // is empty -- an empty folder and a file with no content are both
-    // things a model may legitimately say -- and every node that
-    // survives the flattening must be one this component admits.
     const kids: any = args[1]
     let children: Val
     if (undefined === kids) {
@@ -369,8 +214,6 @@ class CmpFuncVal extends FuncBaseVal {
       }
     }, ctx)
 
-    // Closed: the three keys ARE the node vocabulary (see the note
-    // above). `props` is left open on purpose.
     node.closed = true
 
     return this.place(node)
@@ -379,11 +222,6 @@ class CmpFuncVal extends FuncBaseVal {
 } /* node:coverage ignore next 3 */
 
 
-// ONE CLASS PER COMPONENT, generated from the table, because the
-// registry constructs by `new funcval({peg: args})` and so needs a
-// constructor per name. Written as a factory rather than eight
-// near-identical subclasses: the table is the single statement of what
-// exists, and a ninth component is a row in it and nothing else.
 function cmpFuncClass(fname: string): any {
   class Cmp extends CmpFuncVal {
     constructor(spec: ValSpec, ctx?: AontuContext) {

package/src/val/ConjunctVal.ts

@@ -1,7 +1,6 @@
 /* Copyright (c) 2021-2025 Richard Rodger, MIT License */
 
 
-
 import type {
   Val,
   ValSpec,
@@ -32,14 +31,11 @@ import {
 } from '../utility'
 
 
-
 import {
   top
 } from './top'
 
 
-
-// TODO: move main logic to op/conjunct
 class ConjunctVal extends JunctionVal {
   isConjunct = true
   isGenable = true
@@ -78,7 +74,6 @@ class ConjunctVal extends JunctionVal {
 
     this.peg = norm(this.peg)
 
-    // console.log('\nCONJUNCT', ctx.cc, this.id, this.canon, peer.id, peer.canon)
 
     // Unify each term of conjunct against peer
     let upeer: Val[] = []
@@ -87,7 +82,6 @@ class ConjunctVal extends JunctionVal {
     let newhide = this.mark.hide || peer.mark.hide
 
     for (let vI = 0; vI < this.peg.length; vI++) {
-      // console.log('CONJUNCT-peg', vI, this.peg[vI].canon, this.peg[vI].mark)
       newtype = this.peg[vI].mark.type || newtype
       newhide = this.peg[vI].mark.hide || newhide
     }
@@ -95,7 +89,6 @@ class ConjunctVal extends JunctionVal {
     for (let vI = 0; vI < this.peg.length; vI++) {
       this.peg[vI].mark.type = newtype
       this.peg[vI].mark.hide = newhide
-      // console.log('CONJUNCT-TERM', this.id, vI, this.peg[vI].canon)
 
       upeer[vI] = (this.peg[vI].done && peer.isTop) ? this.peg[vI] :
         unite(te ? ctx.clone({ explain: ec(te, 'OWN') }) : ctx, this.peg[vI], peer, 'cj-own')
@@ -103,17 +96,10 @@ class ConjunctVal extends JunctionVal {
       upeer[vI].mark.type = newtype = newtype || upeer[vI].mark.type
       upeer[vI].mark.hide = newhide = newhide || upeer[vI].mark.hide
 
-      // let prevdone = done
       done = done && (DONE === upeer[vI].dc)
 
       if (upeer[vI].isNil) {
         return upeer[vI]
-        // return Nil.make(
-        //   ctx,
-        //   '&peer[' + upeer[vI].canon + ',' + peer.canon + ']',
-        //   this.peg[vI],
-        //   peer
-        // )
       }
     }
 
@@ -155,7 +141,6 @@ class ConjunctVal extends JunctionVal {
 
       else {
         val = unite(te ? ctx.clone({ explain: ec(te, 'DEF') }) : ctx, t0, t1, 'cj-peer-t0t1')
-        // console.log('CONJUNCT-T', t0.canon, t1?.canon, '->', val.canon)
         done = done && DONE === val.dc
         newtype = this.mark.type || val.mark.type
         newhide = this.mark.hide || val.mark.hide
@@ -184,7 +169,6 @@ class ConjunctVal extends JunctionVal {
       out = top()
     }
 
-    // TODO: corrects CV[CV[1&/x]] issue above, but swaps term order!
     else if (1 === outvals.length) {
       out = outvals[0]
       out.mark.type = newtype
@@ -196,7 +180,6 @@ class ConjunctVal extends JunctionVal {
 
     out.dc = done ? DONE : this.dc + 1
 
-    // console.log('CONJUNCT-unify', this.id, sc, pc, '->', out.canon, 'D=' + out.dc, 'E=', this.err)
 
     explainClose(te, out)
 
@@ -216,19 +199,6 @@ class ConjunctVal extends JunctionVal {
 
 
   gen(ctx?: AontuContext) {
-    // A RESIDUATED SIZING ATOM DECIDES HERE (the review's finding C,
-    // use-cases/BUGS.md §16). `length`/`unique` over a container keep
-    // the readings that MORE MEMBERS COULD STILL CHANGE -- an upper
-    // bound satisfied, a lower bound violated, distinctness so far --
-    // rather than deciding against whatever the container held when it
-    // first settled (ConstraintVal.admitContainer). Generation is where
-    // no more members can arrive, so it is where the provisional
-    // reading becomes the verdict: the container generates if the atom
-    // is satisfied, and the atom's OWN refusal is raised if it is not.
-    //
-    // Without this the conjunct would report `conjunct` for a document
-    // whose only fault is a length -- the constraint's message is the
-    // one the author needs.
     const residue = sizingResidue(this)
     if (undefined !== residue) {
       const settled: any = residue.con.settleContainer(residue.bag, ctx)
@@ -243,13 +213,11 @@ class ConjunctVal extends JunctionVal {
       undefined
     )
 
-    // TODO: refactor to use Site
     nil.path = this.path
     nil.site.url = this.site.url
     nil.site.row = this.site.row
     nil.site.col = this.site.col
 
-    // descErr(nil, ctx)
 
     if (null == ctx) {
       throw new AontuError(nil.msg)
@@ -260,7 +228,6 @@ class ConjunctVal extends JunctionVal {
 }
 
 
-
 // Normalize Conjunct:
 // - flatten child conjuncts
 // - consistent sorting of terms