@abide/abide 0.57.1 → 0.100.0

package/src/lib/test/createScriptedSurface.ts

@@ -1,45 +0,0 @@
-import type { ToolResult } from '../mcp/types/ToolResult.ts'
-import type { AgentSurface } from '../server/agent.ts'
-
-type ScriptedTool = {
-    name: string
-    description?: string
-    inputSchema?: Record<string, unknown>
-    /* Result handed back to the engine; throw to simulate a failed dispatch. */
-    result: (args: Record<string, unknown> | undefined) => ToolResult
-}
-
-type RecordedCall = { name: string; args: Record<string, unknown> | undefined }
-
-/*
-A scripted AgentSurface for engine tests: declarative tool stubs in, an MCP
-surface out, with every `call` recorded so a test can assert exactly which
-tools an engine dispatched and with what arguments. Prompts and resources are
-empty — engines must tolerate an app exposing none.
-*/
-// @documentation plumbing
-export function createScriptedSurface(
-    tools: ScriptedTool[] = [],
-): AgentSurface & { calls: RecordedCall[] } {
-    const calls: RecordedCall[] = []
-    return {
-        calls,
-        tools: tools.map((tool) => ({
-            name: tool.name,
-            description: tool.description ?? tool.name,
-            inputSchema: tool.inputSchema ?? { type: 'object' },
-        })),
-        async call(name, args) {
-            calls.push({ name, args })
-            const tool = tools.find((candidate) => candidate.name === name)
-            if (!tool) {
-                return { content: [{ type: 'text', text: `unknown tool: ${name}` }], isError: true }
-            }
-            return tool.result(args)
-        },
-        prompts: [],
-        getPrompt: () => [],
-        listResources: async () => [],
-        readResource: async () => undefined,
-    }
-}

package/src/lib/test/createTestApp.ts

@@ -1,242 +0,0 @@
-import type { Server } from 'bun'
-// @ts-expect-error virtual module resolved by abideResolverPlugin
-import * as appMod from '../../_virtual/app.ts'
-// @ts-expect-error virtual module resolved by abideResolverPlugin
-import { appInfo } from '../../_virtual/app-info.ts'
-// @ts-expect-error virtual module resolved by abideResolverPlugin
-import { assets } from '../../_virtual/assets.ts'
-// @ts-expect-error virtual module resolved by abideResolverPlugin
-import cliProgramName from '../../_virtual/cli-name.ts'
-// @ts-expect-error virtual module resolved by abideResolverPlugin
-import { layouts } from '../../_virtual/layouts.ts'
-// @ts-expect-error virtual module resolved by abideResolverPlugin
-import mcp from '../../_virtual/mcp.ts'
-// @ts-expect-error virtual module resolved by abideResolverPlugin
-import { mcpResources } from '../../_virtual/mcp-resources.ts'
-// @ts-expect-error virtual module resolved by abideResolverPlugin
-import { pages } from '../../_virtual/pages.ts'
-// @ts-expect-error virtual module resolved by abideResolverPlugin
-import { prompts } from '../../_virtual/prompts.ts'
-// @ts-expect-error virtual module resolved by abideResolverPlugin
-import { publicAssets } from '../../_virtual/public-assets.ts'
-// @ts-expect-error virtual module resolved by abideResolverPlugin
-import { rpc } from '../../_virtual/rpc.ts'
-// @ts-expect-error virtual module resolved by abideResolverPlugin
-import { shell } from '../../_virtual/shell.ts'
-// @ts-expect-error virtual module resolved by abideResolverPlugin
-import { sockets } from '../../_virtual/sockets.ts'
-import { rpcRegistry } from '../server/rpc/rpcRegistry.ts'
-import { broadcastCacheStaleness } from '../server/runtime/cacheStalenessBroadcaster.ts'
-import { createServer } from '../server/runtime/createServer.ts'
-import { pageRenderSlot } from '../server/runtime/pageRenderSlot.ts'
-import { ensureRegistriesLoaded } from '../server/runtime/registryManifests.ts'
-import { requestContext } from '../server/runtime/requestContext.ts'
-import { resolvePageSnapshot } from '../server/runtime/resolvePageSnapshot.ts'
-import { serverSlot } from '../server/runtime/serverSlot.ts'
-import { baseSlot } from '../shared/baseSlot.ts'
-import { buildRpcProxy } from '../shared/buildRpcProxy.ts'
-import { buildRpcRequest } from '../shared/buildRpcRequest.ts'
-import { cacheStalenessSlot } from '../shared/cacheStalenessSlot.ts'
-import { cacheStoreSlot } from '../shared/cacheStoreSlot.ts'
-import { commandNameForUrl } from '../shared/commandNameForUrl.ts'
-import { createCacheStore } from '../shared/createCacheStore.ts'
-import { docSnapshotsSlot } from '../shared/docSnapshotsSlot.ts'
-import { HEALTH_PATH } from '../shared/HEALTH_PATH.ts'
-import { pageSlot } from '../shared/pageSlot.ts'
-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'
-import { createTestSocketChannel } from './createTestSocketChannel.ts'
-
-/*
-Augmentable rpc/socket maps for `app.rpc.<rpc>` / `app.sockets.<name>`. The
-build's writeTestRpcDts / writeTestSocketsDts emit one entry per rpc/socket
-(into src/.abide/), so the keys + signatures are the project's real surface
-with no imports. Empty here; types arrive once the app has been built. Mirrors
-url's RpcRoutes / health's AppHealthMap.
-*/
-// @documentation testing
-// biome-ignore lint/suspicious/noEmptyInterface: augmented by the generated testRpc.d.ts
-export interface RpcClient {}
-// biome-ignore lint/suspicious/noEmptyInterface: augmented by the generated testSockets.d.ts
-export interface SocketClient {}
-
-/* The booted app under test. Every named subsystem is reachable as the rpc
-   you call, the socket you iterate, or a path you fetch — over the real
-   server, so the full pipeline (CSRF, cookies, base path) runs. */
-export type TestApp = {
-    /* The kernel-assigned origin, e.g. http://localhost:51234. */
-    origin: string
-    /* fetch against the app: prefixes the kernel-assigned origin, so you pass a
-       route-space path (`/products/1`), not the wire URL. The booted server
-       matches routes at raw paths — the APP_URL mount base is stripped by an
-       external proxy in production, absent here — so paths carry no base. */
-    fetch: (path: string, init?: RequestInit) => Promise<Response>
-    /* Rpc calls over HTTP, keyed by command name: `app.rpc.getProduct({ id })`. */
-    rpc: RpcClient
-    /* Sockets keyed by name: `app.sockets.ticker` is the Socket — iterate it for
-       the live stream, `.tail(n)` to seed, `.publish(m)` to send. */
-    sockets: SocketClient
-    /* The /__abide/health payload, decoded. */
-    health: () => Promise<unknown>
-    /* Stops the server, releases the port, restores every touched slot. */
-    stop: () => Promise<void>
-    /* `await using app = await createTestApp()` — disposal runs stop(), so a
-       thrown assertion still releases the port and restores the slots rather
-       than leaking the request-scope/cache/page resolvers into the next file. */
-    [Symbol.asyncDispose]: () => Promise<void>
-}
-
-/*
-Boots the real app on an ephemeral port — the same wiring serverEntry performs,
-minus the standalone-binary env layers. Imports the framework's virtual
-manifests (resolved by abideResolverPlugin, registered via `abide/preload`
-in the consumer's bunfig), so the routes, rpcs, and sockets are the project's
-real surface, not a fixture. Pass nothing: `await createTestApp()` is the app
-exactly as `bun start` would serve it.
-
-Slots are saved and restored around the boot so a suite tears down without
-leaking the request-scope/cache/page resolvers into the next test file.
-*/
-export async function createTestApp(): Promise<TestApp> {
-    const previous = {
-        cacheResolver: cacheStoreSlot.resolver,
-        sharedResolver: sharedCacheStoreSlot.resolver,
-        pageResolver: pageSlot.resolver,
-        baseResolver: baseSlot.resolver,
-        pendingAsyncCellsResolver: pendingAsyncCellsSlot.resolver,
-        resolvedCellsResolver: resolvedCellsSlot.resolver,
-        streamedCellsResolver: streamedCellsSlot.resolver,
-        socketTailsResolver: socketTailsSlot.resolver,
-        docSnapshotsResolver: docSnapshotsSlot.resolver,
-        activeServer: serverSlot.active,
-        pageRender: pageRenderSlot.render,
-        stalenessResolver: cacheStalenessSlot.resolver,
-    }
-
-    const sharedStore = createCacheStore()
-    sharedCacheStoreSlot.resolver = () => sharedStore
-    cacheStoreSlot.resolver = () => requestContext.getStore()?.cache ?? sharedStore
-    const sharedPendingAsyncCells = { promises: [] }
-    pendingAsyncCellsSlot.resolver = () =>
-        requestContext.getStore()?.pendingAsyncCells ?? sharedPendingAsyncCells
-    const sharedResolvedCells = { entries: [] }
-    resolvedCellsSlot.resolver = () =>
-        requestContext.getStore()?.resolvedCells ?? sharedResolvedCells
-    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
-    /* Server-side invalidate()/refresh() broadcast over the reserved socket (ADR-0041),
-       exactly as serverEntry installs it. */
-    cacheStalenessSlot.resolver = () => broadcastCacheStaleness
-
-    /* Eager env validation, exactly as serverEntry: a top-level env(schema) in
-       src/server/config.ts fails the boot loudly here rather than lazily. No-op
-       when the file is absent. */
-    // @ts-expect-error virtual module resolved by abideResolverPlugin
-    await import('../../_virtual/config.ts')
-
-    const server: Server<unknown> = await createServer({
-        pages,
-        layouts,
-        rpc,
-        sockets,
-        prompts,
-        shell,
-        app: appMod,
-        assets,
-        publicAssets,
-        mcpResources,
-        mcp,
-        cliProgramName,
-        appInfo,
-        port: 0,
-    })
-
-    const origin = `http://localhost:${server.port}`
-
-    function appFetch(path: string, init?: RequestInit): Promise<Response> {
-        return fetch(`${origin}${path}`, init)
-    }
-
-    /* Rpc modules loaded once so the registry holds every RemoteFunction; the
-       proxy maps command name → an HTTP call against the booted server. */
-    await ensureRegistriesLoaded()
-    const remotes = new Map<string, RemoteFunction<unknown, unknown>>(
-        Array.from(rpcRegistry.values()).map((entry) => [
-            commandNameForUrl(entry.remote.url),
-            entry.remote,
-        ]),
-    )
-
-    function send(remote: RemoteFunction<unknown, unknown>, args: unknown): Promise<Response> {
-        /* Same-origin Origin header so the CSRF gate admits mutating rpcs; the
-           server serves rpcs at their raw url (no mount base applied here). */
-        const request = buildRpcRequest({
-            method: remote.method,
-            url: remote.url,
-            args,
-            baseUrl: `${origin}/`,
-            headers: new Headers({ origin }),
-        })
-        return fetch(request)
-    }
-
-    const rpcClient = buildRpcProxy<RpcClient>((name) => {
-        const remote = remotes.get(name)
-        return remote ? (args) => send(remote, args) : undefined
-    })
-
-    /* One ws to the booted multiplex, dialed lazily on first socket access so a
-       suite touching no socket holds no connection. http→ws, raw path. */
-    const wsUrl = `${origin.replace(/^http/, 'ws')}${SOCKETS_PATH}`
-    let channel: ReturnType<typeof createTestSocketChannel> | undefined
-    const socketNames = new Set(Object.keys(sockets as Record<string, unknown>))
-    const socketClient = new Proxy({} as Record<string, Socket<unknown>>, {
-        get(_target, prop): Socket<unknown> | undefined {
-            if (typeof prop !== 'string' || !socketNames.has(prop)) {
-                return undefined
-            }
-            channel ??= createTestSocketChannel(wsUrl)
-            return channel.socket(prop)
-        },
-    })
-
-    async function stop(): Promise<void> {
-        channel?.close()
-        server.stop(true)
-        cacheStoreSlot.resolver = previous.cacheResolver
-        sharedCacheStoreSlot.resolver = previous.sharedResolver
-        pageSlot.resolver = previous.pageResolver
-        baseSlot.resolver = previous.baseResolver
-        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
-        cacheStalenessSlot.resolver = previous.stalenessResolver
-    }
-
-    return {
-        origin,
-        fetch: appFetch,
-        rpc: rpcClient,
-        sockets: socketClient as unknown as SocketClient,
-        health: () => appFetch(HEALTH_PATH).then((response) => response.json()),
-        stop,
-        [Symbol.asyncDispose]: stop,
-    }
-}

package/src/lib/test/createTestSocketChannel.ts

@@ -1,85 +0,0 @@
-import { buildSocketOverChannel } from '../shared/buildSocketOverChannel.ts'
-import { createSocketSubRegistry } from '../shared/createSocketSubRegistry.ts'
-import { decodeRefJson } from '../shared/decodeRefJson.ts'
-import { encodeRefJson } from '../shared/encodeRefJson.ts'
-import type { Socket } from '../shared/types/Socket.ts'
-import type { SocketClientFrame } from '../shared/types/SocketClientFrame.ts'
-import type { SocketServerFrame } from '../shared/types/SocketServerFrame.ts'
-
-/*
-Test-side substitute for the browser socketChannel: one ws to the booted
-server's multiplex, speaking the same SocketClientFrame/SocketServerFrame
-protocol. Stripped of the browser channel's reconnect/backoff/visibility
-machinery — a test owns the connection lifecycle through `close()`, so a drop
-is teardown, not something to recover from. Frames sent before the ws opens
-queue and flush on open, the one piece of timing a test can't sidestep.
-
-Uses the same createSocketSubRegistry-backed SocketChannel the browser channel
-uses, so `socket(name)` passes it to the same buildSocketOverChannel the browser
-socketProxy uses — the Socket<T> surface can't drift between the test path and production.
-*/
-export function createTestSocketChannel(wsUrl: string): {
-    socket: <T>(name: string) => Socket<T>
-    close: () => void
-    /* `using channel = createTestSocketChannel(url)` — disposal closes the ws. */
-    [Symbol.dispose]: () => void
-} {
-    let pendingSends: string[] = []
-
-    const ws = new WebSocket(wsUrl)
-
-    function flushPending(): void {
-        if (ws.readyState !== WebSocket.OPEN) {
-            return
-        }
-        for (const message of pendingSends) {
-            ws.send(message)
-        }
-        pendingSends = []
-    }
-
-    function send(frame: SocketClientFrame): void {
-        // ref-json, matching the browser channel + the server's dispatcher/publish codec.
-        const message = encodeRefJson(frame)
-        if (ws.readyState === WebSocket.OPEN) {
-            ws.send(message)
-            return
-        }
-        pendingSends.push(message)
-    }
-
-    /* Same sub registry + frame routing the browser channel uses; this harness owns
-       only the bare ws (no reconnect — a test drives the lifecycle through close()). */
-    const registry = createSocketSubRegistry(send)
-
-    ws.addEventListener('open', flushPending)
-    ws.addEventListener('message', (event) => {
-        let frame: SocketServerFrame
-        try {
-            // The server sends ref-json frames (createSocketDispatcher/defineSocket); decode to match.
-            frame = decodeRefJson(event.data as string) as SocketServerFrame
-        } catch {
-            return
-        }
-        registry.routeFrame(frame)
-    })
-    /* A drop after subs are live is unexpected; surface it so iterators unblock
-       instead of awaiting a frame that never comes. Idempotent — the first of
-       error/close drains the subs, the second finds none. error covers a failed
-       handshake (no open, no clean close) that close alone would miss. */
-    function disconnectAll(): void {
-        for (const callbacks of registry.drainSubs()) {
-            callbacks.onDisconnect()
-        }
-    }
-    ws.addEventListener('close', disconnectAll)
-    ws.addEventListener('error', disconnectAll)
-
-    /* Same Socket<T> builder the browser proxy uses, over this test channel. */
-    function socket<T>(name: string): Socket<T> {
-        return buildSocketOverChannel<T>(name, () => registry.channel)
-    }
-
-    const close = () => ws.close()
-    return { socket, close, [Symbol.dispose]: close }
-}

package/src/lib/ui/README.md

@@ -1,86 +0,0 @@
-# abide-ui
-
-A from-scratch, single-file UI framework for abide — reactive, with `<script>` +
-template + `<style>` in one `.abide` file. Signal surface, document
-substrate, server-rendered and streamed, with true DOM adoption.
-
-abide-ui is the framework's UI runtime: `createUiPageRenderer` renders and streams
-every page, and `.abide` files are the only component format.
-
-## A component
-
-```html
-<script>
-  import Layout from './Layout.abide'
-  let count = state(0)              // signal
-  let items = state([])
-  let total = derived(() => items.length)   // computed
-  function add() { items.push('item ' + (total + 1)) }
-</script>
-
-<Layout title="home">
-  <button onclick={() => count += 1}>count: {count}</button>
-  <button onclick={add}>add ({total})</button>
-  <template if={total}>
-    <ul>
-      <template each={items} as="it" key="it"><li>{it}</li></template>
-    </ul>
-    <template else><p>empty</p></template>
-  </template>
-</Layout>
-
-<style>
-  button { cursor: pointer }   /* scoped to this component */
-</style>
-```
-
-## Idioms
-
-- **Signals are the surface**: `state(v)`, `derived(fn)`, `effect(fn)`, `props()`.
-  You write plain assignment (`count += 1`, `items.push(x)`); the compiler lowers
-  it. Templates auto-read (`{count}`); ordering and cross-references compose.
-- **Everything dynamic lives in `{ }`** — `{expr}` text, `name={expr}`,
-  `onclick={fn}`, `bind:value={path}`.
-- **Control flow is native `<template>`** (valid HTML, no mustache DSL):
-  `<template if>`/`<template else>`, `<template each as key>`,
-  `<template await>`/`then`/`catch`, `<template switch>`/`case`/`default`.
-- **Components** are capitalised tags (`<Layout title="…">`); children fill the
-  child's `<slot>`. Props are reactive (passed as thunks).
-- **Scoped styles**: a `<style>` block is scoped via a `[data-a-<hash>]`
-  attribute — per component, or per control-flow branch when nested in one.
-
-## Substrate (why it's fast)
-
-State is one mutable document addressed by path; every change is a patch over a
-path. The compiler turns `model.a[i].b` into a path read and `model.x = y` into a
-patch, hoisting static paths to a `cell` resolved once. Reactivity is shape-only
-(a deep field edit wakes only that field, not the list above it). On the
-write-path microbench this runs ~20× faster than a deep-proxy signal baseline.
-
-## SSR + streaming + hydration
-
-- `compileSSR` renders to an HTML string (byte-identical to the client DOM).
-- `renderToStream` streams: pending shell first, then resolved `<template await>`
-  fragments out of order as their promises settle; the inline swap script swaps them in.
-- `hydrate` adopts the server DOM in place (no re-render) for static-structure
-  components — claims existing nodes, splits merged text, wires effects/listeners.
-
-## Pipeline
-
-```
-.abide → analyzeComponent (split script/style/template, desugar signals → doc,
-                           lower data access, scope CSS)
-       → generateBuild  (client: skeleton/cloneStatic/appendText/attr/on/each/when/…)
-       → generateSSR    (server: HTML-string back-end, await markers)
-       → hoistCells     (static paths → cells)
-       → compileModule  (ES module: default mount + render() for SSR)
-```
-
-`compile/abideUiPlugin.ts` is the Bun loader for `.abide` files.
-
-## Known gaps
-
-- Hydration adopts static structure only; control-flow blocks (if/each/await/
-  switch) and child components fall back to `mount` (re-render).
-- `compileModule` emits `abide/ui/*` specifiers (a published consumer needs
-  `abide/ui/*` or `abideImportName`).

package/src/lib/ui/activePendingCells.ts

@@ -1,14 +0,0 @@
-import { pendingAsyncCellsSlot } from '../shared/pendingAsyncCellsSlot.ts'
-import type { PendingAsyncCells } from '../shared/types/PendingAsyncCells.ts'
-import { cellBarrierBacking } from './runtime/cellBarrierBacking.ts'
-
-/*
-The async-cell barrier list a registration (`createAsyncCell`) or a drain (`settleAsyncCells`) should
-use RIGHT NOW: a per-render isolated list if one is active (a hoisted concurrent child render — see
-`isolateCellBarrier`), else the per-request list from `pendingAsyncCellsSlot`. The single seam both
-barrier consumers read, so an isolated render can't leak its in-flight cells into a sibling's or the
-page's drain. Undefined only when neither a render override nor a request/fallback list is installed.
-*/
-export function activePendingCells(): PendingAsyncCells | undefined {
-    return cellBarrierBacking.active.current() ?? pendingAsyncCellsSlot.get()
-}

package/src/lib/ui/amendReaderHook.ts

@@ -1,125 +0,0 @@
-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, key)
-                        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 }
-}