aontu 0.52.0 → 0.53.0

package/src/val/RefVal.ts

@@ -1,7 +1,6 @@
 /* Copyright (c) 2021-2025 Richard Rodger, MIT License */
 
 
-import Util from 'node:util'
 
 import {
   walk,
@@ -49,6 +48,30 @@ import { BigDecimalVal } from './BigDecimalVal'
 const UNSPELLABLE_SEGMENT = '\u0000unspellable'
 
 
+// Is this value an unresolved type()/hide() call — or a conjunct still
+// carrying one? A reference that lands on one must defer rather than
+// clone it (see the call site in `find`): the marks such a call will
+// stamp belong to the field it was WRITTEN at, and a clone resolving
+// at the reference's site re-applies them after the reference's
+// mark-clearing walk has already run. Only the two mark wrappers
+// qualify — every other pending call resolves to an unmarked value,
+// and the existing early-clone behaviour for those is pinned
+// (move()/copy() ghost rows, hole-filling conjuncts).
+function pendingMarkWrapper(v: any): boolean {
+  if (true === v.isTypeFunc || true === v.isHideFunc) {
+    return !v.done
+  }
+  if (true === v.isConjunct && Array.isArray(v.peg)) {
+    for (const t of v.peg) {
+      if (pendingMarkWrapper(t)) {
+        return true
+      }
+    }
+  }
+  return false
+}
+
+
 class RefVal extends FeatureVal {
   isRef = true
   isGenable = true
@@ -175,7 +198,6 @@ class RefVal extends FeatureVal {
 
     const te = ctx.explain && explainOpen(ctx, ctx.explain, 'Ref', this, peer)
     let out: Val = this
-    let why = 'id'
 
     if (this.id !== peer.id) {
 
@@ -191,29 +213,24 @@ class RefVal extends FeatureVal {
       if (resolved instanceof RefVal) {
         if (peer.isTop) {
           out = this
-          why = 'pt'
         }
         else if (peer.isNil) {
           out = makeNilErr(ctx, 'ref[' + this.peg + ']', this, peer)
-          why = 'pn'
         }
 
         // same path
         else if (this.canon === peer.canon) {
           out = this
-          why = 'pp'
         }
 
         else {
           // Ensure RefVal done is incremented
           this.dc = DONE === this.dc ? DONE : this.dc + 1
           out = new ConjunctVal({ peg: [this, peer] }, ctx)
-          why = 'cj'
         }
       }
       else {
         out = unite(te ? ctx.clone({ explain: ec(te, 'RES') }) : ctx, resolved, peer, 'ref')
-        why = 'u'
       }
 
       out.dc = DONE === out.dc ? DONE : this.dc + 1
@@ -226,7 +243,15 @@ class RefVal extends FeatureVal {
   }
 
 
-  find(ctx: AontuContext) {
+  // `snap` is set by snapshotRefSpread (MapVal): a SPREAD snapshot
+  // wants the target's pre-resolution STRUCTURE — key()/path() still
+  // unresolved, to be re-resolved per destination — so the
+  // pending-mark-wrapper defer below must not apply to it. Deferring
+  // there made the snapshot wait until the target's own key() had
+  // resolved at the target, and the literal leaked into every
+  // destination (the exact failure the snapshot exists to prevent —
+  // test/spec/spread-type.tsv, spread-type-key-ref).
+  find(ctx: AontuContext, snap?: boolean) {
     let out: Val | undefined = undefined
 
     // Check if self.path starts with peg (cycle detection).
@@ -265,6 +290,16 @@ class RefVal extends FeatureVal {
 
       for (let pI = 0; pI < this.peg.length; pI++) {
         let part = this.peg[pI]
+        // An unspellable segment MISSES BEFORE ANY LOOKUP. The marker
+        // is NUL-prefixed because no spelling produces one, but a
+        // document can still hold a key spelled with an escaped NUL
+        // (`a:{"unspellable":7}`), and matching it would turn the
+        // silent path-shortening this marker exists to prevent into a
+        // different silent wrong value. The marker is a marker, never a
+        // lookup key.
+        if (UNSPELLABLE_SEGMENT === part) {
+          return makeNilErr(ctx, 'no_path', this)
+        }
         if (part instanceof VarVal) {
           let strval = (part as VarVal).peg
           let name = strval ? '' + strval.peg : ''
@@ -413,14 +448,52 @@ class RefVal extends FeatureVal {
       else if (pI === refpath.length) {
         out = node
 
-        // A reference landing on another reference may be a PROVEN
-        // mutual cycle (a: $.b, b: $.a) -- follow the plain-ref chain
-        // and, if it revisits a node, report path_cycle now instead of
-        // deferring every pass and dying later as a generic ref error.
-        // No proof (chain leaves plain refs, or ends) defers as before.
-        if (null != out && (out as any).isRef && this.detectRefCycle(ctx)) {
+        // A reference landing on another reference -- or on a FUNCTION,
+        // whose arguments the chase now follows (issue #35) -- may be a
+        // PROVEN mutual cycle (a: $.b, b: $.a; a: $.b, b: upper($.a)).
+        // Follow the chain and, if it returns to a node still open above
+        // it, report path_cycle now instead of deferring every pass and
+        // dying later as a spent budget. No proof (the chain leaves plain
+        // refs and calls, or ends) defers as before.
+        if (null != out && ((out as any).isRef || (out as any).isFunc) &&
+          this.detectRefCycle(ctx)) {
           out = makeNilErr(ctx, 'path_cycle', this)
         }
+        // A PENDING MARK WRAPPER IS NOT YET A VALUE TO COPY (ADR-005).
+        // A type()/hide() call still waiting for its argument — an
+        // alias reference inside a type() body, a generator inside a
+        // hide() — would be cloned here as the CALL, and the clone
+        // then resolves at the REFERENCE's site, stamping marks that
+        // the mark-clearing walk below has already run too early to
+        // clear. That is how a type-marked alias silently suppressed
+        // the referring field's emission (use-cases/BUGS.md §12), how
+        // `hide(pack(...))` leaked its mark onto downstream packs
+        // (§11), and how hide() around a computed field swallowed the
+        // value into a silent [] (§35b). Defer instead: the reference
+        // residuates until the wrapper has resolved at its OWN field,
+        // and the ordinary marked-value path below then clears the
+        // marks on the clone as documented. The move() reference
+        // (`_hide_found`) is exempt: a move TRANSPLANTS the pending
+        // call, and the ghost rows (test/spec/func.tsv) pin that its
+        // innards resolve at the destination.
+        else if (null != out && !snap && !this.mark._hide_found &&
+          pendingMarkWrapper(out)) {
+          out = undefined
+        }
+        // A STAGED ARGUMENT SNAPSHOTS A SETTLED SOURCE (the argsnap
+        // flag, set by driveStagedArgs). A generator's data argument is
+        // a copy OUTSIDE the tree, so anything in the target that still
+        // resolves against its own tree location — a spread-injected
+        // relative reference, a pending template — must finish there
+        // BEFORE the copy is taken: cloned earlier, the copy's rebased
+        // relative refs dangle under the generator and the model dies
+        // as *_no_gen with the generator never firing. Deferring here
+        // is exactly the documented staging rule: the generator waits
+        // for the source, then snapshots it whole.
+        else if (null != out && !snap && true === (ctx as any).argsnap &&
+          !out.done) {
+          out = undefined
+        }
         // Types and hidden values are cloned and made concrete
         else if (null != out) { //  && (out.mark.type || out.mark.hide)) {
 
@@ -449,6 +522,19 @@ class RefVal extends FeatureVal {
           walk(out, (_key: string | number | undefined, val: Val) => {
             val.mark.type = false
             val.mark.hide = false
+            // REFERENCES DO NOT CARRY IDENTITY (G4 phase 1, clearing
+            // rule 1). The clone is a copy of an entity, not the
+            // entity: without this, `w:b:$.q.a & {y:2,z:3}` (row
+            // `ref-and-merge`, test/spec/ref.tsv) would push `y:2`
+            // back into `q.a` through the identity merge — pinned
+            // behaviour, silently changed by a mark the author never
+            // wrote at the reference site.
+            //
+            // The LINK is NOT cleared (G4 phase 3): an identity says
+            // what a value IS, so a copy must not be that entity; a
+            // link says what a value POINTS AT, and a copy of a link
+            // points at the same thing.
+            val.entity = undefined
             return val
           })
           //}
@@ -468,33 +554,80 @@ class RefVal extends FeatureVal {
   // chain revisits a node -- a PROVEN reference cycle, distinct from a
   // merely unresolved reference. Detection is only on the resolution
   // chain revisiting a node, never on syntactic shape: a chain that
-  // passes through a variable segment, a conjunct, a function, or any
-  // non-ref value yields no proof and the ref defers as before.
+  // passes through a variable segment, a conjunct or any other non-ref
+  // value yields no proof and the ref defers as before.
+  //
+  // A FUNCTION is followed, through its arguments (issue #35). A
+  // function resolves only once every argument does, so a chain that
+  // reaches `b:upper($.a)` and out through `$.a` has proved the same
+  // dependency a bare `b:$.a` proves -- `a:$.b b:upper($.a)` is a cycle
+  // whichever link wears the call. Without this the shape exhausted the
+  // depth budget instead: a `unify_cycle`, which under the G5 taxonomy
+  // means "retry with more may help", where a proven structural cycle is
+  // FIX THE MODEL. A conjunct and a disjunct stay unfollowed for reasons
+  // that are not the same: a disjunct member may simply not be taken, so
+  // reaching one proves nothing; a conjunct would be sound to follow, and
+  // is left out only because nothing needs it yet.
+  //
+  // The Go port reaches the same verdict on this shape by a DIFFERENT
+  // arm, and that difference outlives this method: its clonePath re-paths
+  // a resolved clone to the referring site, so the inner `$.a` lands at
+  // path [a] and the plain isprefixpath test proves the cycle before any
+  // chase is needed. TypeScript's clone keeps the source paths. ADR-001
+  // asks for arm-for-arm correspondence, so the clone-path difference is
+  // worth closing on its own; it is wider than this issue and both ports
+  // now agree on the verdict and the code either way.
   detectRefCycle(ctx: AontuContext): boolean {
-    const seen = new Set<number>()
-    let cur: RefVal = this
-    // No hop cap: every iteration either returns or adds a NEW ref to
-    // `seen`, and the tree holds finitely many refs, so the chase
-    // terminates at the first repetition or the first non-ref — a cap
-    // would just make cycles longer than it invisible.
-    for (; ;) {
-      if (seen.has(cur.id)) {
-        return true
-      }
-      seen.add(cur.id)
-      const rp = cur.plainRefPath()
+    // Depth-first with an explicit ANCESTOR set, because a function may
+    // carry several reference arguments and the cycle can run through
+    // any one of them. The set holds the chain currently being walked,
+    // not every node ever walked: revisiting a node reached down a
+    // DIFFERENT branch is an ordinary shared reference (two keys reading
+    // one third key), and only revisiting one that is still open above
+    // us is a cycle.
+    //
+    // Identity is the RESOLVED PATH, not the RefVal instance: the same
+    // target can be reached through distinct ref instances, and it is
+    // returning to the same place that closes a loop.
+    const chase = (ref: RefVal, ancestors: Set<string>): boolean => {
+      const rp = ref.plainRefPath()
       if (null == rp) {
         return false
       }
+      const key = rp.join('')
+      if (ancestors.has(key)) {
+        return true
+      }
+
       let node: any = ctx.root
       for (let i = 0; i < rp.length && null != node; i++) {
         node = (node.isMap || node.isList) ? node.peg[rp[i]] : undefined
       }
-      if (null == node || !node.isRef) {
+      if (null == node) {
         return false
       }
-      cur = node
+
+      // Terminates: each level adds a path to `ancestors` and refuses a
+      // repeat, and the tree holds finitely many distinct paths.
+      ancestors.add(key)
+      let found = false
+      if (node.isRef) {
+        found = chase(node, ancestors)
+      }
+      else if (node.isFunc && Array.isArray(node.peg)) {
+        for (const arg of node.peg) {
+          if (null != arg && arg.isRef && chase(arg, ancestors)) {
+            found = true
+            break
+          }
+        }
+      }
+      ancestors.delete(key)
+
+      return found
     }
+
+    return chase(this, new Set<string>())
   }
 
 

package/src/val/ReferFuncVal.ts

@@ -0,0 +1,387 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// CHECKED, TYPED, LINK-SHAPED REFERENCES (G4 phase 2,
+// docs/capability-review/g4-identity-relations.md): `refer(t)` is a
+// constraint on a string-valued field. The string must be an ENTITY
+// ADDRESS, the addressed node must exist in the evaluation, and — when
+// `t` is given — `t` is unified INTO the target. The field's own value
+// stays the address string: a LINK, not an embedding.
+//
+// This is the piece a plain reference cannot be. `$.a.b` resolves by
+// CLONING its target into place, so `dependsOn: [$.services.auth]`
+// generates a full copy of the auth node where the author meant a
+// name. `refer` leaves the name and checks it.
+//
+// Constraint FLOW rather than a check: `refer(t)` does not merely test
+// the target against `t`, it unifies `t` into it. Referring to
+// something as a Service MAKES it one, and if it cannot be, the
+// conflict is an ordinary located error. Check-only semantics would be
+// non-monotone — true, then false as the target grows — and the
+// lattice guarantee is that more information never falsifies what has
+// been observed.
+
+import type {
+  Val,
+  ValSpec,
+} from '../type'
+
+import {
+  DONE,
+} from '../type'
+
+import {
+  AontuContext,
+} from '../ctx'
+
+import { makeNilErr } from '../err'
+
+import { FuncBaseVal } from './FuncBaseVal'
+import { FeatureVal } from './FeatureVal'
+import { StringVal } from './StringVal'
+import { unite } from '../unify'
+import { top } from './top'
+import { propagateMarks, walk } from '../utility'
+
+
+// A segment of the path INSIDE an entity. The entity name's own
+// grammar (no dots) is what makes the split unambiguous: everything
+// before the first dot names the entity, everything after walks its
+// value.
+const ADDR_SEGMENT = /^[A-Za-z0-9_-]+$/
+const ADDR_NAME = /^[A-Za-z0-9_/-]+$/
+
+
+export type Address = {
+  name: string
+  path: string[]
+}
+
+
+// The address a string spells, or undefined when it does not spell
+// one. `svc/auth` is the entity; `svc/auth.ports.http` is a node
+// inside it — the two addressing schemes reconciled: `$.a.b` answers
+// WHERE, an address answers WHAT, and beneath entity granularity the
+// tree is authoritative again.
+export function parseAddress(s: string): Address | undefined {
+  const parts = s.split('.')
+  if (!ADDR_NAME.test(parts[0])) {
+    return undefined
+  }
+  for (const seg of parts.slice(1)) {
+    if (!ADDR_SEGMENT.test(seg)) {
+      return undefined
+    }
+  }
+  return { name: parts[0], path: parts.slice(1) }
+}
+
+
+// The value an address names, or undefined when the evaluation does
+// not (yet) have one. Pending is not failure: an entity may be
+// declared by a later conjunct, include or spread, so `refer`
+// residuates exactly as a forward reference does.
+export function findEntity(
+  reg: Map<string, Val> | undefined, addr: Address
+): { parent?: any, key?: string, val: Val } | undefined {
+  const rep: any = reg?.get(addr.name)
+  if (null == rep) {
+    return undefined
+  }
+  let parent: any = undefined
+  let key: string | undefined = undefined
+  let val: any = rep
+  for (const seg of addr.path) {
+    if (true !== val?.isMap && true !== val?.isList) {
+      return undefined
+    }
+    const next = val.peg[seg]
+    if (null == next) {
+      return undefined
+    }
+    parent = val
+    key = seg
+    val = next
+  }
+  return { parent, key, val }
+}
+
+
+// concreteFlow is `t` as it enters the target: a copy with the
+// type/hide marks cleared at every depth. The clone matters as much as
+// the clearing — `t` is shared by every position that refers to the
+// same thing, and clearing in place would unmark the schema itself.
+function concreteFlow(ctx: AontuContext, t: Val): Val {
+  let marked = false
+  walk(t, (_key: string | number | undefined, v: Val) => {
+    marked = marked || v.mark.type || v.mark.hide
+    return v
+  })
+  // An unmarked flow type is passed THROUGH: cloning one anyway would
+  // move the site an error names, and a conflict has to point at what
+  // the author wrote.
+  if (!marked) {
+    return t
+  }
+  const out = t.clone(ctx)
+  walk(out, (_key: string | number | undefined, v: Val) => {
+    v.mark.type = false
+    v.mark.hide = false
+    return v
+  })
+  return out
+}
+
+
+// ReferVal is what `refer(t)` RESOLVES to: the residual constraint,
+// carrying the type to flow and — once it has met a string — the
+// address to flow it into. A separate value from the function for the
+// reason every residual is: the function is written once and the
+// constraint is met many times, and only the constraint has state
+// worth carrying.
+class ReferVal extends FeatureVal {
+  isRefer = true
+  isGenable = true
+
+  // The type to flow into the target; TOP when `refer()` was written
+  // with no argument.
+  tval: Val
+  // The address, once a string has been met.
+  addr?: Address
+  // The address AS WRITTEN, for canon and for the error message.
+  addrsrc?: string
+  // Constraints met while the address was still pending — a kind, a
+  // regex, a preference. They meet the LINK once there is one.
+  held?: Val
+
+  constructor(spec: ValSpec, ctx?: AontuContext) {
+    super(spec, ctx)
+    this.tval = (spec as any).tval ?? top()
+    this.addr = (spec as any).addr
+    this.addrsrc = (spec as any).addrsrc
+    this.held = (spec as any).held
+    this.dc = 0
+  }
+
+  // The residual's own state — the type to flow, the address it has
+  // met, the constraints it holds — TRAVELS with the clone. A spread
+  // template holds the FUNCTION, so a template never needs this; a
+  // REFERENCE to a value that already contains a resolved link does
+  // (`z: id(a) & {u: refer() & "a"}` then `s: $.z`). Without it the
+  // clone came back as a bare `refer()` — the address silently
+  // dropped, and the copied link resolving to nothing.
+  //
+  // No path-dependence hook, though: a residual is minted at its
+  // destination, so `key()` inside a template resolves there already.
+  clone(ctx: AontuContext, spec?: ValSpec): Val {
+    const out: any = super.clone(ctx, spec)
+    out.tval = this.tval
+    out.addr = this.addr
+    out.addrsrc = this.addrsrc
+    out.held = this.held
+    return out
+  }
+
+  unify(peer: Val, ctx: AontuContext): Val {
+    const p: any = peer
+
+    // Another `refer` at the same position: one constraint, both
+    // types. `refer(A) & refer(B)` is a target that must be both.
+    if (true === p?.isRefer) {
+      return this.with(ctx, {
+        tval: unite(ctx, this.tval, p.tval, 'refer-t'),
+        addr: this.addr ?? p.addr,
+        addrsrc: this.addrsrc ?? p.addrsrc,
+        held: null == this.held ? p.held
+          : null == p.held ? this.held
+            : unite(ctx, this.held, p.held, 'refer-held'),
+      }, this)
+    }
+
+    if (null == peer || true === p.isTop) {
+      return this.settle(ctx, this)
+    }
+
+    if (true === p.isNil) {
+      return peer
+    }
+
+    // A STRING is the ADDRESS, when there is not one yet. It is the
+    // only thing that can be: a link's value is its address.
+    if (undefined === this.addr
+      && true === p.isScalar && 'string' === typeof p.peg) {
+      const addr = parseAddress(p.peg)
+      if (undefined === addr) {
+        return makeNilErr(ctx, 'refer_address', this, peer, 'refer',
+          { addr: p.peg })
+      }
+      return this.with(ctx, { addr, addrsrc: p.peg }, peer)
+    }
+
+    // A value that can never BE a string cannot constrain one either,
+    // and no later pass can repair it — so this arm refuses rather
+    // than defers. A KIND or a constraint is not in it: `string`,
+    // `re("^svc/")` and the like are perfectly good constraints on an
+    // address, and are held below until there is one to apply them to.
+    if ((true === p.isScalar && 'string' !== typeof p.peg)
+      || true === p.isMap || true === p.isList) {
+      return makeNilErr(ctx, 'refer_address', this, peer, 'refer')
+    }
+
+    // HELD: everything else waits for the address. Carried on the
+    // residual rather than parked in a conjunct, because a conjunct
+    // rebuilt every pass grows a level every pass; the held constraint
+    // meets the link the moment the address resolves, so
+    // `refer() & "x" & "y"` still conflicts and `refer() & string & "x"`
+    // still passes.
+    return this.with(ctx, {
+      held: null == this.held ? peer : unite(ctx, this.held, peer, 'refer-held'),
+    }, this)
+  }
+
+  // with is the residual reshaped: every arm above answers a NEW
+  // ReferVal rather than mutating this one, because a spread template's
+  // residual is shared by every child it is applied to.
+  with(ctx: AontuContext, spec: any, site: Val): Val {
+    const out = new ReferVal({}, ctx)
+    out.tval = spec.tval ?? this.tval
+    out.addr = spec.addr ?? this.addr
+    out.addrsrc = spec.addrsrc ?? this.addrsrc
+    out.held = spec.held ?? this.held
+    propagateMarks(this, out)
+    out.site = site.site
+    out.path = this.path
+    return out.settle(ctx, site)
+  }
+
+  // settle answers the address if the evaluation can, and stays
+  // pending if it cannot YET. `site` is the value whose position the
+  // resolved string should take.
+  settle(ctx: AontuContext, site: Val): Val {
+    if (undefined === this.addr) {
+      // NOT DONE, unlike `string` or `min(1)`. A refer without an
+      // address has not done its work — it exists to check one — and
+      // the pass loop must keep offering it the chance. The cost is
+      // that a SCHEMA mentioning a link never resolves either, so
+      // `type({from: refer($.std.Port)})` is not expressible today;
+      // G4 phase 4 records why, and what it would take.
+      this.dc = 0
+      return this
+    }
+    const reg: Map<string, Val> | undefined = (ctx as any)?.entities
+    const found = findEntity(reg, this.addr)
+    if (undefined === found) {
+      // PENDING, not failed — until the last pass. An entity may be
+      // declared by a later conjunct, include or spread, so `refer`
+      // residuates as a forward reference does; but within ONE
+      // evaluation the document-set is fixed, so existence IS
+      // decidable, and the final pass is where it is decided. A
+      // pending refer keeps the tree not-done, so the pass loop always
+      // reaches that pass when there is one to decide.
+      if (ctx.cc + 1 >= ctx.budget.passes) {
+        return makeNilErr(ctx, 'refer_unresolved', this, undefined, 'refer',
+          { addr: this.addrsrc as string })
+      }
+      this.dc = 0
+      return this
+    }
+
+    // THE FLOW. `t` is unified into the target and written back, so
+    // every position of the entity carries it after the pass's
+    // identity merge — the same channel the merge itself uses.
+    //
+    // RE-ENTRANT ONLY ONCE PER ENTITY (use-cases/BUGS.md §19). Uniting
+    // the target drives the target's OWN subtree, and if the target
+    // links back — `a` typed-refers `b`, `b` typed-refers `a`, the
+    // shape every inverse pair has — that drives this entity again,
+    // and the two flow into each other until the depth budget or the
+    // host stack ends it. `unify_cycle` on a model whose meet plainly
+    // converges: `{k:1}` meeting `{k:1}` is a fixpoint, and the
+    // evaluator never got far enough to notice.
+    //
+    // The guard is the set of entities a flow is currently inside, on
+    // the context. A flow that would re-enter one is SKIPPED, not
+    // failed: the outer flow it is nested in is already uniting that
+    // entity, so the same information arrives by the same channel one
+    // frame up. What each flow contributes is unchanged; only the
+    // order it arrives in is, and unification does not care.
+    const flowing: Set<string> = ((ctx as any)._referflow ??=
+      new Set<string>())
+    if (!this.tval.isTop && !flowing.has(this.addr.name)) {
+      flowing.add(this.addr.name)
+      try {
+        // The flowed type is CONCRETE at the target: a schema flowing
+        // into a value must not make the value a schema. Same reasoning
+        // as a reference's clone clearing marks — `refer($.std.Service)`
+        // says the target IS a Service, not that it is the definition
+        // of one — and without it the target silently stopped
+        // generating.
+        const merged = unite(ctx, found.val, concreteFlow(ctx, this.tval),
+          'refer-flow')
+        if (true === (merged as any).isNil) {
+          return merged
+        }
+        if (undefined === found.parent) {
+          reg!.set(this.addr.name, merged)
+        }
+        else {
+          found.parent.peg[found.key as string] = merged
+        }
+      }
+      finally {
+        flowing.delete(this.addr.name)
+      }
+    }
+
+    // The value IS the address string: a link, not an embedding.
+    const out: any = new StringVal({ peg: this.addrsrc as string }, ctx)
+    out.dc = DONE
+    // STAMPED as a link (G4 phase 3): the value is the address string,
+    // so without this nothing downstream could tell a checked link from
+    // a literal that happens to look like one. The edge set is exactly
+    // the set of these stamps.
+    out.link = this.addrsrc
+    propagateMarks(this, out)
+    out.site = site.site
+    out.path = this.path
+    return null == this.held ? out : unite(ctx, out, this.held, 'refer-held')
+  }
+
+  get canon() {
+    const t = this.tval.isTop ? '' : this.tval.canon
+    const call = 'refer(' + t + ')' +
+      (null == this.held ? '' : '&' + this.held.canon)
+    return undefined === this.addrsrc
+      ? call : call + '&' + JSON.stringify(this.addrsrc)
+  }
+}
+
+
+class ReferFuncVal extends FuncBaseVal {
+  isReferFunc = true
+
+  constructor(spec: ValSpec, ctx?: AontuContext) {
+    super(spec, ctx)
+  }
+
+  make(_ctx: AontuContext, spec: ValSpec): Val {
+    return new ReferFuncVal(spec)
+  }
+
+  funcname() {
+    return 'refer'
+  }
+
+  resolve(ctx: AontuContext, args: Val[]) {
+    const out = new ReferVal({}, ctx)
+    out.tval = 0 < args.length ? args[0] : top()
+    out.site = this.site
+    out.path = this.path
+    return out
+  }
+} /* node:coverage ignore next 6 */
+
+
+export {
+  ReferFuncVal,
+  ReferVal,
+}