Merge loops/relations into architecture: relations-on-sx — cross-domain relationship graph on Datalog

Reachability/ancestors/descendants, shortest path + all-route enumeration,
cycle detection, roots/leaves, siblings/degree, ancestors/LCA/topo-order,
weakly-connected components, trust-gated federation, and bulk lifecycle
(relate-many/unrelate-node cascade). Engine derives from an effective relation
erel (local edges + trust-gated peer links); graph algorithms computed in SX
over the minimal Datalog ruleset (every query re-saturates). 158/158, 9 suites.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

plans/relations-on-sx.md

@@ -18,7 +18,7 @@ links. Reuses `lib/datalog/` — does not reimplement the engine.
 
 ## Status (rolling)
 
-`bash lib/relations/conformance.sh` → **0/0** (not yet started)
+`bash lib/relations/conformance.sh` → **158/158** (Phases 1–4 complete + extensions)
 
 ## Ground rules
 
@@ -61,46 +61,176 @@ lib/relations/federation.sx
 
 ## Phase 1 — Schema + direct relations
 
-- [ ] `lib/relations/schema.sx` — `rel(Src, Dst, Kind)` fact projection; a small
+- [x] `lib/relations/schema.sx` — `rel(Src, Dst, Kind)` fact projection; a small
   kind vocabulary (`parent`, `member`, `reply`, `variant`, `origin`, …) kept open
-- [ ] `lib/relations/api.sx` — `(relations/relate src dst kind)` / `(unrelate …)`
+- [x] `lib/relations/api.sx` — `(relations/relate src dst kind)` / `(unrelate …)`
   over a live Datalog db (assert/retract); `(children-of db node kind)`,
   `(parents-of db node kind)`, `(related db node kind)`
-- [ ] `lib/relations/tests/direct.sx` — assert/retract, direct children/parents,
+- [x] `lib/relations/tests/direct.sx` — assert/retract, direct children/parents,
   kind filtering, unknown node → empty
-- [ ] `lib/relations/conformance.sh` + scoreboard
+- [x] `lib/relations/conformance.sh` + scoreboard
 
 ## Phase 2 — Reachability + cycles
 
-- [ ] recursive reachability rules: `ancestors`, `descendants`, `reachable?(A,B)`
+- [x] recursive reachability rules: `ancestors`, `descendants`, `reachable?(A,B)`
   (transitive closure over a kind, the acl inheritance shape)
-- [ ] `roots` / `leaves` (no parents / no children) for a kind
-- [ ] cycle detection: `cycle?(X)` ⇔ `reachable(X, X)`; `acyclic?(db, kind)`
-- [ ] `lib/relations/tests/reach.sx` — deep chains, diamonds, disconnected nodes,
+- [x] `roots` / `leaves` (no parents / no children) for a kind
+- [x] cycle detection: `cycle?(X)` ⇔ `reachable(X, X)`; `acyclic?(db, kind)`
+- [x] `lib/relations/tests/reach.sx` — deep chains, diamonds, disconnected nodes,
   self-loops, multi-kind isolation
 
 ## Phase 3 — Typed relations + path explanation
 
-- [ ] multiple kinds coexisting; mixed-kind vs single-kind reachability
-- [ ] `lib/relations/explain.sx` — `(path db a b kind)` returns the connecting
+- [x] multiple kinds coexisting; mixed-kind vs single-kind reachability
+- [x] `lib/relations/explain.sx` — `(path db a b kind)` returns the connecting
   chain (the relationship equivalent of acl's proof tree), nil if unreachable
-- [ ] `(distance db a b kind)` (hops) + shortest-path selection
-- [ ] `lib/relations/tests/path.sx` — path correctness, shortest among many, no-path
+- [x] `(distance db a b kind)` (hops) + shortest-path selection
+- [x] `lib/relations/tests/path.sx` — path correctness, shortest among many, no-path
 
 ## Phase 4 — Federation
 
-- [ ] cross-instance relationships — a peer asserts `rel(local, remote, kind)`;
+- [x] cross-instance relationships — a peer asserts `rel(local, remote, kind)`;
   replicate rel facts via fed-sx (mock the transport in tests)
-- [ ] trust gating — a peer's link binds locally only under a local trust fact
+- [x] trust gating — a peer's link binds locally only under a local trust fact
   (mirror acl's non-transitive `trust`/gate-in-engine model; do NOT copy acl code,
   re-derive the shape)
-- [ ] revocation — retract a replicated link; reachability re-saturates
-- [ ] `lib/relations/tests/fed.sx` — federated reachability chains, trust gating,
+- [x] revocation — retract a replicated link; reachability re-saturates
+- [x] `lib/relations/tests/fed.sx` — federated reachability chains, trust gating,
   revocation
 
+## Extensions (post-roadmap)
+
+- [x] **shape queries** — `siblings` (nodes sharing a parent), `out-degree`/
+  `in-degree`, weakly-connected `connected?` (undirected reachability). Computed in
+  SX over the fast direct `erel` queries (BFS) — deliberately NOT added as Datalog
+  closures, to keep the per-query saturation cheap. `lib/relations/tests/shape.sx`.
+- [x] **tree/DAG queries** — `common-ancestors` (ancestor-set intersection), `lca`
+  (lowest common ancestors — a set; tree → singleton, DAG → may be several),
+  `topo-order` (Kahn-style; nil for cyclic kinds). New `lib/relations/tree.sx`,
+  computed in SX over `reach`/`ancestors`/`rnode`. `lib/relations/tests/tree.sx`.
+- [x] **route enumeration** — `all-paths` (all simple directed paths a→b, not just
+  the shortest; cycle-safe DFS) in explain.sx. `lib/relations/tests/routes.sx`.
+- [x] **bulk lifecycle** — `relate-many!` (batch assert) + `unrelate-node!` (cascade
+  cleanup: retract every local edge touching a node, all kinds, both directions —
+  for domain object deletion; leaves federated peer links alone). api.sx,
+  `lib/relations/tests/bulk.sx`.
+- [x] **weakly-connected components** — `component` (the undirected cluster of a
+  node), `components` (partition of all nodes for a kind), `component-count`. In
+  tree.sx, reusing `ureach-bfs`. `lib/relations/tests/comp.sx`.
+
 ## Progress log
 
-(loop fills this in)
+- **Extension: weakly-connected components** (158/158). `relations-component`
+  (the undirected cluster containing a node = `ureach-bfs` from it),
+  `relations-components` (greedy partition: pop a remaining node, take its
+  component, repeat) and `relations-component-count`, in tree.sx, + `relations/...`
+  wrappers. `lib/relations/tests/comp.sx` (11 tests: cluster from either end, self-
+  loop as its own component, partition contents, count, kind isolation, api).
+  Engine surface now feels SATURATED — base roadmap + 5 graph-algorithm extensions
+  cover direct/transitive/undirected reach, paths (shortest + all routes), cycles,
+  roots/leaves, siblings/degree, ancestors/LCA/topo, components, federation, and
+  bulk lifecycle. Pacing down.
+- **Extension: bulk lifecycle** (147/147). `relations-relate-many!` (batch
+  `dl-assert!` over a list of (src dst kind) triples) and `relations-unrelate-node!`
+  (query `rel` for every edge with the node as src or dst, across all kinds, then
+  `dl-retract!` each — the cascade-cleanup a domain needs when it deletes the
+  object a node id names). Federated `peer_rel` links are a peer's assertion and
+  are deliberately left untouched. + `relations/relate-many!`/`unrelate-node!`
+  wrappers, `lib/relations/tests/bulk.sx` (12 tests: batch assert, cascade across
+  kinds/both directions, unrelated edges preserved, unknown-node no-op, api layer).
+- **Extension: route enumeration** (135/135). `relations-all-paths(db,a,b,kind)`
+  in explain.sx — every simple (no repeated node) directed path a→b, not just the
+  shortest one `relations-path` returns; DFS that skips nodes already on the
+  current path so cyclic data terminates; a=b → `((a))`, no route → `()`. Reuses
+  engine's `relations-concat-map`/`-eng-member?`/`children-of`. + `relations/all-paths`
+  wrapper, `lib/relations/tests/routes.sx` (9 tests: two-route diamond, single
+  route, no route, self, route-through-cycle, route count, kind isolation).
+- **Extension: tree/DAG queries** (126/126). New `lib/relations/tree.sx`:
+  `relations-common-ancestors` (intersection of the two ancestor sets),
+  `relations-lca` (common ancestors with no other common ancestor reachable below
+  them — a SET, since a DAG can have several lowest common ancestors; a tree gives
+  one), `relations-topo-order` (Kahn-style level-by-level: place every node whose
+  parents are all placed; nil for a cyclic kind) + `relations-nodes` (the `rnode`
+  set) and `relations/...` wrappers. All in SX over the engine's fast queries —
+  again no new Datalog closures. `tree.sx` (16 tests) covers diamond common
+  ancestors, LCA on tree vs converging-DAG, no-common-ancestor, topo validity
+  (parents precede children), and cyclic-kind → nil.
+- **Extension: shape queries** (110/110). Added `relations-siblings`,
+  `relations-out-degree`/`-in-degree`, `relations-connected?` (+ `relations/...`
+  current-db wrappers) and `shape.sx` (18 tests). Design note: an earlier attempt
+  added `sibling`/`uedge`/`ureach` as Datalog rules in the global `relations-rules`;
+  because every `dl-query` re-saturates the whole program, the extra recursive
+  undirected closure taxed EVERY query in EVERY suite and the full run blew past
+  10 min. Reverted the ruleset to the Phase-4 set and compute these in SX instead:
+  siblings = children-of(parents-of(node)) − node; connected? = undirected BFS
+  expanding `relations-related` (children ∪ parents) per frontier with a visited
+  set. No new saturation cost; other suites unaffected. NB: the full 110-test
+  conformance takes several minutes under shared-machine contention (sibling loops)
+  — run with `timeout 1200` in the background; individual suites run in seconds.
+- **Phase 4 — federation** (92/92). Re-derived acl's trust-gate shape (not
+  copied). engine.sx now derives the whole engine from an EFFECTIVE relation
+  `erel` rather than raw `rel`: `erel(S,D,K) :- rel(S,D,K)` (local, always) and
+  `erel(S,D,K) :- peer_rel(P,S,D,K), trust(P)` (peer link, gated by a local trust
+  fact). reach/reach_any/rnode/has_parent/has_child all read `erel`, and the
+  direct-query fns moved into engine.sx to query `erel` too — so with no
+  peer_rel/trust facts `erel ≡ rel` and Phases 1–3 are unchanged. Trust is a body
+  literal, re-checked every saturation, so it is non-transitive (only a peer's own
+  links bind, only under local trust(P)) and revocation is immediate. New
+  federation.sx: `relations-peer-rel`/`relations-trust` constructors, a mock
+  fed-sx transport (`relations-fed-fetch`/`-collect` over a peer→links dict),
+  `relations-fed-build-db` (local facts + pulled peer links), and
+  `relations-fed-assert!`/`relations-revoke!` over a live db. fed.sx covers
+  untrusted-link-doesn't-bind, trusted-link-binds (child + federated reachability
+  + connecting path through the federated edge), non-transitive trust (peerB's
+  link inert without trust(peerB)), link revocation, trust revocation (local edge
+  survives), transport pull with selective trust, and live fed-assert!. The shared
+  recursive-reachability shape with acl is flagged (Phase 2 note); the trust-gate
+  is the same convergence — still NOT extracted, per ground rules.
+- **Phase 3 — typed relations + path explanation** (70/70). New `explain.sx`:
+  `relations-path(db,a,b,kind)` is relations' answer to acl's proof tree — the
+  `reach(K,a,b)` derivation read off as the node chain. lib/datalog/ keeps no
+  provenance, so the chain is re-derived breadth-first over the saturated edge set
+  (`relations-children-of` per frontier node) so the returned path is a SHORTEST
+  derivation; every consecutive pair is a real `rel` fact (no invented edges) and
+  a visited set makes cyclic data terminate. `relations-distance` = hops (0 for
+  a=b, nil if unreachable). Mixed-kind reachability added to engine.sx as a
+  kind-agnostic `reach_any` closure (`relations-descendants-any`,
+  `relations-reachable-any?`) — distinct from single-kind `reach`, so tests show a
+  parent+member graph where a→m is reachable cross-kind but not under `parent`
+  alone. api/explain grew `relations/path`, `/distance`, `/descendants-any`,
+  `/reachable-any?` current-db wrappers. path.sx covers shortest-among-many
+  (a→c→d beats a→b→c→d), direct edge, self path, no-path/disconnected, kind
+  isolation in paths, mixed vs single kind, and path-out-of-a-cycle. Note: the
+  dict-mode conformance driver has no per-suite timeout and the shared machine is
+  contended by sibling loops — a full run can take a few minutes; the path suite
+  alone runs in <1s.
+- **Phase 2 — reachability + cycles** (46/46). New `engine.sx` is one Datalog
+  ruleset. Reachability is kind-parameterised — `reach(K,X,Y)` carries the kind as
+  its first arg so a transitive walk over `parent` never leaks through `reply`
+  edges (the acl inheritance shape, but closures can't cross kinds). `rnode`
+  collects touched nodes; `root`/`leaf` use stratified negation over
+  `has_parent`/`has_child`. Cycles are data, not errors: `cycle?(node,kind)` ⇔
+  `reach(K,node,node)` holds, `acyclic?(kind)` ⇔ no `reach(K,X,X)`. Engine fns:
+  `relations-descendants/-ancestors/-reachable?/-roots/-leaves/-cycle?/-acyclic?`;
+  api.sx grew matching `relations/...` current-db wrappers. `relations-rules` and
+  `relations-pluck` moved from api.sx into engine.sx (engine now loads before api
+  in conformance.conf). reach.sx covers diamonds, deep chains, disconnected
+  components, self-loops, c1<->c2 cycles, and multi-kind isolation. acl
+  convergence: the `reach(X,Y):-edge(X,Y)` / `reach(X,Y):-edge(X,Z),reach(Z,Y)`
+  closure shape is shared with acl's eff_grant/eff_deny inheritance — flagged, not
+  extracted (per ground rules).
+- **Phase 1 — schema + direct relations** (22/22). `schema.sx`: `rel(Src,Dst,Kind)`
+  fact constructor + accessors, open kind vocabulary (`parent member reply variant
+  origin link`), `relations-fact-valid?`/`relations-known-kind?`. `api.sx`: db built
+  via `dl-program-data facts relations-rules` (Phase 1 rules empty — direct queries
+  need none); `relations-children-of`/`-parents-of`/`-related` are plain `dl-query`
+  on the `rel` relation, plucking the bound column from substitution dicts;
+  current-db convenience layer (`relations/load!`, `relations/relate`,
+  `relations/unrelate`, `relations/children`/`parents`/`related`) over `dl-assert!`/
+  `dl-retract!`, mirroring lib/acl/api.sx. Tests cover direct children/parents, leaf/
+  root empties, kind isolation (parent query skips reply edge), retract, the api
+  layer, and schema/constructor shape. Note: query result order is nondeterministic
+  — tests use an order-insensitive `set=?`.
 
 ## Blockers