@nifrajs/core 1.3.1 → 1.5.0

package/src/diff.ts

@@ -0,0 +1,383 @@
+/**
+ * API breaking-change detection over route reflection.
+ *
+ * `snapshotRoutes` turns an app (or reflected descriptors) into a plain-JSON snapshot — the
+ * `standard` validators are dropped, so a snapshot survives `JSON.stringify` and can be committed
+ * as a CI baseline. `diffRouteSnapshots` compares two snapshots and classifies every change by
+ * wire compatibility, direction-aware:
+ *
+ *   request direction (body/query — what clients SEND):  a new required field, a removed field, or
+ *     a narrowed type breaks existing callers; widening (new optional field, enum superset,
+ *     required→optional) is compatible.
+ *   response direction (response/sse/errors — what clients RECEIVE): a removed field, a field made
+ *     optional, or a widened type breaks existing readers; narrowing (new field, optional→required,
+ *     enum subset) is compatible.
+ *
+ * The classifier FAILS CLOSED: a schema change it cannot prove compatible is reported as breaking.
+ * Schemas without JSON Schema metadata (validation-only Standard Schemas) cannot be compared and
+ * yield `info` — never a silent pass presented as proof.
+ */
+
+import {
+  type JsonSchema,
+  type ReflectedRoute,
+  type ReflectedSchemaField,
+  reflectRoutes,
+} from "./reflection.ts"
+
+/** One schema position in a snapshot: JSON Schema metadata only, no validator. */
+export interface SchemaSnapshot {
+  readonly jsonSchema?: JsonSchema
+  readonly fields?: readonly ReflectedSchemaField[]
+}
+
+export interface RouteSnapshotSchema {
+  readonly body?: SchemaSnapshot
+  readonly query?: SchemaSnapshot
+  readonly response?: SchemaSnapshot
+  readonly sse?: SchemaSnapshot
+  readonly errors?: Readonly<Record<string, SchemaSnapshot>>
+}
+
+/** One route in a snapshot — plain JSON, safe to persist as a CI baseline. */
+export interface RouteSnapshot {
+  readonly method: string
+  readonly path: string
+  readonly schema?: RouteSnapshotSchema
+}
+
+export type DiffSeverity = "breaking" | "compatible" | "info"
+
+export interface RouteChange {
+  readonly severity: DiffSeverity
+  readonly method: string
+  readonly path: string
+  /** Which part of the contract changed; "route" for add/remove of the whole route. */
+  readonly section: "route" | "body" | "query" | "response" | "sse" | "errors"
+  /** The top-level field (or error status) the change is about, when field-granular. */
+  readonly field?: string
+  readonly message: string
+}
+
+export interface RoutesDiff {
+  readonly changes: readonly RouteChange[]
+  /** True when any change is `breaking` — the CI-gate signal. */
+  readonly hasBreaking: boolean
+}
+
+const schemaSnapshot = (
+  reflection:
+    | {
+        readonly jsonSchema?: JsonSchema | undefined
+        readonly fields?: readonly ReflectedSchemaField[] | undefined
+      }
+    | undefined,
+): SchemaSnapshot | undefined => {
+  if (reflection === undefined) return undefined
+  return {
+    ...(reflection.jsonSchema !== undefined ? { jsonSchema: reflection.jsonSchema } : {}),
+    ...(reflection.fields !== undefined ? { fields: reflection.fields } : {}),
+  }
+}
+
+/**
+ * Snapshot an app's routes (anything `reflectRoutes` accepts) as plain JSON. Validators are
+ * dropped; only introspectable JSON Schema metadata is kept, so the result round-trips through
+ * `JSON.stringify` unchanged.
+ */
+export function snapshotRoutes(source: unknown): readonly RouteSnapshot[] {
+  return reflectRoutes(source).map((route) => snapshotRoute(route))
+}
+
+const snapshotRoute = (route: ReflectedRoute): RouteSnapshot => {
+  const schema = route.schema
+  if (schema === undefined) return { method: route.method, path: route.path }
+  const errors: Record<string, SchemaSnapshot> = {}
+  for (const [status, reflection] of Object.entries(schema.errors ?? {})) {
+    const snapped = schemaSnapshot(reflection)
+    if (snapped !== undefined) errors[status] = snapped
+  }
+  const body = schemaSnapshot(schema.body)
+  const query = schemaSnapshot(schema.query)
+  const response = schemaSnapshot(schema.response)
+  const sse = schemaSnapshot(schema.sse)
+  const snapped: RouteSnapshotSchema = {
+    ...(body !== undefined ? { body } : {}),
+    ...(query !== undefined ? { query } : {}),
+    ...(response !== undefined ? { response } : {}),
+    ...(sse !== undefined ? { sse } : {}),
+    ...(Object.keys(errors).length > 0 ? { errors } : {}),
+  }
+  return {
+    method: route.method,
+    path: route.path,
+    ...(Object.keys(snapped).length > 0 ? { schema: snapped } : {}),
+  }
+}
+
+type Direction = "request" | "response"
+
+const jsonEqual = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JSON.stringify(b)
+
+const enumOf = (schema: JsonSchema | undefined): readonly unknown[] | undefined => {
+  if (typeof schema !== "object" || schema === null) return undefined
+  const candidate = (schema as { enum?: unknown }).enum
+  return Array.isArray(candidate) ? candidate : undefined
+}
+
+const withoutEnum = (schema: JsonSchema): unknown => {
+  if (typeof schema !== "object" || schema === null) return schema
+  const { enum: _omitted, ...rest } = schema as Record<string, unknown>
+  return rest
+}
+
+const isSuperset = (outer: readonly unknown[], inner: readonly unknown[]): boolean => {
+  const keys = new Set(outer.map((value) => JSON.stringify(value)))
+  return inner.every((value) => keys.has(JSON.stringify(value)))
+}
+
+/**
+ * Compare two JSON Schemas for one position. Returns the change severity, or `undefined` when
+ * they are equivalent. The only refinement proven compatible is an enum-only change in the
+ * safe direction (request may widen, response may narrow); everything else fails closed.
+ */
+const compareJsonSchema = (
+  direction: Direction,
+  before: JsonSchema,
+  after: JsonSchema,
+): DiffSeverity | undefined => {
+  if (jsonEqual(before, after)) return undefined
+  const beforeEnum = enumOf(before)
+  const afterEnum = enumOf(after)
+  if (
+    beforeEnum !== undefined &&
+    afterEnum !== undefined &&
+    jsonEqual(withoutEnum(before), withoutEnum(after))
+  ) {
+    const compatible =
+      direction === "request"
+        ? isSuperset(afterEnum, beforeEnum)
+        : isSuperset(beforeEnum, afterEnum)
+    return compatible ? "compatible" : "breaking"
+  }
+  return "breaking"
+}
+
+interface SectionContext {
+  readonly method: string
+  readonly path: string
+  readonly section: RouteChange["section"]
+  readonly direction: Direction
+  readonly changes: RouteChange[]
+}
+
+const push = (
+  ctx: SectionContext,
+  severity: DiffSeverity,
+  message: string,
+  field?: string,
+): void => {
+  ctx.changes.push({
+    severity,
+    method: ctx.method,
+    path: ctx.path,
+    section: ctx.section,
+    ...(field !== undefined ? { field } : {}),
+    message,
+  })
+}
+
+const fieldMap = (
+  snapshot: SchemaSnapshot,
+): ReadonlyMap<string, ReflectedSchemaField> | undefined => {
+  if (snapshot.fields === undefined) return undefined
+  return new Map(snapshot.fields.map((field) => [field.name, field]))
+}
+
+const diffFields = (ctx: SectionContext, before: SchemaSnapshot, after: SchemaSnapshot): void => {
+  const beforeFields = fieldMap(before)
+  const afterFields = fieldMap(after)
+  if (beforeFields === undefined || afterFields === undefined) {
+    // Non-object schemas: compare the whole JSON Schema in one step.
+    const severity = compareJsonSchema(
+      ctx.direction,
+      before.jsonSchema as JsonSchema,
+      after.jsonSchema as JsonSchema,
+    )
+    if (severity !== undefined) push(ctx, severity, `${ctx.section} schema changed`)
+    return
+  }
+  for (const [name, beforeField] of beforeFields) {
+    const afterField = afterFields.get(name)
+    if (afterField === undefined) {
+      // Request: strict validators reject payloads still sending the field. Response: readers lose it.
+      push(ctx, "breaking", `field "${name}" removed`, name)
+      continue
+    }
+    if (beforeField.required !== afterField.required) {
+      const nowRequired = afterField.required
+      const breaking = ctx.direction === "request" ? nowRequired : !nowRequired
+      push(
+        ctx,
+        breaking ? "breaking" : "compatible",
+        `field "${name}" is now ${nowRequired ? "required" : "optional"}`,
+        name,
+      )
+    }
+    const severity = compareJsonSchema(ctx.direction, beforeField.schema, afterField.schema)
+    if (severity !== undefined) push(ctx, severity, `field "${name}" type changed`, name)
+  }
+  for (const [name, afterField] of afterFields) {
+    if (beforeFields.has(name)) continue
+    if (ctx.direction === "request") {
+      push(
+        ctx,
+        afterField.required ? "breaking" : "compatible",
+        `${afterField.required ? "required" : "optional"} field "${name}" added`,
+        name,
+      )
+    } else {
+      push(ctx, "compatible", `field "${name}" added`, name)
+    }
+  }
+}
+
+const diffSchemaSection = (
+  ctx: SectionContext,
+  before: SchemaSnapshot | undefined,
+  after: SchemaSnapshot | undefined,
+): void => {
+  if (before === undefined && after === undefined) return
+  if (before === undefined) {
+    // A new request contract rejects payloads old clients send freely; a new response contract
+    // only documents what was already returned.
+    push(
+      ctx,
+      ctx.direction === "request" ? "breaking" : "compatible",
+      `${ctx.section} schema added`,
+    )
+    return
+  }
+  if (after === undefined) {
+    // Dropping a request contract loosens validation; dropping a response contract removes a
+    // documented shape clients (and typed consumers) rely on.
+    push(
+      ctx,
+      ctx.direction === "request" ? "compatible" : "breaking",
+      `${ctx.section} schema removed`,
+    )
+    return
+  }
+  if (before.jsonSchema === undefined || after.jsonSchema === undefined) {
+    // Validation-only schemas expose no JSON Schema metadata — nothing provable either way.
+    if (before.jsonSchema !== after.jsonSchema || before.fields !== after.fields) {
+      push(ctx, "info", `${ctx.section} schema is not introspectable — cannot verify compatibility`)
+    }
+    return
+  }
+  diffFields(ctx, before, after)
+}
+
+const diffErrors = (
+  method: string,
+  path: string,
+  changes: RouteChange[],
+  before: Readonly<Record<string, SchemaSnapshot>> | undefined,
+  after: Readonly<Record<string, SchemaSnapshot>> | undefined,
+): void => {
+  const beforeEntries = before ?? {}
+  const afterEntries = after ?? {}
+  for (const [status, beforeSchema] of Object.entries(beforeEntries)) {
+    const afterSchema = afterEntries[status]
+    if (afterSchema === undefined) {
+      // Clients parsing this structured error body lose a documented shape.
+      changes.push({
+        severity: "breaking",
+        method,
+        path,
+        section: "errors",
+        field: status,
+        message: `error ${status} removed from the contract`,
+      })
+      continue
+    }
+    const ctx: SectionContext = { method, path, section: "errors", direction: "response", changes }
+    if (beforeSchema.jsonSchema === undefined || afterSchema.jsonSchema === undefined) {
+      if (!jsonEqual(beforeSchema, afterSchema)) {
+        push(ctx, "info", `error ${status} schema is not introspectable`, status)
+      }
+      continue
+    }
+    const severity = compareJsonSchema("response", beforeSchema.jsonSchema, afterSchema.jsonSchema)
+    if (severity !== undefined) push(ctx, severity, `error ${status} schema changed`, status)
+  }
+  for (const status of Object.keys(afterEntries)) {
+    if (status in beforeEntries) continue
+    changes.push({
+      severity: "compatible",
+      method,
+      path,
+      section: "errors",
+      field: status,
+      message: `error ${status} added to the contract`,
+    })
+  }
+}
+
+const routeKey = (route: RouteSnapshot): string => `${route.method.toUpperCase()} ${route.path}`
+
+/**
+ * Diff two route snapshots (`snapshotRoutes` output, possibly restored from JSON). Every change is
+ * classified breaking/compatible/info; `hasBreaking` is the CI-gate bit.
+ */
+export function diffRouteSnapshots(
+  before: readonly RouteSnapshot[],
+  after: readonly RouteSnapshot[],
+): RoutesDiff {
+  const changes: RouteChange[] = []
+  const afterByKey = new Map(after.map((route) => [routeKey(route), route]))
+  const beforeKeys = new Set(before.map((route) => routeKey(route)))
+  for (const beforeRoute of before) {
+    const afterRoute = afterByKey.get(routeKey(beforeRoute))
+    if (afterRoute === undefined) {
+      changes.push({
+        severity: "breaking",
+        method: beforeRoute.method,
+        path: beforeRoute.path,
+        section: "route",
+        message: "route removed",
+      })
+      continue
+    }
+    const method = beforeRoute.method
+    const path = beforeRoute.path
+    const beforeSchema = beforeRoute.schema ?? {}
+    const afterSchema = afterRoute.schema ?? {}
+    for (const section of ["body", "query"] as const) {
+      diffSchemaSection(
+        { method, path, section, direction: "request", changes },
+        beforeSchema[section],
+        afterSchema[section],
+      )
+    }
+    for (const section of ["response", "sse"] as const) {
+      diffSchemaSection(
+        { method, path, section, direction: "response", changes },
+        beforeSchema[section],
+        afterSchema[section],
+      )
+    }
+    diffErrors(method, path, changes, beforeSchema.errors, afterSchema.errors)
+  }
+  for (const afterRoute of after) {
+    if (beforeKeys.has(routeKey(afterRoute))) continue
+    changes.push({
+      severity: "compatible",
+      method: afterRoute.method,
+      path: afterRoute.path,
+      section: "route",
+      message: "route added",
+    })
+  }
+  return { changes, hasBreaking: changes.some((change) => change.severity === "breaking") }
+}

package/src/index.ts

@@ -12,12 +12,14 @@
  * (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.3.1" as const
+export const VERSION = "1.5.0" as const
 
 export type Version = typeof VERSION
 
+export * from "./diff.ts"
 export { FrameworkError, RouteConfigError, type RouteConfigErrorCode } from "./errors.ts"
 export { FRAMEWORK_NAME, type FrameworkName } from "./internal/brand.ts"
+export * from "./reflection.ts"
 export { METHODS, type Method, Router, type RouterMatch } from "./router/router.ts"
 export type {
   InferInput,
@@ -91,6 +93,7 @@ export {
   type OnRequestResult,
   type PromptArgument,
   type PromptMessage,
+  type ResponseFinalization,
   type RouteDescriptor,
   type RunningServer,
   type ScheduledController,
@@ -107,6 +110,8 @@ export {
   type SSEMessage,
   type SSEStream,
   sse,
+  type TypedSSEStream,
+  typedSSEStream,
 } from "./server/sse.ts"
 export {
   type SignatureEncoding,

package/src/reflection.ts

@@ -0,0 +1,196 @@
+/**
+ * Runtime reflection for schemas and registered routes.
+ *
+ * Standard Schema deliberately standardizes validation, not introspection. This module makes that
+ * distinction explicit: `standard` is present when a value can validate, while `jsonSchema` and
+ * `fields` are present only when the value carries inspectable JSON Schema metadata. The implementation
+ * recognizes Nifra/TypeBox carriers and raw JSON Schema without depending on a validator package.
+ */
+
+import type { StandardSchemaV1 } from "./schema/standard.ts"
+import type { ToolAnnotations } from "./server/server.ts"
+
+/** JSON Schema permits either a schema object or the boolean schemas `true` and `false`. */
+export type JsonSchema = boolean | Readonly<Record<string, unknown>>
+
+/** One top-level property of an introspectable object schema. */
+export interface ReflectedSchemaField {
+  readonly name: string
+  readonly required: boolean
+  readonly schema: JsonSchema
+}
+
+/** Validation and introspection capabilities discovered for one schema-like value. */
+export interface SchemaReflection {
+  /** The Standard Schema validator, when the value implements Standard Schema v1. */
+  readonly standard: StandardSchemaV1 | undefined
+  /** Raw JSON Schema metadata, when the value exposes it or is itself a raw JSON Schema. */
+  readonly jsonSchema: JsonSchema | undefined
+  /** Top-level object fields, or `undefined` when the JSON Schema is absent/non-object. */
+  readonly fields: readonly ReflectedSchemaField[] | undefined
+}
+
+export interface ReflectedRouteSchema {
+  readonly body?: SchemaReflection
+  readonly query?: SchemaReflection
+  readonly response?: SchemaReflection
+  readonly errors?: Readonly<Record<string, SchemaReflection>>
+  /** The SSE event-payload schema of a typed streaming route (`app.sse()`). */
+  readonly sse?: SchemaReflection
+}
+
+export interface ReflectedRoute {
+  readonly method: string
+  readonly path: string
+  readonly schema?: ReflectedRouteSchema
+  readonly tool?: {
+    readonly name: string
+    readonly description: string
+    readonly annotations?: ToolAnnotations
+  }
+}
+
+const recordOf = (value: unknown): Readonly<Record<string, unknown>> | undefined =>
+  value !== null && typeof value === "object"
+    ? (value as Readonly<Record<string, unknown>>)
+    : undefined
+
+const standardOf = (value: unknown): StandardSchemaV1 | undefined => {
+  const record = recordOf(value)
+  const standard = recordOf(record?.["~standard"])
+  return standard?.version === 1 && typeof standard.validate === "function"
+    ? (value as StandardSchemaV1)
+    : undefined
+}
+
+const jsonSchemaOf = (
+  value: unknown,
+  standard: StandardSchemaV1 | undefined,
+): JsonSchema | undefined => {
+  const record = recordOf(value)
+  if (record !== undefined && "jsonSchema" in record) {
+    const carried = record.jsonSchema
+    return normalizeJsonSchema(carried)
+  }
+  // Some Standard Schema implementations (including TypeBox-shaped adapters) expose an object
+  // schema directly rather than through `.jsonSchema`. Only treat an inspectable object shape as
+  // metadata here; validation-library internals are otherwise intentionally opaque.
+  if (standard !== undefined) {
+    return recordOf(record?.properties) !== undefined ? normalizeJsonSchema(record) : undefined
+  }
+  // A malformed/opaque Standard Schema marker is not raw JSON Schema metadata.
+  if (record !== undefined && "~standard" in record) return undefined
+  if (typeof value === "boolean" || record !== undefined) return normalizeJsonSchema(value)
+  return undefined
+}
+
+/** Strip symbol keys and other non-JSON metadata carried by schema-builder objects. */
+const normalizeJsonSchema = (value: unknown): JsonSchema | undefined => {
+  if (typeof value === "boolean") return value
+  if (recordOf(value) === undefined) return undefined
+  try {
+    const normalized: unknown = JSON.parse(JSON.stringify(value))
+    if (typeof normalized === "boolean") return normalized
+    const record = recordOf(normalized)
+    if (record === undefined) return undefined
+    // `~standard` is a Standard Schema *validation* marker, never valid JSON Schema. A TypeBox-shaped
+    // 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
+    return rest
+  } catch {
+    return undefined
+  }
+}
+
+const fieldsOf = (schema: JsonSchema | undefined): readonly ReflectedSchemaField[] | undefined => {
+  const record = recordOf(schema)
+  const properties = recordOf(record?.properties)
+  if (properties === undefined) return undefined
+  const required = new Set(
+    Array.isArray(record?.required)
+      ? record.required.filter((name): name is string => typeof name === "string")
+      : [],
+  )
+  const fields: ReflectedSchemaField[] = []
+  for (const [name, property] of Object.entries(properties)) {
+    if (typeof property !== "boolean" && recordOf(property) === undefined) continue
+    fields.push({ name, required: required.has(name), schema: property as JsonSchema })
+  }
+  return fields
+}
+
+/**
+ * Reflect a Standard Schema, Nifra/TypeBox schema carrier, or raw JSON Schema. Never throws.
+ * Validation-only schemas have `standard` but no `jsonSchema`; raw JSON Schema has the reverse.
+ */
+export function reflectSchema(value: unknown): SchemaReflection {
+  const standard = standardOf(value)
+  const jsonSchema = jsonSchemaOf(value, standard)
+  return { standard, jsonSchema, fields: fieldsOf(jsonSchema) }
+}
+
+const routeCandidates = (source: unknown): readonly unknown[] => {
+  if (Array.isArray(source)) return source
+  const record = recordOf(source)
+  if (typeof record?.routes !== "function") return []
+  try {
+    const routes = record.routes()
+    return Array.isArray(routes) ? routes : []
+  } catch {
+    return []
+  }
+}
+
+const reflectedRouteSchema = (value: unknown): ReflectedRouteSchema | undefined => {
+  const schema = recordOf(value)
+  if (schema === undefined) return undefined
+  const errors = recordOf(schema.errors)
+  const reflectedErrors: Record<string, SchemaReflection> = {}
+  if (errors !== undefined) {
+    for (const [status, errorSchema] of Object.entries(errors)) {
+      reflectedErrors[status] = reflectSchema(errorSchema)
+    }
+  }
+  return {
+    ...(schema.body !== undefined ? { body: reflectSchema(schema.body) } : {}),
+    ...(schema.query !== undefined ? { query: reflectSchema(schema.query) } : {}),
+    ...(schema.response !== undefined ? { response: reflectSchema(schema.response) } : {}),
+    ...(Object.keys(reflectedErrors).length > 0 ? { errors: reflectedErrors } : {}),
+    ...(schema.sse !== undefined ? { sse: reflectSchema(schema.sse) } : {}),
+  }
+}
+
+const reflectedTool = (value: unknown): ReflectedRoute["tool"] => {
+  const tool = recordOf(value)
+  if (typeof tool?.name !== "string" || typeof tool.description !== "string") return undefined
+  return {
+    name: tool.name,
+    description: tool.description,
+    ...(recordOf(tool.annotations) !== undefined
+      ? { annotations: tool.annotations as ToolAnnotations }
+      : {}),
+  }
+}
+
+/**
+ * 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.
+ */
+export function reflectRoutes(source: unknown): readonly ReflectedRoute[] {
+  const reflected: ReflectedRoute[] = []
+  for (const candidate of routeCandidates(source)) {
+    const route = recordOf(candidate)
+    if (typeof route?.method !== "string" || typeof route.path !== "string") continue
+    const schema = reflectedRouteSchema(route.schema)
+    const tool = reflectedTool(route.tool)
+    reflected.push({
+      method: route.method.toUpperCase(),
+      path: route.path,
+      ...(schema !== undefined ? { schema } : {}),
+      ...(tool !== undefined ? { tool } : {}),
+    })
+  }
+  return reflected
+}

package/src/server/context.ts

@@ -39,6 +39,14 @@ export interface RouteSchema {
    * to tooling and coding agents. Like `response`, it is **not** validated at runtime (zero hot-path cost);
    * it's a compile-time + introspection contract. Example: `{ 404: NotFound, 409: Conflict }`. */
   readonly errors?: Readonly<Record<number, StandardSchemaV1>>
+  /**
+   * Optional **SSE event contract**: the Standard Schema of each event's `data` payload on a
+   * streaming route (declared via `app.sse()`). Marks the route as a typed event stream — the
+   * typed client grows a `.subscribe()` for it, and the schema flows into reflection. Like
+   * `response`, it is **not** validated at runtime (zero hot-path cost); the server-side
+   * `stream.send()` is compile-time-checked against it instead.
+   */
+  readonly sse?: StandardSchemaV1
   /**
    * Hook fired when the request fails `body`/`query` validation, before the handler runs. `kind` says
    * which input failed (`"body"` | `"query"`). Its return value selects one of three outcomes (may be async):

package/src/server/contract.ts

@@ -92,6 +92,9 @@ type RouteInfoForOp<O extends OperationDef> = {
   // The error union from the op's non-2xx `responses` — so a decoupled contract client sees typed error
   // bodies, just like an inline route's `errors`. `unknown` when the op declares no error responses.
   readonly errors: OpErrors<O>
+  // Contract operations cannot declare an SSE event contract (yet) — `never` keeps the contract
+  // registry mutually assignable with the inline registry's RouteInfoFor (mode conformance).
+  readonly sse: never
 }
 
 /** Re-key the name-keyed ops into the `path → method → RouteInfo` registry. */
@@ -191,6 +194,8 @@ export type RegistryFromImpl<C extends ContractShape, H extends HandlersFor<C>>
       // The error union from the op's non-2xx `responses` (see OpErrors) — a graduated contract client sees
       // the same typed error bodies as the inline `errors` path.
       readonly errors: OpErrors<C[K]>
+      // Mirrors RouteInfoForOp: no SSE contract on contract ops (yet) — mode conformance holds.
+      readonly sse: never
     }
   }
 }

package/src/server/registry.ts

@@ -19,6 +19,9 @@ export interface RouteInfo {
   /** Union of the route's declared error-response body types (from `schema.errors`); `unknown` when the
    * route declares none. Surfaced by the typed client as the failure `errorData`. */
   readonly errors?: unknown
+  /** The SSE event payload type (from `schema.sse`, declared via `app.sse()`); `never` for ordinary
+   * routes. The typed client keys `.subscribe()` availability and its event type off this. */
+  readonly sse?: unknown
 }
 
 /** The accumulated, type-level map of every route on a Server: path → method → RouteInfo. */
@@ -51,6 +54,11 @@ type RegistryErrors<S extends RouteSchema> = S extends {
   ? { [K in keyof E]: E[K] extends StandardSchemaV1 ? InferOutput<E[K]> : never }[keyof E]
   : unknown
 
+/** The SSE event payload type from a route's `sse` schema; `never` for ordinary routes. */
+type RegistrySse<S extends RouteSchema> = S extends { sse: infer E extends StandardSchemaV1 }
+  ? InferOutput<E>
+  : never
+
 /** Build a {@link RouteInfo} from a route's path, schema, and handler output type. */
 export type RouteInfoFor<Path extends string, S extends RouteSchema, Output> = {
   readonly params: Params<Path>
@@ -58,6 +66,7 @@ export type RouteInfoFor<Path extends string, S extends RouteSchema, Output> = {
   readonly body: RegistryBody<S>
   readonly output: RegistryOutput<S, Output>
   readonly errors: RegistryErrors<S>
+  readonly sse: RegistrySse<S>
 }
 
 /** The client-visible output of a handler: its awaited return, minus raw `Response`. */