@nifrajs/core 2.11.0 → 2.12.0

package/src/internal/route-execution.ts

@@ -17,11 +17,14 @@
  * The `Server` import is type-only and erased, so there is no runtime cycle back into the kernel.
  */
 import type { RequestBudget } from "../budget.ts"
+import type { RequestLedger } from "../ledger.ts"
 import type { StandardSchemaV1 } from "../schema/standard.ts"
 import type { Platform, RouteSchema } from "../server/context.ts"
 import type { ResolvedIdempotency } from "../server/idempotency-lane.ts"
-import type { ResolvedEffectLedger } from "../server/ledger-lane.ts"
+import type { EffectLedgerRuntime, ResolvedEffectLedger } from "../server/ledger-lane.ts"
+import type { ProtoPoisoning } from "../server/proto-guard.ts"
 import type { Registry } from "../server/registry.ts"
+import { RequestContext } from "../server/request-context.ts"
 import type { ResponseContractRuntime } from "../server/response-contract-lane.ts"
 import type { HandlerResult } from "../server/runtime-core.ts"
 import type { CtxSet, MaybePromise, RawContext, RequestSource, Server } from "../server/server.ts"
@@ -58,6 +61,276 @@ export type ContextRouteRunner = <T, R extends Registry, Ctx>(
   wrapResponse: (response: Response) => T,
 ) => MaybePromise<T>
 
+/** The kernel's private execution surface, mirrored structurally. The runner methods are private on
+ * `Server` by design; this compiler lives outside the class, so it reaches them through a type-level
+ * mirror of their exact signatures. The `as unknown as` at each use is erased by compilation - the
+ * request path calls the kernel methods directly, with no adapter object and no extra hop. The mirror
+ * is not exported: it is this module's view of the kernel, not vocabulary anyone else may bind to. */
+interface RouteExecutionRuntime {
+  runContextlessBare<T>(
+    entry: RouteEntry,
+    source: RequestSource,
+    params: Record<string, string>,
+    search: string | undefined,
+    signal: AbortSignal,
+    budget: RequestBudget,
+    platform: Platform | undefined,
+    finalize: (result: unknown, set: CtxSet) => T,
+    wrapResponse: (response: Response) => T,
+  ): MaybePromise<T>
+  runBare<T>(
+    entry: RouteEntry,
+    ctx: RawContext,
+    finalize: (result: unknown, set: CtxSet) => T,
+    wrapResponse: (response: Response) => T,
+  ): MaybePromise<T>
+  runBodyOnly<T>(
+    entry: RouteEntry,
+    source: RequestSource,
+    ctx: RawContext,
+    finalize: (result: unknown, set: CtxSet) => T,
+    wrapResponse: (response: Response) => T,
+  ): MaybePromise<T>
+  runQueryOnly<T>(
+    entry: RouteEntry,
+    ctx: RawContext,
+    finalize: (result: unknown, set: CtxSet) => T,
+    wrapResponse: (response: Response) => T,
+  ): MaybePromise<T>
+  runLifecycleHooks<T>(
+    entry: RouteEntry,
+    ctx: RawContext,
+    finalize: (result: unknown, set: CtxSet) => T,
+    wrapResponse: (response: Response) => T,
+  ): MaybePromise<T>
+  runLifecycleQuery<T>(
+    entry: RouteEntry,
+    ctx: RawContext,
+    finalize: (result: unknown, set: CtxSet) => T,
+    wrapResponse: (response: Response) => T,
+  ): MaybePromise<T>
+  runLifecycleBody<T>(
+    entry: RouteEntry,
+    source: RequestSource,
+    ctx: RawContext,
+    finalize: (result: unknown, set: CtxSet) => T,
+    wrapResponse: (response: Response) => T,
+  ): MaybePromise<T>
+  runLifecycleBodyQuery<T>(
+    entry: RouteEntry,
+    source: RequestSource,
+    ctx: RawContext,
+    finalize: (result: unknown, set: CtxSet) => T,
+    wrapResponse: (response: Response) => T,
+  ): MaybePromise<T>
+  runLifecycle<T>(
+    entry: RouteEntry,
+    source: RequestSource,
+    ctx: RawContext,
+    finalize: (result: unknown, set: CtxSet) => T,
+    wrapResponse: (response: Response) => T,
+  ): MaybePromise<T>
+  runWithAround<T>(
+    entry: RouteEntry,
+    ctx: RawContext,
+    run: () => MaybePromise<T>,
+    finalize: (result: unknown, set: CtxSet) => T,
+    wrapResponse: (response: Response) => T,
+  ): MaybePromise<T>
+  readonly maxBodyBytes: number
+  readonly protoPoisoning: ProtoPoisoning
+  readonly effectLedgerRuntime: EffectLedgerRuntime | undefined
+  readonly logger: {
+    error(message: string, fields: { method: string; path: string; name: string }): void
+  }
+}
+
+export type RouteExecutionLane = "bare" | "body" | "query" | "lifecycle"
+export type LifecycleExecutionLane = "hooks" | "query" | "body" | "body-query" | undefined
+
+/** Compile the one immutable route decision at registration time. The request path only invokes the
+ * selected closure; it never repeats this eligibility ladder. The closures reach the kernel's private
+ * runners through the {@link RouteExecutionRuntime} mirror - a compile-time cast, not a dispatch
+ * object, so the emitted request path is a direct method call on the server. */
+export function compileRouteExecutionPlan(options: {
+  readonly lane: RouteExecutionLane
+  readonly contextless: boolean
+  readonly hasAround: boolean
+  readonly hasLedger: boolean
+  readonly lifecycleLane: LifecycleExecutionLane
+  readonly fusedWeb: FusedWebRunner | undefined
+  readonly fusedBody: FusedBodyRunner | undefined
+  readonly fusedLane: "bare" | "body" | "query" | undefined
+}): RouteExecutionPlan {
+  const { lane, contextless, hasAround, hasLedger, lifecycleLane, fusedWeb, fusedBody, fusedLane } =
+    options
+
+  if (contextless) {
+    const run: RouteExecutionRunner = (
+      runtime,
+      entry,
+      source,
+      params,
+      search,
+      signal,
+      budget,
+      platform,
+      _nativeContext,
+      finalize,
+      wrapResponse,
+    ) =>
+      (runtime as unknown as RouteExecutionRuntime).runContextlessBare(
+        entry,
+        source,
+        params,
+        search,
+        signal,
+        budget,
+        platform,
+        finalize,
+        wrapResponse,
+      )
+    return Object.freeze({ run, fusedWeb, fusedBody, fusedLane })
+  }
+
+  let inner: ContextRouteRunner
+  switch (lane) {
+    case "bare":
+      inner = (runtime, entry, _source, ctx, finalize, wrapResponse) =>
+        (runtime as unknown as RouteExecutionRuntime).runBare(entry, ctx, finalize, wrapResponse)
+      break
+    case "body":
+      inner = (runtime, entry, source, ctx, finalize, wrapResponse) =>
+        (runtime as unknown as RouteExecutionRuntime).runBodyOnly(
+          entry,
+          source,
+          ctx,
+          finalize,
+          wrapResponse,
+        )
+      break
+    case "query":
+      inner = (runtime, entry, _source, ctx, finalize, wrapResponse) =>
+        (runtime as unknown as RouteExecutionRuntime).runQueryOnly(
+          entry,
+          ctx,
+          finalize,
+          wrapResponse,
+        )
+      break
+    default:
+      switch (lifecycleLane) {
+        case "hooks":
+          inner = (runtime, entry, _source, ctx, finalize, wrapResponse) =>
+            (runtime as unknown as RouteExecutionRuntime).runLifecycleHooks(
+              entry,
+              ctx,
+              finalize,
+              wrapResponse,
+            )
+          break
+        case "query":
+          inner = (runtime, entry, _source, ctx, finalize, wrapResponse) =>
+            (runtime as unknown as RouteExecutionRuntime).runLifecycleQuery(
+              entry,
+              ctx,
+              finalize,
+              wrapResponse,
+            )
+          break
+        case "body":
+          inner = (runtime, entry, source, ctx, finalize, wrapResponse) =>
+            (runtime as unknown as RouteExecutionRuntime).runLifecycleBody(
+              entry,
+              source,
+              ctx,
+              finalize,
+              wrapResponse,
+            )
+          break
+        case "body-query":
+          inner = (runtime, entry, source, ctx, finalize, wrapResponse) =>
+            (runtime as unknown as RouteExecutionRuntime).runLifecycleBodyQuery(
+              entry,
+              source,
+              ctx,
+              finalize,
+              wrapResponse,
+            )
+          break
+        default:
+          inner = (runtime, entry, source, ctx, finalize, wrapResponse) =>
+            (runtime as unknown as RouteExecutionRuntime).runLifecycle(
+              entry,
+              source,
+              ctx,
+              finalize,
+              wrapResponse,
+            )
+      }
+  }
+
+  const execute: ContextRouteRunner = hasAround
+    ? (runtime, entry, source, ctx, finalize, wrapResponse) =>
+        (runtime as unknown as RouteExecutionRuntime).runWithAround(
+          entry,
+          ctx,
+          () => inner(runtime, entry, source, ctx, finalize, wrapResponse),
+          finalize,
+          wrapResponse,
+        )
+    : inner
+
+  const run: RouteExecutionRunner = (
+    runtime,
+    entry,
+    source,
+    params,
+    search,
+    signal,
+    budget,
+    platform,
+    nativeContext,
+    finalize,
+    wrapResponse,
+  ) => {
+    const server = runtime as unknown as RouteExecutionRuntime
+    const maxBodyBytes = entry.bodyLimit ?? server.maxBodyBytes
+    const ctx = nativeContext
+      ? RequestContext.native(source, params, search, maxBodyBytes, platform, server.protoPoisoning)
+      : new RequestContext(
+          source,
+          params,
+          search,
+          signal,
+          budget,
+          platform,
+          maxBodyBytes,
+          server.protoPoisoning,
+        )
+    let ledger: RequestLedger | undefined
+    // The runtime is always present when a route resolved a ledger (enforced at registration).
+    const ledgerRuntime = server.effectLedgerRuntime
+    if (hasLedger && ledgerRuntime !== undefined) {
+      const resolved = entry.ledgered as ResolvedEffectLedger
+      ledger = ledgerRuntime.create(resolved)
+      ledgerRuntime.attach(ctx, ledger)
+    }
+    let outcome = execute(runtime, entry, source, ctx, finalize, wrapResponse)
+    if (ledger !== undefined && ledgerRuntime !== undefined) {
+      const active = ledger
+      const resolved = entry.ledgered as ResolvedEffectLedger
+      outcome = (outcome instanceof Promise ? outcome : Promise.resolve(outcome)).then((value) =>
+        ledgerRuntime.settle(active, resolved, value, (fields) =>
+          server.logger.error("effect ledger sink failed", fields),
+        ),
+      )
+    }
+    return outcome
+  }
+  return Object.freeze({ run, fusedWeb, fusedBody, fusedLane })
+}
+
 /** Registration-compiled route behavior. Every adapter invokes the same runner; the optional fused
  * renderer is only a response-format specialization of that same selected route semantics. */
 export interface RouteExecutionPlan {
@@ -73,6 +346,8 @@ export interface RouteExecutionPlan {
 export interface RouteEntry {
   readonly handler: InternalHandler
   readonly schema: RouteSchema | undefined
+  /** Effective transport body cap; `undefined` is an explicit streaming/upload exemption. */
+  readonly bodyLimit: number | undefined
   /** Resolved idempotency config; `undefined` = off (the dedupe lane is never entered). */
   readonly idempotent: ResolvedIdempotency | undefined
   /** Resolved effect-ledger wiring; `undefined` = off (no per-request ledger, no settle step). */

package/src/manifest.ts

@@ -14,6 +14,7 @@ import {
   type RouteSnapshotSchema,
   snapshotRoutes,
 } from "./diff.ts"
+import type { ProjectEvidenceSnapshot } from "./evidence.ts"
 import { reflectRoutes } from "./reflection.ts"
 
 export interface NifraManifestAssurance {
@@ -60,7 +61,10 @@ export interface NifraManifestSignature {
 }
 
 export interface BuildNifraManifestInput {
-  readonly source: unknown
+  /** Runtime route source, retained for compatibility with callers that have not built a snapshot. */
+  readonly source?: unknown
+  /** Canonical offline evidence; when supplied, no second route reflection is performed. */
+  readonly evidence?: ProjectEvidenceSnapshot
   readonly assurance?: AssuranceReport
   readonly capabilities?: CapabilityAssuranceReport
 }
@@ -171,22 +175,40 @@ const sortedStrings = (values: Iterable<string>): readonly string[] =>
 
 /** Build one fail-closed, deterministic manifest from already-evaluated assurance reports. */
 export async function buildNifraManifest(input: BuildNifraManifestInput): Promise<NifraManifest> {
+  if (input.evidence === undefined && input.source === undefined) {
+    throw new TypeError("nifra manifest: source or canonical evidence is required")
+  }
   if (input.assurance !== undefined && !input.assurance.ok) {
     throw new Error("nifra manifest: refusing to emit failing route assurance")
   }
+  if (input.evidence?.assurance !== undefined && !input.evidence.assurance.ok) {
+    throw new Error("nifra manifest: refusing to emit failing route assurance")
+  }
   if (input.capabilities !== undefined && !input.capabilities.ok) {
     throw new Error("nifra manifest: refusing to emit failing capability assurance")
   }
+  if (input.evidence?.capabilities !== undefined && !input.evidence.capabilities.ok) {
+    throw new Error("nifra manifest: refusing to emit failing capability assurance")
+  }
   const reflected = new Map(
-    reflectRoutes(input.source).map((route) => [routeKey(route.method, route.path), route]),
+    (input.evidence?.routes ?? reflectRoutes(input.source)).map((route) => [
+      routeKey(route.method, route.path),
+      route,
+    ]),
   )
   const assured = new Map(
-    (input.assurance?.routes ?? []).map((route) => [routeKey(route.method, route.path), route]),
+    (input.evidence?.assurance?.routes ?? input.assurance?.routes ?? []).map((route) => [
+      routeKey(route.method, route.path),
+      route,
+    ]),
   )
   const capable = new Map(
-    (input.capabilities?.routes ?? []).map((route) => [routeKey(route.method, route.path), route]),
+    (input.evidence?.capabilities?.routes ?? input.capabilities?.routes ?? []).map((route) => [
+      routeKey(route.method, route.path),
+      route,
+    ]),
   )
-  const routes = snapshotRoutes(input.source)
+  const routes = (input.evidence?.routes ?? snapshotRoutes(input.source))
     .map((route): NifraManifestRoute => {
       const key = routeKey(route.method, route.path)
       const reflection = reflected.get(key)

package/src/reflection.ts

@@ -13,7 +13,11 @@ import {
   routeClassification,
 } from "./classification.ts"
 import { normalizeRouteCapabilities } from "./internal/capability-runtime.ts"
-import { type AssuranceEvidence, validEvidence } from "./internal/route-assurance.ts"
+import {
+  type AssuranceEvidence,
+  evidenceProvenance,
+  validEvidence,
+} from "./internal/route-assurance.ts"
 import type { StandardSchemaV1 } from "./schema/standard.ts"
 import type { ToolAnnotations } from "./server/server.ts"
 
@@ -38,6 +42,11 @@ export interface SchemaReflection {
 }
 
 export interface ReflectedRouteSchema {
+  /** Effective transport body policy; surfaced so upload/streaming exemptions are auditable. */
+  readonly bodyLimit?: number | "unlimited"
+  readonly bodyLimitReason?: string
+  /** Request-header schema; names are normalized to lower-case at runtime. */
+  readonly headers?: SchemaReflection
   readonly body?: SchemaReflection
   readonly query?: SchemaReflection
   /** Path-params schema - constraints (uuid format, integer min/max) declared via `params: t.object(…)`. */
@@ -170,6 +179,13 @@ const reflectedRouteSchema = (value: unknown): ReflectedRouteSchema | undefined
     }
   }
   return {
+    ...(schema.bodyLimit === "unlimited" || typeof schema.bodyLimit === "number"
+      ? { bodyLimit: schema.bodyLimit }
+      : {}),
+    ...(typeof schema.bodyLimitReason === "string"
+      ? { bodyLimitReason: schema.bodyLimitReason }
+      : {}),
+    ...(schema.headers !== undefined ? { headers: reflectSchema(schema.headers) } : {}),
     ...(schema.body !== undefined ? { body: reflectSchema(schema.body) } : {}),
     ...(schema.query !== undefined ? { query: reflectSchema(schema.query) } : {}),
     ...(schema.params !== undefined ? { params: reflectSchema(schema.params) } : {}),
@@ -193,9 +209,13 @@ const reflectedTool = (value: unknown): ReflectedRoute["tool"] => {
 
 const reflectedAssurance = (value: unknown): readonly AssuranceEvidence[] | undefined => {
   if (!Array.isArray(value)) return undefined
-  const evidence = value
-    .filter(validEvidence)
-    .map((item) => Object.freeze({ id: item.id, source: item.source.trim() }))
+  const evidence = value.filter(validEvidence).map((item) =>
+    Object.freeze({
+      id: item.id,
+      source: item.source.trim(),
+      provenance: evidenceProvenance(item),
+    }),
+  )
   return evidence.length > 0 ? Object.freeze(evidence) : undefined
 }
 

package/src/replay.ts

@@ -0,0 +1,96 @@
+/** Versioned, token-only replay metadata shared by verification tools. */
+
+export interface ReplayFile {
+  readonly version: 1
+  readonly gate: string
+  readonly case: string
+  readonly seed: string
+  readonly inputsDigest: string
+  readonly meta: Readonly<Record<string, unknown>>
+}
+
+/** Existing adversarial contract replay metadata. Kept as a compatibility envelope. */
+export interface LegacyContractReplayFile {
+  readonly seed: number
+  readonly caseId: string
+  readonly runtime: string
+}
+
+/** Existing deterministic failure-lab replay metadata. Kept as a compatibility envelope. */
+export interface LegacyFailureReplayFile {
+  readonly seed: number
+  readonly schedule: readonly Record<string, unknown>[]
+}
+
+export type CompatibleReplayFile = ReplayFile | LegacyContractReplayFile | LegacyFailureReplayFile
+
+export function defineReplayFile(input: Omit<ReplayFile, "version">): ReplayFile {
+  if (input.gate.trim() === "" || input.case.trim() === "" || input.seed.trim() === "")
+    throw new TypeError("replay metadata requires gate, case, and seed")
+  if (!/^[a-f0-9]{64}$/.test(input.inputsDigest))
+    throw new TypeError("replay inputsDigest must be a SHA-256 hex digest")
+  return Object.freeze({ version: 1, ...input, meta: Object.freeze({ ...input.meta }) })
+}
+
+export function parseReplayFile(value: unknown): ReplayFile {
+  const record =
+    typeof value === "object" && value !== null && !Array.isArray(value)
+      ? Object.fromEntries(Object.entries(value))
+      : undefined
+  if (record === undefined) throw new TypeError("invalid replay file")
+  const meta =
+    typeof record.meta === "object" && record.meta !== null && !Array.isArray(record.meta)
+      ? Object.fromEntries(Object.entries(record.meta))
+      : undefined
+  const gate = typeof record.gate === "string" ? record.gate : undefined
+  const caseId = typeof record.case === "string" ? record.case : undefined
+  const seed = typeof record.seed === "string" ? record.seed : undefined
+  const inputsDigest = typeof record.inputsDigest === "string" ? record.inputsDigest : undefined
+  if (
+    record.version !== 1 ||
+    gate === undefined ||
+    caseId === undefined ||
+    seed === undefined ||
+    inputsDigest === undefined ||
+    meta === undefined
+  ) {
+    throw new TypeError("invalid replay file: expected version 1 metadata")
+  }
+  return defineReplayFile({
+    gate,
+    case: caseId,
+    seed,
+    inputsDigest,
+    meta,
+  })
+}
+
+/** Parse the unified format while preserving the two pre-existing token-only replay shapes. */
+export function parseCompatibleReplayFile(value: unknown): CompatibleReplayFile {
+  try {
+    return parseReplayFile(value)
+  } catch {
+    const record =
+      typeof value === "object" && value !== null && !Array.isArray(value)
+        ? Object.fromEntries(Object.entries(value))
+        : undefined
+    if (
+      typeof record?.seed === "number" &&
+      Number.isSafeInteger(record.seed) &&
+      typeof record.caseId === "string" &&
+      record.caseId.trim() !== "" &&
+      typeof record.runtime === "string" &&
+      record.runtime.trim() !== ""
+    ) {
+      return Object.freeze({ seed: record.seed, caseId: record.caseId, runtime: record.runtime })
+    }
+    if (
+      typeof record?.seed === "number" &&
+      Number.isSafeInteger(record.seed) &&
+      Array.isArray(record.schedule)
+    ) {
+      return Object.freeze({ seed: record.seed, schedule: Object.freeze([...record.schedule]) })
+    }
+    throw new TypeError("invalid replay file: expected unified or legacy token-only metadata")
+  }
+}

package/src/schema/standard.ts

@@ -53,6 +53,22 @@ export type ValidationOutcome<Output> =
   | { readonly ok: true; readonly value: Output }
   | { readonly ok: false; readonly issues: ReadonlyArray<StandardIssue> }
 
+/** Format Standard Schema issues consistently across server and client contract diagnostics. */
+export function formatStandardIssues(issues: ReadonlyArray<StandardIssue>): string {
+  return issues
+    .map((issue) => {
+      const path = Array.isArray(issue.path)
+        ? issue.path
+            .map((segment) =>
+              String(typeof segment === "object" && segment !== null ? segment.key : segment),
+            )
+            .join(".")
+        : ""
+      return path === "" ? issue.message : `${path}: ${issue.message}`
+    })
+    .join("; ")
+}
+
 function normalizeStandardResult<Output>(
   result: StandardResult<Output>,
 ): ValidationOutcome<Output> {