@nifrajs/core 1.4.0 → 1.5.0

package/dist/server/sse.d.ts

@@ -50,5 +50,21 @@ export interface SSEInit {
     /** Send a `: ` comment ping every N ms so idle proxies don't drop the connection. */
     readonly keepAlive?: number;
 }
+/**
+ * The stream handed to an `app.sse()` handler: `send` takes the route's TYPED event payload and
+ * serializes it (JSON) into the SSE `data:` field — the compile-time half of the `sse` contract.
+ */
+export interface TypedSSEStream<Event> {
+    /** Send one typed event. `init` sets the optional SSE frame fields (`event`, `id`, `retry`). */
+    send(event: Event, init?: Pick<SSEMessage, "event" | "id" | "retry">): void;
+    /** Send a `: comment` line (e.g. an explicit ping). */
+    comment(text: string): void;
+    /** End the stream now. */
+    close(): void;
+    /** Aborts when the client disconnects — use it to tear down subscriptions/loops. */
+    readonly signal: AbortSignal;
+}
+/** Wrap a raw {@link SSEStream} in the typed, JSON-serializing surface `app.sse()` hands out. */
+export declare function typedSSEStream<Event>(stream: SSEStream): TypedSSEStream<Event>;
 export declare function sse(c: SSEContext, run: (stream: SSEStream) => void | Promise<void>, init?: SSEInit): Response;
 //# sourceMappingURL=sse.d.ts.map

package/dist/server/sse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/server/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,4GAA4G;AAC5G,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;IACpB,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,mDAAmD;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,+CAA+C;AAC/C,MAAM,WAAW,SAAS;IACxB,+DAA+D;IAC/D,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAAA;IAC/B,0BAA0B;IAC1B,KAAK,IAAI,IAAI,CAAA;IACb,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAC7B;AAED,8FAA8F;AAC9F,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;CACtB;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IAGxB,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,CAAA;IAC3D,qFAAqF;IACrF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAwBD,wBAAgB,GAAG,CACjB,CAAC,EAAE,UAAU,EACb,GAAG,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EAChD,IAAI,GAAE,OAAY,GACjB,QAAQ,CA2EV"}
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/server/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,4GAA4G;AAC5G,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;IACpB,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,mDAAmD;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,+CAA+C;AAC/C,MAAM,WAAW,SAAS;IACxB,+DAA+D;IAC/D,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAAA;IAC/B,0BAA0B;IAC1B,KAAK,IAAI,IAAI,CAAA;IACb,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAC7B;AAED,8FAA8F;AAC9F,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;CACtB;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IAGxB,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,CAAA;IAC3D,qFAAqF;IACrF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,KAAK;IACnC,gGAAgG;IAChG,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,GAAG,IAAI,CAAA;IAC3E,uDAAuD;IACvD,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,0BAA0B;IAC1B,KAAK,IAAI,IAAI,CAAA;IACb,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAC7B;AAED,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,GAAG,cAAc,CAAC,KAAK,CAAC,CAW9E;AAwBD,wBAAgB,GAAG,CACjB,CAAC,EAAE,UAAU,EACb,GAAG,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EAChD,IAAI,GAAE,OAAY,GACjB,QAAQ,CA2EV"}

package/dist/server/sse.js

@@ -21,6 +21,19 @@
  *       stream.signal.addEventListener("abort", () => { off(); resolve() }, { once: true }))
  *   }, { keepAlive: 15_000 }))
  */
+/** Wrap a raw {@link SSEStream} in the typed, JSON-serializing surface `app.sse()` hands out. */
+export function typedSSEStream(stream) {
+    return {
+        send(event, init = {}) {
+            stream.send({ ...init, data: JSON.stringify(event) });
+        },
+        comment(text) {
+            stream.send({ comment: text });
+        },
+        close: stream.close,
+        signal: stream.signal,
+    };
+}
 const CRLF = /[\r\n]/g;
 const LINE_SPLIT = /\r\n|\r|\n/;
 /** `event:`/`id:`/`comment` must be single-line — stripping CR/LF prevents SSE frame injection. */

package/dist/server/sse.js.map

@@ -1 +1 @@
-{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../src/server/sse.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../src/server/sse.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/core",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Bun-native, contract-first HTTP framework — the router, server, and route descriptor.",
   "keywords": [
     "bun",
@@ -36,6 +36,11 @@
       "bun": "./src/reflection.ts",
       "types": "./dist/reflection.d.ts",
       "default": "./dist/reflection.js"
+    },
+    "./diff": {
+      "bun": "./src/diff.ts",
+      "types": "./dist/diff.d.ts",
+      "default": "./dist/diff.js"
     }
   },
   "files": [

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,10 +12,11 @@
  * (it shipped at "0.0.0" through 1.0.0 before those guards existed). Kept narrow (`as const`) so
  * consumers can pin it at the type level — see `test/version.test-d.ts`.
  */
-export const VERSION = "1.4.0" 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"
@@ -92,6 +93,7 @@ export {
   type OnRequestResult,
   type PromptArgument,
   type PromptMessage,
+  type ResponseFinalization,
   type RouteDescriptor,
   type RunningServer,
   type ScheduledController,
@@ -108,6 +110,8 @@ export {
   type SSEMessage,
   type SSEStream,
   sse,
+  type TypedSSEStream,
+  typedSSEStream,
 } from "./server/sse.ts"
 export {
   type SignatureEncoding,

package/src/reflection.ts

@@ -35,6 +35,8 @@ export interface ReflectedRouteSchema {
   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 {
@@ -156,6 +158,7 @@ const reflectedRouteSchema = (value: unknown): ReflectedRouteSchema | undefined
     ...(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) } : {}),
   }
 }
 

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`. */