@nifrajs/core 2.0.0 → 2.1.0

package/src/effect-lifecycle.ts

@@ -0,0 +1,120 @@
+import { validCapabilityId } from "./internal/capability-runtime.ts"
+import { type EffectCost, type EffectMetadata, normalizeEffectMetadata } from "./ledger.ts"
+
+/** A bounded, payload-free stage in an effect's lifecycle. */
+export type EffectLifecycleStage = "admission" | "execution" | "compensation" | "reconciliation"
+
+export type EffectLifecyclePhase = "started" | "succeeded" | "failed" | "ambiguous"
+
+/** Trace-parent tokens copied structurally from an installed tracing plugin. */
+export interface EffectTraceParent {
+  readonly traceId: string
+  readonly spanId: string
+  readonly sampled: boolean
+}
+
+/**
+ * Token-only lifecycle evidence. There is deliberately no payload, argument, result, error message,
+ * request, or context field, so observation adapters cannot accidentally export business data.
+ */
+export interface EffectLifecycleEvent extends EffectMetadata {
+  readonly effectId: string
+  readonly capability: string
+  readonly stage: EffectLifecycleStage
+  readonly phase: EffectLifecyclePhase
+  readonly at: number
+  readonly durationMs?: number
+  readonly attempt?: number
+  readonly errorCode?: string
+  readonly trace?: EffectTraceParent
+}
+
+/** Observation is fail-open: a broken sink must never change effect behavior. */
+export type EffectLifecycleObserver = (event: EffectLifecycleEvent) => void
+
+const ERROR_CODE = /^[a-z][a-z0-9_.-]{0,63}$/
+
+export function effectTraceParentOf(context: object): EffectTraceParent | undefined {
+  const trace = (
+    context as {
+      readonly trace?: {
+        readonly traceId?: unknown
+        readonly spanId?: unknown
+        readonly sampled?: unknown
+      }
+    }
+  ).trace
+  if (
+    trace === undefined ||
+    typeof trace.traceId !== "string" ||
+    !/^[0-9a-f]{32}$/.test(trace.traceId) ||
+    typeof trace.spanId !== "string" ||
+    !/^[0-9a-f]{16}$/.test(trace.spanId) ||
+    typeof trace.sampled !== "boolean"
+  ) {
+    return undefined
+  }
+  return Object.freeze({ traceId: trace.traceId, spanId: trace.spanId, sampled: trace.sampled })
+}
+
+export interface EmitEffectLifecycleInput extends EffectMetadata {
+  readonly effectId: string
+  readonly capability: string
+  readonly stage: EffectLifecycleStage
+  readonly phase: EffectLifecyclePhase
+  readonly at?: number
+  readonly durationMs?: number
+  readonly attempt?: number
+  readonly errorCode?: string
+  readonly trace?: EffectTraceParent
+}
+
+/** @internal Validate, freeze, and fan out one token-only event. */
+export function emitEffectLifecycle(
+  observers: readonly EffectLifecycleObserver[],
+  input: EmitEffectLifecycleInput,
+): void {
+  if (observers.length === 0) return
+  if (!validCapabilityId(input.capability) || !/^[!-~]{1,64}$/u.test(input.effectId)) return
+  let metadata: EffectMetadata
+  try {
+    metadata = normalizeEffectMetadata(input)
+  } catch {
+    return
+  }
+  const at = input.at ?? Date.now()
+  if (!Number.isFinite(at) || at < 0) return
+  if (
+    input.durationMs !== undefined &&
+    (!Number.isFinite(input.durationMs) || input.durationMs < 0)
+  ) {
+    return
+  }
+  if (input.attempt !== undefined && (!Number.isSafeInteger(input.attempt) || input.attempt < 1)) {
+    return
+  }
+  if (input.errorCode !== undefined && !ERROR_CODE.test(input.errorCode)) return
+  const event: EffectLifecycleEvent = Object.freeze({
+    effectId: input.effectId,
+    capability: input.capability,
+    stage: input.stage,
+    phase: input.phase,
+    at,
+    ...(input.durationMs === undefined ? {} : { durationMs: input.durationMs }),
+    ...(input.attempt === undefined ? {} : { attempt: input.attempt }),
+    ...(input.errorCode === undefined ? {} : { errorCode: input.errorCode }),
+    ...(metadata.target === undefined ? {} : { target: metadata.target }),
+    ...(metadata.cost === undefined
+      ? {}
+      : { cost: Object.freeze({ ...metadata.cost }) as EffectCost }),
+    ...(metadata.digest === undefined ? {} : { digest: metadata.digest }),
+    ...(input.trace === undefined ? {} : { trace: input.trace }),
+  })
+  for (const observer of observers) {
+    try {
+      observer(event)
+    } catch {
+      // Observation is deliberately fail-open.
+    }
+  }
+}

package/src/effect-scope.ts

@@ -0,0 +1,267 @@
+/**
+ * One cross-runtime boundary for owned external effects. It centralizes correlation, lifecycle
+ * evidence, cancellation, durable transition ordering, and token-only observation without relying
+ * on Node-only async-local state.
+ */
+
+import {
+  type EffectLifecycleObserver,
+  type EffectLifecycleStage,
+  type EffectTraceParent,
+  emitEffectLifecycle,
+} from "./effect-lifecycle.ts"
+import { validCapabilityId } from "./internal/capability-runtime.ts"
+import { type EffectMetadata, normalizeEffectMetadata } from "./ledger.ts"
+
+const ERROR_CODE = /^[a-z][a-z0-9_.-]{0,63}$/
+
+export interface EffectScopeEvidence {
+  readonly began: boolean
+  readonly committed: boolean
+  readonly ambiguous: boolean
+}
+
+export interface OwnedEffectContext extends EffectMetadata {
+  readonly effectId: string
+  readonly capability: string
+  readonly stage: Exclude<EffectLifecycleStage, "admission" | "reconciliation">
+  readonly signal: AbortSignal
+  readonly attempt?: number
+}
+
+export interface OwnedEffectTransitions<T> {
+  intent?(context: OwnedEffectContext): void | PromiseLike<void>
+  executing?(context: OwnedEffectContext): void | PromiseLike<void>
+  committed?(context: OwnedEffectContext, result: T): void | PromiseLike<void>
+  failed?(
+    context: OwnedEffectContext,
+    input: { readonly began: boolean; readonly errorCode: string; readonly error: unknown },
+  ): void | PromiseLike<void>
+}
+
+export interface OwnedEffectRunOptions<T> extends EffectMetadata {
+  readonly effectId?: string
+  readonly capability: string
+  readonly stage?: Exclude<EffectLifecycleStage, "admission" | "reconciliation">
+  readonly signal?: AbortSignal
+  readonly attempt?: number
+  readonly trace?: EffectTraceParent
+  /** Per-run observers, combined with the scope's observers. */
+  readonly observers?: readonly EffectLifecycleObserver[]
+  /** Optional admission boundary executed before the effect is marked as begun. */
+  readonly admit?: (context: OwnedEffectContext) => void | PromiseLike<void>
+  readonly transitions?: OwnedEffectTransitions<T>
+  readonly errorCode?: string | ((error: unknown, began: boolean) => string)
+  /** Classify a caught execution failure when the caller can prove it is terminal. */
+  readonly failurePhase?: (error: unknown, began: boolean) => "failed" | "ambiguous"
+}
+
+export interface EffectScopeOptions {
+  readonly observers?: readonly EffectLifecycleObserver[]
+  readonly signal?: AbortSignal
+  readonly effectId?: () => string
+}
+
+export interface EffectEvidenceScope {
+  evidence(): EffectScopeEvidence
+  /** Legacy/manual effects cannot prove a terminal outcome and therefore become ambiguous. */
+  markBegan(): void
+  /** Pair a prior manual `markBegan()` with a proven commit. */
+  markCommitted(): void
+  /** Preserve uncertainty when a caller loses the terminal outcome. */
+  markAmbiguous(): void
+  /** Settle one begun effect as a proven terminal failure without claiming it committed. */
+  markFailed(): void
+  /**
+   * Declare that the enclosing request may release its idempotency reservation if it returns a
+   * server error before any owned effect begins.
+   */
+  markSafeToRetry(): void
+  /** True only while the retry declaration remains backed by evidence that no effect began. */
+  safeToRetry(): boolean
+}
+
+export interface EffectScope extends EffectEvidenceScope {
+  run<T>(
+    options: OwnedEffectRunOptions<T>,
+    execute: (context: OwnedEffectContext) => T | PromiseLike<T>,
+  ): Promise<T>
+}
+
+let neverSignal: AbortSignal | undefined
+function signalOrNever(signal?: AbortSignal): AbortSignal {
+  neverSignal ??= new AbortController().signal
+  return signal ?? neverSignal
+}
+
+function assertEffectId(value: string): void {
+  if (!/^[!-~]{1,64}$/u.test(value))
+    throw new TypeError("effect id must be a bounded printable token")
+}
+
+function codeFor(
+  configured: OwnedEffectRunOptions<unknown>["errorCode"],
+  error: unknown,
+  began: boolean,
+): string {
+  const code =
+    typeof configured === "function"
+      ? configured(error, began)
+      : (configured ?? (began ? "execution_failed" : "admission_failed"))
+  if (!ERROR_CODE.test(code)) throw new TypeError("effect errorCode is invalid")
+  return code
+}
+
+/** Lightweight aggregate evidence shared by request idempotency and full owned-effect runners. */
+export function createEffectEvidenceScope(): EffectEvidenceScope {
+  const aggregate = { began: false, committed: false }
+  let uncertain = 0
+  let retryDeclared = false
+  return Object.freeze({
+    evidence() {
+      return Object.freeze({ ...aggregate, ambiguous: uncertain > 0 })
+    },
+    markBegan() {
+      aggregate.began = true
+      retryDeclared = false
+      uncertain++
+    },
+    markCommitted() {
+      aggregate.began = true
+      aggregate.committed = true
+      if (uncertain > 0) uncertain--
+    },
+    markAmbiguous() {
+      aggregate.began = true
+      retryDeclared = false
+      if (uncertain === 0) uncertain = 1
+    },
+    markFailed() {
+      aggregate.began = true
+      retryDeclared = false
+      if (uncertain > 0) uncertain--
+    },
+    markSafeToRetry() {
+      if (aggregate.began) {
+        throw new Error("cannot mark an idempotent request safe to retry after an effect began")
+      }
+      retryDeclared = true
+    },
+    safeToRetry() {
+      return retryDeclared && !aggregate.began
+    },
+  })
+}
+
+export function createEffectScope(
+  options: EffectScopeOptions = {},
+  evidenceScope: EffectEvidenceScope = createEffectEvidenceScope(),
+): EffectScope {
+  const observers = Object.freeze([...(options.observers ?? [])])
+  const idFor = options.effectId ?? crypto.randomUUID.bind(crypto)
+
+  const scope: EffectScope = {
+    async run<T>(
+      input: OwnedEffectRunOptions<T>,
+      execute: (context: OwnedEffectContext) => T | PromiseLike<T>,
+    ) {
+      if (typeof execute !== "function")
+        throw new TypeError("owned effect executor must be a function")
+      if (!validCapabilityId(input.capability))
+        throw new TypeError("owned effect capability is invalid")
+      const effectId = input.effectId ?? idFor()
+      assertEffectId(effectId)
+      const metadata = normalizeEffectMetadata(input)
+      const signal = input.signal ?? options.signal ?? signalOrNever()
+      const stage = input.stage ?? "execution"
+      if (
+        input.attempt !== undefined &&
+        (!Number.isSafeInteger(input.attempt) || input.attempt < 1)
+      )
+        throw new RangeError("owned effect attempt must be a positive safe integer")
+      const context: OwnedEffectContext = Object.freeze({
+        effectId,
+        capability: input.capability,
+        stage,
+        signal,
+        ...metadata,
+        ...(input.attempt === undefined ? {} : { attempt: input.attempt }),
+      })
+      const runObservers =
+        input.observers === undefined
+          ? observers
+          : Object.freeze([...observers, ...input.observers])
+      let began = false
+      const startedAt = performance.now()
+      try {
+        if (signal.aborted) throw signal.reason
+        await input.transitions?.intent?.(context)
+        if (input.admit !== undefined) {
+          emitEffectLifecycle(runObservers, {
+            ...context,
+            stage: "admission",
+            phase: "started",
+            ...(input.trace === undefined ? {} : { trace: input.trace }),
+          })
+          await input.admit(context)
+          emitEffectLifecycle(runObservers, {
+            ...context,
+            stage: "admission",
+            phase: "succeeded",
+            durationMs: Math.max(0, performance.now() - startedAt),
+            ...(input.trace === undefined ? {} : { trace: input.trace }),
+          })
+        }
+        if (signal.aborted) throw signal.reason
+        await input.transitions?.executing?.(context)
+        began = true
+        evidenceScope.markBegan()
+        const executionStartedAt = performance.now()
+        emitEffectLifecycle(runObservers, {
+          ...context,
+          phase: "started",
+          ...(input.trace === undefined ? {} : { trace: input.trace }),
+        })
+        const result = await execute(context)
+        await input.transitions?.committed?.(context, result)
+        evidenceScope.markCommitted()
+        emitEffectLifecycle(runObservers, {
+          ...context,
+          phase: "succeeded",
+          durationMs: Math.max(0, performance.now() - executionStartedAt),
+          ...(input.trace === undefined ? {} : { trace: input.trace }),
+        })
+        return result
+      } catch (error) {
+        const errorCode = codeFor(input.errorCode, error, began)
+        const failurePhase = input.failurePhase?.(error, began) ?? (began ? "ambiguous" : "failed")
+        if (failurePhase !== "failed" && failurePhase !== "ambiguous") {
+          throw new TypeError("owned effect failurePhase returned an invalid phase")
+        }
+        try {
+          await input.transitions?.failed?.(context, { began, errorCode, error })
+        } catch {
+          // Preserve the owned effect's cause. Reconciliation sees the unfinished durable state.
+        }
+        if (began && failurePhase === "failed") evidenceScope.markFailed()
+        emitEffectLifecycle(runObservers, {
+          ...context,
+          stage: began ? stage : input.admit === undefined ? stage : "admission",
+          phase: began ? failurePhase : "failed",
+          durationMs: Math.max(0, performance.now() - startedAt),
+          errorCode,
+          ...(input.trace === undefined ? {} : { trace: input.trace }),
+        })
+        throw error
+      }
+    },
+    evidence: () => evidenceScope.evidence(),
+    markBegan: () => evidenceScope.markBegan(),
+    markCommitted: () => evidenceScope.markCommitted(),
+    markAmbiguous: () => evidenceScope.markAmbiguous(),
+    markFailed: () => evidenceScope.markFailed(),
+    markSafeToRetry: () => evidenceScope.markSafeToRetry(),
+    safeToRetry: () => evidenceScope.safeToRetry(),
+  }
+  return Object.freeze(scope)
+}

package/src/idempotency-plugin.ts

@@ -5,3 +5,13 @@
  * dedupe lane. Import primitives and stores from `@nifrajs/core/idempotency`.
  */
 export { type IdempotencyPluginOptions, idempotency } from "./server/idempotency-lane.ts"
+
+import { markRequestSafeToRetry } from "./internal/effect-execution.ts"
+
+/**
+ * Opt a concrete 5xx response into releasing its idempotency reservation, but only while the
+ * request-local effect scope still proves that no owned effect began.
+ */
+export function markIdempotencySafeToRetry(context: object): void {
+  markRequestSafeToRetry(context)
+}

package/src/index.ts

@@ -10,7 +10,7 @@
  * read its own package.json at runtime. `scripts/version.ts` rewrites it on every release bump and
  * `check:publish` asserts it equals `@nifrajs/core`'s package version.
  */
-export const VERSION = "2.0.0" as const
+export const VERSION = "2.1.0" as const
 
 export type Version = typeof VERSION
 

package/src/internal/capability-runtime.ts

@@ -1,3 +1,6 @@
+import type { EffectLifecycleObserver } from "../effect-lifecycle.ts"
+import type { EffectCost } from "../ledger.ts"
+
 export const CAPABILITY_GUARD = Symbol("nifra.capability.guard")
 const CAPABILITY_ID = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/
 
@@ -11,11 +14,83 @@ export interface CapabilityUseEvent {
   readonly path: string
 }
 
+/** Token-only metadata supplied to an asynchronous capability admission interceptor. */
+export interface CapabilityInterceptorEvent extends CapabilityUseEvent {
+  readonly effectId: string
+  readonly signal: AbortSignal
+  readonly target?: string
+  readonly cost?: EffectCost
+  readonly digest?: string
+}
+
+/** Server-owned identity binding for durable admission. Values are opaque tokens, never payloads. */
+export interface CapabilityExecutionIdentity {
+  readonly tenantId: string
+  readonly principalId: string
+}
+
+export interface CapabilityApprovalInput extends CapabilityExecutionIdentity {
+  /** Signed token returned by the approval coordinator after the first suspended attempt. */
+  readonly resumeToken?: string
+}
+
+export interface CapabilityApprovalGate {
+  authorize(input: {
+    readonly effectId: string
+    readonly capability: string
+    readonly target?: string
+    readonly digest?: string
+    readonly identity: CapabilityExecutionIdentity
+    readonly resumeToken?: string
+    readonly signal: AbortSignal
+  }): void | PromiseLike<void>
+}
+
+/** Durable, token-only journal seam. Implementations must fail closed on transition failure. */
+export interface CapabilityExecutionJournal {
+  intent(input: {
+    readonly effectId: string
+    readonly capability: string
+    readonly target?: string
+    readonly digest?: string
+    readonly identity?: CapabilityExecutionIdentity
+  }): void | PromiseLike<void>
+  executing(effectId: string): void | PromiseLike<void>
+  committed(effectId: string): void | PromiseLike<void>
+  failed(
+    effectId: string,
+    input: { readonly began: boolean; readonly errorCode: string },
+  ): void | PromiseLike<void>
+}
+
+/** Continue to the next admission policy. The owned effect runs only after the full chain admits. */
+export type CapabilityInterceptorNext = () => Promise<void>
+
+export type CapabilityInterceptor = (
+  event: CapabilityInterceptorEvent,
+  next: CapabilityInterceptorNext,
+) => void | PromiseLike<void>
+
+export interface AroundCapabilityOptions {
+  /** Maximum admission time in milliseconds. Default 30_000. */
+  readonly timeoutMs?: number
+}
+
+export interface RegisteredCapabilityInterceptor {
+  readonly interceptor: CapabilityInterceptor
+  readonly timeoutMs: number
+}
+
+export const DEFAULT_CAPABILITY_INTERCEPTOR_TIMEOUT_MS = 30_000
+
 export interface CapabilityGuard {
   readonly allowed: readonly string[]
   readonly method: string
   readonly path: string
   readonly onUse?: (event: CapabilityUseEvent) => void
+  readonly trackEffect?: (context: object, committed: boolean) => void
+  readonly interceptors: readonly RegisteredCapabilityInterceptor[]
+  readonly observers: readonly EffectLifecycleObserver[]
 }
 
 export function normalizeRouteCapabilities(
@@ -44,6 +119,17 @@ export function createCapabilityGuard(
   method: string,
   path: string,
   onUse: ((event: CapabilityUseEvent) => void) | undefined,
+  trackEffect: ((context: object, committed: boolean) => void) | undefined,
+  interceptors: readonly RegisteredCapabilityInterceptor[],
+  observers: readonly EffectLifecycleObserver[],
 ): CapabilityGuard {
-  return Object.freeze({ allowed, method, path, ...(onUse !== undefined ? { onUse } : {}) })
+  return Object.freeze({
+    allowed,
+    method,
+    path,
+    ...(onUse !== undefined ? { onUse } : {}),
+    ...(trackEffect !== undefined ? { trackEffect } : {}),
+    interceptors,
+    observers,
+  })
 }

package/src/internal/effect-execution.ts

@@ -0,0 +1,70 @@
+/** Request-local owned-effect scope used by idempotency and every capability boundary. */
+
+import {
+  createEffectEvidenceScope,
+  type EffectEvidenceScope,
+  type EffectScopeEvidence,
+} from "../effect-scope.ts"
+
+export type RequestEffectEvidence = EffectScopeEvidence
+
+const scopeByRequest = new WeakMap<Request, EffectEvidenceScope>()
+
+export function beginRequestEffectTracking(request: Request): EffectEvidenceScope {
+  const scope = createEffectEvidenceScope()
+  scopeByRequest.set(request, scope)
+  return scope
+}
+
+export function requestEffectScope(request: Request): EffectEvidenceScope | undefined {
+  return scopeByRequest.get(request)
+}
+
+export function requestEffectEvidence(request: Request): RequestEffectEvidence {
+  return (
+    scopeByRequest.get(request)?.evidence() ??
+    Object.freeze({ began: false, committed: false, ambiguous: false })
+  )
+}
+
+export function effectScopeForContext(context: object): EffectEvidenceScope | undefined {
+  const request = (context as { readonly req?: unknown }).req
+  return request instanceof Request ? scopeByRequest.get(request) : undefined
+}
+
+export function markEffect(context: object, committed: boolean): void {
+  const scope = effectScopeForContext(context)
+  if (committed) scope?.markCommitted()
+  else scope?.markBegan()
+}
+
+/** A legacy beacon cannot prove what happens after the call, so it is immediately ambiguous. */
+export function markBeaconEffectBegan(context: object): void {
+  effectScopeForContext(context)?.markBegan()
+}
+
+export function markEffectExecuting(context: object): void {
+  effectScopeForContext(context)?.markBegan()
+}
+
+export function markEffectCommitted(context: object): void {
+  effectScopeForContext(context)?.markCommitted()
+}
+
+export function markEffectAmbiguous(context: object): void {
+  effectScopeForContext(context)?.markAmbiguous()
+}
+
+export function markRequestSafeToRetry(context: object): void {
+  const scope = effectScopeForContext(context)
+  if (scope === undefined) {
+    throw new Error(
+      "markIdempotencySafeToRetry() requires an active route with idempotency enabled",
+    )
+  }
+  scope.markSafeToRetry()
+}
+
+export function requestIsSafeToRetry(request: Request): boolean {
+  return scopeByRequest.get(request)?.safeToRetry() ?? false
+}

package/src/internal/safe-equal.ts

@@ -0,0 +1,27 @@
+/**
+ * Constant-time string comparison for credential-shaped values - lease tokens, token hashes, and
+ * binding digests.
+ *
+ * `a !== b` returns as soon as it finds a differing character, so how long it takes reveals how much
+ * of a guess was correct. That is only exploitable when an attacker can submit guesses and measure,
+ * which is not the case on every path here - but these values are credentials, the comparison is on
+ * the verification path, and doing it correctly costs nothing. Doing it inconsistently is what makes
+ * the one place that matters easy to miss.
+ *
+ * Length is compared first, so a length difference is still observable. Every value compared through
+ * this helper is fixed-width by construction (a UUID, a SHA-256 hex/base64url digest), so length
+ * carries no secret. Content comparison always visits every character.
+ *
+ * Synchronous on purpose: the callers are store transitions and lease checks that are themselves
+ * synchronous. A hash-then-compare variant (which would also hide length) is available as
+ * `timingSafeEqualString` in `@nifrajs/middleware`, but it is async and would force those paths async.
+ */
+export function safeEqual(a: string | undefined, b: string | undefined): boolean {
+  // Accepts `undefined` so optional binding fields keep their exact `!==` semantics at call sites:
+  // absent equals absent, and absent never equals present. Neither branch is secret-bearing.
+  if (a === undefined || b === undefined) return a === b
+  if (a.length !== b.length) return false
+  let diff = 0
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i)
+  return diff === 0
+}