aontu 0.53.0 → 0.55.0

package/dist/val/ReferFuncVal.js

@@ -1,53 +1,50 @@
 "use strict";
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ReferVal = exports.ReferFuncVal = void 0;
-exports.parseAddress = parseAddress;
-exports.findEntity = findEntity;
+exports.RelVal = exports.RelFuncVal = exports.ReferVal = exports.ReferFuncVal = void 0;
+exports.addressPath = addressPath;
+exports.findAt = findAt;
 const type_1 = require("../type");
 const err_1 = require("../err");
 const FuncBaseVal_1 = require("./FuncBaseVal");
+const PathVal_1 = require("./PathVal");
 const FeatureVal_1 = require("./FeatureVal");
-const StringVal_1 = require("./StringVal");
+const ConjunctVal_1 = require("./ConjunctVal");
 const unify_1 = require("../unify");
 const top_1 = require("./top");
 const utility_1 = require("../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_/-]+$/;
-// 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.
-function parseAddress(s) {
-    const parts = s.split('.');
-    if (!ADDR_NAME.test(parts[0])) {
-        return undefined;
+// 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 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.
+function addressPath(addr, at) {
+    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.
-function findEntity(reg, addr) {
-    const rep = reg?.get(addr.name);
-    if (null == rep) {
+function findAt(root, path) {
+    if (null == root || 0 === path.length) {
         return undefined;
     }
     let parent = undefined;
     let key = undefined;
-    let val = rep;
-    for (const seg of addr.path) {
+    let val = root;
+    for (const seg of path) {
         if (true !== val?.isMap && true !== val?.isList) {
             return undefined;
         }
@@ -96,6 +93,16 @@ class ReferVal extends FeatureVal_1.FeatureVal {
         super(spec, ctx);
         this.isRefer = true;
         this.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.
+        this.cjo = 120000;
+        // The codes this residual refuses with: refer() keeps its own,
+        // rel()-minted residuals carry rel_address/rel_unresolved.
+        this.addrcode = 'refer_address';
+        this.unresolvedcode = 'refer_unresolved';
         this.tval = spec.tval ?? (0, top_1.top)();
         this.addr = spec.addr;
         this.addrsrc = spec.addrsrc;
@@ -106,7 +113,7 @@ class ReferVal extends FeatureVal_1.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.
     //
@@ -118,6 +125,9 @@ class ReferVal extends FeatureVal_1.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;
     }
     unify(peer, ctx) {
@@ -140,31 +150,43 @@ class ReferVal extends FeatureVal_1.FeatureVal {
         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 (0, err_1.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 = (0, PathVal_1.parseAddress)(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)
+        // 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 = (0, PathVal_1.prefixMeet)(this.addrsrc, p.peg);
+            if (undefined === merged) {
+                return (0, err_1.makeNilErr)(ctx, 'scalar_value', this, peer);
+            }
+            return this.with(ctx, { addr: (0, PathVal_1.parseAddress)(merged), 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 (0, err_1.makeNilErr)(ctx, 'refer_address', this, peer, 'refer');
+            return (0, err_1.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 : (0, unify_1.unite)(ctx, this.held, peer, 'refer-held'),
         }, this);
@@ -178,6 +200,9 @@ class ReferVal extends FeatureVal_1.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;
         (0, utility_1.propagateMarks)(this, out);
         out.site = site.site;
         out.path = this.path;
@@ -197,75 +222,134 @@ class ReferVal extends FeatureVal_1.FeatureVal {
             this.dc = 0;
             return this;
         }
-        const reg = ctx?.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 (0, err_1.makeNilErr)(ctx, this.unresolvedcode, this, undefined, 'refer', { addr: this.addrsrc });
+        }
+        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 (0, err_1.makeNilErr)(ctx, 'refer_unresolved', this, undefined, 'refer', { addr: this.addrsrc });
+                return (0, err_1.makeNilErr)(ctx, this.unresolvedcode, this, undefined, 'refer', { addr: this.addrsrc });
             }
             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 = (ctx._referflow ??=
-            new Set());
-        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 = (0, unify_1.unite)(ctx, found.val, concreteFlow(ctx, this.tval), 'refer-flow');
-                if (true === merged.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 = ctx._referflow ?? new Set();
+        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 = ctx.referflows ??
+                new Map();
+            const key = target.join('\x00');
+            const prev = flows.get(key);
+            flows.set(key, null == prev ? flow : (0, unify_1.unite)(ctx, prev, flow, 'refer-flow-record'));
+            if (!flowing.has(guard)) {
+                flowing.add(guard);
+                try {
+                    const merged = (0, unify_1.unite)(ctx, found.val, flow, 'refer-flow');
+                    if (true === merged.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._trialMode) {
+                        found.parent.peg[found.key] = merged;
+                    }
                 }
-                else {
-                    found.parent.peg[found.key] = merged;
+                finally {
+                    flowing.delete(guard);
                 }
             }
-            finally {
-                flowing.delete(this.addr.name);
-            }
         }
-        // The value IS the address string: a link, not an embedding.
-        const out = new StringVal_1.StringVal({ peg: this.addrsrc }, 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 = new PathVal_1.PathVal({ peg: this.addrsrc }, ctx);
         out.dc = type_1.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;
+        }
         (0, utility_1.propagateMarks)(this, out);
         out.site = site.site;
         out.path = this.path;
@@ -275,11 +359,228 @@ class ReferVal extends FeatureVal_1.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 + ')';
     }
 }
 exports.ReferVal = ReferVal;
+// 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_1.FeatureVal {
+    constructor(spec, ctx) {
+        super(spec, ctx);
+        this.isRel = true;
+        this.isGenable = true;
+        this.cjo = 45000;
+        this.tval = spec.tval ?? (0, top_1.top)();
+        this.held = spec.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 = type_1.DONE;
+    }
+    clone(ctx, spec) {
+        const out = 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) {
+        const path = ctx.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, relkey) {
+        const rv = new ReferVal({ tval: this.tval }, 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, container) {
+        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, container, relkey) {
+        const out = container.clone(ctx);
+        const peg = out.peg;
+        const keys = Array.isArray(peg)
+            ? peg.map((_v, i) => 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 = peg[k];
+            if (true === child.isMap || true === child.isList) {
+                nested = true;
+                const sub = this.rewriteUnder(ctx.descend('' + k), child, relkey);
+                peg[k] = sub;
+                pending = pending || true !== sub.done;
+            }
+            else if (undefined === child.link) {
+                let leaf = (0, unify_1.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 = (0, unify_1.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.spread.cj) {
+            let tmpl = this.leafRefer(ctx, relkey);
+            if (null != this.held) {
+                tmpl = new ConjunctVal_1.ConjunctVal({ peg: [tmpl, this.held] }, ctx);
+            }
+            ;
+            out.spread.cj = tmpl;
+        }
+        return out;
+    }
+    unify(peer, ctx) {
+        const p = peer;
+        // Two rel() at one field: one relation, both types.
+        if (true === p?.isRel) {
+            const out = new RelVal({}, ctx);
+            out.tval = (0, unify_1.unite)(ctx, this.tval, p.tval, 'rel-t');
+            out.held = null == this.held ? p.held
+                : null == p.held ? this.held
+                    : (0, unify_1.unite)(ctx, this.held, p.held, 'rel-held');
+            (0, utility_1.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 = (0, unify_1.unite)(ctx, this.leafRefer(ctx, this.fieldkey(ctx)), peer, 'rel-scalar');
+            return null == this.held ? out
+                : (0, unify_1.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 (0, err_1.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 = new RelVal({}, ctx);
+        out.tval = this.tval;
+        out.held = null == this.held ? peer
+            : (0, unify_1.unite)(ctx, this.held, peer, 'rel-held');
+        (0, utility_1.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);
+    }
+}
+exports.RelVal = RelVal;
+class RelFuncVal extends FuncBaseVal_1.FuncBaseVal {
+    constructor(spec, ctx) {
+        super(spec, ctx);
+        this.isRelFunc = true;
+    }
+    make(_ctx, spec) {
+        return new RelFuncVal(spec);
+    }
+    funcname() {
+        return 'rel';
+    }
+    resolve(ctx, args) {
+        const out = new RelVal({}, ctx);
+        out.tval = 0 < args.length ? args[0] : (0, top_1.top)();
+        out.site = this.site;
+        out.path = this.path;
+        return out;
+    }
+}
+exports.RelFuncVal = RelFuncVal;
 class ReferFuncVal extends FuncBaseVal_1.FuncBaseVal {
     constructor(spec, ctx) {
         super(spec, ctx);
@@ -298,6 +599,6 @@ class ReferFuncVal extends FuncBaseVal_1.FuncBaseVal {
         out.path = this.path;
         return out;
     }
-} /* node:coverage ignore next 6 */
+} /* node:coverage ignore next 10 */
 exports.ReferFuncVal = ReferFuncVal;
 //# sourceMappingURL=ReferFuncVal.js.map