@abide/abide 0.56.0 → 0.57.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # abide
 
+## 0.57.0
+
+### Minor Changes
+
+- d09e821: `errorTtl` — opt a failed RPC load into the negative cache
+
+    By default a failed load evicts immediately so the next read retries. Setting `errorTtl` on an endpoint's `cache` policy (or a producer's `cache()` options) retains the failure for that many milliseconds instead: reads within the window re-surface the same rejection with no network round-trip — backing off a failing or rate-limited backend rather than hammering it — then the entry hard-evicts and the next read retries. The function form `errorTtl: (status) => number | undefined` returns a per-status window (`status` is `0` for a network-level fault), or `undefined` to keep the immediate-retry default for that status (e.g. back off a 429/503, retry a 500 at once). A `Retry-After` response header overrides the configured window as the authoritative delay. A negative-cached error is never shipped in the SSR snapshot, so it can't warm-hydrate a poisoned client entry.
+
+### Patch Changes
+
+- 3ce8963: Fix an async-cell warm-seed ordering bug where a `linked` cell reading a blocking dependency could desync SSR and client
+
+    An async cell's warm-seed key is `${scope.id}:${index}`, where `index` is a per-scope counter drawn in construction order. Only a cell that actually becomes async draws one — and a `linked` seed becomes async (drawing an index) only when it _suspends_ by reading a still-pending blocking dependency, otherwise it resolves synchronously to a plain `state` and drew none. Because a blocking dependency is typically in flight on the server (the `linked` suspends → index drawn) but already warm-adopted on the client (the `linked` resolves synchronously → no index), every async cell declared _after_ the `linked` in the same scope keyed off-by-one across the handoff and warm-adopted the wrong cell's value (e.g. a grid cell rendering the layout string it followed). `linked` now reserves its ordinal on the synchronous path too, so it always occupies exactly one index — the same invariant `computed` already has from its static `async`-function routing — and downstream keys line up on both sides.
+
+- e8fb019: Type a bare no-`await` promise/stream `state.computed` seed as pending (`T | undefined`)
+
+    `state.computed(getRates())` (no `await`) routes to a STREAMING cell at runtime — it peeks `undefined` while pending — but the type-check shadow projected it as the resolved `T`, so an unguarded read (`rates.map(...)`) type-checked yet could hit `undefined` at first paint. It now projects through `$$cellValuePending` (`T | undefined`), matching the runtime and the semantically identical `state.computed(async () => getRates())` form. A blocking `state.computed(await getRates())` (suspends until resolved) and a genuinely sync seed are unchanged.
+
+    Consuming such a cell with `{#await rates}{:then data}` still binds `data` as the RESOLVED value: the shadow's `{#await}` lowering now strips the pending `undefined` off a bare pending-cell subject (mirroring the runtime's `$$awaitSubject`, ADR-0047), so the idiomatic await/then path stays free of `| undefined` noise. Direct reads should guard with `?.`/`??`.
+
 ## 0.56.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.56.0",
+    "version": "0.57.0",
     "type": "module",
     "sideEffects": false,
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",

package/src/lib/server/runtime/snapshotEntryFromCache.ts

@@ -41,6 +41,13 @@ export async function snapshotEntryFromCache(
     if (!response) {
         return undefined
     }
+    /* A failed load never seeds the client: negative caching (errorTtl) can leave an
+       error-status entry in the store at snapshot time, but shipping it would warm-hydrate
+       a poisoned entry. Skip it — the client live-fetches on the miss and runs its own
+       negative cache. (Before errorTtl, errors evicted at settle and never reached here.) */
+    if (!response.ok) {
+        return undefined
+    }
     if (store.entries.get(entry.key) !== entry) {
         return undefined
     }

package/src/lib/shared/cache.ts

@@ -280,8 +280,28 @@ function readThrough<Args, Return>(
         warnEphemeralTtl(key)
     }
     store.subscribe(key)
-    const existing = store.entries.get(key)
+    let existing = store.entries.get(key)
     recordRead(effectiveOptions?.shared ? activeCacheStore() : store, key, existing)
+    /*
+    Negative-cache short-circuit: a prior failed load retained under errorTtl
+    re-surfaces the same failure with no network until its window elapses — a
+    Response is re-served (raw) or re-decoded to throw the same HttpError, a
+    network Error is re-rejected. Past the deadline (the sweep may not have fired
+    yet) evict it here so the read below is a clean miss that retries.
+    */
+    if (existing?.errorResult !== undefined) {
+        if (existing.expiresAt !== undefined && existing.expiresAt > Date.now()) {
+            const failure = existing.errorResult
+            if (failure instanceof Response) {
+                return isRaw
+                    ? (Promise.resolve(failure.clone()) as Promise<Return | Response>)
+                    : (decodeResponse(failure.clone()) as Promise<Return | Response>)
+            }
+            return Promise.reject(failure)
+        }
+        evictIfCurrent(store, existing)
+        existing = undefined
+    }
     if (existing) {
         tagEntry(existing, effectiveOptions?.tags)
         attachPolicy(existing, effectiveOptions, () => remote(args as Args), retain)
@@ -380,6 +400,7 @@ function resolveEndpointCache<Args, Return>(
         shared: policy.shared,
         throttle: policy.throttle,
         debounce: policy.debounce,
+        errorTtl: policy.errorTtl,
     }
 }
 
@@ -565,61 +586,76 @@ function registerEntry(
     function deleteIfCurrent() {
         evictIfCurrent(store, entry)
     }
-    promise.then((result) => {
-        /*
+    promise.then(
+        (result) => {
+            /*
         Mark settled so SSR snapshot serialization can tell awaited entries
         (resolved by the time render() returns → inline) from {#await} ones
         (still pending → stream). Set before the ttl branches below since a
         ttl=0 server entry stays in the store for the snapshot.
         */
-        entry.settled = true
-        /* The reload finished — this entry now holds fresh data, no longer refreshing. */
-        entry.refreshing = false
-        store.markLifecycle(key)
-        /*
+            entry.settled = true
+            /* The reload finished — this entry now holds fresh data, no longer refreshing. */
+            entry.refreshing = false
+            store.markLifecycle(key)
+            /*
         An error-status Response is a failed load, not a value to retain: fetch
         resolves (it only rejects on a network fault) on a 4xx/5xx, so without
         this the entry would be served as a hit for the whole ttl, even after the
-        backend recovers. Evict it so the next read retries — mirroring fireRefetch,
-        which already guards revalidation results with the same `!result.ok` check.
+        backend recovers. Evict it so the next read retries — unless the endpoint
+        opted into the negative cache (errorTtl), which retains the failure for a
+        bounded window (see retainErroredEntry). Mirrors fireRefetch, which guards
+        revalidation results with the same `!result.ok` check.
         */
-        if (result instanceof Response && !result.ok) {
-            deleteIfCurrent()
-            return
-        }
-        /*
+            if (result instanceof Response && !result.ok) {
+                retainErroredEntry(store, entry, options, result.status, result)
+                return
+            }
+            /*
         A post-invalidate reload registers with refreshing=true; an invalidation
         firing while it was in flight parked its refetch on policy.pending
         (fireRefetch bails when refreshing). This settle path — not fireRefetch —
         cleared the flag, so drain the parked refetch here or it's lost and the
         entry keeps data that predates the invalidation.
         */
-        if (entry.invalidation?.pending) {
-            reschedulePendingRefetch(store, entry, entry.invalidation)
-        }
-        /*
+            if (entry.invalidation?.pending) {
+                reschedulePendingRefetch(store, entry, entry.invalidation)
+            }
+            /*
         Smart retained read: the display value is kept unconditionally — never
         hard-evicted on settle. ttl marks a staleness deadline (the next read past
         it revalidates in the background, stale stays visible, refreshing() true)
         instead of eviction; ttl 0/undefined retain with no staleness clock.
         */
-        if (entry.retain) {
-            materializeRetained(store, entry, result)
-            if (ttl !== undefined && ttl > 0) {
-                stampStaleDeadline(entry, ttl)
+            if (entry.retain) {
+                materializeRetained(store, entry, result)
+                if (ttl !== undefined && ttl > 0) {
+                    stampStaleDeadline(entry, ttl)
+                }
+                return
             }
-            return
-        }
-        if (ttl === 0) {
-            if (!keepZeroTtlForRequest) {
-                deleteIfCurrent()
+            if (ttl === 0) {
+                if (!keepZeroTtlForRequest) {
+                    deleteIfCurrent()
+                }
+                return
             }
-            return
-        }
-        if (ttl !== undefined) {
-            armTtlExpiry(store, entry, ttl)
-        }
-    }, deleteIfCurrent)
+            if (ttl !== undefined) {
+                armTtlExpiry(store, entry, ttl)
+            }
+        },
+        (error) => {
+            /* A network-level fault (fetch rejects — no Response, so no status/Retry-After):
+           negative-cache it under the status-0 window if opted in, else evict-and-retry. */
+            retainErroredEntry(
+                store,
+                entry,
+                options,
+                0,
+                error instanceof Error ? error : new Error(String(error)),
+            )
+        },
+    )
     return entry
 }
 
@@ -636,6 +672,75 @@ function evictIfCurrent(store: CacheStore, entry: CacheEntry): void {
     }
 }
 
+/*
+A failed load is retained (negative cache), not evicted, only when the endpoint
+opted in with `errorTtl` for this status — otherwise it evicts so the next read
+retries (the default). With a window the failure is buffered so reads within it
+re-surface it with no network: a Response is stored as a pristine clone the read
+path re-clones per serve (never consuming errorResult itself), a network Error is
+stored as-is and re-rejected. `armTtlExpiry` hard-evicts at the deadline, so the
+next read retries. A `Retry-After` header overrides the configured window as the
+authoritative delay.
+*/
+function retainErroredEntry(
+    store: CacheStore,
+    entry: CacheEntry,
+    options: CacheOptions | undefined,
+    status: number,
+    failure: Response | Error,
+): void {
+    const configured = errorTtlFor(options, status)
+    /* Not opted in for this status → default evict-and-retry (Retry-After is honoured
+       only under an explicit errorTtl, so no existing endpoint's behaviour shifts). */
+    if (configured === undefined) {
+        evictIfCurrent(store, entry)
+        return
+    }
+    const window =
+        failure instanceof Response ? (retryAfterMs(failure.headers) ?? configured) : configured
+    if (window <= 0) {
+        evictIfCurrent(store, entry)
+        return
+    }
+    if (store.entries.get(entry.key) !== entry) {
+        return
+    }
+    entry.errorResult = failure instanceof Response ? failure.clone() : failure
+    entry.settled = true
+    armTtlExpiry(store, entry, window)
+}
+
+/* Resolves the endpoint's `errorTtl` against a failed status: a number applies to
+   any status, a function returns a per-status window (or undefined to keep the
+   immediate-retry default for that status). `status` is 0 for a network fault. */
+function errorTtlFor(options: CacheOptions | undefined, status: number): number | undefined {
+    const policy = options?.errorTtl
+    if (typeof policy === 'function') {
+        return policy(status)
+    }
+    return policy
+}
+
+/* Parses a `Retry-After` header to ms — a delta-seconds integer or an HTTP-date —
+   clamped to >= 0. Returns undefined when absent or unparseable so the caller falls
+   back to the configured errorTtl. */
+function retryAfterMs(headers: Headers): number | undefined {
+    const value = headers.get('retry-after')
+    if (value === null) {
+        return undefined
+    }
+    const seconds = Number(value)
+    if (Number.isFinite(seconds)) {
+        return seconds > 0 ? seconds * 1000 : 0
+    }
+    const when = Date.parse(value)
+    if (Number.isNaN(when)) {
+        return undefined
+    }
+    const delta = when - Date.now()
+    return delta > 0 ? delta : 0
+}
+
 /* Arms the ttl > 0 expiry sweep; `expiresAt` re-checks at fire time so a refreshed deadline survives. */
 function armTtlExpiry(store: CacheStore, entry: CacheEntry, ttl: number): void {
     entry.expiresAt = Date.now() + ttl

package/src/lib/shared/types/CacheEntry.ts

@@ -73,6 +73,15 @@ export type CacheEntry = {
     its drop-on-ttl / drop-on-invalidate behaviour.
     */
     retain?: boolean
+    /*
+    A retained failed load (negative cache — opt in with `errorTtl`). Holds a
+    pristine Response clone (re-served per read by cloning it, never consumed) or
+    the network Error, so reads within the window re-surface the same failure with
+    no network round-trip. `expiresAt` (armed via the ttl sweep) hard-evicts it when
+    the window elapses, so the next read retries. Unset on a successful entry; its
+    presence is what the read path checks to short-circuit to the retained error.
+    */
+    errorResult?: Response | Error
 }
 
 /* Per-key invalidate coalescing: the throttle/debounce policy plus the timer/in-flight state. */

package/src/lib/shared/types/CacheOptions.ts

@@ -31,6 +31,17 @@ and coalesces a background refetch (leading-edge-then-coalesce, or
 fire-after-quiet respectively) instead of dropping the entry. Set one, not both.
 SWR is otherwise unconditional for replayable remote reads; there is no `swr`
 toggle.
+
+`errorTtl` opts a failed load into the negative cache: without it a failure
+evicts immediately so the next read retries (the default); with it, the failure
+is retained for that many ms — reads within the window re-surface the same
+rejection with no network round-trip, backing off a failing/rate-limited backend
+instead of hammering it — then hard-evicts so the next read retries. A function
+form receives the failed response's HTTP status (0 for a network-level fault with
+no response) and returns a per-status window, or `undefined` to fall back to the
+immediate-retry default for that status (e.g. back off a 429/503, retry a 500 at
+once). A `Retry-After` header on the response overrides the number as the
+authoritative delay. Off (evict-and-retry) when unset.
 */
 export type CacheOptions = {
     ttl?: number
@@ -38,4 +49,5 @@ export type CacheOptions = {
     shared?: boolean
     throttle?: number
     debounce?: number
+    errorTtl?: number | ((status: number) => number | undefined)
 }

package/src/lib/shared/types/CachePolicy.ts

@@ -1,10 +1,10 @@
 /*
 Endpoint cache policy, declared once on the rpc definition (ADR-0020). Same value
 shape as the producer-side `CacheOptions` (`ttl` / `tags` / `throttle` / `debounce`
-/ `shared`, no `swr` — SWR is unconditional for replayable reads), except `tags`
-also accepts an arg-derived function so the group can vary by call. That makes the
-type generic over the rpc's `Args`: `(args) => ['rates:' + args.base]` is typed
-against the endpoint's own argument shape.
+/ `shared` / `errorTtl`, no `swr` — SWR is unconditional for replayable reads),
+except `tags` also accepts an arg-derived function so the group can vary by call.
+That makes the type generic over the rpc's `Args`: `(args) => ['rates:' + args.base]`
+is typed against the endpoint's own argument shape.
 
 - `ttl` — retention/staleness in ms. Default Infinity: the entry is retained for its
   store's lifetime — the request on the server (a non-shared read dies with the request,
@@ -15,6 +15,11 @@ against the endpoint's own argument shape.
 - `shared` — opt the entry into the process-level store (never per-user data — the store
   is keyed by method+url+args, not by user). With the default Infinity ttl this memoises
   across requests; an explicit ttl bounds it. A client no-op (one tab store).
+- `errorTtl` — negative-cache window in ms: retain a failed load for that long (reads
+  within it re-surface the rejection with no network) instead of the default
+  evict-and-retry, then hard-evict. A function of the failed status (0 = network fault)
+  returns a per-status window or `undefined` to keep the immediate-retry default for that
+  status; a `Retry-After` header overrides the number. Off when unset.
 */
 export type CachePolicy<Args> = {
     ttl?: number
@@ -22,4 +27,5 @@ export type CachePolicy<Args> = {
     throttle?: number
     debounce?: number
     shared?: boolean
+    errorTtl?: number | ((status: number) => number | undefined)
 }

package/src/lib/ui/compile/compileShadow.ts

@@ -82,7 +82,6 @@ export function compileShadow(
     propsType = 'Record<string, any>',
     classify?: InterpolationClassifier,
 ): CompiledShadow {
-    const builder = createBuilder(classify)
     const leadingScript = source.match(LEADING_SCRIPT)
     const scriptBody = leadingScript?.[1] ?? ''
     /* Body starts just past the opening `<script …>`; template just past `</script>`. */
@@ -98,7 +97,12 @@ export function compileShadow(
         importedReactives,
         propsLocalName,
         watchLocalName,
+        pendingCellNames,
     } = analyzeScript(scriptBody, scriptStart, classify)
+    /* Built AFTER the script analysis so the `pendingCellNames` set (the `$$cellValuePending`
+       cells) can ride onto the builder — the `{#await}` emit reads it to strip a bare
+       pending-cell subject's pending `undefined` off its resolved binding (ADR-0047 fidelity). */
+    const builder = createBuilder(classify, pendingCellNames)
     builder.raw(shadowPreamble(importedReactives))
     /* Every `computed`/`linked` scope line reads through this: it invokes the seed thunk and
        unwraps a promise/stream to the value a BARE cell read peeks (ADR-0019/0032) — so an async
@@ -117,6 +121,14 @@ export function compileShadow(
     builder.raw(
         'declare function $$cellValuePending<R>(seed: () => R): (R extends AsyncIterable<infer F> ? F : Awaited<R>) | undefined\n',
     )
+    /* `{#await <pendingCell>}` awaits the CELL (ADR-0047 `$$awaitSubject`) — it shows pending then
+       binds the RESOLVED value, never the pending `undefined`. So a bare pending-cell subject's
+       resolved/`:then` binding must drop the `| undefined` the `$$cellValuePending` peek carries;
+       `$$awaitCell` strips exactly `undefined` (`Exclude`, so a genuine `null` in the value survives).
+       Emitted only when a pending cell exists (else the `{#await}` emit never references it). */
+    if (pendingCellNames.size > 0) {
+        builder.raw('declare function $$awaitCell<V>(v: V): Exclude<V, undefined>\n')
+    }
     /* The peek helpers the async-interpolation wrap targets (ADR-0032): `$$peek` unwraps a promise
        sub-expression to its resolved value (`undefined` while pending) and `$$peekStream` reads an
        async iterable's latest frame, so `getFoo()?.name`/`{#if getFoo()}` type-check against the
@@ -245,6 +257,9 @@ type Builder = {
     /* A fresh shadow-local binding name (`__<base>_<n>`) — for synthesised bindings
        like an await's resolved value, kept distinct so nested blocks never collide. */
     unique: (base: string) => string
+    /* The `$$cellValuePending` (STREAMING) cells declared in the leading script — a bare
+       `{#await <name>}` over one strips the pending `undefined` off its resolved binding. */
+    pendingCellNames: ReadonlySet<string>
     result: () => CompiledShadow
 }
 
@@ -252,7 +267,10 @@ type Builder = {
    emitted verbatim from the original script), offset-relative to the line start. */
 type ScopeLine = { text: string; segments: ShadowMapping[] }
 
-function createBuilder(classify?: InterpolationClassifier): Builder {
+function createBuilder(
+    classify?: InterpolationClassifier,
+    pendingCellNames: ReadonlySet<string> = new Set(),
+): Builder {
     let code = ''
     let uniqueCounter = 0
     const mappings: ShadowMapping[] = []
@@ -302,6 +320,7 @@ function createBuilder(classify?: InterpolationClassifier): Builder {
         }
     }
     const builder: Builder = {
+        pendingCellNames,
         unique(base) {
             return `__${base}_${uniqueCounter++}`
         },
@@ -379,6 +398,9 @@ type ScriptAnalysis = {
        overload so the `watch(cell, handler)` form type-checks (the cell is projected to its
        value, so the real State/socket/rpc overloads never match it). */
     watchLocalName: string | undefined
+    /* The STREAMING (`$$cellValuePending`) cell names — a bare `{#await <name>}` over one awaits
+       the cell and strips its pending `undefined` for the resolved binding (ADR-0047). */
+    pendingCellNames: Set<string>
 }
 
 /* Pushes a diagnostic for every author binding whose name starts with the reserved `$$`
@@ -506,6 +528,7 @@ function analyzeScript(
     const scope: ScopeLine[] = []
     const propsShapes: string[] = []
     const diagnostics: ShadowDiagnostic[] = []
+    const pendingCellNames = new Set<string>()
     if (scriptBody.trim() === '') {
         return {
             imports,
@@ -516,6 +539,7 @@ function analyzeScript(
             importedReactives: new Set(),
             propsLocalName: undefined,
             watchLocalName: undefined,
+            pendingCellNames,
         }
     }
     const file = ts.createSourceFile('script.ts', scriptBody, ts.ScriptTarget.Latest, true)
@@ -572,7 +596,17 @@ function analyzeScript(
             continue
         }
         for (const declaration of reactive) {
-            scope.push(scopeLineFor(declaration, propsShapes, verbatim, span, bindings, classify))
+            scope.push(
+                scopeLineFor(
+                    declaration,
+                    propsShapes,
+                    verbatim,
+                    span,
+                    bindings,
+                    classify,
+                    pendingCellNames,
+                ),
+            )
         }
     }
     return {
@@ -584,6 +618,7 @@ function analyzeScript(
         importedReactives,
         propsLocalName,
         watchLocalName,
+        pendingCellNames,
     }
 }
 
@@ -710,6 +745,9 @@ function scopeLineFor(
     span: (node: ts.Node, prefixLength: number) => ShadowMapping,
     bindings: ReactiveImportBindings,
     classify?: InterpolationClassifier,
+    /* Collects the names that project through `$$cellValuePending` (STREAMING cells) so the
+       `{#await}` emit can strip their pending `undefined`. Absent for nested scripts. */
+    pendingCellNames?: Set<string>,
 ): ScopeLine {
     const name = ts.isIdentifier(declaration.name) ? declaration.name.text : '_'
     const call = declaration.initializer as ts.CallExpression
@@ -807,12 +845,21 @@ function scopeLineFor(
     const fnIsThunk = ts.isArrowFunction(fn) || ts.isFunctionExpression(fn)
     const wrapPrefix = fnIsThunk ? '' : seedIsAsync(fn) ? 'async () => (' : '() => ('
     const wrapSuffix = fnIsThunk ? '' : ')'
-    /* ADR-0042: a STREAMING promise cell (async seed, no top-level `await`) reads
-       `undefined`-while-pending → `$$cellValuePending` (resolved `T | undefined`). A BLOCKING
-       (`await`) cell suspends its region so it is always resolved, and a sync cell is never pending
-       → `$$cellValue` (resolved `T`). (A bare stream seed keeps `$$cellValue`'s frame type — the
-       pre-existing type-directed case, unchanged here.) */
-    const helper = seedIsAsync(fn) && !seedIsBlocking(fn) ? '$$cellValuePending' : '$$cellValue'
+    /* ADR-0042/0043: a STREAMING cell reads `undefined`-while-pending → `$$cellValuePending`
+       (resolved `T | undefined`). Two seed shapes stream: a no-`await` async thunk (`async () =>
+       x`), and a bare call/identifier whose type resolves to a promise/stream — the latter is what
+       desugarSignals routes to `trackedComputed(…, streaming)` (`isPromiseComputed` /
+       `isEagerStreamComputed`), so the shadow must agree or a `state.computed(getFoo())` reads as
+       non-optional `T` while the runtime peeks `undefined`. A BLOCKING (`await`) cell suspends its
+       region so it is always resolved, and a genuinely sync seed is never pending → `$$cellValue`
+       (resolved `T`). The bare-seed arm needs the warm classifier; fail-open keeps `$$cellValue`. */
+    const streamingSeed =
+        (seedIsAsync(fn) && !seedIsBlocking(fn)) || bareSeedStreams(fn, span, verbatim, classify)
+    const helper = streamingSeed ? '$$cellValuePending' : '$$cellValue'
+    /* Record the pending cell so `{#await <name>}` strips its pending `undefined` (ADR-0047). */
+    if (streamingSeed && ts.isIdentifier(declaration.name)) {
+        pendingCellNames?.add(name)
+    }
     const prefix = `${keyword} ${name}${annotation} = ${helper}(${wrapPrefix}`
     /* Peek-wrap any buried async sub-expression in the seed (ADR-0032, script side) so a bare
        `getSession()?.x ?? []` types as its resolved value — matching the `desugarSignals` lift.
@@ -870,6 +917,31 @@ function seedIsBlocking(seed: ts.Expression): boolean {
     return hasTopLevelAwait(seed)
 }
 
+/* True for a bare (non-thunk, no-`await`) call/identifier seed whose checker type resolves to a
+   promise or async iterable — the STREAMING cell desugarSignals routes to `trackedComputed(…,
+   streaming)` (`isPromiseComputed` / `isEagerStreamComputed`). Such a cell peeks `undefined` while
+   pending, so its shadow type must be `$$cellValuePending` (resolved `T | undefined`), matching the
+   `async () => x` streaming form. Restricted to a bare CALL/IDENTIFIER seed — the whole-seed shape,
+   mirroring desugarSignals' bare-seed routing; a compound seed's buried async sub-expression is
+   peek-wrapped separately. Needs the warm classifier — absent (or on a resolution throw) it returns
+   false, keeping today's `$$cellValue`. */
+function bareSeedStreams(
+    seed: ts.Expression,
+    span: (node: ts.Node, prefixLength: number) => ShadowMapping,
+    verbatim: (node: ts.Node) => string,
+    classify: InterpolationClassifier | undefined,
+): boolean {
+    if (classify === undefined || (!ts.isCallExpression(seed) && !ts.isIdentifier(seed))) {
+        return false
+    }
+    try {
+        const kind = classify(span(seed, 0).sourceStart, verbatim(seed))
+        return kind === 'promise' || kind === 'asyncIterable'
+    } catch {
+        return false
+    }
+}
+
 /* Whether any ELEMENT in the tree carries an `attach` — gates emitting the DOM-typed
    attachment aliases. All nested content (block bodies, await/switch branches, snippet
    bodies) routes through `children`, so a recursive `children` walk is complete. */
@@ -1123,9 +1195,17 @@ function emitNode(node: TemplateNode, builder: Builder): void {
                they're the pending content, checked without the resolved value. */
             const resolved = builder.unique('awaited')
             builder.raw('{\n')
-            builder.raw(`const ${resolved} = await `)
+            /* A bare `{#await <pendingCell>}` awaits the CELL (ADR-0047 `$$awaitSubject`): it shows
+               pending then binds the RESOLVED value, never the pending `undefined` the
+               `$$cellValuePending` peek carries. So strip that `undefined` with `$$awaitCell` — the
+               resolved/`:then` bindings all derive from `resolved`, so one strip covers every one.
+               Only a whole-subject bare pending-cell reference qualifies (mirrors the runtime
+               `awaitSubjectExpr` classification); any other subject (a plain promise, a blocking
+               cell, a compound expression) stays a plain `await`. */
+            const subjectIsPendingCell = builder.pendingCellNames.has(node.promise.trim())
+            builder.raw(`const ${resolved} = ${subjectIsPendingCell ? '$$awaitCell(' : 'await '}`)
             builder.expr(node.promise, node.loc)
-            builder.raw(`;\nvoid ${resolved};\n`)
+            builder.raw(`${subjectIsPendingCell ? ')' : ''};\nvoid ${resolved};\n`)
             const pending = node.children.filter((child) => child.kind !== 'branch')
             const branches = node.children.filter((child) => child.kind === 'branch')
             if (node.blocking && node.as !== undefined) {

package/src/lib/ui/createScope.ts

@@ -85,7 +85,14 @@ export function createScope(
        declaration order — the local half of a cell's serialization-stable warm-seed key
        (`${scope.id}:${index}`, see `createAsyncCell`). Per-scope (not global) so a client-only
        sibling component can't shift another component's cell keys: divergence stays local. Both
-       SSR and client construct a component's cells in the same order, so the indices agree. */
+       SSR and client construct a component's cells in the same order, so the indices agree — but
+       ONLY because every cell that CAN become async draws exactly one index per construction,
+       independent of whether it materializes as async on a given render. `computed` gets this from
+       its static `isAsyncFunction` routing; `linked` decides at runtime (it draws in
+       `createAsyncCell` when its seed suspends, else RESERVES the index in its plain-`state`
+       fall-through), so a `linked` whose blocking dep is in flight on the server but warm on the
+       client still occupies its one slot on both sides. Break that "exactly one per construction"
+       rule and every downstream cell keys off-by-one across the handoff. */
     let cellIndex = 0
 
     /* `cell` and `nextCellIndex` are not on the public `Scope` type — `cell` is the compiler-only

package/src/lib/ui/linked.ts

@@ -1,6 +1,7 @@
 import { isAsyncIterable } from '../shared/isAsyncIterable.ts'
 import type { AsyncState } from '../shared/types/AsyncState.ts'
 import type { NamedAsyncIterable } from '../shared/types/NamedAsyncIterable.ts'
+import { CURRENT_SCOPE } from './runtime/CURRENT_SCOPE.ts'
 import { createAsyncCell } from './runtime/createAsyncCell.ts'
 import { createEffectNode } from './runtime/createEffectNode.ts'
 import { isAsyncFunction } from './runtime/isAsyncFunction.ts'
@@ -8,6 +9,7 @@ import { routeBareSeed } from './runtime/routeBareSeed.ts'
 import { SuspenseSignal } from './runtime/SuspenseSignal.ts'
 import type { State } from './runtime/types/State.ts'
 import { state } from './state.ts'
+import type { Scope } from './types/Scope.ts'
 
 /*
 A writable cell seeded reactively from upstream — the abide form of Angular's
@@ -95,6 +97,19 @@ export function linked<T>(
             transform: coerce,
         }) as AsyncState<T>
     }
+    /* Reserve this cell's async-cell ordinal even though the seed resolved synchronously to a
+       plain `state`. Whether a `linked` seed suspends (→ `createAsyncCell`, which draws a
+       `nextCellIndex()` for its warm-seed key) or resolves synchronously (→ this plain `state`,
+       drawing none) is DATA-dependent, and that data can differ across the SSR→client handoff: a
+       blocking dependency still in flight on the server (→ suspend → async cell → index drawn) is
+       already warm-adopted on the warm client (→ sync resolve → plain state → no index). Without
+       this reserve, every async cell declared AFTER a `linked` in the same scope would key
+       off-by-one between sides and adopt the wrong warm seed. Drawing the index here makes a
+       `linked` ALWAYS occupy exactly one ordinal — the invariant `computed` gets for free from its
+       static `isAsyncFunction` routing — so downstream keys align regardless of which path ran. A
+       detached cell (no scope) never warm-seeds, so it draws nothing, mirroring `createAsyncCell`. */
+    const scope = CURRENT_SCOPE.current as (Scope & { nextCellIndex: () => number }) | undefined
+    scope?.nextCellIndex()
     /* The cell is a plain `state` — same store, same write path, so `transform` gates
        reseeds and explicit writes identically. */
     const cell = state<T>(undefined as T, transform)