fed-sx-types Phase 2: peer_types.erl receiver-side cache

next/kernel/peer_types.erl — a mirror of peer_actors keyed by type CID
(plans/fed-sx-host-types.md step 2). State [{TypeCidBytes, TypeRecord}],
where TypeRecord is the parsed DefineType :object payload. Refinement
schemas are immutable per CID, so cache entries never go stale.

Pure API: new/0, lookup/2, store/3, evict/2, types/1, lookup_or_fetch/3.
gen_server API (registered `peer_types`): put/2, lookup/1, state_for/1,
known_types/0, lookup_or_fetch/2, start_link/0,1.

lookup_or_fetch pulls a Cfg-supplied
  type_fetch_fn :: fun ((TypeCid, Cfg) -> {ok, Bytes} | {error, _})
on a miss, decodes the wire bytes via term_codec into the TypeRecord,
and caches it. No fn -> {error, no_fetch_fn}; fetch error / bad bytes
don't poison the cache (caller can retry). Keeping transport in the
closure (Phase 3 discovery_type_fetch) keeps the cache testable.

Test: next/tests/peer_types.sh (18) — pure + gen_server surface, fetch
miss/hit, no-fn, error-no-poison, undecodable-bytes, prepopulate.

Conformance 771/771.

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

next/kernel/peer_types.erl

@@ -0,0 +1,180 @@
+-module(peer_types).
+-export([new/0, lookup/2, store/3, evict/2, types/1,
+         lookup_or_fetch/3, decode_type_doc/1,
+         start_link/0, start_link/1, stop/0,
+         put/2, lookup/1, state_for/1, known_types/0,
+         lookup_or_fetch/2, evict/1]).
+-export([init/1, handle_call/3, handle_cast/2, handle_info/2]).
+-behaviour(gen_server).
+
+%% Peer-types cache — receiver-side mirror of peer_actors.erl, for
+%% host-type federation (plans/fed-sx-host-types.md, Phase 2). When an
+%% inbound activity references a refinement type the local node hasn't
+%% seen, the object-schema validation stage (Phase 4) needs that
+%% type's record — its :refinement-schema and field shape — to vet the
+%% inner object. Re-fetching the type doc on every inbound would be
+%% wasteful, so we cache the TypeRecord keyed by its content-address.
+%%
+%% State shape (pure-functional):
+%%   [{TypeCidBytes, TypeRecord}, ...]
+%%
+%% TypeCidBytes is the type's CID (a binary). TypeRecord is the parsed
+%% DefineType envelope's :object payload — a proplist carrying :name,
+%% :fields, :refinement-schema, :instance-type. Refinement schemas are
+%% immutable per CID (an updated type is a new CID), so cache entries
+%% never go stale — TTL-free, like peer_actors' v2 entries.
+%%
+%% lookup_or_fetch is the load-bearing entry point: a miss invokes a
+%% Cfg-supplied closure to fetch the type doc over the wire. Per the
+%% design the closure has shape
+%%   type_fetch_fn :: fun ((TypeCid, Cfg) -> {ok, Bytes} | {error, _})
+%% returning the term_codec-encoded type-doc bytes; lookup_or_fetch
+%% decodes them into the TypeRecord and caches it. Keeping the
+%% transport in the closure (Phase 3's discovery_type_fetch) keeps
+%% peer_types testable with a mocked fetch — same split as
+%% peer_actors / discovery_fetch.
+%%
+%% gen_server wrapper registers under the atom `peer_types` so the
+%% pipeline + http_server handlers can reach it without threading a
+%% Pid through Cfg.
+
+%% ── Pure-functional API ─────────────────────────────────────────
+
+new() -> [].
+
+lookup(TypeCid, State) ->
+    case find_keyed(TypeCid, State) of
+        {ok, TR}   -> {ok, TR};
+        {error, _} -> not_found
+    end.
+
+store(TypeCid, TR, State) ->
+    set_keyed(TypeCid, TR, State).
+
+evict(TypeCid, State) ->
+    delete_keyed(TypeCid, State).
+
+types(State) -> [Cid || {Cid, _TR} <- State].
+
+%% lookup_or_fetch/3 — cache hit returns {ok, TR, State} unchanged.
+%% Cache miss pulls the type_fetch_fn out of Cfg and calls it with
+%% (TypeCid, Cfg); a {ok, Bytes} reply is decoded via term_codec into
+%% the TypeRecord, which is then stored. Failures (no fn, fetch error,
+%% bad bytes) do NOT poison the cache so the caller can retry.
+%%
+%%   no type_fetch_fn in Cfg       -> {error, no_fetch_fn, State}
+%%   fn -> {ok, Bytes}, decodable  -> {ok, TR, store(...)}
+%%   fn -> {ok, Bytes}, bad bytes  -> {error, bad_type_doc, State}
+%%   fn -> {error, Reason}         -> {error, Reason, State}
+%%   fn -> Other                   -> {error, {bad_fetch_return, Other}, State}
+
+lookup_or_fetch(TypeCid, Cfg, State) ->
+    case find_keyed(TypeCid, State) of
+        {ok, TR}   -> {ok, TR, State};
+        {error, _} -> fetch_and_store(TypeCid, Cfg, State)
+    end.
+
+fetch_and_store(TypeCid, Cfg, State) ->
+    case field(type_fetch_fn, Cfg) of
+        nil -> {error, no_fetch_fn, State};
+        Fn when is_function(Fn, 2) ->
+            case Fn(TypeCid, Cfg) of
+                {ok, Bytes} ->
+                    case decode_type_doc(Bytes) of
+                        {ok, TR}   -> {ok, TR, store(TypeCid, TR, State)};
+                        {error, R} -> {error, R, State}
+                    end;
+                {error, Reason} -> {error, Reason, State};
+                Other           -> {error, {bad_fetch_return, Other}, State}
+            end;
+        _ -> {error, bad_fetch_fn_cfg, State}
+    end.
+
+%% decode_type_doc/1 — round the wire body back through term_codec.
+%% The on-wire form is term_codec:encode(TypeRecord) (Phase 3's
+%% /types/<cid> route), so a clean decode yields the proplist TR.
+decode_type_doc(Bytes) ->
+    case term_codec:decode(Bytes) of
+        {ok, TR, _} when is_list(TR) -> {ok, TR};
+        _ -> {error, bad_type_doc}
+    end.
+
+%% ── gen_server wrapper ──────────────────────────────────────────
+
+start_link() ->
+    start_link([]).
+
+start_link(InitialState) ->
+    Pid = gen_server:start_link(peer_types, [InitialState]),
+    erlang:register(peer_types, Pid),
+    Pid.
+
+stop() ->
+    R = gen_server:call(peer_types, '$gen_stop'),
+    erlang:unregister(peer_types),
+    R.
+
+%% put/2 — store a TypeRecord under its CID. Mirrors store_srv.
+put(TypeCid, TR) ->
+    gen_server:call(peer_types, {put, TypeCid, TR}).
+
+%% lookup/1 — cache read. {ok, TR} | not_found.
+lookup(TypeCid) ->
+    gen_server:call(peer_types, {lookup, TypeCid}).
+
+%% state_for/1 — alias of lookup/1, named to match peer_actors'
+%% state_for accessor used by http_server's kernel bridge.
+state_for(TypeCid) ->
+    gen_server:call(peer_types, {lookup, TypeCid}).
+
+known_types() ->
+    gen_server:call(peer_types, get_types).
+
+evict(TypeCid) ->
+    gen_server:call(peer_types, {evict, TypeCid}).
+
+%% lookup_or_fetch/2 — gen_server form. Cfg carries the type_fetch_fn.
+%% Reply is {ok, TR} on hit-or-fetched, {error, Reason} otherwise.
+lookup_or_fetch(TypeCid, Cfg) ->
+    gen_server:call(peer_types, {lookup_or_fetch, TypeCid, Cfg}).
+
+%% gen_server callbacks
+
+init([InitialState]) ->
+    {ok, InitialState}.
+
+handle_call({put, TypeCid, TR}, _From, State) ->
+    {reply, ok, store(TypeCid, TR, State)};
+handle_call({lookup, TypeCid}, _From, State) ->
+    {reply, lookup(TypeCid, State), State};
+handle_call({lookup_or_fetch, TypeCid, Cfg}, _From, State) ->
+    case lookup_or_fetch(TypeCid, Cfg, State) of
+        {ok, TR, NewState}     -> {reply, {ok, TR}, NewState};
+        {error, Reason, Same}  -> {reply, {error, Reason}, Same}
+    end;
+handle_call(get_types, _From, State) ->
+    {reply, types(State), State};
+handle_call({evict, TypeCid}, _From, State) ->
+    {reply, ok, evict(TypeCid, State)}.
+
+handle_cast(_, S) -> {noreply, S}.
+
+handle_info(_, S) -> {noreply, S}.
+
+%% ── Internal helpers ────────────────────────────────────────────
+
+field(K, [{K, V} | _]) -> V;
+field(K, [_ | Rest]) -> field(K, Rest);
+field(_, []) -> nil.
+
+find_keyed(_, []) -> {error, not_found};
+find_keyed(K, [{K, V} | _]) -> {ok, V};
+find_keyed(K, [_ | Rest]) -> find_keyed(K, Rest).
+
+set_keyed(K, V, []) -> [{K, V}];
+set_keyed(K, V, [{K, _} | Rest]) -> [{K, V} | Rest];
+set_keyed(K, V, [P | Rest]) -> [P | set_keyed(K, V, Rest)].
+
+delete_keyed(_, []) -> [];
+delete_keyed(K, [{K, _} | Rest]) -> Rest;
+delete_keyed(K, [P | Rest]) -> [P | delete_keyed(K, Rest)].

next/tests/peer_types.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+# next/tests/peer_types.sh — host-type federation Phase 2 acceptance.
+#
+# Receiver-side peer-types cache (next/kernel/peer_types.erl), a mirror
+# of peer_actors keyed by type CID. Tracks {TypeCidBytes, TypeRecord}
+# pairs so the object-schema validation stage can vet inbound objects
+# against a fetched-once refinement type. lookup_or_fetch pulls a
+# Cfg-supplied type_fetch_fn on a miss, decodes the returned wire bytes
+# via term_codec, and caches the TypeRecord.
+
+set -uo pipefail
+cd "$(git rev-parse --show-toplevel)"
+
+SX_SERVER="${SX_SERVER:-hosts/ocaml/_build/default/bin/sx_server.exe}"
+if [ ! -x "$SX_SERVER" ]; then
+  SX_SERVER="/root/rose-ash/hosts/ocaml/_build/default/bin/sx_server.exe"
+fi
+if [ ! -x "$SX_SERVER" ]; then
+  echo "ERROR: sx_server.exe not found." >&2
+  exit 1
+fi
+
+VERBOSE="${1:-}"
+PASS=0; FAIL=0; ERRORS=""
+TMPFILE=$(mktemp); trap "rm -f $TMPFILE" EXIT
+
+# TR1/TR2 are TypeRecords (the DefineType :object payloads). Doc1 is
+# TR1's on-wire form (term_codec). FetchOk serves Doc1 for Cid1;
+# FetchBad returns undecodable bytes. CfgOk/CfgBad/CfgNone vary the
+# type_fetch_fn slot.
+SETUP='Cid1 = <<98,97,102,121,49>>, Cid2 = <<98,97,102,121,50>>, TR1 = [{name, <<80,111,115,116>>}, {instance_type, <<78,111,116,101>>}], TR2 = [{name, <<82,101,112,108,121>>}], Doc1 = term_codec:encode(TR1), FetchOk = fun(C, _) -> case C =:= Cid1 of true -> {ok, Doc1}; false -> {error, not_found} end end, FetchBad = fun(_, _) -> {ok, <<255>>} end, CfgOk = [{type_fetch_fn, FetchOk}], CfgBad = [{type_fetch_fn, FetchBad}], CfgNone = [],'
+
+cat > "$TMPFILE" <<EPOCHS
+(epoch 1)
+(load "lib/erlang/tokenizer.sx")
+(load "lib/erlang/parser.sx")
+(load "lib/erlang/parser-core.sx")
+(load "lib/erlang/parser-expr.sx")
+(load "lib/erlang/parser-module.sx")
+(load "lib/erlang/transpile.sx")
+(load "lib/erlang/runtime.sx")
+(load "lib/erlang/vm/dispatcher.sx")
+(epoch 2)
+(eval "(er-load-gen-server!)")
+(epoch 3)
+(eval "(get (erlang-load-module (file-read \"next/kernel/term_codec.erl\")) :name)")
+(epoch 4)
+(eval "(get (erlang-load-module (file-read \"next/kernel/peer_types.erl\")) :name)")
+
+;; ── pure API ───────────────────────────────────────────────
+;; new/0 -> []
+(epoch 10)
+(eval "(get (erlang-eval-ast \"peer_types:new() =:= []\") :name)")
+;; lookup miss -> not_found
+(epoch 11)
+(eval "(get (erlang-eval-ast \"peer_types:lookup(<<1>>, peer_types:new()) =:= not_found\") :name)")
+;; store + lookup round-trip
+(epoch 12)
+(eval "(get (erlang-eval-ast \"${SETUP} S = peer_types:store(Cid1, TR1, peer_types:new()), peer_types:lookup(Cid1, S) =:= {ok, TR1}\") :name)")
+;; types/1 lists CIDs in insertion order
+(epoch 13)
+(eval "(get (erlang-eval-ast \"${SETUP} S = peer_types:store(Cid2, TR2, peer_types:store(Cid1, TR1, peer_types:new())), peer_types:types(S) =:= [Cid1, Cid2]\") :name)")
+;; evict removes the entry
+(epoch 14)
+(eval "(get (erlang-eval-ast \"${SETUP} S = peer_types:evict(Cid1, peer_types:store(Cid1, TR1, peer_types:new())), peer_types:lookup(Cid1, S) =:= not_found\") :name)")
+
+;; ── lookup_or_fetch (pure) ─────────────────────────────────
+;; miss -> fetch via Cfg.fn, decode bytes, cache TR
+(epoch 20)
+(eval "(get (erlang-eval-ast \"${SETUP} case peer_types:lookup_or_fetch(Cid1, CfgOk, peer_types:new()) of {ok, TR1, [{Cid1, TR1}]} -> ok; _ -> bad end\") :name)")
+;; hit -> returns cached without calling fetch
+(epoch 21)
+(eval "(get (erlang-eval-ast \"${SETUP} S = peer_types:store(Cid1, TR1, peer_types:new()), case peer_types:lookup_or_fetch(Cid1, CfgBad, S) of {ok, TR1, S} -> ok; _ -> bad end\") :name)")
+;; no type_fetch_fn -> {error, no_fetch_fn}, cache untouched
+(epoch 22)
+(eval "(get (erlang-eval-ast \"${SETUP} case peer_types:lookup_or_fetch(Cid1, CfgNone, peer_types:new()) of {error, no_fetch_fn, []} -> ok; _ -> bad end\") :name)")
+;; fetch error does NOT poison the cache
+(epoch 23)
+(eval "(get (erlang-eval-ast \"${SETUP} BadCfg = [{type_fetch_fn, fun(_, _) -> {error, http_404} end}], case peer_types:lookup_or_fetch(Cid1, BadCfg, peer_types:new()) of {error, http_404, []} -> ok; _ -> bad end\") :name)")
+;; undecodable bytes -> {error, bad_type_doc}
+(epoch 24)
+(eval "(get (erlang-eval-ast \"${SETUP} case peer_types:lookup_or_fetch(Cid1, CfgBad, peer_types:new()) of {error, bad_type_doc, []} -> ok; _ -> bad end\") :name)")
+
+;; ── gen_server API ─────────────────────────────────────────
+;; start_link + put + lookup round-trip
+(epoch 30)
+(eval "(get (erlang-eval-ast \"${SETUP} peer_types:start_link(), peer_types:put(Cid1, TR1), peer_types:lookup(Cid1) =:= {ok, TR1}\") :name)")
+;; lookup miss -> not_found
+(epoch 31)
+(eval "(get (erlang-eval-ast \"peer_types:start_link(), peer_types:lookup(<<9>>) =:= not_found\") :name)")
+;; state_for is an alias of lookup
+(epoch 32)
+(eval "(get (erlang-eval-ast \"${SETUP} peer_types:start_link(), peer_types:put(Cid1, TR1), peer_types:state_for(Cid1) =:= {ok, TR1}\") :name)")
+;; known_types lists stored CIDs
+(epoch 33)
+(eval "(get (erlang-eval-ast \"${SETUP} peer_types:start_link(), peer_types:put(Cid1, TR1), peer_types:put(Cid2, TR2), peer_types:known_types() =:= [Cid1, Cid2]\") :name)")
+;; lookup_or_fetch miss fetches + caches
+(epoch 34)
+(eval "(get (erlang-eval-ast \"${SETUP} peer_types:start_link(), R = peer_types:lookup_or_fetch(Cid1, CfgOk), R =:= {ok, TR1} andalso peer_types:known_types() =:= [Cid1]\") :name)")
+;; lookup_or_fetch with no fn -> {error, no_fetch_fn}, pristine
+(epoch 35)
+(eval "(get (erlang-eval-ast \"${SETUP} peer_types:start_link(), R = peer_types:lookup_or_fetch(Cid1, CfgNone), R =:= {error, no_fetch_fn} andalso peer_types:known_types() =:= []\") :name)")
+;; start_link/1 pre-populates the cache
+(epoch 36)
+(eval "(get (erlang-eval-ast \"${SETUP} peer_types:start_link([{Cid1, TR1}]), peer_types:lookup(Cid1) =:= {ok, TR1}\") :name)")
+EPOCHS
+
+OUTPUT=$(timeout 300 "$SX_SERVER" < "$TMPFILE" 2>/dev/null)
+
+check() {
+  local epoch="$1" desc="$2" expected="$3"
+  local actual
+  actual=$(echo "$OUTPUT" | awk -v e="$epoch" '
+    $0 ~ "^\\(ok-len " e " " { getline; print; exit }
+    $0 ~ "^\\(ok " e " "     { print; exit }
+    $0 ~ "^\\(error " e " "  { print; exit }
+  ')
+  [ -z "$actual" ] && actual="<no output for epoch $epoch>"
+  if echo "$actual" | grep -qF -- "$expected"; then
+    PASS=$((PASS+1))
+    [ "$VERBOSE" = "-v" ] && echo "  ok $desc"
+  else
+    FAIL=$((FAIL+1))
+    ERRORS+="  FAIL [$desc] (epoch $epoch) expected: $expected | actual: $actual
+"
+  fi
+}
+
+check  4  "peer_types module loaded"          "peer_types"
+check 10  "new/0 -> []"                       "true"
+check 11  "lookup miss -> not_found"          "true"
+check 12  "store + lookup round-trip"         "true"
+check 13  "types/1 lists in insertion order"  "true"
+check 14  "evict removes entry"               "true"
+check 20  "lookup_or_fetch miss fetches"      "ok"
+check 21  "lookup_or_fetch hit skips fetch"   "ok"
+check 22  "no fetch_fn -> no_fetch_fn"        "ok"
+check 23  "fetch error doesn't poison"        "ok"
+check 24  "undecodable bytes -> bad_type_doc" "ok"
+check 30  "gen_server put + lookup"           "true"
+check 31  "gen_server lookup miss"            "true"
+check 32  "gen_server state_for alias"        "true"
+check 33  "gen_server known_types lists"      "true"
+check 34  "gen_server fetch + cache"          "true"
+check 35  "gen_server no fn -> pristine"      "true"
+check 36  "start_link/1 pre-populates"        "true"
+
+TOTAL=$((PASS+FAIL))
+if [ $FAIL -eq 0 ]; then
+  echo "ok $PASS/$TOTAL next/tests/peer_types.sh passed"
+else
+  echo "FAIL $PASS/$TOTAL passed, $FAIL failed:"
+  echo "$ERRORS"
+fi
+[ $FAIL -eq 0 ]