aontu 0.62.0 → 0.64.0

package/src/query.ts

@@ -1,32 +1,6 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 import { includeOpts } from './utility'
 
-// THE QUERY SURFACE (G7 phase 1,
-// docs/capability-review/g7-machine-access.md): select one node of an
-// evaluated document by path and render it — the slice an agent asks
-// for, instead of the whole file as one JSON blob.
-//
-// Evaluation is still GLOBAL. Unification has no partial mode to sell:
-// the whole document is evaluated and then one node is selected. What
-// `get` buys is the SIZE OF THE ANSWER, not the cost of producing it.
-//
-// The three projections are lattice ABSTRACTIONS, and each is defined
-// so that the view it prints is a valid Aontu document that SUBSUMES
-// the truth — generalisation, never distortion:
-//
-//   - `types` replaces every concrete leaf with its own kind, using
-//     the lattice's own superior() rather than a table of this file's
-//     opinions: {"replicas":3} becomes {"replicas":integer}.
-//   - `depth n` keeps structure to depth n and renders every elided
-//     subtree as `top` — "no further information at this tier".
-//   - `keys` is `depth 1` degenerated to a listing.
-//
-// That property is not a promise here: every projection row of
-// test/spec/query.tsv asserts subsume(view, truth) == 'subsumes' in
-// both runners, which G3 made mechanically checkable.
-//
-// Projections are NOT canonical form and are never fed to G6's hash,
-// which is why they are named views rather than spellings of --canon.
 
 import { Aontu } from './aontu'
 import type { TrustOptions } from './type'
@@ -49,13 +23,6 @@ export type QueryOptions = {
   // it resolves from its own directory (vet's schemaPath precedent).
   path?: string
 
-  // The trust profile this run evaluates under (G5, docs/trust.md).
-  // The source arrives from a caller, so the caller must be able to
-  // say what it may reach: without this the include chain is the
-  // default one, and `@"../../etc/passwd.aon"` reads whatever the
-  // process can. (`@"x.js"` no longer executes -- ADR-012 refuses the
-  // extension -- but reading is enough.) A server passes
-  // `{include:'none'}`.
   trust?: TrustOptions
 
   // Extensions additionally read as text (the CLI's `--text-ext`).
@@ -67,8 +34,6 @@ export type QueryOptions = {
 export type QueryReport = {
   ok: boolean
   out: string
-  // Empty when ok. G2's finding shape, deliberately: `get` invents no
-  // error format (G7's own rule).
   findings: VetFinding[]
 }
 
@@ -76,10 +41,6 @@ export type QueryReport = {
 const TOP = 'top'
 
 
-// The nearest key at the parent of a path that named nothing, by a
-// plain edit distance over the sibling names — the "did you mean"
-// half of the no_path contract. Undefined when nothing is close
-// enough to be worth suggesting.
 export function nearestKey(
   want: string, have: string[]): string | undefined {
   let best: string | undefined
@@ -135,20 +96,12 @@ function pathText(path: string): string {
 }
 
 
-// The projection walk, exported for the direct unit tests (ADR-002,
-// ts/test/coverage3.test.ts): a junction member that is itself a
-// junction of more than one term keeps its parens, and no SOURCE
-// reaches that arm because norm flattens junctions at unification.
 export function projectFor(
   v: any, view: QueryView, depth: number): string {
   return project(v, view, depth)
 }
 
 
-// The canon-shaped views. One walk, two knobs: `types` generalises
-// each leaf through the lattice, `depth` elides below its level. Bags
-// recurse (their canon getters would render children through plain
-// canon, which neither knob can reach); everything else is a leaf.
 function project(v: any, view: QueryView, depth: number): string {
   if (depth <= 0) {
     return TOP
@@ -173,10 +126,6 @@ function project(v: any, view: QueryView, depth: number): string {
       keys.map((k) => project(v.peg[k], view, depth - 1)).join(',') +
       ']'
   }
-  // Junctions and prefs are TRANSPARENT: not a structural tier (so
-  // they do not spend a level of depth) but not a leaf either (so
-  // `*8080|integer` generalises to `*integer|integer` rather than
-  // collapsing to `top` and throwing the alternatives away).
   if (true === v?.isPref) {
     return '*' + project(v.peg, view, depth)
   }
@@ -188,12 +137,6 @@ function project(v: any, view: QueryView, depth: number): string {
       .join(true === v.isConjunct ? '&' : '|')
   }
 
-  // A LEAF. Under `types` a CONCRETE scalar lifts to its own kind —
-  // superior() is the lattice's answer, so the view subsumes the truth
-  // by construction and not by this file's good intentions. Everything
-  // else is already an abstraction (a kind marker, a constraint, an
-  // unresolved reference) and is left alone: lifting `integer` to
-  // `number` would generalise a shape view that was already a shape.
   return 'types' === view && true === v?.isScalar ? v.superior().canon : v.canon
 }
 
@@ -227,17 +170,7 @@ function finding(
 }
 
 
-// A document that does not stand up has no node to select. The
-// engine's own first error IS the report: the query surface adds
-// nothing to a diagnosis the evaluator already made. The path is the
-// DOCUMENT — what failed is the whole thing standing up, not the node
-// the caller asked about, which may never have existed.
 export function evalFailure(ctx: any): VetFinding {
-  // ctx.err is never empty at a call site: every failure that reaches
-  // one collected an error first — a parse that did not stand up, a
-  // root that came back nil. Not coalesced, on the vet siteOf
-  // precedent: an impossible state should fail loudly rather than be
-  // quietly papered over with a made-up code.
   const err: any = ctx.err[0]
   return finding(err.why, '$', err.msg)
 }
@@ -292,12 +225,6 @@ export function get(
   }
 
   if ('json' === view) {
-    // GENERATION CAN FAIL WHERE UNIFICATION DID NOT: `k: integer` is a
-    // perfectly good unified document and not a concrete value, so the
-    // json view of it is an error, exactly as `aontu file.aon` on the
-    // same document is. Under `collect` the failure lands on the
-    // context rather than throwing, so it has to be read back — the Go
-    // port's Gen returns it as an error and the two must agree.
     const before = ctx.err.length
     const gen = node.gen(ctx)
     if (before < ctx.err.length) {
@@ -331,13 +258,6 @@ export type WhyReport = {
 }
 
 
-// WHY does the value at this path hold? Evaluate with the provenance
-// recorder on, select the node, and answer the ordered contributions
-// that met there — the positive twin of G2's error report.
-//
-// Two evaluations are NOT needed: the recorder rides the one run this
-// call makes. What it costs is site materialisation and one map entry
-// per path met, which an instrumented run pays knowingly.
 export function why(
   src: string, path: string, opts?: QueryOptions): WhyReport {
   const options = opts ?? {}
@@ -346,10 +266,6 @@ export function why(
   const ctx = aontu.ctx({ collect: true, prov })
   const parseOpts = null == options.path ? undefined : { path: options.path }
 
-  // Parse and unify SEPARATELY, so the parsed tree can be stamped
-  // before the fixpoint runs: a contribution is a value the author
-  // wrote, and after unification there is no longer any way to tell
-  // one from a value the engine minted on the way.
   const parsed: any = aontu.parse(src, parseOpts, ctx)
   if (0 < ctx.err.length || null == parsed) {
     return { ok: false, findings: [evalFailure(ctx)] }

package/src/reach.ts

@@ -1,33 +1,6 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 import { includeOpts } from './utility'
 
-// REACHABILITY OVER THE LINK GRAPH (the review's finding J,
-// use-cases/REVIEW.md): "ship a transitive `reaches(a, b)` check verb".
-//
-// `relations` answers questions about the edge set as a whole --- is it
-// acyclic, does every edge have its inverse, is every far end what the
-// relation says it is. This answers the question that needs the CLOSURE
-// rather than the edges: does anything `a` depends on, at any remove,
-// end up at `b`? That is the shape of every blast-radius question an
-// operator asks ("if the billing database goes, what falls over?") and
-// every containment question a policy asks ("nothing in the public tier
-// may reach the ledger"), and neither can be expressed by looking one
-// edge at a time.
-//
-// It is a VERB and not a constraint, for the same reason acyclicity is
-// (docs/reference-language.md, "Declared relations"): reachability is
-// global and non-monotone. One more edge can make an unreachable pair
-// reachable, so a lattice citizen asserting non-reachability could be
-// true and then false, and the lattice guarantee is that more
-// information never falsifies what has already been observed.
-//
-// TRANSITIVE, NOT REFLEXIVE-TRANSITIVE: `reaches(a, a)` is true only
-// when a path of one or more edges returns to `a`, which is the useful
-// answer (it says the graph has a cycle through `a`) rather than the
-// vacuous one.
-//
-// The Go twin is go/reach.go; what the two ports must agree on --- the
-// verdict and the path --- is test/spec/reach.tsv.
 
 import { Aontu } from './aontu'
 import { failureFinding } from './vet'
@@ -42,15 +15,8 @@ export type ReachVerdict = 'reaches' | 'unreachable' | 'error'
 export type ReachReport = {
   verdict: ReachVerdict
 
-  // The path found, as `$.dotted` node paths from the source to the
-  // destination, both included. Present ONLY on `reaches`: a path is
-  // the evidence for the answer, and there is no evidence for a
-  // negative one.
   path?: string[]
 
-  // WHY the graph could not be looked at, in vet's finding shape (the
-  // review's finding F): a document that does not stand up, or an
-  // endpoint that names no node. Present ONLY on `error`.
   errors?: VetFinding[]
 }
 
@@ -62,9 +28,6 @@ export type ReachOptions = {
   // docs/trust.md).
   trust?: TrustOptions
 
-  // Extensions additionally read as text (the CLI's `--text-ext`).
-  // Rides beside `trust` because it is the other half of what an
-  // include may read.
   textExt?: string[]
   // Follow only edges under this relation. Absent means follow every
   // edge, which is the whole graph and the commoner question.
@@ -72,10 +35,6 @@ export type ReachOptions = {
 }
 
 
-// The segments a `$.dotted` endpoint spells, or undefined when it is
-// not one. Reachability is between TREE POSITIONS (ADR-014), so an
-// endpoint is a path and nothing else --- the same spelling the report
-// prints back.
 export function parseNodePath(s: string): string[] | undefined {
   if ('$' === s) {
     return []
@@ -88,9 +47,6 @@ export function parseNodePath(s: string): string[] | undefined {
 }
 
 
-// Whether a path names a node of the evaluated tree. An endpoint that
-// exists but has no edges is a perfectly good question with the answer
-// `unreachable`; only one that names NOTHING is an error.
 function nodeAt(root: any, path: string[]): boolean {
   let node: any = root
   for (const seg of path) {
@@ -112,10 +68,6 @@ function endpointFinding(name: string, known: string[]): VetFinding {
     class: 'reference',
     severity: 'error',
     path: '$',
-    // NOT "unreachable". An endpoint that names no node is a question
-    // the document cannot answer, and answering it `no` would report a
-    // typo as a fact about the model --- the fail-open shape this
-    // review exists to retire.
     message: `${name} names no node in this document.`,
     sites: [],
     ...(0 === known.length ? {} : {
@@ -182,11 +134,6 @@ export function reachCheck(
     list.sort(cmpCodePoint)
   }
 
-  // BREADTH-FIRST, so the path reported is a SHORTEST one --- the
-  // evidence an operator wants is the tightest chain, not whichever the
-  // walk happened to find first --- and, with the successors sorted, a
-  // determined one: among shortest paths, the first in code-point order
-  // at the first step that distinguishes them.
   const prev = new Map<string, string>()
   const seen = new Set<string>()
   let front: string[] = [from]

package/src/relation.ts

@@ -1,29 +1,6 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 import { includeOpts } from './utility'
 
-// RELATION GRAPH VERDICTS (RELATIONS.0.md §3.3, replacing the G4
-// phase 5 magic-key pass): acyclicity and inverse consistency over
-// the edge set, DECLARED by the graph atoms -- `acyclic()` and
-// `inverse(name)` conjoined at the field whose key is the predicate
-// -- and decided AFTER unification, never by it.
-//
-// Why not in the lattice. Both properties are GLOBAL and NON-MONOTONE:
-// an acyclic graph becomes cyclic when one more edge unifies in, and an
-// inverse that is present becomes absent when the far side is narrowed.
-// The lattice guarantee is that more information never falsifies what
-// has been observed, so a constraint that could be true and then false
-// is not a constraint the lattice may hold. These are facts about the
-// finished model, so the atoms only REGISTER during unification
-// (GraphAtomVal.register, onto ctx._reldecls), and the verdict lands
-// at GENERATION -- the sizing atoms' model -- where no more
-// information can arrive. The `relations` verb reports the same
-// verdict from the same declarations: one decision, two surfaces.
-//
-// The old declaration channel -- a `relations:` key at the document
-// root, read by name -- is GONE, discharging ADR-010's grandfather
-// clause: the engine no longer knows any spellable key. The target
-// half of the old declaration is `rel(t)`'s flow at the site, which
-// checks by unifying rather than by a report-layer probe.
 
 import { Aontu } from './aontu'
 import { failureFinding } from './vet'
@@ -40,13 +17,9 @@ export type RelationVerdict = 'pass' | 'fail' | 'error'
 
 export type RelationFinding = {
   code: string
-  // The relation the finding is about.
   relation: string
   // Where the offending edge is written, as a `$.dotted.path`.
   at: string
-  // For a cycle, the node paths it runs through, in the order the walk
-  // found them, closing back on the first. For a missing inverse, the
-  // two ends and the relation that should have mirrored it.
   detail: string[]
 }
 
@@ -54,18 +27,8 @@ export type RelationReport = {
   verdict: RelationVerdict
   findings: RelationFinding[]
 
-  // WHY the graph could not be looked at, in the same finding shape
-  // vet reports in (the review's finding F). `findings` is about the
-  // GRAPH and stays that way; a document that does not stand up has no
-  // graph to have findings about, and an `error` verdict used to
-  // arrive with an empty list -- something is wrong, and nothing about
-  // what. Present ONLY on an `error` verdict.
   errors?: VetFinding[]
 
-  // How many relation declarations the document makes (G11 phase 4).
-  // ZERO is the answer that matters: `pass` over no declarations means
-  // nothing was checked, and without this the two are one word.
-  // Absent unless the run asked for it (`RelationOptions.count`).
   declared?: number
 }
 
@@ -73,9 +36,6 @@ export type RelationOptions = {
   // Where the document CAME FROM, so a relative `@"file"` load inside
   // it resolves from its own directory (trimCheck's precedent).
   path?: string
-  // The include capability this document evaluates under (G5,
-  // docs/trust.md). vet's precedent: the verb passes the profile the
-  // caller asked for, and an absent option means today's default.
   trust?: TrustOptions
 
   // Extensions additionally read as text (the CLI's `--text-ext`).
@@ -83,20 +43,10 @@ export type RelationOptions = {
   // include may read.
   textExt?: string[]
 
-  // Count the relation declarations the document makes (G11 phase 4),
-  // so a caller can tell a graph that CHECKED CLEAN from one there was
-  // nothing to check. `pass` is the same word for both, which is the
-  // whole reason this exists. Absent from the report unless asked for,
-  // so no existing caller's report changes shape -- `vet --coverage`
-  // sets the precedent.
   count?: boolean
 }
 
 
-// The first cycle reachable from `start`, as the node paths it runs
-// through, or undefined. Depth-first with the path as the stack, and
-// the successors visited in sorted order, so the cycle a report names
-// is the same one in both ports.
 function findCycle(
   start: string,
   succ: Map<string, string[]>,
@@ -130,16 +80,11 @@ function findCycle(
 }
 
 
-// The verdict itself, pure over what the evaluation produced: the
-// registered declarations and the edge set. Shared by the generation
-// hook (relationErrors) and the `relations` verb, so the two surfaces
-// cannot disagree.
 export function relationFindings(
   decls: Map<string, RelDecl>, graph: Graph
 ): RelationFinding[] {
   const findings: RelationFinding[] = []
 
-  // The edge set, indexed the two ways the checks read it.
   const byRelation = new Map<string, Edge[]>()
   const pairs = new Set<string>()
   for (const e of graph.edges) {
@@ -215,11 +160,6 @@ export function relationFindings(
     }
   }
 
-  // SORTED, because a report is read by a machine that diffs it: by the
-  // position the offending edge is written at, then by code, then by
-  // the detail (two inverse declarations on one predicate can flag one
-  // edge twice). The sort is STABLE and the predicates were iterated
-  // in sorted order, so what order remains is fixed anyway.
   findings.sort((a, b) =>
     cmpCodePoint(a.at, b.at) || cmpCodePoint(a.code, b.code)
     || cmpCodePoint(a.detail.join(' '), b.detail.join(' ')))
@@ -228,11 +168,6 @@ export function relationFindings(
 }
 
 
-// The generation hook (Aontu.generate, between unification success
-// and value generation): each finding becomes a LOCATED evaluation
-// error at the offending edge, exactly as an unmet sizing atom
-// refuses at generation. Findings name node paths and positions the
-// document spelled, so the walk to the site cannot miss.
 export function relationErrors(ctx: any, root: any): void {
   const decls: Map<string, RelDecl> = ctx._reldecls
   if (0 === decls.size) {
@@ -250,11 +185,6 @@ export function relationErrors(ctx: any, root: any): void {
       }
       node = node?.peg?.[seg]
     }
-    // No unwrap AFTER the walk: a finding's `at` names an edge
-    // element, and an edge's element is a string -- an atom-wrapped
-    // element mints no edge in the first place (the graph visit
-    // descends atoms only at field values), so the walk cannot end on
-    // an atom.
     ctx.adderr(makeNilErr(ctx, f.code, node, undefined, 'relate', {
       relation: f.relation,
       detail: f.detail.join(' -> '),
@@ -285,25 +215,11 @@ export function relationCheck(
   }
 
   const decls: Map<string, RelDecl> = (ctx as any)._reldecls
-  // The count rides every report from here down: the engine knows it
-  // at exactly this point, and a caller asking "was there anything to
-  // check?" should not have to evaluate the document a second time to
-  // find out.
   const counted = true === options.count ? { declared: decls.size } : {}
   if (0 === decls.size) {
     return { verdict: 'pass', findings: [], ...counted }
   }
 
-  // NOR IS A DOCUMENT THAT CANNOT BE GENERATED. Unification can
-  // succeed over a tree that still holds an unsettled disjunction --
-  // more than one alternative admitted, which `disjunct_no_gen`
-  // refuses at generation -- and the graph walk cannot read inside
-  // one: the links in every alternative are invisible, so a mirror
-  // the document plainly writes is missing from the edge set and
-  // `inverse(n)` calls it missing. Generation is therefore asked
-  // FIRST, on a collecting context of its own, and what it says is
-  // the answer. Generation is what the atoms' verdict lands at, so
-  // this is the same order the engine itself now runs in.
   const gctx = ctx.clone({ err: [], collect: true })
   root.gen(gctx)
   if (0 < gctx.err.length) {

package/src/report-sarif.ts

@@ -1,25 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// SARIF rendering for a vet report (G2 phase 5,
-// docs/capability-review/g2-validation-verb.md).
-//
-// A MINIMAL SARIF 2.1.0 profile, and deliberately nothing more: one
-// run, one `result` per finding, the finding's first site as the
-// primary location, its remaining sites under `relatedLocations`, and
-// the whole finding object embedded in `properties` so a SARIF consumer
-// still holds the native contract. No fixes, no code flows, no
-// baselines — the JSON report is the native contract, SARIF is the
-// interchange skin CI systems already ingest (GitHub code scanning
-// uploads, PR annotation).
-//
-// This is library API, not CLI plumbing, for the same reason the vet
-// engine is: an embedder (and G7's MCP server later) must be able to
-// emit the interchange form without shelling out. The Go twin is
-// go/report_sarif.go, and the two are held to byte parity over the
-// shared fixture pair in test/spec/files/vet-sarif/ — with the message
-// text and producer version redacted, exactly as test/spec/vet.tsv
-// carves the message out of its goldens, because prose and the two
-// independent version series are deliberately not in cross-port parity.
 
 import type { VetReport, VetFinding, VetSite } from './vet'
 
@@ -37,13 +17,6 @@ const SARIF_LEVEL: Record<string, string> = {
 }
 
 
-// A site's file is a filesystem path, and a SARIF artifactLocation.uri
-// is a URI reference: `#`, `%`, spaces and every other URI-significant
-// character must be percent-encoded or a consumer parses the path as
-// something else (text after `#` becomes a fragment). Encoded BY BYTE
-// over UTF-8, with RFC 3986's unreserved and path characters kept
-// literal, so the Go twin produces identical bytes from an identical
-// loop (go/report_sarif.go sarifURI).
 function sarifUri(path: string): string {
   const bytes = Buffer.from(path, 'utf8')
   let out = ''
@@ -75,11 +48,6 @@ function sarifLocation(site: VetSite): any {
 
 
 function sarifResult(finding: VetFinding): any {
-  // The engine orders sites data-first (the thing to fix), so the first
-  // site is the primary location and the rest are related — which for a
-  // two-site conflict puts the schema's declaration under
-  // `relatedLocations`, exactly where a code-scanning UI shows "the
-  // other side".
   const result: any = {
     level: SARIF_LEVEL[finding.severity],
     locations: [sarifLocation(finding.sites[0])],
@@ -95,26 +63,10 @@ function sarifResult(finding: VetFinding): any {
 }
 
 
-/**
- * Render a vet report as SARIF 2.1.0 text (a minimal profile: one run,
- * one result per finding, the finding embedded in `properties`).
- *
- * @param report   A report from `vet()`.
- * @param version  The producer version for `tool.driver.version` —
- *                 the CLI passes its package version; the two ports'
- *                 version series are independent by design.
- * @returns        The SARIF JSON text, indented two spaces, keys in
- *                 the canonical emitter's sorted order.
- */
 function sarifReport(report: VetReport, version: string): string {
   return exactJSON({
     $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
     runs: [{
-      // An `error` verdict means the run could not be set up (an
-      // unusable schema): zero findings from a FAILED run must not
-      // read like zero findings from a clean one, so the failure is
-      // carried in SARIF's own invocation metadata rather than by an
-      // indistinguishable empty result list.
       invocations: [{
         executionSuccessful: 'error' !== report.verdict,
       }],

package/src/sig.ts

@@ -1,29 +1,5 @@
 /* Copyright (c) 2021-2026 Richard Rodger, MIT License */
 
-// THE SIGNATURE REGISTRY (docs/design/SIGNATURES.0.md). The call
-// surface of the built-in functions is DECLARED, in the signature
-// syntax itself, in test/spec/signature.tsv; this module is the
-// TypeScript half of the pair that reads it. The declaration text is
-// inlined at build time (ts/src/sigdecl.ts, `make sig`) and parsed at
-// initialisation by the signature grammar -- a custom tabnas grammar,
-// the same engine the aontu grammar itself is built on -- into the
-// registry the runtime signature checker, the error-message builder,
-// the docs table and the LSP all consume. Neither port authors a
-// table: go/sig.go parses the same text with the same grammar, and
-// the shared suite round-trips every line (render(parse(line)) is the
-// line) so the two parsers cannot drift.
-//
-//   line = name '(' [ arg {',' arg} ] ')' ':' type
-//   arg  = [mode] name ['?'] ':' type
-//        | '...' name ':' ( type | '(' [mode] type {',' [mode] type} ')' )
-//   type = word {'|' word}
-//   mode = 'capture' | 'template' | 'trial' | 'projector' | 'text'
-//
-// `value` mode is unmarked; the five marked modes are the vocabulary
-// plain pseudo-TypeScript cannot say (a captured spelling is not a
-// string value). The grammar is line-oriented: the loader strips
-// comment and blank lines and parses each declaration line alone, so
-// the grammar never sees line structure.
 
 import { Tabnas } from '@tabnas/parser'
 
@@ -59,11 +35,6 @@ const ARG_MODES: Record<string, boolean> = {
 }
 
 
-// The signature grammar, as a tabnas grammar plugin. Rules: sig (the
-// line) -> args -> arg -> argtype -> type | group -> gmember. Alts
-// match at most two tokens, the engine's shape; lists loop the
-// json-grammar way (the element rule replaces itself on ',' and
-// backtracks the closer for its parent to consume).
 function sigGrammar(tn: any) {
   tn.options({
     fixed: {
@@ -326,12 +297,6 @@ export type {
   FuncSig,
 }
 
-// The parsed registry, built once from the inlined declaration -- the
-// one source every consumer (the arity tables, the runtime gate, the
-// hints, the docs table, the LSP) reads. A parse failure here throws
-// at module load: the inlined text is repository content whose parse
-// the round-trip suite gates, so a failure is a build defect, not a
-// runtime condition. Twin: funcSig in go/sig.go.
 const funcSig: Record<string, FuncSig> =
   parseSigText(SIGDECL) /* node:coverage ignore next 9 */
 

package/src/sigdecl.ts

@@ -6,6 +6,6 @@
 // this copy is identical with the shared file.
 
 const SIGDECL: string =
-"# The call surface: one declaration line per built-in function\n# (docs/design/SIGNATURES.0.md). THIS FILE IS THE SOURCE — both ports\n# carry a build-time-inlined copy (ts/src/sigdecl.ts, go/sigdecl.txt;\n# `make sig` regenerates both, and each port's suite asserts its copy\n# is byte-identical with this file) and parse it at initialisation\n# with the signature grammar, a tabnas grammar (ts/src/sig.ts,\n# go/sig.go). The suites also round-trip every line:\n# render(parse(line)) must be the line exactly, in both ports.\n#\n# The syntax (rendered TypeScript-ish, honest about argument MODES):\n#   line = name '(' [ arg {',' arg} ] ')' ':' type\n#   arg  = [mode] name ['?'] ':' type\n#        | '...' name ':' '(' [mode] type {',' [mode] type} ')'\n#   type = word {'|' word}\n#   mode = 'capture' | 'template' | 'trial' | 'projector' | 'text'\n# `value` mode is unmarked. `constraint` is the result word for\n# residuals whose meet depends on the peer; `any` is the honest type\n# where a function is a wrapper.\nupper(s: string|number, start?: integer|biginteger, len?: integer|biginteger) : string\nlower(s: string|number, start?: integer|biginteger, len?: integer|biginteger) : string\ncopy(v: any) : any\npref(v: any) : any\nsuper(t: any) : any\ntype(t: any) : any\nhide(v: any) : any\nclose(m: any) : any\nopen(m: any) : any\nmove(v: any) : any\npath(capture p?: path) : path\nmap() : map\nlist() : list\nmin(n: number|string) : constraint\nmax(n: number|string) : constraint\nabove(n: number|string) : constraint\nbelow(n: number|string) : constraint\nre(text p: string) : constraint\nlength(n: number|constraint) : constraint\nkey(up?: integer|biginteger) : string\nunique(projector k?: string) : constraint\nneq(...vals: number|string) : constraint\nmust(trial c: any, text msg: string) : constraint\ndeprecate(v: any, r?: map) : any\nacyclic() : constraint\ninverse(projector k: string) : constraint\nrefer(template t?: any) : constraint\nrel(template t?: any) : constraint\npack(d: map|list, template t: any) : map\neach(d: map|list, template t: any) : list\nfilter(d: map|list, trial c: any) : map|list\nmatch(s: any, ...pr: (trial any, any), dflt?: any) : any\nadd(a: number, b: number) : number\nsub(a: number, b: number) : number\nmul(a: number, b: number) : number\ndiv(a: number, b: number) : number\nmod(a: number, b: number) : number\nrem(a: number, b: number) : number\nsum(d: map|list) : number\nleast(d: map|list) : number\ngreatest(d: map|list) : number\npick(d: map|list, projector k: string|integer) : any\njoin(d: map|list, sep?: string) : string\nesc(s: string, variant?: string) : string\nusc(s: string, variant?: string) : string\nrep(s: string, text p: string, text sub: string) : string\nsplit(s: string, sep: string|constraint) : list\nemit(s: map|list, template t: map|list) : list\n"
+"# The call surface: one declaration line per built-in function\n# (docs/design/SIGNATURES.0.md). THIS FILE IS THE SOURCE — both ports\n# carry a build-time-inlined copy (ts/src/sigdecl.ts, go/sigdecl.txt;\n# `make sig` regenerates both, and each port's suite asserts its copy\n# is byte-identical with this file) and parse it at initialisation\n# with the signature grammar, a tabnas grammar (ts/src/sig.ts,\n# go/sig.go). The suites also round-trip every line:\n# render(parse(line)) must be the line exactly, in both ports.\n#\n# The syntax (rendered TypeScript-ish, honest about argument MODES):\n#   line = name '(' [ arg {',' arg} ] ')' ':' type\n#   arg  = [mode] name ['?'] ':' type\n#        | '...' name ':' '(' [mode] type {',' [mode] type} ')'\n#   type = word {'|' word}\n#   mode = 'capture' | 'template' | 'trial' | 'projector' | 'text'\n# `value` mode is unmarked. `constraint` is the result word for\n# residuals whose meet depends on the peer; `any` is the honest type\n# where a function is a wrapper.\nupper(s: string|number, start?: integer|biginteger, len?: integer|biginteger) : string\nlower(s: string|number, start?: integer|biginteger, len?: integer|biginteger) : string\ncopy(v: any) : any\npref(v: any) : any\nsuper(t: any) : any\ntype(t: any) : any\nhide(v: any) : any\nmaybe(v: any) : any\nclose(m: any) : any\nopen(m: any) : any\nmove(v: any) : any\npath(capture p?: path) : path\nmap() : map\nlist() : list\nmin(n: number|string) : constraint\nmax(n: number|string) : constraint\nabove(n: number|string) : constraint\nbelow(n: number|string) : constraint\nre(text p: string) : constraint\nlength(n: number|constraint) : constraint\nkey(up?: integer|biginteger) : string\nunique(projector k?: string) : constraint\nneq(...vals: number|string) : constraint\nmust(trial c: any, text msg: string) : constraint\ndeprecate(v: any, r?: map) : any\nacyclic() : constraint\ninverse(projector k: string) : constraint\nrefer(template t?: any) : constraint\nrel(template t?: any) : constraint\npack(d: map|list, template t: any) : map\neach(d: map|list, template t: any) : list\nfilter(d: map|list, trial c: any) : map|list\nmatch(s: any, ...pr: (trial any, any), dflt?: any) : any\nadd(a: number, b: number) : number\nsub(a: number, b: number) : number\nmul(a: number, b: number) : number\ndiv(a: number, b: number) : number\nmod(a: number, b: number) : number\nrem(a: number, b: number) : number\nsum(d: map|list) : number\nleast(d: map|list) : number\ngreatest(d: map|list) : number\npick(d: map|list, projector k: string|integer) : any\nsort(d: map|list, projector k?: string|integer, dir?: string) : list\njoin(d: map|list, sep?: string) : string\nesc(s: string, variant?: string) : string\nusc(s: string, variant?: string) : string\nrep(s: string, text p: string, text sub: string) : string\nsplit(s: string, sep: string|constraint) : list\nemit(s: map|list, template t: map|list) : list\nabnf(g: string) : string\nparse(g: string, v?: string) : map|list|constraint\nnom(name: string, style?: string|list, acronyms?: list) : string|map\ntranslate(s: string, from: string, to?: string) : string\nproject(spec?: string|map, children?: list) : map\nfolder(spec: string|map, children?: list) : map\nfile(spec: string|map, children?: list) : map\ncontent(spec: string|map) : map\nline(spec: string|map) : map\nfragment(spec: string|map, children?: list) : map\nslot(spec: string|map, children?: list) : map\ninject(spec: string|map, children?: list) : map\ncopyfiles(spec: string|map) : map\nlistitems(spec: map, children?: list) : map\n"
 
 export { SIGDECL }

package/src/siggate.ts

@@ -1,31 +1,5 @@
 /* Copyright (c) 2021-2026 Richard Rodger, MIT License */
 
-// THE RUNTIME SIGNATURE CHECKER (docs/design/SIGNATURES.0.md). One
-// argument gate, run by the shared function machinery
-// (FuncBaseVal.unify) just before a call resolves, when its arguments
-// are driven: for each VALUE-mode argument whose declared type is
-// scalar-kind words, the driven Val must be a concrete scalar of an
-// admitted kind. A failure refuses as `func_arg`, whose hint renders
-// the signature line and names the offending argument -- the
-// error-message builder the registry exists for.
-//
-// The gate owns exactly the argument-shape refusals that were bare
-// `invalid-arg` at the call: the case family's operand, the
-// arithmetic operands, join's separator, pick's key. Everything with
-// more meaning than a shape mismatch keeps its own code: the bag
-// arguments (`pack_data`, `each_data`, `filter_data`,
-// `aggregate_data` -- container words are not gate words), the
-// constraint atoms (not on this path at all -- their refusals ride
-// the residual), `key()` (whose level meaning `key_level` names, and
-// which is skipped here for that reason), and the capture, template,
-// trial, projector and text modes, none of which are read as values.
-//
-// What the gate refuses it must POSITIVELY identify: a concrete
-// scalar of a wrong kind, a map, a list, or a scalar KIND marker
-// where a value belongs. Anything else -- a preference, a residual, a
-// disjunct -- passes through to the builtin's own logic, which is
-// what keeps arith's unpref reading and join's deferral working.
-// Twin: sigRefuse in go/siggate.go.
 
 import type { Val } from './type'
 import { AontuContext } from './ctx'
@@ -44,10 +18,6 @@ import {
 } from './val/ScalarKindVal'
 
 
-// The scalar-kind words the gate enforces, each to its lattice
-// marker. A declared type is gate-checkable only when EVERY union
-// word is here: `any`, `constraint`, and the container words leave
-// the argument to the builtin.
 const SIG_KIND = new Map<string, any>([
   ['string', String],
   ['number', Number],