From 85083a0fff1cf7e45a1e5c1fc2c760c4274db0fd Mon Sep 17 00:00:00 2001
From: giles <giles.bradshaw@rose-ash.com>
Date: Sat, 7 Mar 2026 17:03:07 +0000
Subject: [PATCH] Formalise Phase 5 (Client IO Proxy) as complete
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 5 was solved by IO proxy registration + async DOM renderer +
JavaScript Promises — no continuations needed on the client side.
Continuations remain a prerequisite for Phase 6 (server-side streaming).

Updated plan status: Phases 1-5 complete. Phase 4 moved from Partial.
Renumbered: streaming/suspense is now Phase 6, full iso is Phase 7.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 sx/sx/plans.sx | 97 ++++++++++++++++++++++++++++++++------------------
 1 file changed, 62 insertions(+), 35 deletions(-)

diff --git a/sx/sx/plans.sx b/sx/sx/plans.sx
index 347ac89..ef9c8f7 100644
--- a/sx/sx/plans.sx
+++ b/sx/sx/plans.sx
@@ -282,7 +282,7 @@
               (li "Inline content renders immediately")
               (li "CID-referenced content shows placeholder → fetches from IPFS → renders")
               (li "Large media uses IPFS streaming (chunked CIDs)")
-              (li "Integrates with Phase 5 of isomorphic plan (streaming/suspense)")))))
+              (li "Integrates with Phase 6 of isomorphic plan (streaming/suspense)")))))
 
       (~doc-subsection :title "Verification"
         (ul :class "list-disc pl-5 text-stone-700 space-y-1"
@@ -535,7 +535,7 @@
           (li "Phase 1 (component distribution) → IPFS replaces per-server bundles")
           (li "Phase 2 (IO detection) → pure components safe for IPFS publication")
           (li "Phase 3 (client routing) → client can resolve federated content without server")
-          (li "Phase 5 (streaming/suspense) → progressive IPFS resolution uses same infrastructure"))))
+          (li "Phase 6 (streaming/suspense) → progressive IPFS resolution uses same infrastructure"))))
 
     ;; -----------------------------------------------------------------------
     ;; Critical Files
@@ -1316,7 +1316,25 @@
           (div :class "flex items-center gap-2 mb-1"
             (span :class "inline-block px-2 py-0.5 rounded text-xs font-bold bg-green-600 text-white uppercase" "Complete")
             (a :href "/isomorphism/" :class "font-semibold text-green-800 underline" "Isomorphic Phase 3: Client-Side Routing"))
-          (p :class "text-sm text-stone-600" "router.sx spec, page registry via <script type=\"text/sx-pages\">, client route matching, try-first/fallback to server. Pure pages render without server roundtrips."))))
+          (p :class "text-sm text-stone-600" "router.sx spec, page registry via <script type=\"text/sx-pages\">, client route matching, try-first/fallback to server. Pure pages render without server roundtrips."))
+
+        (div :class "rounded border border-green-200 bg-green-50 p-4"
+          (div :class "flex items-center gap-2 mb-1"
+            (span :class "inline-block px-2 py-0.5 rounded text-xs font-bold bg-green-600 text-white uppercase" "Complete")
+            (a :href "/isomorphism/" :class "font-semibold text-green-800 underline" "Isomorphic Phase 4: Client Async & IO Bridge"))
+          (p :class "text-sm text-stone-600" "Server evaluates :data expressions, serializes as SX wire format. Client fetches pre-evaluated data, caches with 30s TTL, renders :content locally. 30 unit tests."))
+
+        (div :class "rounded border border-green-200 bg-green-50 p-4"
+          (div :class "flex items-center gap-2 mb-1"
+            (span :class "inline-block px-2 py-0.5 rounded text-xs font-bold bg-green-600 text-white uppercase" "Complete")
+            (a :href "/isomorphism/" :class "font-semibold text-green-800 underline" "Isomorphic Phase 5: Client IO Proxy"))
+          (p :class "text-sm text-stone-600" "IO primitives (highlight, asset-url, etc.) proxied to server via registerIoDeps(). Async DOM renderer handles promises through the render tree. Components with IO deps render client-side via server round-trips — no continuations needed."))
+
+        (div :class "rounded border border-green-200 bg-green-50 p-4"
+          (div :class "flex items-center gap-2 mb-1"
+            (span :class "inline-block px-2 py-0.5 rounded text-xs font-bold bg-green-600 text-white uppercase" "Complete")
+            (a :href "/testing/" :class "font-semibold text-green-800 underline" "Modular Test Architecture"))
+          (p :class "text-sm text-stone-600" "Per-module test specs (eval, parser, router, render) with 161 tests. Three runners: Python, Node.js, browser. 5 platform functions, everything else pure SX."))))
 
     ;; -----------------------------------------------------------------------
     ;; In Progress / Partial
@@ -1330,13 +1348,7 @@
           (div :class "flex items-center gap-2 mb-1"
             (span :class "inline-block px-2 py-0.5 rounded text-xs font-bold bg-amber-600 text-white uppercase" "Partial")
             (a :href "/plans/fragment-protocol" :class "font-semibold text-amber-900 underline" "Fragment Protocol"))
-          (p :class "text-sm text-stone-600" "Fragment GET infrastructure works. The planned POST/sexp structured protocol for transferring component definitions between services is not yet implemented. Fragment endpoints still use legacy GET + X-Fragment-Request headers."))
-
-        (div :class "rounded border border-amber-200 bg-amber-50 p-4"
-          (div :class "flex items-center gap-2 mb-1"
-            (span :class "inline-block px-2 py-0.5 rounded text-xs font-bold bg-amber-600 text-white uppercase" "Partial")
-            (a :href "/isomorphism/" :class "font-semibold text-amber-900 underline" "Isomorphic Phase 4: Client Async & IO Bridge"))
-          (p :class "text-sm text-stone-600" "Some async evaluation infrastructure exists (helpers.py, async_eval.py). The io-bridge.sx spec file for client-side IO primitives (query -> REST, frag -> fetch) does not exist yet."))))
+          (p :class "text-sm text-stone-600" "Fragment GET infrastructure works. The planned POST/sexp structured protocol for transferring component definitions between services is not yet implemented. Fragment endpoints still use legacy GET + X-Fragment-Request headers."))))
 
     ;; -----------------------------------------------------------------------
     ;; Not Started
@@ -1377,14 +1389,14 @@
         (div :class "rounded border border-stone-200 bg-stone-50 p-4"
           (div :class "flex items-center gap-2 mb-1"
             (span :class "inline-block px-2 py-0.5 rounded text-xs font-bold bg-stone-500 text-white uppercase" "Not Started")
-            (a :href "/isomorphism/" :class "font-semibold text-stone-800 underline" "Isomorphic Phase 5: Streaming & Suspense"))
-          (p :class "text-sm text-stone-600" "Server streams partially-evaluated SX as IO resolves. Client renders available subtrees immediately, fills in suspended parts. No suspense.sx spec or chunked transfer implementation.")
-          (p :class "text-sm text-stone-500 mt-1" "Depends on: Phase 4 (client async)."))
+            (a :href "/isomorphism/" :class "font-semibold text-stone-800 underline" "Isomorphic Phase 6: Streaming & Suspense"))
+          (p :class "text-sm text-stone-600" "Server streams partially-evaluated SX as IO resolves. Client renders available subtrees immediately, fills in suspended parts. Requires async-aware delimited continuations for suspension.")
+          (p :class "text-sm text-stone-500 mt-1" "Depends on: Phase 5 (IO proxy), continuations spec."))
 
         (div :class "rounded border border-stone-200 bg-stone-50 p-4"
           (div :class "flex items-center gap-2 mb-1"
             (span :class "inline-block px-2 py-0.5 rounded text-xs font-bold bg-stone-500 text-white uppercase" "Not Started")
-            (a :href "/isomorphism/" :class "font-semibold text-stone-800 underline" "Isomorphic Phase 6: Full Isomorphism"))
+            (a :href "/isomorphism/" :class "font-semibold text-stone-800 underline" "Isomorphic Phase 7: Full Isomorphism"))
           (p :class "text-sm text-stone-600" "Runtime boundary optimizer, affinity annotations, offline data layer via Service Worker + IndexedDB, isomorphic testing harness.")
           (p :class "text-sm text-stone-500 mt-1" "Depends on: all previous phases."))))))
 
@@ -1822,36 +1834,47 @@
     ;; Phase 5
     ;; -----------------------------------------------------------------------
 
-    (~doc-section :title "Phase 5: Async Continuations & Inline IO" :id "phase-5"
+    (~doc-section :title "Phase 5: Client IO Proxy" :id "phase-5"
 
-      (div :class "rounded border border-violet-200 bg-violet-50 p-4 mb-4"
-        (p :class "text-violet-900 font-medium" "What it enables")
-        (p :class "text-violet-800" "Components call IO primitives directly in their body. The evaluator suspends mid-evaluation via async-aware continuations, fetches data, resumes. Same component source works on both server (Python async/await) and client (continuation-based suspension)."))
+      (div :class "rounded border border-green-300 bg-green-50 p-4 mb-4"
+        (div :class "flex items-center gap-2 mb-2"
+          (span :class "inline-block px-2 py-0.5 rounded text-xs font-bold bg-green-600 text-white uppercase" "Complete"))
+        (p :class "text-green-900 font-medium" "What it enables")
+        (p :class "text-green-800" "Components with IO dependencies render client-side. IO primitives are proxied to the server — the client evaluator calls them like normal functions, the proxy fetches results via HTTP, the async DOM renderer awaits the promises and continues."))
 
-      (~doc-subsection :title "The Problem"
-        (p "The existing shift/reset continuations extension is synchronous (throw/catch). Client-side IO via fetch() returns a Promise — you can't throw-catch across an async boundary. The evaluator needs Promise-aware continuations or a CPS transform."))
+      (~doc-subsection :title "How it works"
+        (p "Instead of async-aware continuations (originally planned), Phase 5 was solved by combining three mechanisms that emerged from Phases 3-4:")
 
-      (~doc-subsection :title "Approach"
         (div :class "space-y-4"
           (div
-            (h4 :class "font-semibold text-stone-700" "1. Async-aware shift/reset")
-            (p "Extend the continuations extension: sfShift captures the continuation and returns a Promise, sfReset awaits Promise results in the trampoline. Continuation resume feeds the fetched value back into evaluation."))
+            (h4 :class "font-semibold text-stone-700" "1. IO dependency detection (from Phase 2)")
+            (p "The component dep analyzer scans AST bodies for IO primitive names (highlight, asset-url, query, frag, etc.) and computes transitive IO refs. Pages include their IO dep list in the page registry."))
 
           (div
-            (h4 :class "font-semibold text-stone-700" "2. IO primitive bridge")
-            (p "Register async IO primitives in client PRIMITIVES:")
-            (ul :class "list-disc pl-5 text-stone-700 space-y-1 font-mono text-sm"
-              (li "query → fetch to /internal/data/")
-              (li "service → fetch to target service internal endpoint")
-              (li "frag → fetch fragment HTML")
-              (li "current-user → cached from initial page load")))
+            (h4 :class "font-semibold text-stone-700" "2. IO proxy registration")
+            (p (code "registerIoDeps(names)") " in orchestration.sx registers proxy functions for each IO primitive. When the client evaluator encounters " (code "(highlight code \"sx\")") ", the proxy sends an HTTP request to the server's IO endpoint and returns a Promise."))
 
           (div
-            (h4 :class "font-semibold text-stone-700" "3. CPS transform option")
-            (p "Alternative: transform the evaluator to continuation-passing style. Every eval step takes a continuation argument. IO primitives call the continuation after fetch resolves. Architecturally cleaner but requires deeper changes."))))
+            (h4 :class "font-semibold text-stone-700" "3. Async DOM renderer")
+            (p (code "asyncRenderToDom") " walks the expression tree and handles Promises transparently. When a subexpression returns a Promise (from an IO proxy call), the renderer awaits it and continues building the DOM tree. No continuations needed — JavaScript's native Promise mechanism provides the suspension."))))
 
-      (div :class "rounded border border-amber-200 bg-amber-50 p-3 mt-2"
-        (p :class "text-amber-800 text-sm" (strong "Depends on: ") "Phase 4 (data endpoint infrastructure).")))
+      (~doc-subsection :title "Why continuations weren't needed"
+        (p "The original Phase 5 plan called for async-aware shift/reset or a CPS transform of the evaluator. In practice, JavaScript's Promise mechanism provided the same capability: the async DOM renderer naturally suspends when it encounters a Promise and resumes when it resolves.")
+        (p "Delimited continuations remain valuable for Phase 6 (streaming/suspense on the " (em "server") " side, where Python doesn't have native Promise-based suspension in the evaluator). But for client-side IO, Promises + async render were sufficient."))
+
+      (~doc-subsection :title "Files"
+        (ul :class "list-disc pl-5 text-stone-700 space-y-1 font-mono text-sm"
+          (li "shared/sx/ref/orchestration.sx — registerIoDeps, IO proxy registration")
+          (li "shared/sx/ref/bootstrap_js.py — asyncRenderToDom, IO proxy HTTP transport")
+          (li "shared/sx/helpers.py — io_deps in page registry entries")
+          (li "shared/sx/deps.py — transitive IO ref computation")))
+
+      (~doc-subsection :title "Verification"
+        (ul :class "list-disc pl-5 text-stone-700 space-y-1"
+          (li "Navigate to any page with IO deps (e.g. /testing/eval) — console shows IO proxy calls")
+          (li "Components using " (code "highlight") " render correctly via proxy")
+          (li "Pages with " (code "asset-url") " resolve script paths via proxy")
+          (li "Async render completes without blocking — partial results appear as promises resolve"))))
 
     ;; -----------------------------------------------------------------------
     ;; Phase 6
@@ -1863,6 +1886,10 @@
         (p :class "text-violet-900 font-medium" "What it enables")
         (p :class "text-violet-800" "Server streams partially-evaluated SX as IO resolves. Client renders available subtrees immediately, fills in suspended parts. Like React Suspense but built on delimited continuations."))
 
+      (div :class "rounded border border-amber-200 bg-amber-50 p-3 mb-4"
+        (p :class "text-amber-800 text-sm" (strong "Prerequisite: ") "Async-aware delimited continuations. The client solved IO suspension via JavaScript Promises (Phase 5), but the server needs continuations to suspend mid-evaluation when IO is encountered during streaming. Python's evaluator must capture the continuation at an IO call, emit a placeholder, schedule the IO, and resume the continuation when the result arrives."))
+
+
       (~doc-subsection :title "Approach"
 
         (div :class "space-y-4"
@@ -1887,7 +1914,7 @@
             (p "Above-fold content resolves first. All IO starts concurrently (asyncio.create_task), results flushed in priority order."))))
 
       (div :class "rounded border border-amber-200 bg-amber-50 p-3 mt-2"
-        (p :class "text-amber-800 text-sm" (strong "Depends on: ") "Phase 5 (async continuations for filling suspended subtrees), Phase 2 (IO analysis for priority).")))
+        (p :class "text-amber-800 text-sm" (strong "Depends on: ") "Phase 5 (IO proxy for client rendering), async-aware delimited continuations (for server-side suspension), Phase 2 (IO analysis for priority).")))
 
     ;; -----------------------------------------------------------------------
     ;; Phase 7