@abide/abide 0.53.0 → 0.54.0

package/src/lib/shared/cache.ts

@@ -920,26 +920,27 @@ cached list). The next value is stored onto `entry.value`, which the read path
 serves warm (cloned per read), so it persists across reads until a refresh /
 invalidate replaces the entry. `current` comes from `entry.value` when already
 materialized, else decoded from the settled/in-flight promise (async — readers
-re-render when the patch lands). Follows the selector grammar, but only fn / args
-/ tags select a value to mutate; a not-yet-read key has nothing to patch.
+re-render when the amend lands). Follows the selector grammar, but only fn / args
+/ tags select a value to mutate; a not-yet-read key has nothing to amend.
 */
-function patch<Args, Return>(
+function amend<Args, Return>(
     arg: CacheSelector<Args, Return>,
     args: Args | undefined,
     updater: (current: Return) => Return,
+    isValue: boolean,
 ): void {
     const prefix = selectorPrefix(arg, args)
     const matches = selectorMatcher(arg, args, prefix)
     for (const store of cacheStores()) {
         for (const entry of store.entries.values()) {
             if (matches(entry)) {
-                applyPatch(store, entry, updater as (current: unknown) => unknown)
+                applyAmend(store, entry, updater as (current: unknown) => unknown, isValue)
             }
         }
     }
 }
 
-cache.patch = patch
+cache.amend = amend
 
 /*
 Synchronous, non-triggering value probe: returns the currently-retained value for
@@ -947,7 +948,7 @@ a call, or undefined when nothing is retained (no entry, or not yet settled). Ne
 invokes — reading it opens no fetch. Reactive: it subscribes the key AND taps the
 key's lifecycle channel (the exact key is a one-entry prefix, same as
 pending(fn, args)) so a state.computed / on / template scope re-runs both when the
-value changes (invalidate, patch) and when a retained value lands —
+value changes (invalidate, amend) and when a retained value lands —
 materializeRetained's async decode signals only markLifecycle, no invalidate event,
 so without the lifecycle tap a scope that read undefined would never see the value
 arrive. Outside a tracking scope it is a one-shot snapshot. Returns a clone (like
@@ -1003,21 +1004,26 @@ function peek<Args, Return>(
 cache.peek = peek
 
 /*
-Applies one entry's patch: materialize the current decoded value (warm value if
+Applies one entry's amend: materialize the current decoded value (warm value if
 present, else decode the promise — a Response for a remote entry, cloned so the
 readers' own clones still succeed), run the updater, store it warm, and emit so
-readers re-read. Fire-and-forget on the async branch: patch() stays sync-return.
+readers re-read. Fire-and-forget on the async branch: amend() stays sync-return.
 */
-function applyPatch(
+function applyAmend(
     store: CacheStore,
     entry: CacheEntry,
     updater: (current: unknown) => unknown,
+    isValue: boolean,
 ): void {
     function apply(current: unknown): void {
         entry.value = updater(current)
         notify(store, [entry.key], [entry.key])
     }
-    if (entry.value !== undefined) {
+    /* A value-form amend is current-independent (its updater ignores the argument), so set it
+       directly and synchronously like the wire path (amendByKey) — never defer to the in-flight
+       promise. Deferring would drop the value if that fetch rejects (the reject handler below
+       swallows it), diverging local value-amend from the broadcast receive path. */
+    if (isValue || entry.value !== undefined) {
         apply(entry.value)
         return
     }
@@ -1030,6 +1036,25 @@ function applyPatch(
     currentValue.then(apply, () => undefined)
 }
 
+/*
+Wire-driven value apply (ADR-0043): set the retained value of the entry at an exact
+cache key and re-render its readers — the receive half of a server amend broadcast. A
+direct set, not the applyAmend materialize-current dance: the frame carries the
+authoritative value now, and the receiving subscriber is by construction reading this
+key. A key with no local entry is a no-op (nothing to amend).
+*/
+function amendByKey(key: string, value: unknown): void {
+    for (const store of cacheStores()) {
+        const entry = store.entries.get(key)
+        if (entry !== undefined) {
+            entry.value = value
+            notify(store, [entry.key], [entry.key])
+        }
+    }
+}
+
+cache.amendByKey = amendByKey
+
 /*
 Event-driven cache maintenance: subscribes to a NamedAsyncIterable (socket or rpc
 stream) and runs `handler` once per frame — the declarative home for "this

package/src/lib/shared/cacheReaderSocketSlot.ts

@@ -0,0 +1,11 @@
+import { createResolverSlot } from './createResolverSlot.ts'
+import type { CacheReaderHook } from './types/CacheReaderHook.ts'
+
+/*
+Client-only seam for the reactive-reader lifecycle (ADR-0043). No fallback: unresolved,
+get() is undefined and the store's engage/disengage calls are inert — so the server's
+request store and isolated unit tests do nothing. The client entry (startClient) installs
+a hook that opens a per-key amend value subscription on a key's first reader and closes it
+on its last, keeping the subscription set congruent with what this tab is reading.
+*/
+export const cacheReaderSocketSlot = createResolverSlot<CacheReaderHook>()

package/src/lib/shared/createCacheStore.ts

@@ -1,4 +1,5 @@
 import { REACTIVE_CONTEXT } from '../ui/runtime/REACTIVE_CONTEXT.ts'
+import { cacheReaderSocketSlot } from './cacheReaderSocketSlot.ts'
 import { createLifecycleChannel } from './createLifecycleChannel.ts'
 import { createSubscriber } from './createSubscriber.ts'
 import { keyMatchesPrefix } from './keyMatchesPrefix.ts'
@@ -62,10 +63,17 @@ export function createCacheStore(): CacheStore {
                        Drop the marker so the tab-scoped store can't accrete one per
                        invalidated-but-never-reread key over a session. */
                     pendingRefresh.delete(key)
+                    /* Last reader gone: close any per-key amend subscription opened on engage
+                       (ADR-0043). Inert unless the client entry installed the hook. */
+                    cacheReaderSocketSlot.get()?.disengage(key)
                 }
             }
         })
         subscribers.set(key, registered)
+        /* First reader for this key: open a per-key amend value subscription (ADR-0043), so a
+           server amend(args, value) push lands on a key this tab is actually reading. Inert on
+           the server / in unit tests (slot unresolved). Paired with disengage in the cleanup. */
+        cacheReaderSocketSlot.get()?.engage(key)
         registered()
     }
 

package/src/lib/shared/peek.ts

@@ -8,7 +8,7 @@ import type { Socket } from './types/Socket.ts'
 The value member of the probe family: the currently-retained value, synchronously,
 without triggering anything — `T | undefined` (undefined when nothing is retained
 yet). For a cached read it is the retained cache value (reactive in a tracking
-scope — re-runs when a refresh lands or a patch mutates it; a one-shot snapshot
+scope — re-runs when a refresh lands or an amend mutates it; a one-shot snapshot
 otherwise). For a subscribable (socket / stream) it is the latest frame, read off
 the source's own `.peek()`. Instance sugar `getFoo.peek(args?)` ≡ `peek(getFoo,
 args?)`, `socket.peek()` ≡ `peek(socket)`.

package/src/lib/shared/socketTailsSlot.ts

@@ -0,0 +1,13 @@
+import { createResolverSlot } from './createResolverSlot.ts'
+import type { SocketTails } from './types/SocketTails.ts'
+
+/*
+The active socket-tail slot — mirrors `resolvedCellsSlot`, but deliberately WITHOUT a lazily-created
+shared fallback. `defineSocket`'s server `peek()` records into it on every retained-frame read, and a
+socket peeked outside a request (a ws message handler, boot, cron) has no request store — a shared
+fallback would then accumulate entries no page render ever drains, a slow leak. With no fallback,
+`get()` returns undefined off-request and the record is skipped. During an SSR render the server
+entry's resolver returns the request store's list, which `createUiPageRenderer` drains into
+`__SSR__.sockets`.
+*/
+export const socketTailsSlot = createResolverSlot<SocketTails>()

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

@@ -0,0 +1,15 @@
+import type { CacheSelector } from './CacheSelector.ts'
+
+/*
+The side-swappable applier stored in amendBroadcastSlot (ADR-0043). Given a selector,
+its args, whether the payload is a concrete value (vs. an updater closure), and the
+payload itself, either apply it to this side's store (client / fallback) or broadcast
+the keyed value to every authorized reader (server). Only the value form is
+broadcastable; the server resolver throws on an updater (a closure has no wire form).
+*/
+export type AmendApply = <Args, Return>(
+    selector: CacheSelector<Args, Return>,
+    args: Args | undefined,
+    isValue: boolean,
+    payload: Return | ((current: Return) => Return),
+) => void

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

@@ -0,0 +1,11 @@
+/*
+The client-installed reactive-reader lifecycle hook stored in cacheReaderSocketSlot
+(ADR-0043). The cache store calls engage(key) when a key gains its first live reader
+and disengage(key) when it loses its last, so the client can open/close a per-key
+amend value subscription whose lifetime tracks "a reader is holding this key on
+screen". Inert (slot unresolved) on the server and in isolated unit tests.
+*/
+export interface CacheReaderHook {
+    engage(key: string): void
+    disengage(key: string): void
+}

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

@@ -71,7 +71,7 @@ export type RemoteFunction<
        reloads lazily, while `refresh(args?)` REFETCHES now keeping the stale value visible — both
        apply locally on the client and broadcast to every connected client from the server.
        `peek(args?)` reads the retained value synchronously (a streaming rpc peeks its latest
-       frame). `patch` is fetch-only, so it is omitted for a streaming rpc (a stream isn't a
+       frame). `amend` is fetch-only, so it is omitted for a streaming rpc (a stream isn't a
        memoized value) via the intersection below. */
     pending(args?: Args): boolean
     refreshing(args?: Args): boolean
@@ -84,22 +84,33 @@ export type RemoteFunction<
        shadow the server `error()` thrower). Reads the rpc error registry captured at the call
        boundary; the cache is untouched. */
     error(args?: Args): RpcError<Errors> | undefined
-    /* Client-only reaction sugar: `fn.watch(handler)` / `fn.watch(args, handler)` ≡
-       `watch(fn, …)` — runs the smart read reactively and pipes each resolved value to the
-       handler, returning a scope-tied disposer. Reaction is a client concern (`watch` is a ui
-       primitive), so this is an inert no-op server-side; an author `fn.watch(…)` surviving the
-       SSR effect-strip (which leaves member calls intact) is a safe no-op there. The real method
-       is attached client-side by remoteProxy. */
-    watch(handler: (value: Return) => void): () => void
-    watch(args: Args, handler: (value: Return) => void): () => void
-} /* `patch` is fetch-only: a streaming rpc has no single memoized value to mutate, so the
-     method is present only when `Return` is not an AsyncIterable. Two signatures: with args
-     (`patch(args, updater)`) and without (`patch(updater)` — every args-variant). Tuple-wrapped
-     so the conditional doesn't distribute over a `never` Return (an error-only rpc). */ & ([
-        Return,
-    ] extends [AsyncIterable<unknown>]
-        ? Record<never, never>
+} /* Client-only reaction sugar: `fn.watch(handler)` / `fn.watch(args, handler)` ≡ `watch(fn, …)`
+     — runs the smart read reactively and pipes each resolved value to the handler, returning a
+     scope-tied disposer. Inert no-op server-side (reaction is a ui concern; the real method is
+     attached client-side by remoteProxy). The keyed overload collapses away for a no-input rpc
+     (`undefined extends Args`) — there is no key to scope to (ADR-0043 §5, type-only). */ & (undefined extends Args
+        ? {
+              watch(handler: (value: Return) => void): () => void
+          }
         : {
-              patch(args: Args | undefined, updater: (current: Return) => Return): void
-              patch(updater: (current: Return) => Return): void
-          })
+              watch(handler: (value: Return) => void): () => void
+              watch(args: Args, handler: (value: Return) => void): () => void
+          }) /* `amend` is fetch-only: a streaming rpc has no single memoized value to mutate, so the
+     method is present only when `Return` is not an AsyncIterable. The last argument is a
+     replacement `Return` value (broadcastable — ADR-0043) or an updater `(current) => Return`
+     (a local closure). For a keyed rpc the value/updater takes the args key first; the bare
+     `amend(updater)` covers every args-variant (local-only). For a no-input rpc the key
+     collapses away (`amend(value)` / `amend(updater)`). Tuple-wrapped so the conditional
+     doesn't distribute over a `never` Return (an error-only rpc). */ &
+    ([Return] extends [AsyncIterable<unknown>]
+        ? Record<never, never>
+        : undefined extends Args
+          ? {
+                amend(value: Return): void
+                amend(updater: (current: Return) => Return): void
+            }
+          : {
+                amend(args: Args, value: Return): void
+                amend(args: Args, updater: (current: Return) => Return): void
+                amend(updater: (current: Return) => Return): void
+            })

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

@@ -0,0 +1,13 @@
+/*
+The per-request list of retained socket frames read via `peek(socket)` during an SSR render, each
+keyed by the socket's name. `defineSocket`'s server `peek()` pushes an entry when a retained frame is
+read server-side; the page renderer stamps them into `__SSR__.sockets` (ref-json-encoded, last write
+per name winning) so the client seeds the socket's latest frame WARM — a not-yet-connected client's
+`peek(socket)` then returns the same retained value the SSR render committed to instead of `undefined`,
+which would otherwise diverge from the server HTML and trip a hydration desync. Sibling of
+`ResolvedCells` — sockets carry a server value forward like cells, not withhold on the client like
+cache (whose server peek is uniformly undefined).
+*/
+export type SocketTails = {
+    entries: { name: string; value: unknown }[]
+}

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

@@ -27,4 +27,10 @@ export type SsrPayload = SsrBootState & {
        write to each slot adopts the server value, so a plain `state(uuid())`/`state(Date.now())`
        keeps the SSR value instead of recomputing a divergent one. */
     docs?: Record<string, string>
+    /* Retained socket frames read via `peek(socket)` during SSR, keyed by socket name → ref-json
+       string. `startClient` seeds these into `SOCKET_SEED`; a hydrating `socketProxy` adopts the frame
+       as its `lastFrame` so `peek(socket)` returns the SAME retained value the server rendered instead
+       of `undefined` on the not-yet-connected client — otherwise the two disagree and hydration
+       discards the server markup. */
+    sockets?: Record<string, string>
 }

package/src/lib/test/createTestApp.ts

@@ -47,6 +47,7 @@ import { pendingAsyncCellsSlot } from '../shared/pendingAsyncCellsSlot.ts'
 import { resolvedCellsSlot } from '../shared/resolvedCellsSlot.ts'
 import { SOCKETS_PATH } from '../shared/SOCKETS_PATH.ts'
 import { sharedCacheStoreSlot } from '../shared/sharedCacheStoreSlot.ts'
+import { socketTailsSlot } from '../shared/socketTailsSlot.ts'
 import { streamedCellsSlot } from '../shared/streamedCellsSlot.ts'
 import type { RemoteFunction } from '../shared/types/RemoteFunction.ts'
 import type { Socket } from '../shared/types/Socket.ts'
@@ -111,6 +112,7 @@ export async function createTestApp(): Promise<TestApp> {
         pendingAsyncCellsResolver: pendingAsyncCellsSlot.resolver,
         resolvedCellsResolver: resolvedCellsSlot.resolver,
         streamedCellsResolver: streamedCellsSlot.resolver,
+        socketTailsResolver: socketTailsSlot.resolver,
         docSnapshotsResolver: docSnapshotsSlot.resolver,
         activeServer: serverSlot.active,
         pageRender: pageRenderSlot.render,
@@ -129,6 +131,9 @@ export async function createTestApp(): Promise<TestApp> {
     const sharedStreamedCells = { entries: [] }
     streamedCellsSlot.resolver = () =>
         requestContext.getStore()?.streamedCells ?? sharedStreamedCells
+    /* No shared fallback — mirrors serverEntry: `defineSocket.peek` records off-request too, so a
+       fallback would leak. Off-request this resolves undefined and the record is skipped. */
+    socketTailsSlot.resolver = () => requestContext.getStore()?.socketTails
     const sharedDocSnapshots = { entries: [] }
     docSnapshotsSlot.resolver = () => requestContext.getStore()?.docSnapshots ?? sharedDocSnapshots
     pageSlot.resolver = resolvePageSnapshot
@@ -218,6 +223,7 @@ export async function createTestApp(): Promise<TestApp> {
         pendingAsyncCellsSlot.resolver = previous.pendingAsyncCellsResolver
         resolvedCellsSlot.resolver = previous.resolvedCellsResolver
         streamedCellsSlot.resolver = previous.streamedCellsResolver
+        socketTailsSlot.resolver = previous.socketTailsResolver
         docSnapshotsSlot.resolver = previous.docSnapshotsResolver
         serverSlot.active = previous.activeServer
         pageRenderSlot.render = previous.pageRender

package/src/lib/ui/amendReaderHook.ts

@@ -0,0 +1,125 @@
+import { AMEND_TOPIC_PREFIX } from '../shared/AMEND_TOPIC_PREFIX.ts'
+import { abideLog } from '../shared/abideLog.ts'
+import { cache } from '../shared/cache.ts'
+import { SocketDisconnectedError } from '../shared/SocketDisconnectedError.ts'
+import type { CacheReaderHook } from '../shared/types/CacheReaderHook.ts'
+import type { Socket } from '../shared/types/Socket.ts'
+import { socketProxy } from './socketProxy.ts'
+
+/* A cache key is a broadcastable amend target only when it carries cross-client wire
+   identity — a remote call key (`METHOD /url…`, per keyForRemoteCall). Producer keys
+   (per-process reference ids) and anything else can't be pushed across clients, so we
+   never open a subscription for them. */
+const REMOTE_KEY = /^(?:GET|POST|PUT|PATCH|DELETE|HEAD) \//
+
+/*
+The client-only reactive-reader lifecycle hook (ADR-0043) installed into
+cacheReaderSocketSlot by startClient. When a remote key gains its first live reader it
+opens a subscription to that call's reserved amend topic and folds each pushed value
+into the cache; when the key loses its last reader it closes the subscription — so the
+set of subscribed topics stays congruent with the set of keys this tab is reading (and
+therefore already authorized for). Refcounted per key so co-readers (or the active/shared
+store both reporting a reader) share one subscription.
+
+The channel is live-only (no tail): a value pushed while this tab was disconnected is
+missed, so on a transport loss the hook re-opens a fresh live iterator AND refreshes the
+key — the ADR-0043 convergence rule, reconciling against authoritative server state
+rather than leaving a silently-stale value. `openSocket` is injectable so a test can drive
+frames over its own channel without a live ws.
+*/
+export function createAmendReaderHook(
+    openSocket: (name: string) => Socket<unknown> = socketProxy,
+): { hook: CacheReaderHook; dispose: () => void } {
+    const open = new Map<string, { readers: number; dispose: () => void }>()
+
+    function subscribe(key: string): () => void {
+        const socket = openSocket(AMEND_TOPIC_PREFIX + key)
+        const controller = new AbortController()
+        /* Opening the shared ws channel must never propagate into the cache read that engaged
+           this key — a read can't fail because an optional real-time subscription couldn't open
+           (e.g. no ws transport). Log and give up on this key's push channel; SWR still holds. */
+        let iterator: AsyncIterator<unknown>
+        try {
+            iterator = socket[Symbol.asyncIterator]()
+        } catch (error) {
+            abideLog.error(error)
+            return () => undefined
+        }
+        ;(async () => {
+            while (!controller.signal.aborted) {
+                let next: IteratorResult<unknown>
+                try {
+                    next = await iterator.next()
+                } catch (error) {
+                    if (controller.signal.aborted) {
+                        return
+                    }
+                    /* Transport loss: reconcile the possibly-missed value against server truth,
+                       then re-open a fresh LIVE subscription (no replay) and keep going. */
+                    if (error instanceof SocketDisconnectedError) {
+                        cache.refreshMatching((entry) => entry.key === key, key, undefined)
+                        try {
+                            iterator = socket[Symbol.asyncIterator]()
+                        } catch (reopenError) {
+                            abideLog.error(reopenError)
+                            return
+                        }
+                        continue
+                    }
+                    abideLog.error(error)
+                    return
+                }
+                if (controller.signal.aborted || next.done === true) {
+                    return
+                }
+                /* One malformed frame must not tear down the live pipe. Frames come only from the
+                   trusted server (clientPublish is false), so this is defense in depth. */
+                try {
+                    cache.amendByKey(key, next.value)
+                } catch (error) {
+                    abideLog.error(error)
+                }
+            }
+        })()
+        return () => {
+            controller.abort()
+            iterator.return?.(undefined)?.catch(() => undefined)
+        }
+    }
+
+    const hook: CacheReaderHook = {
+        engage(key) {
+            if (!REMOTE_KEY.test(key)) {
+                return
+            }
+            const existing = open.get(key)
+            if (existing) {
+                existing.readers += 1
+                return
+            }
+            open.set(key, { readers: 1, dispose: subscribe(key) })
+        },
+        disengage(key) {
+            const existing = open.get(key)
+            if (existing === undefined) {
+                return
+            }
+            existing.readers -= 1
+            if (existing.readers <= 0) {
+                existing.dispose()
+                open.delete(key)
+            }
+        },
+    }
+
+    /* Tear down every open subscription — for the startClient disposer, in case reads are
+       still mounted when the whole client is torn down (e.g. a test harness). */
+    function dispose(): void {
+        for (const entry of open.values()) {
+            entry.dispose()
+        }
+        open.clear()
+    }
+
+    return { hook, dispose }
+}

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

@@ -0,0 +1,38 @@
+import { createShadowProgram, type ShadowProgram } from './createShadowProgram.ts'
+
+/*
+Get-or-build the warm shadow program for a project root, cached once per root and shared by
+the interpolation and seed classifiers (whichever is requested first for a root warms it; the
+other reuses it). The shadow program is what makes type-directed async detection possible —
+resolving whether `{getFoo()}` is a promise/stream and lifting it to a streaming/blocking cell.
+
+On a build FAILURE the program is cached as `undefined` and the classifiers degrade to today's
+plain-value / syntactic behavior — the build never breaks. But the failure is WARNED once per
+root: a silent `undefined` disables type-directed async detection for EVERY component in the
+root, so a broken tsconfig would otherwise ship a bare `{getFoo()}` as the literal
+`[object Promise]` text with no signal at all. The warn fires once (guarded by `cache.has`), so
+the two classifiers sharing a cache never double-report.
+
+`build` is injectable so the warn-once path is testable without a broken project on disk;
+callers pass nothing and get `createShadowProgram`.
+*/
+export function cachedShadowProgram(
+    cache: Map<string, ShadowProgram | undefined>,
+    root: string,
+    build: (root: string) => ShadowProgram = createShadowProgram,
+): ShadowProgram | undefined {
+    if (!cache.has(root)) {
+        try {
+            cache.set(root, build(root))
+        } catch (error) {
+            cache.set(root, undefined)
+            const detail = error instanceof Error ? error.message : String(error)
+            console.warn(
+                `[abide] couldn't build the type program for ${root}: ${detail}\n` +
+                    '  type-directed async detection is disabled for this project — a bare promise/stream\n' +
+                    '  read like {getFoo()} renders as text instead of streaming. Check the tsconfig.',
+            )
+        }
+    }
+    return cache.get(root)
+}

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

@@ -29,8 +29,15 @@ export function compileComponent(
        a direct caller (tests) omits it and the front-end runs here — threading `classify` and
        `seedClassify` so type-directed interpolation + cell lowering happen on this path too. */
     const resolved = analyzed ?? analyzeComponent(source, scopeSeed, classify, seedClassify)
-    const { script, stateNames, derivedNames, computedNames, cellReadNames, blockingCellNames, nodes } =
-        resolved
+    const {
+        script,
+        stateNames,
+        derivedNames,
+        computedNames,
+        cellReadNames,
+        blockingCellNames,
+        nodes,
+    } = resolved
     const build = generateBuild(
         nodes,
         'host',

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

@@ -36,6 +36,24 @@ function wrapSeed(argument: ts.Expression): ts.Expression {
     )
 }
 
+/* Wraps a seed expression as an async unwrapping thunk `async () => await (arg)` — for a
+   type-directed PROMISE seed (ADR-0023/0043) the author wrote WITHOUT `await`
+   (`state.computed(getFoo())`). The `async`+`await` makes createAsyncCell unwrap the resolved
+   value; a plain `() => getFoo()` thunk would fall to trackedComputed's lazy opaque path (its
+   probe self-identifies only a stream, never a promise). The parens keep a comma/ternary seed
+   a single await operand. Distinct from `wrapSeed`, which only makes the arrow async when the
+   arg already carries a top-level `await`. */
+function wrapAwaitSeed(argument: ts.Expression): ts.Expression {
+    return factory.createArrowFunction(
+        [factory.createModifier(ts.SyntaxKind.AsyncKeyword)],
+        undefined,
+        [],
+        undefined,
+        factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+        factory.createAwaitExpression(factory.createParenthesizedExpression(argument)),
+    )
+}
+
 /* True for an async seed thunk — an arrow/function carrying the `async` modifier, whether
    from `wrapSeed`'s `await` lowering or a passthrough `async () => …` literal the author
    wrote. The routing signal: an async seed becomes an async cell (read via `$$readCell`),
@@ -275,6 +293,21 @@ export function desugarSignals(
         }
         return isBareCallComputed(declaration)
     }
+    /* A type-directed PROMISE seed (ADR-0023/0043): a no-`await` `state.computed(getFoo())` whose
+       seed's checker type resolves to a promise. Routed to an eager STREAMING async cell that
+       unwraps the resolved value and reactively re-resolves when its tracked deps change — the
+       script-level twin of a bare async interpolation (ADR-0032). Only fires with a warm classifier
+       ('promise'); fail-open (no program) leaves it to `isEagerStreamComputed`'s bare-call probe,
+       and the `await`-marker seed is excluded (its wrapped thunk is already async). Kept separate
+       from `isEagerStreamComputed` so `computedStatements` can wrap it as `async () => await (seed)`
+       (a stream seed stays a bare probe thunk). */
+    const isPromiseComputed: EagerStreamPredicate = (declaration) => {
+        const argument = seedArgument(declaration)
+        if (argument === undefined || isAsyncSeed(wrapSeed(argument))) {
+            return false
+        }
+        return seedKind(argument) === 'promise'
+    }
     for (const statement of source.statements) {
         if (!ts.isVariableStatement(statement)) {
             continue
@@ -321,9 +354,15 @@ export function desugarSignals(
                    `name()` (a sync/promise seed), or an eager cell read via `$$readCell(name)`
                    when the wrapped seed is async (an `await`-lowered / passthrough-`async` thunk)
                    or its seed type resolves to a stream (`isEagerStreamComputed`, ADR-0023). */
-                if (isAsyncComputed(declaration) || isEagerStreamComputed(declaration)) {
+                if (
+                    isAsyncComputed(declaration) ||
+                    isEagerStreamComputed(declaration) ||
+                    isPromiseComputed(declaration)
+                ) {
                     cellReadNames.add(declaration.name.text)
-                    /* A blocking async computed (author `await`) reads suspend-on-pending. */
+                    /* A blocking async computed (author `await`) reads suspend-on-pending; a bare
+                       promise (isPromiseComputed) carries no `await` → streaming, so isBlockingSeed
+                       is false and it never joins this set. */
                     const argument = seedArgument(declaration)
                     if (argument !== undefined && isBlockingSeed(argument)) {
                         scriptBlockingNames.add(declaration.name.text)
@@ -389,6 +428,7 @@ export function desugarSignals(
                     blockingCellNames,
                     writtenNames,
                     isEagerStreamComputed,
+                    isPromiseComputed,
                 ),
             )
         }
@@ -417,12 +457,19 @@ function loweredStatement(
     blockingCellNames: ReadonlySet<string>,
     writtenNames: ReadonlySet<string>,
     isEagerStreamComputed: EagerStreamPredicate,
+    isPromiseComputed: EagerStreamPredicate,
 ): ts.Statement[] {
     rejectMixedDeclaration(statement, bindings)
     return (
         injectedComputedStatements(statement, injectedCellNames, blockingCellNames) ??
         stateAssignmentStatements(statement, bindings) ??
-        computedStatements(statement, bindings, signalNames, isEagerStreamComputed) ??
+        computedStatements(
+            statement,
+            bindings,
+            signalNames,
+            isEagerStreamComputed,
+            isPromiseComputed,
+        ) ??
         propsStatements(statement, bindings, writtenNames) ??
         cellStatements(statement, bindings, signalNames) ?? [statement]
     )
@@ -613,6 +660,7 @@ function computedStatements(
     bindings: ReactiveImportBindings,
     signalNames: ReadonlySet<string>,
     isEagerStreamComputed: EagerStreamPredicate,
+    isPromiseComputed: EagerStreamPredicate,
 ): ts.Statement[] | undefined {
     if (!ts.isVariableStatement(statement)) {
         return undefined
@@ -659,6 +707,23 @@ function computedStatements(
                     ]),
                 ),
             )
+        } else if (argument !== undefined && isPromiseComputed(declaration)) {
+            /* Type-directed PROMISE seed (ADR-0023/0043): a bare `state.computed(getFoo())` whose
+               seed resolves to a promise. Wrap it as `async () => await (seed)` so createAsyncCell
+               unwraps the resolved value — a plain `() => getFoo()` thunk would fall to
+               trackedComputed's lazy opaque path (its probe self-identifies only a stream). Passed
+               `streaming: true` (the `true` arg): no author `await` → it does NOT join the SSR
+               blocking barrier — the shell ships pending and the client resolves + reactively
+               re-resolves, the ADR-0032 no-await tier. `await getFoo()` stays the BLOCKING form. */
+            statements.push(
+                constDeclaration(
+                    name,
+                    scopeMethodCall('trackedComputed', [
+                        wrapAwaitSeed(argument),
+                        factory.createTrue(),
+                    ]),
+                ),
+            )
         } else if (isEagerStreamComputed(declaration)) {
             /* Stream seed → the eager `trackedComputed`, which probes the seed and auto-tracks a
                stream (`AsyncComputed`) or falls back to a lazy computed; read via `$$readCell`.