fed-sx-types Phase 8: blog-publish-digest e2e + flow:wait

The motivating end-to-end demonstration (fed-sx-triggers-loop.md Phase
4): one trigger arriving in the pipeline drives a multi-step business
flow with a branch, a timer suspension, an injected effect, and a
follow-up activity emit — all in the kernel's own runtime.

- flow.erl: flow:wait/1 — a timer-style suspend that PRESERVES the value
  on resume (vs flow:suspend/1, which returns the logged result), so a
  "wait until morning" step lets the env flow through to later steps.
- next/flow/flows/blog_publish_digest.erl: the flow. Branches on the
  article :category (newsletter -> wait-until-morning -> send + emit;
  urgent -> send + emit now; else -> skip), fetches followers (injected),
  builds a digest email per follower, and emits a DigestSent activity
  OBJECT. Effect-as-data: a flow can't call kernel gen_servers from
  inside the drive (a blocking call there deadlocks the scheduler), so
  it returns the emails + DigestSent object for a driver to dispatch and
  append — which can then trigger downstream flows, closing the loop.

Test: triggers_e2e.sh (10) — urgent completes in one cycle with 3 emails
+ a DigestSent object; newsletter suspends on the morning timer, then
resumes to the same on "advancing the clock"; draft takes the else
branch (no emails); a non-Article note is rejected by the guard; a
duplicate activity fires once. flow:wait covered in next/flow (36/36).

plans/fed-sx-design.md §13.10 documents the trigger fan-out as a
kernel convention. lib/erlang 771/771.

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

next/flow/conformance.sh

@@ -103,6 +103,11 @@ cat > "$TMPFILE" <<EPOCHS
 (eval "(get (erlang-eval-ast \"flow:drive(${SUSP_FLOW}, 0, [{wait1, 99}]) =:= {flow_done, {resumed, 99}}\") :name)")
 (epoch 62)
 (eval "(get (erlang-eval-ast \"flow:run(flow_spec:sequence([flow:suspend(a), flow:suspend(b)]), 0) =:= {flow_suspended, a}\") :name)")
+;; wait/1 — timer-style suspend that PRESERVES the value on resume
+(epoch 63)
+(eval "(get (erlang-eval-ast \"flow:run(flow_spec:sequence([flow:wait(t), flow_spec:flow_node(fun(X) -> X + 1 end)]), 5) =:= {flow_suspended, t}\") :name)")
+(epoch 64)
+(eval "(get (erlang-eval-ast \"flow:drive(flow_spec:sequence([flow:wait(t), flow_spec:flow_node(fun(X) -> X + 1 end)]), 5, [{t, ignored}]) =:= {flow_done, 6}\") :name)")
 
 ;; ── durable store: registry ────────────────────────────────
 (epoch 70)
@@ -178,6 +183,8 @@ check 52 "retry runs node"               "true"
 check 60 "suspend miss short-circuits"   "true"
 check 61 "suspend replay completes"      "true"
 check 62 "first of two suspends wins"    "true"
+check 63 "wait short-circuits on miss"   "true"
+check 64 "wait preserves value on resume" "true"
 check 70 "register + resolve + list"     "true"
 check 71 "resolve unknown -> not_found"  "true"
 check 80 "start one-shot -> done"        "true"

next/flow/flow.erl

@@ -1,7 +1,7 @@
 -module(flow).
 -export([drive/3, run/2,
          cont/2, susp/2, is_susp/1, ctx_value/1, ctx_log/1,
-         suspend/1, log_lookup/2]).
+         suspend/1, wait/1, log_lookup/2]).
 
 %% flow-on-erlang — the deterministic-replay core. A native Erlang port
 %% of the Scheme flow engine (lib/flow), so the fed-sx kernel can fan
@@ -62,6 +62,24 @@ suspend(Tag) ->
         end
     end.
 
+%% wait(Tag) — a timer-style suspend that PRESERVES the current value
+%% instead of replacing it with the resolved one. Use it for pure
+%% waits ("resume in the morning") where the resume is just a signal,
+%% not a result: on the first pass it short-circuits like suspend; once
+%% Tag is in the log the value flows through unchanged, so downstream
+%% steps still see the value (e.g. the env) they had before the wait.
+wait(Tag) ->
+    fun (Ctx) ->
+        case Ctx of
+            {flow_susp, _, _} -> Ctx;
+            {flow_cont, Value, Log} ->
+                case log_lookup(Tag, Log) of
+                    {ok, _} -> {flow_cont, Value, Log};
+                    miss    -> {flow_susp, Tag, Log}
+                end
+        end
+    end.
+
 log_lookup(_, []) -> miss;
 log_lookup(Tag, [{Tag, Value} | _]) -> {ok, Value};
 log_lookup(Tag, [_ | Rest]) -> log_lookup(Tag, Rest).

next/flow/flows/blog_publish_digest.erl

@@ -0,0 +1,81 @@
+-module(blog_publish_digest).
+-export([build/1]).
+
+%% A motivating multi-step business flow for the fed-sx-triggers e2e:
+%% when an Article is published, decide a batch policy by category,
+%% (for newsletters) wait until morning, fetch the author's followers,
+%% build a digest email for each, and emit a DigestSent activity — the
+%% flow's own output, which a driver appends, closing the loop so it can
+%% trigger downstream flows.
+%%
+%% Demonstrates: a branch on an activity field (:category), a timer
+%% suspension (flow:wait/1, resumed by advancing the clock), an injected
+%% effect (fetch_followers), and a follow-up activity emit.
+%%
+%% Effect-as-data: a flow runs inside flow_store's drive, where a
+%% blocking call (e.g. into nx_kernel) would deadlock this scheduler, so
+%% the flow does NOT perform IO itself. It DESCRIBES the effects in its
+%% result — {digest_sent, Emails, DigestActivityObject} — and the driver
+%% (the fan-out caller) dispatches the emails and appends the DigestSent
+%% activity. fetch_followers is injected (the one external read) as a
+%% pure function so the e2e can supply a deterministic list.
+%%
+%% Input env (from flow_dispatch): [{activity, A}, {actor, Actor}, ...].
+%% Result: {digest_sent, [Email], DigestObject} | skipped.
+
+build(Effects) ->
+    FetchFollowers = field(fetch_followers, Effects),
+    flow_spec:branch(
+      fun (Env) -> is_article(Env) end,
+      flow_spec:branch(
+        fun (Env) -> category_is(Env, newsletter) end,
+        %% newsletter: hold until morning, then send + emit
+        flow_spec:sequence([flow:wait(morning), send_emit(FetchFollowers)]),
+        flow_spec:branch(
+          fun (Env) -> category_is(Env, urgent) end,
+          %% urgent: send + emit now (no wait)
+          send_emit(FetchFollowers),
+          %% any other category: skip
+          flow_spec:flow_const(skipped))),
+      %% not an Article: skip
+      flow_spec:flow_const(skipped)).
+
+%% send_emit(FetchFollowers) — the terminal step: build one digest email
+%% per follower and the DigestSent emit object. Pure given the injected
+%% follower list, so it is replay-safe (and it sits after the only
+%% suspend point, so it runs exactly once).
+send_emit(FetchFollowers) ->
+    flow_spec:flow_node(
+      fun (Env) ->
+          Activity  = env_activity(Env),
+          Actor     = env_actor(Env),
+          ArtId     = activity_id(Activity),
+          Followers = FetchFollowers(Actor),
+          Emails    = [ [{to, F}, {article, ArtId}] || F <- Followers ],
+          Digest    = [{type, digest_sent},
+                       {for, ArtId},
+                       {follower_count, length(Followers)}],
+          {digest_sent, Emails, Digest}
+      end).
+
+%% ── predicates / accessors ──────────────────────────────────────
+
+is_article(Env) ->
+    object_type(object_of(env_activity(Env))) =:= article.
+
+category_is(Env, Cat) ->
+    object_category(object_of(env_activity(Env))) =:= Cat.
+
+env_activity(Env) -> field(activity, Env).
+env_actor(Env)    -> field(actor, Env).
+
+object_of(Activity)     -> field(object, Activity).
+object_type(Obj)        -> field(type, Obj).
+object_category(Obj)    -> field(category, Obj).
+activity_id(Activity)   -> field(id, Activity).
+
+field(Key, Proplist) ->
+    case envelope:get_field(Key, Proplist) of
+        {ok, V} -> V;
+        _       -> undefined
+    end.