aontu 0.52.0 → 0.53.0

package/src/query.ts

@@ -0,0 +1,379 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// 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'
+import { exactJSON } from './exactjson'
+import { anchorAt } from './vet'
+import type { VetFinding } from './vet'
+import { cmpCodePoint } from './keyorder'
+import { Provenance } from './provenance'
+import type { WhyRecord } from './provenance'
+
+
+export type QueryView = 'json' | 'canon' | 'types' | 'keys'
+
+export type QueryOptions = {
+  view?: QueryView
+  // Levels of structure kept below the selected node; everything
+  // deeper renders as `top`. Undefined means the whole subtree.
+  depth?: number
+  // Where the document CAME FROM, so a relative `@"file"` load inside
+  // 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 `@"x.js"` is arbitrary code execution in the
+  // evaluating process. A server passes `{include:'none'}`.
+  trust?: TrustOptions
+}
+
+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[]
+}
+
+
+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
+  let bestd = Infinity
+  for (const k of have) {
+    const d = editDistance(want, k)
+    if (d < bestd) {
+      bestd = d
+      best = k
+    }
+  }
+  // Half the name may differ, no more: past that the suggestion is
+  // noise, and a wrong suggestion costs more than none.
+  return bestd <= Math.max(1, Math.floor(want.length / 2)) ? best : undefined
+}
+
+
+function editDistance(a: string, b: string): number {
+  const prev: number[] = []
+  for (let j = 0; j <= b.length; j++) {
+    prev[j] = j
+  }
+  for (let i = 1; i <= a.length; i++) {
+    let diag = prev[0]
+    prev[0] = i
+    for (let j = 1; j <= b.length; j++) {
+      const tmp = prev[j]
+      prev[j] = Math.min(
+        prev[j] + 1,
+        prev[j - 1] + 1,
+        diag + (a[i - 1] === b[j - 1] ? 0 : 1))
+      diag = tmp
+    }
+  }
+  return prev[b.length]
+}
+
+
+// The path split anchorAt walks: `$` and empty segments dropped, so
+// `$`, `$.` and `` all name the root.
+export function pathParts(path: string): string[] {
+  const trimmed = path.startsWith('$') ? path.slice(1) : path
+  return trimmed.split('.').filter((p) => '' !== p)
+}
+
+
+// The queried path, normalised the way anchorAt reads it — so a
+// finding names `$.a.b` whether the caller wrote that, `a.b` or
+// `$.a.b.` — and `$` for the root.
+function pathText(path: string): string {
+  const parts = pathParts(path)
+  return '$' + (0 < parts.length ? '.' + parts.join('.') : '')
+}
+
+
+// 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
+  }
+  if (true === v?.isMap) {
+    const keys = Object.keys(v.peg).sort(cmpCodePoint)
+    return '{' +
+      (v.spread.cj ? '&:' + project(v.spread.cj, view, depth - 1) +
+        (0 < keys.length ? ',' : '') : '') +
+      keys.map((k) =>
+        JSON.stringify(k) +
+        (v.optionalKeys.includes(k) ? '?' : '') +
+        ':' +
+        project(v.peg[k], view, depth - 1)).join(',') +
+      '}'
+  }
+  if (true === v?.isList) {
+    const keys = Object.keys(v.peg)
+    return '[' +
+      (v.spread.cj ? '&:' + project(v.spread.cj, view, depth - 1) +
+        (0 < keys.length ? ',' : '') : '') +
+      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)
+  }
+  if (true === v?.isConjunct || true === v?.isDisjunct) {
+    return v.peg.map((m: any) =>
+      true === m?.isJunction && 1 < m.peg.length
+        ? '(' + project(m, view, depth) + ')'
+        : project(m, view, depth))
+      .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
+}
+
+
+// The `keys` listing: the node's own key names (or list indices), one
+// per line, code-point ordered as canon orders them. A leaf has none,
+// which is an empty answer rather than an error — "nothing below
+// here" is a true statement about a scalar.
+function keyList(v: any): string {
+  if (true === v?.isMap) {
+    return Object.keys(v.peg).sort(cmpCodePoint).join('\n')
+  }
+  if (true === v?.isList) {
+    return Object.keys(v.peg).join('\n')
+  }
+  return ''
+}
+
+
+function finding(
+  code: string, path: string, message: string, note?: string): VetFinding {
+  return {
+    code,
+    class: 'reference',
+    severity: 'error',
+    path,
+    message,
+    sites: [],
+    ...(null == note ? {} : { note }),
+  }
+}
+
+
+// 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)
+}
+
+
+// The refusal for a path that names nothing, shared by `get` and
+// `why`: WHICH segment failed, and what was there instead — the "did
+// you mean" the no_path contract promises. Walking again is cheap (the
+// tree is in hand) and is the only way to name the parent.
+export function noPathFinding(root: any, path: string): VetFinding {
+  const parts = pathParts(path)
+  let at: any = root
+  let want = ''
+  for (const part of parts) {
+    const next: any = anchorAt(at, part)
+    if (null == next) {
+      want = part
+      break
+    }
+    at = next
+  }
+  const have = true === at?.isMap
+    ? Object.keys(at.peg).sort(cmpCodePoint)
+    : (true === at?.isList ? Object.keys(at.peg) : [])
+  const near = nearestKey(want, have)
+  return finding(
+    'no_path',
+    pathText(path),
+    `The path ${path} names nothing in this document.`,
+    null == near ? undefined : `did you mean ${near}?`)
+}
+
+
+// Evaluate the document, select the node at `path`, and render it.
+export function get(
+  src: string, path: string, opts?: QueryOptions): QueryReport {
+  const options = opts ?? {}
+  const view: QueryView = options.view ?? 'json'
+
+  const aontu = new Aontu(
+    null == options.trust ? undefined : { trust: options.trust })
+  const ctx = aontu.ctx({ collect: true })
+  const parseOpts = null == options.path ? undefined : { path: options.path }
+  const root: any = aontu.unify(src, parseOpts, ctx)
+
+  if (0 < ctx.err.length || null == root || true === root.isNil) {
+    return { ok: false, out: '', findings: [evalFailure(ctx)] }
+  }
+
+  const node: any = anchorAt(root, path)
+  if (null == node) {
+    return { ok: false, out: '', findings: [noPathFinding(root, path)] }
+  }
+
+  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) {
+      const err: any = ctx.err[before]
+      return {
+        ok: false,
+        out: '',
+        findings: [finding(
+          err?.why ?? 'no_gen',
+          pathText(path),
+          err?.msg ?? 'The value at this path is not concrete.')],
+      }
+    }
+    return { ok: true, out: exactJSON(gen, 2), findings: [] }
+  }
+  if ('keys' === view) {
+    return { ok: true, out: keyList(node), findings: [] }
+  }
+  return {
+    ok: true,
+    out: project(node, view, options.depth ?? Infinity),
+    findings: [],
+  }
+}
+
+
+export type WhyReport = {
+  ok: boolean
+  record?: WhyRecord
+  findings: VetFinding[]
+}
+
+
+// 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 ?? {}
+  const aontu = new Aontu(
+    null == options.trust ? undefined : { trust: options.trust })
+  const prov = new Provenance()
+  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)] }
+  }
+  prov.writtenFrom(parsed)
+
+  const root: any = aontu.unify(parsed, parseOpts, ctx)
+  if (0 < ctx.err.length || null == root || true === root.isNil) {
+    return { ok: false, findings: [evalFailure(ctx)] }
+  }
+
+  const node: any = anchorAt(root, path)
+  if (null == node) {
+    return { ok: false, findings: [noPathFinding(root, path)] }
+  }
+
+  // The value that stands here is a contribution when nothing met
+  // (see Provenance.stands): a generator places a value without a
+  // meet, and "nothing met at this path" is not an answer to "where
+  // did this come from".
+  const parts = pathParts(path)
+  prov.stands(parts, node)
+
+  return {
+    ok: true,
+    record: {
+      conjuncts: prov.at(parts),
+      path: pathText(path),
+      value: node.canon,
+    },
+    findings: [],
+  }
+}

package/src/reach.ts

@@ -0,0 +1,184 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// REACHABILITY OVER THE ENTITY 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'
+import type { VetFinding } from './vet'
+import type { TrustOptions } from './type'
+import { graphOf } from './graph'
+import { cmpCodePoint } from './keyorder'
+
+
+export type ReachVerdict = 'reaches' | 'unreachable' | 'error'
+
+export type ReachReport = {
+  verdict: ReachVerdict
+
+  // The path found, as entity names 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 entity. Present ONLY on `error`.
+  errors?: VetFinding[]
+}
+
+export type ReachOptions = {
+  // Where the document CAME FROM, so a relative `@"file"` load inside
+  // it resolves from its own directory (relationCheck's precedent).
+  path?: string
+  // The include capability this document evaluates under (G5,
+  // docs/trust.md).
+  trust?: TrustOptions
+  // Follow only edges under this relation. Absent means follow every
+  // edge, which is the whole graph and the commoner question.
+  relation?: string
+}
+
+
+// The entity an address names --- everything before the first dot. A
+// link into `svc/auth.ports.http` reaches `svc/auth`: reachability is
+// between ENTITIES, and the path inside one says which part of it the
+// link arrives at. Same rule as relation.ts's entityOf, and it has to
+// be, or the two verbs would disagree about what an edge connects.
+function entityOf(addr: string): string {
+  const dot = addr.indexOf('.')
+  return dot < 0 ? addr : addr.slice(0, dot)
+}
+
+
+function endpointFinding(name: string, known: string[]): VetFinding {
+  return {
+    code: 'refer_unresolved',
+    class: 'reference',
+    severity: 'error',
+    path: '$',
+    // NOT "unreachable". An endpoint that names no entity 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 entity in this document.`,
+    sites: [],
+    ...(0 === known.length ? {} : {
+      note: 'known entities: ' + known.join(', '),
+    }),
+  }
+}
+
+
+// The reachability check for one document.
+export function reachCheck(
+  src: string, from: string, to: string, opts?: ReachOptions
+): ReachReport {
+  const options = opts ?? {}
+  const aontu = new Aontu(
+    null == options.trust ? undefined : { trust: options.trust })
+  const ctx = aontu.ctx({ collect: true })
+  const parseOpts = null == options.path ? undefined : { path: options.path }
+  const root: any = aontu.unify(src, parseOpts, ctx)
+
+  // A document that does not stand up is not a document with an
+  // unreachable pair: the errors it already has are the answer.
+  if (0 < ctx.err.length || true === root?.isNil) {
+    return {
+      verdict: 'error',
+      errors: [failureFinding(ctx, options.path, root)],
+    }
+  }
+
+  const graph = graphOf(root)
+  const known = graph.entities.map((e) => e.id).sort(cmpCodePoint)
+  const missing = [from, to].filter((n) => !known.includes(n))
+  if (0 < missing.length) {
+    return {
+      verdict: 'error',
+      errors: missing.map((n) => endpointFinding(n, known)),
+    }
+  }
+
+  // The successor map, restricted to one relation when the caller asked
+  // for one. Sorted, so the path the search finds is the same one in
+  // both ports.
+  const succ = new Map<string, string[]>()
+  for (const e of graph.edges) {
+    if ('' === e.from ||
+      (null != options.relation && options.relation !== e.key)) {
+      continue
+    }
+    const list = succ.get(e.from)
+    const dest = entityOf(e.to)
+    if (undefined === list) {
+      succ.set(e.from, [dest])
+    }
+    else if (!list.includes(dest)) {
+      list.push(dest)
+    }
+  }
+  for (const list of succ.values()) {
+    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]
+  while (0 < front.length) {
+    const next: string[] = []
+    for (const node of front) {
+      for (const dest of succ.get(node) ?? []) {
+        if (dest === to) {
+          const path = [dest]
+          let step = node
+          while (step !== from) {
+            path.unshift(step)
+            step = prev.get(step) as string
+          }
+          path.unshift(from)
+          return { verdict: 'reaches', path }
+        }
+        if (!seen.has(dest)) {
+          seen.add(dest)
+          prev.set(dest, node)
+          next.push(dest)
+        }
+      }
+    }
+    front = next
+  }
+
+  return { verdict: 'unreachable' }
+}