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)].