1.AF P3 + P4/D13 — media egress, failover re-materialization, SSRF mechanism + byte-delivery gate

CLAUDE.md

@@ -38,7 +38,7 @@ A run executes in one of **three execution modes** behind the one `LLMProvider`
 engine is identical across all three. See [ADR-0012](docs/decisions/0012-managed-inference-dual-mode.md) to [ADR-0015](docs/decisions/0015-managed-mode-data-handling-and-compliance.md)
 and [docs/architecture/managed-inference.md](docs/architecture/managed-inference.md).
 
-**Status:** Phase 1 in progress — milestone M1 (LLM seam proven) reached (PR #9, 2026-06-07); the `FallbackChain` runner (1.K) landed, completing 1.m2 with the cost tracker (PR #13, 2026-06-11); the run loop (1.N — `WorkflowEngine` + `RunEventBus`) landed (PR #17, 2026-06-13) **completing 1.m3** (parse → DAG → run loop emits the canonical event stream), with the built-in `ToolRegistry` (1.T, a 1.m4 component) landing alongside it as the other `AgentRunner` (1.O) join prerequisite; the **`AgentRunner` (1.O) — per-node LLM execution behind the seam — landed (PR #18, 2026-06-14)**; and the **node-type handlers (1.P) — the six non-agent `NodeExecutor` arms (condition / transform / fan_out / fan_in / input / output) behind a dispatching executor — landed (PR #20, 2026-06-14)**; and **checkpoint/resume (1.R) + the human gate (1.Q) landed (PR #22, 2026-06-15)** — the derived `Checkpointer` + cross-process `resumeFromCheckpoint`, and the `human_in_the_loop` gate with the one-shot timeout port; and **node retry (1.S) — the above-chain whole-node retry budget ([ADR-0040](docs/decisions/0040-node-retry-budget-above-the-chain.md), amending ADR-0038) — landed (PR #24, 2026-06-15)**, re-dispatching a whole node on a retryable failure up to `retry.max` attempts (with `node:retrying`, abort-aware backoff, and `retry_on` filtering), with retry-from-node (ADR-0040 Part B) deferred to Phase-2; and the **pre-egress budget governor (1.AC, [ADR-0028](docs/decisions/0028-workflow-resource-governance.md)) + the `AgentSession` agent-first entry point (1.V, [ADR-0024](docs/decisions/0024-agent-first-entry-point-agentsession.md)) landed together (PR #26, 2026-06-16)** — 1.AC was the last 1.m4 component, so **1.m4 is complete** (the full engine stack: node handlers, gate, checkpoint/resume, retry, tools, sandbox, budget governor), and 1.V opens the Lane-C agent-first sub-spine (1.m5); then the **end-to-end Node harness (1.U) landed (PR #27, 2026-06-16), reaching 🎯 M2** — the engine runs end-to-end (live streaming + per-node-boundary checkpointing + cross-process resume + node retry + provider failover, gap-free), **completing the Phase-1 engine critical path**. The remaining Phase-1 work is additive and off the critical path (Lane C: the **`session:*` namespace (1.W) landed (PR #28, 2026-06-17)** — the `SessionEventSink`→`RunEventBus` adapter + per-session `sequenceNumber`, the `SessionHandle`, and the combined `RunOrSessionEventSchema` gate — and **session persistence (1.X) landed (PR #29, 2026-06-17)** — the `agent_sessions`/`session_messages` tables + migration, `SessionMessageSchema`/`AgentSessionSchema`, and the `SessionStore` + domain↔row mappers (data-layer only); then **session checkpoint/resume (1.Y) + export-to-workflow (1.Z) landed (PR #30, 2026-06-17)** — `reconstructSessionState`/`AgentSession.resume` (reload-not-replay; preload the text-only transcript, re-seed turnCount/cost, no `session:started` re-emit) + the `serializeWorkflow`/`sessionToWorkflow` pair (one agent node per completed turn, transcript in `metadata`, secret/signature exclusion structural) — leaving only the **1.AA** chat-regression harness ‖ the 1.m6 multimodal sub-spine, whose first step — **media-input adapters + the shared SSRF policy primitive (1.AE) — landed (PR #32, 2026-06-18)** (base64 image/audio across the three adapters behind per-modality `assertMediaCapabilities`, and the one `@relavium/shared` SSRF policy primitive reused by the provider-`baseURL` + `http_request` callers; the SSRF *mechanism* half + per-modality FallbackChain gating moved into **1.AF**). **1.AF (engine media plumbing) is now in progress — PR #33** lands its P1+P2: the `MediaStore`/`deInlineMedia` choke point (the active I3 enforcement), per-modality capability gating (`mediaSupportReason`/`requestSupportReason` — replacing coarse vision), the `media_objects`/`media_references` tables, and ADR-0042/0043/0044; P3/P4 (egress + access/cost) follow. **Phase 2 (CLI, M3) is unblocked**.
+**Status:** Phase 1 in progress — milestone M1 (LLM seam proven) reached (PR #9, 2026-06-07); the `FallbackChain` runner (1.K) landed, completing 1.m2 with the cost tracker (PR #13, 2026-06-11); the run loop (1.N — `WorkflowEngine` + `RunEventBus`) landed (PR #17, 2026-06-13) **completing 1.m3** (parse → DAG → run loop emits the canonical event stream), with the built-in `ToolRegistry` (1.T, a 1.m4 component) landing alongside it as the other `AgentRunner` (1.O) join prerequisite; the **`AgentRunner` (1.O) — per-node LLM execution behind the seam — landed (PR #18, 2026-06-14)**; and the **node-type handlers (1.P) — the six non-agent `NodeExecutor` arms (condition / transform / fan_out / fan_in / input / output) behind a dispatching executor — landed (PR #20, 2026-06-14)**; and **checkpoint/resume (1.R) + the human gate (1.Q) landed (PR #22, 2026-06-15)** — the derived `Checkpointer` + cross-process `resumeFromCheckpoint`, and the `human_in_the_loop` gate with the one-shot timeout port; and **node retry (1.S) — the above-chain whole-node retry budget ([ADR-0040](docs/decisions/0040-node-retry-budget-above-the-chain.md), amending ADR-0038) — landed (PR #24, 2026-06-15)**, re-dispatching a whole node on a retryable failure up to `retry.max` attempts (with `node:retrying`, abort-aware backoff, and `retry_on` filtering), with retry-from-node (ADR-0040 Part B) deferred to Phase-2; and the **pre-egress budget governor (1.AC, [ADR-0028](docs/decisions/0028-workflow-resource-governance.md)) + the `AgentSession` agent-first entry point (1.V, [ADR-0024](docs/decisions/0024-agent-first-entry-point-agentsession.md)) landed together (PR #26, 2026-06-16)** — 1.AC was the last 1.m4 component, so **1.m4 is complete** (the full engine stack: node handlers, gate, checkpoint/resume, retry, tools, sandbox, budget governor), and 1.V opens the Lane-C agent-first sub-spine (1.m5); then the **end-to-end Node harness (1.U) landed (PR #27, 2026-06-16), reaching 🎯 M2** — the engine runs end-to-end (live streaming + per-node-boundary checkpointing + cross-process resume + node retry + provider failover, gap-free), **completing the Phase-1 engine critical path**. The remaining Phase-1 work is additive and off the critical path (Lane C: the **`session:*` namespace (1.W) landed (PR #28, 2026-06-17)** — the `SessionEventSink`→`RunEventBus` adapter + per-session `sequenceNumber`, the `SessionHandle`, and the combined `RunOrSessionEventSchema` gate — and **session persistence (1.X) landed (PR #29, 2026-06-17)** — the `agent_sessions`/`session_messages` tables + migration, `SessionMessageSchema`/`AgentSessionSchema`, and the `SessionStore` + domain↔row mappers (data-layer only); then **session checkpoint/resume (1.Y) + export-to-workflow (1.Z) landed (PR #30, 2026-06-17)** — `reconstructSessionState`/`AgentSession.resume` (reload-not-replay; preload the text-only transcript, re-seed turnCount/cost, no `session:started` re-emit) + the `serializeWorkflow`/`sessionToWorkflow` pair (one agent node per completed turn, transcript in `metadata`, secret/signature exclusion structural) — leaving only the **1.AA** chat-regression harness ‖ the 1.m6 multimodal sub-spine, whose first step — **media-input adapters + the shared SSRF policy primitive (1.AE) — landed (PR #32, 2026-06-18)** (base64 image/audio across the three adapters behind per-modality `assertMediaCapabilities`, and the one `@relavium/shared` SSRF policy primitive reused by the provider-`baseURL` + `http_request` callers; the SSRF *mechanism* half + per-modality FallbackChain gating moved into **1.AF**). **1.AF (engine media plumbing) is in progress: P1+P2 merged (PR #33)** — the `MediaStore`/`deInlineMedia` choke point (the active I3 enforcement), per-modality capability gating (`mediaSupportReason`/`requestSupportReason` — replacing coarse vision), the `media_objects`/`media_references` tables, and ADR-0042/0043/0044 — and **P3 + P4/D13 have landed on `development` in a follow-on PR (pending merge):** the binary media-egress + the **SSRF mechanism half** (D9 — the `MediaUrlFetch` re-host hook + the `fetchMediaBytes` SSRF-validated host reference wired at the choke point), the `FallbackChain` resolve-before-egress + the **byte-free re-materialization sidecar** (D8/D7), and the byte-delivery **`Range` gate** (D13 — `MediaStore.readRange` + `validateByteRange`), with the dedicated **P3 egress/SSRF security-review clean** (0 blockers/highs). The rest of **P4** follows: `read_media` + the scope-set authz (D12), the terminal sweep + GC (D11), `save_to` (D16), the `output_modalities` load-check (D15), the per-modality media cost governor (D17), the byte-delivery security-review + the keychain IPC test. **Phase 2 (CLI, M3) is unblocked**.
 Phase 0 (M0, 2026-06-04) landed the monorepo, strict toolchain + CI, `@relavium/shared` (the
 full Zod contract set), the no-vendor-type seam fence, and `@relavium/db`. Phase 1 has since
 landed `@relavium/llm` — the `LLMProvider` seam + all three adapters (Anthropic, OpenAI/DeepSeek,
@@ -64,7 +64,7 @@ The pre-egress budget governor (1.AC) + the agent-first `AgentSession` (1.V) lan
 **completing 1.m4**; then the end-to-end Node harness (1.U) landed (PR #27, 2026-06-16) **reaching M2** —
 the Phase-1 engine critical path is complete. The additive Lane-C agent-first sub-spine is now **complete**
 (session events **1.W ✅ (PR #28)** + persistence **1.X ✅ (PR #29)** + checkpoint/resume **1.Y** & export **1.Z ✅ (PR #30, 2026-06-17)** + the **1.AA** chat-regression harness ✅ (2026-06-17), closing **1.m5**);
-on the 1.m6 multimodal sub-spine, **media-input adapters + the shared SSRF policy primitive (1.AE) landed (PR #32, 2026-06-18)** — after a multi-round + final 8-dimension adversarial review (no SSRF bypass found); the SSRF *mechanism* half + per-modality gating moved into 1.AF. **1.AF (engine media plumbing) is now in progress — PR #33** lands P1+P2 (the `MediaStore`/`deInlineMedia` choke point, per-modality gating, the media tables + ADR-0042/0043/0044); P3/P4 (egress + access/cost) follow. The remaining Phase-1 work is 1.AF (in progress) + 1.AG/1.AH; Phase 2 (CLI) is unblocked. See
+on the 1.m6 multimodal sub-spine, **media-input adapters + the shared SSRF policy primitive (1.AE) landed (PR #32, 2026-06-18)** — after a multi-round + final 8-dimension adversarial review (no SSRF bypass found); the SSRF *mechanism* half + per-modality gating moved into 1.AF. **1.AF (engine media plumbing) is in progress: P1+P2 merged (PR #33)**; **P3 + P4/D13 landed on `development` (pending merge)** — the media-egress + SSRF mechanism half (D9), the `FallbackChain` resolve-before-egress + byte-free re-materialization sidecar (D8/D7), the byte-delivery `Range` gate (D13), and a clean P3 egress/SSRF security-review — with the rest of P4 (D12 `read_media` + authz, D11 GC sweep, D16 `save_to`, D15 load-check, D17 cost governor) to follow. The remaining Phase-1 work is 1.AF (in progress) + 1.AG/1.AH; Phase 2 (CLI) is unblocked. See
 [docs/roadmap/current.md](docs/roadmap/current.md). See [README.md](README.md) for the public overview.
 
 ## Non-negotiable rules for AI agents

docs/roadmap/current.md

@@ -217,18 +217,26 @@ harness is now ✅ Done (2026-06-17), completing **1.m5**; cost-event persistenc
 > **media-input adapters + the shared SSRF policy primitive (1.AE) are ✅ Done (PR #32, 2026-06-18)** —
 > after a multi-round + final 8-dimension adversarial review (no SSRF bypass found); the SSRF *mechanism*
 > half (host DNS-resolve + connect-by-validated-IP), per-modality FallbackChain gating, `mediaUnits`, and
-> handle/url media resolution are deferred to **1.AF**. **1.AF (engine media plumbing) is 🔨 in progress on
-> `development`** — its three design ADRs (0042/0043/0044) are Accepted, and **P1 + P2 have landed (NOT yet
-> merged):** the `MediaStore` contract impls + `media_objects`/`media_references` tables (migration 0002),
-> per-modality capability gating + `FallbackChain` skip, `deInlineMedia`, the strict `output_modalities`/
-> `save_to` node fields, OpenAI `mediaUnits`, and **the I3 keystone — `deInlineMedia` at the one
-> `#emitDurable` choke point** (all green, Leakwatch-clean). **Remaining (P3 + P4, some security-critical):**
-> the binary media-egress + SSRF mechanism half (D9), `read_media` + the byte-delivery gate (D12/D13),
-> the failover sidecar (D7), adapter handle/url resolution (D8), the terminal sweep (D11), the
-> `output_modalities` load-check (D15), the `save_to` write port (D16), and the per-modality media cost
-> governor (D17) — D9 and D12/D13 want a dedicated security-review pass. The remaining Phase-1 work is
-> **additive and off the critical path**: only **1.AF–1.AH** (engine media plumbing, output, surfaces) remain
-> before Phase 1 closes. **Phase 2 (CLI, milestone M3) is unblocked.**
+> handle/url media resolution are deferred to **1.AF**. **1.AF (engine media plumbing) is 🔨 in progress:
+> P1 + P2 merged (PR #33)**, and **P3 + P4/D13 have landed on `development` in a follow-on PR (NOT yet
+> merged)** — its three design ADRs (0042/0043/0044) are Accepted.
+> **Merged (P1+P2, PR #33):** the `MediaStore` contract impls + `media_objects`/`media_references` tables
+> (migration 0002), per-modality capability gating + `FallbackChain` skip, `deInlineMedia`, the strict
+> `output_modalities`/`save_to` node fields, OpenAI `mediaUnits`, and **the I3 keystone — `deInlineMedia`
+> at the one `#emitDurable` choke point**.
+> **Landed on `development` (pending merge):** the binary media-egress + **SSRF mechanism half** (D9 — the
+> `MediaUrlFetch` re-host hook + `fetchMediaBytes` SSRF-validated host reference: DNS-resolve +
+> connect-by-validated-IP + per-hop redirect re-validation + streamed size-bound, wired at the choke point);
+> the `FallbackChain` resolve-before-egress + **byte-free re-materialization sidecar** (D8 + D7); the
+> **byte-delivery `Range` gate** (D13 — `MediaStore.readRange` + the engine-pure `validateByteRange`); and the
+> dedicated **P3 egress/SSRF security-review** (independent adversarial — 0 blockers/highs). All green +
+> Leakwatch-clean.
+> **Remaining (P4):** `read_media` + the scope-set authz (D12), the terminal sweep + GC (D11), the
+> `save_to` write port (D16), the `output_modalities` load-check (D15), and the per-modality media cost
+> governor (D17) — D12/D13 share a dedicated byte-delivery security-review pass + the keychain no-raw-key
+> IPC test; plus the still-pending canonical-home docs (built-in-tools, config-spec, security-review). The
+> remaining Phase-1 work is **additive and off the critical path**: only **1.AF–1.AH** (engine media plumbing,
+> output, surfaces) remain before Phase 1 closes. **Phase 2 (CLI, milestone M3) is unblocked.**
 
 Carry-over hardening is tracked in [deferred-tasks.md](deferred-tasks.md) — pick items up as Phase 1
 first touches each file.