@abide/abide 0.28.0

package/src/lib/shared/health.ts

@@ -0,0 +1,179 @@
+import { canonicalJson } from './canonicalJson.ts'
+import { createLivenessWatch } from './createLivenessWatch.ts'
+import { createSubscriber } from './createSubscriber.ts'
+import { HEALTH_PATH } from './HEALTH_PATH.ts'
+import { healthReadSlot } from './healthReadSlot.ts'
+import { healthSeedSlot } from './healthSeedSlot.ts'
+import { isAbideHealthPayload } from './isAbideHealthPayload.ts'
+import { withBase } from './withBase.ts'
+
+/*
+Augmented by the generated `src/.abide/health.d.ts` with
+`{ fields: <the app health() hook's resolved return> }`, so a project's
+`health()` reads type against its own hook. Unaugmented (no app.ts, or no
+hook), AppHealth resolves to no fields.
+*/
+// @readme observability
+// biome-ignore lint/suspicious/noEmptyInterface: augmented by the generated health.d.ts
+export interface AppHealthMap {}
+export type AppHealth = AppHealthMap extends { fields: infer Fields }
+    ? Fields extends object
+        ? Fields
+        : Record<never, never>
+    : Record<never, never>
+
+/*
+What health() reports: `reachable` is the framework's transport verdict; the
+rest is the last successful payload, whole — the framework identity (`abide`
+carries the framework version, `name`/`version` the app's) plus the app
+health() hook's fields, exactly as /__abide/health serves them. Fields
+persist while unreachable (last-known state beats vanishing fields: "was
+authenticated, currently unreachable" and "reachable, not authenticated"
+need different UI) and are Partial because nothing has arrived before the
+first poll — unless the SSR seed shipped them with the document.
+*/
+export type HealthState = {
+    reachable: boolean
+    abide?: string
+    name?: string
+    version?: string
+} & Partial<AppHealth>
+
+const PROBE_INTERVAL_MS = 10_000
+const PROBE_TIMEOUT_MS = 5_000
+
+/* Last successful payload's app fields (framework identity keys stripped). */
+let fields: Record<string, unknown> = {}
+/* The watch's verdict; composed with navigator.onLine at read time. */
+let backendAlive = true
+let notify: (() => void) | undefined
+
+/*
+One probe: the same standard of proof as the launcher's probeAbideServer —
+a `abide` key in the body, never response.ok alone, because a captive
+portal answers any GET with a 200. Captures the whole payload (identity
+keys included) as a side effect; a changed payload (e.g. authenticated
+flipping) notifies readers even though reachability didn't transition.
+*/
+async function probeHealth(url: string): Promise<boolean> {
+    try {
+        const response = await fetch(url, {
+            headers: { accept: 'application/json' },
+            cache: 'no-store',
+            signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+        })
+        if (!response.ok) {
+            return false
+        }
+        const body = (await response.json()) as Record<string, unknown>
+        if (!isAbideHealthPayload(body)) {
+            return false
+        }
+        applyFields(body)
+        return true
+    } catch {
+        return false
+    }
+}
+
+/* Swaps in a changed payload and notifies readers; identical payloads stay silent. */
+function applyFields(payload: Record<string, unknown>): void {
+    if (canonicalJson(payload) !== canonicalJson(fields)) {
+        fields = payload
+        notify?.()
+    }
+}
+
+const watch = createLivenessWatch({
+    probe: probeHealth,
+    onChange(alive) {
+        backendAlive = alive
+        notify?.()
+    },
+    intervalMs: PROBE_INTERVAL_MS,
+})
+
+/*
+Reader-driven lifecycle (the createSubscriber rule): the first tracking
+reader starts the poll, the last one tears it down — an app that never
+reads health() never sends a byte. Mirrors the socket channel's visibility
+philosophy: hidden tabs hold no poll (nobody is looking at the banner),
+and the visible transition probes immediately so the value is honest the
+moment eyes return. The online event also probes immediately — recovery
+confirmation shouldn't wait out the interval; offline needs no probe
+because read-time composition with navigator.onLine reports it instantly.
+*/
+const subscribeHealth =
+    typeof window === 'undefined'
+        ? undefined
+        : createSubscriber((update) => {
+              notify = update
+              const onVisibility = () => {
+                  if (document.visibilityState === 'hidden') {
+                      watch.stop()
+                      return
+                  }
+                  watch.watch(withBase(HEALTH_PATH))
+                  watch.probeNow()
+              }
+              const onOnline = () => {
+                  watch.probeNow()
+                  update()
+              }
+              const onOffline = () => update()
+              document.addEventListener('visibilitychange', onVisibility)
+              window.addEventListener('online', onOnline)
+              window.addEventListener('offline', onOffline)
+              watch.watch(withBase(HEALTH_PATH))
+              /*
+              SSR seed: a page that read health() during its server render
+              shipped the payload in __SSR__ (startClient parks it on the
+              slot). The document's arrival just proved the server
+              reachable, so the immediate first probe is skipped — the
+              watch's interval owns the next one — and the fields apply a
+              microtask after connect: the hydration read still matches the
+              server-rendered DOM (the server render carried no fields),
+              while the update lands before first paint. Consumed once;
+              later reconnects probe immediately as usual.
+              */
+              const seed = healthSeedSlot.payload
+              healthSeedSlot.payload = undefined
+              if (seed) {
+                  queueMicrotask(() => applyFields(seed))
+              } else {
+                  watch.probeNow()
+              }
+              return () => {
+                  document.removeEventListener('visibilitychange', onVisibility)
+                  window.removeEventListener('online', onOnline)
+                  window.removeEventListener('offline', onOffline)
+                  watch.stop()
+                  notify = undefined
+              }
+          })
+
+/*
+Reactive backend-health read: `reachable` plus whatever the app's
+health(request) hook reports, polled from /__abide/health only while a
+tracking scope ($derived/$effect) is reading it. Like tail and cache —
+and unlike the pending()/refreshing() probes — reading this opens a
+resource (the poll). Constant `{ reachable: true }` on the server: the
+server is its own backend. navigator.onLine composes in at read time, so
+a lost network reports instantly without waiting for a probe to time out.
+*/
+export function health(): HealthState {
+    /* window, not navigator: Bun defines a partial navigator with no onLine. */
+    if (typeof window === 'undefined') {
+        /*
+        Mark the request (when the server runtime installed a marker) so the
+        renderer stamps the health payload into __SSR__ — the client's seed.
+        The render itself stays fields-less: the hook may be async and this
+        read is sync, so the payload is built after the render returns.
+        */
+        healthReadSlot.mark?.()
+        return { reachable: true } as HealthState
+    }
+    subscribeHealth?.()
+    /* reachable last: it is the framework's verdict, never a hook field's to shadow. */
+    return { ...fields, reachable: backendAlive && navigator.onLine } as HealthState
+}

package/src/lib/shared/healthReadSlot.ts

@@ -0,0 +1,11 @@
+/*
+Server-side registration point for health()'s SSR read mark. createServer
+installs a marker that flags the current request store; the renderer reads
+the flag to stamp the health payload into __SSR__ only for pages that
+actually read health() during their render — the same reader-driven rule as
+the client poll. Browser bundles never install one, so the shared module's
+call no-ops there. Mirrors requestScopeSlot.
+*/
+export const healthReadSlot: { mark: (() => void) | undefined } = {
+    mark: undefined,
+}

package/src/lib/shared/healthSeedSlot.ts

@@ -0,0 +1,12 @@
+/*
+One-shot handoff of the SSR-stamped health payload (__SSR__.health) from
+startClient to the shared health module. startClient writes it before
+hydrate; health()'s first subscriber consumes it, applying the fields
+without the immediate first probe — the document's arrival just proved the
+server reachable, so the first poll waits a full interval. A slot rather
+than a second export on health.ts keeps the seeding one-way and the module
+single-callable. Mirrors healthReadSlot, its server half.
+*/
+export const healthSeedSlot: { payload: Record<string, unknown> | undefined } = {
+    payload: undefined,
+}

package/src/lib/shared/html.ts

@@ -0,0 +1,38 @@
+const RAW_HTML = Symbol.for('abide.rawHtml')
+
+/* A value marked as trusted raw markup — a `{expr}` interpolation inserts it
+   verbatim (not escaped) on both sides. The brand is a registered Symbol, so it
+   survives across module/bundle copies. */
+export type RawHtml = { readonly [RAW_HTML]: string }
+
+/*
+Marks a string as trusted raw HTML so a `{expr}` interpolation inserts its nodes
+instead of escaped text — the abide idiom for raw markup (no `{@html}` mustache).
+Works two ways:
+
+  html(trustedString)        // plain call — insert the string verbatim
+  html`<b>${name}</b>`       // tagged — concatenate parts verbatim
+
+Calling `html` is the explicit opt-in to raw insertion; plain `{value}` always
+escapes. The tag does NOT auto-escape interpolations (it's raw by intent), so only
+build markup from values you trust, or escape them yourself.
+*/
+// @readme plumbing
+export function html(strings: TemplateStringsArray | string, ...values: unknown[]): RawHtml {
+    if (typeof strings === 'string') {
+        return { [RAW_HTML]: strings }
+    }
+    let markup = strings[0] ?? ''
+    for (let index = 0; index < values.length; index += 1) {
+        markup += String(values[index]) + (strings[index + 1] ?? '')
+    }
+    return { [RAW_HTML]: markup }
+}
+
+/* The raw markup of a `html`-branded value, or undefined for anything else
+   (so text bindings can fast-path plain values and only branded ones go raw). */
+export function rawHtmlString(value: unknown): string | undefined {
+    return value !== null && typeof value === 'object' && RAW_HTML in value
+        ? (value as RawHtml)[RAW_HTML]
+        : undefined
+}

package/src/lib/shared/importNamesToStrip.ts

@@ -0,0 +1,13 @@
+import { ABIDE_PACKAGE_NAME } from './ABIDE_PACKAGE_NAME.ts'
+
+/*
+The names a user may import a abide server helper under: the project's chosen
+alias plus the canonical package name. The resolver strips the dead import
+under both so it can't side-effect-load the server stub into the client
+bundle. When the alias already is the canonical name, there's only one.
+*/
+export function importNamesToStrip(importName: string): string[] {
+    return importName === ABIDE_PACKAGE_NAME
+        ? [ABIDE_PACKAGE_NAME]
+        : [importName, ABIDE_PACKAGE_NAME]
+}

package/src/lib/shared/invalidateEvent.ts

@@ -0,0 +1,11 @@
+import type { CacheInvalidation } from './types/CacheInvalidation.ts'
+
+/*
+Constructs the cache store's 'invalidate' event from the keys an
+invalidation touched. The single definition of the event name + detail
+shape, so the two dispatch sites (cache.invalidate and the streamed-
+resolution placeholder settle) can't drift from the cache store's listener.
+*/
+export function invalidateEvent(keys: Iterable<string>): CustomEvent<CacheInvalidation> {
+    return new CustomEvent('invalidate', { detail: new Set(keys) })
+}

package/src/lib/shared/invalidateTripwire.ts

@@ -0,0 +1,40 @@
+import { abideLog } from './abideLog.ts'
+
+/*
+Same-selector invalidations within one macrotask before the warning fires. A
+reactive loop spins on microtasks (lifecycle mark → effect flush →
+invalidate), starving macrotasks — so the reset timer below never runs while
+one is live, and legitimate repeats (socket frames, user events) arriving
+across macrotasks clear the count instead.
+*/
+const LOOP_THRESHOLD = 25
+
+const invalidationCounts = new Map<string, number>()
+let resetTimer: ReturnType<typeof setTimeout> | undefined
+
+/*
+Cycle tripwire for cache.invalidate. A synchronous re-run counter (an
+effect-update-depth limit) counts synchronous re-runs, but the probes' lifecycle marks defer a microtask
+(createLifecycleChannel), so a self-feeding effect — one that reads a probe or
+cached value and invalidates a selector that re-wakes its own scope — spins
+forever without tripping it, pinning the CPU. Many invalidations of one
+selector inside a single macrotask is that signature. Warns once per episode
+(the starved reset timer can't fire mid-loop, so the count only crosses the
+threshold once); reporting only — invalidation proceeds.
+*/
+export function invalidateTripwire(selectorLabel: string): void {
+    const count = (invalidationCounts.get(selectorLabel) ?? 0) + 1
+    invalidationCounts.set(selectorLabel, count)
+    if (resetTimer === undefined) {
+        resetTimer = setTimeout(() => {
+            resetTimer = undefined
+            invalidationCounts.clear()
+        }, 0)
+        resetTimer.unref?.()
+    }
+    if (count === LOOP_THRESHOLD) {
+        abideLog.warn(
+            `cache.invalidate(${selectorLabel}) fired ${LOOP_THRESHOLD}× within one task — likely a reactive loop: an effect that reads pending()/refreshing() or a cached value and invalidates a selector waking its own scope re-triggers itself across microtasks, invisible to synchronous loop detection. Find the effect invalidating ${selectorLabel}.`,
+        )
+    }
+}

package/src/lib/shared/isAbideHealthPayload.ts

@@ -0,0 +1,11 @@
+/*
+Whether a health/identity response body identifies a abide server. The
+`abide` field carries the framework version (a non-empty string) on current
+servers and `true` on older ones — both accepted, so a newer prober still
+recognises an older server. The body check (never response.ok alone) is the
+captive-portal defense shared by every prober: a portal answers any GET with
+a 200, but it doesn't answer with this.
+*/
+export function isAbideHealthPayload(body: { abide?: unknown }): boolean {
+    return body.abide === true || (typeof body.abide === 'string' && body.abide !== '')
+}

package/src/lib/shared/isCompileTarget.ts

@@ -0,0 +1,15 @@
+import type { CompileTarget } from './types/CompileTarget.ts'
+
+/* The canonical cross-compile targets, as a runtime set for validation. */
+const COMPILE_TARGETS: readonly CompileTarget[] = [
+    'bun-darwin-arm64',
+    'bun-darwin-x64',
+    'bun-linux-arm64',
+    'bun-linux-x64',
+    'bun-windows-x64',
+]
+
+/* Narrows an arbitrary string to a known CompileTarget. */
+export function isCompileTarget(value: string): value is CompileTarget {
+    return (COMPILE_TARGETS as readonly string[]).includes(value)
+}

package/src/lib/shared/isDebugEnabled.ts

@@ -0,0 +1,26 @@
+import { isDebugNegated } from './isDebugNegated.ts'
+import { matchesDebugPattern } from './matchesDebugPattern.ts'
+import { parseDebugPatterns } from './parseDebugPatterns.ts'
+
+/*
+Whether a DEBUG-gated channel is enabled, npm-debug conventions:
+DEBUG="abide"           → enables "abide"
+DEBUG="abide:*"         → enables "abide" and "abide:anything"
+DEBUG="*"               → enables everything
+DEBUG="a,abide"         → comma-separated list
+DEBUG="abide:*,-abide:cache" → negation: exclusions win over inclusions
+Always-on channels don't consult this — they check isDebugNegated only.
+The default is guarded: this runs in the browser bundle, where `process`
+doesn't exist.
+*/
+export function isDebugEnabled(
+    name: string,
+    env: string | undefined = typeof process === 'undefined' ? undefined : process.env.DEBUG,
+): boolean {
+    if (isDebugNegated(name, env)) {
+        return false
+    }
+    return parseDebugPatterns(env)
+        .filter((pattern) => !pattern.startsWith('-'))
+        .some((pattern) => matchesDebugPattern(name, pattern))
+}

package/src/lib/shared/isDebugNegated.ts

@@ -0,0 +1,19 @@
+import { matchesDebugPattern } from './matchesDebugPattern.ts'
+import { parseDebugPatterns } from './parseDebugPatterns.ts'
+
+/*
+Whether a `-` pattern in DEBUG explicitly shuts a channel off — the off
+switch for the always-on channels (the app's name, 'abide'): DEBUG="-abide"
+silences framework lines including the per-request closing records,
+DEBUG="-myapp" the app's own. Silencing a channel silences all its levels —
+levels never gate, in either direction. The default is guarded: this runs in
+the browser bundle, where `process` doesn't exist.
+*/
+export function isDebugNegated(
+    name: string,
+    env: string | undefined = typeof process === 'undefined' ? undefined : process.env.DEBUG,
+): boolean {
+    return parseDebugPatterns(env)
+        .filter((pattern) => pattern.startsWith('-'))
+        .some((pattern) => matchesDebugPattern(name, pattern.slice(1)))
+}

package/src/lib/shared/isModuleNotFound.ts

@@ -0,0 +1,16 @@
+/*
+True when an error from a dynamic `import(...)` is a module-resolution
+failure (the package isn't installed) rather than an error thrown while
+the module's own code ran. Lets optional-peer loads swallow "not installed"
+while letting a genuine load-time failure surface. Bun surfaces the former
+as a ResolveMessage / ERR_MODULE_NOT_FOUND; the message check is the
+cross-runtime fallback.
+*/
+export function isModuleNotFound(error: unknown): boolean {
+    const code = (error as { code?: string })?.code
+    if (code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND') {
+        return true
+    }
+    const message = error instanceof Error ? error.message : String(error)
+    return /cannot find (module|package)|failed to resolve/i.test(message)
+}

package/src/lib/shared/isReadOnlyMethod.ts

@@ -0,0 +1,14 @@
+import type { HttpVerb } from './types/HttpVerb.ts'
+
+/*
+Read-only (safe) HTTP methods — they don't mutate server state. Abide
+uses this to decide which verbs auto-expose to MCP: reads flip MCP on
+when a schema is present, mutations require an explicit `clients.mcp`
+opt-in so a model can't delete/overwrite data just because the handler
+carries a schema. Also feeds the MCP tool `readOnlyHint` annotation.
+*/
+const READ_ONLY_METHODS = new Set<HttpVerb>(['GET', 'HEAD'])
+
+export function isReadOnlyMethod(method: HttpVerb): boolean {
+    return READ_ONLY_METHODS.has(method)
+}

package/src/lib/shared/isReplayableMethod.ts

@@ -0,0 +1,7 @@
+import { REPLAYABLE_METHODS } from './REPLAYABLE_METHODS.ts'
+import type { ReplayableMethod } from './types/ReplayableMethod.ts'
+
+/* Narrowing gate over REPLAYABLE_METHODS so callers get the typed method without a cast. */
+export function isReplayableMethod(method: string): method is ReplayableMethod {
+    return REPLAYABLE_METHODS.has(method)
+}

package/src/lib/shared/isStreamingResponse.ts

@@ -0,0 +1,11 @@
+import { STREAMING_CONTENT_TYPES } from './STREAMING_CONTENT_TYPES.ts'
+
+/*
+Whether a Response carries a streaming body (SSE / JSONL / NDJSON) by its
+Content-Type, so callers drain it frame-by-frame instead of buffering.
+Shared by the CLI print path and the MCP tool dispatcher.
+*/
+export function isStreamingResponse(response: Response): boolean {
+    const contentType = (response.headers.get('content-type') ?? '').toLowerCase()
+    return STREAMING_CONTENT_TYPES.some((type) => contentType.startsWith(type))
+}

package/src/lib/shared/isSubscribable.ts

@@ -0,0 +1,15 @@
+import type { Subscribable } from './types/Subscribable.ts'
+
+/*
+A Subscribable is a named AsyncIterable — distinguishes a stream argument from
+the other probe selector shapes (callables and `{ scope }` objects, neither of
+which carries Symbol.asyncIterator).
+*/
+export function isSubscribable(value: unknown): value is Subscribable<unknown> {
+    return (
+        typeof value === 'object' &&
+        value !== null &&
+        Symbol.asyncIterator in value &&
+        'name' in value
+    )
+}

package/src/lib/shared/jsonSchemaForPromptArguments.ts

@@ -0,0 +1,29 @@
+import type { PromptArgument } from './types/PromptArgument.ts'
+
+/*
+Turns a markdown prompt's frontmatter `arguments` list into the JSON
+Schema the MCP dispatcher advertises in `prompts/list` (top-level string
+properties + a `required` array). Prompt arguments are always strings —
+MCP fills them from model output — so every property is `{ type: 'string' }`.
+Returns undefined for an argument-less prompt so the generated module
+omits the field entirely.
+*/
+export function jsonSchemaForPromptArguments(
+    args: PromptArgument[],
+): Record<string, unknown> | undefined {
+    if (args.length === 0) {
+        return undefined
+    }
+    const properties = Object.fromEntries(
+        args.map((arg) => [
+            arg.name,
+            { type: 'string', ...(arg.description ? { description: arg.description } : {}) },
+        ]),
+    )
+    const required = args.filter((arg) => arg.required).map((arg) => arg.name)
+    return {
+        type: 'object',
+        properties,
+        ...(required.length > 0 ? { required } : {}),
+    }
+}

package/src/lib/shared/jsonSchemaForSchema.ts

@@ -0,0 +1,39 @@
+import type { StandardSchemaV1 } from './types/StandardSchemaV1.ts'
+
+const OPAQUE = { type: 'object', additionalProperties: true } as const
+
+/*
+Resolves a JSON Schema for an MCP tool's `inputSchema`, an OpenAPI body, a CLI
+flag set, or the bundle setup form. Probes the schema's own projection:
+
+  1. `schema.toJsonSchema()` (Arktype 2+)
+  2. `schema.toJSONSchema()` (Zod 4, Effect Schema, or a withJsonSchema wrap)
+  3. Opaque object — the surface still works, the consumer just gets no shape hint
+
+A projection that exists but throws (e.g. Zod 4 can't render `z.custom()`)
+degrades to the same opaque fallback rather than escaping — one un-serializable
+schema must not take down the whole list its caller is building (an MCP
+tools/list, an OpenAPI doc). Wrap with withJsonSchema to supply a shape.
+
+Schemas whose library exposes neither carry one via withJsonSchema. Returns a
+fresh object each call; callers can mutate (e.g. add a description) without
+aliasing the schema's own.
+*/
+export function jsonSchemaForSchema(schema: StandardSchemaV1 | undefined): Record<string, unknown> {
+    if (!schema) {
+        return { ...OPAQUE }
+    }
+    const candidate = schema as unknown as {
+        toJsonSchema?: () => Record<string, unknown>
+        toJSONSchema?: () => Record<string, unknown>
+    }
+    const project = candidate.toJsonSchema ?? candidate.toJSONSchema
+    if (typeof project !== 'function') {
+        return { ...OPAQUE }
+    }
+    try {
+        return { ...project.call(candidate) }
+    } catch {
+        return { ...OPAQUE }
+    }
+}

package/src/lib/shared/jsonlErrorFrame.ts

@@ -0,0 +1,24 @@
+/*
+The in-band error sentinel for a JSONL/NDJSON stream: when a handler's
+generator throws, `jsonl()` emits a final `{"$error":"<message>"}` line,
+and `streamResponse` re-throws it on the consumer side. Encoder and decoder
+live together here so the sentinel field has one definition and can't drift
+between the two ends of the wire.
+*/
+export const jsonlErrorFrame = {
+    // Error line for a thrown message, including the trailing newline.
+    encode(message: string): string {
+        return `${JSON.stringify({ $error: message })}\n`
+    },
+    // The message carried by a parsed line, or undefined when it isn't the error sentinel.
+    decode(parsed: unknown): string | undefined {
+        if (
+            parsed &&
+            typeof parsed === 'object' &&
+            typeof (parsed as { $error?: unknown }).$error === 'string'
+        ) {
+            return (parsed as { $error: string }).$error
+        }
+        return undefined
+    },
+}

package/src/lib/shared/keyForRemoteCall.ts

@@ -0,0 +1,29 @@
+import { canonicalJson } from './canonicalJson.ts'
+import { carriesBodyArgs } from './carriesBodyArgs.ts'
+import { queryStringFromArgs } from './queryStringFromArgs.ts'
+import type { HttpVerb } from './types/HttpVerb.ts'
+
+/*
+Derives a cache key from a verb-defined remote function and its args. The
+prefix is `${method} ${url}` where `url` is the route template. GET/DELETE/HEAD
+serialise args onto the URL as `?key=value` (sorted, via queryStringFromArgs —
+the same encoder buildRpcRequest builds its query with, so the key and the
+synthesized Request can't disagree); POST/PUT/PATCH join args after a space as
+canonical JSON. The verb split mirrors buildRpcRequest exactly.
+*/
+export function keyForRemoteCall(method: HttpVerb, url: string, args: unknown): string {
+    const prefix = `${method} ${url}`
+    if (!carriesBodyArgs(method)) {
+        if (args && typeof args === 'object' && !Array.isArray(args)) {
+            const search = queryStringFromArgs(args as Record<string, unknown>, true)
+            if (search.length > 0) {
+                return `${prefix}?${search}`
+            }
+        }
+        return prefix
+    }
+    if (args === undefined) {
+        return prefix
+    }
+    return `${prefix} ${canonicalJson(args)}`
+}

package/src/lib/shared/keyMatchesPrefix.ts

@@ -0,0 +1,9 @@
+/*
+The selector-prefix grammar shared by selectorMatcher and the cache store's
+scoped lifecycle marks: a prefix owns its exact key plus arg-bearing
+extensions — `?` (GET/DELETE query args) or ` ` (canonical-json body /
+producer args) — so `GET /a` never matches `GET /ab`.
+*/
+export function keyMatchesPrefix(key: string, prefix: string): boolean {
+    return key === prefix || key.startsWith(`${prefix}?`) || key.startsWith(`${prefix} `)
+}

package/src/lib/shared/lastConnectionPath.ts

@@ -0,0 +1,7 @@
+import { join } from 'node:path'
+import { appDataDir } from './appDataDir.ts'
+
+// Path to the per-program last-connection record, beside the data-dir `.env`.
+export function lastConnectionPath(programName: string): string {
+    return join(appDataDir(programName), 'last-connection.json')
+}

package/src/lib/shared/layoutChainForRoute.ts

@@ -0,0 +1,22 @@
+/*
+The ordered layout chain that wraps a page route: every directory prefix that
+holds a `layout.abide` and is an ancestor of (or equal to) the route, outermost
+first. `layoutKeys` are directory URLs (a layout's URL is its folder path, via
+pageUrlForFile). `/` matches every route; a deeper prefix matches when the route
+equals it or descends into it. Dynamic segments compare literally (`/media/[id]`)
+since both keys and routes carry the same `[name]` form. Pure — both the SSR
+renderer and the client router resolve a page's chain from the same function so
+they nest identically.
+*/
+export function layoutChainForRoute(routeUrl: string, layoutKeys: Iterable<string>): string[] {
+    const route = routeUrl === '/' ? '' : routeUrl.replace(/^\//, '')
+    const applies: string[] = []
+    for (const key of layoutKeys) {
+        const dir = key === '/' ? '' : key.replace(/^\//, '')
+        if (dir === '' || route === dir || route.startsWith(`${dir}/`)) {
+            applies.push(key)
+        }
+    }
+    /* Outermost first: a shorter prefix is an ancestor of a longer one. */
+    return applies.sort((first, second) => first.length - second.length)
+}

package/src/lib/shared/loadEnvFile.ts

@@ -0,0 +1,17 @@
+import { readEnvFile } from './readEnvFile.ts'
+
+/*
+Reads a `.env` at `path` and merges each declared var into `process.env`
+only when not already set. Fill-when-unset is the precedence rule the whole
+env stack relies on: layers loaded earlier (shell/ambient, Bun's CWD `.env`)
+win, and later callers back-fill only what's still missing. So a value's
+source is invisible to the app — it reads one flat `process.env` (Bun.env is
+the same object). Missing file is a no-op.
+*/
+export async function loadEnvFile(path: string): Promise<void> {
+    for (const [key, value] of Object.entries(await readEnvFile(path))) {
+        if (process.env[key] === undefined) {
+            process.env[key] = value
+        }
+    }
+}