rose-ash/plans/agent-briefings/host-fed-sx-adapter-loop.md

; -*- mode: markdown -*-
# loops/host — fed-sx adapter slice (host side of host-type federation)

Scoped briefing for the follow-up that wires `loops/host`'s SX/dream
front door to the fed-sx kernel substrate landed by
`loops/fed-sx-types`. Companion to `plans/fed-sx-host-types.md` (the
substrate design + public surface). This is the build sheet for the
host-side adapters the substrate loop deliberately deferred.

```
description: loops/host — fed-sx adapter (publish/serve/ingest typed posts)
subagent_type: general-purpose
run_in_background: true
isolation: worktree     # worktree at /root/rose-ash-loops/host
```

## Why this is small now

The substrate is done and tested (`origin/loops/fed-sx-types`, 4
phases). And the host already has *most of a type system*:
`lib/host/blog.sx` models a **type as a post** with a content-address
`:cid`, a `:schema` (`{:required [...]}`), `:fields`, `:template`, and a
**`subtype-of` graph over lib/relations**. So this loop is not building
a type model — it is **projecting the host's existing one onto fed-sx**
and ingesting peers' types back. The pieces line up almost 1:1:

| host (lib/host/blog.sx)                    | fed-sx (next/kernel)                     |
|--------------------------------------------|------------------------------------------|
| a type-post + `:schema {:required [...]}`  | `DefineType` activity + refinement `{required, [...]}` |
| `subtype-of` edge (lib/relations)          | `SubtypeOf` activity                     |
| `host/blog-by-cid` / `host/blog-type-defs` | `peer_types` cache + `GET /types/<cid>`  |
| `host/blog-type-issues` (local validate)   | `pipeline:apply_object_schema/2` (inbound) |

The host's `{:required [...]}` schema maps **directly** onto the
term_codec-safe `{required, [Field,...]}` refinement form the substrate
already validates — so schema translation is nearly trivial. Derive
both validators from the *same* schema data to avoid drift.

## Scope

**In scope** — `lib/host/**` only (the mirror of fed-sx-types'
`next/**` only). New: `lib/host/fed_sx_outbox.sx`,
`lib/host/fed_sx_inbox.sx` (and a small shared `lib/host/fed_sx.sx`
bridge + a `host/types-routes`), plus `serve.sh` bring-up wiring and
`lib/host/tests/`.

**Out of scope** — `next/**`. The substrate is frozen public surface;
do **not** edit `next/kernel/**` or the genesis verbs from here. If a
gap is found, file it against fed-sx-types, don't patch across the
boundary. **Hard line: do not edit `next/`.**

## Branch base

Start from `loops/host`, then bring in the substrate (clean, additive —
disjoint paths, no conflicts):

```bash
cd /root/rose-ash-loops/host
git fetch origin
git merge origin/loops/fed-sx-types     # adds next/kernel + genesis + plan doc
```

After the merge the worktree has both `lib/host/**` (host) and
`next/kernel/**` (fed-sx substrate) on one branch.

## Phase 0 — settle the runtime boundary (DECIDE FIRST, blocks all else)

`lib/host` is **pure same-runtime SX** (one `sx_server.exe`: stdlib →
R7RS → APL → Datalog → ACL → Relations → Feed → Persist → Dream →
Host, per `serve.sh`). The fed-sx kernel is **Erlang-on-SX** on the
er-scheduler (`erlang-load-module` + gen_servers: `peer_types`,
`nx_kernel`). The host's dream handlers run on the native `http-listen`
accept loop — **outside** the er-scheduler. Calling a kernel
`gen_server:call` synchronously from a native-thread handler hits the
known scheduler-context deadlock (see
`plans/fed-sx-design.md` §, and the fed-prims http-listen note: a
handler on `Thread.create` outside er-sched can't complete a
`gen_server:call → receive`).

Two architectures; **the loop's first deliverable is choosing one with
a tiny spike**:

- **Option A — in-process Erlang bridge.** Host's sx_server also
  `erlang-load-module`s the kernel and calls it directly. Pro: one
  process, no serialization. Con: the deadlock above — kernel calls
  must be marshalled onto the er-scheduler or restricted to pure
  (non-gen_server) functions. Fragile; not recommended.

- **Option B — HTTP boundary (RECOMMENDED).** Run the fed-sx kernel
  with its own `http_server`/`http-listen` loop (it already has the
  whole route surface, and the m2 two-instance smoke test proves
  HTTP federation between fed-sx nodes). The host talks to its local
  fed-sx node **over localhost HTTP using the wire it already speaks**
  (term_codec / activity+json / type-doc). This is literally what
  federation is — the host is just another peer to its own node. An
  `httpc`/localhost call from a native-thread host handler does **not**
  touch the er-scheduler, so the deadlock never arises; the kernel's
  own listen handler runs the gen_server calls within er-sched context.
  Works whether the kernel is a sidecar process or spawned on an
  er-scheduler process inside the host's sx_server (two ports, one
  process). Pro: clean, reuses the fully-tested surface, no deadlock.
  Con: serialization + lifecycle coordination.

**Recommendation: Option B.** Spike: host handler → `httpc` POST to the
local kernel's `/activity` → 200/cid back, with no hang. Lock the
decision before Phase 1.

## Phase 1 — outbox: project host types → DefineType / SubtypeOf

`lib/host/fed_sx_outbox.sx`. When a host type-post is created/updated
(`host/blog-put!` path), project it and publish to the local fed-sx
node:

- type-post → `DefineType` activity: `:object` = `{name: slug,
  fields: (host/blog-fields-of slug), refinement-schema:
  (host/blog-schema-of slug), instance-type: <base>}`. The host
  `{:required [...]}` becomes the substrate `{required, [...]}` form
  verbatim.
- each `subtype-of` edge (`relations/parents` over `"subtype-of"`) →
  a `SubtypeOf` activity `{child-type-cid, parent-type-cid}`.
- publish via Phase 0's transport (POST `/activity` to the local node,
  authed with the node's publish token).

**Key open decision — the type CID.** The host computes `:cid` via
`host/blog--cid-of` (double-hash over the canonical record); fed-sx
keys `peer_types` by a `TypeCid`. Either:
  (a) **adopt the host `:cid` as the fed-sx TypeCid** — one identity,
      no reconciliation, but peers can't content-verify it from the
      wire bytes; or
  (b) **let the kernel content-address the TypeRecord** — verifiable,
      but the host must keep a `slug → fed-sx-cid` map (and
      `SubtypeOf` edges must reference fed-sx CIDs, not host CIDs).
Pick one and document it in `plans/fed-sx-host-types.md`. (a) is
simpler and probably right for v1; revisit when cross-node verification
matters.

## Phase 2 — inbox: ingest peers' types + validate typed objects

`lib/host/fed_sx_inbox.sx`. Inbound from the local node's inbox:

- inbound `DefineType` → `peer_types:put` (cache it). Decide whether to
  also **materialize** it as a host post (`host/blog-put!` +
  `host/blog--set-schema!`) or keep federation-only types out of the
  local blog (recommended for v1: cache-only, materialize on demand).
- inbound `SubtypeOf` → record the edge (peer_types hierarchy and/or
  `host/blog-relate! child parent "subtype-of"` if materialized).
- inbound typed `Create` (a post that `is-a` some refinement type) →
  the kernel inbound pipeline runs `pipeline:apply_object_schema/2`
  (configured with a `type_index` + `{peer_types, peer_types}` +
  `type_fetch_fn`), so a typed object is validated against its declared
  type **before** the host sees it. Choose `strict_object_schema`
  per-node (default false = open-world).

**Avoid double-validation drift:** the host already has
`host/blog-type-issues`. Let the **kernel validate federation inbound**
and the **host validate local writes**, both deriving from the same
`{:required [...]}` schema data — don't fork the rules.

## Phase 3 — serve + bring-up wiring

- **Serve `GET /types/<cid>`** on the host front door. Either proxy to
  the kernel's `/types/<cid>` (Option B keeps one source of truth), or
  serve directly from `host/blog-by-cid` + the projected TypeRecord.
  Hook as `(dream-get "/types/:cid" host/types-by-cid)` and add
  `host/types-routes` to the `host/serve` list (per `router.sx` /
  `serve.sh` pattern).
- **Bring-up** in `serve.sh`: start the fed-sx node (Phase 0 transport),
  start `peer_types`, configure `type_fetch_fn =
  discovery_type_fetch:make_fetch_fn()` + a `type_url` resolver, and on
  startup project existing host types (Phase 1) so the node is
  type-aware from boot. Gate writes behind the existing
  `host/require-auth` / `host/require-permission` middleware, same as
  the relations write routes.

## Phase 4 — end-to-end round-trip test

Two nodes (host A + host B, or host + a sidecar fed-sx node): A defines
a refinement type → B fetches the type-doc via `GET /types/<cid>` → B
ingests an inbound typed object and `apply_object_schema` accepts the
valid one / rejects a refinement-failing one. Mirror the m2
two-instance smoke test style. Plus per-phase suites in
`lib/host/tests/` (the host runs its own `conformance.sh`).

## Tests discipline

- The host's `lib/host/conformance.sh` green before AND after every
  commit. `lib/host` is **LIVE at blog.rose-ash.com** — pushing
  `loops/host` reloads dev, so treat pushes as deliberate.
- Commits scoped to `lib/host/**` (+ `plans/fed-sx-host-types.md` as
  decisions ratify). Do **not** edit `next/**`.
- One commit per phase; smaller intermediate commits fine if each
  leaves the gate green. The Phase-0 spike can be its own commit.

## Done when

- A host type round-trips: defined locally → published as
  `DefineType`/`SubtypeOf` → fetchable at `GET /types/<cid>` → a peer
  validates an inbound typed object against it.
- `peer_types` is populated from inbound `DefineType`, and the inbound
  pipeline rejects refinement-failing typed objects (strict node).
- The runtime-boundary decision and the type-CID decision are recorded
  in `plans/fed-sx-host-types.md`.
- Host `conformance.sh` + the new fed-sx adapter suites green.

## Parallel-safety with loops/fed-sx-types

That loop owns `next/**` and is feature-complete; this loop owns
`lib/host/**`. Disjoint surfaces — they meet only at the merge that
brings the substrate in (Branch base, above). If this loop needs a
substrate change, file it against fed-sx-types rather than editing
`next/` here.