@nifrajs/core 0.1.0-alpha.1

package/src/schema/standard.ts

@@ -0,0 +1,76 @@
+/**
+ * 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.
+ * The spec is MIT-licensed and explicitly designed to be copied.
+ */
+
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly "~standard": StandardSchemaProps<Input, Output>
+}
+
+export interface StandardSchemaProps<Input = unknown, Output = Input> {
+  readonly version: 1
+  readonly vendor: string
+  readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>
+  readonly types?: StandardTypes<Input, Output> | undefined
+}
+
+export type StandardResult<Output> = StandardSuccess<Output> | StandardFailure
+
+export interface StandardSuccess<Output> {
+  readonly value: Output
+  readonly issues?: undefined
+}
+
+export interface StandardFailure {
+  readonly issues: ReadonlyArray<StandardIssue>
+}
+
+export interface StandardIssue {
+  readonly message: string
+  readonly path?: ReadonlyArray<PropertyKey | StandardPathSegment> | undefined
+}
+
+export interface StandardPathSegment {
+  readonly key: PropertyKey
+}
+
+export interface StandardTypes<Input = unknown, Output = Input> {
+  readonly input: Input
+  readonly output: Output
+}
+
+export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<
+  Schema["~standard"]["types"]
+>["output"]
+
+export type InferInput<Schema extends StandardSchemaV1> = NonNullable<
+  Schema["~standard"]["types"]
+>["input"]
+
+export type ValidationOutcome<Output> =
+  | { readonly ok: true; readonly value: Output }
+  | { readonly ok: false; readonly issues: ReadonlyArray<StandardIssue> }
+
+function normalizeStandardResult<Output>(
+  result: StandardResult<Output>,
+): ValidationOutcome<Output> {
+  if (result.issues !== undefined) {
+    return { ok: false, issues: result.issues }
+  }
+  return { ok: true, value: result.value }
+}
+
+/** Run a Standard Schema and normalize the result. Sync validators stay sync; async validators are awaited. */
+export function validateStandard<Schema extends StandardSchemaV1>(
+  schema: Schema,
+  value: unknown,
+): ValidationOutcome<InferOutput<Schema>> | Promise<ValidationOutcome<InferOutput<Schema>>> {
+  const result = schema["~standard"].validate(value)
+  return result instanceof Promise
+    ? result.then((settled) =>
+        normalizeStandardResult(settled as StandardResult<InferOutput<Schema>>),
+      )
+    : normalizeStandardResult(result as StandardResult<InferOutput<Schema>>)
+}

package/src/seo.ts

@@ -0,0 +1,155 @@
+/**
+ * `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", () =>
+ *     new Response(sitemap([{ url: "/" }, { url: "/about", priority: 0.8 }], { hostname: "https://x.com" }), {
+ *       headers: { "content-type": "application/xml; charset=utf-8" },
+ *     }))
+ *
+ *   app.get("/robots.txt", () =>
+ *     new Response(robots({ rules: [{ userAgent: "*", disallow: ["/admin"] }], sitemap: "https://x.com/sitemap.xml" }), {
+ *       headers: { "content-type": "text/plain; charset=utf-8" },
+ *     }))
+ */
+
+const XML_ESCAPES: Readonly<Record<string, string>> = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&apos;",
+}
+
+/** 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)
+}
+
+export type SitemapChangeFreq =
+  | "always"
+  | "hourly"
+  | "daily"
+  | "weekly"
+  | "monthly"
+  | "yearly"
+  | "never"
+
+const CHANGE_FREQS: ReadonlySet<string> = new Set([
+  "always",
+  "hourly",
+  "daily",
+  "weekly",
+  "monthly",
+  "yearly",
+  "never",
+])
+
+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. */
+  readonly lastmod?: string | Date
+  readonly changefreq?: SitemapChangeFreq
+  /** Crawl priority, `0.0`–`1.0`. */
+  readonly priority?: number
+}
+
+export interface SitemapOptions {
+  /** Prepended to path-only `url`s (e.g. `"https://example.com"`). Sitemaps require absolute URLs. */
+  readonly hostname?: string
+}
+
+/** sitemaps.org caps a single sitemap file at 50,000 URLs. Beyond this, split into a sitemap index. */
+const SITEMAP_MAX_URLS = 50_000
+
+/** Build a `<urlset>` sitemap XML document from `entries`. Throws on out-of-spec input (dev-time data). */
+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`,
+    )
+  }
+  const base = options.hostname?.replace(/\/+$/, "")
+  const urls = entries.map((entry) => {
+    const parts = [`<loc>${escapeXml(resolveLoc(entry.url, base))}</loc>`]
+    if (entry.lastmod !== undefined) {
+      const value = entry.lastmod instanceof Date ? entry.lastmod.toISOString() : entry.lastmod
+      parts.push(`<lastmod>${escapeXml(value)}</lastmod>`)
+    }
+    if (entry.changefreq !== undefined) {
+      if (!CHANGE_FREQS.has(entry.changefreq)) {
+        throw new RangeError(`sitemap: invalid changefreq "${entry.changefreq}"`)
+      }
+      parts.push(`<changefreq>${entry.changefreq}</changefreq>`)
+    }
+    if (entry.priority !== undefined) {
+      if (!Number.isFinite(entry.priority) || entry.priority < 0 || entry.priority > 1) {
+        throw new RangeError(`sitemap: priority must be between 0.0 and 1.0, got ${entry.priority}`)
+      }
+      parts.push(`<priority>${entry.priority.toFixed(1)}</priority>`)
+    }
+    return `  <url>${parts.join("")}</url>`
+  })
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls.join("\n")}\n</urlset>\n`
+}
+
+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)
+  return `${base}${url.startsWith("/") ? "" : "/"}${url}`
+}
+
+export interface RobotsRule {
+  /** A single user-agent token (`"*"`, `"Googlebot"`, …) or several sharing the same directives. */
+  readonly userAgent: string | readonly string[]
+  readonly allow?: readonly string[]
+  readonly disallow?: readonly string[]
+  /** Seconds between requests (honored by some crawlers). */
+  readonly crawlDelay?: number
+}
+
+export interface RobotsOptions {
+  readonly rules: readonly RobotsRule[]
+  /** One or more absolute `Sitemap:` URLs. */
+  readonly sitemap?: string | readonly string[]
+  /** A `Host:` directive (preferred mirror). */
+  readonly host?: string
+}
+
+/** robots.txt is line-oriented, so a newline in any value could inject a forged directive. Flatten it. */
+function sanitizeLine(value: string): string {
+  return value.replace(/[\r\n]+/g, " ").trim()
+}
+
+/** Build a `robots.txt` body from grouped rules plus optional `Sitemap:`/`Host:` lines. */
+export function robots(options: RobotsOptions): string {
+  const lines: string[] = []
+  for (const rule of options.rules) {
+    const agents = typeof rule.userAgent === "string" ? [rule.userAgent] : rule.userAgent
+    if (agents.length === 0) {
+      throw new RangeError("robots: each rule needs at least one userAgent")
+    }
+    for (const agent of agents) lines.push(`User-agent: ${sanitizeLine(agent)}`)
+    for (const path of rule.allow ?? []) lines.push(`Allow: ${sanitizeLine(path)}`)
+    for (const path of rule.disallow ?? []) lines.push(`Disallow: ${sanitizeLine(path)}`)
+    if (rule.crawlDelay !== undefined) {
+      if (!Number.isFinite(rule.crawlDelay) || rule.crawlDelay < 0) {
+        throw new RangeError(
+          `robots: crawlDelay must be a non-negative number, got ${rule.crawlDelay}`,
+        )
+      }
+      lines.push(`Crawl-delay: ${rule.crawlDelay}`)
+    }
+    lines.push("") // blank line between groups
+  }
+  const sitemaps =
+    options.sitemap === undefined
+      ? []
+      : typeof options.sitemap === "string"
+        ? [options.sitemap]
+        : options.sitemap
+  for (const url of sitemaps) lines.push(`Sitemap: ${sanitizeLine(url)}`)
+  if (options.host !== undefined) lines.push(`Host: ${sanitizeLine(options.host)}`)
+  return `${lines.join("\n").trim()}\n`
+}

package/src/server/body.ts

@@ -0,0 +1,89 @@
+/**
+ * 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
+ * `verifyWebhook` so they all enforce the same guarantee.
+ */
+
+interface BodySource {
+  readonly headers: Pick<Headers, "get">
+  readonly body: ReadableStream<Uint8Array> | null
+  arrayBuffer(): Promise<ArrayBuffer>
+}
+
+export function parseContentLength(value: string): number | undefined {
+  if (value.length === 0) return undefined
+  let length = 0
+  for (let i = 0; i < value.length; i++) {
+    const digit = value.charCodeAt(i) - 48
+    if (digit < 0 || digit > 9) return undefined
+    length = length * 10 + digit
+    if (length > Number.MAX_SAFE_INTEGER) return Number.POSITIVE_INFINITY
+  }
+  return length
+}
+
+/** 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. */
+export async function drainCapped(
+  body: ReadableStream<Uint8Array>,
+  maxBytes: number,
+): Promise<{ ok: true; bytes: Uint8Array } | { ok: false; status: 413 }> {
+  const reader = body.getReader()
+  let first: Uint8Array | undefined
+  let rest: Uint8Array[] | undefined
+  let total = 0
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    total += value.byteLength
+    if (total > maxBytes) {
+      await reader.cancel()
+      return { ok: false, status: 413 }
+    }
+    if (first === undefined) {
+      first = value
+    } else {
+      rest ??= []
+      rest.push(value)
+    }
+  }
+  if (rest === undefined) return { ok: true, bytes: first ?? new Uint8Array(0) }
+  const merged = new Uint8Array(total)
+  merged.set(first as Uint8Array, 0)
+  let offset = (first as Uint8Array).byteLength
+  for (const chunk of rest) {
+    merged.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return { ok: true, bytes: merged }
+}
+
+/**
+ * Read a request body as **bytes**, capped at `maxBytes`. Rejects a `Content-Length` over the cap
+ * before buffering (`413`) and a malformed `Content-Length` (`400`); a chunked / length-less body
+ * falls through to the streaming byte-cap guard. Fast path: a non-chunked request with a
+ * `Content-Length` within the cap is read via native `arrayBuffer()` (framing-bounded by the runtime's
+ * HTTP server), skipping the manual stream loop.
+ */
+export async function readBoundedBytes(
+  req: BodySource,
+  maxBytes: number,
+): Promise<{ ok: true; bytes: Uint8Array } | { ok: false; status: 400 | 413 }> {
+  const declared = req.headers.get("content-length")
+  if (declared !== null) {
+    // A present Content-Length must be a non-negative integer (HTTP grammar: `1*DIGIT`). A non-numeric
+    // / negative / fractional value is malformed → 400, rather than falling through to the streaming
+    // guard (an UPPER-bound cap only, so a lying SMALLER length would otherwise be read in full).
+    const length = parseContentLength(declared)
+    if (length === undefined) return { ok: false, status: 400 }
+    if (length > maxBytes) return { ok: false, status: 413 }
+    const chunked = req.headers.get("transfer-encoding") !== null
+    if (!chunked) return { ok: true, bytes: new Uint8Array(await req.arrayBuffer()) }
+  }
+  const body = req.body
+  if (body === null) return { ok: true, bytes: new Uint8Array(0) }
+  return drainCapped(body, maxBytes)
+}

package/src/server/context.ts

@@ -0,0 +1,124 @@
+import type { InferOutput, StandardSchemaV1 } from "../schema/standard.ts"
+import type { CookieOptions } from "./cookies.ts"
+
+/** Flattens an intersection into a single object type for readable hovers. */
+export type Prettify<T> = { [K in keyof T]: T[K] } & {}
+
+/**
+ * Extracts `:param` and trailing `*wildcard` names from a route-path literal into
+ * a string→string record: `/users/:id/posts/:postId` → `{ id: string; postId:
+ * string }`, `/files/*path` → `{ path: string }`, `/files/*` → `{ "*": string }`.
+ * A non-literal `string` path widens to `Record<string, string>`.
+ */
+type RawParams<Path extends string> = string extends Path
+  ? Record<string, string>
+  : Path extends `${infer _Start}:${infer Param}/${infer Rest}`
+    ? Record<Param, string> & RawParams<`/${Rest}`>
+    : Path extends `${infer _Start}:${infer Param}`
+      ? Record<Param, string>
+      : Path extends `${infer _Start}*${infer Wild}`
+        ? Record<Wild extends "" ? "*" : Wild, string>
+        : Record<never, string>
+
+export type Params<Path extends string> = Prettify<RawParams<Path>>
+
+/** Per-route input schemas. Each is any Standard Schema (zod/valibot/arktype/…). */
+export interface RouteSchema {
+  readonly body?: StandardSchemaV1
+  readonly query?: StandardSchemaV1
+  /** Optional **response contract**. When declared: the handler's return is type-checked against it
+   * (the implementation can't drift from the contract), the typed client sees THIS as the response type
+   * (the contract — not the handler's incidental return), and it's emitted into OpenAPI/JSON-Schema so
+   * tooling and coding agents can read the exact shape. It is **not** validated at runtime (zero
+   * hot-path cost) — purely a compile-time + introspection contract. */
+  readonly response?: StandardSchemaV1
+}
+
+/** The validated body type, or `undefined` when no body schema is declared. */
+type BodyOf<S extends RouteSchema> = S extends { body: infer B extends StandardSchemaV1 }
+  ? InferOutput<B>
+  : undefined
+
+/** The validated query type, or raw `URLSearchParams` when no query schema is declared. */
+type QueryOf<S extends RouteSchema> = S extends { query: infer Q extends StandardSchemaV1 }
+  ? InferOutput<Q>
+  : URLSearchParams
+
+/** Mutable response controls a handler may write to before returning. */
+export interface ResponseControls {
+  status?: number
+  readonly headers: Record<string, string>
+  /**
+   * Queue a `Set-Cookie` on the response. Defaults are **secure-by-default** —
+   * `HttpOnly; Secure; SameSite=Lax; Path=/` — overridable per call (pass `{ secure: false }` for
+   * local http dev). Multiple calls set multiple cookies (they're merged via a `Headers` object, so
+   * they don't collapse the way the plain `headers` Record would). Sign the value with `signValue`
+   * for tamper-evidence (what `@nifrajs/auth` sessions do).
+   */
+  cookie(name: string, value: string, options?: CookieOptions): void
+  /** Queue a cookie deletion (`Max-Age=0` + a past `Expires`). Match the `path`/`domain` the cookie
+   * was set with, or the browser keeps it. */
+  deleteCookie(name: string, options?: Pick<CookieOptions, "path" | "domain">): void
+}
+
+/**
+ * Runtime platform inputs, passed as `app.fetch(request, platform)`. Edge adapters (e.g.
+ * Cloudflare Workers) supply `env` (bindings) + `waitUntil`; Bun/Node/Deno omit them. Optional +
+ * runtime-neutral, so `app.fetch` stays a Web-standard handler.
+ */
+export interface Platform<Env = unknown> {
+  /** Platform bindings (KV/D1/secrets on Workers). Typed as `Env` when the app declares them via
+   * `server<Env>()`; otherwise `unknown` — validate before use. */
+  readonly env?: Env
+  /** Extend the response's lifetime for background work (Workers `ctx.waitUntil`). */
+  readonly waitUntil?: (promise: Promise<unknown>) => void
+}
+
+/**
+ * Handler context. `params` are inferred from the path; `body` and `query` are
+ * the validated outputs of their schemas when declared (else `undefined` /
+ * raw `URLSearchParams`).
+ */
+export interface Context<Path extends string = string, S extends RouteSchema = RouteSchema> {
+  readonly req: Request
+  readonly params: Params<Path>
+  readonly query: QueryOf<S>
+  readonly body: BodyOf<S>
+  /** The request's cookies, parsed from the `Cookie` header (values URL-decoded). Parsed lazily on
+   * first access + cached. Signed cookies arrive as `value.signature` — verify with `unsignValue`. */
+  readonly cookies: Readonly<Record<string, string>>
+  readonly set: ResponseControls
+  /**
+   * Aborts when the server's `requestTimeoutMs` elapses (and never, when no timeout
+   * is configured). Pass it to cancellation-aware work — DB drivers, `fetch` — so a
+   * timed-out request stops doing work instead of running on after the 503.
+   */
+  readonly signal: AbortSignal
+  /**
+   * Platform bindings from `app.fetch(request, { env })` — Workers `env` (KV/D1/secrets), etc.
+   * `undefined` off-edge (Bun/Node/Deno). Declare the shape with `server<Env>()` to read it typed
+   * (`c.env: Env`); otherwise `unknown`. Validate at the trust boundary before use either way.
+   */
+  readonly env: unknown
+  /**
+   * Schedule background work. On edge runtimes it extends the response lifetime (Workers
+   * `ctx.waitUntil`); off-edge it runs the promise fire-and-forget (a rejection is swallowed,
+   * never an unhandled rejection).
+   */
+  readonly waitUntil: (promise: Promise<unknown>) => void
+  /**
+   * Read the raw request body as bytes, **capped** at `maxBytes` (default: the server's
+   * `maxBodyBytes`). For routes with **no body schema** — raw bodies, file uploads,
+   * BYO-validation — where the automatic schema cap doesn't apply. An over-cap body (by
+   * `Content-Length` or while streaming) throws a flat `413`; a malformed `Content-Length`
+   * throws `400`. Consumes the body stream (call once). Pass a larger `maxBytes` for an
+   * upload route, a smaller one to tighten a specific endpoint.
+   */
+  readonly boundedBody: (maxBytes?: number) => Promise<Uint8Array>
+  /**
+   * `boundedBody` + `JSON.parse` (UTF-8). Same cap + `413`/`400` semantics; additionally
+   * throws a flat `400` on invalid JSON. Use for a schema-less JSON endpoint that still
+   * wants the body bounded.
+   */
+  readonly boundedJson: <T = unknown>(maxBytes?: number) => Promise<T>
+}

package/src/server/contract.ts

@@ -0,0 +1,209 @@
+import { RouteConfigError } from "../errors.ts"
+import { METHODS, type Method } from "../router/router.ts"
+import type { InferOutput, StandardSchemaV1 } from "../schema/standard.ts"
+import type { Context, Params, RouteSchema } from "./context.ts"
+import type { OutputOf } from "./registry.ts"
+import { Server } from "./server.ts"
+
+/** An additional (non-success) response a contract operation can document, e.g. a `404`. */
+export interface ResponseDef {
+  readonly description?: string
+  /** Response body schema (any Standard Schema; a `t` schema yields full JSON Schema in OpenAPI). */
+  readonly schema?: StandardSchemaV1
+  /** Content type. Default `application/json`. */
+  readonly contentType?: string
+}
+
+/**
+ * One operation in a contract. Input schemas are any Standard Schema; `response` is optional.
+ *
+ * The fields below `response` are **optional OpenAPI metadata** — they don't affect runtime
+ * validation or the inferred handler types, they enrich the document `toOpenAPI` emits. A contract is
+ * the natural home for them: it's the versionable description of the API, decoupled from the impl.
+ */
+export interface OperationDef {
+  readonly method: Method
+  readonly path: string
+  readonly body?: StandardSchemaV1
+  readonly query?: StandardSchemaV1
+  readonly response?: StandardSchemaV1
+  /** Short summary (OpenAPI `summary`). */
+  readonly summary?: string
+  /** Longer description (OpenAPI `description`, CommonMark). */
+  readonly description?: string
+  /** Grouping tags (OpenAPI `tags`). */
+  readonly tags?: readonly string[]
+  /** Mark the operation deprecated. */
+  readonly deprecated?: boolean
+  /** Security requirements (names ref `securitySchemes`); `[]` = explicitly public. Omit ⇒ inherit the document default. */
+  readonly security?: ReadonlyArray<Readonly<Record<string, readonly string[]>>>
+  /** Request body content type. Default `application/json`. */
+  readonly requestContentType?: string
+  /** Content type of the success (`200`) response. Default `application/json`. */
+  readonly responseContentType?: string
+  /** Additional responses by status code, e.g. `{ "404": { description: "Not found" } }`. */
+  readonly responses?: Readonly<Record<string, ResponseDef>>
+}
+
+/** A contract: named operations. Names are the handler keys and OpenAPI operationIds. */
+export type ContractShape = Record<string, OperationDef>
+
+type OpBody<O extends OperationDef> = O extends { body: infer B extends StandardSchemaV1 }
+  ? InferOutput<B>
+  : never
+type OpQuery<O extends OperationDef> = O extends { query: infer Q extends StandardSchemaV1 }
+  ? InferOutput<Q>
+  : never
+type OpResponse<O extends OperationDef> = O extends { response: infer R extends StandardSchemaV1 }
+  ? InferOutput<R>
+  : unknown
+
+/**
+ * RouteInfo as a *decoupled consumer* sees it from the contract alone: the
+ * `output` is the declared `response` schema's type, or `unknown` when none is
+ * declared (the consumer can't know the response without the server). Path/method
+ * levels are mutable and fields are `readonly` — matching the inline registry, so
+ * the two are mutually assignable.
+ */
+type RouteInfoForOp<O extends OperationDef> = {
+  readonly params: Params<O["path"]>
+  readonly query: OpQuery<O>
+  readonly body: OpBody<O>
+  readonly output: OpResponse<O>
+}
+
+/** Re-key the name-keyed ops into the `path → method → RouteInfo` registry. */
+export type RegistryFor<C extends ContractShape> = {
+  [P in C[keyof C]["path"]]: {
+    [K in keyof C as C[K]["path"] extends P ? C[K]["method"] : never]: RouteInfoForOp<C[K]>
+  }
+}
+
+/** The schema shape an op contributes to its handler context (mirrors inline `RouteSchema`). */
+type SchemaForOp<O extends OperationDef> = (O extends { body: infer B extends StandardSchemaV1 }
+  ? { body: B }
+  : Record<never, never>) &
+  (O extends { query: infer Q extends StandardSchemaV1 } ? { query: Q } : Record<never, never>)
+
+/**
+ * The handler context for an op — identical to the inline `Context<Path, S>`, so a
+ * handler written for an inline route type-checks unchanged under `implement`
+ * (the graduation guarantee).
+ */
+export type ContextForOp<O extends OperationDef> = Context<O["path"], SchemaForOp<O> & RouteSchema>
+
+type MaybePromise<T> = T | Promise<T>
+
+/**
+ * What a handler may return for an op. When the op declares a `response`, the return is constrained to
+ * that contract shape (or a raw `Response`) — so an `implement`ed backend can't drift from the response
+ * the contract's client was built against. With no `response` it's unconstrained (`unknown`), identical
+ * to before. Purely type-level — erased at compile time, zero runtime cost — and mirrors the inline
+ * route's `ResponseOf` constraint, so a handler graduates inline↔contract unchanged.
+ */
+type HandlerReturnForOp<O extends OperationDef> = O extends {
+  response: infer R extends StandardSchemaV1
+}
+  ? Response | InferOutput<R>
+  : unknown
+
+/** The handlers `implement` requires: one per operation, typed from the op's input + response contract. */
+export type HandlersFor<C extends ContractShape> = {
+  [K in keyof C]: (context: ContextForOp<C[K]>) => MaybePromise<HandlerReturnForOp<C[K]>>
+}
+
+const METHOD_SET: ReadonlySet<string> = new Set(METHODS)
+
+/**
+ * Define a standalone, versionable contract. Identity at runtime (it returns the
+ * contract for type inference via the `const` type parameter, which preserves the
+ * path/method literals) plus boot-time (L2) validation: each operation must use a
+ * known method, a path starting with `/`, and no two operations may share a
+ * `(method, path)`. Deeper path validation (param names, wildcard position) runs
+ * when the contract is `implement`ed.
+ */
+export function defineContract<const C extends ContractShape>(contract: C): C {
+  const seen = new Set<string>()
+  for (const [name, op] of Object.entries(contract)) {
+    const method = op.method.toUpperCase()
+    if (!METHOD_SET.has(method)) {
+      throw new RouteConfigError(
+        "INVALID_METHOD",
+        `operation "${name}": unsupported method "${op.method}"`,
+      )
+    }
+    if (op.path.length === 0 || op.path.charCodeAt(0) !== 47 /* "/" */) {
+      throw new RouteConfigError(
+        "INVALID_PATH",
+        `operation "${name}": path must start with "/": "${op.path}"`,
+      )
+    }
+    const key = `${method} ${op.path}`
+    if (seen.has(key)) {
+      throw new RouteConfigError("DUPLICATE_ROUTE", `duplicate operation route: ${key}`)
+    }
+    seen.add(key)
+  }
+  return contract
+}
+
+type AnyFn = (...args: never[]) => unknown
+
+/**
+ * The registry produced by `implement`: input from the contract op; `output` is the declared `response`
+ * contract when present (it wins — exactly as in the inline path), else the bound HANDLER's return — so
+ * the implemented server stays route-for-route identical to the equivalent inline server (the
+ * mode-conformance guarantee), and a contract-typed client and a `typeof app`-typed client agree.
+ */
+export type RegistryFromImpl<C extends ContractShape, H extends HandlersFor<C>> = {
+  [P in C[keyof C]["path"]]: {
+    [K in keyof C as C[K]["path"] extends P ? C[K]["method"] : never]: {
+      readonly params: Params<C[K]["path"]>
+      readonly query: OpQuery<C[K]>
+      readonly body: OpBody<C[K]>
+      readonly output: C[K] extends { response: infer R extends StandardSchemaV1 }
+        ? InferOutput<R>
+        : H[K] extends AnyFn
+          ? OutputOf<H[K]>
+          : unknown
+    }
+  }
+}
+
+/**
+ * Bind handlers to a contract, producing a real {@link Server} you can `.listen()`
+ * or `.fetch()`. Each op is registered through the same path as the inline
+ * builder, so the result is identical to writing the routes inline — handlers
+ * lift over **unchanged** ("graduation"), and body/query schemas validate at the
+ * request boundary exactly as in inline mode.
+ */
+export function implement<const C extends ContractShape, H extends HandlersFor<C>>(
+  contract: C,
+  handlers: H,
+): Server<RegistryFromImpl<C, H>> {
+  const app = new Server()
+  for (const [name, op] of Object.entries(contract)) {
+    // body/query are validated at the request boundary; `response` is a type + introspection contract
+    // ONLY — never validated at runtime and never read on the request hot path (the lifecycle reads
+    // schema.body/query by name; the `bare`/bodyOnly/queryOnly fast-path gates ignore `response`). Built
+    // once here at bind time, not per request — it just carries a reference to the op's existing schema.
+    // A response-less op still yields `undefined`, byte-identical to before.
+    const schema: RouteSchema | undefined =
+      op.body !== undefined || op.query !== undefined || op.response !== undefined
+        ? {
+            ...(op.body !== undefined ? { body: op.body } : {}),
+            ...(op.query !== undefined ? { query: op.query } : {}),
+            ...(op.response !== undefined ? { response: op.response } : {}),
+          }
+        : undefined
+    app.register(
+      op.method,
+      op.path,
+      schema,
+      handlers[name as keyof H] as (context: never) => unknown,
+    )
+  }
+  // Runtime registered exactly the contract's routes through the inline path; the
+  // registry type is computed from the contract inputs + handler return types.
+  return app as unknown as Server<RegistryFromImpl<C, H>>
+}