aontu 0.53.0 → 0.55.0

package/src/val/ReferFuncVal.ts

@@ -36,61 +36,59 @@ import {
 import { makeNilErr } from '../err'
 
 import { FuncBaseVal } from './FuncBaseVal'
+import {
+  Address,
+  PathVal,
+  parseAddress,
+  prefixMeet,
+} from './PathVal'
 import { FeatureVal } from './FeatureVal'
-import { StringVal } from './StringVal'
+import { ConjunctVal } from './ConjunctVal'
 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[]
-}
+// A RELATION PREDICATE is still a declared D-1 name
+// (docs/design/RELATIONS.0.md §3.2). Entity names are gone with
+// ADR-014; predicate names are not -- a relation is a vocabulary term,
+// not an address.
+const PREDICATE_NAME = /^[_a-zA-Z][-_a-zA-Z0-9]*$/
 
 
-// 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
+// The tree path an address resolves to from `at` -- the position of
+// the link itself -- or undefined when a relative address climbs off
+// the top of the tree.
+export function addressPath(
+  addr: Address, at: (string | number)[]
+): string[] | undefined {
+  if (addr.absolute) {
+    return addr.parts
   }
-  for (const seg of parts.slice(1)) {
-    if (!ADDR_SEGMENT.test(seg)) {
-      return undefined
-    }
+  // The SIBLING scope: drop the link's own key, then take the parent
+  // steps. A link at `$.a.b.dep` spelling `.other` means `$.a.b.other`.
+  const cut = at.length - 1 - addr.up
+  if (cut < 0) {
+    return undefined
   }
-  return { name: parts[0], path: parts.slice(1) }
+  return at.slice(0, cut).map(String).concat(addr.parts)
 }
 
 
-// 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`
+// The node a tree path names, with the parent and key that hold it so
+// a type flow can be written back. Pending is not failure: the target
+// may be introduced 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
+export function findAt(
+  root: Val | undefined, path: string[]
 ): { parent?: any, key?: string, val: Val } | undefined {
-  const rep: any = reg?.get(addr.name)
-  if (null == rep) {
+  if (null == root || 0 === path.length) {
     return undefined
   }
   let parent: any = undefined
   let key: string | undefined = undefined
-  let val: any = rep
-  for (const seg of addr.path) {
+  let val: any = root
+  for (const seg of path) {
     if (true !== val?.isMap && true !== val?.isList) {
       return undefined
     }
@@ -141,6 +139,12 @@ function concreteFlow(ctx: AontuContext, t: Val): Val {
 class ReferVal extends FeatureVal {
   isRefer = true
   isGenable = true
+  // AFTER the plain values (base 99999), BEFORE the sizing atoms
+  // (LATE_CJO): sibling path values fold together first under the
+  // prefix rule, and the residual then meets ONE merged address --
+  // without this, `refer() & path($.a) & path($.a.b)` settled on the
+  // first path and the second met the finished link too late.
+  cjo = 120000
 
   // The type to flow into the target; TOP when `refer()` was written
   // with no argument.
@@ -152,6 +156,15 @@ class ReferVal extends FeatureVal {
   // Constraints met while the address was still pending — a kind, a
   // regex, a preference. They meet the LINK once there is one.
   held?: Val
+  // The PREDICATE the produced link belongs to, when this residual was
+  // minted by `rel()` on a field: the field's key, stamped onto the
+  // link so the graph reports the edge under a DECLARED relation
+  // rather than inferring one from the path (RELATIONS.0.md §3.2).
+  relkey?: string
+  // The codes this residual refuses with: refer() keeps its own,
+  // rel()-minted residuals carry rel_address/rel_unresolved.
+  addrcode: string = 'refer_address'
+  unresolvedcode: string = 'refer_unresolved'
 
   constructor(spec: ValSpec, ctx?: AontuContext) {
     super(spec, ctx)
@@ -166,7 +179,7 @@ class ReferVal extends FeatureVal {
   // 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
+  // (`z: {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.
   //
@@ -178,6 +191,9 @@ class ReferVal extends FeatureVal {
     out.addr = this.addr
     out.addrsrc = this.addrsrc
     out.held = this.held
+    out.relkey = this.relkey
+    out.addrcode = this.addrcode
+    out.unresolvedcode = this.unresolvedcode
     return out
   }
 
@@ -205,34 +221,47 @@ class ReferVal extends FeatureVal {
       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 })
-      }
+    // A PATH VALUE is the ADDRESS, when there is not one yet. Only a
+    // path value can be one (PATHS.0.md, amended): a bare string is
+    // never a path -- `path("...")` is the one string conversion, and
+    // it happens at the call, not here. The peg is pre-validated by
+    // the capture, so no parse can fail.
+    if (undefined === this.addr && true === p.isPath) {
+      const addr = parseAddress(p.peg) as Address
       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)
+    // A SECOND path peer refines the address by the prefix rule: the
+    // longer of the two when one opens the other, exactly as two path
+    // values meet on their own. Two incomparable addresses are the
+    // same conflict two unequal scalars are.
+    if (undefined !== this.addr && true === p.isPath) {
+      const merged = prefixMeet(this.addrsrc as string, p.peg)
+      if (undefined === merged) {
+        return makeNilErr(ctx, 'scalar_value', this, peer)
+      }
+      return this.with(ctx,
+        { addr: parseAddress(merged) as Address, addrsrc: merged }, peer)
+    }
+
+    // A value that can never BE a path cannot be the address, and no
+    // later pass can repair it — so this arm refuses rather than
+    // defers. A bare STRING is in it now (PATHS.0.md, amended):
+    // `path("...")` is the one conversion, at the call. 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 && true !== p.isPath)
       || true === p.isMap || true === p.isList) {
-      return makeNilErr(ctx, 'refer_address', this, peer, 'refer')
+      return makeNilErr(ctx, this.addrcode, 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.
+    // `refer() & re("a") & re("b") & path($.z)` still applies both and
+    // `refer() & string & path($.z)` still passes.
     return this.with(ctx, {
       held: null == this.held ? peer : unite(ctx, this.held, peer, 'refer-held'),
     }, this)
@@ -247,6 +276,9 @@ class ReferVal extends FeatureVal {
     out.addr = spec.addr ?? this.addr
     out.addrsrc = spec.addrsrc ?? this.addrsrc
     out.held = spec.held ?? this.held
+    out.relkey = this.relkey
+    out.addrcode = this.addrcode
+    out.unresolvedcode = this.unresolvedcode
     propagateMarks(this, out)
     out.site = site.site
     out.path = this.path
@@ -267,79 +299,141 @@ class ReferVal extends FeatureVal {
       this.dc = 0
       return this
     }
-    const reg: Map<string, Val> | undefined = (ctx as any)?.entities
-    const found = findEntity(reg, this.addr)
+    // The address is a TREE PATH, resolved from the link's own
+    // position for a relative one. A climb off the top of the tree can
+    // never be repaired by a later pass, so it refuses at once.
+    const target = addressPath(this.addr, this.path)
+    if (undefined === target) {
+      return makeNilErr(ctx, this.unresolvedcode, this, undefined, 'refer',
+        { addr: this.addrsrc as string })
+    }
+    const found = findAt(ctx?.root, target)
     if (undefined === found) {
-      // PENDING, not failed — until the last pass. An entity may be
-      // declared by a later conjunct, include or spread, so `refer`
+      // PENDING, not failed — until the last pass. The target may be
+      // introduced 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',
+        return makeNilErr(ctx, this.unresolvedcode, 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.
+    // THE FLOW. `t` is unified into the target and written back at the
+    // target's own position — one position, because the tree is the
+    // namespace and a path names exactly one node.
     //
-    // RE-ENTRANT ONLY ONCE PER ENTITY (use-cases/BUGS.md §19). Uniting
+    // RE-ENTRANT ONLY ONCE PER TARGET (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,
+    // shape every inverse pair has — that drives this target 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)
+    // The guard is the set of paths a flow is currently inside, on the
+    // context. A flow that would re-enter one has its MEET skipped:
+    // the outer flow it is nested in is already uniting that node, and
+    // re-entering is what runs the host stack out.
+    //
+    // ITS RECORD IS STILL WRITTEN. The skip used to take the record
+    // with it, on the reasoning that "the same information arrives by
+    // the same channel one frame up" -- true of the outer flow's TYPE,
+    // and false of a nested flow carrying a DIFFERENT one. The outer
+    // flow delivers only its own type, the residual is consumed into a
+    // settled link in the same breath, and nothing re-offers it: the
+    // nested type was lost for good, and which of two flows was the
+    // nested one depended on which link the evaluator happened to
+    // reach first. A layering rule declared on one field and reached
+    // through another module's mirror therefore held in one
+    // declaration order and not in the other (BUGS.md 69).
+    //
+    // Recording it DEFERS the meet to `applyFlows`, which runs at the
+    // top of the tree with no flow in flight and so cannot re-enter
+    // anything -- the channel this record already exists to be.
+    const guard = target.join('.')
+    // Seeded on the unify root (ts/src/unify.ts): a `??=` here would
+    // make a fresh set on whichever descended context asked first.
+    const flowing: Set<string> = (ctx as any)._referflow ?? new Set<string>()
+    if (!this.tval.isTop) {
+      // 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 flow = concreteFlow(ctx, this.tval)
+
+      // THE RECORD, keyed by the target's path, replayed onto every
+      // later pass by applyFlows in ts/src/unify.ts. A pass rebuilds
+      // subtrees, so the write below does not survive one when the
+      // link sits inside its own target or two nodes link at each
+      // other; the record is what makes the flow reach the result
+      // rather than the tree it was computed from.
+      const flows: Map<string, Val> = (ctx as any).referflows ??
+        new Map<string, Val>()
+      const key = target.join('\x00')
+      const prev = flows.get(key)
+      flows.set(key, null == prev ? flow : unite(ctx, prev, flow,
+        'refer-flow-record'))
+
+      if (!flowing.has(guard)) {
+        flowing.add(guard)
+        try {
+          const merged = unite(ctx, found.val, flow, 'refer-flow')
+          if (true === (merged as any).isNil) {
+            return merged
+          }
+          // The write into THIS pass's view, so the rest of the pass
+          // sees it. findAt refuses the empty path, so a resolved
+          // target always has a parent holding it.
+          //
+          // NOT FROM INSIDE A TRIAL. A disjunction member is a
+          // HYPOTHESIS, and writing its flow into the live tree
+          // asserts the member's type on another node before the
+          // member is known to survive. The `unite` above still runs:
+          // its nil is how a member legitimately fails. Only the
+          // COMMIT waits, and the surviving member's flow reaches the
+          // tree on the next pass, from the record DisjunctVal stages
+          // and merges for survivors alone.
+          if (true !== (ctx as any)._trialMode) {
+            found.parent.peg[found.key as string] = merged
+          }
         }
-        else {
-          found.parent.peg[found.key as string] = merged
+        finally {
+          flowing.delete(guard)
         }
       }
-      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)
+    // The value IS the address, as a PATH VALUE (ADR-016): a link,
+    // not an embedding -- and re-stating or refining the address
+    // still meets it, which a string link could not do under the
+    // strict rules.
+    const out: any = new PathVal({ 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
+    // the set of these stamps. A rel()-minted link also carries its
+    // PREDICATE (the rel field's key), so the graph reports a declared
+    // relation rather than inferring one from the path.
+    //
+    // The stamp is the RESOLVED path, not the written one: a relative
+    // address means a different node from each position it is written
+    // at, and an edge set whose far ends were spellings rather than
+    // nodes could not be traversed. The VALUE stays what the author
+    // wrote --- the link is what it says, the edge is where it goes.
+    out.link = '$.' + target.join('.')
+    if (undefined !== this.relkey) {
+      out.relkey = this.relkey
+    }
     propagateMarks(this, out)
     out.site = site.site
     out.path = this.path
@@ -350,8 +444,255 @@ class ReferVal extends FeatureVal {
     const t = this.tval.isTop ? '' : this.tval.canon
     const call = 'refer(' + t + ')' +
       (null == this.held ? '' : '&' + this.held.canon)
+    // The address renders as the path call: a bare string address no
+    // longer reparses (PATHS.0.md, amended), and canon must.
     return undefined === this.addrsrc
-      ? call : call + '&' + JSON.stringify(this.addrsrc)
+      ? call : call + '&path(' + this.addrsrc + ')'
+  }
+}
+
+
+// RelVal is what `rel(t?)` RESOLVES to (RELATIONS.0.md §3.2): the
+// relation constraint, sited on the FIELD the way the sizing atoms sit
+// on containers. Its value may be one address, a LIST of addresses, or
+// a MAP whose string leaves are addresses -- the container shapes are
+// rewritten leaf by leaf through the refer machinery, so pending
+// resolution, type flow and link stamping are the one battle-tested
+// path, and the data side stays plain strings. The PREDICATE of every
+// edge produced is the key the rel() sits on -- declared once, in the
+// schema, never inferred from the path.
+class RelVal extends FeatureVal {
+  isRel = true
+  isGenable = true
+  cjo = 45000
+
+  // The type to flow into each target; TOP when `rel()` has none.
+  tval: Val
+  // Container-level constraints met before the container arrived
+  // (`rel() & length(min(1)) & [...]`): they meet the REWRITTEN
+  // container, exactly as refer's held meets the link.
+  held?: Val
+
+  constructor(spec: ValSpec, ctx?: AontuContext) {
+    super(spec, ctx)
+    this.tval = (spec as any).tval ?? top()
+    this.held = (spec as any).held
+    // DONE while unmet, deliberately -- the property refer() lacks and
+    // G4 phase 4 records the cost of: a type() body holding a rel()
+    // must SETTLE, or the schema idiom (`dependsOn?: rel($.T)` inside
+    // a vocabulary) leaves the type unresolved and every reference to
+    // it deferring forever. An unmet rel is its own settled residual,
+    // like `min(1)`; the meet re-activates it whenever a value
+    // arrives, because map merges build the conjunct regardless.
+    this.dc = DONE
+  }
+
+  clone(ctx: AontuContext, spec?: ValSpec): Val {
+    const out: any = super.clone(ctx, spec)
+    out.tval = this.tval
+    out.held = this.held
+    return out
+  }
+
+  // The predicate: the last segment of the field path the constraint
+  // is being APPLIED at -- when that segment is a D-1 NAME. A relation
+  // predicate is a declared name (RELATIONS.0.md §3.2), so a list
+  // index or a key outside the name grammar produces unlabelled
+  // links, and the graph falls back to its old inference. The D-1
+  // test is also what keeps the two ports' edges identical: a list
+  // index is a number here and a string in Go.
+  //
+  // THE PATH COMES FROM THE CONTEXT, not from `this.path`. The val's
+  // own path records where this constraint was CLONED FROM, and the
+  // two part company the moment a second document merges into an
+  // entity: the field's constraint is then driven at the ENTITY, and
+  // `this.path` names the entity while the context names the field.
+  // The predicate became the entity's own key, every link under it
+  // minted an edge starting one level too high, and `inverse(n)`
+  // reported a mirror that was written as missing.
+  fieldkey(ctx: AontuContext): string | undefined {
+    const path: any[] = (ctx as any).path
+    const seg = path[path.length - 1]
+    return 'string' === typeof seg && PREDICATE_NAME.test(seg) ? seg : undefined
+  }
+
+  // One leaf's residual: the refer machinery carrying rel's codes,
+  // predicate and type. The predicate is passed IN, because the field
+  // it names is decided where the rewrite starts and must not be
+  // re-read on the way down (see `rewriteUnder`).
+  leafRefer(ctx: AontuContext, relkey: string | undefined): ReferVal {
+    const rv = new ReferVal({ tval: this.tval } as any, ctx)
+    rv.addrcode = 'rel_address'
+    rv.unresolvedcode = 'rel_unresolved'
+    rv.relkey = relkey
+    rv.site = this.site
+    rv.path = this.path
+    return rv
+  }
+
+  // The container, every string leaf wrapped as a link. Nested
+  // containers descend; a leaf already STAMPED as a link is left
+  // alone, which is what makes a second application (a template
+  // re-applied, a later pass) a no-op.
+  rewrite(ctx: AontuContext, container: any): Val {
+    return this.rewriteUnder(ctx, container, this.fieldkey(ctx))
+  }
+
+  // The rewrite proper, carrying the predicate decided at the field.
+  // It is decided ONCE, at the top: a map-valued relation
+  // (`dependsOn: {primary: [...]}`) descends through the inner label
+  // and must still report `dependsOn`, which is the whole reason a
+  // link carries a declared predicate rather than letting the graph
+  // infer one from its position.
+  rewriteUnder(
+    ctx: AontuContext, container: any, relkey: string | undefined
+  ): Val {
+    const out: any = container.clone(ctx)
+    const peg: any = out.peg
+    const keys: any[] = Array.isArray(peg)
+      ? peg.map((_v: any, i: number) => i) : Object.keys(peg)
+    let pending = false
+    let nested = false
+    for (const k of keys) {
+      // Children here are always Vals: the parse builds Vals, elision
+      // builds a NilVal, and clone preserved whatever the container
+      // held.
+      const child: any = peg[k]
+      if (true === child.isMap || true === child.isList) {
+        nested = true
+        const sub: any = this.rewriteUnder(ctx.descend('' + k), child, relkey)
+        peg[k] = sub
+        pending = pending || true !== sub.done
+      }
+      else if (undefined === child.link) {
+        let leaf = unite(ctx.descend('' + k), this.leafRefer(ctx, relkey),
+          child, 'rel-leaf')
+        // The held constraints apply PER LEAF: a re() on the relation
+        // constrains every address, never the container that holds
+        // them (found by the service catalog, whose re("^svc_") met
+        // the whole list and refused it).
+        if (null != this.held) {
+          leaf = unite(ctx.descend('' + k), leaf, this.held, 'rel-held')
+        }
+        peg[k] = leaf
+        pending = pending || true !== leaf.done
+      }
+    }
+    // The rewrite holds its PENDING leaves open (an address whose
+    // entity a later statement declares), so the pass loop keeps
+    // driving the container until every link settles. A rewrite that
+    // minted NOTHING pending -- every leaf already linked or settled
+    // in place -- keeps the clone's doneness: re-applying a template
+    // over a settled value must converge in the same pass, or the
+    // enclosing bags reopen forever (the service catalog, where the
+    // entity merge drops the spread stamp each pass).
+    if (pending) {
+      out.dc = 0
+    }
+    // Elements that arrive AFTER this rewrite -- another statement of
+    // the list, a patch position of the entity -- must convert too, so
+    // the rewrite installs its own leaf constraint as the container's
+    // ELEMENT SPREAD, exactly the machinery the old per-element
+    // `[&: refer()]` idiom used. Only on a FLAT address container (a
+    // labelled map's sub-containers get their own spread from the
+    // recursion above; a leaf template meeting a map child would
+    // refuse it), and only where no spread already stands: a schema's
+    // own template is not this rewrite's to clobber.
+    if (!nested && null == (out as any).spread.cj) {
+      let tmpl: Val = this.leafRefer(ctx, relkey)
+      if (null != this.held) {
+        tmpl = new ConjunctVal({ peg: [tmpl, this.held] }, ctx)
+      }
+      ; (out as any).spread.cj = tmpl
+    }
+    return out
+  }
+
+  unify(peer: Val, ctx: AontuContext): Val {
+    const p: any = peer
+
+    // Two rel() at one field: one relation, both types.
+    if (true === p?.isRel) {
+      const out: any = new RelVal({}, ctx)
+      out.tval = unite(ctx, this.tval, p.tval, 'rel-t')
+      out.held = null == this.held ? p.held
+        : null == p.held ? this.held
+          : unite(ctx, this.held, p.held, 'rel-held')
+      propagateMarks(this, out)
+      out.site = this.site
+      out.path = this.path
+      return out
+    }
+
+    // No null/top/nil arms: unite's dispatch ladder absorbs those
+    // peers before any Val's own unify is consulted (a null or top
+    // peer returns this side; a nil peer returns the nil), and unite
+    // is the only entrance -- the container hand-offs pass the
+    // container itself.
+
+    // ONE ADDRESS: the scalar-valued field, refer's own shape. A path
+    // value only -- a bare string is never an address (PATHS.0.md,
+    // amended); the scalar arm below refuses it.
+    if (true === p.isPath) {
+      const out = unite(ctx, this.leafRefer(ctx, this.fieldkey(ctx)), peer,
+        'rel-scalar')
+      return null == this.held ? out
+        : unite(ctx, out, this.held, 'rel-held')
+    }
+
+    // A SET OF LINKS: list or map, rewritten leaf by leaf; the held
+    // constraints ride into each leaf inside the rewrite.
+    if (true === p.isMap || true === p.isList) {
+      return this.rewrite(ctx, peer)
+    }
+
+    // A scalar that can never be an address.
+    if (true === p.isScalar) {
+      return makeNilErr(ctx, 'rel_address', this, peer, 'refer')
+    }
+
+    // Everything else -- a reference still resolving, a kind, a
+    // container constraint -- waits for the value, as refer's held
+    // does.
+    const out: any = new RelVal({}, ctx)
+    out.tval = this.tval
+    out.held = null == this.held ? peer
+      : unite(ctx, this.held, peer, 'rel-held')
+    propagateMarks(this, out)
+    out.site = this.site
+    out.path = this.path
+    return out
+  }
+
+  get canon() {
+    const t = this.tval.isTop ? '' : this.tval.canon
+    return 'rel(' + t + ')' +
+      (null == this.held ? '' : '&' + this.held.canon)
+  }
+}
+
+
+class RelFuncVal extends FuncBaseVal {
+  isRelFunc = true
+
+  constructor(spec: ValSpec, ctx?: AontuContext) {
+    super(spec, ctx)
+  }
+
+  make(_ctx: AontuContext, spec: ValSpec): Val {
+    return new RelFuncVal(spec)
+  }
+
+  funcname() {
+    return 'rel'
+  }
+
+  resolve(ctx: AontuContext, args: Val[]) {
+    const out = new RelVal({}, ctx)
+    out.tval = 0 < args.length ? args[0] : top()
+    out.site = this.site
+    out.path = this.path
+    return out
   }
 }
 
@@ -378,10 +719,14 @@ class ReferFuncVal extends FuncBaseVal {
     out.path = this.path
     return out
   }
-} /* node:coverage ignore next 6 */
+} /* node:coverage ignore next 10 */
 
 
+// The address machinery itself (Address, parseAddress, prefixMeet)
+// lives in PathVal, its home since ADR-016 -- import it from there.
 export {
   ReferFuncVal,
   ReferVal,
+  RelFuncVal,
+  RelVal,
 }