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

- [x] `lib/relations/schema.sx` — `rel(Src, Dst, Kind)` fact projection; a small
  kind vocabulary (`parent`, `member`, `reply`, `variant`, `origin`, …) kept open
- [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)`
- [x] `lib/relations/tests/direct.sx` — assert/retract, direct children/parents,
  kind filtering, unknown node → empty
- [x] `lib/relations/conformance.sh` + scoreboard

## Phase 2 — Reachability + cycles

- [x] recursive reachability rules: `ancestors`, `descendants`, `reachable?(A,B)`
  (transitive closure over a kind, the acl inheritance shape)
- [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

- [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
- [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

- [x] cross-instance relationships — a peer asserts `rel(local, remote, kind)`;
  replicate rel facts via fed-sx (mock the transport in tests)
- [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)
- [x] revocation — retract a replicated link; reachability re-saturates
- [x] `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)