rose-ash/plans/relations-on-sx.md

relations-on-sx: Cross-domain relationship graph on Datalog

rose-ash's internal relations service tracks parent/child and peer relationships across domains — a blog post's comments, a thread's replies, a product's variants, an order's line items, a resource's containment tree, a federated content's origin. The questions are graph questions: who are X's children? its ancestors? is A reachable from B? what's the chain that connects them? is there a cycle?

That is recursive Datalog in one rule — the same bottom-up reachability acl-on-sx uses for group/resource inheritance. Decisions come with a trace: not just "yes, related," but the path that proves it. relations is an internal-only service (no public URL); other domains call it to resolve hierarchy and linkage.

End-state: a Datalog-on-SX layer for typed relationship facts, with reachability, path explanation, cycle detection, and a federation extension for cross-instance links. Reuses lib/datalog/ — does not reimplement the engine.

Status (rolling)

bash lib/relations/conformance.sh → 92/92 (Phases 1–4 complete)

Ground rules

• Scope: only lib/relations/** and plans/relations-on-sx.md. Do not edit spec/, hosts/, shared/, lib/datalog/**, or other lib/<lang>/. You may import from lib/datalog/ (public API in lib/datalog/datalog.sx); do not copy or modify Datalog.
• Shared-file issues → "Blockers" with a minimal repro; do not fix here.
• SX files: sx-tree MCP tools only; sx_validate after every edit.
• Architecture: relationships are rel(Src, Dst, Kind) Datalog facts; reachability/ancestry are recursive rules; the proof tree is the connecting path; the lifecycle (assert/retract) is an SX layer over the db. Keep relations content-agnostic — a node is an opaque id string; domains own what ids mean.
• Shared with acl-sx: both run on Datalog and both lean on the same recursive- reachability shape (reach(X,Y) :- edge(X,Y). / reach(X,Y) :- edge(X,Z), reach(Z,Y).). Watch for it; flag convergence in the Progress log, but do not extract — plans/mod-on-sx.md records why cross-subsystem extraction waits for the architecture integrator with all consumers in view.
• Commits: one feature per commit. Keep Progress log updated and tick boxes.

Architecture sketch

relate(src, dst, kind)                  query
        │                                  │
        ▼                                  ▼
lib/relations/schema.sx          lib/relations/engine.sx
  — rel(Src,Dst,Kind) facts         — children/parents/ancestors/descendants
  — kind vocabulary                 — reachable?(A,B), cycle?(X)
        │                                  ▲
        ▼                                  │
lib/relations/api.sx             lib/relations/explain.sx
  — relate / unrelate               — path(A,B): the connecting chain
  — registry over a live db           (from the Datalog derivation)
        │
        ▼
lib/relations/federation.sx
  — cross-instance links via fed-sx (replicated rel facts, peer-trust gated)

Phase 1 — Schema + direct relations

• 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 …) 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, kind filtering, unknown node → empty
• lib/relations/conformance.sh + scoreboard

Phase 2 — Reachability + cycles

• 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, 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 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

Phase 4 — Federation

• 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 (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, revocation

Progress log

• 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

(loop fills this in)