dd-trace 6.18.0 → 6.20.0

package/packages/dd-trace/src/openfeature/writers/flag-evaluation-aggregation.js

@@ -0,0 +1,190 @@
+'use strict'
+
+const { createHash } = require('node:crypto')
+
+const {
+  FLAG_EVALUATION_DEGRADED_CAP,
+  FLAG_EVALUATION_GLOBAL_CAP,
+  FLAG_EVALUATION_PER_FLAG_CAP,
+} = require('../constants/constants')
+const { validatedContextEntries, snapshotFromEntries } = require('./flag-evaluation-context')
+const { normalizeTargetingKey, optionalKey, protectedErrorCode } =
+  require('./flag-evaluation-pii')
+const { recordDegraded, recordDropped } = require('./flag-evaluation-telemetry')
+
+// V8 hashes longer strings by length alone, making equal-length identities expensive to distinguish.
+const MAX_DIRECT_IDENTITY_LENGTH = 16_383
+
+/** @typedef {import('./flag-evaluation-context').ContextSnapshot} ContextSnapshot */
+/**
+ * @typedef {object} FlagEvaluationEvent
+ * @property {string} flagKey
+ * @property {string} [variant]
+ * @property {string} [allocationKey]
+ * @property {boolean} runtimeDefault
+ * @property {unknown} [errorCode]
+ * @property {unknown} [targetingKey]
+ * @property {ContextSnapshot} [attrs]
+ * @property {unknown} [observeFullEvaluationData]
+ * @property {number} timestamp
+ */
+/**
+ * @typedef {object} AggregationDimensions
+ * @property {string} flagKey
+ * @property {string} [variant]
+ * @property {string} [allocation]
+ * @property {string} [error]
+ */
+/**
+ * @typedef {AggregationDimensions & {
+ *   runtimeDefault: boolean,
+ *   rawTargetingKey?: string,
+ *   attrs?: ContextSnapshot,
+ *   consent: boolean,
+ *   count: number,
+ *   first: number,
+ *   last: number
+ * }} AggregationEntry
+ */
+/**
+ * @typedef {object} AggregationResult
+ * @property {Map<string, AggregationEntry>} full
+ * @property {Map<string, AggregationEntry>} degraded
+ */
+
+/**
+ * Merge one observation into an aggregation entry.
+ *
+ * @param {AggregationEntry} entry
+ * @param {number} timestamp
+ * @param {unknown} consent
+ */
+function observeEntry (entry, timestamp, consent) {
+  entry.count++
+  entry.first = Math.min(entry.first, timestamp)
+  entry.last = Math.max(entry.last, timestamp)
+  entry.consent &&= consent === true
+}
+
+/** @param {Map<string, AggregationEntry>} entries */
+function evaluationCount (entries) {
+  let count = 0
+  for (const entry of entries.values()) count += entry.count
+  return count
+}
+
+class FlagEvaluationAggregator {
+  /** @type {Map<string, AggregationEntry>} */
+  #full = new Map()
+  /** @type {Map<string, AggregationEntry>} */
+  #degraded = new Map()
+  /** @type {Map<string, number>} */
+  #perFlag = new Map()
+
+  /** @param {FlagEvaluationEvent} event */
+  add (event) {
+    const flagKey = normalizeTargetingKey(event.flagKey)
+    if (flagKey === undefined || !Number.isSafeInteger(event.timestamp)) {
+      recordDropped('serialization_error')
+      return
+    }
+    const consent = event.observeFullEvaluationData === true
+    const targetingKey = normalizeTargetingKey(event.targetingKey)
+    const contextEntries = consent ? validatedContextEntries(event.attrs) : undefined
+    const error = protectedErrorCode(event.errorCode)
+    const variant = optionalKey(event.variant)
+    const allocation = optionalKey(event.allocationKey)
+    // Group by the raw key; the serializer independently hashes protected rows once per output bucket.
+    const identity = JSON.stringify([
+      flagKey, variant, allocation, event.runtimeDefault === true, error,
+      targetingKey, contextEntries, consent,
+    ])
+    // Keep digest keys separate from short JSON identities, which always start with '['.
+    const fullKey = identity.length > MAX_DIRECT_IDENTITY_LENGTH
+      ? '#' + createHash('sha256').update(identity).digest('base64')
+      : identity
+    const existing = this.#full.get(fullKey)
+    if (existing) {
+      observeEntry(existing, event.timestamp, consent)
+      return
+    }
+
+    const perFlag = this.#perFlag.get(flagKey) ?? 0
+    if (perFlag >= FLAG_EVALUATION_PER_FLAG_CAP) {
+      this.#addDegraded(event, { flagKey, variant, allocation, error })
+      return
+    }
+    if (this.#full.size >= FLAG_EVALUATION_GLOBAL_CAP) {
+      this.#addDegraded(event, { flagKey, variant, allocation, error })
+      return
+    }
+
+    this.#perFlag.set(flagKey, perFlag + 1)
+    this.#full.set(fullKey, {
+      flagKey,
+      variant,
+      allocation,
+      runtimeDefault: event.runtimeDefault === true,
+      error,
+      rawTargetingKey: targetingKey,
+      // Repeated observations need validation and identity, but no new retained snapshot.
+      attrs: snapshotFromEntries(contextEntries),
+      consent,
+      count: 1,
+      first: event.timestamp,
+      last: event.timestamp,
+    })
+  }
+
+  /** @returns {AggregationResult} */
+  take () {
+    const result = { full: this.#full, degraded: this.#degraded }
+    this.#full = new Map()
+    this.#degraded = new Map()
+    this.#perFlag = new Map()
+    return result
+  }
+
+  clear () {
+    const count = evaluationCount(this.#full) + evaluationCount(this.#degraded)
+    this.#full = new Map()
+    this.#degraded = new Map()
+    this.#perFlag = new Map()
+    return count
+  }
+
+  get size () {
+    return this.#full.size + this.#degraded.size
+  }
+
+  /**
+   * @param {FlagEvaluationEvent} event
+   * @param {AggregationDimensions} dimensions
+   */
+  #addDegraded (event, dimensions) {
+    recordDegraded('cardinality_cap')
+    const key = JSON.stringify([
+      dimensions.flagKey, dimensions.variant, dimensions.allocation,
+      event.runtimeDefault === true, dimensions.error,
+    ])
+    const existing = this.#degraded.get(key)
+    if (existing) {
+      observeEntry(existing, event.timestamp, event.observeFullEvaluationData)
+      return
+    }
+    if (this.#degraded.size >= FLAG_EVALUATION_DEGRADED_CAP) {
+      recordDropped('degraded_cap')
+      return
+    }
+    this.#degraded.set(key, {
+      ...dimensions,
+      runtimeDefault: event.runtimeDefault === true,
+      consent: event.observeFullEvaluationData === true,
+      count: 1,
+      first: event.timestamp,
+      last: event.timestamp,
+    })
+  }
+}
+
+module.exports = { FlagEvaluationAggregator }

package/packages/dd-trace/src/openfeature/writers/flag-evaluation-consumer.js

@@ -0,0 +1,233 @@
+'use strict'
+
+const {
+  EVP_PAYLOAD_SIZE_LIMIT,
+  FLAG_EVALUATION_ENDPOINT,
+  FLAG_EVALUATION_FLUSH_INTERVAL,
+  FLAG_EVALUATION_QUEUE_CAP,
+} = require('../constants/constants')
+const {
+  EVP_EVENT_PLATFORM_SUBDOMAIN,
+  EVP_PROXY_PATH_V2,
+  EVP_SUBDOMAIN_HEADER_NAME,
+} = require('../../evp_proxy/constants')
+const { joinEVPProxyPath } = require('../../evp_proxy/path')
+const { FlagEvaluationAggregator } = require('./flag-evaluation-aggregation')
+const { iterateFlagEvaluationPayloads } = require('./flag-evaluation-payload')
+const { normalizeFlagEvaluationEvent, normalizeTargetingKey } = require('./flag-evaluation-pii')
+const { recordDropped, recordTargetingKeyOmitted } = require('./flag-evaluation-telemetry')
+const BaseFFEWriter = require('./base')
+
+/** @typedef {import('./flag-evaluation-aggregation').FlagEvaluationEvent} FlagEvaluationEvent */
+
+/**
+ * @typedef {object} FlagEvaluationRoute
+ * @property {URL} url
+ * @property {string} basePath
+ * @property {object} [headers]
+ * @property {import('node:https').Agent} [agent]
+ * @property {() => void} [onFallback]
+ * @property {() => void} [onUnavailable]
+ * @property {FlagEvaluationRoute} [fallback]
+ */
+
+class FlagEvaluationConsumer extends BaseFFEWriter {
+  #enabled = false
+  #closed = false
+  #queue = []
+  #immediate
+  #aggregator = new FlagEvaluationAggregator()
+  #context
+  #pendingBytes = 0
+  #pending
+  #pendingCount = 0
+  #pumping = false
+  #flushRequested = false
+  #onProcessed
+  #onDelivered
+  #onIdle
+
+  /**
+   * @param {import('../../config/config-base')} config
+   * @param {FlagEvaluationRoute} [route]
+   * @param {object} [callbacks] - Worker ownership callbacks
+   * @param {(count: number) => void} [callbacks.onProcessed] - Release input credit after processing
+   * @param {(count: number) => void} [callbacks.onDelivered] - Release observations after successful delivery
+   * @param {() => void} [callbacks.onIdle] - Called once shutdown has drained delivery
+   */
+  constructor (config, route, { onProcessed, onDelivered, onIdle } = {}) {
+    route ??= {
+      url: /** @type {URL} */ (config.url),
+      basePath: EVP_PROXY_PATH_V2,
+    }
+    const headers = route.headers ?? { [EVP_SUBDOMAIN_HEADER_NAME]: EVP_EVENT_PLATFORM_SUBDOMAIN }
+    super({
+      config,
+      interval: FLAG_EVALUATION_FLUSH_INTERVAL,
+      agentUrl: route.url,
+      endpoint: joinEVPProxyPath(route.basePath, FLAG_EVALUATION_ENDPOINT),
+      headers,
+      // Consent to send evaluation data never permits logging an echoed response body or error message.
+      formatError: (error, statusCode) => statusCode === undefined
+        ? `Transport error ${error.code ?? 'UNKNOWN'}`
+        : `HTTP status ${statusCode}`,
+    })
+    this.#setRoute({ ...route, headers })
+    this.#onProcessed = onProcessed
+    this.#onDelivered = onDelivered
+    this.#onIdle = onIdle
+
+    this.#context = { service: typeof config.service === 'string' ? config.service : '' }
+    if (typeof config.env === 'string') this.#context.env = config.env
+    if (typeof config.version === 'string') this.#context.version = config.version
+  }
+
+  hasCapacity () {
+    return this.#enabled && !this.#closed && this.#queue.length < FLAG_EVALUATION_QUEUE_CAP
+  }
+
+  /**
+   * @param {boolean} enabled
+   * @param {FlagEvaluationRoute} [route]
+   */
+  setEnabled (enabled, route) {
+    if (route) this.#setRoute(route)
+    if (!enabled && this.#enabled) this.#discardBuffered('unavailable')
+    this.#enabled = enabled && !this.#closed
+  }
+
+  /** @param {FlagEvaluationEvent} event */
+  enqueue (event) {
+    if (this.#closed) {
+      recordDropped('closed')
+      return false
+    }
+    if (!this.#enabled) {
+      recordDropped('unavailable')
+      return false
+    }
+    if (this.#queue.length >= FLAG_EVALUATION_QUEUE_CAP) {
+      recordDropped('queue_overflow')
+      return false
+    }
+
+    const targetingKey = normalizeTargetingKey(event.targetingKey)
+    if (targetingKey === undefined && event.targetingKey !== undefined && event.targetingKey !== null) {
+      recordTargetingKeyOmitted()
+    }
+    this.#queue.push(normalizeFlagEvaluationEvent(event, targetingKey))
+    if (this.#immediate === undefined) {
+      this.#immediate = setImmediate(() => this.#drain())
+      this.#immediate.unref?.()
+    }
+    return true
+  }
+
+  flush () {
+    this.#cancelImmediate()
+    this.#drain()
+    if (!this.#enabled && !this.#closed) return
+    this.#flushRequested = true
+    this.#pump()
+  }
+
+  destroy () {
+    if (this.#closed) return
+    this.#cancelImmediate()
+    this.#drain()
+    this.#closed = true
+    this.#enabled = false
+    super.destroy()
+  }
+
+  #pump () {
+    if (this.#pumping) return
+    this.#pumping = true
+    try {
+      // Reserve a maximum-sized payload before advancing the iterator. HTTP callbacks release this budget.
+      while (this.#pendingBytes <= EVP_PAYLOAD_SIZE_LIMIT) {
+        if (!this.#pending) {
+          if ((!this.#flushRequested && !this.#closed) || this.#aggregator.size === 0) break
+          this.#flushRequested = false
+          const { full, degraded } = this.#aggregator.take()
+          for (const entry of full.values()) this.#pendingCount += entry.count
+          for (const entry of degraded.values()) this.#pendingCount += entry.count
+          this.#pending = iterateFlagEvaluationPayloads(full, degraded, this.#context, Date.now(), count => {
+            this.#pendingCount -= count
+          })
+        }
+        const next = this.#pending.next()
+        if (next.done) {
+          this.#pending = undefined
+          continue
+        }
+        const payload = next.value
+        const bytes = Buffer.byteLength(payload.encoded)
+        this.#pendingBytes += bytes
+        this._sendPayload(payload.encoded, payload.rows, delivered => {
+          this.#pendingBytes -= bytes
+          if (delivered) this.#onDelivered?.(payload.evaluations)
+          else recordDropped('delivery_failure', payload.evaluations)
+          this.#pump()
+        })
+      }
+    } finally {
+      this.#pumping = false
+    }
+    if (this.#closed && !this.#pending && this.#aggregator.size === 0 && this.#pendingBytes === 0) {
+      this.#onIdle?.()
+      this.#onIdle = undefined
+    }
+  }
+
+  /** @param {FlagEvaluationRoute} route */
+  #setRoute (route) {
+    const headers = route.headers ?? { [EVP_SUBDOMAIN_HEADER_NAME]: EVP_EVENT_PLATFORM_SUBDOMAIN }
+    const fallback = route.fallback && {
+      url: route.fallback.url,
+      endpoint: joinEVPProxyPath(route.fallback.basePath, FLAG_EVALUATION_ENDPOINT),
+      headers: route.fallback.headers ?? {},
+      agent: route.fallback.agent,
+      onFallback: route.fallback.onFallback,
+      onUnavailable: route.fallback.onUnavailable,
+    }
+    this._setRoutes({
+      url: route.url,
+      endpoint: joinEVPProxyPath(route.basePath, FLAG_EVALUATION_ENDPOINT),
+      headers,
+      agent: route.agent,
+      onFallback: route.onFallback,
+      onUnavailable: route.onUnavailable,
+    }, fallback)
+  }
+
+  #cancelImmediate () {
+    if (this.#immediate !== undefined) clearImmediate(this.#immediate)
+    this.#immediate = undefined
+  }
+
+  #drain () {
+    this.#immediate = undefined
+    const queue = this.#queue
+    this.#queue = []
+    for (const event of queue) {
+      this.#aggregator.add(event)
+      this.#onProcessed?.(1)
+    }
+  }
+
+  /** @param {string} reason */
+  #discardBuffered (reason) {
+    this.#cancelImmediate()
+    const count = this.#queue.length + this.#aggregator.clear() + this.#pendingCount
+    this.#pending?.return()
+    this.#pending = undefined
+    this.#pendingCount = 0
+    this.#flushRequested = false
+    this.#onProcessed?.(this.#queue.length)
+    this.#queue = []
+    recordDropped(reason, count)
+  }
+}
+
+module.exports = FlagEvaluationConsumer

package/packages/dd-trace/src/openfeature/writers/flag-evaluation-context.js

@@ -0,0 +1,262 @@
+'use strict'
+
+const { types: { isDate, isProxy } } = require('node:util')
+
+const { normalizeTargetingKey } = require('./flag-evaluation-pii')
+
+const MAX_CONTEXT_FIELDS = 256
+const MAX_KEY_LENGTH = 256
+const MAX_VALUE_LENGTH = 256
+const MAX_LIST_ELEMENTS = 256
+const MAX_STRUCTURE_PROPERTIES = 256
+const MAX_SNAPSHOT_DEPTH = 4
+const MAX_VISITED_NODES = MAX_CONTEXT_FIELDS * (MAX_SNAPSHOT_DEPTH + 1)
+const OMIT_CONTEXT_VALUE = Symbol('omit context value')
+
+/** @typedef {string | number | boolean | null} ContextScalar */
+/** @typedef {Readonly<Record<string, ContextScalar>>} ContextSnapshot */
+/** @typedef {Array<[string, ContextScalar]>} ContextEntries */
+/**
+ * @typedef {object} Frame
+ * @property {object} container
+ * @property {string} prefix
+ * @property {number} depth
+ * @property {string[] | undefined} keys
+ * @property {number} index
+ * @property {number} limit
+ */
+
+/**
+ * Only plain data records are supported; caller-defined behavior is not part of telemetry.
+ * Check proxies before any reflection, including revoked proxies.
+ *
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isRecord (value) {
+  if (value === null || typeof value !== 'object' || isProxy(value)) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === null || prototype === Object.prototype
+}
+
+/**
+ * Revalidate a hook-owned scalar snapshot without invoking caller behavior.
+ * Aggregation and serialization call this independently at their privacy boundaries.
+ *
+ * @param {unknown} value
+ * @returns {ContextSnapshot | undefined}
+ */
+function validateContextSnapshot (value) {
+  if (!isRecord(value)) return
+  /** @type {Record<string, ContextScalar>} */
+  const attrs = Object.create(null)
+  let hasAttrs = false
+  for (const key of Object.keys(value)) {
+    const item = validatedContextValue(value, key)
+    if (item === OMIT_CONTEXT_VALUE) continue
+    attrs[key] = item
+    hasAttrs = true
+  }
+  return hasAttrs ? Object.freeze(attrs) : undefined
+}
+
+/**
+ * Share the privacy checks without making serialization allocate identity tuples.
+ * The sentinel distinguishes rejected values from a valid null scalar.
+ *
+ * @param {Record<string, unknown>} snapshot
+ * @param {string} key
+ * @returns {ContextScalar | typeof OMIT_CONTEXT_VALUE}
+ */
+function validatedContextValue (snapshot, key) {
+  const descriptor = Object.getOwnPropertyDescriptor(snapshot, key)
+  if (!descriptor?.enumerable || !Object.hasOwn(descriptor, 'value')) return OMIT_CONTEXT_VALUE
+  const item = descriptor.value
+  if (normalizeTargetingKey(key) === undefined) return OMIT_CONTEXT_VALUE
+  if (item === null || typeof item === 'boolean' ||
+    (typeof item === 'number' && Number.isFinite(item)) ||
+    (typeof item === 'string' && normalizeTargetingKey(item) !== undefined)) return item
+  return OMIT_CONTEXT_VALUE
+}
+
+/**
+ * Validate once and order the scalar entries for aggregation identity. Returning
+ * tuples lets the complete key be JSON-encoded once, preserving scalar types and
+ * escaping delimiters without embedding an already-encoded context string.
+ *
+ * @param {unknown} value - Hook-owned snapshot, after queue handoff
+ * @returns {ContextEntries | undefined}
+ */
+function validatedContextEntries (value) {
+  if (!isRecord(value)) return
+  /** @type {ContextEntries} */
+  const entries = []
+  for (const key of Object.keys(value).sort()) {
+    const item = validatedContextValue(value, key)
+    if (item !== OMIT_CONTEXT_VALUE) entries.push([key, item])
+  }
+  return entries.length > 0 ? entries : undefined
+}
+
+/**
+ * Materialize owned, immutable attributes only when they will be retained or sent.
+ * Callers must obtain entries from validatedContextEntries, never caller-owned data.
+ *
+ * @param {ContextEntries | undefined} entries
+ * @returns {ContextSnapshot | undefined}
+ */
+function snapshotFromEntries (entries) {
+  if (entries === undefined) return
+  /** @type {Record<string, ContextScalar>} */
+  const attrs = Object.create(null)
+  for (const [key, value] of entries) attrs[key] = value
+  return Object.freeze(attrs)
+}
+
+/**
+ * Retain only a capped set of property names, in JavaScript's natural key order.
+ *
+ * Object.keys must enumerate the complete object: JS has no bounded own-key API.
+ * The key-list allocation is proportional to object width, unlike indexed array
+ * traversal. Explicit traversal, frame retention, and output are independently capped.
+ *
+ * @param {object} container
+ * @param {string} prefix
+ * @param {number} depth
+ * @param {Set<string>} reasons
+ * @returns {Frame}
+ */
+function createFrame (container, prefix, depth, reasons) {
+  let keys
+  let limit
+  if (Array.isArray(container)) {
+    limit = Math.min(container.length, MAX_LIST_ELEMENTS)
+    if (container.length > limit) reasons.add('max_list_elements')
+  } else {
+    const allKeys = Object.keys(container)
+    if (depth === -1) {
+      const excluded = Object.getOwnPropertyDescriptor(container, 'targetingKey')?.enumerable === true
+      if (allKeys.length - Number(excluded) > MAX_STRUCTURE_PROPERTIES) reasons.add('max_context_fields')
+      keys = allKeys.slice(0, MAX_STRUCTURE_PROPERTIES + 1)
+        .filter(key => key !== 'targetingKey').slice(0, MAX_STRUCTURE_PROPERTIES)
+    } else {
+      if (allKeys.length > MAX_STRUCTURE_PROPERTIES) reasons.add('max_structure_properties')
+      keys = allKeys.slice(0, MAX_STRUCTURE_PROPERTIES)
+    }
+    limit = keys.length
+  }
+  return { container, prefix, depth, keys, index: 0, limit }
+}
+
+/**
+ * Flatten consented context into a frozen, scalar-only snapshot before enqueue.
+ * No getters, proxy traps, iterators, or caller serialization hooks are invoked.
+ * The caller must check capacity and consent before calling this function.
+ *
+ * @param {unknown} context - Caller-owned OpenFeature context
+ * @returns {{ attrs: ContextSnapshot, reasons: Set<string> }}
+ */
+function snapshotEvaluationContext (context) {
+  /** @type {Record<string, ContextScalar>} */
+  const attrs = Object.create(null)
+  const reasons = new Set()
+  if (!isRecord(context)) {
+    if (context !== null && context !== undefined) reasons.add('unsupported_type')
+    return { attrs: Object.freeze(attrs), reasons }
+  }
+
+  const root = /** @type {object} */ (context)
+  const ancestors = new WeakSet([root])
+  const stack = [createFrame(root, '', -1, reasons)]
+  let visited = 0
+  let fields = 0
+
+  while (stack.length > 0) {
+    const frame = /** @type {Frame} */ (stack.at(-1))
+    if (frame.index === frame.limit) {
+      ancestors.delete(frame.container)
+      stack.pop()
+      continue
+    }
+    if (fields === MAX_CONTEXT_FIELDS) {
+      reasons.add('max_context_fields')
+      break
+    }
+    if (visited === MAX_VISITED_NODES) {
+      reasons.add('max_visited_nodes')
+      break
+    }
+    visited++
+    const key = frame.keys ? frame.keys[frame.index++] : String(frame.index++)
+    const prefix = frame.depth === -1 ? key : frame.prefix + '.' + key
+    if (prefix.length > MAX_KEY_LENGTH) {
+      reasons.add('max_key_length')
+      continue
+    }
+    if (normalizeTargetingKey(prefix) === undefined) {
+      reasons.add('invalid_encoding')
+      continue
+    }
+
+    const descriptor = Object.getOwnPropertyDescriptor(frame.container, key)
+    if (!descriptor?.enumerable) continue
+    if (!Object.hasOwn(descriptor, 'value')) {
+      reasons.add('unsupported_type')
+      continue
+    }
+    /** @type {unknown} */
+    let value = descriptor.value
+    if (typeof value === 'string') {
+      if (value.length > MAX_VALUE_LENGTH) {
+        reasons.add('max_value_length')
+        continue
+      }
+      if (normalizeTargetingKey(value) === undefined) {
+        reasons.add('invalid_encoding')
+        continue
+      }
+    } else if (value !== null && typeof value === 'object') {
+      if (isProxy(value)) {
+        reasons.add('unsupported_type')
+        continue
+      }
+      if (isDate(value)) {
+        if (!Number.isFinite(Date.prototype.getTime.call(value))) {
+          reasons.add('unsupported_type')
+          continue
+        }
+        value = Date.prototype.toISOString.call(value)
+      } else {
+        if (!Array.isArray(value) && !isRecord(value)) {
+          reasons.add('unsupported_type')
+          continue
+        }
+        const depth = frame.depth + 1
+        if (depth >= MAX_SNAPSHOT_DEPTH) {
+          reasons.add('max_snapshot_depth')
+          continue
+        }
+        if (ancestors.has(value)) {
+          reasons.add('cycle')
+          continue
+        }
+        ancestors.add(value)
+        stack.push(createFrame(value, prefix, depth, reasons))
+        continue
+      }
+    } else if (
+      value !== null && typeof value !== 'boolean' &&
+      (typeof value !== 'number' || !Number.isFinite(value))
+    ) {
+      reasons.add('unsupported_type')
+      continue
+    }
+
+    if (!Object.hasOwn(attrs, prefix)) fields++
+    attrs[prefix] = /** @type {ContextScalar} */ (value)
+  }
+
+  return { attrs: Object.freeze(attrs), reasons }
+}
+
+module.exports = { snapshotEvaluationContext, validatedContextEntries, snapshotFromEntries, validateContextSnapshot }