dsh-zen-remote 2.3.3 → 2.3.5

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. */

package/src/plugin-bridge.ts

@@ -11,7 +11,9 @@
  * ({@link createBridgeRegistry}), and the local-vs-server comparison that a
  * later task feeds handshake data into ({@link compareBridges}).
  *
- * Pure logic by design: no DSH imports, no I/O, no clocks — the digest is
+ * Pure logic by design: no DSH imports (the one exception is the
+ * pure-constants src/upload-limits.ts, itself zero-import), no I/O, no
+ * clocks — the digest is
  * the only place node:crypto appears, which is fine because this module only
  * ever runs in the backend process. Nothing here talks to the relay or the
  * network; the handshake side and the request rewrite side are later tasks
@@ -19,6 +21,7 @@
  */
 
 import { createHash } from 'node:crypto'
+import { MAX_UPLOAD_BYTES } from './upload-limits.js'
 
 /** Where a bridged route's caller supplies the session id. `'session'` — the
  * data is scoped to one session, forwarded after the server checks the share.
@@ -30,12 +33,48 @@ export type BridgeScope = 'session' | 'server'
  * only; the write methods arrived with the `methods` field. */
 export const BRIDGE_METHODS = ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE'] as const
 
-/** The body cap a route may declare (`maxBody`), in bytes: 64 MiB. */
-export const MAX_ROUTE_BODY_BYTES = 64 * 1024 * 1024
+/** The body cap a route may declare (`maxBody`), in bytes. This is the SAME
+ * single 500 MiB ceiling {@link MAX_UPLOAD_BYTES} defines in
+ * src/upload-limits.ts, re-exported under the bridge-local name so existing
+ * consumers stay untouched: three ceilings that used to be three numbers —
+ * the relay's `/v1/upload` route, the sub-client's streaming upload forward
+ * (both reading upload-limits.ts directly) and this bridge `maxBody` cap
+ * (hand-copied 64 MiB before declaration-v2) — now share one definition, so
+ * they can never drift apart again. */
+export { MAX_UPLOAD_BYTES as MAX_ROUTE_BODY_BYTES }
 
 /** The body cap a route gets when it declares none: 1 MiB. */
 export const DEFAULT_ROUTE_BODY_BYTES = 1024 * 1024
 
+/** The `fields` form of a route's `rewriteIds` (PB-25a): the DOT PATHS where
+ * the response's NEWLY-CREATED session ids sit — ids a creation route mints
+ * (`sidechat.start`'s `childId`), which were never in the request and so are
+ * invisible to the value deep-scan. Each path walks objects only: segments
+ * of `[A-Za-z0-9_-]`, non-empty, no wildcards, no numeric (array-index)
+ * segments — array elements stay the value scan's business. */
+export interface BridgeRewriteFields {
+  fields: readonly string[]
+}
+
+/** A route's `rewriteIds` value: `true` — deep-scan the answer for the
+ * request's own ids (the 2.4 echo shape) — or the {@link BridgeRewriteFields}
+ * object, which adds the position-based rewrite on top. The two are
+ * DIFFERENT declarations: each hashes its own way, and an old `true`
+ * declaration's digest is bit-for-bit what it always was. */
+export type BridgeRewriteIds = true | BridgeRewriteFields
+
+/** Where a bridged route's caller supplies the session id — the `locator`
+ * field (declaration-v2). The same three shapes as the adapter core's
+ * `AdapterLocator`: `query` names the search parameter; `path-segment`
+ * counts segments AFTER the declared path (a `prefix` route's variable
+ * part); `json-body` names TOP-LEVEL fields of the parsed JSON request
+ * body. A route without a locator keeps the 2.1 behavior: the session id
+ * rides the query parameter named `sessionParam`. */
+export type BridgeLocator =
+  | { in: 'query'; name: string }
+  | { in: 'path-segment'; index: number }
+  | { in: 'json-body'; fields: string[] }
+
 /** One forwardable route as a plugin declares it. `sessionParam` names the
  * URL query parameter carrying the session id (default `'sessionId'`);
  * `stream` marks routes answered as an event stream rather than one JSON
@@ -45,7 +84,19 @@ export const DEFAULT_ROUTE_BODY_BYTES = 1024 * 1024
  * (PB-9) caps the forwarded request body in bytes; omitted means
  * {@link DEFAULT_ROUTE_BODY_BYTES}. `upgrade` (PB-10) marks the route as a
  * WebSocket endpoint carried over the byte tunnel — GET-only, mutually
- * exclusive with `stream`. */
+ * exclusive with `stream`.
+ *
+ * The four declaration-v2 fields: `locator` replaces the query-parameter
+ * session-id convention with an explicit {@link BridgeLocator} (mutually
+ * exclusive with `sessionParam`); `prefix: true` admits the route's
+ * variable path tail (sub-paths under `path`) — required for a
+ * `path-segment` locator, refused together with `upgrade` for now; `deny:
+ * true` marks a route the sub-client refuses to serve from a REMOTE
+ * is local-only data); `rewriteIds` asks the sub-client to rewrite
+ * real↔virtual session ids inside the JSON it forwards — `true` deep-scans
+ * for the request's own ids, `{ fields }` additionally wraps the
+ * NEWLY-CREATED ids sitting at the declared positions (PB-25a) — never
+ * legal on a `stream` route, whose response is never buffered. */
 export interface BridgeRoute {
   path: string
   scope: BridgeScope
@@ -54,6 +105,10 @@ export interface BridgeRoute {
   methods?: readonly string[]
   maxBody?: number
   upgrade?: boolean
+  locator?: BridgeLocator
+  prefix?: boolean
+  deny?: boolean
+  rewriteIds?: BridgeRewriteIds
 }
 
 /** What a plugin hands `zenRemote.bridge(...)` — the raw, unvalidated shape. */
@@ -68,7 +123,11 @@ export interface BridgeDeclaration {
  * explicitly — the distinction is load-bearing for the digest (see the
  * canonical form in {@link normalizeDeclaration}), while consumers read the
  * EFFECTIVE values through {@link routeMethodsOf} / {@link routeMaxBodyOf}
- * / {@link routeUpgradesOf}. */
+ * / {@link routeUpgradesOf}. The four declaration-v2 fields (`locator`,
+ * `prefix`, `deny`, `rewriteIds`) follow the same explicit-only rule, and
+ * each carries its own effective reader:
+ * {@link routeLocatorOf} / {@link routePrefixOf} / {@link routeDeniesRemoteOf}
+ * / {@link routeRewritesIdsOf} / {@link routeRewriteFieldsOf}. */
 export interface NormalizedBridgeRoute {
   path: string
   scope: BridgeScope
@@ -77,6 +136,12 @@ export interface NormalizedBridgeRoute {
   methods: string[] | undefined
   maxBody: number | undefined
   upgrade: boolean | undefined
+  /** Present only when declared — an ABSENT key (not a `locator: undefined`
+   * key) keeps the digest-compatible shape and deep-equality of 2.1 routes. */
+  locator?: BridgeLocator
+  prefix?: true
+  deny?: true
+  rewriteIds?: BridgeRewriteIds
 }
 
 /** The effective upgrade mark of one normalized route. */
@@ -94,6 +159,41 @@ export function routeMaxBodyOf(route: NormalizedBridgeRoute): number {
   return route.maxBody ?? DEFAULT_ROUTE_BODY_BYTES
 }
 
+/** The effective session-id locator of one normalized route. A route that
+ * declared none keeps the 2.1 convention: the session id rides the query
+ * parameter named by `sessionParam`. */
+export function routeLocatorOf(route: NormalizedBridgeRoute): BridgeLocator {
+  return route.locator ?? { in: 'query', name: route.sessionParam }
+}
+
+/** The effective prefix mark of one normalized route: does the route admit
+ * its variable path tail (sub-paths under `path`)? */
+export function routePrefixOf(route: NormalizedBridgeRoute): boolean {
+  return route.prefix === true
+}
+
+/** The effective remote-deny mark of one normalized route: must this route
+ * refuse to serve a REMOTE session (local-only data)? */
+export function routeDeniesRemoteOf(route: NormalizedBridgeRoute): boolean {
+  return route.deny === true
+}
+
+/** The effective id-rewrite mark of one normalized route: does the
+ * sub-client rewrite real↔virtual session ids while forwarding? Both
+ * `rewriteIds` forms enable it (`true` and `{ fields }` alike) — which form
+ * decides only whether the POSITION rewrite joins the value scan. */
+export function routeRewritesIdsOf(route: NormalizedBridgeRoute): boolean {
+  return route.rewriteIds !== undefined
+}
+
+/** The declared field paths of a `{ fields }`-form `rewriteIds` route
+ * (PB-25a) — where the response's NEWLY-CREATED session ids sit. `undefined`
+ * for a `true` route and for a route without the field: the position
+ * rewrite exists only when explicitly declared. */
+export function routeRewriteFieldsOf(route: NormalizedBridgeRoute): readonly string[] | undefined {
+  return typeof route.rewriteIds === 'object' ? route.rewriteIds.fields : undefined
+}
+
 /** A declaration after validation: every route field filled, routes sorted
  * by path, and the 16-hex-char digest both ends will compare. */
 export interface NormalizedDeclaration {
@@ -119,6 +219,13 @@ const PLUGIN_PATTERN = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u
 /** Query-parameter name carrying the session id. */
 const SESSION_PARAM_PATTERN = /^[A-Za-z][A-Za-z0-9_]{0,63}$/u
 
+/** One dot-path segment of a `rewriteIds: { fields }` declaration (PB-25a):
+ * `[A-Za-z0-9_-]`, non-empty. The full path splits on `.`; a segment of
+ * ONLY digits is an array index and refused separately below — array
+ * elements are the value deep-scan's business, and a declaration that could
+ * never match (the position rewrite walks objects only) must not register. */
+const REWRITE_FIELD_SEGMENT_PATTERN = /^[A-Za-z0-9_-]+$/u
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
@@ -162,11 +269,11 @@ export function normalizeDeclaration(input: unknown): NormalizedDeclaration {
   const normalizedRoutes = routes.map((route, index): NormalizedBridgeRoute => {
     if (!isPlainObject(route)) fail(`routes[${index}]`, 'expected an object')
     for (const key of Object.keys(route)) {
-      if (key !== 'path' && key !== 'scope' && key !== 'sessionParam' && key !== 'stream' && key !== 'methods' && key !== 'maxBody' && key !== 'upgrade') {
+      if (key !== 'path' && key !== 'scope' && key !== 'sessionParam' && key !== 'stream' && key !== 'methods' && key !== 'maxBody' && key !== 'upgrade' && key !== 'locator' && key !== 'prefix' && key !== 'deny' && key !== 'rewriteIds') {
         fail(`routes[${index}].${key}`, 'unknown field (typo guard)')
       }
     }
-    const { path, scope, sessionParam, stream, methods, maxBody, upgrade } = route
+    const { path, scope, sessionParam, stream, methods, maxBody, upgrade, locator, prefix, deny, rewriteIds } = route
     if (typeof path !== 'string' || path === '') fail(`routes[${index}].path`, 'must be a non-empty string')
     if (!path.startsWith('/')) fail(`routes[${index}].path`, `"${path}" must start with "/"`)
     if (path.includes('?')) fail(`routes[${index}].path`, `"${path}" must not contain "?"`)
@@ -215,8 +322,8 @@ export function normalizeDeclaration(input: unknown): NormalizedDeclaration {
     // default.
     let normalizedMaxBody: number | undefined
     if (maxBody !== undefined) {
-      if (typeof maxBody !== 'number' || !Number.isInteger(maxBody) || maxBody <= 0 || maxBody > MAX_ROUTE_BODY_BYTES) {
-        fail(`routes[${index}].maxBody`, `must be a positive integer up to ${MAX_ROUTE_BODY_BYTES}`)
+      if (typeof maxBody !== 'number' || !Number.isInteger(maxBody) || maxBody <= 0 || maxBody > MAX_UPLOAD_BYTES) {
+        fail(`routes[${index}].maxBody`, `must be a positive integer up to ${MAX_UPLOAD_BYTES}`)
       }
       normalizedMaxBody = maxBody
     }
@@ -224,6 +331,15 @@ export function normalizeDeclaration(input: unknown): NormalizedDeclaration {
     // declaration, not a toggle), it cannot coexist with `stream` (a route
     // is one thing), and it is GET-only — an explicit `methods` naming
     // anything else cannot be an upgrade route.
+    // PB-20: `prefix` — a declaration that the route admits its variable
+    // path tail (sub-paths under `path`), required by a `path-segment`
+    // locator below and refused next to `upgrade` (checked in the upgrade
+    // block). Only `true` is legal — this is a declaration, not a toggle.
+    let normalizedPrefix: true | undefined
+    if (prefix !== undefined) {
+      if (prefix !== true) fail(`routes[${index}].prefix`, 'must be true or omitted')
+      normalizedPrefix = true
+    }
     let normalizedUpgrade: boolean | undefined
     if (upgrade !== undefined) {
       if (upgrade !== true) fail(`routes[${index}].upgrade`, 'must be true or omitted')
@@ -231,18 +347,112 @@ export function normalizeDeclaration(input: unknown): NormalizedDeclaration {
       if (normalizedMethods !== undefined && normalizedMethods.some((entry) => entry !== 'GET')) {
         fail(`routes[${index}].upgrade`, 'upgrade routes are GET-only')
       }
+      if (normalizedPrefix === true) {
+        fail(`routes[${index}].prefix`, 'cannot be combined with upgrade — a WebSocket tunnel over a prefix route is left for when a need shows up')
+      }
       normalizedUpgrade = true
     }
-    return { path, scope, sessionParam: param, stream: streamFlag, methods: normalizedMethods, maxBody: normalizedMaxBody, upgrade: normalizedUpgrade }
+    // PB-20: `locator` — where the session id lives, REPLACING the
+    // query-parameter convention (so the two fields can never coexist; a
+    // route without one keeps `sessionParam`'s 2.1 semantics). Shapes and
+    // the path-segment/prefix pairing mirror the adapter core's locator
+    // (PB-11) so the two ends read identically.
+    let normalizedLocator: BridgeLocator | undefined
+    if (locator !== undefined) {
+      if (sessionParam !== undefined) {
+        fail(`routes[${index}].locator`, 'cannot be combined with sessionParam — a route locates its session id one way')
+      }
+      if (!isPlainObject(locator)) fail(`routes[${index}].locator`, 'expected an object')
+      if (locator.in === 'query') {
+        if (typeof locator.name !== 'string' || !SESSION_PARAM_PATTERN.test(locator.name)) {
+          fail(`routes[${index}].locator.name`, `"${String(locator.name)}" must match ${SESSION_PARAM_PATTERN.source}`)
+        }
+        normalizedLocator = { in: 'query', name: locator.name }
+      } else if (locator.in === 'path-segment') {
+        if (typeof locator.index !== 'number' || !Number.isInteger(locator.index) || locator.index < 0) {
+          fail(`routes[${index}].locator.index`, 'must be a non-negative integer')
+        }
+        if (normalizedPrefix !== true) {
+          fail(`routes[${index}].locator`, 'path-segment locating needs prefix: true (the id lives in the variable tail only a prefix route admits)')
+        }
+        normalizedLocator = { in: 'path-segment', index: locator.index }
+      } else if (locator.in === 'json-body') {
+        if (!Array.isArray(locator.fields) || locator.fields.length === 0 || locator.fields.some((entry) => typeof entry !== 'string' || entry === '')) {
+          fail(`routes[${index}].locator.fields`, 'must be a non-empty array of field names')
+        }
+        normalizedLocator = { in: 'json-body', fields: [...locator.fields] }
+      } else {
+        fail(`routes[${index}].locator.in`, 'must be "query", "path-segment" or "json-body"')
+      }
+    }
+    // PB-20: `deny` — the route must refuse a REMOTE session (its data is
+    // local-only). Only `true` is legal.
+    let normalizedDeny: true | undefined
+    if (deny !== undefined) {
+      if (deny !== true) fail(`routes[${index}].deny`, 'must be true or omitted')
+      normalizedDeny = true
+    }
+    // PB-20/PB-25a: `rewriteIds` — the sub-client rewrites real↔virtual
+    // session ids while forwarding. Two forms: `true` (the 2.4 echo shape —
+    // the value deep-scan over the request's own ids) and `{ fields }`
+    // (PB-25a — adds the position rewrite where NEWLY-CREATED ids sit).
+    // Never legal on a stream route: a streaming response is never buffered,
+    // so there is nothing to rewrite. The two forms hash DIFFERENTLY (see
+    // the canonical form below); an old `true` declaration's digest is
+    // bit-for-bit what it always was.
+    let normalizedRewriteIds: BridgeRewriteIds | undefined
+    if (rewriteIds !== undefined) {
+      if (rewriteIds === true) {
+        normalizedRewriteIds = true
+      } else if (isPlainObject(rewriteIds)) {
+        for (const key of Object.keys(rewriteIds)) {
+          if (key !== 'fields') fail(`routes[${index}].rewriteIds.${key}`, 'unknown field (typo guard)')
+        }
+        const { fields } = rewriteIds
+        if (!Array.isArray(fields) || fields.length === 0 || fields.some((entry) => typeof entry !== 'string')) {
+          fail(`routes[${index}].rewriteIds.fields`, 'must be a non-empty array of dot paths')
+        }
+        for (const entry of fields as string[]) {
+          const segments = entry.split('.')
+          if (segments.some((segment) => !REWRITE_FIELD_SEGMENT_PATTERN.test(segment))) {
+            fail(`routes[${index}].rewriteIds.fields`, `"${entry}" must be a dot path of non-empty [A-Za-z0-9_-] segments`)
+          }
+          if (segments.some((segment) => /^\d+$/u.test(segment))) {
+            fail(`routes[${index}].rewriteIds.fields`, `"${entry}" must not carry an array index — array elements are the value deep-scan's business`)
+          }
+        }
+        normalizedRewriteIds = { fields: [...fields] }
+      } else {
+        fail(`routes[${index}].rewriteIds`, 'must be true, { fields: [...] } or omitted')
+      }
+      if (streamFlag) fail(`routes[${index}].rewriteIds`, 'cannot be combined with stream — a streaming response is never buffered, so there are no ids to rewrite')
+    }
+    // Explicit-only (digest rule): the four v2 fields attach to the
+    // normalized route ONLY when declared — an absent key, not an
+    // `undefined` one, so the canonical form and the deep-equality shape of
+    // 2.1-era routes stay byte-for-byte what they were.
+    return {
+      path,
+      scope,
+      sessionParam: param,
+      stream: streamFlag,
+      methods: normalizedMethods,
+      maxBody: normalizedMaxBody,
+      upgrade: normalizedUpgrade,
+      ...(normalizedLocator !== undefined && { locator: normalizedLocator }),
+      ...(normalizedPrefix && { prefix: normalizedPrefix }),
+      ...(normalizedDeny && { deny: normalizedDeny }),
+      ...(normalizedRewriteIds && { rewriteIds: normalizedRewriteIds }),
+    }
   })
   normalizedRoutes.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
 
   // Fixed key order = the canonical form both ends hash; insertion order of
   // the object literal IS the contract, JSON.stringify never sorts. The
-  // route entries carry `methods` / `maxBody` ONLY when the plugin declared
-  // them — `JSON.stringify` drops `undefined` values, but the explicit
-  // conditional documents the intent and keeps the PB-1 compatibility
-  // visible instead of incidental.
+  // route entries carry `methods` / `maxBody` / `upgrade` and the four v2
+  // fields ONLY when the plugin declared them — `JSON.stringify` drops
+  // `undefined` values, but the explicit conditional documents the intent
+  // and keeps the PB-1 compatibility visible instead of incidental.
   const canonical = JSON.stringify({
     plugin,
     version,
@@ -256,6 +466,10 @@ export function normalizeDeclaration(input: unknown): NormalizedDeclaration {
       if (route.methods !== undefined) entry.methods = route.methods
       if (route.maxBody !== undefined) entry.maxBody = route.maxBody
       if (route.upgrade !== undefined) entry.upgrade = route.upgrade
+      if (route.locator !== undefined) entry.locator = route.locator
+      if (route.prefix !== undefined) entry.prefix = route.prefix
+      if (route.deny !== undefined) entry.deny = route.deny
+      if (route.rewriteIds !== undefined) entry.rewriteIds = route.rewriteIds
       return entry
     }),
   })