@nifrajs/core 2.2.0 → 2.4.0

package/src/index.ts

@@ -1,16 +1,16 @@
 /**
- * `@nifrajs/core` — Nifra's lean HTTP server API.
+ * `@nifrajs/core` - Nifra's lean HTTP server API.
  *
  * Nifra 2.0 keeps the package root intentionally lean. Optional systems live at documented
  * subpaths so importing the root cannot activate unrelated runtimes.
  */
 
 /**
- * Current package version. A hardcoded literal on purpose — core runs on the edge (no fs), so it can't
+ * Current package version. A hardcoded literal on purpose - core runs on the edge (no fs), so it can't
  * read its own package.json at runtime. `scripts/version.ts` rewrites it on every release bump and
  * `check:publish` asserts it equals `@nifrajs/core`'s package version.
  */
-export const VERSION = "2.2.0" as const
+export const VERSION = "2.4.0" as const
 
 export type Version = typeof VERSION
 

package/src/internal/brand.ts

@@ -3,7 +3,7 @@
  *
  * Every developer-facing string (error prefixes, the default OpenAPI title, the
  * logger tag) pulls from here, so renaming the brand is a one-line change. The
- * npm scope (`@nifrajs/*`) is the other naming axis — `scripts/rename.ts` flips
+ * npm scope (`@nifrajs/*`) is the other naming axis - `scripts/rename.ts` flips
  * both at once.
  */
 export const FRAMEWORK_NAME = "Nifra" as const

package/src/internal/route-catalog.ts

@@ -0,0 +1,94 @@
+/**
+ * The app's route table: one canonical fact per registered route, and the router built over them.
+ *
+ * ## Why this is not in the server kernel
+ *
+ * Nothing here knows what a `Server` is. It owns matching, reflection, assurance and native-compilation
+ * input, and the kernel holds one instance - which is the whole relationship. The reason it lived in
+ * `server.ts` is that `RouteEntry` used to be declared there, and until that vocabulary moved to
+ * `internal/` this could not be split out without exporting the engine's internals as public types.
+ *
+ * ## Why this costs the request path nothing
+ *
+ * Per-request code calls `this.catalog.find(...)`: a property load and a method call on an instance.
+ * Which module DECLARED the class does not enter into that. The only cross-module operation is the
+ * `new RouteCatalog()` in the server's constructor, once per server; every other method here runs at
+ * registration.
+ */
+import type { CompiledRoutePattern } from "../router/pattern.ts"
+import { type Method, Router, type RouterMatch } from "../router/router.ts"
+import type { RouteDescriptor } from "../server/server-types.ts"
+import type { AssuranceDeclaration } from "./route-assurance.ts"
+import type { RouteEntry } from "./route-execution.ts"
+
+/** One canonical runtime route fact. The catalog owns matching, reflection, assurance, tool metadata,
+ * replay, and native compilation input so batch registration has one commit point. */
+export interface CatalogRoute {
+  readonly method: Method
+  readonly path: string
+  readonly pattern: CompiledRoutePattern
+  readonly entry: RouteEntry
+  readonly descriptor: RouteDescriptor
+  readonly assurance: readonly AssuranceDeclaration[]
+}
+
+/**
+ * Runtime route catalog. Single-route registration mutates directly; multi-route registration replays
+ * the existing catalog plus the candidate batch into a staged router, then swaps the complete state only
+ * after every route validates. Failed `implement()`/`merge()` batches therefore leave matching and
+ * reflection unchanged.
+ *
+ * Coverage note: this file reports 90% functions with every method exercised. `bun test --coverage`
+ * (1.3.14) counts one synthetic function per class that it never marks hit - a one-method class with a
+ * passing test for that method reports 50%. So 90 is this file's ceiling, not a missing test; do not go
+ * looking for the tenth function.
+ */
+export class RouteCatalog {
+  private matcher = new Router<RouteEntry>()
+  private records: CatalogRoute[] = []
+  /** Allocation-free reflection view for the common no-assurance case. Derived only at commit time. */
+  private descriptors: RouteDescriptor[] = []
+  private assurancePresent = false
+
+  add(route: CatalogRoute): void {
+    this.matcher.add(route.method, route.pattern, route.entry)
+    this.records.push(route)
+    this.descriptors.push(route.descriptor)
+    if (route.assurance.length > 0) this.assurancePresent = true
+  }
+
+  addBatch(routes: readonly CatalogRoute[]): void {
+    if (routes.length === 0) return
+    const nextRecords = this.records.concat(routes)
+    const nextDescriptors = this.descriptors.concat(routes.map(({ descriptor }) => descriptor))
+    const nextAssurancePresent =
+      this.assurancePresent || routes.some((route) => route.assurance.length > 0)
+    const staged = new Router<RouteEntry>()
+    for (const route of this.records) staged.add(route.method, route.pattern, route.entry)
+    for (const route of routes) staged.add(route.method, route.pattern, route.entry)
+    this.matcher = staged
+    this.records = nextRecords
+    this.descriptors = nextDescriptors
+    this.assurancePresent = nextAssurancePresent
+  }
+
+  find(method: string, path: string): RouterMatch<RouteEntry> {
+    return this.matcher.find(method, path)
+  }
+
+  entries(): readonly CatalogRoute[] {
+    return this.records
+  }
+
+  routeDescriptors(): ReadonlyArray<RouteDescriptor> {
+    return this.descriptors
+  }
+
+  lastDescriptor(): RouteDescriptor | undefined {
+    return this.records[this.records.length - 1]?.descriptor
+  }
+
+  hasAssurance(): boolean {
+    return this.assurancePresent
+  }
+}

package/src/internal/route-execution.ts

@@ -0,0 +1,106 @@
+/**
+ * What a compiled route IS, and the registration-time decision that produces it.
+ *
+ * ## Why this is not in the server kernel
+ *
+ * `compileExecutionPlan` is BOOT work: it runs from `register`/`registerBatch`, both gated by
+ * `assertConfigurable`, so nothing here is reachable once the server is serving. Moving it costs the
+ * request path nothing - per-request code still calls the same frozen `run` closure it always did.
+ *
+ * ## Why `internal/`
+ *
+ * These types are the engine's vocabulary, not the package's API. They lived in `server.ts`, which IS
+ * published as `./server`, so every attempt to split the kernel had the same choice: export the engine's
+ * internals as public types, or not split. `internal/` is not a published subpath, so this moves the
+ * vocabulary somewhere it can be shared without becoming API. That is the step that unblocks the rest.
+ *
+ * The `Server` import is type-only and erased, so there is no runtime cycle back into the kernel.
+ */
+import type { RequestBudget } from "../budget.ts"
+import type { StandardSchemaV1 } from "../schema/standard.ts"
+import type { Platform, RouteSchema } from "../server/context.ts"
+import type { ResolvedIdempotency } from "../server/idempotency-lane.ts"
+import type { ResolvedEffectLedger } from "../server/ledger-lane.ts"
+import type { Registry } from "../server/registry.ts"
+import type { ResponseContractRuntime } from "../server/response-contract-lane.ts"
+import type { HandlerResult } from "../server/runtime-core.ts"
+import type { CtxSet, MaybePromise, RawContext, RequestSource, Server } from "../server/server.ts"
+
+export type InternalHandler = (ctx: RawContext) => MaybePromise<HandlerResult>
+
+/** A `derive` computes per-request context extensions; stored path-erased. */
+export type RawDerive = (ctx: RawContext) => MaybePromise<object>
+export type RawBeforeHandle = (ctx: RawContext) => MaybePromise<unknown>
+export type RawAfterHandle = (result: unknown, ctx: RawContext) => MaybePromise<unknown>
+export type RawErrorHandler = (error: unknown, ctx: RawContext) => MaybePromise<unknown>
+export type RawAround = <T>(ctx: RawContext, next: () => MaybePromise<T>) => MaybePromise<T>
+
+export type RouteExecutionRunner = <T, R extends Registry, Ctx>(
+  runtime: Server<R, Ctx>,
+  entry: RouteEntry,
+  source: RequestSource,
+  params: Record<string, string>,
+  search: string | undefined,
+  signal: AbortSignal,
+  budget: RequestBudget,
+  platform: Platform | undefined,
+  finalize: (result: unknown, set: CtxSet) => T,
+  wrapResponse: (response: Response) => T,
+) => MaybePromise<T>
+
+export type ContextRouteRunner = <T, R extends Registry, Ctx>(
+  runtime: Server<R, Ctx>,
+  entry: RouteEntry,
+  source: RequestSource,
+  ctx: RawContext,
+  finalize: (result: unknown, set: CtxSet) => T,
+  wrapResponse: (response: Response) => T,
+) => MaybePromise<T>
+
+/** Registration-compiled route behavior. Every adapter invokes the same runner; the optional fused
+ * renderer is only a response-format specialization of that same selected route semantics. */
+export interface RouteExecutionPlan {
+  readonly run: RouteExecutionRunner
+  readonly fusedWeb: FusedWebRunner | undefined
+}
+
+export interface RouteEntry {
+  readonly handler: InternalHandler
+  readonly schema: RouteSchema | undefined
+  /** Resolved idempotency config; `undefined` = off (the dedupe lane is never entered). */
+  readonly idempotent: ResolvedIdempotency | undefined
+  /** Resolved effect-ledger wiring; `undefined` = off (no per-request ledger, no settle step). */
+  readonly ledgered: ResolvedEffectLedger | undefined
+  /** The installed response-contract runtime paired with this route's declared schema, resolved once
+   * at registration; `undefined` = not checked (the default, and the only state in which the route can
+   * still take the fused/native lanes). */
+  readonly responseContract:
+    | { readonly runtime: ResponseContractRuntime; readonly schema: StandardSchemaV1 }
+    | undefined
+  /** Per-request context extensions captured at registration (order-scoped). */
+  readonly derives: ReadonlyArray<RawDerive>
+  /** Static context extensions captured at registration. */
+  readonly decorations: Record<PropertyKey, unknown>
+  /** Whether {@link decorations} has any keys - precomputed so the hot path skips a no-op
+   * `Object.assign` on the (common) no-decoration route. */
+  readonly hasDecorations: boolean
+  /** Lifecycle hooks captured at registration (order-scoped). */
+  readonly beforeHandle: ReadonlyArray<RawBeforeHandle>
+  readonly afterHandle: ReadonlyArray<RawAfterHandle>
+  readonly onError: ReadonlyArray<RawErrorHandler>
+  /** Wraps the matched route lifecycle. Empty for the common no-around path. */
+  readonly around: ReadonlyArray<RawAround>
+  /** The single immutable execution decision consumed by portable, Node-direct, and Bun-native paths. */
+  readonly execution: RouteExecutionPlan
+}
+
+/** The fused Web lane: same inputs `routeAndRun` would hand the generic path, a `Response` out. */
+export type FusedWebRunner = (
+  source: RequestSource,
+  params: Record<string, string>,
+  search: string | undefined,
+  signal: AbortSignal,
+  budget: RequestBudget,
+  platform: Platform | undefined,
+  nativeContext: boolean,
+) => MaybePromise<Response>

package/src/internal/same-origin.ts

@@ -0,0 +1,43 @@
+/**
+ * The same-origin test every browser-facing endpoint in Nifra uses.
+ *
+ * One owner, because there are two of these seams - the WebSocket handshake's CSWSH default and the
+ * server-function mount - and they answered differently for the same request. A browser that could
+ * open a socket was told its POST was cross-origin.
+ */
+
+/**
+ * True when `origin` is the request's own origin, as observed from inside a possibly-proxied server.
+ *
+ * The host must match exactly. The scheme must be equal or STRONGER on the Origin side, never weaker:
+ *
+ *   - `https://app` page → `http://app` request URL: accepted. This is what every TLS-terminating
+ *     proxy looks like from the origin server - Cloudflare, a tunnel, an ingress. The socket is plain
+ *     HTTP, so `request.url` says `http:` while the browser correctly reports an `https:` page.
+ *   - `http://app` page → `https://app` request URL: rejected. Nifra terminated TLS itself here, so a
+ *     plaintext page on the same host is the downgrade an attacker would need and buys nothing real.
+ *
+ * Comparing full origins instead is not the stricter option, it is an outage: measured, it rejects
+ * every server-function POST behind a terminating proxy, while the cross-origin attacker it aims at
+ * was already rejected by the host comparison. Nifra deliberately does not read `X-Forwarded-Proto` -
+ * a forwarded header is attacker-controlled unless something upstream is proven to overwrite it - so
+ * the scheme in `request.url` is the socket's, not the browser's, and this asymmetry is how the two
+ * are reconciled without trusting a header.
+ *
+ * An unparseable Origin is not same-origin.
+ */
+export function isSameOriginRequest(origin: string, request: Request): boolean {
+  try {
+    const from = new URL(origin)
+    const own = new URL(request.url)
+    if (from.host !== own.host) return false
+    // Written out rather than ranked through a lookup table: a table is a shipped object, and there
+    // are exactly two schemes to order. Any other scheme on either side falls through to `false`,
+    // which is what refuses `Origin: null`, `file:` and webview schemes.
+    if (from.protocol === "https:") return own.protocol === "https:" || own.protocol === "http:"
+    if (from.protocol === "http:") return own.protocol === "http:"
+    return false
+  } catch {
+    return false
+  }
+}

package/src/internal/secret.ts

@@ -7,7 +7,7 @@ const MIN_SECRET_BYTES = 32
 const SECRET_ENCODER = new TextEncoder()
 
 /**
- * Boot-time guard: reject an HMAC secret under 256 bits, loudly, at construction — never at the
+ * Boot-time guard: reject an HMAC secret under 256 bits, loudly, at construction - never at the
  * first request. UTF-8 byte length (not char count), so a multibyte secret is measured honestly.
  * The single source of truth for the framework's secret-strength floor; every HMAC entry point
  * (signed cookies, `@nifrajs/auth` sessions, webhook verification, signed upload/image URLs) routes

package/src/ledger.ts

@@ -4,7 +4,7 @@
  * Every owned effect seam (a repository write, an external call, an email send) records one entry via
  * the `useCapability` beacon. The entry type is deliberately **token-only**: capability ids, phase,
  * an adapter/resource token, dimensionless cost counters, an optional keyed digest, and an error code.
- * There is no free-form payload field — request bodies, rows, and values cannot enter the ledger, so
+ * There is no free-form payload field - request bodies, rows, and values cannot enter the ledger, so
  * redaction holds by construction rather than by filtering. The sealed ledger carries the **route
  * pattern** (`/users/:id`), never the concrete URL, so path parameters cannot leak either.
  *
@@ -29,7 +29,7 @@ export type EffectCost = Readonly<Record<string, number>>
 
 /** Token-only caller metadata shared by an effect intent and outcome. */
 export interface EffectMetadata {
-  /** Adapter/resource token (`repo:orders`, `provider:payments`). A token — never a value or a row. */
+  /** Adapter/resource token (`repo:orders`, `provider:payments`). A token - never a value or a row. */
   readonly target?: string
   /** Dimensionless counters; see {@link EffectCost}. At most {@link MAX_COST_AXES} axes. */
   readonly cost?: EffectCost
@@ -45,7 +45,7 @@ export interface EffectEntryInput extends EffectMetadata {
   readonly capability: string
   /** Default `"intent"`. Record `committed`/`failed`/`compensated` only after the outcome is known. */
   readonly phase?: EffectPhase
-  /** Outcome error as a bounded token code — never a message, never a stack. */
+  /** Outcome error as a bounded token code - never a message, never a stack. */
   readonly error?: { readonly code: string }
 }
 
@@ -75,10 +75,10 @@ export interface EffectChain {
 /** The immutable result of sealing a request's ledger. Token-only; safe to hand to any sink. */
 export interface SealedEffectLedger {
   readonly method: string
-  /** The registered route pattern (`/users/:id`) — never the concrete request URL. */
+  /** The registered route pattern (`/users/:id`) - never the concrete request URL. */
   readonly path: string
   readonly entries: readonly EffectEntry[]
-  /** The route's declared capability tokens — the runtime-enforcement view: recorded ⊆ declared is
+  /** The route's declared capability tokens - the runtime-enforcement view: recorded ⊆ declared is
    * guaranteed by the beacon, and `declared` minus the recorded ids is the unused declaration set. */
   readonly declared: readonly string[]
   /** Present when the ledger was created with `chain: true`. */
@@ -99,7 +99,7 @@ export class EffectLedgerOverflowError extends Error {
   }
 }
 
-/** Thrown by `append` after `seal()` — e.g. an effect attempted while streaming a response body. */
+/** Thrown by `append` after `seal()` - e.g. an effect attempted while streaming a response body. */
 export class EffectLedgerSealedError extends Error {
   constructor() {
     super("effect ledger is sealed: effects cannot be recorded after the response settles")
@@ -115,14 +115,14 @@ export interface RequestLedger {
   entries(): readonly EffectEntry[]
   readonly size: number
   readonly sealed: boolean
-  /** Finalize the ledger (computing the chain when enabled). Idempotent — always the same result. */
+  /** Finalize the ledger (computing the chain when enabled). Idempotent - always the same result. */
   seal(): Promise<SealedEffectLedger>
 }
 
 export interface CreateRequestLedgerOptions {
   /** HTTP method of the matched route. */
   readonly method: string
-  /** The registered route pattern — callers must never pass the concrete request URL. */
+  /** The registered route pattern - callers must never pass the concrete request URL. */
   readonly path: string
   /** The route's declared capability tokens, surfaced verbatim on the sealed ledger. Default `[]`. */
   readonly declared?: readonly string[]
@@ -255,7 +255,7 @@ class BoundedRequestLedger implements RequestLedger {
     if (input.error !== undefined && !ERROR_CODE.test(input.error.code)) {
       throw new TypeError("effect ledger: error code must be a bounded lowercase token")
     }
-    // Only the known token fields are copied — a stray `payload`-like property never survives append.
+    // Only the known token fields are copied - a stray `payload`-like property never survives append.
     const at = this.clock()
     if (!Number.isFinite(at) || at < 0) {
       throw new TypeError("effect ledger: clock must return a finite non-negative number")
@@ -315,7 +315,7 @@ export function createRequestLedger(options: CreateRequestLedgerOptions): Reques
   return new BoundedRequestLedger(options)
 }
 
-/** Canonical, key-ordered serialization of one entry — the hash-chain input. */
+/** Canonical, key-ordered serialization of one entry - the hash-chain input. */
 function canonicalEntry(entry: EffectEntry): string {
   const cost =
     entry.cost === undefined
@@ -382,7 +382,7 @@ export function createMemoryLedgerSink(options: MemoryLedgerSinkOptions = {}): M
 /** Minimum digest key material. A short key would make the keyed digest brute-forceable. */
 export const MIN_DIGEST_KEY_BYTES = 16
 
-/** Fresh random digest key (32 bytes). Per-process by default — persist one externally to correlate across restarts. */
+/** Fresh random digest key (32 bytes). Per-process by default - persist one externally to correlate across restarts. */
 export function randomEffectDigestKey(): Uint8Array {
   const bytes = new Uint8Array(32)
   crypto.getRandomValues(bytes)

package/src/reflection.ts

@@ -40,7 +40,7 @@ export interface SchemaReflection {
 export interface ReflectedRouteSchema {
   readonly body?: SchemaReflection
   readonly query?: SchemaReflection
-  /** Path-params schema — constraints (uuid format, integer min/max) declared via `params: t.object(…)`. */
+  /** Path-params schema - constraints (uuid format, integer min/max) declared via `params: t.object(…)`. */
   readonly params?: SchemaReflection
   readonly response?: SchemaReflection
   readonly errors?: Readonly<Record<string, SchemaReflection>>

package/src/router/pattern.ts

@@ -71,17 +71,17 @@ function validParamName(name: string): boolean {
  *
  * The grammar is per-segment: a segment is wholly static or wholly a parameter, so everything after
  * the colon is the name. `/v/:id.json` therefore asks for a parameter literally named `id.json`,
- * which is not what anyone means by it — but the bare "invalid parameter" that produces reads as a
+ * which is not what anyone means by it - but the bare "invalid parameter" that produces reads as a
  * typo rather than as a rule, leaving the author to guess whether the dot, the length, or the casing
  * was the problem. Naming the actual limitation and showing the two ways out is the difference
  * between a five-second fix and a trip to the source.
  */
 function paramNameHint(name: string): string {
-  if (RESERVED_PARAM_NAMES.has(name)) return ` — "${name}" is reserved (prototype key)`
-  if (name.length === 0) return ` — ":" needs a name after it`
+  if (RESERVED_PARAM_NAMES.has(name)) return ` - "${name}" is reserved (prototype key)`
+  if (name.length === 0) return ` - ":" needs a name after it`
   // No "a segment is wholly static or wholly a parameter" case here any more: mixed segments made
   // that message obsolete. `:id.json` was the shape it explained, and `:id.json` now compiles.
-  return ` — a name must match ${PARAM_NAME.source}`
+  return ` - a name must match ${PARAM_NAME.source}`
 }
 
 function escapeRegex(value: string): string {
@@ -312,6 +312,18 @@ export function compareRoutePatternSpecificity(
   return 0
 }
 
+/**
+ * Sort compiled routes most-specific-first - a static segment beats a dynamic one, the order the router
+ * resolves a path in. The single home for that precedence: the web router, the mock server, and the
+ * editor plugin all order routes through this one comparator, so which file a path resolves to can never
+ * diverge between runtime, client, and editor. Sorts in place and returns the same array.
+ */
+export function sortRoutesBySpecificity<T extends { readonly pattern: CompiledRoutePattern }>(
+  routes: T[],
+): T[] {
+  return routes.sort((left, right) => compareRoutePatternSpecificity(left.pattern, right.pattern))
+}
+
 /** Decode router captures under one rule. Plain values take the zero-allocation path; malformed
  * escapes return `null`, allowing HTTP to emit 400 while client navigation declines the match. */
 export function decodeRouteParams(raw: Record<string, string>): Record<string, string> | null {

package/src/router/router.ts

@@ -35,7 +35,7 @@ export type RouterMatch<T> =
 /**
  * Payload at a terminal node: per-method handlers plus the ordered param names
  * for this path shape. Bundling them means "a node that has handlers always has
- * param names" is enforced by the type, not by a runtime invariant — which
+ * param names" is enforced by the type, not by a runtime invariant - which
  * removes the otherwise-dead defensive branches in `find`.
  */
 interface Terminal<T> {
@@ -85,7 +85,7 @@ interface RouteNode<T> {
    * no allocation, and one `undefined` check on the match path.
    */
   mixedChildren: MixedChild<T>[] | undefined
-  /** Catch-all `*` child, if any — always terminal. */
+  /** Catch-all `*` child, if any - always terminal. */
   wildcardChild: RouteNode<T> | undefined
   /** Set once this node terminates one or more routes. */
   terminal: Terminal<T> | undefined
@@ -129,7 +129,7 @@ function sameNames(a: readonly string[], b: readonly string[]): boolean {
  * instead of pre-splitting it into an array. `start` is the index of the first
  * char of the current segment; the segment runs to the next `/` (or end). Tries
  * static, then param, then wildcard; if a static branch dead-ends, param/wildcard
- * are still attempted — so `/a/b/c` and `/a/:x/d` coexist and `/a/b/d` resolves
+ * are still attempted - so `/a/b/c` and `/a/:x/d` coexist and `/a/b/d` resolves
  * to the param route. Fills `paramValues` along the successful path; abandoned
  * branches are popped. Avoiding the split keeps `find` allocation-light: only the
  * segment substrings needed for map lookups (and matched param values) are cut.
@@ -179,9 +179,9 @@ function matchNode<T>(
   }
 
   const paramChild = node.paramChild
-  // An empty segment (`/users//posts`) never matches a `:param` — matching would hand the handler
+  // An empty segment (`/users//posts`) never matches a `:param` - matching would hand the handler
   // `id: ""` and downstream code a `WHERE id = ''` class of bug. Peers (Hono, Elysia, Next) 404
-  // here too; a static "" child can still match (none is ever registered — INVALID_PATH guards).
+  // here too; a static "" child can still match (none is ever registered - INVALID_PATH guards).
   if (paramChild !== undefined && seg.length > 0) {
     paramValues.push(seg)
     if (isLast) {

package/src/schema/standard.ts

@@ -1,7 +1,7 @@
 /**
  * The Standard Schema v1 interface (https://standardschema.dev), vendored as
- * types + a tiny runtime helper so any compliant validator — zod, valibot,
- * arktype, … — validates requests without coupling the framework to one lib.
+ * types + a tiny runtime helper so any compliant validator - zod, valibot,
+ * arktype, … - validates requests without coupling the framework to one lib.
  * The spec is MIT-licensed and explicitly designed to be copied.
  */
 

package/src/seo.ts

@@ -1,5 +1,5 @@
 /**
- * `sitemap.xml` + `robots.txt` builders — pure, edge-safe string generators (no I/O, no runtime deps).
+ * `sitemap.xml` + `robots.txt` builders - pure, edge-safe string generators (no I/O, no runtime deps).
  * Wire them to a route on any runtime:
  *
  *   app.get("/sitemap.xml", () =>
@@ -21,7 +21,7 @@ const XML_ESCAPES: Readonly<Record<string, string>> = {
   "'": "&apos;",
 }
 
-/** Escape the five XML metacharacters — `<loc>` and `<lastmod>` carry app- or DB-derived strings. */
+/** Escape the five XML metacharacters - `<loc>` and `<lastmod>` carry app- or DB-derived strings. */
 function escapeXml(value: string): string {
   return value.replace(/[&<>"']/g, (char) => XML_ESCAPES[char] as string)
 }
@@ -48,10 +48,10 @@ const CHANGE_FREQS: ReadonlySet<string> = new Set([
 export interface SitemapEntry {
   /** An absolute URL, or a path that `hostname` will make absolute. */
   readonly url: string
-  /** Last-modified — a `Date` (serialized as ISO 8601) or a pre-formatted W3C-datetime string. */
+  /** Last-modified - a `Date` (serialized as ISO 8601) or a pre-formatted W3C-datetime string. */
   readonly lastmod?: string | Date
   readonly changefreq?: SitemapChangeFreq
-  /** Crawl priority, `0.0`–`1.0`. */
+  /** Crawl priority, `0.0`-`1.0`. */
   readonly priority?: number
 }
 
@@ -67,7 +67,7 @@ const SITEMAP_MAX_URLS = 50_000
 export function sitemap(entries: readonly SitemapEntry[], options: SitemapOptions = {}): string {
   if (entries.length > SITEMAP_MAX_URLS) {
     throw new RangeError(
-      `sitemap: ${entries.length} entries exceeds the ${SITEMAP_MAX_URLS}-URL per-file limit — split into a sitemap index`,
+      `sitemap: ${entries.length} entries exceeds the ${SITEMAP_MAX_URLS}-URL per-file limit - split into a sitemap index`,
     )
   }
   const base = options.hostname?.replace(/\/+$/, "")
@@ -96,7 +96,7 @@ export function sitemap(entries: readonly SitemapEntry[], options: SitemapOption
 
 function resolveLoc(url: string, base: string | undefined): string {
   if (/^https?:\/\//i.test(url)) return url // already absolute
-  if (base === undefined) return url // relative — caller's choice (sitemaps prefer absolute)
+  if (base === undefined) return url // relative - caller's choice (sitemaps prefer absolute)
   return `${base}${url.startsWith("/") ? "" : "/"}${url}`
 }
 

package/src/server/body.ts

@@ -1,5 +1,5 @@
 /**
- * Bounded request-body reading — the single source of truth for nifra's body-size cap. A lying or
+ * Bounded request-body reading - the single source of truth for nifra's body-size cap. A lying or
  * absent `Content-Length` can't force us to buffer an oversized payload: a declared length over the
  * cap is rejected *before* buffering, and a chunked / length-less body is aborted mid-stream once the
  * running byte count exceeds the cap. Shared by the server's schema path, `c.boundedBody`, and
@@ -26,7 +26,7 @@ export function parseContentLength(value: string): number | undefined {
 
 /** The shared streaming byte-cap loop: read until done, or cancel + 413 once over `maxBytes`.
  * A single-chunk body (the common case for small chunked payloads) returns the runtime's own
- * chunk directly — no chunk array, no copy-merge. */
+ * chunk directly - no chunk array, no copy-merge. */
 export async function drainCapped(
   body: ReadableStream<Uint8Array>,
   maxBytes: number,