@nifrajs/core 1.7.0 → 1.8.0

package/src/assurance.ts

@@ -0,0 +1,263 @@
+/**
+ * Route assurance: reflection-time proof that every route is classified and carries the enforcement
+ * evidence its policy requires. Evaluation is pure and never runs on the request hot path.
+ */
+
+import type {
+  AssuranceDeclaration,
+  AssuranceEvidence,
+  AssuranceScope,
+} from "./internal/route-assurance.ts"
+import {
+  NIFRA_ASSURANCE_IDS,
+  routeGlob,
+  validEvidenceId,
+  validMethod,
+  withRouteAssurance,
+} from "./internal/route-assurance.ts"
+import { type ReflectedRoute, reflectRoutes } from "./reflection.ts"
+import type { Method } from "./router/router.ts"
+
+export type { AssuranceDeclaration, AssuranceEvidence, AssuranceScope }
+export { withRouteAssurance }
+
+/** Canonical evidence ids emitted by Nifra's official middleware modules. */
+export const NIFRA_ASSURANCE = NIFRA_ASSURANCE_IDS
+
+export interface AssuranceRouteSelector {
+  /** Omit for every method. */
+  readonly methods?: readonly Method[]
+  /** Absolute route globs. `*` matches one segment; final `**` matches zero or more. */
+  readonly paths?: readonly string[]
+  /** Restrict the rule to MCP tool routes (`true`) or non-tool routes (`false`). */
+  readonly tools?: boolean
+}
+
+export interface AssuranceRule {
+  /** Stable human-readable classification included in diagnostics. */
+  readonly name: string
+  readonly match: AssuranceRouteSelector
+  /** Evidence ids the route must carry. */
+  readonly require?: readonly string[]
+  /** Evidence ids the route must not carry (useful for public webhooks and health routes). */
+  readonly forbid?: readonly string[]
+}
+
+export interface AssurancePolicy {
+  /** First matching rule owns a route. Put exceptions before broad defaults. */
+  readonly rules: readonly AssuranceRule[]
+  /** Default `error`: an unclassified route fails closed. */
+  readonly unmatched?: "error" | "ignore"
+  /** Default false: reject an empty reflected source so a wrong import cannot pass CI silently. */
+  readonly allowEmpty?: boolean
+}
+
+export type AssuranceFindingCode =
+  | "no-routes"
+  | "unclassified-route"
+  | "missing-evidence"
+  | "forbidden-evidence"
+
+export interface AssuranceFinding {
+  readonly code: AssuranceFindingCode
+  readonly method: string
+  readonly path: string
+  readonly rule?: string
+  readonly evidence?: string
+  readonly message: string
+}
+
+export interface AssuredRoute {
+  readonly method: string
+  readonly path: string
+  readonly rule?: string
+  readonly evidence: readonly AssuranceEvidence[]
+  readonly missing: readonly string[]
+  readonly forbidden: readonly string[]
+}
+
+export interface AssuranceReport {
+  readonly ok: boolean
+  readonly routes: readonly AssuredRoute[]
+  readonly findings: readonly AssuranceFinding[]
+}
+
+export interface AssuranceConfig {
+  readonly source: unknown
+  readonly policy: AssurancePolicy
+}
+
+const nonEmpty = (value: string): boolean => value.trim() !== ""
+
+function normalizeEvidenceIds(
+  values: readonly string[] | undefined,
+  label: string,
+): readonly string[] {
+  const out: string[] = []
+  const seen = new Set<string>()
+  for (const value of values ?? []) {
+    if (!validEvidenceId(value)) {
+      throw new Error(`route assurance: invalid ${label} evidence id ${JSON.stringify(value)}`)
+    }
+    if (!seen.has(value)) {
+      seen.add(value)
+      out.push(value)
+    }
+  }
+  return Object.freeze(out)
+}
+
+/** Validate and freeze an ordered assurance policy. */
+export function defineAssurancePolicy(policy: AssurancePolicy): AssurancePolicy {
+  if (
+    policy.unmatched !== undefined &&
+    policy.unmatched !== "error" &&
+    policy.unmatched !== "ignore"
+  ) {
+    throw new Error(`route assurance: invalid unmatched mode ${JSON.stringify(policy.unmatched)}`)
+  }
+  if (policy.allowEmpty !== undefined && typeof policy.allowEmpty !== "boolean") {
+    throw new Error(`route assurance: allowEmpty must be boolean`)
+  }
+  const names = new Set<string>()
+  const rules = policy.rules.map((rule): AssuranceRule => {
+    if (typeof rule.name !== "string" || !nonEmpty(rule.name)) {
+      throw new Error("route assurance: rule name must be non-empty")
+    }
+    const name = rule.name.trim()
+    if (names.has(name))
+      throw new Error(`route assurance: duplicate rule name ${JSON.stringify(name)}`)
+    names.add(name)
+    if (rule.match.tools !== undefined && typeof rule.match.tools !== "boolean") {
+      throw new Error(
+        `route assurance: rule ${JSON.stringify(name)} tools selector must be boolean`,
+      )
+    }
+    const methods = rule.match.methods?.map((method) => method.toUpperCase())
+    for (const method of methods ?? []) {
+      if (!validMethod(method)) {
+        throw new Error(`route assurance: unsupported HTTP method ${JSON.stringify(method)}`)
+      }
+    }
+    const paths = rule.match.paths?.map((path) => {
+      routeGlob(path)
+      return path
+    })
+    const required = normalizeEvidenceIds(rule.require, "required")
+    const forbidden = normalizeEvidenceIds(rule.forbid, "forbidden")
+    const overlap = required.find((id) => forbidden.includes(id))
+    if (overlap !== undefined) {
+      throw new Error(
+        `route assurance: rule ${JSON.stringify(name)} both requires and forbids ${overlap}`,
+      )
+    }
+    return Object.freeze({
+      name,
+      match: Object.freeze({
+        ...(methods !== undefined ? { methods: Object.freeze(methods as Method[]) } : {}),
+        ...(paths !== undefined ? { paths: Object.freeze(paths) } : {}),
+        ...(rule.match.tools !== undefined ? { tools: rule.match.tools } : {}),
+      }),
+      require: required,
+      forbid: forbidden,
+    })
+  })
+  return Object.freeze({
+    rules: Object.freeze(rules),
+    unmatched: policy.unmatched ?? "error",
+    allowEmpty: policy.allowEmpty ?? false,
+  })
+}
+
+/** Identity helper for a `nifra.assurance.ts` default export. */
+export function defineAssuranceConfig(config: AssuranceConfig): AssuranceConfig {
+  return Object.freeze({ source: config.source, policy: defineAssurancePolicy(config.policy) })
+}
+
+/** Shared selector semantics for policy rules and framework adapters. */
+export function matchesAssuranceSelector(
+  route: Pick<ReflectedRoute, "method" | "path" | "tool">,
+  selector: AssuranceRouteSelector,
+): boolean {
+  const { methods, paths, tools } = selector
+  if (methods !== undefined && !methods.includes(route.method as Method)) return false
+  if (paths !== undefined && !paths.some((pattern) => routeGlob(pattern).test(route.path)))
+    return false
+  if (tools !== undefined && (route.tool !== undefined) !== tools) return false
+  return true
+}
+
+/** Evaluate reflected route evidence against the first matching policy rule. */
+export function evaluateRouteAssurance(
+  source: unknown,
+  policyInput: AssurancePolicy,
+): AssuranceReport {
+  const policy = defineAssurancePolicy(policyInput)
+  const findings: AssuranceFinding[] = []
+  const routes: AssuredRoute[] = []
+  const reflected = reflectRoutes(source)
+
+  if (reflected.length === 0 && policy.allowEmpty !== true) {
+    findings.push({
+      code: "no-routes",
+      method: "*",
+      path: "*",
+      message: "route assurance source reflected zero routes (set allowEmpty: true if intentional)",
+    })
+  }
+
+  for (const route of reflected) {
+    const rule = policy.rules.find((candidate) => matchesAssuranceSelector(route, candidate.match))
+    const evidence = route.assurance ?? []
+    const evidenceIds = new Set(evidence.map((item) => item.id))
+    if (rule === undefined) {
+      if (policy.unmatched !== "ignore") {
+        findings.push({
+          code: "unclassified-route",
+          method: route.method,
+          path: route.path,
+          message: `${route.method} ${route.path} is not classified by an assurance rule`,
+        })
+      }
+      routes.push({ method: route.method, path: route.path, evidence, missing: [], forbidden: [] })
+      continue
+    }
+
+    const missing = (rule.require ?? []).filter((id) => !evidenceIds.has(id))
+    const forbidden = (rule.forbid ?? []).filter((id) => evidenceIds.has(id))
+    for (const id of missing) {
+      findings.push({
+        code: "missing-evidence",
+        method: route.method,
+        path: route.path,
+        rule: rule.name,
+        evidence: id,
+        message: `${route.method} ${route.path} (${rule.name}) is missing ${id}`,
+      })
+    }
+    for (const id of forbidden) {
+      findings.push({
+        code: "forbidden-evidence",
+        method: route.method,
+        path: route.path,
+        rule: rule.name,
+        evidence: id,
+        message: `${route.method} ${route.path} (${rule.name}) carries forbidden ${id}`,
+      })
+    }
+    routes.push({
+      method: route.method,
+      path: route.path,
+      rule: rule.name,
+      evidence,
+      missing: Object.freeze(missing),
+      forbidden: Object.freeze(forbidden),
+    })
+  }
+
+  return Object.freeze({
+    ok: findings.length === 0,
+    routes: Object.freeze(routes),
+    findings: Object.freeze(findings),
+  })
+}

package/src/index.ts

@@ -12,10 +12,11 @@
  * (it shipped at "0.0.0" through 1.0.0 before those guards existed). Kept narrow (`as const`) so
  * consumers can pin it at the type level — see `test/version.test-d.ts`.
  */
-export const VERSION = "1.7.0" as const
+export const VERSION = "1.8.0" as const
 
 export type Version = typeof VERSION
 
+export * from "./assurance.ts"
 export * from "./diff.ts"
 export { FrameworkError, RouteConfigError, type RouteConfigErrorCode } from "./errors.ts"
 export { FRAMEWORK_NAME, type FrameworkName } from "./internal/brand.ts"

package/src/internal/route-assurance.ts

@@ -0,0 +1,166 @@
+import { METHODS, type Method } from "../router/router.ts"
+
+/** Where enforcement evidence follows Nifra's route-registration semantics. */
+export type AssuranceScope = "global" | "subsequent" | "plugin"
+
+/** Reflection-safe proof that a named enforcement module covered a route. */
+export interface AssuranceEvidence {
+  readonly id: string
+  readonly source: string
+}
+
+/** Metadata installed on a middleware/plugin by {@link withRouteAssurance}. */
+export interface AssuranceDeclaration extends AssuranceEvidence {
+  readonly scope: AssuranceScope
+  /** Restrict evidence to these HTTP methods. Omit for every method. */
+  readonly methods?: readonly Method[]
+  /** Restrict evidence to these absolute route globs. Omit for every path. */
+  readonly paths?: readonly string[]
+}
+
+const EVIDENCE_ID = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/
+const METHOD_SET: ReadonlySet<string> = new Set(METHODS)
+const declarations = new WeakMap<object, readonly AssuranceDeclaration[]>()
+
+export const NIFRA_ASSURANCE_IDS = Object.freeze({
+  AUTHENTICATED: "nifra.authenticated",
+  BODY_BOUNDED: "nifra.body-bounded",
+  CSRF: "nifra.csrf",
+  IDEMPOTENCY_KEY: "nifra.idempotency-key",
+  IP_RESTRICTED: "nifra.ip-restricted",
+  RATE_LIMITED: "nifra.rate-limited",
+  SECURITY_HEADERS: "nifra.security-headers",
+} as const)
+
+const escapeRegex = (value: string): string => value.replace(/[|\\{}()[\]^$+?.-]/g, "\\$&")
+
+/** Compile an absolute route glob. `*` is one segment; `**` is zero or more segments. */
+export function routeGlob(pattern: string): RegExp {
+  if (!pattern.startsWith("/") || pattern.includes("?") || pattern.includes("#")) {
+    throw new Error(
+      `route assurance: path glob must be an absolute path: ${JSON.stringify(pattern)}`,
+    )
+  }
+  if (pattern === "/") return /^\/$/
+  const segments = pattern.slice(1).split("/")
+  let source = "^"
+  for (const [index, segment] of segments.entries()) {
+    if (segment === "**") {
+      if (index !== segments.length - 1) {
+        throw new Error(
+          `route assurance: ** must be the final path segment: ${JSON.stringify(pattern)}`,
+        )
+      }
+      source += "(?:/.*)?"
+    } else if (segment === "*") {
+      source += "/[^/]+"
+    } else {
+      if (segment.includes("*")) {
+        throw new Error(
+          `route assurance: * must occupy a whole path segment: ${JSON.stringify(pattern)}`,
+        )
+      }
+      source += `/${escapeRegex(segment)}`
+    }
+  }
+  return new RegExp(`${source}$`)
+}
+
+function normalizeDeclaration(value: AssuranceDeclaration): AssuranceDeclaration {
+  if (!EVIDENCE_ID.test(value.id)) {
+    throw new Error(
+      `route assurance: invalid evidence id ${JSON.stringify(value.id)} (use lowercase dot/dash segments)`,
+    )
+  }
+  if (typeof value.source !== "string" || value.source.trim() === "") {
+    throw new Error("route assurance: evidence source must be a non-empty string")
+  }
+  if (value.scope !== "global" && value.scope !== "subsequent" && value.scope !== "plugin") {
+    throw new Error(`route assurance: invalid scope ${JSON.stringify(value.scope)}`)
+  }
+  const methods = value.methods?.map((method) => method.toUpperCase())
+  for (const method of methods ?? []) {
+    if (!METHOD_SET.has(method)) {
+      throw new Error(`route assurance: unsupported HTTP method ${JSON.stringify(method)}`)
+    }
+  }
+  const paths = value.paths?.map((path) => {
+    routeGlob(path)
+    return path
+  })
+  return Object.freeze({
+    id: value.id,
+    source: value.source.trim(),
+    scope: value.scope,
+    ...(methods !== undefined ? { methods: Object.freeze(methods as Method[]) } : {}),
+    ...(paths !== undefined ? { paths: Object.freeze(paths) } : {}),
+  })
+}
+
+/** Attach enforcement evidence to the middleware/plugin that installs it. */
+export function withRouteAssurance<T extends object>(
+  target: T,
+  declaration: AssuranceDeclaration | readonly AssuranceDeclaration[],
+): T {
+  const values = Array.isArray(declaration) ? declaration : [declaration]
+  if (values.length === 0) throw new Error("route assurance: at least one declaration is required")
+  const previous = declarations.get(target) ?? []
+  declarations.set(
+    target,
+    Object.freeze([...previous, ...values.map((value) => normalizeDeclaration(value))]),
+  )
+  return target
+}
+
+export function assuranceDeclarationsOf(value: object): readonly AssuranceDeclaration[] {
+  return declarations.get(value) ?? []
+}
+
+export function declarationApplies(
+  declaration: AssuranceDeclaration,
+  method: string,
+  path: string,
+): boolean {
+  if (declaration.methods !== undefined && !declaration.methods.includes(method as Method))
+    return false
+  return (
+    declaration.paths === undefined ||
+    declaration.paths.some((pattern) => routeGlob(pattern).test(path))
+  )
+}
+
+export function assuranceEvidenceFor(
+  declarationsToApply: readonly AssuranceDeclaration[],
+  method: string,
+  path: string,
+): readonly AssuranceEvidence[] {
+  const seen = new Set<string>()
+  const evidence: AssuranceEvidence[] = []
+  for (const declaration of declarationsToApply) {
+    if (!declarationApplies(declaration, method, path)) continue
+    const key = `${declaration.id}\n${declaration.source}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    evidence.push(Object.freeze({ id: declaration.id, source: declaration.source }))
+  }
+  return Object.freeze(evidence)
+}
+
+export function validEvidence(value: unknown): value is AssuranceEvidence {
+  if (typeof value !== "object" || value === null) return false
+  const candidate = value as Partial<AssuranceEvidence>
+  return (
+    typeof candidate.id === "string" &&
+    EVIDENCE_ID.test(candidate.id) &&
+    typeof candidate.source === "string" &&
+    candidate.source.trim() !== ""
+  )
+}
+
+export function validEvidenceId(value: string): boolean {
+  return EVIDENCE_ID.test(value)
+}
+
+export function validMethod(value: string): value is Method {
+  return METHOD_SET.has(value.toUpperCase())
+}

package/src/reflection.ts

@@ -7,6 +7,7 @@
  * recognizes Nifra/TypeBox carriers and raw JSON Schema without depending on a validator package.
  */
 
+import { type AssuranceEvidence, validEvidence } from "./internal/route-assurance.ts"
 import type { StandardSchemaV1 } from "./schema/standard.ts"
 import type { ToolAnnotations } from "./server/server.ts"
 
@@ -43,6 +44,7 @@ export interface ReflectedRoute {
   readonly method: string
   readonly path: string
   readonly schema?: ReflectedRouteSchema
+  readonly assurance?: readonly AssuranceEvidence[]
   readonly tool?: {
     readonly name: string
     readonly description: string
@@ -97,7 +99,7 @@ const normalizeJsonSchema = (value: unknown): JsonSchema | undefined => {
     // carrier (a JSON Schema object that also carries `~standard`, with no separate `.jsonSchema`) would
     // otherwise leak the marker into emitted OpenAPI / mock / form output.
     if (!("~standard" in record)) return record
-    const { ["~standard"]: _omitted, ...rest } = record
+    const { "~standard": _omitted, ...rest } = record
     return rest
   } catch {
     return undefined
@@ -174,6 +176,14 @@ const reflectedTool = (value: unknown): ReflectedRoute["tool"] => {
   }
 }
 
+const reflectedAssurance = (value: unknown): readonly AssuranceEvidence[] | undefined => {
+  if (!Array.isArray(value)) return undefined
+  const evidence = value
+    .filter(validEvidence)
+    .map((item) => Object.freeze({ id: item.id, source: item.source.trim() }))
+  return evidence.length > 0 ? Object.freeze(evidence) : undefined
+}
+
 /**
  * Safely enumerate and normalize route descriptors from an app or descriptor array. Invalid entries
  * are ignored; a missing/throwing `routes()` method yields an empty array.
@@ -185,10 +195,12 @@ export function reflectRoutes(source: unknown): readonly ReflectedRoute[] {
     if (typeof route?.method !== "string" || typeof route.path !== "string") continue
     const schema = reflectedRouteSchema(route.schema)
     const tool = reflectedTool(route.tool)
+    const assurance = reflectedAssurance(route.assurance)
     reflected.push({
       method: route.method.toUpperCase(),
       path: route.path,
       ...(schema !== undefined ? { schema } : {}),
+      ...(assurance !== undefined ? { assurance } : {}),
       ...(tool !== undefined ? { tool } : {}),
     })
   }

package/src/server/registry.ts

@@ -78,14 +78,20 @@ export type OutputOf<H extends (...args: never[]) => unknown> = Exclude<
 /**
  * Merge a new route into the registry, combining methods that share a path.
  *
- * SCALING CEILING (measured, see many-routes.test-d.ts): each chained route call nests one alias
- * level (`AddRoute<AddRoute<...`), and TypeScript resolves the whole stack lazily in ONE
- * recursion on first demand — its instantiation-depth limit fires as TS2589 at ~95-100 calls on
- * a single server. Eager-flattening variants (mapped remap, `extends infer` force, phantom
- * constraint params) were all tried and either lower the ceiling or leave spurious diagnostics —
- * the lazy first-walk is not defeatable from library code. Past ~90 routes on one app, compose
- * instead: split into domain groups and `.merge()` them (each group resolves its own short
- * stack), or use contract-first `implement()` (a single object type — no accumulation at all).
+ * SCALING CEILING (measured — see many-routes.test-d.ts and the isolation study below): a single
+ * fluent chain hits TS2589 at ~95-100 routes. This intersection is NOT the cause — in isolation it
+ * accumulates 1000+ routes cleanly, and heavy per-route `Params<Path>`/schema inference alone
+ * reaches 600+. The wall is an INTERACTION unique to the fluent builder: each `.get(path, handler)`
+ * both (a) computes the handler's context type from the path (`c.params.id` inferred from `:id`)
+ * AND (b) returns `Server<AddRoute<growing-R, …>, Ctx>`. Neither alone strains the compiler; the
+ * PRODUCT — recomputing the handler context while re-threading the ever-larger registry at each of
+ * N steps — exhausts TypeScript's per-expression instantiation budget around N≈95. It is therefore
+ * O(N) and inherent to any builder that infers handler context AND accumulates a typed route
+ * registry (Elysia/tRPC/hono's typed clients cap the same way); it is not fixable by reshaping
+ * AddRoute. Past ~90 routes, use a path that DOESN'T form the product: split into domain groups and
+ * `.merge()` them (each group is a short chain; a merge is one `R & R2` intersection with no
+ * per-call context work), or contract-first `implement()` (the registry is one object type declared
+ * upfront — no grow-R-per-call, so no ceiling at all).
  */
 export type AddRoute<
   R extends Registry,

package/src/server/server.ts

@@ -1,4 +1,11 @@
 import { FrameworkError, RouteConfigError } from "../errors.ts"
+import {
+  type AssuranceDeclaration,
+  type AssuranceEvidence,
+  assuranceDeclarationsOf,
+  assuranceEvidenceFor,
+  NIFRA_ASSURANCE_IDS,
+} from "../internal/route-assurance.ts"
 import { EMPTY_PARAMS, type Method, Router } from "../router/router.ts"
 import type {
   InferOutput,
@@ -289,6 +296,8 @@ export interface RouteDescriptor {
   readonly method: Method
   readonly path: string
   readonly schema: RouteSchema | undefined
+  /** Effective enforcement evidence, populated only during reflection/introspection. */
+  readonly assurance?: readonly AssuranceEvidence[]
   readonly tool?: {
     readonly name: string
     readonly description: string
@@ -1126,6 +1135,10 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   private readonly responseRequests: WeakMap<Request, Request>
   /** Names of plugins/middleware already applied via `use` — for idempotent dedupe. */
   private readonly appliedPlugins: Set<string>
+  /** Order-scoped evidence captured by routes registered after an assured plugin. */
+  private readonly activeAssurance: AssuranceDeclaration[]
+  /** App-wide evidence from global hooks; applies retroactively to every route. */
+  private readonly globalAssurance: AssuranceDeclaration[]
   /** App-declared MCP resources / prompts (via {@link resource} / {@link prompt}), read by `nifra mcp`. */
   private readonly mcpResourceList: McpResourceDescriptor[]
   private readonly mcpPromptList: McpPromptDescriptor[]
@@ -1140,6 +1153,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     readonly path: string
     readonly entry: RouteEntry
     readonly descriptor: RouteDescriptor
+    readonly assurance: readonly AssuranceDeclaration[]
   }>
 
   constructor(options: ServerOptions = {}) {
@@ -1166,6 +1180,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     this.onResponseFinalizedHooks = []
     this.responseRequests = new WeakMap()
     this.appliedPlugins = new Set()
+    this.activeAssurance = []
+    this.globalAssurance = []
     this.mcpResourceList = []
     this.mcpPromptList = []
     this.rawEntries = []
@@ -1263,12 +1279,32 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         if (this.appliedPlugins.has(name)) return this // idempotent: already applied
         this.appliedPlugins.add(name)
       }
-      return arg(this)
+      const evidence = assuranceDeclarationsOf(arg)
+      const pluginOnly = evidence.filter((item) => item.scope === "plugin")
+      this.globalAssurance.push(...evidence.filter((item) => item.scope === "global"))
+      this.activeAssurance.push(...evidence.filter((item) => item.scope === "subsequent"))
+      this.activeAssurance.push(...pluginOnly)
+      try {
+        return arg(this)
+      } finally {
+        // Remove only this plugin's temporary evidence. Nested assured plugins may deliberately leave
+        // subsequent evidence active, so truncating the whole array would lose real ordering semantics.
+        for (const item of pluginOnly) {
+          const index = this.activeAssurance.indexOf(item)
+          if (index !== -1) this.activeAssurance.splice(index, 1)
+        }
+      }
     }
     if (arg.name !== undefined) {
       if (this.appliedPlugins.has(arg.name)) return this
       this.appliedPlugins.add(arg.name)
     }
+    const evidence = assuranceDeclarationsOf(arg)
+    if (evidence.some((item) => item.scope === "plugin")) {
+      throw new Error('route assurance: scope "plugin" may only annotate a plugin function')
+    }
+    this.globalAssurance.push(...evidence.filter((item) => item.scope === "global"))
+    this.activeAssurance.push(...evidence.filter((item) => item.scope === "subsequent"))
     if (arg.onRequest !== undefined) this.onRequest(arg.onRequest)
     if (arg.around !== undefined) this.around(arg.around)
     if (arg.beforeHandle !== undefined) this.beforeHandle(arg.beforeHandle)
@@ -1633,7 +1669,23 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     this.router.add(method, path, entry)
     const descriptor: RouteDescriptor = { method, path, schema }
     this.routeList.push(descriptor)
-    this.rawEntries.push({ method, path, entry, descriptor })
+    const routeAssurance: AssuranceDeclaration[] = [...this.activeAssurance]
+    if (schema?.body !== undefined) {
+      routeAssurance.push(
+        Object.freeze({
+          id: NIFRA_ASSURANCE_IDS.BODY_BOUNDED,
+          source: "route-schema",
+          scope: "plugin",
+        }),
+      )
+    }
+    this.rawEntries.push({
+      method,
+      path,
+      entry,
+      descriptor,
+      assurance: Object.freeze(routeAssurance),
+    })
   }
 
   /**
@@ -1663,14 +1715,15 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         "merge() does not carry WebSocket routes — register .ws() routes on the parent server",
       )
     }
-    for (const { method, path, entry, descriptor } of source.rawEntries) {
+    for (const { method, path, entry, descriptor, assurance } of source.rawEntries) {
       this.router.add(method, path, entry) // throws RouteConfigError on a duplicate — fail closed
       this.routeList.push(descriptor) // shared ref on purpose: carries later .tool() tagging
-      this.rawEntries.push({ method, path, entry, descriptor })
+      this.rawEntries.push({ method, path, entry, descriptor, assurance })
     }
     this.onRequestHooks.push(...source.onRequestHooks)
     this.onResponseHooks.push(...source.onResponseHooks)
     this.onResponseFinalizedHooks.push(...source.onResponseFinalizedHooks)
+    this.globalAssurance.push(...source.globalAssurance)
     this.mcpResourceList.push(...source.mcpResourceList)
     this.mcpPromptList.push(...source.mcpPromptList)
     return this as unknown as Server<R & R2, Ctx>
@@ -1682,7 +1735,14 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    * longer holds the original patterns.
    */
   routes(): ReadonlyArray<RouteDescriptor> {
-    return this.routeList
+    if (this.activeAssurance.length === 0 && this.globalAssurance.length === 0) {
+      const anyRouteEvidence = this.rawEntries.some((entry) => entry.assurance.length > 0)
+      if (!anyRouteEvidence) return this.routeList
+    }
+    return this.rawEntries.map(({ method, path, descriptor, assurance }) => {
+      const effective = assuranceEvidenceFor([...assurance, ...this.globalAssurance], method, path)
+      return effective.length > 0 ? { ...descriptor, assurance: effective } : descriptor
+    })
   }
 
   /**