@ultimat3/http 0.0.1

package/src/response.ts

@@ -0,0 +1,129 @@
+// Response constructors. Every response in the framework is built here so that
+// content types, charsets and cache semantics are decided once instead of per route.
+import { toProblem } from './error-map';
+
+type HeaderSource = { readonly headers?: HeadersInit | undefined } | undefined;
+
+const withDefaults = (init: HeaderSource, defaults: Record<string, string>): Headers => {
+  const headers = new Headers(init?.headers);
+  for (const [name, value] of Object.entries(defaults)) {
+    if (!headers.has(name)) headers.set(name, value);
+  }
+  return headers;
+};
+
+export const json = <T>(body: T, init?: ResponseInit): Response =>
+  new Response(JSON.stringify(body), {
+    ...init,
+    headers: withDefaults(init, { 'content-type': 'application/json; charset=utf-8' }),
+  });
+
+export const text = (body: string, init?: ResponseInit): Response =>
+  new Response(body, {
+    ...init,
+    headers: withDefaults(init, { 'content-type': 'text/plain; charset=utf-8' }),
+  });
+
+export const html = (markup: string, init?: ResponseInit): Response =>
+  new Response(markup, {
+    ...init,
+    headers: withDefaults(init, { 'content-type': 'text/html; charset=utf-8' }),
+  });
+
+/**
+ * Streamed responses must never be buffered by an intermediary, otherwise the
+ * shell-then-holes render mode degrades to plain SSR without anyone noticing.
+ */
+export const stream = (
+  body: ReadableStream<Uint8Array>,
+  init?: ResponseInit & { readonly contentType?: string },
+): Response =>
+  new Response(body, {
+    ...init,
+    headers: withDefaults(init, {
+      'content-type': init?.contentType ?? 'text/html; charset=utf-8',
+      'transfer-encoding': 'chunked',
+      'x-accel-buffering': 'no',
+    }),
+  });
+
+export const noContent = (init?: ResponseInit): Response =>
+  new Response(null, { ...init, status: 204 });
+
+/** 303 after a mutation, 302 otherwise — never 301 from application code. */
+export const redirect = (location: string, status: 302 | 303 | 307 | 308 = 302): Response =>
+  new Response(null, { status, headers: { location } });
+
+/**
+ * RFC-9457. The body carries the framework's error contract verbatim: `code`,
+ * `cause`, `fix`, `docs`. An agent reading a failed response gets the same three
+ * strings a human reads in the terminal.
+ */
+export const problem = (
+  error: unknown,
+  meta: { instance?: string; requestId?: string; headers?: Record<string, string> } = {},
+): Response => {
+  const document = toProblem(error, {
+    ...(meta.instance === undefined ? {} : { instance: meta.instance }),
+    ...(meta.requestId === undefined ? {} : { requestId: meta.requestId }),
+  });
+  return new Response(JSON.stringify(document), {
+    status: document.status,
+    headers: withDefaults(
+      { headers: meta.headers },
+      {
+        'content-type': 'application/problem+json; charset=utf-8',
+        // A problem is never cacheable: the next request may well succeed.
+        'cache-control': 'no-store',
+      },
+    ),
+  });
+};
+
+export interface CacheHint {
+  readonly mode: 'no-store' | 'private' | 'public' | 'immutable';
+  readonly maxAgeSeconds?: number;
+  /** Shared/CDN age. `isr` routes set this and rely on tag purges to revalidate. */
+  readonly sMaxAgeSeconds?: number;
+  readonly staleWhileRevalidateSeconds?: number;
+  /** Cache tags a purge can target; mirrored into `x-cache-tags`. */
+  readonly tags?: readonly string[];
+  readonly vary?: readonly string[];
+}
+
+export const NO_STORE: CacheHint = { mode: 'no-store' };
+
+export const cacheControl = (hint: CacheHint): string => {
+  if (hint.mode === 'no-store') return 'no-store';
+  if (hint.mode === 'immutable') {
+    return `public, max-age=${hint.maxAgeSeconds ?? 31_536_000}, immutable`;
+  }
+  const parts = [hint.mode, `max-age=${hint.maxAgeSeconds ?? 0}`];
+  if (hint.mode === 'public' && hint.sMaxAgeSeconds !== undefined) {
+    parts.push(`s-maxage=${hint.sMaxAgeSeconds}`);
+  }
+  if (hint.staleWhileRevalidateSeconds !== undefined) {
+    parts.push(`stale-while-revalidate=${hint.staleWhileRevalidateSeconds}`);
+  }
+  return parts.join(', ');
+};
+
+/** Mutates the response headers in place — responses are per-request, never shared. */
+export const applyCacheHeaders = (response: Response, hint: CacheHint): Response => {
+  response.headers.set('cache-control', cacheControl(hint));
+  if (hint.tags !== undefined && hint.tags.length > 0) {
+    response.headers.set('x-cache-tags', hint.tags.join(','));
+  }
+  const vary = hint.vary ?? (hint.mode === 'public' ? ['accept-language'] : []);
+  if (vary.length > 0) {
+    const existing = response.headers.get('vary');
+    const merged = new Set([...(existing === null ? [] : existing.split(/,\s*/)), ...vary]);
+    response.headers.set('vary', [...merged].join(', '));
+  }
+  return response;
+};
+
+export const withHeaders = (response: Response, headers: Record<string, string>): Response => {
+  for (const [name, value] of Object.entries(headers)) response.headers.set(name, value);
+  return response;
+};

package/src/router.ts

@@ -0,0 +1,251 @@
+// The route table. A segment trie, not a regex list, so matching cost is bounded by
+// path depth and precedence is a property of the structure rather than of
+// declaration order.
+//
+// PRECEDENCE (deterministic, tested in router.test.ts):
+//   1. static segment   `/posts/new`
+//   2. param segment    `/posts/:id`
+//   3. wildcard segment `/posts/*rest`  (matches ONE OR MORE remaining segments)
+// Depth-first with backtracking: `/posts/new` beats `/posts/:id` even though the
+// param branch would also match, and a dead end in the static branch still falls
+// back to the param branch. Two routes that would tie are a build error
+// (`X_ROUTE_CONFLICT`) rather than a coin flip.
+import type { RequestContext } from './context';
+import { routeConflict } from './errors';
+import type { UltimateRequest } from './request';
+import type { CacheHint } from './response';
+import type { Schema } from './validate';
+
+export type HttpMethod = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';
+
+export const HTTP_METHODS: readonly HttpMethod[] = [
+  'GET',
+  'HEAD',
+  'POST',
+  'PUT',
+  'PATCH',
+  'DELETE',
+  'OPTIONS',
+];
+
+export type RenderMode = 'static' | 'isr' | 'ssr' | 'stream' | 'spa';
+
+export type RouteParams = Readonly<Record<string, string>>;
+
+export interface RouteMeta {
+  /** Stable id used by rate-limit keys, traces and the manifest. */
+  readonly name: string;
+  /**
+   * Required, never inferred: a route that forgets to declare its auth posture is a
+   * type error instead of an accidentally public endpoint.
+   */
+  readonly auth: 'public' | 'required';
+  /** Name of the policy the authz stage must satisfy. Resolved by tier 3. */
+  readonly policy?: string;
+  /** Validated in the body stage; also what the OpenAPI/MCP emitters read. */
+  readonly input?: Schema;
+  readonly render?: RenderMode;
+  readonly cache?: CacheHint;
+  /** Named bucket from `rateLimit.buckets`. */
+  readonly rateLimit?: string;
+  readonly tags?: readonly string[];
+  readonly description?: string;
+}
+
+export type RouteHandler = (
+  request: UltimateRequest,
+  ctx: RequestContext,
+) => Response | Promise<Response>;
+
+export interface Route {
+  readonly method: HttpMethod;
+  /** Leading slash, no trailing slash, segments may be `:param` or `*wildcard`. */
+  readonly path: string;
+  readonly handler: RouteHandler;
+  readonly meta: RouteMeta;
+}
+
+export type MatchResult =
+  | { readonly ok: true; readonly route: Route; readonly params: RouteParams }
+  | { readonly ok: false; readonly reason: 'not-found' }
+  | {
+      readonly ok: false;
+      readonly reason: 'method-not-allowed';
+      readonly allow: readonly HttpMethod[];
+    };
+
+interface TrieNode {
+  readonly statics: Map<string, TrieNode>;
+  param: { readonly name: string; readonly node: TrieNode } | undefined;
+  wildcard: { readonly name: string; readonly node: TrieNode } | undefined;
+  readonly routes: Map<HttpMethod, Route>;
+}
+
+export interface RouteTable {
+  readonly routes: readonly Route[];
+  readonly root: TrieNode;
+}
+
+const node = (): TrieNode => ({
+  statics: new Map(),
+  param: undefined,
+  wildcard: undefined,
+  routes: new Map(),
+});
+
+/** `/a/b/` and `//a//b` both normalise to `/a/b`; `/` stays `/`. */
+export const normalizePath = (path: string): string => {
+  const trimmed = path.split('/').filter((segment) => segment.length > 0);
+  return trimmed.length === 0 ? '/' : `/${trimmed.join('/')}`;
+};
+
+const segmentsOf = (path: string): readonly string[] =>
+  normalizePath(path)
+    .split('/')
+    .filter((segment) => segment.length > 0);
+
+export const createRouter = (routes: readonly Route[]): RouteTable => {
+  const root = node();
+  for (const route of routes) {
+    let current = root;
+    const segments = segmentsOf(route.path);
+    for (const [index, segment] of segments.entries()) {
+      if (segment.startsWith(':')) {
+        const name = segment.slice(1);
+        if (current.param !== undefined && current.param.name !== name) {
+          throw routeConflict(
+            route.path,
+            `segment ${index} is :${current.param.name} in an existing route and :${name} here`,
+          );
+        }
+        current.param = current.param ?? { name, node: node() };
+        current = current.param.node;
+        continue;
+      }
+      if (segment.startsWith('*')) {
+        const name = segment.slice(1) || 'wildcard';
+        if (index !== segments.length - 1) {
+          throw routeConflict(route.path, 'a wildcard must be the last segment');
+        }
+        if (current.wildcard !== undefined && current.wildcard.name !== name) {
+          throw routeConflict(route.path, `wildcard is *${current.wildcard.name} elsewhere`);
+        }
+        current.wildcard = current.wildcard ?? { name, node: node() };
+        current = current.wildcard.node;
+        continue;
+      }
+      const existing = current.statics.get(segment);
+      const next = existing ?? node();
+      if (existing === undefined) current.statics.set(segment, next);
+      current = next;
+    }
+    if (current.routes.has(route.method)) {
+      throw routeConflict(route.path, `${route.method} is already handled by another route`);
+    }
+    current.routes.set(route.method, route);
+  }
+  return { routes: [...routes], root };
+};
+
+interface Candidate {
+  readonly node: TrieNode;
+  readonly params: RouteParams;
+}
+
+/** Terminal nodes reachable for `segments`, in precedence order. */
+const candidates = (
+  current: TrieNode,
+  segments: readonly string[],
+  index: number,
+  params: RouteParams,
+  out: Candidate[],
+): void => {
+  if (index === segments.length) {
+    if (current.routes.size > 0) out.push({ node: current, params });
+    return;
+  }
+  const segment = segments[index];
+  if (segment === undefined) return;
+
+  const staticChild = current.statics.get(segment);
+  if (staticChild !== undefined) candidates(staticChild, segments, index + 1, params, out);
+
+  if (current.param !== undefined) {
+    const next = { ...params, [current.param.name]: decodeURIComponent(segment) };
+    candidates(current.param.node, segments, index + 1, next, out);
+  }
+
+  if (current.wildcard !== undefined) {
+    const rest = segments.slice(index).map(decodeURIComponent).join('/');
+    const next = { ...params, [current.wildcard.name]: rest };
+    if (current.wildcard.node.routes.size > 0) {
+      out.push({ node: current.wildcard.node, params: next });
+    }
+  }
+};
+
+/**
+ * HEAD falls back to the GET route: the runtime strips the body, so declaring both
+ * would be two ways to do one thing.
+ */
+const routeFor = (candidate: Candidate, method: HttpMethod): Route | undefined =>
+  candidate.node.routes.get(method) ??
+  (method === 'HEAD' ? candidate.node.routes.get('GET') : undefined);
+
+export const matchRoute = (table: RouteTable, method: string, pathname: string): MatchResult => {
+  const segments = segmentsOf(pathname);
+  const found: Candidate[] = [];
+  candidates(table.root, segments, 0, {}, found);
+  if (found.length === 0) return { ok: false, reason: 'not-found' };
+
+  const wanted = method.toUpperCase() as HttpMethod;
+  for (const candidate of found) {
+    const route = routeFor(candidate, wanted);
+    if (route !== undefined) return { ok: true, route, params: candidate.params };
+  }
+  const allow = new Set<HttpMethod>();
+  for (const candidate of found) for (const key of candidate.node.routes.keys()) allow.add(key);
+  if (allow.has('GET')) allow.add('HEAD');
+  return { ok: false, reason: 'method-not-allowed', allow: [...allow] };
+};
+
+export interface RouteDescription {
+  readonly method: HttpMethod;
+  readonly path: string;
+  readonly name: string;
+  readonly params: readonly string[];
+  readonly auth: 'public' | 'required';
+  readonly policy: string | null;
+  readonly render: RenderMode | null;
+  readonly rateLimit: string | null;
+  readonly tags: readonly string[];
+  readonly description: string | null;
+  readonly hasInputSchema: boolean;
+}
+
+const compare = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+const paramsOf = (path: string): readonly string[] =>
+  segmentsOf(path)
+    .filter((segment) => segment.startsWith(':') || segment.startsWith('*'))
+    .map((segment) => segment.slice(1));
+
+/** Feeds the `/_x` dashboard, the manifest emitter and `x routes list --json`. */
+export const describeRoutes = (table: RouteTable): readonly RouteDescription[] =>
+  table.routes
+    .map((route) => ({
+      method: route.method,
+      path: normalizePath(route.path),
+      name: route.meta.name,
+      params: paramsOf(route.path),
+      auth: route.meta.auth,
+      policy: route.meta.policy ?? null,
+      render: route.meta.render ?? null,
+      rateLimit: route.meta.rateLimit ?? null,
+      tags: route.meta.tags ?? [],
+      description: route.meta.description ?? null,
+      hasInputSchema: route.meta.input !== undefined,
+    }))
+    // Code-unit compare, not localeCompare: the manifest is a build artefact and must
+    // be byte-identical across machines and ICU versions.
+    .sort((a, b) => compare(a.path, b.path) || compare(a.method, b.method));

package/src/security-headers.ts

@@ -0,0 +1,90 @@
+// Locked security headers. The CSP is written to work with the three things the
+// framework actually ships — a service worker, streamed HTML with a hydration
+// nonce, and wasm — and nothing else, so widening it is a visible config change.
+
+export interface SecurityConfig {
+  readonly csp: {
+    /** Extra sources per directive, merged into the locked baseline. */
+    readonly extend: Readonly<Record<string, readonly string[]>>;
+    readonly reportUri: string | null;
+    /** `true` sends Content-Security-Policy-Report-Only instead. Dev default. */
+    readonly reportOnly: boolean;
+  };
+  readonly hsts: {
+    readonly maxAgeSeconds: number;
+    readonly includeSubdomains: boolean;
+    readonly preload: boolean;
+  } | null;
+  readonly frameAncestors: readonly string[];
+  readonly referrerPolicy: string;
+  readonly permissionsPolicy: string;
+  readonly coop: string;
+  readonly corp: string;
+}
+
+export const DEFAULT_SECURITY: SecurityConfig = {
+  csp: { extend: {}, reportUri: null, reportOnly: false },
+  frameAncestors: ["'none'"],
+  referrerPolicy: 'strict-origin-when-cross-origin',
+  permissionsPolicy: 'camera=(), microphone=(), geolocation=(), payment=()',
+  coop: 'same-origin',
+  corp: 'same-origin',
+  hsts: { maxAgeSeconds: 63_072_000, includeSubdomains: true, preload: false },
+};
+
+/** Directive -> sources. `'nonce-*'` is injected per response, never stored here. */
+const baseline = (config: SecurityConfig): Record<string, readonly string[]> => ({
+  'default-src': ["'self'"],
+  // 'wasm-unsafe-eval' only: no 'unsafe-inline', no 'unsafe-eval'.
+  'script-src': ["'self'", "'wasm-unsafe-eval'"],
+  'style-src': ["'self'"],
+  'img-src': ["'self'", 'data:', 'blob:'],
+  'font-src': ["'self'"],
+  // ws:/wss: are required by the realtime tiers; blob: by streamed responses.
+  'connect-src': ["'self'", 'ws:', 'wss:', 'blob:'],
+  'worker-src': ["'self'", 'blob:'],
+  'manifest-src': ["'self'"],
+  'media-src': ["'self'", 'blob:'],
+  'frame-ancestors': config.frameAncestors,
+  'form-action': ["'self'"],
+  'base-uri': ["'none'"],
+  'object-src': ["'none'"],
+});
+
+export const buildCsp = (config: SecurityConfig, nonce?: string): string => {
+  const directives = baseline(config);
+  for (const [name, sources] of Object.entries(config.csp.extend)) {
+    directives[name] = [...(directives[name] ?? []), ...sources];
+  }
+  if (nonce !== undefined) {
+    directives['script-src'] = [...(directives['script-src'] ?? []), `'nonce-${nonce}'`];
+  }
+  const parts = Object.entries(directives).map(([name, sources]) => `${name} ${sources.join(' ')}`);
+  if (config.csp.reportUri !== null) parts.push(`report-uri ${config.csp.reportUri}`);
+  return parts.join('; ');
+};
+
+export const securityHeaders = (
+  config: SecurityConfig,
+  options: { nonce?: string; https?: boolean } = {},
+): Record<string, string> => {
+  const cspHeader = config.csp.reportOnly
+    ? 'content-security-policy-report-only'
+    : 'content-security-policy';
+  const headers: Record<string, string> = {
+    [cspHeader]: buildCsp(config, options.nonce),
+    'x-content-type-options': 'nosniff',
+    'referrer-policy': config.referrerPolicy,
+    'permissions-policy': config.permissionsPolicy,
+    'cross-origin-opener-policy': config.coop,
+    'cross-origin-resource-policy': config.corp,
+  };
+  // HSTS over plaintext is ignored by browsers and confuses local dev, so skip it.
+  if (config.hsts !== null && options.https !== false) {
+    const parts = [`max-age=${config.hsts.maxAgeSeconds}`];
+    if (config.hsts.includeSubdomains) parts.push('includeSubDomains');
+    if (config.hsts.preload) parts.push('preload');
+    headers['strict-transport-security'] = parts.join('; ');
+  }
+  return headers;
+};

package/src/server.ts

@@ -0,0 +1,157 @@
+// We own the server lifecycle instead of exposing `Bun.serve` directly, because ALS
+// context, tracing and authz must be impossible to skip — a route is a data
+// declaration, never a chance to hand-roll a request handler.
+
+import type { Role } from '@ultimat3/core';
+import { logger, onShutdown } from '@ultimat3/core';
+import type { Server } from 'bun';
+import { defineHttpConfig, type HttpConfig } from './config';
+import { serverNotStarted } from './errors';
+import type { ServerHooks } from './hooks';
+import type { Middleware } from './middleware';
+import { createPipeline, type Pipeline } from './pipeline';
+import { json } from './response';
+import { createRouter, describeRoutes, type Route, type RouteDescription } from './router';
+
+export type LifecycleState = 'idle' | 'starting' | 'ready' | 'draining' | 'stopped';
+
+/** `Server` is generic over its websocket payload; the `web` role does not use one. */
+type BunServer = Server<unknown>;
+
+type NativeHandler = (request: Request, socket: BunServer) => Promise<Response>;
+
+export interface ServerOptions {
+  readonly routes: readonly Route[];
+  readonly config?: HttpConfig;
+  /** `ROLE` env selects behaviour; one image, N processes. */
+  readonly role?: Role;
+  readonly hooks?: ServerHooks;
+  readonly middleware?: readonly Middleware[];
+}
+
+export interface ServerHandle {
+  readonly role: Role;
+  readonly config: HttpConfig;
+  readonly pipeline: Pipeline;
+  state(): LifecycleState;
+  /** `http://host:port` once started; throws before `start()`. */
+  url(): string;
+  describe(): readonly RouteDescription[];
+  start(): ServerHandle;
+  stop(options?: { readonly timeoutMs?: number }): Promise<void>;
+  /**
+   * Runs one request through the entire lifecycle with no socket. This is the
+   * supported way to test routes: there is no second, "lighter" code path.
+   */
+  fetch(request: Request): Promise<Response>;
+}
+
+const roleFromEnv = (): Role => (Bun.env['ROLE'] ?? 'web') as Role;
+
+export const createServer = (options: ServerOptions): ServerHandle => {
+  const config = options.config ?? defineHttpConfig();
+  const role = options.role ?? roleFromEnv();
+  const table = createRouter(options.routes);
+  const pipeline = createPipeline({
+    table,
+    config,
+    ...(options.hooks === undefined ? {} : { hooks: options.hooks }),
+    ...(options.middleware === undefined ? {} : { middleware: options.middleware }),
+  });
+
+  let state: LifecycleState = 'idle';
+  let server: BunServer | undefined;
+  let inflight = 0;
+
+  const health = (): Response =>
+    json(
+      { status: 'ok', role, state, buildId: config.buildId },
+      {
+        headers: { 'cache-control': 'no-store' },
+      },
+    );
+
+  // Readiness is the only thing a load balancer reads, so it must flip to 503 the
+  // instant we start draining — before the socket closes, so in-flight work finishes.
+  const ready = (): Response =>
+    json(
+      { status: state === 'ready' ? 'ready' : state, role, buildId: config.buildId },
+      { status: state === 'ready' ? 200 : 503, headers: { 'cache-control': 'no-store' } },
+    );
+
+  const dispatch = async (request: Request, socket?: BunServer): Promise<Response> => {
+    inflight += 1;
+    try {
+      return await pipeline.handle(request, {
+        role,
+        ip: socket?.requestIP(request)?.address ?? null,
+      });
+    } finally {
+      inflight -= 1;
+    }
+  };
+
+  /**
+   * Static paths go into Bun's native route table so path dispatch happens in
+   * native code. Method resolution stays ours: Bun's automatic 405 would not carry
+   * our problem+json body. Param/wildcard paths fall through to `fetch`.
+   */
+  const nativeRoutes = (): Record<string, NativeHandler> => {
+    const out: Record<string, NativeHandler> = {};
+    const prefix = config.basePath === '/' ? '' : config.basePath.replace(/\/$/, '');
+    for (const description of describeRoutes(table)) {
+      if (description.params.length > 0) continue;
+      out[`${prefix}${description.path}`] = dispatch;
+    }
+    return out;
+  };
+
+  const handle: ServerHandle = {
+    role,
+    config,
+    pipeline,
+    state: () => state,
+    url: () => {
+      if (server === undefined) throw serverNotStarted('url()');
+      return server.url.origin;
+    },
+    describe: () => describeRoutes(table),
+    fetch: (request) => dispatch(request),
+    start() {
+      state = 'starting';
+      server = Bun.serve({
+        port: config.port,
+        hostname: config.hostname,
+        development: config.dev,
+        routes: {
+          ...nativeRoutes(),
+          // Health endpoints answer outside the pipeline on purpose: a draining or
+          // rate-limited process must still be able to say what it is doing.
+          '/healthz': () => health(),
+          '/readyz': () => ready(),
+        },
+        fetch: (request, socket) => dispatch(request, socket),
+      });
+      state = 'ready';
+      logger.info(`ultimate ${role} listening on ${server.url.origin}`);
+      // SIGTERM handling belongs to core so every role drains identically.
+      onShutdown(() => handle.stop());
+      return handle;
+    },
+    async stop(stopOptions) {
+      if (state === 'stopped') return;
+      state = 'draining';
+      const deadline = Date.now() + (stopOptions?.timeoutMs ?? config.drainTimeoutMs);
+      while (inflight > 0 && Date.now() < deadline) await Bun.sleep(25);
+      if (inflight > 0) {
+        logger.warn(`ultimate ${role} draining timed out with ${inflight} in-flight requests`);
+      }
+      await server?.stop(true);
+      server = undefined;
+      state = 'stopped';
+      logger.info(`ultimate ${role} stopped`);
+    },
+  };
+
+  return handle;
+};

package/src/validate.ts

@@ -0,0 +1,55 @@
+// Validation goes through the Standard Schema interface, never through a vendor
+// API, so ArkType (`t`) is a default rather than a dependency of the HTTP layer.
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+
+export type Schema<Out = unknown> = StandardSchemaV1<unknown, Out>;
+
+export type InferOutput<S> = S extends Schema<infer Out> ? Out : never;
+
+export type ValidationOutcome<Out> =
+  | { readonly ok: true; readonly value: Out }
+  | { readonly ok: false; readonly issues: readonly string[] };
+
+type Issue = { readonly message: string; readonly path?: readonly unknown[] | undefined };
+
+const segment = (value: unknown): string => {
+  if (typeof value === 'string' || typeof value === 'number') return String(value);
+  if (typeof value === 'object' && value !== null && 'key' in value) {
+    return String((value as { key: unknown }).key);
+  }
+  return '?';
+};
+
+/** `posts.0.title: must be a string` — a path an agent can act on directly. */
+export const formatIssue = (issue: Issue): string => {
+  const path = (issue.path ?? []).map(segment).join('.');
+  return path.length > 0 ? `${path}: ${issue.message}` : issue.message;
+};
+
+const outcome = <Out>(result: {
+  readonly value?: Out;
+  readonly issues?: readonly Issue[] | undefined;
+}): ValidationOutcome<Out> => {
+  if (result.issues !== undefined && result.issues.length > 0) {
+    return { ok: false, issues: result.issues.map(formatIssue) };
+  }
+  return { ok: true, value: result.value as Out };
+};
+
+/**
+ * Query strings and route params must validate without awaiting: they are read
+ * inside synchronous stages. A schema that returns a promise here is a bug in the
+ * schema, not in the request.
+ */
+export const validateSync = <Out>(schema: Schema<Out>, value: unknown): ValidationOutcome<Out> => {
+  const result = schema['~standard'].validate(value);
+  if (result instanceof Promise) {
+    return { ok: false, issues: ['schema is async; use validate() for request bodies'] };
+  }
+  return outcome<Out>(result);
+};
+
+export const validate = async <Out>(
+  schema: Schema<Out>,
+  value: unknown,
+): Promise<ValidationOutcome<Out>> => outcome<Out>(await schema['~standard'].validate(value));