dsh-zen-remote 2.3.3 → 2.3.4

package/src/index.ts

@@ -16,6 +16,7 @@
  */
 
 import { createOwnerPeerSource, createSharedApiFetchGetter } from './owner-peer.js'
+import { readFileSync } from 'node:fs'
 import { lstat, mkdir, open, realpath, rename, rm, writeFile } from 'node:fs/promises'
 import type { FileHandle } from 'node:fs/promises'
 import type { IncomingMessage, ServerResponse } from 'node:http'
@@ -55,7 +56,7 @@ import { createRelayClient, RelayError, volatileUpdateTouchesServerName } from '
 import type { RelayClient } from './relay-client.js'
 import { computeFingerprints } from './fingerprint.js'
 import { runSelfCheck, installIntercept } from './intercept.js'
-import type { CurrentSessionRead, InterceptDiagnostics, InterceptHandle } from './intercept.js'
+import type { CurrentSessionRead, InterceptDiagnostics, InterceptHandle, SessionInventorySlot } from './intercept.js'
 import { checkGatewayShape } from './intercept-shape.js'
 import type { GatewayShapeCheck } from './intercept-shape.js'
 import { checkFetchRouteShape, installFetchRouteIntercept } from './fetch-route-intercept.js'
@@ -65,6 +66,12 @@ import type { PluginRouteInterceptDiagnostics, PluginRouteInterceptHandle, WebSe
 import { normalizeAdapter, adapterOwnsRegistryEntry } from './plugin-adapter-core.js'
 import type { NormalizedAdapter } from './plugin-adapter-core.js'
 import { ADAPTERS } from './adapters/index.js'
+// PB-19: the better-sidebar surface extractor, a PURE utility inside the
+// adapters directory — the one subdirectory import the wiring makes besides
+// the ADAPTERS array (test/adapters-pluggable.test.cjs pins both to this
+// file). The fs read that feeds it also lives HERE: nothing inside
+// src/adapters/ touches the disk.
+import { betterSidebarSurfaceDigest, extractBetterSidebarSurface, surfaceLooksHealthy } from './adapters/dsh-better-sidebar/surface.js'
 import { createRelayHandler, loadServerId, RELAY_PREFIX, resolveDshVersion } from './relay-server.js'
 import type { RelayGateway, RelayHandler } from './relay-server.js'
 import { createBridgeRegistry, compareBridges } from './plugin-bridge.js'
@@ -80,6 +87,7 @@ import { createVerificationManager } from './wizard/verify.js'
 import type { BridgeDeclaration, BridgeRegistry, BridgeStatus, ServerPluginEntry, ZenRemoteService } from './plugin-bridge.js'
 import { createPluginLoopback } from './plugin-loopback.js'
 import { createPluginTunnel } from './plugin-tunnel.js'
+import { DEFAULT_MAX_UPLOAD_BYTES } from './upload-limits.js'
 
 // The plugin bridge's public types (PB-1), re-exported so another plugin's
 // author can `import type { … } from 'dsh-zen-remote'` without reaching into
@@ -127,8 +135,11 @@ export const CLIENT_CONFIG_ROUTE = '/_dsh/mobile-nav/client-config'
 /** Workspace-relative directory uploads land in (also the `@` prefix the composer inserts). */
 export const UPLOAD_DIR = '.dsh-uploads'
 
-/** Body cap when the plugin row sets no `maxUploadBytes`. */
-export const DEFAULT_MAX_UPLOAD_BYTES = 20 * 1024 * 1024
+// The phone composer's default body cap lives in upload-limits.ts with the
+// plugin's other upload numbers (the comment there spells out why this must
+// stay phone-only and never size the relay); re-exported so the main entry's
+// public surface keeps the name.
+export { DEFAULT_MAX_UPLOAD_BYTES }
 
 /** Longest filename, in bytes, that survives sanitization (ext4/APFS leaf limit is 255). */
 const MAX_NAME_BYTES = 180
@@ -588,12 +599,18 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
   // (`packageOf(name, ctx.baseUrl)` — verified on 0.2.0-rc.2 to answer
   // `{name, version, dir, …}` or undefined; any other shape, a missing
   // service or a probe failure reads as "not installed" and the adapter
-  // stays out). A plugin that registers its OWN cooperative declaration
-  // always wins: the adapter yields at registration time (logged), and the
-  // runtime re-checks the registry digest on every request. Both roles run
-  // this loop — the registry entries drive the handshake table, the bridge
-  // verdicts and the settings listing on either side, while the returned
-  // array feeds the two request halves.
+  // stays out). PB-19 exception: a version OUTSIDE the list still registers
+  // when the installed build's wire-surface digest (extracted here from its
+  // lib/index.js, the wiring being the only place the feature touches the
+  // disk) is whitelisted in the adapter's `surfaces` table — a wire-identical
+  // patch release bridges without a zen-remote release, and every failure of
+  // the extraction is logged apart from the digest-mismatch refusal. A plugin
+  // that registers its OWN cooperative declaration always wins: the adapter
+  // yields at registration time (logged), and the runtime re-checks the
+  // registry digest on every request. Both roles run this loop — the registry
+  // entries drive the handshake table, the bridge verdicts and the settings
+  // listing on either side, while the returned array feeds the two request
+  // halves.
   const adapters: NormalizedAdapter[] = []
   {
     const adapterWarn = (text: string): void => { ctx.logger?.warn('dsh-zen-remote adapter: %s', text) }
@@ -601,7 +618,7 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
       try {
         const holder = ctx as unknown as { get?: (name: string) => unknown; baseUrl?: string }
         const packages = holder.get?.('pluginPackages') as { packageOf?: (specifier: string, parentURL: string) => unknown } | undefined
-        const found = packages?.packageOf?.(adapter.plugin, holder.baseUrl ?? '') as { version?: unknown } | undefined
+        const found = packages?.packageOf?.(adapter.plugin, holder.baseUrl ?? '') as { version?: unknown; dir?: unknown } | undefined
         const installedVersion = found !== null && typeof found === 'object' && typeof (found as { version?: unknown }).version === 'string'
           ? (found as { version: string }).version
           : undefined
@@ -609,14 +626,44 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
           adapterWarn(`${adapter.plugin}: target package (or its version) not found; not registered`)
           continue
         }
-        const normalized = normalizeAdapter(adapter, installedVersion)
+        // PB-19: a version outside the adapter's list gets ONE more chance —
+        // its wire surface. Extract it, hash it, and let normalizeAdapter
+        // judge the digest against the adapter's `surfaces` table. Anything
+        // that goes wrong here leaves the digest undefined — the core then
+        // refuses as a plain unlisted version, and the warns below name WHY
+        // no digest was offered (no dir, unreadable file, lost dispatch
+        // table), distinct from a digest that simply missed.
+        const unlisted = !adapter.versions.includes(installedVersion)
+        let surfaceDigest: string | undefined
+        if (unlisted) {
+          const dir = typeof found?.dir === 'string' && found.dir !== '' ? found.dir : undefined
+          if (dir === undefined) {
+            adapterWarn(`${adapter.plugin}: version ${installedVersion} is unlisted and packageOf gave no dir; no surface digest to offer`)
+          } else {
+            try {
+              const surface = extractBetterSidebarSurface(readFileSync(join(dir, 'lib/index.js'), 'utf8'))
+              if (!surfaceLooksHealthy(surface)) {
+                adapterWarn(`${adapter.plugin}: surface extractor lost the dispatch table (${surface.methods.length} methods) — treating as unknown surface`)
+              } else {
+                surfaceDigest = betterSidebarSurfaceDigest(surface)
+              }
+            } catch (error) {
+              adapterWarn(`${adapter.plugin}: cannot read ${join(dir, 'lib/index.js')} for a surface digest: ${error instanceof Error ? error.message : String(error)}`)
+            }
+          }
+        }
+        const normalized = normalizeAdapter(adapter, installedVersion, surfaceDigest === undefined ? undefined : { surfaceDigest })
         if (registry.get(normalized.plugin) !== undefined) {
           adapterWarn(`${normalized.plugin}: the plugin registers its own bridge declaration; the adapter yields`)
           continue
         }
         registry.registerNormalized(normalized.declaration)
         adapters.push(normalized)
-        ctx.logger?.info('dsh-zen-remote adapter: %s adapted at version %s', normalized.plugin, installedVersion)
+        if (unlisted && surfaceDigest !== undefined) {
+          ctx.logger?.info('dsh-zen-remote adapter: %s bridged by surface digest %s (version %s unlisted)', normalized.plugin, surfaceDigest, installedVersion)
+        } else {
+          ctx.logger?.info('dsh-zen-remote adapter: %s adapted at version %s', normalized.plugin, installedVersion)
+        }
       } catch (error) {
         adapterWarn(`${adapter.plugin} refused: ${error instanceof Error ? error.message : String(error)}`)
       }
@@ -1301,6 +1348,39 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
       // carries nothing new costs one compare.
       interceptHandle?.currentSessionChanged()
     }
+    // PB-25b: the KNOWN-real-session inventory — the union of the merged
+    // global streams' session snapshots (the workspace merger's sessionHome:
+    // every real id the sidebar currently holds as a `zr~` row). Each merged
+    // stream owns one slot; a report REPLACES that stream's share (never a
+    // delta — merge-streams' contract) and the union rebuilds wholesale on
+    // every report and dispose (stream count is single digits). The
+    // plugin-route rewrite reads the union LIVE per answer through the
+    // getter — the same live-read discipline as getServerId/getStatus: a
+    // snapshot captured at install time would be permanently empty (the
+    // streams start reporting after the install), and an id that appears
+    // between two stream refreshes waits for the next refresh by design
+    // (the documented ceiling in merge-streams.ts). Read-only consumption:
+    // nothing below ever mutates what a merger handed over.
+    const knownSessionShares = new Map<SessionInventorySlot, ReadonlySet<string>>()
+    const knownRealIds = new Set<string>()
+    const rebuildKnownRealIds = (): void => {
+      knownRealIds.clear()
+      for (const share of knownSessionShares.values()) {
+        for (const id of share) knownRealIds.add(id)
+      }
+    }
+    const createSessionInventorySlot = (): SessionInventorySlot => {
+      const slot: SessionInventorySlot = {
+        replace(ids) {
+          knownSessionShares.set(slot, ids)
+          rebuildKnownRealIds()
+        },
+        dispose() {
+          if (knownSessionShares.delete(slot)) rebuildKnownRealIds()
+        },
+      }
+      return slot
+    }
     const interceptDiagnostics = (): InterceptDiagnostics | undefined => {
       if (interceptHandle !== undefined) return interceptHandle.diagnostics()
       if (interceptRefused !== undefined) {
@@ -1334,6 +1414,9 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
         relay: relayClient,
         getServerId: () => relayClient.handshakeInfo?.serverId,
         getCurrentSession: () => reportedCurrentSession,
+        // PB-25b: each merged stream reports its real-session inventory
+        // share into the union above.
+        createSessionInventorySlot,
         log: (format, ...args) => { ctx.logger?.info(`dsh-zen-remote ${format}`, ...args) },
       })
       interceptHandle = handle
@@ -1491,6 +1574,10 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
         // routes' deny hooks read (better-sidebar's open.external carries
         // no session field of its own).
         getCurrentSession: () => (reportedCurrentSession.kind === 'open' ? reportedCurrentSession.sessionId : undefined),
+        // PB-25b: the known-real-session union, read LIVE per rewriteIds
+        // answer — the rewriteIds deep scan rewrites an id that already sits
+        // in the browser's view even when this request never carried it.
+        getKnownRealIds: () => knownRealIds,
         log: (format, ...args) => { ctx.logger?.info(`dsh-zen-remote ${format}`, ...args) },
       })
       pluginRouteHandle = handle

package/src/intercept.ts

@@ -605,6 +605,19 @@ export interface InterceptDiagnostics {
   closedSessions: ClosedSessionRecord[]
 }
 
+/** PB-25b: one merged global stream's share of the KNOWN-real-session
+ * inventory. REPLACE semantics: each `replace` call carries that stream's
+ * FULL current set (the workspace merger's sessionHome snapshot — every real
+ * id the sidebar currently holds as a `zr~` id), never a delta; `dispose`
+ * drops the share (the stream ended — its merger is gone, its ids may no
+ * longer be in the UI's view). The wiring unions the live shares into the
+ * read-only set the plugin-route rewrite consults; nothing here hands out a
+ * mutable reference to merge state. */
+export interface SessionInventorySlot {
+  replace(ids: ReadonlySet<string>): void
+  dispose(): void
+}
+
 export interface InstallInterceptOptions {
   /** The RAW gateway instance (`ctx.typertGateway[symbols.original]`), not
    * the cordis proxy — own properties on the proxy are ignored by everyone. */
@@ -629,6 +642,13 @@ export interface InstallInterceptOptions {
    * read got wrong — so the value must be carried in. Default: permanently
    * `unavailable` (the conservative fallback — tombstones stay). */
   getCurrentSession?: () => CurrentSessionRead
+  /** PB-25b: the inventory slot factory — one slot per merged global stream
+   * (only the workspace merger ever reports; the control merger has no
+   * session inventory). The wiring unions the live slots' shares into the
+   * set the plugin-route rewrite reads. Absent: no shares are ever reported
+   * and the plugin-route value scan stays exactly the request-local
+   * behavior. */
+  createSessionInventorySlot?: () => SessionInventorySlot
 }
 
 export interface InterceptHandle {
@@ -1339,6 +1359,10 @@ interface MergedGlobalStreamDeps {
    * sync can announce list rows the UI has no summary for; the control
    * route carries no session lists and never calls it. */
   summarySync: SessionSummarySync
+  /** PB-25b: the inventory slot factory (the wiring's union feed — see
+   * {@link SessionInventorySlot}). One slot per merged stream, disposed with
+   * it; absent when the wiring passed no factory. */
+  createSessionInventorySlot?: () => SessionInventorySlot
 }
 
 /**
@@ -1366,13 +1390,25 @@ async function* mergedGlobalStream(deps: MergedGlobalStreamDeps): AsyncGenerator
     log?.('client merge dropped a frame on %s: %s', endpoint, message)
   }
   const initial = relayIdentityOf(relay)
+  // PB-25b: this stream's inventory share — the workspace merger reports its
+  // full real-id set through it (replace-style), and the share dies with the
+  // stream (both exits below: the degraded local-only path and the main
+  // teardown). The control merger has no session inventory and never
+  // reports.
+  const sessionSlot = deps.createSessionInventorySlot?.()
   // Created eagerly so the local leg is observed from its first frame on.
   // The empty identity is a placeholder: the remote pump retargets before
   // any remote frame is ever fed (it only runs under a real handshake).
   let merger: WorkspaceMerger | ControlMerger =
     endpoint === 'session/control'
       ? createControlMerger({ serverId: initial?.serverId ?? '', serverName: initial?.serverName ?? '', onDiagnostic })
-      : createWorkspaceMerger({ serverId: initial?.serverId ?? '', serverName: initial?.serverName ?? '', onDiagnostic, now: clock.now })
+      : createWorkspaceMerger({
+          serverId: initial?.serverId ?? '',
+          serverName: initial?.serverName ?? '',
+          onDiagnostic,
+          now: clock.now,
+          ...(sessionSlot !== undefined ? { onKnownSessions: (ids: ReadonlySet<string>) => sessionSlot.replace(ids) } : {}),
+        })
 
   /**
    * The status annotation (T34) the CURRENT relay state maps onto, applied
@@ -1563,6 +1599,9 @@ async function* mergedGlobalStream(deps: MergedGlobalStreamDeps): AsyncGenerator
     // Remote-side setup failed: degrade to a pure local passthrough so the
     // UI's own stream is untouched and the remote leg never starts.
     log?.('client merge on %s degraded to local-only: %s', endpoint, messageOf(error))
+    // PB-25b: this stream never reports (no remote leg) — drop its share
+    // before the degraded passthrough takes over.
+    sessionSlot?.dispose()
     yield* localOnly(local)
     return
   }
@@ -1740,6 +1779,9 @@ async function* mergedGlobalStream(deps: MergedGlobalStreamDeps): AsyncGenerator
     if (signal !== undefined) signal.removeEventListener('abort', onExternalAbort)
     currentController?.abort()
     flushWaiters()
+    // PB-25b: the stream is over — its inventory share leaves the wiring's
+    // union (its ids may no longer be in the UI's view).
+    sessionSlot?.dispose()
     // Best-effort half-close of the local stream the consumer walked away
     // from — never awaited: an upstream that ignores return() must not
     // hang the teardown.
@@ -2425,6 +2467,9 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
   // outlives individual stream generations so a nudge from a workspace leg
   // reaches whichever $events generation is open.
   const summarySync = createSessionSummarySync()
+  // PB-25b: the inventory slot factory (the wiring's union feed) — passed
+  // down to every merged stream, which owns one slot for its lifetime.
+  const createSessionInventorySlot = options.createSessionInventorySlot
   // T62: the current-session getter and the live-merged-stream listener
   // registry behind handle.currentSessionChanged().
   const getCurrentSession = options.getCurrentSession ?? (() => ({ kind: 'unavailable' }) as const)
@@ -3341,6 +3386,7 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
             watchCurrentSession,
             watchUninstall,
             summarySync,
+            createSessionInventorySlot,
           })
         })()
       }

package/src/merge-streams.ts

@@ -220,6 +220,18 @@ export interface WorkspaceMergerOptions extends MergerIdentity {
   /** T65: the clock the tombstone hide-grace runs on. Default Date.now;
    * tests advance an injectable fake to cross the grace. */
   now?: () => number
+  /** PB-25b: the known-real-session inventory report — every time the
+   * session registry changes, the FULL current set of real ids this merger
+   * knows (the sessionHome keys: live ids and tombstones alike, each one the
+   * UI holds as a `zr~` id under this identity) is handed over as a fresh
+   * snapshot. REPLACE semantics, never a delta: the consumer's share is
+   * redefined wholesale by every report, so no invalidation bookkeeping
+   * exists on either side. Documented ceiling: an id that appears (or
+   * leaves) between two registry changes is invisible to the consumer until
+   * the next change reports — dumb but correct, and the wiring owns the
+   * other half of the contract (read-only consumption; the plugin-route
+   * rewrite never mutates merge state). */
+  onKnownSessions?: (ids: ReadonlySet<string>) => void
 }
 
 export interface WorkspaceMerger {
@@ -285,6 +297,7 @@ export interface WorkspaceMerger {
  */
 export function createWorkspaceMerger(options: WorkspaceMergerOptions): WorkspaceMerger {
   const onDiagnostic = options.onDiagnostic
+  const onKnownSessions = options.onKnownSessions
   let identity: MergerIdentity = { serverId: options.serverId, serverName: options.serverName }
 
   // The locally observed truth, updated from every local baseline / order /
@@ -359,19 +372,43 @@ export function createWorkspaceMerger(options: WorkspaceMergerOptions): Workspac
    * remembered under THIS workspace as its last home (originals, cumulative). */
   function learnSessions(record: Record<string, unknown>, workspaceId: string): void {
     if (!Array.isArray(record.sessionIds)) return
-    for (const id of record.sessionIds) if (typeof id === 'string') sessionHome.set(id, workspaceId)
+    let learned = false
+    for (const id of record.sessionIds) {
+      if (typeof id === 'string') {
+        sessionHome.set(id, workspaceId)
+        learned = true
+      }
+    }
+    // PB-25b: the inventory grew — re-report the full set (replace-style;
+    // see onKnownSessions). Once per record with string ids, never per id.
+    if (learned) reportKnownSessions()
   }
 
   /** Drop the ids whose last home was this workspace — tombstones die with
    * their group (a server remove / a workspace diffed away; a session that
    * moved on lives under its NEW home and survives this). */
   function forgetWorkspace(workspaceId: string): void {
+    let forgot = false
     for (const [id, home] of sessionHome) {
       if (home === workspaceId) {
         sessionHome.delete(id)
         closedAt.delete(id)
+        forgot = true
       }
     }
+    // PB-25b: the inventory shrank — the gone ids must leave the consumer's
+    // share with this refresh, or a session that left the sub-client's view
+    // would keep being rewritten.
+    if (forgot) reportKnownSessions()
+  }
+
+  /** PB-25b: the inventory report — the FULL sessionHome key set as a fresh
+   * snapshot, handed to the callback replace-style. Fired at the three
+   * registry mutation points (learn / forget / the identity end) rather than
+   * once per frame: a frame that changes nothing costs nothing, and any
+   * future frame type that touches the registry reports automatically. */
+  function reportKnownSessions(): void {
+    onKnownSessions?.(new Set(sessionHome.keys()))
   }
 
   /** T65: stamp the ids that JUST left a workspace's live list (their
@@ -885,6 +922,9 @@ export function createWorkspaceMerger(options: WorkspaceMergerOptions): Workspac
       // So does the shown set: a NEW server may reuse original workspace ids,
       // and a stale entry would forward the new server's empty groups.
       shown.clear()
+      // PB-25b: the inventory died with the identity — the empty report is
+      // what empties the consumer's share (a NEW server mints new ids).
+      reportKnownSessions()
       return out
     },
   }

package/src/plugin-adapter-core.ts

@@ -24,6 +24,7 @@
 
 import { createHash } from 'node:crypto'
 import { isVirtual, fromVirtual } from './virtual-id.js'
+import { MAX_UPLOAD_BYTES } from './upload-limits.js'
 import type { NormalizedBridgeRoute, NormalizedDeclaration } from './plugin-bridge.js'
 import { BRIDGE_METHODS, DEFAULT_ROUTE_BODY_BYTES } from './plugin-bridge.js'
 
@@ -146,7 +147,9 @@ export interface AdapterHooks {
 export interface NormalizedAdapter {
   plugin: string
   /** The exact versions this adapter was written against; the INSTALLED
-   * version must be among them or the adapter does not register. */
+   * version must be among them — or its wire surface must be whitelisted in
+   * the adapter's `surfaces` table (PB-19) — or the adapter does not
+   * register. */
   versions: readonly string[]
   routes: NormalizedAdapterRoute[]
   /** The digest of the ROUTE TABLE (locator and match included) — the
@@ -163,13 +166,12 @@ export interface NormalizedAdapter {
 const PLUGIN_PATTERN = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u
 const MAX_ROUTES = 64
 
-/** The body cap an ADAPTER route may declare: 500 MiB — the relay's own
- * upload budget (lib/relay-server.js `MAX_UPLOAD_BYTES`), which the
- * better-sidebar upload route rides. Wider than the cooperative
- * declaration's 64 MiB because raw media uploads are exactly what an
- * adapter exists to carry; test/adapter-better-sidebar.test.cjs pins the
- * two numbers together. */
-export const MAX_ADAPTER_BODY_BYTES = 500 * 1024 * 1024
+/** The body cap an ADAPTER route may declare: the relay's own upload
+ * budget (`MAX_UPLOAD_BYTES` in upload-limits.ts), which the better-sidebar
+ * upload route rides. The same 500 MiB the cooperative declaration's
+ * maxBody allows — both read the one constant since PB-20; raw media
+ * uploads are exactly what an adapter exists to carry. */
+export const MAX_ADAPTER_BODY_BYTES = MAX_UPLOAD_BYTES
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
@@ -186,13 +188,19 @@ function fail(field: string, detail: string): never {
  * absolute paths, off the host-owned `/_dsh/` and `/api` prefixes) — an
  * adapter must not be able to reach anything a declaration cannot. The
  * installed version must be listed EXACTLY (`versions` are what the
- * adapter was written against); anything else refuses the adapter whole.
+ * adapter was written against) — with ONE out (PB-19): a version outside
+ * the list is admitted anyway when `options.surfaceDigest` — the wiring's
+ * extraction of the INSTALLED build's wire surface — is a key of the
+ * adapter's `surfaces` table; the registration then carries the installed
+ * version with the usual route-table digest, so two machines on the same
+ * unlisted-but-surface-identical release still agree. A miss refuses with
+ * the digest and the table's size in the message, for the logs.
  * @throws with a field-naming message on any illegal shape.
  */
-export function normalizeAdapter(input: unknown, installedVersion: string): NormalizedAdapter {
+export function normalizeAdapter(input: unknown, installedVersion: string, options?: { surfaceDigest?: string }): NormalizedAdapter {
   if (!isRecord(input)) fail('adapter', 'expected an object')
   for (const key of Object.keys(input)) {
-    if (key !== 'plugin' && key !== 'versions' && key !== 'routes' && key !== 'client' && key !== 'server') {
+    if (key !== 'plugin' && key !== 'versions' && key !== 'routes' && key !== 'client' && key !== 'server' && key !== 'surfaces') {
       fail(key, 'unknown field (typo guard)')
     }
   }
@@ -203,8 +211,21 @@ export function normalizeAdapter(input: unknown, installedVersion: string): Norm
   if (!Array.isArray(versions) || versions.length === 0 || versions.some((v) => typeof v !== 'string' || v === '')) {
     fail('versions', 'must be a non-empty array of version strings')
   }
+  // The surfaces table is validated whenever present, listed version or not
+  // (a malformed credential must not lurk until the one version that needs it).
+  if (input.surfaces !== undefined) {
+    if (!isRecord(input.surfaces)) fail('surfaces', 'expected an object (digest16 → remark)')
+    for (const [key, value] of Object.entries(input.surfaces)) {
+      if (!/^[0-9a-f]{16}$/u.test(key)) fail(`surfaces.${key}`, 'the key must be a 16-hex surface digest')
+      if (typeof value !== 'string' || value === '') fail(`surfaces.${key}`, 'the remark must be a non-empty string')
+    }
+  }
   if (!versions.includes(installedVersion)) {
-    fail('versions', `installed version "${installedVersion}" is not among the adapter's versions`)
+    const surfaceDigest = options?.surfaceDigest
+    const surfaces = input.surfaces as Record<string, string> | undefined
+    if (!(surfaceDigest !== undefined && surfaces !== undefined && Object.hasOwn(surfaces, surfaceDigest))) {
+      fail('versions', `installed version "${installedVersion}" is not among the adapter's versions (surface ${surfaceDigest ?? 'not computed'} vs ${surfaces === undefined ? 0 : Object.keys(surfaces).length} listed)`)
+    }
   }
   if (!Array.isArray(routes) || routes.length === 0) fail('routes', 'must be a non-empty array')
   if (routes.length > MAX_ROUTES) fail('routes', `${routes.length} routes exceeds the ${MAX_ROUTES} cap`)
@@ -350,13 +371,47 @@ export function adapterDigestOf(plugin: string, version: string, routes: Normali
   return createHash('sha256').update(canonical, 'utf8').digest('hex').slice(0, 16)
 }
 
-/** The prefix-match rule, shared verbatim by both halves: equality or one
- * path segment deeper, on the RAW undecoded pathname. */
+/** The prefix-match rule, shared verbatim by both halves: equality, or any
+ * deeper sub-path (`startsWith(path + '/')`), on the RAW undecoded pathname. */
 export function adapterPathMatches(route: NormalizedAdapterRoute, pathname: string): boolean {
   if (route.match === 'exact') return pathname === route.path
   return pathname === route.path || pathname.startsWith(`${route.path}/`)
 }
 
+/** The prefix TAIL's shape red line (PB-23b): the part of the RAW pathname
+ * AFTER a matched prefix path — the variable tail prefix matching admits —
+ * refuses `?`, `#`, `..` and whitespace. Exact equality inherited these
+ * declaration-side red lines structurally (the declared path itself passed
+ * them at registration); a prefix hit forwards an arbitrary tail straight
+ * into the loopback request line, so the tail carries them itself. A `?`
+ * would break the parse-once query discipline (the loopback appends ITS
+ * `?query`, and a host splits at the FIRST `?` — the unchecked part would
+ * ride in as query); a `#` is fragment garbage in the request line;
+ * whitespace mirrors the declaration rule. `..` is refused RAW and in its
+ * `%2e`/`%2E` encoding — ANY encoded dot, not just the `%2e%2e` pair, since
+ * a mixed form like `.%2e.` decodes to dot-dot and would slip a pair-only
+ * check. The verdict deliberately runs on the RAW bytes (reject-on-sight),
+ * not decode-then-check: `.` is RFC 3986-unreserved, so no legitimate
+ * encoder — including this module's own `encodeURIComponent` rewrite — ever
+ * produces `%2e`, while a decoded verdict would depend on the decode depth
+ * (`%252e%252e` survives one decode) and on malformed-escape handling,
+ * i.e. on exactly the host-decoder behavior this red line exists because it
+ * is NOT pinned. The check is tail-only because a declaration may legally
+ * carry `%` (only these four shapes are refused at registration) — judging
+ * the whole pathname would retro-illegalize blessed declarations. Both
+ * halves answer the refusal with 400 `bad-request`, the coordinate-shape
+ * code the entries already use (no client classifies on it). */
+const TAIL_SHAPE_VIOLATION = /[?#\s]|\.\.|%2e/iu
+
+/** Whether {@link adapterPathMatches} hit via a deeper tail whose shape
+ * breaks the red line — `false` for a non-match (the caller's routing
+ * refusal answers first) and for an equality hit (no tail at all). */
+export function adapterTailShapeViolation(route: NormalizedAdapterRoute, pathname: string): boolean {
+  if (!adapterPathMatches(route, pathname)) return false
+  if (pathname === route.path) return false
+  return TAIL_SHAPE_VIOLATION.test(pathname.slice(route.path.length))
+}
+
 /** The adapter route a forwarded request hit, or `undefined`. `local`
  * routes never match here — they stay on the sub-client's own machine in
  * both directions, so the server half must never see (nor serve) them. */