aontu 0.62.0 → 0.63.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) {