@nifrajs/core 2.0.0 → 2.2.0

package/src/router/pattern.ts

@@ -8,6 +8,13 @@ export type RoutePatternSegment =
   | { readonly kind: "static"; readonly value: string }
   | { readonly kind: "param"; readonly name: string }
   | { readonly kind: "wildcard"; readonly name: string }
+  /** A segment that is part literal, part parameter: `:key.txt`, `feed.:format`, `v:major.:minor`. */
+  | { readonly kind: "mixed"; readonly parts: readonly MixedPart[] }
+
+/** One piece of a {@link RoutePatternSegment} of kind `mixed`, in left-to-right order. */
+export type MixedPart =
+  | { readonly t: "lit"; readonly v: string }
+  | { readonly t: "param"; readonly name: string }
 
 /**
  * Compiled route grammar shared by runtime routers, browser navigation, mocks, and adapters.
@@ -45,7 +52,9 @@ function regexOf(compiled: CompiledRoutePattern): RegExp {
         ? escapeRegex(segment.value)
         : segment.kind === "param"
           ? "([^/]+)"
-          : "(.+)",
+          : segment.kind === "mixed"
+            ? mixedSegmentSource(segment.parts)
+            : "(.+)",
     )
     regex = new RegExp(parts.length === 0 ? "^/$" : `^/${parts.join("/")}$`)
     REGEX_CACHE.set(compiled, regex)
@@ -57,10 +66,93 @@ function validParamName(name: string): boolean {
   return PARAM_NAME.test(name) && !RESERVED_PARAM_NAMES.has(name)
 }
 
+/**
+ * Explain WHY a parameter name was rejected, in the terms the author was thinking in.
+ *
+ * The grammar is per-segment: a segment is wholly static or wholly a parameter, so everything after
+ * the colon is the name. `/v/:id.json` therefore asks for a parameter literally named `id.json`,
+ * which is not what anyone means by it — but the bare "invalid parameter" that produces reads as a
+ * typo rather than as a rule, leaving the author to guess whether the dot, the length, or the casing
+ * was the problem. Naming the actual limitation and showing the two ways out is the difference
+ * between a five-second fix and a trip to the source.
+ */
+function paramNameHint(name: string): string {
+  if (RESERVED_PARAM_NAMES.has(name)) return ` — "${name}" is reserved (prototype key)`
+  if (name.length === 0) return ` — ":" needs a name after it`
+  // No "a segment is wholly static or wholly a parameter" case here any more: mixed segments made
+  // that message obsolete. `:id.json` was the shape it explained, and `:id.json` now compiles.
+  return ` — a name must match ${PARAM_NAME.source}`
+}
+
 function escapeRegex(value: string): string {
   return value.replace(/[.*+?^()|[\]\\{}$]/g, "\\$&")
 }
 
+/**
+ * Split a segment containing `:` into literal and parameter parts.
+ *
+ * The param name is the LONGEST run matching {@link PARAM_NAME}'s body after each `:`; everything
+ * else in the segment is literal. So `:key.txt` is `[param key][lit ".txt"]`. Choosing a greedy scan
+ * on the existing sigil rather than a new `{key}.txt` syntax is a safety argument, not a taste one:
+ * every segment this newly accepts currently THROWS `INVALID_PARAM_NAME`, so no pattern that compiles
+ * today can change meaning.
+ *
+ * Returns `undefined` when the segment holds no parameter at all, so a literal colon
+ * (`/v1/things:batchGet` - legal in a URL path) stays a plain static segment.
+ */
+function splitMixed(value: string): MixedPart[] | undefined {
+  const parts: MixedPart[] = []
+  let literal = ""
+  let sawParam = false
+  for (let i = 0; i < value.length; i++) {
+    if (value[i] !== ":") {
+      literal += value[i]
+      continue
+    }
+    const rest = value.slice(i + 1)
+    const name = /^[A-Za-z_][A-Za-z0-9_]*/.exec(rest)?.[0]
+    // A `:` not followed by a valid name start is literal text, not a malformed parameter.
+    if (name === undefined) {
+      literal += ":"
+      continue
+    }
+    const paramEnd = i + 1 + name.length
+    const previous = i > 0 ? value[i - 1] : undefined
+    const precededByBoundary = previous === undefined || !/[A-Za-z0-9_]/.test(previous)
+    // Preserve established RPC-style literals such as `things:batchGet`. A colon embedded after an
+    // identifier and running to the end is literal; mixed params remain unambiguous at segment start,
+    // after punctuation (`post-:id`), or when followed by a literal suffix (`v:major.json`).
+    if (!precededByBoundary && paramEnd === value.length) {
+      literal += `:${name}`
+      i += name.length
+      continue
+    }
+    if (literal !== "") {
+      parts.push({ t: "lit", v: literal })
+      literal = ""
+    }
+    parts.push({ t: "param", name })
+    sawParam = true
+    i += name.length
+  }
+  if (!sawParam) return undefined
+  if (literal !== "") parts.push({ t: "lit", v: literal })
+  return parts
+}
+
+/** The regex source matching one segment's worth of a mixed pattern, with a capture per parameter. */
+export function mixedSegmentSource(parts: readonly MixedPart[]): string {
+  let source = ""
+  for (const part of parts) {
+    // LAZY (`+?`), not greedy. A greedy capture swallows the trailing literal, so `/:key.txt` against
+    // `/abc.txt` would capture `abc.txt` and then fail to match `\.txt`. With `^…$` anchoring, the
+    // lazy form still yields `abc.txt` for `/abc.txt.txt` - the anchor forces the LAST `.txt` to be
+    // the literal. `+?` and not `*?`: an empty capture must not match (see the empty-segment rule).
+    source += part.t === "lit" ? escapeRegex(part.v) : "([^/]+?)"
+  }
+  return source
+}
+
 /** Parse and validate Nifra's strict route grammar once. Trailing slashes remain significant. */
 export function compileRoutePattern(pattern: string): CompiledRoutePattern {
   if (pattern.length === 0 || pattern.charCodeAt(0) !== 47 /* / */) {
@@ -71,14 +163,20 @@ export function compileRoutePattern(pattern: string): CompiledRoutePattern {
   const paramNames: string[] = []
   for (let i = 0; i < raw.length; i++) {
     const value = raw[i]!
-    if (value.charCodeAt(0) === 58 /* : */) {
-      const name = value.slice(1)
-      if (!validParamName(name)) {
+    // A leading `:` whose name run spans the WHOLE segment is a plain parameter - the untouched fast
+    // path. When it does not (`:key.txt`), the segment is mixed and is handled below; but a leading
+    // `:` that yields no usable name at all (`:9lives`, `:`) was clearly meant as a parameter, so it
+    // still fails here rather than being silently reinterpreted as literal text.
+    if (value.charCodeAt(0) === 58 /* : */ && !validParamName(value.slice(1))) {
+      if (splitMixed(value) === undefined) {
+        const name = value.slice(1)
         throw new RouteConfigError(
           "INVALID_PARAM_NAME",
-          `invalid parameter ":${name}" in "${pattern}"`,
+          `invalid parameter ":${name}" in "${pattern}"${paramNameHint(name)}`,
         )
       }
+    } else if (value.charCodeAt(0) === 58 /* : */) {
+      const name = value.slice(1)
       if (paramNames.includes(name)) {
         throw new RouteConfigError(
           "DUPLICATE_PARAM",
@@ -113,6 +211,32 @@ export function compileRoutePattern(pattern: string): CompiledRoutePattern {
       segments.push(Object.freeze({ kind: "wildcard", name }))
       continue
     }
+    // A segment holding a `:` anywhere other than the front is part literal, part parameter. Checked
+    // last so the wholly-static and wholly-param fast paths above are untouched.
+    const mixed = value.includes(":") ? splitMixed(value) : undefined
+    if (mixed !== undefined) {
+      for (const part of mixed) {
+        if (part.t !== "param") continue
+        if (!validParamName(part.name)) {
+          throw new RouteConfigError(
+            "INVALID_PARAM_NAME",
+            `invalid parameter ":${part.name}" in "${pattern}"${paramNameHint(part.name)}`,
+          )
+        }
+        // Duplicates must be rejected WITHIN a segment (`/:a.:a`) as well as across segments,
+        // or two captures would race for one params key.
+        if (paramNames.includes(part.name)) {
+          throw new RouteConfigError(
+            "DUPLICATE_PARAM",
+            `duplicate parameter ":${part.name}" in "${pattern}"`,
+          )
+        }
+        // Pushed left-to-right so `paramNames` stays aligned with regex capture order.
+        paramNames.push(part.name)
+      }
+      segments.push(Object.freeze({ kind: "mixed", parts: Object.freeze(mixed) }))
+      continue
+    }
     segments.push(Object.freeze({ kind: "static", value }))
   }
   const compiled = Object.freeze({
@@ -124,7 +248,50 @@ export function compileRoutePattern(pattern: string): CompiledRoutePattern {
   return compiled
 }
 
-/** Core precedence: static > param > wildcard at the first differing segment, independent of order. */
+/** Weight for {@link compareRoutePatternSpecificity}. A mixed segment constrains more than a bare
+ * param (it pins literal text) and less than a fully static one, so it sits between them. */
+const SPECIFICITY: Readonly<Record<RoutePatternSegment["kind"], number>> = {
+  static: 4,
+  mixed: 3,
+  param: 2,
+  wildcard: 1,
+}
+
+/**
+ * Total ordering for mixed segment shapes, shared by the trie and regex-based routers.
+ *
+ * Code-unit comparison, never `localeCompare`: this exists so the server and the browser agree on which
+ * of two equally-weighted patterns wins, and `localeCompare` answers by the RUNTIME's locale - a server
+ * and a visitor in different locales would order the same pair differently, which is the divergence
+ * being prevented.
+ */
+export function compareMixedPartsSpecificity(
+  left: readonly MixedPart[],
+  right: readonly MixedPart[],
+): number {
+  const literalWeight = (parts: readonly MixedPart[]): number =>
+    parts.reduce((sum, part) => (part.t === "lit" ? sum + part.v.length : sum), 0)
+  const order = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0)
+
+  const weightDifference = literalWeight(right) - literalWeight(left)
+  if (weightDifference !== 0) return weightDifference
+
+  const length = Math.max(left.length, right.length)
+  for (let i = 0; i < length; i++) {
+    const a = left[i]
+    const b = right[i]
+    if (a === undefined || b === undefined) return b === undefined ? -1 : 1
+    if (a.t !== b.t) return a.t === "lit" ? -1 : 1
+    if (a.t === "lit" && b.t === "lit" && a.v !== b.v) {
+      return a.v.length === b.v.length ? order(a.v, b.v) : b.v.length - a.v.length
+    }
+  }
+
+  return order(mixedSegmentSource(left), mixedSegmentSource(right))
+}
+
+/** Core precedence: static > mixed > param > wildcard at the first differing segment, independent of
+ * registration order. */
 export function compareRoutePatternSpecificity(
   left: CompiledRoutePattern,
   right: CompiledRoutePattern,
@@ -134,9 +301,13 @@ export function compareRoutePatternSpecificity(
     const a = left.segments[i]
     const b = right.segments[i]
     if (a === undefined || b === undefined) return b === undefined ? -1 : 1
-    const aWeight = a.kind === "static" ? 3 : a.kind === "param" ? 2 : 1
-    const bWeight = b.kind === "static" ? 3 : b.kind === "param" ? 2 : 1
+    const aWeight = SPECIFICITY[a.kind]
+    const bWeight = SPECIFICITY[b.kind]
     if (aWeight !== bWeight) return bWeight - aWeight
+    if (a.kind === "mixed" && b.kind === "mixed") {
+      const mixed = compareMixedPartsSpecificity(a.parts, b.parts)
+      if (mixed !== 0) return mixed
+    }
   }
   return 0
 }

package/src/router/router.ts

@@ -1,5 +1,11 @@
 import { RouteConfigError } from "../errors.ts"
-import { type CompiledRoutePattern, compileRoutePattern } from "./pattern.ts"
+import {
+  type CompiledRoutePattern,
+  compareMixedPartsSpecificity,
+  compileRoutePattern,
+  type MixedPart,
+  mixedSegmentSource,
+} from "./pattern.ts"
 
 /** HTTP methods the router accepts. */
 export const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"] as const
@@ -68,16 +74,43 @@ interface RouteNode<T> {
   readonly staticChildren: Map<string, RouteNode<T>>
   /** Single `:param` child, if any. */
   paramChild: RouteNode<T> | undefined
+  /**
+   * Part-literal-part-param children (`:key.txt`), ordered by specificity.
+   *
+   * Unlike `paramChild` there can legitimately be SEVERAL at one level - `/:id.txt` and `/:id.json`
+   * are different shapes, not a conflict - so this is a list rather than a slot, and it must be tried
+   * in specificity order rather than registration order.
+   *
+   * Left `undefined` unless a mixed route is registered, so an app that never uses one pays nothing:
+   * no allocation, and one `undefined` check on the match path.
+   */
+  mixedChildren: MixedChild<T>[] | undefined
   /** Catch-all `*` child, if any — always terminal. */
   wildcardChild: RouteNode<T> | undefined
   /** Set once this node terminates one or more routes. */
   terminal: Terminal<T> | undefined
 }
 
+interface MixedChild<T> {
+  /** Anchored matcher for ONE segment, with a capture group per parameter. */
+  readonly regex: RegExp
+  /**
+   * How many values this segment pushes. A mixed segment pushes N, not one, so a failed branch must
+   * pop exactly N to keep `paramValues` aligned with `paramNames`.
+   */
+  readonly arity: number
+  /** Parsed shape used by the same total specificity comparator as the browser router. */
+  readonly parts: readonly MixedPart[]
+  readonly node: RouteNode<T>
+  /** The pattern source, so re-registering the same shape reuses its node. */
+  readonly source: string
+}
+
 function createNode<T>(): RouteNode<T> {
   return {
     staticChildren: new Map(),
     paramChild: undefined,
+    mixedChildren: undefined,
     wildcardChild: undefined,
     terminal: undefined,
   }
@@ -123,6 +156,28 @@ function matchNode<T>(
     }
   }
 
+  // Mixed sits between static and param: it pins literal text, so it is more specific than a bare
+  // `:param`, and less than an exact segment. Guarded on `undefined` so a mixed-free route table
+  // never enters this branch.
+  const mixedChildren = node.mixedChildren
+  if (mixedChildren !== undefined && seg.length > 0) {
+    for (const child of mixedChildren) {
+      const matched = child.regex.exec(seg)
+      if (matched === null) continue
+      // Push left-to-right, matching the order `paramNames` was built in.
+      for (let i = 1; i <= child.arity; i++) paramValues.push(matched[i] as string)
+      if (isLast) {
+        if (child.node.terminal !== undefined) return child.node.terminal
+      } else {
+        const found = matchNode(child.node, path, end + 1, len, paramValues)
+        if (found !== undefined) return found
+      }
+      // Backtrack: a mixed segment pushed `arity` values, not one, so unwind exactly that many or
+      // every later param reads a value belonging to an abandoned branch.
+      for (let i = 0; i < child.arity; i++) paramValues.pop()
+    }
+  }
+
   const paramChild = node.paramChild
   // An empty segment (`/users//posts`) never matches a `:param` — matching would hand the handler
   // `id: ""` and downstream code a `WHERE id = ''` class of bug. Peers (Hono, Elysia, Next) 404
@@ -250,6 +305,25 @@ export class Router<T> {
       } else if (segment.kind === "wildcard") {
         node.wildcardChild ??= createNode<T>()
         node = node.wildcardChild
+      } else if (segment.kind === "mixed") {
+        const source = mixedSegmentSource(segment.parts)
+        node.mixedChildren ??= []
+        let child = node.mixedChildren.find((entry) => entry.source === source)
+        if (child === undefined) {
+          child = {
+            regex: new RegExp(`^${source}$`),
+            arity: segment.parts.reduce((n, part) => (part.t === "param" ? n + 1 : n), 0),
+            parts: segment.parts,
+            node: createNode<T>(),
+            source,
+          }
+          node.mixedChildren.push(child)
+          // Most literal text first. Registration order must not decide which of `/:id.txt` and
+          // `/:id.json` wins, and re-sorting on insert (a boot-time cost) keeps the match path a
+          // straight scan.
+          node.mixedChildren.sort((a, b) => compareMixedPartsSpecificity(a.parts, b.parts))
+        }
+        node = child.node
       } else {
         let child = node.staticChildren.get(segment.value)
         if (child === undefined) {

package/src/server/idempotency-lane.ts

@@ -21,6 +21,12 @@ import {
   validIdempotencyKey,
   validIdempotencyNamespace,
 } from "../idempotency.ts"
+import {
+  beginRequestEffectTracking,
+  markEffect,
+  requestEffectEvidence,
+  requestIsSafeToRetry,
+} from "../internal/effect-execution.ts"
 import { readBoundedBytes } from "./body.ts"
 import type { Platform, RouteSchema } from "./context.ts"
 import { jsonError, urlPartsOf } from "./http.ts"
@@ -53,6 +59,7 @@ export interface IdempotencyHost {
 
 /** The injected idempotency implementation the kernel calls through when the plugin is installed. */
 export interface IdempotencyRuntime {
+  readonly trackEffect: (context: object, committed: boolean) => void
   /** Resolve a route's declared idempotency into a pinned store + defaults, or `undefined` when off. */
   resolve(
     schema: RouteSchema | undefined,
@@ -97,9 +104,6 @@ export function idempotency(options?: IdempotencyPluginOptions): IdentityPlugin
   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
@@ -115,6 +119,9 @@ export function createIdempotencyRuntime(options?: IdempotencyPluginOptions): Id
   }
 
   return {
+    trackEffect(context, committed) {
+      markEffect(context, committed)
+    },
     resolve(schema, authenticated, maxBodyBytes) {
       const config = schema?.idempotency
       if (config === undefined) return undefined
@@ -234,52 +241,79 @@ export function createIdempotencyRuntime(options?: IdempotencyPluginOptions): Id
       if (read.bytes.byteLength > 0)
         bufferedInit.body = read.bytes as NonNullable<RequestInit["body"]>
       const buffered = new Request(req.url, bufferedInit)
+      beginRequestEffectTracking(buffered)
       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 evidence = requestEffectEvidence(buffered)
+        if (!evidence.began) {
+          // The request-local boundary proves no owned effect started, so this is the one safe case
+          // where releasing the key cannot duplicate an effect.
+          await config.store.abandon({ namespace, key, reservation })
+          throw err
         }
+        // A committed or ambiguous effect must never be repeated. Persist a payload-free terminal
+        // response even though the normal handler lifecycle escaped without producing one.
+        response = new Response(null, { status: 500 })
         const completed = await config.store.complete({
           namespace,
           key,
           reservation,
-          response: storedResponse,
+          response: await serializeResponse(response, { maxBytes: config.maxResponseBytes }),
         })
         if (!completed) {
           return wrapResponse(
             jsonError(503, "idempotency_reservation_lost", { "Retry-After": "1" }),
           )
         }
-      } else {
-        await config.store.abandon({ namespace, key, reservation })
+        return wrapResponse(response)
+      }
+      if (
+        response.status >= 500 &&
+        requestIsSafeToRetry(buffered) &&
+        !requestEffectEvidence(buffered).began
+      ) {
+        const abandoned = await config.store.abandon({ namespace, key, reservation })
+        if (!abandoned) {
+          return wrapResponse(
+            jsonError(503, "idempotency_reservation_lost", { "Retry-After": "1" }),
+          )
+        }
+        return wrapResponse(response)
+      }
+      // Once the handler ran, every concrete response is terminal for this key. A non-2xx may follow
+      // an already-committed external effect; abandoning it would let a retry duplicate that effect.
+      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" }))
       }
       return wrapResponse(response)
     },

package/src/server/respond.ts

@@ -3,6 +3,7 @@
  * responders, the fast JSON path, and cookie append. Imports only the runtime-core primitives + the
  * spine types, so the wire-response format lives in one module distinct from the request engine.
  */
+
 import {
   CONTEXT_SET,
   EMPTY_RESPONSE_CONTROLS,

package/src/server/server.ts

@@ -6,12 +6,17 @@ import {
   NIFRA_DEADLINE_HEADER,
   type RequestBudget,
 } from "../budget.ts"
+import type { EffectLifecycleObserver } from "../effect-lifecycle.ts"
 import { FrameworkError, RouteConfigError } from "../errors.ts"
 import {
+  type AroundCapabilityOptions,
   CAPABILITY_GUARD,
+  type CapabilityInterceptor,
   type CapabilityUseEvent,
   createCapabilityGuard,
+  DEFAULT_CAPABILITY_INTERCEPTOR_TIMEOUT_MS,
   normalizeRouteCapabilities,
+  type RegisteredCapabilityInterceptor,
 } from "../internal/capability-runtime.ts"
 import {
   type AssuranceDeclaration,
@@ -517,6 +522,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   /** Capacity-admission gate; `undefined` = off (the request path pays nothing). */
   private readonly capacityGate: AdmissionController | undefined
   private readonly onCapabilityUse: ((event: CapabilityUseEvent) => void) | undefined
+  private readonly capabilityInterceptors: RegisteredCapabilityInterceptor[]
+  private readonly capabilityObservers: EffectLifecycleObserver[]
   /** The installed effect-ledger runtime (owns the sink + per-route resolution + settle), or
    * `undefined` when the effect-ledger plugin is not installed. */
   private effectLedgerRuntime: EffectLedgerRuntime | undefined
@@ -579,6 +586,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     this.gracefulSignals = options.gracefulSignals ?? false
     this.capacityGate = options.admission
     this.onCapabilityUse = options.onCapabilityUse
+    this.capabilityInterceptors = []
+    this.capabilityObservers = []
     // The effect-ledger runtime is installed by `.use(effectLedger())`; a bare app never imports it, so
     // the ledger machinery tree-shakes out. Capability-declaring routes simply carry no ledger without it.
     this.effectLedgerRuntime = undefined
@@ -659,6 +668,40 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     return this
   }
 
+  /**
+   * Asynchronously admit each subsequent `executeCapability()` call before its owned effect runs.
+   * Interceptors receive token-only metadata plus an abort signal and must call `next()` exactly once
+   * to admit. Returning without `next()`, timing out, aborting, or throwing fails the effect closed.
+   */
+  aroundCapability(
+    interceptor: CapabilityInterceptor,
+    options: AroundCapabilityOptions = {},
+  ): this {
+    this.assertConfigurable("aroundCapability()")
+    if (typeof interceptor !== "function") {
+      throw new TypeError("aroundCapability interceptor must be a function")
+    }
+    const timeoutMs = options.timeoutMs ?? DEFAULT_CAPABILITY_INTERCEPTOR_TIMEOUT_MS
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+      throw new RangeError("aroundCapability timeoutMs must be a positive safe integer")
+    }
+    // JS timers wrap larger delays to ~1ms, which would unexpectedly deny every effect.
+    this.capabilityInterceptors.push(
+      Object.freeze({ interceptor, timeoutMs: Math.min(timeoutMs, 2_147_483_647) }),
+    )
+    return this
+  }
+
+  /** Observe token-only admission/execution lifecycle events for subsequent capability routes. */
+  observeCapability(observer: EffectLifecycleObserver): this {
+    this.assertConfigurable("observeCapability()")
+    if (typeof observer !== "function") {
+      throw new TypeError("observeCapability observer must be a function")
+    }
+    this.capabilityObservers.push(observer)
+    return this
+  }
+
   /** Transform the handler's result before it is serialized. Order-scoped. */
   afterHandle(fn: (result: unknown, context: Context & Ctx) => MaybePromise<unknown>): this {
     this.assertConfigurable("afterHandle()")
@@ -1120,6 +1163,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         method,
         path,
         this.onCapabilityUse,
+        this.idempotencyRuntime?.trackEffect,
+        Object.freeze([...this.capabilityInterceptors]),
+        Object.freeze([...this.capabilityObservers]),
       )
     }
     const hasDecorations = Reflect.ownKeys(routeDecorations).length > 0