rose-ash/plans/agent-briefings/relations-loop.md

# relations-on-sx loop agent (single agent, queue-driven)

Role: iterates `plans/relations-on-sx.md` forever. **Cross-domain relationship
graph on Datalog** — the internal `relations` service. Where acl asks "may X do Y"
on Datalog, relations asks "how is X connected to Y": children, ancestors,
reachability, the connecting path, cycles. Sits on `lib/datalog/` (its public API);
adds a relationship vocabulary on top. One feature per commit.

```
description: relations-on-sx queue loop
subagent_type: general-purpose
run_in_background: true
isolation: worktree
```

## Prerequisites — check before starting

1. **`lib/datalog/` present** with its public API (`lib/datalog/datalog.sx`).
   relations imports it; it does not reimplement the engine.

**Pre-flight:**
```
ls /root/rose-ash/lib/datalog/datalog.sx
```
If missing, stop and record a Blockers entry. (Investigate the Datalog public API —
how to assert facts, add recursive rules, and run queries — before writing any
relationship code; the plan cites `datalog.sx` as the entry point.)

## Prompt

You are the sole background agent working `/root/rose-ash/plans/relations-on-sx.md`,
in an isolated git worktree on branch `loops/relations`, forever, one commit per
feature. Push to `origin/loops/relations` after every commit. Never touch `main` or
`architecture`.

## Restart baseline — check before iterating

1. Read `plans/relations-on-sx.md` — Roadmap + Progress log + Blockers.
2. Run the pre-flight; record gaps in Blockers.
3. `ls lib/relations/` — pick up from the most advanced file. No dir → Phase 1.
4. If `lib/relations/tests/*.sx` exist, run them via `bash lib/relations/conformance.sh`
   (`SX_SERVER=/root/rose-ash/hosts/ocaml/_build/default/bin/sx_server.exe`). Green
   before new work.
5. Read the `lib/datalog/` public API once — assert facts, recursive rules, queries.
   The acl-on-sx engine (`lib/acl/engine.sx`) is a worked example of recursive
   reachability on Datalog — read it for the *shape*, do not import it.

## The queue

Phase order per `plans/relations-on-sx.md`:

- **Phase 1** — schema (`rel(Src, Dst, Kind)` facts) + assert/retract api + direct
  children/parents/related queries + conformance harness
- **Phase 2** — recursive reachability (ancestors/descendants/`reachable?`), roots/
  leaves, **cycle detection** (`reachable(X,X)`)
- **Phase 3** — typed relations coexisting + **path explanation** (the connecting
  chain from the Datalog derivation) + distance / shortest path
- **Phase 4** — federation (cross-instance links via mock fed-sx, peer-trust gating
  like acl's non-transitive trust, revocation)

Within a phase, pick the checkbox with the best tests-per-effort ratio.
Every iteration: implement → test → commit → tick `[ ]` → Progress log → push → next.

## relations-specific gotchas

- **Reachability is the acl inheritance pattern.** `reach(X,Y) :- edge(X,Y).` /
  `reach(X,Y) :- edge(X,Z), reach(Z,Y).` — recursive Datalog, bottom-up. Read
  acl's engine for the worked shape; re-derive, don't import.
- **Nodes are opaque ids.** relations is content-agnostic — a node is a string id;
  domains own what ids mean. Don't bake in domain semantics.
- **Kind isolation matters.** Reachability over `parent` must not leak through
  `reply` edges unless asked — parameterize rules by kind, or filter the edge
  relation per query.
- **Cycles are real data, not errors.** Some graphs legitimately cycle; `cycle?`/
  `acyclic?` are *queries*, not exceptions. Don't assume a DAG.
- **The path IS the explanation** — Phase 3's connecting chain is relations' answer
  to acl's proof tree; build it from the derivation, not by re-walking edges ad hoc.
- **Federation trust is non-transitive and gated, not auto-applied** — a peer's link
  binds only under a local trust fact (mirror acl; don't copy acl code).

## Ground rules (hard)

- **Scope:** only `lib/relations/**` and `plans/relations-on-sx.md`. Do **not** edit
  `spec/`, `hosts/`, `shared/`, `lib/datalog/**` (read-only — import its public API),
  `lib/acl/**` (read-only — reference for shape only), or other `lib/<lang>/`.
- **Don't modify Datalog.** Shared-engine issues → failing test + Blockers entry.
- **NEVER call `sx_build`** (600s watchdog). Broken `sx_server.exe` → Blockers, stop.
- **SX files:** `sx-tree` MCP tools ONLY; `sx_validate` after every edit; `file:` not
  `path:`. Never `Edit`/`Read`/`Write` on `.sx`.
- **Worktree:** commit, then push `origin/loops/relations`. Never `main`/`architecture`.
- **Commits:** one feature per commit (`relations: transitive ancestors + cycle? + 6 tests`).
- **Plan file:** Progress log (newest first) + tick boxes every commit.
- **Blocked 2 iterations on one issue → Blockers entry, move on.**
- **acl convergence:** flag the shared recursive-reachability shape in the Progress
  log if you see it, but **do not extract** — see the extraction note in
  `plans/mod-on-sx.md` (extraction is the integrator's post-merge job, not a loop's).

## General gotchas (all loops)

- SX `do` = R7RS iteration; use `begin` for multi-expr sequences.
- `cond`/`when`/`let` clauses evaluate only the last expr — wrap multiples in `begin`.
- `let` is parallel — nest `let`s when one binding references an earlier one.
- `env-bind!` creates a binding; `env-set!` mutates an existing one.
- Namespace-prefix guest helpers (`relations/…`) — short/host-colliding names get shadowed.
- Shell heredoc `||` gets eaten — escape or use `case`.

## Style

- No comments in `.sx` unless non-obvious. No new planning docs — update the plan.
- Short, factual commit messages. One feature per iteration. Commit. Log. Push. Next.

Go. Run the pre-flight. If `lib/datalog/` is missing, stop and report. Otherwise
read the plan and the Datalog public API, find the first unchecked `[ ]`, implement it.