From afb17fc33474e32b90eaa9bb2e15a47d17db6b84 Mon Sep 17 00:00:00 2001
From: udo <udo@openfu.com>
Date: Tue, 14 Jul 2026 04:34:52 +0000
Subject: [PATCH] test: retry transient doc gate reads

---
 docs/wasm-runtime-architecture.md |  4 ++-
 site/tests/cli_runner.uce         | 43 +++++++++++++++++++------------
 2 files changed, 29 insertions(+), 18 deletions(-)

diff --git a/docs/wasm-runtime-architecture.md b/docs/wasm-runtime-architecture.md
index be3a020..1a3e408 100644
--- a/docs/wasm-runtime-architecture.md
+++ b/docs/wasm-runtime-architecture.md
@@ -365,7 +365,9 @@ header free-functions are `inline`. The wasm backend exposes only declarations
   failing group is visible before the rest of the gate runs. `doc-gate` can take
   several minutes on a cold runtime because it compiles generated documentation
   examples; `UCE_CLI_TEST_TIMEOUT` controls the per-group curl timeout and
-  defaults to 900 seconds. The dependency-invalidation gate changes a transitive
+  defaults to 900 seconds. Individual doc-page checks retry transient empty
+  frontend reads, but still fail persistent status, marker, compile, runtime, or
+  placeholder-example errors. The dependency-invalidation gate changes a transitive
   `#load`, then replaces a warmed worker artifact while preserving its
   whole-second mtime to prove both compiler and worker caches invalidate it. It
   also rejects an unreadable unit without publishing a wasm artifact, restores
diff --git a/site/tests/cli_runner.uce b/site/tests/cli_runner.uce
index 2fcb25b..915539a 100644
--- a/site/tests/cli_runner.uce
+++ b/site/tests/cli_runner.uce
@@ -214,27 +214,36 @@ void cli_run_doc_pages_gate()
 			continue;
 		bool has_example = cli_doc_source_has_example(source);
 		String path = "/doc/index.uce?p=" + uri_encode(page);
-		CliHttpResponse res = cli_frontend(path);
+		CliHttpResponse res;
 		String summary;
-		bool ok = cli_expect_http_once(res, path, 200, "doc-detail", error_markers, summary);
-		String lower = to_lower(res.body);
-		if(has_example)
+		bool ok = false;
+		for(u64 attempt = 0; attempt < 3; attempt++)
 		{
-			if(!cli_contains(res.body, "class=\"example-output\"") || !cli_contains(res.body, "example-output-label\">Output"))
+			if(attempt > 0)
+				usleep(500000);
+			res = cli_frontend(path);
+			ok = cli_expect_http_once(res, path, 200, "doc-detail", error_markers, summary);
+			String lower = to_lower(res.body);
+			if(has_example)
 			{
-				ok = false;
-				summary += "; missing example Output block";
-			}
-			if(cli_contains(lower, "doc example error"))
-			{
-				ok = false;
-				summary += "; example reported an error";
-			}
-			if(cli_doc_example_is_placeholder(source))
-			{
-				ok = false;
-				summary += "; placeholder example (must exercise the API)";
+				if(!cli_contains(res.body, "class=\"example-output\"") || !cli_contains(res.body, "example-output-label\">Output"))
+				{
+					ok = false;
+					summary += "; missing example Output block";
+				}
+				if(cli_contains(lower, "doc example error"))
+				{
+					ok = false;
+					summary += "; example reported an error";
+				}
+				if(cli_doc_example_is_placeholder(source))
+				{
+					ok = false;
+					summary += "; placeholder example (must exercise the API)";
+				}
 			}
+			if(ok)
+				break;
 		}
 		cli_test_case("uce_doc_gate:doc page " + page, ok, ok ? summary : summary + "; body=" + cli_truncate(res.body));
 	}