@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/variantProps.ts

@@ -0,0 +1,598 @@
+// The NATIVE component-boundary gate for the R7 variants surface (REQ-API-032 law f):
+// outer shapes refuse AS A UNIT at the supplying render — `variants` a plain object,
+// `inherit` a boolean, a label ARRAY string-only (a non-string member names its index) —
+// and every dictionary entry validates eagerly through core's entry law (shape, member
+// validity, the embedded-transition law, the dynamic-form refusal) PLUS the native depth
+// the R6 gesture gate pins: member drivability (the numeric/color lanes drive numbers and
+// color strings — a core-valid unit string is native-undrivable) and the property-lane
+// option set (an option the lane never reads — e.g. a tree-lane orchestration key — must
+// refuse loud, never ride as a silent no-op; G-INV-8; `velocity` left this class at T21,
+// the lane seeds springs from it). Development throws; production reports once and refuses the
+// offending UNIT — the whole prop for outer shapes, the single ENTRY within a valid
+// dictionary — while the valid remainder survives (the severity law's granularity).
+
+import {
+  describeValue,
+  hostCapabilities,
+  isDiscreteKeyword,
+  ORCHESTRATION_OPTION_KEYS,
+  parseValue,
+  TARGET_PROPERTY_KEYS,
+  InvalidTransitionError,
+  InvalidVariantError,
+  resolveInitialOverlay,
+  resolveVariantDefinition,
+  validateVariantEntrySnapshot,
+  variantsShapeRefusal,
+  type Target,
+  type VariantApplication,
+  type VariantEntry,
+  type VariantResolver,
+  type Transition,
+  type VariantsDictionary,
+} from '@unrulysystems/native-motion-core'
+import {
+  executableLengthValueRefusal,
+  resolveVariantDefinitionResult,
+} from '@unrulysystems/native-motion-core/internal-driver'
+import {
+  isNativeExecutableLengthValue,
+  NATIVE_PROPERTY_TRANSITION_OPTIONS,
+  nativeMountTargetValueKind,
+} from './shippedSurface'
+import {
+  captureBoundedArray,
+  capturedArrayDescription,
+  keyframeTransitionRefusal,
+  resolveTransitionForKey,
+} from '@unrulysystems/native-motion-core/internal-driver'
+import type { StyleValueGate } from './styleValueBinding'
+import type { MotionComponentId } from './motionViewController'
+
+const NATIVE_HOST = hostCapabilities('native', ['universal', 'native-extension'])
+const TRANSITION_MAP_KEYS = new Set<string>(['default', 'layout', ...TARGET_PROPERTY_KEYS])
+
+/** The label (variant) form of a declarative prop: a string, or an array of strings. */
+export function isVariantLabelForm(value: unknown): value is string | readonly string[] {
+  return typeof value === 'string' || Array.isArray(value)
+}
+
+/** The pin's runtime-only direct function form plus its public label form. */
+export function isRuntimeVariantDefinitionForm(
+  value: unknown,
+): value is string | readonly string[] | VariantResolver {
+  return typeof value === 'function' || isVariantLabelForm(value)
+}
+
+/**
+ * Law (g): the target keys a dictionary names — the mount-known data that joins the mounted
+ * key set regardless of which label (if any) is active at mount.
+ */
+export function dictionaryTargetKeys(dictionary: VariantsDictionary | undefined): string[] {
+  if (dictionary === undefined) return []
+  return [
+    ...new Set(
+      Object.values(dictionary).flatMap((entry) =>
+        Object.entries(entry).flatMap(([key, value]) => {
+          if (key === 'transition') return []
+          // T23 B3b: the transitionEnd CARRIER is structural, never an animated key — but its
+          // SUB-keys are mount-registered animated keys (a value must be mounted to jump).
+          if (key === 'transitionEnd') {
+            return typeof value === 'object' && value !== null ? Object.keys(value) : []
+          }
+          return [key]
+        }),
+      ),
+    ),
+  ]
+}
+
+/**
+ * T23 B3b: the EXIT lane is not chartered for settle jumps — T23 B3 charters the
+ * animate-lane jump; an exit jump precedes removal. A carrier on an exit target refuses
+ * loud naming the deferred lane (development throws; production reports and DROPS the
+ * member — sibling exit keys survive). Non-object shapes pass through untouched: the exit
+ * shape gates downstream own those refusals.
+ */
+export function gateExitTransitionEnd(target: Target, gate: StyleValueGate): Target {
+  if (typeof target !== 'object' || target === null || !Object.hasOwn(target, 'transitionEnd')) {
+    return target
+  }
+  const error = new Error(
+    `${gate.componentId}: "exit" carries transitionEnd — the presence exit jump is the exit-jump ` +
+      'successor lane (T23 B3 charters the animate-lane settle jump; an exit jump precedes ' +
+      'removal); the member is refused and sibling exit keys survive.',
+  )
+  if (gate.severity === 'development') throw error
+  gate.report(error)
+  const { transitionEnd: _dropped, ...rest } = target as Record<string, unknown>
+  return rest as Target
+}
+
+/**
+ * Law (f): the native depth ON TOP of core's entry law — every member must be drivable by
+ * the native lanes, and an embedded transition may carry only property-lane options.
+ * RETURN-shaped over the already-validated plain SNAPSHOT (M3 r3 major 5cb2381e272c): no
+ * foreign object is ever re-enumerated here, so no catch or class discriminant exists —
+ * the returned refusal is this boundary's by construction; the caller owns severity.
+ */
+const ORCHESTRATION_KEY_SET: ReadonlySet<string> = new Set(ORCHESTRATION_OPTION_KEYS)
+
+function entryNativeDepthRefusal(
+  label: string,
+  entry: VariantEntry,
+  componentId: MotionComponentId,
+): Error | null {
+  const { transition, ...target } = entry
+  if (transition !== undefined) {
+    const source = transition as Record<PropertyKey, unknown>
+    const hasMap = Reflect.ownKeys(transition).some(
+      (key) => typeof key === 'string' && TRANSITION_MAP_KEYS.has(key),
+    )
+    const refusalForSelected = (selected: Transition, path: string): Error | null => {
+      for (const option of Reflect.ownKeys(selected)) {
+        if (typeof option !== 'string' || TRANSITION_MAP_KEYS.has(option)) continue
+        // T21 (REQ-API-053): root-level orchestration options are TREE-lane vocabulary — the
+        // variant episode consumes them and MotionView strips them before any property-lane
+        // command (L1), so they are consumed, not inert. Core's map-entry law upstream still
+        // refuses them INSIDE per-value entries; this depth check governs the property lane.
+        if (ORCHESTRATION_KEY_SET.has(option)) continue
+        const optionValue = (selected as Record<string, unknown>)[option]
+        if (optionValue === undefined) continue // explicitly-undefined reads as absent (R6 law)
+        if (!NATIVE_PROPERTY_TRANSITION_OPTIONS.has(option)) {
+          return new InvalidTransitionError(
+            componentId,
+            option,
+            optionValue,
+            `${path}.${option} is not executable by the native property lane (it drives: ` +
+              `${NATIVE_PROPERTY_TRANSITION_OPTIONS.options.join(', ')}) — a silently inert ` +
+              'option is refused (G-INV-8, shippedSurface.ts)',
+          )
+        }
+      }
+      return null
+    }
+    if (!hasMap) {
+      const refusal = refusalForSelected(transition, `variants.${label}.transition`)
+      if (refusal !== null) return refusal
+    } else {
+      const selectedKeys = Object.keys(target)
+      const selectors = selectedKeys.length === 0 ? ['__root__'] : selectedKeys
+      const seen = new Set<string>()
+      for (const key of selectors) {
+        const mapKey =
+          TRANSITION_MAP_KEYS.has(key) &&
+          Object.hasOwn(source, key) &&
+          source[key] !== undefined &&
+          source[key] !== null
+            ? key
+            : Object.hasOwn(source, 'default') && source['default'] !== undefined
+              ? 'default'
+              : 'root'
+        if (seen.has(mapKey)) continue
+        seen.add(mapKey)
+        const selected = resolveTransitionForKey(transition, key)
+        const refusal = refusalForSelected(selected, `variants.${label}.transition.${mapKey}`)
+        if (refusal !== null) return refusal
+      }
+    }
+  }
+  for (const [memberKey, memberValue] of Object.entries(target)) {
+    // T23 B3b: the transitionEnd carrier passes whole — core deep-validated each sub-value
+    // (family + path-named diagnostics, B3a), and the controller's jump lane re-gates native
+    // executability at jump time (applyTransitionEnd). It is structural, not a drivable member.
+    if (memberKey === 'transitionEnd') continue
+    const valueKind = nativeMountTargetValueKind(memberKey)
+    // Both lanes drive a scalar OR a keyframe ARRAY (REQ-API-033 on variants, majors 31 + 35): core
+    // validation already proved a well-formed same-value-type array, and the array-aware controller
+    // drives it — the color lane through the progress projection (projectColorSequence), the numeric
+    // lane directly. Positional length strings share the controller's measure/defer lane — checked
+    // ELEMENT-WISE through the ONE key-aware executable matrix (review 91d41675d511): a scalar or
+    // array element outside it refuses eagerly here, never latently at selection.
+    const lengthRefusal =
+      valueKind === 'color' || valueKind === 'discrete'
+        ? null
+        : executableLengthValueRefusal(memberKey, memberValue)
+    // The discrete lane (T23 B2b) drives a SINGLE keyword of the discrete FAMILY — the
+    // controller's own triple guard (isDiscreteKeyword pre-guards the parse; the family verdict
+    // refuses 'auto'/named colors); keyframe arrays are not chartered for discrete keys.
+    const drivable =
+      valueKind === 'color'
+        ? typeof memberValue === 'string' || Array.isArray(memberValue)
+        : valueKind === 'discrete'
+          ? typeof memberValue === 'string' &&
+            isDiscreteKeyword(memberValue) &&
+            parseValue(memberValue).kind === 'discrete'
+          : isNativeExecutableLengthValue(memberKey, memberValue)
+    if (!drivable) {
+      return new InvalidVariantError(
+        label,
+        entry,
+        `${componentId}: variants.${label}.${memberKey} received ${describeValue(memberValue)} — ${
+          lengthRefusal ??
+          `the native ${valueKind} lane drives ${
+            valueKind === 'color'
+              ? 'color strings or a color keyframe array'
+              : valueKind === 'discrete'
+                ? 'a single CSS keyword string (keyframe arrays are not chartered for discrete keys)'
+                : 'numbers, numeric keyframe arrays, or measure-resolved positional lengths'
+          }; the supplied value is not executable by the native property lane (REQ-API-032 law f)`
+        }`,
+      )
+    }
+    // R8-F1 at the SUPPLYING boundary (review major 42): a keyframe array member under an EMBEDDED
+    // spring interpolates exactly two keyframes — a longer array refuses the ENTRY EAGERLY here (an
+    // invalid entry can never sit latent until selection, the R7 law) instead of an uncaught controller
+    // throw. An array with NO embedded spring rides the controller's own severity-aware compat filter.
+    // R8 M2-B (REQ-API-033 law d): validate this variant's EMBEDDED keyframe timing eagerly (the
+    // R7 no-latent law). Exact-count `times` override even offsets; other shape-valid counts fall
+    // back as a whole. Per-segment easing lists allow missing/extra entries; scalar consumers still
+    // refuse keyframe-only timing as inert.
+    const timingRefusal = keyframeTransitionRefusal(
+      `variants.${label}`,
+      memberKey,
+      memberValue,
+      transition === undefined ? undefined : resolveTransitionForKey(transition, memberKey),
+    )
+    if (timingRefusal !== null) return new InvalidVariantError(label, entry, timingRefusal.message)
+  }
+  return null
+}
+
+// A dictionary entry with no embedded transition inherits the element transition when a label selects
+// it. That fallback is an effective per-property consumer, not an optional later detail: timing or a
+// spring keyframe cardinality it cannot execute must be refused before the resolver/controller sees it.
+// Core and the existing native-depth gate retain their entry-unit law for embedded transitions. The
+// inherited case is per-property under production severity, matching every other fallback supplier:
+// an incompatible key is absent while a valid sibling remains executable.
+export function gateVariantApplicationFallback(
+  application: VariantApplication,
+  elementTransition: Transition | undefined,
+  gate: StyleValueGate,
+  componentId: MotionComponentId = '<Motion.View>',
+): VariantApplication {
+  if (application.transition !== undefined || elementTransition === undefined) return application
+  const accepted = Object.create(null) as Record<string, unknown>
+  for (const [key, value] of Object.entries(application.target)) {
+    const timingRefusal = keyframeTransitionRefusal(
+      componentId,
+      key,
+      value,
+      resolveTransitionForKey(elementTransition, key),
+    )
+    if (timingRefusal !== null) {
+      if (gate.severity === 'development') throw timingRefusal
+      gate.report(timingRefusal)
+      continue
+    }
+    accepted[key] = value
+  }
+  return { target: accepted as VariantEntry, transition: undefined }
+}
+
+/** Only concrete timing consumers (animate/exit) inherit the element transition. */
+export function gateVariantApplicationFallbacks(
+  applications: readonly VariantApplication[],
+  elementTransition: Transition | undefined,
+  gate: StyleValueGate,
+  componentId: MotionComponentId = '<Motion.View>',
+): readonly VariantApplication[] {
+  return gateVariantApplicationFallbacksWithEvidence(
+    applications,
+    elementTransition,
+    gate,
+    componentId,
+  ).applications
+}
+
+/**
+ * The accepted projection alone cannot say whether a fallback property was attempted: production may
+ * have removed every such key. Keep that evidence beside the same resolved applications so the
+ * element-transition owner decision distinguishes a genuinely inert transition from one already refused.
+ */
+export function gateVariantApplicationFallbacksWithEvidence(
+  applications: readonly VariantApplication[],
+  elementTransition: Transition | undefined,
+  gate: StyleValueGate,
+  componentId: MotionComponentId = '<Motion.View>',
+): {
+  readonly applications: readonly VariantApplication[]
+  readonly fallbackAttempted: boolean
+} {
+  const fallbackAttempted =
+    elementTransition !== undefined &&
+    applications.some(
+      (application) =>
+        application.transition === undefined && Object.keys(application.target).length > 0,
+    )
+  return {
+    applications: applications.map((application) =>
+      gateVariantApplicationFallback(application, elementTransition, gate, componentId),
+    ),
+    fallbackAttempted,
+  }
+}
+
+/**
+ * The dictionary gate: outer shape as a unit, then EVERY entry eagerly (an invalid entry
+ * can never sit latent until selection). Returns the SANITIZED dictionary — in production
+ * an offending entry is DROPPED (reported once) and the valid remainder survives; a
+ * malformed outer shape refuses the whole prop to `undefined`.
+ */
+export function gateVariantsDictionary(
+  variants: unknown,
+  gate: StyleValueGate,
+  componentId: MotionComponentId = '<Motion.View>',
+): VariantsDictionary | undefined {
+  if (variants === undefined) return undefined
+  // RETURN-shaped refusals, no catch (M3 r3 majors 1b53e9337aec/13af48a64530/5cb2381e272c):
+  // the shape probe and the entry READ phase run foreign traps UNGUARDED — their faults
+  // (including authentic same-class sentinels) propagate untouched by construction. A
+  // returned refusal is boundary-made; severity applies only to those.
+  const shapeRefusal = variantsShapeRefusal(variants)
+  if (shapeRefusal !== null) {
+    const ownedRefusal = new InvalidVariantError(
+      '(variants)',
+      variants,
+      `${componentId}: ${shapeRefusal.message}`,
+      shapeRefusal,
+    )
+    if (gate.severity === 'development') throw ownedRefusal
+    gate.report(ownedRefusal)
+    return undefined
+  }
+  // Null-prototype accumulator (M2 r1 major 11): a valid own '__proto__' label must land as
+  // an OWN property — plain-object assignment would invoke the legacy prototype setter and
+  // silently turn the label into a local miss (and pollute the accumulator's prototype).
+  const accepted: Record<string, VariantEntry | VariantResolver> = Object.create(null) as Record<
+    string,
+    VariantEntry | VariantResolver
+  >
+  for (const [label, entry] of Object.entries(variants as Record<string, unknown>)) {
+    const { refusal, entry: snapshot } = validateVariantEntrySnapshot(label, entry, NATIVE_HOST, {
+      componentId,
+    })
+    // T24 B2: a RESOLVER entry mounts by identity, uninvoked — its keys do not exist until
+    // resolution, so BOTH the core entry law and the native depth law apply to its RESULT
+    // inside resolveVariantApplicationsGated, never here.
+    if (typeof snapshot === 'function') {
+      accepted[label] = snapshot
+      continue
+    }
+    // Production: the ENTRY is the refusal unit within a valid dictionary (law f).
+    const nativeRefusal = refusal ?? entryNativeDepthRefusal(label, snapshot!, componentId)
+    if (nativeRefusal !== null) {
+      if (gate.severity === 'development') throw nativeRefusal
+      gate.report(nativeRefusal)
+      continue
+    }
+    // The SNAPSHOT is what mounts (one read, one truth): a stateful proxy cannot show the
+    // validators one value and the engine another.
+    accepted[label] = snapshot!
+  }
+  return accepted
+}
+
+// The fallback state for a value-less/pre-mount native site. Mounted hosts supply their
+// controller's fresh live-state reader at each resolver arm.
+const EMPTY_CURRENT: Readonly<Record<string, unknown>> = Object.freeze({})
+const EMPTY_VELOCITY: Readonly<Record<string, number>> = Object.freeze({})
+const EMPTY_VALUE_STATE = Object.freeze({ current: EMPTY_CURRENT, velocity: EMPTY_VELOCITY })
+
+/**
+ * T24 B2: THE native resolution seam — every native site resolves labels through this
+ * gate, never bare `resolveVariantDefinition`. Static labels are the pinned static law
+ * unchanged. A RESOLVER label resolves through the core seam (unguarded invocation — user
+ * faults propagate untouched; typed refusals for the two-step bound and the core entry
+ * law) and its RESULT then rides the SAME native depth law a static entry rides at the
+ * boundary. Severity granularity is the LABEL: development throws; production reports once
+ * and skips the offending label while the remainder survives.
+ */
+export function resolveVariantApplicationsGated(
+  definition: string | readonly string[] | VariantResolver,
+  dictionary: VariantsDictionary | undefined,
+  gate: StyleValueGate,
+  componentId: MotionComponentId,
+  custom?: unknown,
+  readValueState: () => {
+    readonly current: Readonly<Record<string, unknown>>
+    readonly velocity: Readonly<Record<string, number>>
+  } = () => EMPTY_VALUE_STATE,
+): readonly VariantApplication[] {
+  if (typeof definition === 'function') {
+    const resolution = resolveVariantDefinitionResult(definition, dictionary, {
+      custom,
+      readValueState,
+      host: NATIVE_HOST,
+      componentId,
+    })
+    if (resolution.refusal !== null) {
+      if (gate.severity === 'development') throw resolution.refusal
+      gate.report(resolution.refusal)
+      return []
+    }
+    return resolution.applications.filter((application) => {
+      const producedEntry = {
+        ...application.target,
+        ...(application.transition === undefined ? {} : { transition: application.transition }),
+      } as VariantEntry
+      const refusal = entryNativeDepthRefusal('(definition)', producedEntry, componentId)
+      if (refusal === null) return true
+      if (gate.severity === 'development') throw refusal
+      gate.report(refusal)
+      return false
+    })
+  }
+  const labels = typeof definition === 'string' ? [definition] : definition
+  const applications: VariantApplication[] = []
+  for (const label of labels) {
+    if (dictionary === undefined || !Object.hasOwn(dictionary, label)) continue
+    if (typeof dictionary[label] !== 'function') {
+      // Static entries cannot refuse here (validated at the boundary) — the bare core
+      // resolution is the single static law.
+      for (const application of resolveVariantDefinition(label, dictionary)) {
+        applications.push(application)
+      }
+      continue
+    }
+    const resolution = resolveVariantDefinitionResult(label, dictionary, {
+      custom,
+      readValueState,
+      host: NATIVE_HOST,
+      componentId,
+    })
+    if (resolution.refusal !== null) {
+      if (gate.severity === 'development') throw resolution.refusal
+      gate.report(resolution.refusal)
+      continue
+    }
+    for (const application of resolution.applications) {
+      // The produced entry rides the SAME native depth law a static entry rides.
+      const producedEntry = {
+        ...application.target,
+        ...(application.transition === undefined ? {} : { transition: application.transition }),
+      } as VariantEntry
+      const depthRefusal = entryNativeDepthRefusal(label, producedEntry, componentId)
+      if (depthRefusal !== null) {
+        if (gate.severity === 'development') throw depthRefusal
+        gate.report(depthRefusal)
+        continue
+      }
+      applications.push(application)
+    }
+  }
+  return applications
+}
+
+/**
+ * T24 B1: law (c) through the gated seam — the synchronous initial overlay with RESOLVER
+ * labels admitted. Composes core `resolveInitialOverlay` PER LABEL (the overlay law is an
+ * ordered per-application assign, so per-label calls compose identically) so severity keeps
+ * the LABEL granularity: development throws, production reports and skips the offending
+ * label while the remainder overlays. Static-only definitions behave byte-identically to
+ * the bare core overlay.
+ */
+export function resolveInitialOverlayGated(
+  definition: string | readonly string[] | VariantResolver,
+  dictionary: VariantsDictionary | undefined,
+  gate: StyleValueGate,
+  componentId: MotionComponentId,
+  custom?: unknown,
+  readValueState?: () => {
+    readonly current: Readonly<Record<string, unknown>>
+    readonly velocity: Readonly<Record<string, number>>
+  },
+): Target {
+  if (typeof definition === 'function') {
+    const overlay: Record<string, unknown> = {}
+    for (const application of resolveVariantApplicationsGated(
+      definition,
+      dictionary,
+      gate,
+      componentId,
+      custom,
+      readValueState,
+    )) {
+      const { transitionEnd: carrier, ...plain } = application.target as Record<string, unknown>
+      Object.assign(overlay, plain)
+      if (typeof carrier === 'object' && carrier !== null && !Array.isArray(carrier)) {
+        Object.assign(overlay, carrier)
+      }
+    }
+    return overlay as Target
+  }
+  const labels = typeof definition === 'string' ? [definition] : definition
+  const overlay: Record<string, unknown> = {}
+  for (const label of labels) {
+    if (dictionary === undefined || !Object.hasOwn(dictionary, label)) continue
+    if (typeof dictionary[label] !== 'function') {
+      // Static labels: the bare core overlay is the single law (boundary-validated entries).
+      Object.assign(overlay, resolveInitialOverlay(label, dictionary))
+      continue
+    }
+    // Resolver labels resolve through the ONE depth-checked seam, then law (c) applies on
+    // top: targets assign in order, transitions discarded, the transitionEnd carrier folds
+    // instantly over its own target keys (T23 B3c) and never rides the overlay itself.
+    for (const application of resolveVariantApplicationsGated(
+      label,
+      dictionary,
+      gate,
+      componentId,
+      custom,
+      readValueState,
+    )) {
+      const { transitionEnd: carrier, ...plain } = application.target as Record<string, unknown>
+      Object.assign(overlay, plain)
+      if (typeof carrier === 'object' && carrier !== null && !Array.isArray(carrier)) {
+        Object.assign(overlay, carrier)
+      }
+    }
+  }
+  return overlay as Target
+}
+
+/** Law (f): `inherit` is a boolean; anything else refuses naming the contract. */
+export function gateInheritProp(
+  inherit: unknown,
+  gate: StyleValueGate,
+  componentId: MotionComponentId = '<Motion.View>',
+): boolean | undefined {
+  if (inherit === undefined || typeof inherit === 'boolean') return inherit
+  // describeValue, never JSON.stringify (M3 r2 major 0a96290934e2): the same formatter law
+  // the label gate learned — a BigInt crashes the serializer with zero reports.
+  const error = new Error(
+    `${componentId}: "inherit" must be a boolean — received ${describeValue(inherit)} (REQ-API-032 law f; ` +
+      'the pinned visual-state switch takes true/false only)',
+  )
+  if (gate.severity === 'development') throw error
+  gate.report(error)
+  return undefined
+}
+
+/**
+ * Law (f): normalize a label definition to the ordered label list. A string is one label;
+ * an ARRAY must be string-only — a non-string member refuses naming the prop and its index,
+ * and production refuses the whole PROP (the outer-shape unit).
+ */
+export function gateLabelDefinition(
+  prop: string,
+  definition: string | readonly unknown[],
+  gate: StyleValueGate,
+  componentId: MotionComponentId = '<Motion.View>',
+): readonly string[] | undefined {
+  if (typeof definition === 'string') return [definition]
+  const capturedDefinition = captureBoundedArray(definition)
+  if (capturedDefinition.kind !== 'captured') {
+    const error = new Error(
+      `${componentId}: "${prop}" label array must have a safe length — received ${capturedArrayDescription(capturedDefinition)} ` +
+        '(REQ-API-032 law f)',
+    )
+    if (gate.severity === 'development') throw error
+    gate.report(error)
+    return undefined
+  }
+  const length = capturedDefinition.values.length
+  const captured: string[] = []
+  captured.length = length
+  for (let index = 0; index < length; index++) {
+    const member = Object.hasOwn(capturedDefinition.values, index)
+      ? capturedDefinition.values[index]
+      : undefined
+    if (typeof member === 'string') {
+      captured[index] = member
+      continue
+    }
+    // describeValue, never JSON.stringify (M3 r1 major cdc42f01c118): a BigInt member
+    // would crash the FORMATTER itself — a raw serialize TypeError replacing the typed
+    // law-(f) refusal in development and escaping unreported in production.
+    const error = new Error(
+      `${componentId}: "${prop}" label array member at index ${index} must be a string — received ` +
+        `${describeValue(member)} (REQ-API-032 law f; the label array is ` +
+        'string-only)',
+    )
+    if (gate.severity === 'development') throw error
+    gate.report(error)
+    return undefined
+  }
+  return Object.freeze(captured)
+}