@nifrajs/core 3.5.0 → 4.0.0

package/src/idempotency.ts

@@ -16,6 +16,9 @@ export type IdempotencyScope = "request" | "durable"
 /** Default retention for a stored idempotent response: 24 hours. */
 export const DEFAULT_IDEMPOTENCY_TTL_MS = 86_400_000
 
+/** Default lease on a key whose handler is still running, with a store that can renew it: 60 seconds. */
+export const DEFAULT_IDEMPOTENCY_PENDING_TTL_MS = 60_000
+
 /** Canonical request header carrying the client-chosen idempotency key. */
 export const DEFAULT_IDEMPOTENCY_HEADER = "idempotency-key"
 
@@ -80,7 +83,14 @@ export interface IdempotencyEntryKey {
 
 export interface IdempotencyBeginInput extends IdempotencyEntryKey {
   readonly fingerprint: string
+  /** Retention for the completed response. */
   readonly ttlMs: number
+  /**
+   * Lease on a `new` reservation: it lapses after this long unless {@link IdempotencyStore.renew}
+   * extends it, and `complete` then keeps the response for `ttlMs`. Passed only to a store with
+   * `renew`; when absent, the pending reservation holds the key for `ttlMs`.
+   */
+  readonly pendingTtlMs?: number | undefined
 }
 
 export interface IdempotencyCompletionInput extends IdempotencyEntryKey {
@@ -94,6 +104,13 @@ export interface IdempotencyAbandonInput extends IdempotencyEntryKey {
   readonly reservation: string
 }
 
+export interface IdempotencyRenewInput extends IdempotencyEntryKey {
+  /** Opaque ownership token returned by `begin(state:"new")`. */
+  readonly reservation: string
+  /** The new lease, from now. */
+  readonly ttlMs: number
+}
+
 /**
  * Storage seam for idempotent responses. `begin` MUST be atomic: for one key, exactly one concurrent
  * caller sees `new`; the rest see `in-flight` (or `replay` once completed). The in-memory store gets
@@ -115,6 +132,12 @@ export interface IdempotencyStore {
   complete(input: IdempotencyCompletionInput): boolean | Promise<boolean>
   /** Release only the pending reservation owned by `reservation`. */
   abandon(input: IdempotencyAbandonInput): boolean | Promise<boolean>
+  /**
+   * Extend the pending reservation owned by `reservation` to `ttlMs` from now. Returns false when it
+   * is gone, lapsed, or completed. The server calls it while the handler runs, so with it a key
+   * whose process died frees after `pendingTtlMs` instead of `ttlMs`.
+   */
+  renew?(input: IdempotencyRenewInput): boolean | Promise<boolean>
 }
 
 /** A key must be a non-empty, bounded, control-char-free token. Fail closed on anything else. */
@@ -312,6 +335,7 @@ export function responseFromStored(
 }
 
 interface MemoryEntry {
+  readonly namespace: string
   readonly fingerprint: string
   readonly reservation: string
   readonly ttlMs: number
@@ -324,6 +348,11 @@ export interface MemoryIdempotencyStoreOptions {
   readonly now?: () => number
   /** Hard memory bound. At capacity new keys fail closed; completed/pending entries are never evicted early. */
   readonly maxEntries?: number
+  /**
+   * Bound for one namespace, so a single tenant or principal cannot use up `maxEntries` for the
+   * rest: past it, only that namespace's new keys fail closed. Default: no separate bound.
+   */
+  readonly maxEntriesPerNamespace?: number
 }
 
 /**
@@ -334,8 +363,10 @@ export interface MemoryIdempotencyStoreOptions {
 export class MemoryIdempotencyStore implements IdempotencyStore {
   readonly durability = "memory" as const
   private readonly entries = new Map<string, MemoryEntry>()
+  private readonly perNamespace = new Map<string, number>()
   private readonly now: () => number
   private readonly maxEntries: number
+  private readonly maxPerNamespace: number
 
   constructor(options: MemoryIdempotencyStoreOptions = {}) {
     this.now = options.now ?? Date.now
@@ -343,6 +374,10 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
     if (!Number.isInteger(this.maxEntries) || this.maxEntries < 1) {
       throw new RangeError("idempotency: maxEntries must be a positive integer")
     }
+    this.maxPerNamespace = options.maxEntriesPerNamespace ?? this.maxEntries
+    if (!Number.isInteger(this.maxPerNamespace) || this.maxPerNamespace < 1) {
+      throw new RangeError("idempotency: maxEntriesPerNamespace must be a positive integer")
+    }
   }
 
   begin(input: IdempotencyBeginInput): IdempotencyBeginResult {
@@ -353,17 +388,19 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
       if (existing.response !== undefined) return { state: "replay", response: existing.response }
       return { state: "in-flight" }
     }
-    if (existing !== undefined) this.entries.delete(storageKey)
-    if (this.entries.size >= this.maxEntries) {
+    if (existing !== undefined) this.drop(storageKey, existing)
+    if (this.full(input.namespace)) {
       this.sweep()
-      if (this.entries.size >= this.maxEntries) return { state: "capacity" }
+      if (this.full(input.namespace)) return { state: "capacity" }
     }
     const reservation = crypto.randomUUID()
+    this.perNamespace.set(input.namespace, (this.perNamespace.get(input.namespace) ?? 0) + 1)
     this.entries.set(storageKey, {
+      namespace: input.namespace,
       fingerprint: input.fingerprint,
       reservation,
       ttlMs: input.ttlMs,
-      expiresAt: this.now() + input.ttlMs,
+      expiresAt: this.now() + (input.pendingTtlMs ?? input.ttlMs),
       response: undefined,
     })
     return { state: "new", reservation }
@@ -374,7 +411,7 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
     const entry = this.entries.get(key)
     if (entry === undefined || entry.reservation !== input.reservation) return false
     if (entry.expiresAt <= this.now()) {
-      this.entries.delete(key)
+      this.drop(key, entry)
       return false
     }
     entry.response = input.response
@@ -386,7 +423,7 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
     const key = this.storageKey(input)
     const entry = this.entries.get(key)
     if (entry !== undefined && entry.expiresAt <= this.now()) {
-      this.entries.delete(key)
+      this.drop(key, entry)
       return false
     }
     // Only drop a still-pending reservation; never evict a completed (replayable) response.
@@ -395,17 +432,30 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
       entry.response === undefined &&
       entry.reservation === input.reservation
     ) {
-      this.entries.delete(key)
+      this.drop(key, entry)
       return true
     }
     return false
   }
 
+  renew(input: IdempotencyRenewInput): boolean {
+    const entry = this.entries.get(this.storageKey(input))
+    if (
+      entry?.reservation !== input.reservation ||
+      entry.response !== undefined ||
+      entry.expiresAt <= this.now()
+    ) {
+      return false
+    }
+    entry.expiresAt = this.now() + input.ttlMs
+    return true
+  }
+
   /** Evict expired entries. Callers may run this on an interval; access-time eviction covers the rest. */
   sweep(): void {
     const now = this.now()
     for (const [key, entry] of this.entries) {
-      if (entry.expiresAt <= now) this.entries.delete(key)
+      if (entry.expiresAt <= now) this.drop(key, entry)
     }
   }
 
@@ -417,6 +467,20 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
   private storageKey(input: IdempotencyEntryKey): string {
     return `${input.namespace.length}:${input.namespace}${input.key}`
   }
+
+  private full(namespace: string): boolean {
+    return (
+      this.entries.size >= this.maxEntries ||
+      (this.perNamespace.get(namespace) ?? 0) >= this.maxPerNamespace
+    )
+  }
+
+  private drop(key: string, entry: MemoryEntry): void {
+    this.entries.delete(key)
+    const left = (this.perNamespace.get(entry.namespace) ?? 1) - 1
+    if (left > 0) this.perNamespace.set(entry.namespace, left)
+    else this.perNamespace.delete(entry.namespace)
+  }
 }
 
 /** Convenience factory mirroring the other core primitives' `create*` style. */

package/src/index.ts

@@ -16,14 +16,25 @@
  * 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 = "3.5.0" as const
+export const VERSION = "4.0.0" as const
 
 export type Version = typeof VERSION
 
 export { FrameworkError, RouteConfigError, type RouteConfigErrorCode } from "./errors.ts"
 export { FRAMEWORK_NAME, type FrameworkName } from "./internal/brand.ts"
 export { isSameOriginRequest } from "./internal/same-origin.ts"
-export { METHODS, type Method, Router, type RouterMatch } from "./router/router.ts"
+export {
+  ROUTE_PATTERN_OVERLAP_MAX_STATES,
+  RoutePatternOverlapLimitError,
+  routePatternOverlap,
+} from "./router/overlap.ts"
+export {
+  METHODS,
+  type Method,
+  type RouteMethod,
+  Router,
+  type RouterMatch,
+} from "./router/router.ts"
 export type {
   InferInput,
   InferOutput,
@@ -33,11 +44,24 @@ export type {
   StandardTypes,
   ValidationOutcome,
 } from "./schema/standard.ts"
+export {
+  type AuthenticationFailure,
+  type AuthenticationFailureReason,
+  type AuthenticationInput,
+  type AuthenticationResult,
+  type AuthenticationStage,
+  type AuthenticationSuccess,
+  type AuthHeaders,
+  type AuthMaybePromise,
+  authenticated,
+  rejected,
+} from "./server/auth.ts"
 export type {
   Context,
   Params,
   Platform,
   Prettify,
+  RequestPath,
   ResponseControls,
   RouteSchema,
 } from "./server/context.ts"
@@ -83,7 +107,15 @@ export {
   toVercelHandler,
   type VercelHandler,
 } from "./server/platform-adapters.ts"
-export type { Registry, ResponseMapFor, RouteInfo, RouteInfoFor } from "./server/registry.ts"
+export type {
+  JoinRoutePath,
+  PrefixRegistry,
+  Registry,
+  ResponseMapFor,
+  RouteInfo,
+  RouteInfoFor,
+} from "./server/registry.ts"
+export { replacedRequestOf } from "./server/request-lineage.ts"
 export {
   type PlainRender,
   type ResponseResult,
@@ -102,13 +134,18 @@ export {
   defineRouterPlugin,
   type Handler,
   type IdentityPlugin,
+  type ListenTlsOptions,
   type McpPromptDescriptor,
   type McpResourceDescriptor,
   type Middleware,
+  type MountableApp,
+  type MountFetchOptions,
+  type MountOptions,
   type NifraFeatureVersion,
   type NifraPlugin,
   type NodeRequestContext,
   type NodeRequestHook,
+  type NodeResponseBodyHook,
   type NodeResponseContext,
   type NodeResponseHook,
   type NodeServeOutcome,

package/src/internal/code-unit-order.ts

@@ -0,0 +1,8 @@
+/**
+ * Code-unit order, the same on every runtime and in every locale. `localeCompare` answers by the
+ * runtime's locale and ICU data, so an artifact that is hashed, signed, or committed sorts with this
+ * instead: its bytes must not depend on the machine that built it.
+ */
+export function codeUnitOrder(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0
+}

package/src/internal/durable-saga-protocol.ts

@@ -22,6 +22,8 @@ function transitionSaga(
 ): SagaRecord | undefined {
   if (
     input.record.version !== input.version + 1 ||
+    // A record filed under another saga's key could never load again, and scans would act on its id.
+    input.record.sagaId !== input.sagaId ||
     (current !== undefined &&
       (current.sagaId !== input.sagaId || current.version !== input.version))
   ) {

package/src/internal/route-catalog.ts

@@ -16,7 +16,7 @@
  * registration.
  */
 import type { CompiledRoutePattern } from "../router/pattern.ts"
-import { type Method, Router, type RouterMatch } from "../router/router.ts"
+import { Router, type RouterMatch } from "../router/router.ts"
 import type { RouteDescriptor } from "../server/server-types.ts"
 import type { AssuranceDeclaration } from "./route-assurance.ts"
 import type { RouteEntry } from "./route-execution.ts"
@@ -24,7 +24,7 @@ import type { RouteEntry } from "./route-execution.ts"
 /** One canonical runtime route fact. The catalog owns matching, reflection, assurance, tool metadata,
  * replay, and native compilation input so batch registration has one commit point. */
 export interface CatalogRoute {
-  readonly method: Method
+  readonly method: string
   readonly path: string
   readonly pattern: CompiledRoutePattern
   readonly entry: RouteEntry
@@ -33,10 +33,10 @@ export interface CatalogRoute {
 }
 
 /**
- * Runtime route catalog. Single-route registration mutates directly; multi-route registration replays
- * the existing catalog plus the candidate batch into a staged router, then swaps the complete state only
- * after every route validates. Failed `implement()`/`merge()` batches therefore leave matching and
- * reflection unchanged.
+ * Runtime route catalog. Single-route registration mutates directly. A batch adds its routes the same
+ * way and, if one is rejected, restores the catalog to what it was before the batch. A failed
+ * `implement()`/`merge()` batch therefore leaves matching and reflection unchanged, and a batch that
+ * validates costs what its routes cost one by one.
  *
  * Coverage note: this file reports 90% functions with every method exercised. `bun test --coverage`
  * (1.3.14) counts one synthetic function per class that it never marks hit - a one-method class with a
@@ -58,18 +58,19 @@ export class RouteCatalog {
   }
 
   addBatch(routes: readonly CatalogRoute[]): void {
-    if (routes.length === 0) return
-    const nextRecords = this.records.concat(routes)
-    const nextDescriptors = this.descriptors.concat(routes.map(({ descriptor }) => descriptor))
-    const nextAssurancePresent =
-      this.assurancePresent || routes.some((route) => route.assurance.length > 0)
-    const staged = new Router<RouteEntry>()
-    for (const route of this.records) staged.add(route.method, route.pattern, route.entry)
-    for (const route of routes) staged.add(route.method, route.pattern, route.entry)
-    this.matcher = staged
-    this.records = nextRecords
-    this.descriptors = nextDescriptors
-    this.assurancePresent = nextAssurancePresent
+    const kept = this.records.length
+    const assurancePresent = this.assurancePresent
+    try {
+      for (const route of routes) this.add(route)
+    } catch (error) {
+      // The rejected route may have left nodes in the trie, so the matcher is not patched: it is
+      // rebuilt from the routes that were there before the batch. They validated once already.
+      this.records.length = this.descriptors.length = kept
+      this.assurancePresent = assurancePresent
+      this.matcher = new Router<RouteEntry>()
+      for (const route of this.records) this.matcher.add(route.method, route.pattern, route.entry)
+      throw error
+    }
   }
 
   find(method: string, path: string): RouterMatch<RouteEntry> {

package/src/internal/route-compiler.ts

@@ -13,13 +13,14 @@
 import type { EffectLifecycleObserver } from "../effect-lifecycle.ts"
 import { RouteConfigError } from "../errors.ts"
 import { type CompiledRoutePattern, compileRoutePattern } from "../router/pattern.ts"
-import type { Method } from "../router/router.ts"
-import type { StandardSchemaV1 } from "../schema/standard.ts"
 import { assertByteLimit } from "../server/body.ts"
 import type { RouteSchema } from "../server/context.ts"
 import type { IdempotencyRuntime, ResolvedIdempotency } from "../server/idempotency-lane.ts"
 import type { EffectLedgerRuntime, ResolvedEffectLedger } from "../server/ledger-lane.ts"
-import type { ResponseContractRuntime } from "../server/response-contract-lane.ts"
+import type {
+  ResponseContractDefinition,
+  ResponseContractRuntime,
+} from "../server/response-contract-lane.ts"
 import {
   CAPABILITY_GUARD,
   type CapabilityUseEvent,
@@ -37,6 +38,7 @@ import {
 import type {
   RawAfterHandle,
   RawAround,
+  RawAuthStage,
   RawBeforeHandle,
   RawDerive,
   RawErrorHandler,
@@ -55,6 +57,7 @@ export interface RouteCompilerContext {
   readonly idempotencyRuntime: IdempotencyRuntime | undefined
   readonly responseContractRuntime: ResponseContractRuntime | undefined
   readonly derives: readonly RawDerive[]
+  readonly authStages: readonly RawAuthStage[]
   readonly beforeHandleHooks: readonly RawBeforeHandle[]
   readonly afterHandleHooks: readonly RawAfterHandle[]
   readonly onErrorHooks: readonly RawErrorHandler[]
@@ -72,16 +75,18 @@ export interface CompiledRouteOptions {
   readonly idempotent: ResolvedIdempotency | undefined
   readonly ledgered: ResolvedEffectLedger | undefined
   readonly responseContract:
-    | { readonly runtime: ResponseContractRuntime; readonly schema: StandardSchemaV1 }
+    | { readonly runtime: ResponseContractRuntime; readonly definition: ResponseContractDefinition }
     | undefined
   readonly lanes: RouteLaneSelection
   readonly routeAssurance: readonly AssuranceDeclaration[]
+  readonly authStages: readonly RawAuthStage[]
+  readonly authenticated: boolean
 }
 
 /** Resolve all registration-time policy and lane facts for one route. */
 export function compileRouteOptions(
   context: RouteCompilerContext,
-  method: Method,
+  method: string,
   path: string,
   schema: RouteSchema | undefined,
   handler: (context: never) => unknown,
@@ -91,6 +96,25 @@ export function compileRouteOptions(
   const invalidBodyLimit = (message: string): never => {
     throw new RouteConfigError("INVALID_BODY_LIMIT", `route ${method} ${path}: ${message}`)
   }
+  if (schema?.wire !== undefined && schema.wire !== "raw") {
+    throw new RouteConfigError("INVALID_WIRE", `route ${method} ${path}: wire must be "raw"`)
+  }
+  if (schema?.wire === "raw" && schema.body !== undefined) {
+    throw new RouteConfigError(
+      "INVALID_WIRE",
+      `route ${method} ${path}: wire: "raw" cannot be combined with a body schema`,
+    )
+  }
+  if (
+    schema?.validationOrder !== undefined &&
+    schema.validationOrder !== "validate-before-auth" &&
+    schema.validationOrder !== "auth-before-validation"
+  ) {
+    throw new RouteConfigError(
+      "INVALID_VALIDATION_ORDER",
+      `route ${method} ${path}: validationOrder is invalid`,
+    )
+  }
   if (schema?.bodyLimitReason !== undefined && schema.bodyLimit !== "unlimited") {
     invalidBodyLimit('bodyLimitReason is only valid with bodyLimit: "unlimited"')
   }
@@ -124,11 +148,13 @@ export function compileRouteOptions(
     )
   }
 
-  const authenticated = assuranceEvidenceFor(
-    [...context.activeAssurance, ...handlerAssurance, ...context.globalAssurance],
-    method,
-    path,
-  ).some((evidence) => evidence.id === NIFRA_ASSURANCE_IDS.AUTHENTICATED)
+  const authenticated =
+    context.authStages.length > 0 ||
+    assuranceEvidenceFor(
+      [...context.activeAssurance, ...handlerAssurance, ...context.globalAssurance],
+      method,
+      path,
+    ).some((evidence) => evidence.id === NIFRA_ASSURANCE_IDS.AUTHENTICATED)
   const routeDecorations: Record<PropertyKey, unknown> = { ...context.decorations }
   if (capabilities.length > 0) {
     routeDecorations[CAPABILITY_GUARD] = createCapabilityGuard(
@@ -155,12 +181,20 @@ export function compileRouteOptions(
     context.maxBodyBytes,
   )
   const ledgered = context.effectLedgerRuntime?.resolve(capabilities, method, path)
+  const responseDefinition =
+    schema?.response !== undefined || schema?.errors !== undefined
+      ? {
+          ...(schema.response === undefined ? {} : { response: schema.response }),
+          ...(schema.errors === undefined ? {} : { errors: schema.errors }),
+        }
+      : undefined
   const contracted =
-    context.responseContractRuntime !== undefined && schema?.response !== undefined
-      ? { runtime: context.responseContractRuntime, schema: schema.response }
+    context.responseContractRuntime !== undefined && responseDefinition !== undefined
+      ? { runtime: context.responseContractRuntime, definition: responseDefinition }
       : undefined
   const lanes = selectRouteLanes({
     schema,
+    hasAuth: context.authStages.length > 0,
     hasIdempotency: idempotent !== undefined,
     hasLedger: ledgered !== undefined,
     hasResponseContract: contracted !== undefined,
@@ -174,7 +208,7 @@ export function compileRouteOptions(
   })
 
   const routeAssurance: AssuranceDeclaration[] = [...context.activeAssurance, ...handlerAssurance]
-  if (contracted?.runtime.mode === "enforce" && schema?.response !== undefined) {
+  if (contracted?.runtime.mode === "enforce") {
     routeAssurance.push(
       Object.freeze({
         id: NIFRA_ASSURANCE_IDS.RESPONSE_CONTRACT,
@@ -217,6 +251,19 @@ export function compileRouteOptions(
       }),
     )
   }
+  if (context.authStages.length > 0) {
+    // `authenticate()` is an actual runtime enforcement stage, not a route assertion. Publish its
+    // proof directly so a core-authenticated route cannot accidentally become assurance
+    // classification-only when it is not using an integration plugin such as better-auth.
+    routeAssurance.push(
+      Object.freeze({
+        id: NIFRA_ASSURANCE_IDS.AUTHENTICATED,
+        source: "nifra.authenticate",
+        scope: "plugin",
+        provenance: "runtime" as const,
+      }),
+    )
+  }
 
   return {
     pattern,
@@ -230,5 +277,7 @@ export function compileRouteOptions(
     responseContract: contracted,
     lanes,
     routeAssurance: Object.freeze(routeAssurance),
+    authStages: Object.freeze([...context.authStages]),
+    authenticated,
   }
 }

package/src/internal/route-execution.ts

@@ -18,7 +18,7 @@
  */
 import type { RequestBudget } from "../budget.ts"
 import type { RequestLedger } from "../ledger.ts"
-import type { StandardSchemaV1 } from "../schema/standard.ts"
+import type { AuthenticationStage } from "../server/auth.ts"
 import { UNLIMITED_BODY_BYTES } from "../server/body.ts"
 import type { Platform, RouteSchema } from "../server/context.ts"
 import type { ResolvedIdempotency } from "../server/idempotency-lane.ts"
@@ -26,7 +26,10 @@ import type { EffectLedgerRuntime, ResolvedEffectLedger } from "../server/ledger
 import type { ProtoPoisoning } from "../server/proto-guard.ts"
 import type { Registry } from "../server/registry.ts"
 import { RequestContext } from "../server/request-context.ts"
-import type { ResponseContractRuntime } from "../server/response-contract-lane.ts"
+import type {
+  ResponseContractDefinition,
+  ResponseContractRuntime,
+} from "../server/response-contract-lane.ts"
 import type { HandlerResult, ResponseResult } from "../server/runtime-core.ts"
 import type { CtxSet, MaybePromise, RawContext, RequestSource, Server } from "../server/server.ts"
 import type { RouteProgram } from "./route-program.ts"
@@ -35,6 +38,8 @@ export type InternalHandler = (ctx: RawContext) => MaybePromise<HandlerResult>
 
 /** A `derive` computes per-request context extensions; stored path-erased. */
 export type RawDerive = (ctx: RawContext) => MaybePromise<object>
+/** A route-scoped authentication provider, stored path-erased after registration. */
+export type RawAuthStage = AuthenticationStage<unknown, unknown>
 export type RawBeforeHandle = (ctx: RawContext) => MaybePromise<unknown>
 export type RawAfterHandle = (result: unknown, ctx: RawContext) => MaybePromise<unknown>
 export type RawErrorHandler = (error: unknown, ctx: RawContext) => MaybePromise<unknown>
@@ -311,10 +316,15 @@ export interface RouteEntry {
    * at registration; `undefined` = not checked (the default, and the only state in which the route can
    * still take the fused/native lanes). */
   readonly responseContract:
-    | { readonly runtime: ResponseContractRuntime; readonly schema: StandardSchemaV1 }
+    | {
+        readonly runtime: ResponseContractRuntime
+        readonly definition: ResponseContractDefinition
+      }
     | undefined
   /** Per-request context extensions captured at registration (order-scoped). */
   readonly derives: ReadonlyArray<RawDerive>
+  /** Dedicated auth stages run before validation; ordinary derives keep their existing order. */
+  readonly authStages: ReadonlyArray<RawAuthStage>
   /** Static context extensions captured at registration. */
   readonly decorations: Record<PropertyKey, unknown>
   /** Whether {@link decorations} has any keys - precomputed so the hot path skips a no-op