From 9cb2708abc83d09fba87b267380348f97c912d19 Mon Sep 17 00:00:00 2001
From: Dami <dami.etoile@gmail.com>
Date: Mon, 20 Jul 2026 12:23:55 -0600
Subject: [PATCH] fix: restore enrolled sync before runtime startup

---
 .../overlay/src/islands/IncidentBoard.tsx     |  1 +
 package/preact/DeviceStatus.tsx               |  9 ++-
 package/runtime/boot.ts                       |  8 +--
 package/runtime/data-sink.ts                  | 71 ++++++++++++++-----
 package/runtime/data-sink_test.ts             | 68 ++++++++++++++++++
 package/runtime/runtime.ts                    | 11 ++-
 tools/demo_overlay_test.ts                    |  4 ++
 7 files changed, 145 insertions(+), 27 deletions(-)

diff --git a/apps/demo/overlay/src/islands/IncidentBoard.tsx b/apps/demo/overlay/src/islands/IncidentBoard.tsx
index 50ca64c..583c503 100644
--- a/apps/demo/overlay/src/islands/IncidentBoard.tsx
+++ b/apps/demo/overlay/src/islands/IncidentBoard.tsx
@@ -78,6 +78,7 @@ export default function IncidentBoard() {
             autocomplete="off"
           />
           <select
+            name="severity"
             aria-label="Severity"
             value={severity}
             onChange={(event) => setSeverity(event.currentTarget.value as Severity)}
diff --git a/package/preact/DeviceStatus.tsx b/package/preact/DeviceStatus.tsx
index c716303..49e4744 100644
--- a/package/preact/DeviceStatus.tsx
+++ b/package/preact/DeviceStatus.tsx
@@ -98,7 +98,14 @@ export function DeviceStatus(): VNode {
 
   useEffect(() => subscribePwaState(setPwa), []);
   useEffect(
-    () => subscribeRuntimeDiagnostics(() => setRuntimeDiagnostics(getRuntimeDiagnostics())),
+    () =>
+      subscribeRuntimeDiagnostics(() => {
+        setRuntimeDiagnostics(getRuntimeDiagnostics());
+        // Initial boot restores a sealed runtime-declared sink asynchronously.
+        // An island can mount before that restore completes, so refresh the
+        // synchronous session snapshot whenever boot diagnostics advance.
+        setSession(readSession());
+      }),
     [],
   );
   useEffect(() => {
diff --git a/package/runtime/boot.ts b/package/runtime/boot.ts
index 0b0195a..2a98168 100644
--- a/package/runtime/boot.ts
+++ b/package/runtime/boot.ts
@@ -1,7 +1,7 @@
 /// <reference path="./env.d.ts" />
 // Package-owned browser boot orchestration.
 import { getLofiApp } from "./app.ts";
-import { restoreDeclaredSink } from "./data-sink.ts";
+import { ensureDeclaredSinkRestored } from "./data-sink.ts";
 import {
   attachPwaUpdateCoordination,
   registerProductionServiceWorker,
@@ -69,11 +69,7 @@ export async function bootLofi(): Promise<void> {
   // The sink envelope must be open before lifecycle.ts reads the sync
   // location at import time. A restore failure degrades to local-only; it
   // must never brick boot.
-  try {
-    await restoreDeclaredSink();
-  } catch {
-    // Continue local-only; enrollment can re-declare the sink.
-  }
+  await ensureDeclaredSinkRestored();
   startCompatibilityGate();
   await import("./lifecycle.ts");
   // Arm the write ledger so journaled writes reconcile and outstanding effect
diff --git a/package/runtime/data-sink.ts b/package/runtime/data-sink.ts
index 0cb63c8..13397a5 100644
--- a/package/runtime/data-sink.ts
+++ b/package/runtime/data-sink.ts
@@ -112,10 +112,27 @@ const sinkKey = `lofi:data-sink:${anchorAppId}`;
 const sinkPurpose = `lofi:data-sink:${anchorAppId}`;
 const sinkDeviceKeyId = `data-sink:${anchorAppId}`;
 
-// The declaration in effect for this document, populated by
-// restoreDeclaredSink at boot and by successful declarations afterwards.
-// Synchronous readers answer from here; storage holds only the envelope.
-let cachedSink: DataSinkDeclaration | null = null;
+// Astro islands can bundle this module more than once in the same document.
+// Keep the restored declaration on globalThis so every island observes the
+// boot script's restore and a declaration made by any sibling island. Storage
+// still holds only the sealed envelope.
+type DataSinkSlot = {
+  cachedSink: DataSinkDeclaration | null;
+  lastRestoreOutcome: SinkRestoreOutcome;
+  restorePromise: Promise<SinkRestoreOutcome> | null;
+};
+
+const dataSinkSlotName = "__LOFI_ALPHA53_DATA_SINK__";
+const browserGlobal = globalThis as typeof globalThis & { [dataSinkSlotName]?: DataSinkSlot };
+
+function dataSinkSlot(): DataSinkSlot {
+  browserGlobal[dataSinkSlotName] ??= {
+    cachedSink: null,
+    lastRestoreOutcome: "none",
+    restorePromise: null,
+  };
+  return browserGlobal[dataSinkSlotName];
+}
 
 function validateDeclaration(value: unknown): DataSinkDeclaration | null {
   if (value === null || typeof value !== "object") return null;
@@ -167,8 +184,6 @@ export type SinkRestoreOutcome = "none" | "restored" | "migrated" | "unopenable"
 // The most recent restore's outcome, kept so status surfaces can distinguish
 // "no sync location" from "a sync location exists but this device cannot open
 // it". Cleared when the record is removed or successfully re-declared.
-let lastRestoreOutcome: SinkRestoreOutcome = "none";
-
 /**
  * How the most recent {@link restoreDeclaredSink} resolved. An `unopenable`
  * answer means a declaration is persisted but no available key opens it — the
@@ -176,7 +191,7 @@ let lastRestoreOutcome: SinkRestoreOutcome = "none";
  * status surface should say so rather than showing plain local-only.
  */
 export function readSinkRestoreOutcome(): SinkRestoreOutcome {
-  return lastRestoreOutcome;
+  return dataSinkSlot().lastRestoreOutcome;
 }
 
 /**
@@ -187,12 +202,32 @@ export function readSinkRestoreOutcome(): SinkRestoreOutcome {
 export async function restoreDeclaredSink(
   keyStore: DeviceKeyStore = defaultDeviceKeyStore(),
 ): Promise<SinkRestoreOutcome> {
-  lastRestoreOutcome = await resolveRestore(keyStore);
-  return lastRestoreOutcome;
+  const state = dataSinkSlot();
+  state.lastRestoreOutcome = await resolveRestore(keyStore);
+  return state.lastRestoreOutcome;
+}
+
+/**
+ * Restores the document's sealed sink exactly once before the first runtime
+ * opens. App islands and the boot script can start concurrently; sharing this
+ * promise prevents an eager island from creating a local-only client while
+ * boot is still unsealing a configured sink.
+ */
+export function ensureDeclaredSinkRestored(
+  keyStore: DeviceKeyStore = defaultDeviceKeyStore(),
+): Promise<SinkRestoreOutcome> {
+  const state = dataSinkSlot();
+  state.restorePromise ??= restoreDeclaredSink(keyStore).catch(() => {
+    state.cachedSink = null;
+    state.lastRestoreOutcome = "none";
+    return "none";
+  });
+  return state.restorePromise;
 }
 
 async function resolveRestore(keyStore: DeviceKeyStore): Promise<SinkRestoreOutcome> {
-  cachedSink = null;
+  const state = dataSinkSlot();
+  state.cachedSink = null;
   if (typeof localStorage === "undefined") return "none";
   let raw: string | null = null;
   try {
@@ -213,7 +248,7 @@ async function resolveRestore(keyStore: DeviceKeyStore): Promise<SinkRestoreOutc
     // cleartext bearer URL leaves storage on the first boot that can.
     const sink = validateDeclaration(record.sink);
     if (!sink) return "none";
-    cachedSink = sink;
+    state.cachedSink = sink;
     await persistSealed(sink, keyStore);
     return "migrated";
   }
@@ -224,7 +259,7 @@ async function resolveRestore(keyStore: DeviceKeyStore): Promise<SinkRestoreOutc
       const payload = await openJsonEnvelope(sinkPurpose, sealed, deviceKeyResolver(keyStore));
       const sink = validateDeclaration(payload);
       if (!sink) return "unopenable";
-      cachedSink = sink;
+      state.cachedSink = sink;
       return "restored";
     } catch (error) {
       if (error instanceof EnvelopeError) return "unopenable";
@@ -240,7 +275,7 @@ async function resolveRestore(keyStore: DeviceKeyStore): Promise<SinkRestoreOutc
  * (tests, embedders) await {@link restoreDeclaredSink} first.
  */
 export function readDeclaredSink(): DataSinkDeclaration | null {
-  return cachedSink;
+  return dataSinkSlot().cachedSink;
 }
 
 function assertHttpServerUrl(serverUrl: string): void {
@@ -295,17 +330,19 @@ export async function declareDataSink(
     );
   }
   await persistSealed(declaration, keyStore);
-  cachedSink = declaration;
+  const state = dataSinkSlot();
+  state.cachedSink = declaration;
   // The record now seals under an available key; an earlier unopenable
   // restore no longer describes it.
-  lastRestoreOutcome = "restored";
+  state.lastRestoreOutcome = "restored";
   return declaration;
 }
 
 /** Removes the declared sink. Existing local data and elections are untouched. */
 export function clearDeclaredSink(): void {
-  cachedSink = null;
-  lastRestoreOutcome = "none";
+  const state = dataSinkSlot();
+  state.cachedSink = null;
+  state.lastRestoreOutcome = "none";
   if (typeof localStorage === "undefined") return;
   try {
     localStorage.removeItem(sinkKey);
diff --git a/package/runtime/data-sink_test.ts b/package/runtime/data-sink_test.ts
index d480b5c..30e41a2 100644
--- a/package/runtime/data-sink_test.ts
+++ b/package/runtime/data-sink_test.ts
@@ -8,6 +8,7 @@ import {
   clearDeclaredSink,
   declareDataSink,
   declareSinkFromTicket,
+  ensureDeclaredSinkRestored,
   isDataSinkError,
   parseSyncTicket,
   readDeclaredSink,
@@ -105,6 +106,73 @@ test(
   }),
 );
 
+test(
+  "boot and app islands single-flight the sealed sink restore",
+  withCleanState(async () => {
+    const keyStore = memoryDeviceKeyStore();
+    await declareDataSink({
+      appId: ticketAppId,
+      serverUrl: "https://node.example:4802",
+      label: "boot race",
+    }, keyStore);
+    const stored = localStorage.getItem(sinkKey);
+    assert(stored !== null, "the test sink must persist before simulating a fresh document");
+    clearDeclaredSink();
+    localStorage.setItem(sinkKey, stored);
+
+    let release!: () => void;
+    const gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    let reads = 0;
+    const delayedStore = {
+      getOrCreate: (keyId: string) => keyStore.getOrCreate(keyId),
+      async get(keyId: string) {
+        reads++;
+        await gate;
+        return await keyStore.get(keyId);
+      },
+    };
+    const boot = ensureDeclaredSinkRestored(delayedStore);
+    const island = (await import("./data-sink.ts?island=early-runtime"))
+      .ensureDeclaredSinkRestored(delayedStore);
+    assert(boot === island, "boot and an eager island must await the same restore promise");
+    assert(
+      readDeclaredSink() === null,
+      "the sink must remain unavailable while restore is pending",
+    );
+    release();
+    assert(await boot === "restored", "the shared restore must open the sealed sink");
+    assert(reads === 1, `the device key was read ${reads} times instead of once`);
+    assert(
+      readDeclaredSink()?.label === "boot race",
+      "the restored sink must precede runtime open",
+    );
+  }),
+);
+
+test(
+  "duplicate app-island module instances share the document sink cache",
+  withCleanState(async () => {
+    const accountIsland = await import("./data-sink.ts?island=account");
+    const deviceIsland = await import("./data-sink.ts?island=device");
+    await accountIsland.declareDataSink({
+      appId: ticketAppId,
+      serverUrl: "https://node.example:4802",
+      label: "shared island sink",
+    });
+    assert(
+      deviceIsland.readDeclaredSink()?.label === "shared island sink",
+      "a sibling island must observe the sink declared through another module instance",
+    );
+    deviceIsland.clearDeclaredSink();
+    assert(
+      accountIsland.readDeclaredSink() === null,
+      "clearing through one island must update every module instance",
+    );
+  }),
+);
+
 test(
   "an unreadable or unversioned sink record restores as absent",
   withCleanState(async () => {
diff --git a/package/runtime/runtime.ts b/package/runtime/runtime.ts
index 6d69b30..87262a2 100644
--- a/package/runtime/runtime.ts
+++ b/package/runtime/runtime.ts
@@ -5,6 +5,7 @@ import { getLofiApp } from "./app.ts";
 import { bootProgressTracker } from "./boot-progress.ts";
 import { createDiagnostics, type RuntimeDiagnostics } from "./diagnostics.ts";
 import { activeSink, appId, databaseConfig, syncing } from "./config.ts";
+import { ensureDeclaredSinkRestored } from "./data-sink.ts";
 import { assertSchemaWritable, schemaCompatGate, subscribeSchemaCompat } from "./schema-compat.ts";
 import { resolveStoreStatus } from "./store-status.ts";
 import { acquireUpgradeWriteLock } from "./upgrade-coordination.ts";
@@ -481,10 +482,14 @@ subscribeSchemaCompat((compat) => {
 });
 
 /** Opens or reuses the one package runtime for the current browser document. */
-export function getRuntime(): Promise<LofiRuntime> {
-  if (recreationPromise) return recreationPromise;
+export async function getRuntime(): Promise<LofiRuntime> {
+  // client:load islands can run concurrently with the inline boot module.
+  // Never let either path create a client until the one document-wide sink
+  // restore has settled, or a configured device can open local-only by race.
+  await ensureDeclaredSinkRestored();
+  if (recreationPromise) return await recreationPromise;
   const state = slot();
-  return adapter.get(
+  return await adapter.get(
     () => getResource(state.client, () => createClient(state)),
     (db) => attachRuntime(state, db),
   );
diff --git a/tools/demo_overlay_test.ts b/tools/demo_overlay_test.ts
index 265134e..7ee6ebd 100644
--- a/tools/demo_overlay_test.ts
+++ b/tools/demo_overlay_test.ts
@@ -48,4 +48,8 @@ Deno.test("the demo uses the starter's durable notice surface", async () => {
     "the overlay must not restore the hand-rolled in-memory notice channel",
   );
   assert(board.includes("<Notices"), "the incident board must render the durable notice queue");
+  assert(
+    board.includes('name="severity"'),
+    "the severity control must expose a form-field name for browser tooling",
+  );
 });