@nifrajs/core 1.12.0 → 2.0.0

package/src/server/contract.ts

@@ -4,7 +4,7 @@ import { normalizeRouteCapabilities } from "../internal/capability-runtime.ts"
 import { METHODS, type Method } from "../router/router.ts"
 import type { InferOutput, StandardSchemaV1 } from "../schema/standard.ts"
 import type { Context, IdempotencyConfig, Params, RouteSchema } from "./context.ts"
-import type { OutputOf } from "./registry.ts"
+import type { EmptyRegistry, OutputOf, Registry } from "./registry.ts"
 import { Server } from "./server.ts"
 
 /** An additional (non-success) response a contract operation can document, e.g. a `404`. */
@@ -26,6 +26,8 @@ export interface ResponseDef {
 export interface OperationDef {
   readonly method: Method
   readonly path: string
+  /** Optional path-params schema (validated + coercible at the boundary; see {@link RouteSchema.params}). */
+  readonly params?: StandardSchemaV1
   readonly body?: StandardSchemaV1
   readonly query?: StandardSchemaV1
   readonly response?: StandardSchemaV1
@@ -35,6 +37,10 @@ export interface OperationDef {
   readonly idempotency?: IdempotencyConfig
   /** Highest data-sensitivity the response carries (see {@link RouteSchema.classification}). */
   readonly classification?: DataClassification
+  /** Inline route-assurance evidence this operation carries (see {@link RouteSchema.assurance}). */
+  readonly assurance?: readonly string[]
+  /** Mark this operation a dynamic route family (see {@link RouteSchema.family}). */
+  readonly family?: boolean
   /** Short summary (OpenAPI `summary`). */
   readonly summary?: string
   /** Longer description (OpenAPI `description`, CommonMark). */
@@ -68,21 +74,27 @@ type OpResponse<O extends OperationDef> = O extends { response: infer R extends
 
 /** The body types of a contract op's declared **non-2xx** `responses` (schema-bearing ones), keyed by status. */
 type OpErrorBodies<Rs extends Record<string, ResponseDef>> = {
-  [K in keyof Rs as K extends `2${string}` ? never : K]: Rs[K] extends {
+  // Non-2xx statuses, re-keyed from the contract's string keys ("404") to number literals (404) so
+  // the client's failure union discriminates on the numeric `status` it actually receives.
+  [K in keyof Rs as K extends `2${string}`
+    ? never
+    : K extends `${infer N extends number}`
+      ? N
+      : never]: Rs[K] extends {
     schema: infer S extends StandardSchemaV1
   }
     ? InferOutput<S>
     : never
 }
 
-/** The client-visible error union for a contract op — the union of its non-2xx `responses` body schemas,
- * or `unknown` when it declares none (mirrors an inline route with no `errors`). */
+/** The client-visible error bodies for a contract op as a status-keyed record (`{ 404: Body }`), or
+ * `unknown` when it declares none (mirrors an inline route with no `errors`). */
 type OpErrors<O extends OperationDef> = O extends {
   responses: infer Rs extends Record<string, ResponseDef>
 }
-  ? [OpErrorBodies<Rs>[keyof OpErrorBodies<Rs>]] extends [never]
+  ? [keyof OpErrorBodies<Rs>] extends [never]
     ? unknown
-    : OpErrorBodies<Rs>[keyof OpErrorBodies<Rs>]
+    : OpErrorBodies<Rs>
   : unknown
 
 /**
@@ -116,7 +128,8 @@ export type RegistryFor<C extends ContractShape> = {
 type SchemaForOp<O extends OperationDef> = (O extends { body: infer B extends StandardSchemaV1 }
   ? { body: B }
   : Record<never, never>) &
-  (O extends { query: infer Q extends StandardSchemaV1 } ? { query: Q } : Record<never, never>)
+  (O extends { query: infer Q extends StandardSchemaV1 } ? { query: Q } : Record<never, never>) &
+  (O extends { params: infer P extends StandardSchemaV1 } ? { params: P } : Record<never, never>)
 
 /**
  * The handler context for an op — identical to the inline `Context<Path, S>`, so a
@@ -140,9 +153,13 @@ type HandlerReturnForOp<O extends OperationDef> = O extends {
   ? Response | InferOutput<R>
   : unknown
 
-/** The handlers `implement` requires: one per operation, typed from the op's input + response contract. */
-export type HandlersFor<C extends ContractShape> = {
-  [K in keyof C]: (context: ContextForOp<C[K]>) => MaybePromise<HandlerReturnForOp<C[K]>>
+/**
+ * The handlers `implement` requires: one per operation, typed from the op's input + response contract,
+ * intersected with the host app's accumulated `derive`/`decorate` context - the same
+ * `Context & Ctx` an inline {@link Handler} receives, so a handler graduates either way unchanged.
+ */
+export type HandlersFor<C extends ContractShape, Ctx = NonNullable<unknown>> = {
+  [K in keyof C]: (context: ContextForOp<C[K]> & Ctx) => MaybePromise<HandlerReturnForOp<C[K]>>
 }
 
 const METHOD_SET: ReadonlySet<string> = new Set(METHODS)
@@ -189,7 +206,11 @@ type AnyFn = (...args: never[]) => unknown
  * the implemented server stays route-for-route identical to the equivalent inline server (the
  * mode-conformance guarantee), and a contract-typed client and a `typeof app`-typed client agree.
  */
-export type RegistryFromImpl<C extends ContractShape, H extends HandlersFor<C>> = {
+export type RegistryFromImpl<
+  C extends ContractShape,
+  H extends HandlersFor<C, Ctx>,
+  Ctx = NonNullable<unknown>,
+> = {
   [P in C[keyof C]["path"]]: {
     [K in keyof C as C[K]["path"] extends P ? C[K]["method"] : never]: {
       readonly params: Params<C[K]["path"]>
@@ -215,42 +236,64 @@ export type RegistryFromImpl<C extends ContractShape, H extends HandlersFor<C>>
  * builder, so the result is identical to writing the routes inline — handlers
  * lift over **unchanged** ("graduation"), and body/query schemas validate at the
  * request boundary exactly as in inline mode.
+ *
+ * Pass a pre-configured `app` to give the contract's routes a middleware chain. A route captures the
+ * server's `derive`/`decorate`/assurance chain **at registration**, so anything applied to the
+ * returned server afterwards reaches the contract's routes not at all - the app must already carry it:
+ *
+ * ```ts
+ * const app = implement(contract, handlers, server().use(auth).derive(sessionOf))
+ * ```
+ *
+ * That is also the seam that lets `nifra assure` prove rather than merely classify a contract-first
+ * app: the plugin that installs the enforcement is what declares the evidence
+ * ({@link withRouteAssurance}), and only a plugin installed *before* registration is captured. Handlers
+ * then see the app's `Ctx`, and the returned server keeps any routes the app already had.
  */
-export function implement<const C extends ContractShape, H extends HandlersFor<C>>(
-  contract: C,
-  handlers: H,
-): Server<RegistryFromImpl<C, H>> {
-  const app = new Server()
-  for (const [name, op] of Object.entries(contract)) {
+export function implement<
+  const C extends ContractShape,
+  H extends HandlersFor<C, Ctx>,
+  R extends Registry = EmptyRegistry,
+  Ctx = NonNullable<unknown>,
+>(contract: C, handlers: H, app?: Server<R, Ctx>): Server<R & RegistryFromImpl<C, H, Ctx>, Ctx> {
+  const target = (app ?? new Server()) as Server<R, Ctx>
+  const routes = Object.entries(contract).map(([name, op]) => {
     // body/query are validated at the request boundary; `response` is a type + introspection contract
     // ONLY — never validated at runtime and never read on the request hot path (the lifecycle reads
     // schema.body/query by name; the `bare`/bodyOnly/queryOnly fast-path gates ignore `response`). Built
     // once here at bind time, not per request — it just carries a reference to the op's existing schema.
     // A response-less op still yields `undefined`, byte-identical to before.
     const schema: RouteSchema | undefined =
+      op.params !== undefined ||
       op.body !== undefined ||
       op.query !== undefined ||
       op.response !== undefined ||
       op.capabilities !== undefined ||
       op.idempotency !== undefined ||
-      op.classification !== undefined
+      op.classification !== undefined ||
+      op.assurance !== undefined ||
+      op.family !== undefined
         ? {
+            ...(op.params !== undefined ? { params: op.params } : {}),
             ...(op.body !== undefined ? { body: op.body } : {}),
             ...(op.query !== undefined ? { query: op.query } : {}),
             ...(op.response !== undefined ? { response: op.response } : {}),
             ...(op.capabilities !== undefined ? { capabilities: op.capabilities } : {}),
             ...(op.idempotency !== undefined ? { idempotency: op.idempotency } : {}),
             ...(op.classification !== undefined ? { classification: op.classification } : {}),
+            ...(op.assurance !== undefined ? { assurance: op.assurance } : {}),
+            ...(op.family !== undefined ? { family: op.family } : {}),
           }
         : undefined
-    app.register(
-      op.method,
-      op.path,
+    return {
+      method: op.method,
+      path: op.path,
       schema,
-      handlers[name as keyof H] as (context: never) => unknown,
-    )
-  }
+      handler: handlers[name as keyof H] as (context: never) => unknown,
+    }
+  })
+  target.registerBatch(routes)
   // Runtime registered exactly the contract's routes through the inline path; the
   // registry type is computed from the contract inputs + handler return types.
-  return app as unknown as Server<RegistryFromImpl<C, H>>
+  return target as unknown as Server<R & RegistryFromImpl<C, H, Ctx>, Ctx>
 }

package/src/server/http.ts

@@ -0,0 +1,58 @@
+/**
+ * Dependency-free HTTP helpers shared by the kernel and the opt-in request lanes (idempotency,
+ * effect-ledger). Kept in a leaf module so a lane can reuse them without importing the server, and so
+ * the server can reuse them without pulling a lane's feature code into the base bundle.
+ */
+
+/** A uniform JSON error envelope: `{ ok: false, error }` at the given status. */
+export function jsonError(
+  status: number,
+  error: string,
+  headers?: Record<string, string>,
+): Response {
+  return Response.json(
+    { ok: false, error },
+    headers !== undefined ? { status, headers } : { status },
+  )
+}
+
+export interface UrlParts {
+  readonly pathname: string
+  readonly search: string
+}
+
+// Extract pathname + query WITHOUT a full WHATWG `new URL(req.url)` parse.
+// `req.url` from every supported runtime is an absolute, already-normalized URL, so the pathname is
+// the substring after `scheme://host[:port]` up to `?`/`#`. Query-schema routes also need the search
+// string; parsing both in one scanner avoids the old `pathnameOf()` + `searchOf()` double scan.
+export function urlPartsOf(url: string): UrlParts {
+  const schemeEnd = url.indexOf("://")
+  const start = schemeEnd === -1 ? url.indexOf("/") : url.indexOf("/", schemeEnd + 3)
+  if (start === -1) return { pathname: "/", search: "" }
+
+  let pathEnd = url.length
+  let searchStart = -1
+  let searchEnd = url.length
+  for (let i = start; i < url.length; i++) {
+    const c = url.charCodeAt(i)
+    if (c === 63 /* ? */ && searchStart === -1) {
+      pathEnd = i
+      searchStart = i
+    } else if (c === 35 /* # */) {
+      if (searchStart === -1) pathEnd = i
+      searchEnd = i
+      break
+    }
+  }
+
+  return {
+    pathname: url.slice(start, pathEnd),
+    search: searchStart === -1 ? "" : url.slice(searchStart, searchEnd),
+  }
+}
+
+// Extract the pathname WITHOUT a full WHATWG `new URL(req.url)` parse. Kept as a public-ish helper
+// for tests and callers that only need the path; the request hot path uses `urlPartsOf()` once.
+export function pathnameOf(url: string): string {
+  return urlPartsOf(url).pathname
+}

package/src/server/idempotency-lane.ts

@@ -0,0 +1,287 @@
+/**
+ * The opt-in idempotency request lane. Installed by `.use(idempotency())` and reached only by routes
+ * that declare `schema.idempotency`, so the kernel never statically imports this code: a bare
+ * `server()` tree-shakes the whole dedupe machinery out.
+ *
+ * The kernel resolves a route's declared idempotency at registration (via {@link IdempotencyRuntime.resolve})
+ * and, on the request path, hands a matched idempotent route to {@link IdempotencyRuntime.run}. Everything
+ * server-specific is supplied through {@link IdempotencyHost} so this module depends on no server internals.
+ */
+import { RouteConfigError } from "../errors.ts"
+import {
+  canonicalizeIdempotencyBody,
+  computeIdempotencyFingerprint,
+  DEFAULT_IDEMPOTENCY_HEADER,
+  DEFAULT_IDEMPOTENCY_TTL_MS,
+  IdempotencyResponseTooLargeError,
+  type IdempotencyStore,
+  MemoryIdempotencyStore,
+  responseFromStored,
+  serializeResponse,
+  validIdempotencyKey,
+  validIdempotencyNamespace,
+} from "../idempotency.ts"
+import { readBoundedBytes } from "./body.ts"
+import type { Platform, RouteSchema } from "./context.ts"
+import { jsonError, urlPartsOf } from "./http.ts"
+import { INSTALL_IDEMPOTENCY } from "./install.ts"
+import type { AnyServer, IdentityPlugin } from "./server.ts"
+
+/** Registration-resolved idempotency for a route: the config with its store + defaults pinned. */
+export interface ResolvedIdempotency {
+  readonly store: IdempotencyStore
+  readonly ttlMs: number
+  readonly headerName: string
+  readonly namespace: NonNullable<RouteSchema["idempotency"]>["namespace"]
+  readonly maxResponseBytes: number
+}
+
+/**
+ * What the dedupe lane needs from the server to run a fresh key: the app-wide body cap and a way to
+ * run the buffered request through the route's normal lanes to a concrete `Response`.
+ */
+export interface IdempotencyHost {
+  readonly maxBodyBytes: number
+  runLanes(
+    buffered: Request,
+    platform: Platform | undefined,
+    entry: unknown,
+    params: Record<string, string>,
+    search: string | undefined,
+  ): Promise<Response>
+}
+
+/** The injected idempotency implementation the kernel calls through when the plugin is installed. */
+export interface IdempotencyRuntime {
+  /** Resolve a route's declared idempotency into a pinned store + defaults, or `undefined` when off. */
+  resolve(
+    schema: RouteSchema | undefined,
+    authenticated: boolean,
+    maxBodyBytes: number,
+  ): ResolvedIdempotency | undefined
+  /** The dedupe lane: read the key, fingerprint the request, consult the store, run/replay/reject. */
+  run<T>(
+    config: ResolvedIdempotency,
+    req: Request,
+    platform: Platform | undefined,
+    entry: unknown,
+    params: Record<string, string>,
+    search: string | undefined,
+    wrapResponse: (response: Response) => T,
+    host: IdempotencyHost,
+  ): Promise<T>
+}
+
+/** The install seam a server exposes so the `idempotency()` plugin can hand it a runtime. */
+interface IdempotencyInstallable {
+  [INSTALL_IDEMPOTENCY](runtime: IdempotencyRuntime): void
+}
+
+/**
+ * Enable request idempotency. Routes that declare `schema.idempotency` get the dedupe lane: a repeat
+ * `Idempotency-Key` replays the stored response instead of re-running the handler. Without this plugin,
+ * declaring `schema.idempotency` is a registration error (the safety gate can never be silently
+ * dropped). `store` is the app-wide default backing routes that do not pin their own; omit it for a
+ * shared in-process store (development/tests only - inject a durable store in production).
+ */
+export interface IdempotencyPluginOptions {
+  readonly store?: IdempotencyStore | undefined
+}
+
+export function idempotency(options?: IdempotencyPluginOptions): IdentityPlugin {
+  const runtime = createIdempotencyRuntime(options)
+  const apply = <S extends AnyServer>(app: S): S => {
+    ;(app as unknown as IdempotencyInstallable)[INSTALL_IDEMPOTENCY](runtime)
+    return app
+  }
+  return Object.assign(apply, { pluginName: "nifra:idempotency" }) as IdentityPlugin
+}
+
+const RESPONSE_2XX_LOWER = 200
+const RESPONSE_2XX_UPPER = 300
+
+/**
+ * Build an idempotency runtime. `store` is the app-wide default backing routes that declare
+ * `schema.idempotency` without their own `store`; when omitted, a shared in-process
+ * {@link MemoryIdempotencyStore} is created lazily on first idempotent route.
+ */
+export function createIdempotencyRuntime(options?: IdempotencyPluginOptions): IdempotencyRuntime {
+  const configuredStore = options?.store
+  let lazyStore: IdempotencyStore | undefined
+  const defaultStore = (): IdempotencyStore => {
+    if (configuredStore !== undefined) return configuredStore
+    lazyStore ??= new MemoryIdempotencyStore()
+    return lazyStore
+  }
+
+  return {
+    resolve(schema, authenticated, maxBodyBytes) {
+      const config = schema?.idempotency
+      if (config === undefined) return undefined
+      if (schema?.sse !== undefined) {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          "streaming/SSE responses cannot be used on an idempotency route",
+        )
+      }
+      const store = config.store ?? defaultStore()
+      if (config.scope === "durable" && store.durability !== "durable") {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          'durable idempotency requires a durable store (store.durability must be "durable")',
+        )
+      }
+      const ttlMs = config.ttlMs ?? DEFAULT_IDEMPOTENCY_TTL_MS
+      if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0) {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          "idempotency ttlMs must be a finite positive number",
+        )
+      }
+      const headerName = (config.headerName ?? DEFAULT_IDEMPOTENCY_HEADER).toLowerCase()
+      try {
+        new Headers().set(headerName, "probe")
+      } catch {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          `invalid idempotency header name ${JSON.stringify(headerName)}`,
+        )
+      }
+      const namespace = config.namespace
+      if (namespace === undefined) {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          "idempotency namespace is required; use a principal resolver or an explicit shared scope",
+        )
+      }
+      if (typeof namespace === "string" && !validIdempotencyNamespace(namespace)) {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          `invalid idempotency namespace ${JSON.stringify(namespace)}`,
+        )
+      }
+      if (authenticated && typeof namespace !== "function") {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          "authenticated idempotency routes require a principal namespace resolver",
+        )
+      }
+      const maxResponseBytes = config.maxResponseBytes ?? maxBodyBytes
+      if (!Number.isSafeInteger(maxResponseBytes) || maxResponseBytes < 1) {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          "idempotency maxResponseBytes must be a positive integer",
+        )
+      }
+      return Object.freeze({
+        store,
+        ttlMs,
+        headerName,
+        namespace,
+        maxResponseBytes,
+      })
+    },
+
+    async run(config, req, platform, entry, params, search, wrapResponse, host) {
+      const key = req.headers.get(config.headerName)
+      if (key === null || !validIdempotencyKey(key)) {
+        return wrapResponse(jsonError(400, "idempotency_key_required"))
+      }
+      const namespace =
+        typeof config.namespace === "function"
+          ? await config.namespace(req.clone(), platform)
+          : config.namespace
+      if (!validIdempotencyNamespace(namespace)) {
+        return wrapResponse(jsonError(500, "idempotency_namespace_invalid"))
+      }
+      const read = await readBoundedBytes(req, host.maxBodyBytes)
+      if (!read.ok) {
+        return wrapResponse(
+          jsonError(read.status, read.status === 413 ? "payload_too_large" : "bad_request"),
+        )
+      }
+      const url = urlPartsOf(req.url)
+      const canonicalBody = canonicalizeIdempotencyBody(read.bytes, req.headers.get("content-type"))
+      const fingerprint = await computeIdempotencyFingerprint(
+        req.method,
+        `${url.pathname}${url.search}`,
+        canonicalBody,
+        req.headers.get("content-type") ?? "",
+      )
+
+      const begin = await config.store.begin({ namespace, key, fingerprint, ttlMs: config.ttlMs })
+      if (begin.state === "replay") {
+        return wrapResponse(
+          responseFromStored(begin.response, { maxBytes: config.maxResponseBytes }),
+        )
+      }
+      if (begin.state === "mismatch") return wrapResponse(jsonError(409, "idempotency_key_reused"))
+      if (begin.state === "in-flight") {
+        return wrapResponse(jsonError(409, "idempotency_in_progress", { "Retry-After": "1" }))
+      }
+      if (begin.state === "capacity") {
+        return wrapResponse(jsonError(503, "idempotency_store_capacity", { "Retry-After": "1" }))
+      }
+      const reservation = begin.reservation
+
+      // Fresh key: re-expose the buffered body as a Request so the normal lanes can read + validate it,
+      // then run those lanes to a concrete Response.
+      const bufferedInit: RequestInit = {
+        method: req.method,
+        headers: req.headers,
+        signal: req.signal,
+      }
+      if (read.bytes.byteLength > 0)
+        bufferedInit.body = read.bytes as NonNullable<RequestInit["body"]>
+      const buffered = new Request(req.url, bufferedInit)
+      let response: Response
+      try {
+        response = await host.runLanes(buffered, platform, entry, params, search)
+      } catch (err) {
+        // The lanes never throw (errors resolve to a 500 Response), but stay fail-safe: release the
+        // reservation so a retry isn't wedged, then re-throw.
+        await config.store.abandon({ namespace, key, reservation })
+        throw err
+      }
+      // Cache only successful responses; release the key on any error so the client can retry.
+      if (response.status >= RESPONSE_2XX_LOWER && response.status < RESPONSE_2XX_UPPER) {
+        let storedResponse: Awaited<ReturnType<typeof serializeResponse>>
+        try {
+          storedResponse = await serializeResponse(response, { maxBytes: config.maxResponseBytes })
+        } catch (error) {
+          if (!(error instanceof IdempotencyResponseTooLargeError)) throw error
+          // The effect may already have happened, so never abandon and permit a duplicate execution.
+          // Commit a small terminal response under the winning key and return that same response now.
+          response = jsonError(507, "idempotency_response_too_large")
+          try {
+            storedResponse = await serializeResponse(response, {
+              maxBytes: config.maxResponseBytes,
+            })
+          } catch (terminalError) {
+            if (!(terminalError instanceof IdempotencyResponseTooLargeError)) throw terminalError
+            // Even an intentionally tiny bound must remain truthful. An empty 507 preserves terminal
+            // status + replay safety without silently storing more bytes than the route permits.
+            response = new Response(null, { status: 507 })
+            storedResponse = await serializeResponse(response, {
+              maxBytes: config.maxResponseBytes,
+            })
+          }
+        }
+        const completed = await config.store.complete({
+          namespace,
+          key,
+          reservation,
+          response: storedResponse,
+        })
+        if (!completed) {
+          return wrapResponse(
+            jsonError(503, "idempotency_reservation_lost", { "Retry-After": "1" }),
+          )
+        }
+      } else {
+        await config.store.abandon({ namespace, key, reservation })
+      }
+      return wrapResponse(response)
+    },
+  }
+}

package/src/server/install.ts

@@ -0,0 +1,28 @@
+/**
+ * Symbol-keyed install seams the opt-in feature plugins (`idempotency()`, `effectLedger()`) use to
+ * hand their runtime to a server. Kept in a dependency-free leaf, and keyed by symbol, so:
+ *   - the kernel can implement the seam without importing a feature's code (importing a bare symbol
+ *     never drags the lane's implementation into the base bundle), and
+ *   - the seam stays off the server's public typed surface (symbol-keyed methods are not part of it).
+ * Both sides reference the SAME registered symbol, so no module has to import the other.
+ */
+
+/** @internal Install the idempotency runtime on a server (called by the `idempotency()` plugin). */
+export const INSTALL_IDEMPOTENCY: unique symbol = Symbol.for("@nifrajs/core/install-idempotency")
+
+/** @internal Install the effect-ledger runtime on a server (called by the `effectLedger()` plugin). */
+export const INSTALL_EFFECT_LEDGER: unique symbol = Symbol.for(
+  "@nifrajs/core/install-effect-ledger",
+)
+
+/** @internal Install the MCP runtime on a server (called by the `mcp()` plugin). */
+export const INSTALL_MCP: unique symbol = Symbol.for("@nifrajs/core/install-mcp")
+
+/** @internal Install the SSE streaming runtime on a server (called by the `sse()` plugin). */
+export const INSTALL_SSE: unique symbol = Symbol.for("@nifrajs/core/install-sse")
+
+/** @internal Install the Node-direct renderer on a server (called by the `nodeDirect()` plugin). */
+export const INSTALL_NODE_DIRECT: unique symbol = Symbol.for("@nifrajs/core/install-node-direct")
+
+/** @internal Install the WebSocket runtime on a server (called by the `websocket()` plugin). */
+export const INSTALL_WS: unique symbol = Symbol.for("@nifrajs/core/install-ws")

package/src/server/ledger-lane.ts

@@ -0,0 +1,125 @@
+/**
+ * The opt-in per-request effect ledger. Installed by `.use(effectLedger())` and reached only by routes
+ * that declare `schema.capabilities`, so the kernel never statically imports this code: a bare
+ * `server()` tree-shakes the ledger machinery out.
+ *
+ * The kernel resolves a capability-declaring route's ledger wiring at registration (via
+ * {@link EffectLedgerRuntime.resolve}) and, on the request path, creates + attaches a ledger before the
+ * handler and settles it after (via {@link EffectLedgerRuntime.create}/`attach`/`settle`). Nothing here
+ * depends on server internals; the sink-error log is supplied per settle.
+ */
+import {
+  attachEffectLedger,
+  createRequestLedger,
+  DEFAULT_MAX_ENTRIES,
+  type EffectLedgerOptions,
+  type RequestLedger,
+} from "../ledger.ts"
+import { INSTALL_EFFECT_LEDGER } from "./install.ts"
+import type { AnyServer, IdentityPlugin } from "./server.ts"
+
+/** Registration-resolved effect-ledger wiring for one capability-declaring route. */
+export interface ResolvedEffectLedger {
+  readonly sink: EffectLedgerOptions["sink"]
+  readonly maxEntries: number
+  readonly chain: boolean
+  /** The registered route pattern - what the sealed ledger names (never the concrete URL). */
+  readonly method: string
+  readonly path: string
+  /** The route's declared capability tokens, surfaced on the sealed ledger. */
+  readonly declared: readonly string[]
+}
+
+/** The injected effect-ledger implementation the kernel calls through when the plugin is installed. */
+export interface EffectLedgerRuntime {
+  /** Resolve a capability-declaring route into its ledger wiring, or `undefined` when it declares none. */
+  resolve(
+    capabilities: readonly string[],
+    method: string,
+    path: string,
+  ): ResolvedEffectLedger | undefined
+  /** Create the per-request ledger for a ledgered route. */
+  create(resolved: ResolvedEffectLedger): RequestLedger
+  /** Attach a ledger to the request context so `useCapability` can append to it. */
+  attach(context: object, ledger: RequestLedger): void
+  /** Seal the ledger and deliver it to the sink (empty ledgers are not delivered). */
+  settle<T>(
+    ledger: RequestLedger,
+    resolved: ResolvedEffectLedger,
+    value: T,
+    onSinkError: (fields: { method: string; path: string; name: string }) => void,
+  ): Promise<T>
+}
+
+/**
+ * Build an effect-ledger runtime from the app-wide options. `sink` receives the sealed, token-only
+ * ledger when a capability-declaring route settles with recorded entries; `maxEntries` bounds a single
+ * request's ledger; `chain` opts into the per-entry hash chain.
+ */
+export function createEffectLedgerRuntime(options: EffectLedgerOptions): EffectLedgerRuntime {
+  if (typeof options.sink !== "function") {
+    throw new TypeError("effectLedger.sink must be a function")
+  }
+  const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES
+  if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
+    throw new RangeError("effectLedger.maxEntries must be a positive safe integer")
+  }
+  const chain = options.chain ?? false
+  const sink = options.sink
+
+  return {
+    resolve(capabilities, method, path) {
+      if (capabilities.length === 0) return undefined
+      return Object.freeze({ sink, maxEntries, chain, method, path, declared: capabilities })
+    },
+    create(resolved) {
+      return createRequestLedger({
+        method: resolved.method,
+        path: resolved.path,
+        declared: resolved.declared,
+        maxEntries: resolved.maxEntries,
+        chain: resolved.chain,
+      })
+    },
+    attach(context, ledger) {
+      attachEffectLedger(context, ledger)
+    },
+    async settle(ledger, resolved, value, onSinkError) {
+      const sealed = await ledger.seal()
+      if (sealed.entries.length === 0) return value
+      try {
+        await resolved.sink(sealed)
+      } catch (err) {
+        // Token-only: the route pattern and the failure name - never entry payloads (there are none)
+        // and never the request. The ledger is observational, so a sink outage never fails the effect.
+        onSinkError({
+          method: resolved.method,
+          path: resolved.path,
+          name: err instanceof Error ? err.name : "Error",
+        })
+      }
+      return value
+    },
+  }
+}
+
+/** The install seam a server exposes so the `effectLedger()` plugin can hand it a runtime. */
+interface EffectLedgerInstallable {
+  [INSTALL_EFFECT_LEDGER](runtime: EffectLedgerRuntime): void
+}
+
+/**
+ * Enable the per-request effect ledger. Each route that declares `schema.capabilities` gets a bounded,
+ * token-only ledger; `useCapability(c, id, …)` appends one entry per effect, and the sink receives the
+ * sealed ledger when the response settles (only when it recorded entries). Token-only by construction -
+ * capability ids, phases, counters, digests; never payloads, values, or the concrete URL (the route
+ * pattern is recorded). Without this plugin, capability-declaring routes simply carry no ledger.
+ */
+export function effectLedger(options: EffectLedgerOptions): IdentityPlugin {
+  const runtime = createEffectLedgerRuntime(options)
+  const apply = <S extends AnyServer>(app: S): S => {
+    ;(app as unknown as EffectLedgerInstallable)[INSTALL_EFFECT_LEDGER](runtime)
+    return app
+  }
+  return Object.assign(apply, { pluginName: "nifra:effect-ledger" }) as IdentityPlugin
+}