@nifrajs/core 1.13.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/core",
-  "version": "1.13.0",
+  "version": "2.1.0",
   "description": "Bun-native, contract-first HTTP framework — the router, server, and route descriptor.",
   "keywords": [
     "bun",
@@ -27,11 +27,36 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./server": {
+      "bun": "./src/server.ts",
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
     "./ws": {
       "bun": "./src/ws.ts",
       "types": "./dist/ws.d.ts",
       "default": "./dist/ws.js"
     },
+    "./wire": {
+      "bun": "./src/wire.ts",
+      "types": "./dist/wire.d.ts",
+      "default": "./dist/wire.js"
+    },
+    "./transport-codec": {
+      "bun": "./src/transport-codec.ts",
+      "types": "./dist/transport-codec.d.ts",
+      "default": "./dist/transport-codec.js"
+    },
+    "./transport-codec-rich": {
+      "bun": "./src/transport-codec-rich.ts",
+      "types": "./dist/transport-codec-rich.d.ts",
+      "default": "./dist/transport-codec-rich.js"
+    },
+    "./transport-plugin": {
+      "bun": "./src/transport-plugin.ts",
+      "types": "./dist/transport-plugin.d.ts",
+      "default": "./dist/transport-plugin.js"
+    },
     "./reflection": {
       "bun": "./src/reflection.ts",
       "types": "./dist/reflection.d.ts",
@@ -62,16 +87,46 @@
       "types": "./dist/idempotency.d.ts",
       "default": "./dist/idempotency.js"
     },
-    "./invariants": {
-      "bun": "./src/invariants.ts",
-      "types": "./dist/invariants.d.ts",
-      "default": "./dist/invariants.js"
+    "./idempotency-plugin": {
+      "bun": "./src/idempotency-plugin.ts",
+      "types": "./dist/idempotency-plugin.d.ts",
+      "default": "./dist/idempotency-plugin.js"
     },
     "./ledger": {
       "bun": "./src/ledger.ts",
       "types": "./dist/ledger.d.ts",
       "default": "./dist/ledger.js"
     },
+    "./effect-ledger": {
+      "bun": "./src/effect-ledger.ts",
+      "types": "./dist/effect-ledger.d.ts",
+      "default": "./dist/effect-ledger.js"
+    },
+    "./effect-lifecycle": {
+      "bun": "./src/effect-lifecycle.ts",
+      "types": "./dist/effect-lifecycle.d.ts",
+      "default": "./dist/effect-lifecycle.js"
+    },
+    "./effect-scope": {
+      "bun": "./src/effect-scope.ts",
+      "types": "./dist/effect-scope.d.ts",
+      "default": "./dist/effect-scope.js"
+    },
+    "./durable-execution": {
+      "bun": "./src/durable-execution.ts",
+      "types": "./dist/durable-execution.d.ts",
+      "default": "./dist/durable-execution.js"
+    },
+    "./durable-adapters": {
+      "bun": "./src/durable-adapters.ts",
+      "types": "./dist/durable-adapters.d.ts",
+      "default": "./dist/durable-adapters.js"
+    },
+    "./reconciliation-worker": {
+      "bun": "./src/reconciliation-worker.ts",
+      "types": "./dist/reconciliation-worker.d.ts",
+      "default": "./dist/reconciliation-worker.js"
+    },
     "./manifest": {
       "bun": "./src/manifest.ts",
       "types": "./dist/manifest.d.ts",
@@ -82,6 +137,16 @@
       "types": "./dist/mount.d.ts",
       "default": "./dist/mount.js"
     },
+    "./mcp": {
+      "bun": "./src/mcp.ts",
+      "types": "./dist/mcp.d.ts",
+      "default": "./dist/mcp.js"
+    },
+    "./node-direct": {
+      "bun": "./src/node-direct.ts",
+      "types": "./dist/node-direct.d.ts",
+      "default": "./dist/node-direct.js"
+    },
     "./pattern": {
       "bun": "./src/router/pattern.ts",
       "types": "./dist/router/pattern.d.ts",
@@ -91,6 +156,51 @@
       "bun": "./src/causality.ts",
       "types": "./dist/causality.d.ts",
       "default": "./dist/causality.js"
+    },
+    "./classification": {
+      "bun": "./src/classification.ts",
+      "types": "./dist/classification.d.ts",
+      "default": "./dist/classification.js"
+    },
+    "./contract": {
+      "bun": "./src/server/contract.ts",
+      "types": "./dist/server/contract.d.ts",
+      "default": "./dist/server/contract.js"
+    },
+    "./cookies": {
+      "bun": "./src/server/cookies.ts",
+      "types": "./dist/server/cookies.d.ts",
+      "default": "./dist/server/cookies.js"
+    },
+    "./logger": {
+      "bun": "./src/server/logger.ts",
+      "types": "./dist/server/logger.d.ts",
+      "default": "./dist/server/logger.js"
+    },
+    "./router": {
+      "bun": "./src/router/router.ts",
+      "types": "./dist/router/router.d.ts",
+      "default": "./dist/router/router.js"
+    },
+    "./schema": {
+      "bun": "./src/schema/standard.ts",
+      "types": "./dist/schema/standard.d.ts",
+      "default": "./dist/schema/standard.js"
+    },
+    "./seo": {
+      "bun": "./src/seo.ts",
+      "types": "./dist/seo.d.ts",
+      "default": "./dist/seo.js"
+    },
+    "./sse": {
+      "bun": "./src/server/sse.ts",
+      "types": "./dist/server/sse.d.ts",
+      "default": "./dist/server/sse.js"
+    },
+    "./webhook": {
+      "bun": "./src/server/webhook.ts",
+      "types": "./dist/server/webhook.d.ts",
+      "default": "./dist/server/webhook.js"
     }
   },
   "files": [
@@ -99,7 +209,13 @@
   ],
   "sideEffects": [
     "./src/ws.ts",
-    "./dist/ws.js"
+    "./dist/ws.js",
+    "./src/server/sse.ts",
+    "./dist/server/sse.js",
+    "./src/node-direct.ts",
+    "./dist/node-direct.js",
+    "./src/mcp-runtime.ts",
+    "./dist/mcp-runtime.js"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"

package/src/assurance.ts

@@ -20,7 +20,6 @@ import {
   validMethod,
   withRouteAssurance,
 } from "./internal/route-assurance.ts"
-import type { InvariantExecutor } from "./invariants.ts"
 import type { NifraManifestSigner } from "./manifest.ts"
 import { type ReflectedRoute, reflectRoutes } from "./reflection.ts"
 import type { Method } from "./router/router.ts"
@@ -28,6 +27,9 @@ import type { Method } from "./router/router.ts"
 export type { AssuranceDeclaration, AssuranceEvidence, AssuranceScope }
 export { withRouteAssurance }
 
+/** Isolated request executor used by adversarial contract verification. */
+export type InvariantExecutor = (request: Request) => Response | Promise<Response>
+
 /** Canonical evidence ids emitted by Nifra's official middleware modules. */
 export const NIFRA_ASSURANCE = NIFRA_ASSURANCE_IDS
 
@@ -57,6 +59,14 @@ export interface AssurancePolicy {
   readonly unmatched?: "error" | "ignore"
   /** Default false: reject an empty reflected source so a wrong import cannot pass CI silently. */
   readonly allowEmpty?: boolean
+  /**
+   * Default false. When true, a route matched by a **pure-classification** rule (no `require`, no `forbid`)
+   * that carries NO enforcement evidence is reported (`classified-no-evidence`). This surfaces the gap the
+   * feedback flagged: a classification-only policy silently degrades "proof" to a "label". Opt-in, because
+   * a genuinely public route legitimately carries no evidence; enable it once your guards emit evidence
+   * (inline `schema.assurance` or a `withRouteAssurance` middleware) to keep classification honest.
+   */
+  readonly flagClassifiedWithoutEvidence?: boolean
 }
 
 export type AssuranceFindingCode =
@@ -64,6 +74,7 @@ export type AssuranceFindingCode =
   | "unclassified-route"
   | "missing-evidence"
   | "forbidden-evidence"
+  | "classified-no-evidence"
 
 export interface AssuranceFinding {
   readonly code: AssuranceFindingCode
@@ -140,6 +151,12 @@ export function defineAssurancePolicy(policy: AssurancePolicy): AssurancePolicy
   if (policy.allowEmpty !== undefined && typeof policy.allowEmpty !== "boolean") {
     throw new Error(`route assurance: allowEmpty must be boolean`)
   }
+  if (
+    policy.flagClassifiedWithoutEvidence !== undefined &&
+    typeof policy.flagClassifiedWithoutEvidence !== "boolean"
+  ) {
+    throw new Error(`route assurance: flagClassifiedWithoutEvidence must be boolean`)
+  }
   const names = new Set<string>()
   const rules = policy.rules.map((rule): AssuranceRule => {
     if (typeof rule.name !== "string" || !nonEmpty(rule.name)) {
@@ -187,6 +204,7 @@ export function defineAssurancePolicy(policy: AssurancePolicy): AssurancePolicy
     rules: Object.freeze(rules),
     unmatched: policy.unmatched ?? "error",
     allowEmpty: policy.allowEmpty ?? false,
+    flagClassifiedWithoutEvidence: policy.flagClassifiedWithoutEvidence ?? false,
   })
 }
 
@@ -292,6 +310,23 @@ export function evaluateRouteAssurance(
         message: `${route.method} ${route.path} (${rule.name}) carries forbidden ${id}`,
       })
     }
+    // Opt-in visibility: a pure-classification rule (no require + no forbid) matching a route with zero
+    // evidence is a "label without proof". Surface it so the gap isn't silently green. A rule that expects
+    // or forbids evidence already speaks for itself via the loops above, so it's excluded here.
+    if (
+      policy.flagClassifiedWithoutEvidence === true &&
+      evidence.length === 0 &&
+      (rule.require ?? []).length === 0 &&
+      (rule.forbid ?? []).length === 0
+    ) {
+      findings.push({
+        code: "classified-no-evidence",
+        method: route.method,
+        path: route.path,
+        rule: rule.name,
+        message: `${route.method} ${route.path} (${rule.name}) is classified but carries no enforcement evidence`,
+      })
+    }
     routes.push({
       method: route.method,
       path: route.path,

package/src/capabilities.ts

@@ -4,17 +4,45 @@
  */
 
 import type { DataClassification } from "./classification.ts"
+import { type EffectLifecycleObserver, effectTraceParentOf } from "./effect-lifecycle.ts"
+import { createEffectScope } from "./effect-scope.ts"
 import {
+  type AroundCapabilityOptions,
   CAPABILITY_GUARD,
+  type CapabilityApprovalGate,
+  type CapabilityApprovalInput,
+  type CapabilityExecutionIdentity,
+  type CapabilityExecutionJournal,
   type CapabilityGuard,
+  type CapabilityInterceptor,
+  type CapabilityInterceptorEvent,
+  type CapabilityInterceptorNext,
   type CapabilityUseEvent,
+  type RegisteredCapabilityInterceptor,
   validCapabilityId,
 } from "./internal/capability-runtime.ts"
+import { effectScopeForContext } from "./internal/effect-execution.ts"
 import { NIFRA_ASSURANCE_IDS } from "./internal/route-assurance.ts"
-import { type EffectCost, type EffectPhase, effectLedgerOf } from "./ledger.ts"
+import {
+  type EffectCost,
+  type EffectPhase,
+  effectLedgerOf,
+  normalizeEffectMetadata,
+} from "./ledger.ts"
 import { reflectRoutes } from "./reflection.ts"
 
-export type { CapabilityUseEvent }
+export type {
+  AroundCapabilityOptions,
+  CapabilityApprovalGate,
+  CapabilityApprovalInput,
+  CapabilityExecutionIdentity,
+  CapabilityExecutionJournal,
+  CapabilityInterceptor,
+  CapabilityInterceptorEvent,
+  CapabilityInterceptorNext,
+  CapabilityUseEvent,
+  EffectLifecycleObserver,
+}
 
 export type CapabilityZone = "domain" | "operational"
 export type CapabilityAccess = "read" | "write"
@@ -409,6 +437,162 @@ export interface CapabilityOutcomeOptions extends UseCapabilityOptions {
   readonly error?: { readonly code: string }
 }
 
+/** Durable controls consumed by `executeCapability`; none of these fields enter the effect ledger. */
+export interface CapabilityExecutionOptions extends UseCapabilityOptions {
+  readonly approval?: CapabilityApprovalInput & { readonly gate: CapabilityApprovalGate }
+  readonly journal?: CapabilityExecutionJournal
+}
+
+/** Context passed to the owned effect callback. Use the signal for cancellation-aware I/O. */
+export interface CapabilityExecutionContext {
+  readonly effectId: string
+  readonly signal: AbortSignal
+}
+
+export type CapabilityExecutor<T> = (execution: CapabilityExecutionContext) => T | PromiseLike<T>
+
+/** A capability admission policy returned without calling `next()`. */
+export class CapabilityDeniedError extends Error {
+  constructor(
+    public readonly capability: string,
+    public readonly effectId: string,
+  ) {
+    super(`capability assurance: ${capability} was denied by an async interceptor`)
+    this.name = "CapabilityDeniedError"
+  }
+}
+
+/** A capability admission policy exceeded its configured bound. */
+export class CapabilityInterceptorTimeoutError extends Error {
+  constructor(
+    public readonly capability: string,
+    public readonly effectId: string,
+    public readonly timeoutMs: number,
+  ) {
+    super(`capability assurance: ${capability} admission timed out after ${timeoutMs}ms`)
+    this.name = "CapabilityInterceptorTimeoutError"
+  }
+}
+
+/** The request was cancelled while capability admission was pending. */
+export class CapabilityAdmissionAbortedError extends Error {
+  constructor(
+    public readonly capability: string,
+    public readonly effectId: string,
+  ) {
+    super(`capability assurance: ${capability} admission was aborted`)
+    this.name = "CapabilityAdmissionAbortedError"
+  }
+}
+
+/** An interceptor called its one-shot `next()` continuation more than once. */
+export class CapabilityInterceptorProtocolError extends Error {
+  constructor(
+    public readonly capability: string,
+    public readonly effectId: string,
+  ) {
+    super(`capability assurance: ${capability} interceptor called next() more than once`)
+    this.name = "CapabilityInterceptorProtocolError"
+  }
+}
+
+/** The effect may have committed, but its durable terminal transition could not be recorded. */
+export class CapabilityJournalTransitionError extends Error {
+  constructor(
+    public readonly capability: string,
+    public readonly effectId: string,
+    public readonly transition: "committed",
+  ) {
+    super(`capability assurance: ${capability} durable ${transition} transition failed`)
+    this.name = "CapabilityJournalTransitionError"
+  }
+}
+
+let unboundedCapabilitySignal: AbortSignal | undefined
+
+function signalFor(context: object): AbortSignal {
+  const signal = (context as { readonly signal?: AbortSignal }).signal
+  if (signal !== undefined) return signal
+  unboundedCapabilitySignal ??= new AbortController().signal
+  return unboundedCapabilitySignal
+}
+
+function admissionErrorCode(error: unknown): string {
+  if (error instanceof CapabilityDeniedError) return "admission_denied"
+  if (error instanceof CapabilityInterceptorTimeoutError) return "admission_timeout"
+  if (error instanceof CapabilityAdmissionAbortedError) return "admission_aborted"
+  if (error instanceof CapabilityInterceptorProtocolError) return "admission_protocol"
+  return "admission_failed"
+}
+
+async function withInterceptorBound(
+  registration: RegisteredCapabilityInterceptor,
+  parentSignal: AbortSignal,
+  capability: string,
+  effectId: string,
+  run: (signal: AbortSignal) => Promise<void>,
+): Promise<void> {
+  if (parentSignal.aborted) throw new CapabilityAdmissionAbortedError(capability, effectId)
+  const controller = new AbortController()
+  let timeout: ReturnType<typeof setTimeout> | undefined
+  let rejectGate: ((error: Error) => void) | undefined
+  const gate = new Promise<never>((_resolve, reject) => {
+    rejectGate = reject
+  })
+  const abort = (): void => {
+    const error = new CapabilityAdmissionAbortedError(capability, effectId)
+    controller.abort(error)
+    rejectGate?.(error)
+  }
+  parentSignal.addEventListener("abort", abort, { once: true })
+  timeout = setTimeout(() => {
+    const error = new CapabilityInterceptorTimeoutError(
+      capability,
+      effectId,
+      registration.timeoutMs,
+    )
+    controller.abort(error)
+    rejectGate?.(error)
+  }, registration.timeoutMs)
+  try {
+    await Promise.race([run(controller.signal), gate])
+  } finally {
+    clearTimeout(timeout)
+    parentSignal.removeEventListener("abort", abort)
+  }
+}
+
+async function runCapabilityInterceptors(
+  registrations: readonly RegisteredCapabilityInterceptor[],
+  baseEvent: Omit<CapabilityInterceptorEvent, "signal">,
+  parentSignal: AbortSignal,
+  index = 0,
+): Promise<void> {
+  const registration = registrations[index]
+  if (registration === undefined) return
+  let nextPromise: Promise<void> | undefined
+  await withInterceptorBound(
+    registration,
+    parentSignal,
+    baseEvent.capability,
+    baseEvent.effectId,
+    async (signal) => {
+      const event = Object.freeze({ ...baseEvent, signal })
+      await registration.interceptor(event, () => {
+        if (nextPromise !== undefined) {
+          throw new CapabilityInterceptorProtocolError(baseEvent.capability, baseEvent.effectId)
+        }
+        nextPromise = runCapabilityInterceptors(registrations, baseEvent, signal, index + 1)
+        return nextPromise
+      })
+    },
+  )
+  if (nextPromise === undefined) {
+    throw new CapabilityDeniedError(baseEvent.capability, baseEvent.effectId)
+  }
+  await nextPromise
+}
+
 function guardFor(context: object, capability: string): CapabilityGuard {
   if (!validCapabilityId(capability)) {
     throw new Error(
@@ -444,6 +628,7 @@ export function useCapability(
   // Validate/append the intent before private admission hooks debit budgets. Overflow or malformed
   // evidence therefore cannot consume quota and then fail the request.
   ledger?.append({ capability, ...options, phase: "intent" })
+  guard.trackEffect?.(context, false)
   guard.onUse?.({ capability, method: guard.method, path: guard.path })
 }
 
@@ -453,10 +638,126 @@ export function recordCapabilityOutcome(
   capability: string,
   options: CapabilityOutcomeOptions,
 ): void {
-  guardFor(context, capability)
+  const guard = guardFor(context, capability)
   const ledger = effectLedgerOf(context)
-  if (ledger === undefined) return
-  ledger.append({ capability, ...options })
+  ledger?.append({ capability, ...options })
+  if (options.phase === "committed" || options.phase === "compensated") {
+    guard.trackEffect?.(context, true)
+  } else {
+    guard.trackEffect?.(context, false)
+  }
+}
+
+/**
+ * Execute one owned effect behind a fail-closed capability boundary. The boundary assigns a stable
+ * effect id, records intent before execution, and records exactly one terminal outcome automatically.
+ * The callback result and errors never enter the token-only ledger.
+ */
+export async function executeCapability<T>(
+  context: object,
+  capability: string,
+  options: CapabilityExecutionOptions,
+  executor: CapabilityExecutor<T>,
+): Promise<T> {
+  if (typeof executor !== "function") {
+    throw new TypeError("capability assurance: executeCapability executor must be a function")
+  }
+  const guard = guardFor(context, capability)
+  const ledger = effectLedgerOf(context)
+  const effectId = crypto.randomUUID()
+  const metadata = normalizeEffectMetadata(options)
+  const trace = effectTraceParentOf(context)
+  const identity = options.approval
+  const requestEvidence = effectScopeForContext(context)
+  const scope = createEffectScope({}, requestEvidence)
+  const result = await scope.run(
+    {
+      effectId,
+      capability,
+      ...metadata,
+      signal: signalFor(context),
+      observers: guard.observers,
+      ...(trace === undefined ? {} : { trace }),
+      errorCode: (error, began) => (began ? "execution_failed" : admissionErrorCode(error)),
+      async admit(execution) {
+        if (identity !== undefined) {
+          await identity.gate.authorize({
+            effectId: execution.effectId,
+            capability,
+            ...(metadata.target === undefined ? {} : { target: metadata.target }),
+            ...(metadata.digest === undefined ? {} : { digest: metadata.digest }),
+            identity: { tenantId: identity.tenantId, principalId: identity.principalId },
+            ...(identity.resumeToken === undefined ? {} : { resumeToken: identity.resumeToken }),
+            signal: execution.signal,
+          })
+        }
+        guard.onUse?.({ capability, method: guard.method, path: guard.path })
+        if (guard.interceptors.length > 0) {
+          await runCapabilityInterceptors(
+            guard.interceptors,
+            Object.freeze({
+              capability,
+              method: guard.method,
+              path: guard.path,
+              effectId: execution.effectId,
+              ...metadata,
+            }),
+            execution.signal,
+          )
+        }
+      },
+      transitions: {
+        async intent(execution) {
+          ledger?.append({ capability, effectId: execution.effectId, ...metadata, phase: "intent" })
+          await options.journal?.intent({
+            effectId: execution.effectId,
+            capability,
+            ...(metadata.target === undefined ? {} : { target: metadata.target }),
+            ...(metadata.digest === undefined ? {} : { digest: metadata.digest }),
+            ...(identity === undefined
+              ? {}
+              : { identity: { tenantId: identity.tenantId, principalId: identity.principalId } }),
+          })
+        },
+        async executing(execution) {
+          await options.journal?.executing(execution.effectId)
+        },
+        async committed(execution) {
+          try {
+            await options.journal?.committed(execution.effectId)
+          } catch {
+            throw new CapabilityJournalTransitionError(capability, execution.effectId, "committed")
+          }
+        },
+        async failed(execution, failure) {
+          try {
+            await options.journal?.failed(execution.effectId, {
+              began: failure.began,
+              errorCode: failure.errorCode,
+            })
+          } finally {
+            try {
+              ledger?.append({
+                capability,
+                effectId: execution.effectId,
+                ...metadata,
+                phase: "failed",
+                error: { code: failure.errorCode },
+              })
+            } catch {
+              // Preserve the original effect failure when terminal evidence overflows.
+            }
+          }
+        },
+      },
+    },
+    (execution) =>
+      executor(Object.freeze({ effectId: execution.effectId, signal: execution.signal })),
+  )
+  // Durable commit and success telemetry are already final. A ledger overflow here must not rewrite
+  // the effect to failed/unknown or erase the request scope's proven committed evidence.
+  ledger?.append({ capability, effectId, ...metadata, phase: "committed" })
+  return result
 }
 
 /**