@voxgig/sdkgen 4.9.0 → 4.10.0

package/project/.sdk/tm/rb/feature/secrets/voxgig_plugin/config.rb

@@ -0,0 +1,315 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (ruby/lib/voxgig_plugin/config.rb)
+# Source: https://github.com/voxgig/plugin @ 48392f5e2b6d1434ee9b1a4a9a11f4480aaeb46a  [tag: sdk-20260908-1556-0]
+# License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+# frozen_string_literal: true
+
+# The declarative document (section 9): normalization, and the ten-level
+# precedence ladder.
+#
+# TWO FUNCTIONS, AND THE SPLIT BETWEEN THEM IS FORCED.
+#
+# `normalize_config` normalizes STRUCTURE and ENTRY KEYS. It does not
+# merge options, and cannot: section 9.4 makes merge behaviour a property
+# of the definition's option SHAPE, which normalization has never seen. A
+# normalizer that flattened the option layers would make `$MERGE: append`
+# unimplementable at load time, because the layers it must concatenate
+# would already be collapsed.
+#
+# `resolve_options` applies the ladder, and it is the only place that
+# knows the shape.
+
+require_relative 'types'
+require_relative 'ref'
+
+module VoxgigPlugin
+  MERGE_WORDS = %w[replace append].freeze
+
+  def self.normalize_config(input)
+    input ||= {}
+    doc = input['doc'] || {}
+    keys = input['keys'] || {}
+    ikey = keys['instance'] || 'instance'
+    dkey = keys['default'] || 'default'
+    reserved = input['reserved'] || []
+    profile = input['profile']
+
+    # The rename is applied at TWO PLACES AND NO OTHERS: the document
+    # root, and every profile.<name> overlay root (section 9.1). A rename
+    # applied only at the root would leave `profile.prod.sdk`
+    # untranslated and silently drop every environment override the host
+    # depends on. Recursing further would be worse: option data is the
+    # definition's.
+    baseinst = doc[ikey]
+    basedef = doc[dkey] || {}
+
+    overlay = nil
+    overlay = (doc['profile'] || {})[profile] if profile
+    overlay = {} unless overlay.is_a?(Hash)
+    overinst = overlay[ikey]
+    overdef = overlay[dkey] || {}
+
+    # Entry layers, base then overlay, each as {ref -> entry} plus the
+    # order the form implies.
+    base = config_entries(baseinst)
+    over = config_entries(overinst)
+
+    [base[:map].keys, over[:map].keys, basedef.keys, overdef.keys].each do |group|
+      group.each { |r| config_checkreserved(r, reserved) }
+    end
+
+    # A PARTIAL ARRAY IS NOT A FILTER (section 9.1). sdkgen learned this
+    # the hard way: deriving order from a partial array silently dropped
+    # config-activated features. Refs in the base but absent from the
+    # overlay still load, in sorted position AFTER the listed ones. A
+    # profile may also INTRODUCE a ref the base never declared.
+    order = []
+    over[:order].each { |r| order << r unless order.include?(r) }
+    # The remainder keeps the BASE's own order - array position for the
+    # array form, sorted refs for the map form.
+    base[:order].each { |r| order << r unless order.include?(r) }
+
+    instance = {}
+    order.each_with_index do |ref, i|
+      b = base[:map][ref]
+      o = over[:map][ref]
+
+      # MERGE THE ENTRIES AS AUTHORED, THEN APPLY DEFAULTS TO THE RESULT
+      # (section 9.3). A safety rule, not a tidiness one: if the overlay
+      # had its defaults filled in before merging it would carry a
+      # synthesized active:true and overwrite a base's false - silently
+      # re-enabling a deliberately disabled integration in production.
+      active = config_pick(o, 'active', config_pick(b, 'active', true))
+      start = config_pick(o, 'start', config_pick(b, 'start', 'eager'))
+      block = config_pick(o, 'order', config_pick(b, 'order', nil))
+
+      # Option layers, levels 3-6, IN LADDER ORDER. Never merged here.
+      layers = []
+      nm = refname(ref)
+      [basedef[nm], b, overdef[nm], o].each do |src|
+        layers << src['options'] if src.is_a?(Hash) && src.key?('options')
+      end
+
+      ent = { 'pos' => i, 'active' => active, 'start' => start,
+              'optionlayers' => layers }
+      ent['order'] = block unless block.nil?
+      instance[ref] = ent
+    end
+
+    # `default` DECLARES NOTHING (section 9.3). It is a base for every
+    # instance of that definition; it does not create one, and an entry
+    # for a name with no instances is inert rather than an error - which
+    # is what makes a shared library of defaults shippable.
+    defout = {}
+    basedef.each { |n, v| defout[n] = v }
+    overdef.each { |n, v| defout[n] = v }
+
+    { 'instance' => instance, 'order' => order, 'default' => defout }
+  end
+
+  # Both document forms reduce to {ref -> entry} plus the order the form
+  # implies: array POSITION for the array form, sorted refs for the map
+  # form.
+  def self.config_entries(src)
+    out = { map: {}, order: [] }
+    return out if src.nil?
+
+    if src.is_a?(Array)
+      src.each do |item|
+        ref = canon_ref(item['ref'])
+        out[:map][ref] = item
+        out[:order] << ref
+      end
+      return out
+    end
+
+    # Map-form refs arrive as KEYS, through a different path than an
+    # array element's `ref` field - and must canonicalize the same way.
+    src.each_key { |key| out[:map][canon_ref(key)] = src[key] }
+    # Byte-wise, NOT locale-aware and NOT case-folded. All-lowercase refs
+    # sort identically under all three, so only mixed input
+    # discriminates: '@' is 0x40, uppercase 0x41-0x5A, lowercase
+    # 0x61-0x7A. Ruby's String#<=> is bytewise, which is exactly that.
+    out[:order] = out[:map].keys.sort
+    out
+  end
+
+  # Section 9.1: reservation is all-or-nothing per NAME, so the tagged
+  # forms go too. A configuration surface that can disable the thing
+  # reading it is not a surface, it is a trap.
+  def self.config_checkreserved(ref, reserved)
+    return if reserved.empty?
+    return unless reserved.include?(refname(ref))
+
+    fail_with('plugin_ref_reserved', "ref is reserved by the host: #{ref}",
+              { 'ref' => ref })
+  end
+
+  # PRESENCE decides, not truthiness and not nil. A JSON `null` is a
+  # present value in JavaScript (`undefined !== null`), so it must be one
+  # here.
+  def self.config_pick(src, key, dflt)
+    src.is_a?(Hash) && src.key?(key) ? src[key] : dflt
+  end
+
+  # -------------------------------------------------------------------
+  # resolve_options - section 9.3's ten levels, and 9.4's directives
+  # -------------------------------------------------------------------
+
+  def self.resolve_options(input)
+    shape = input['shape'] || {}
+    check_shape(shape)
+
+    ref = canon_ref(input['ref'])
+    name = refname(ref)
+    doc = input['doc'] || {}
+    profile = input['profile']
+
+    overlay = nil
+    overlay = (doc['profile'] || {})[profile] if profile
+    overlay = {} unless overlay.is_a?(Hash)
+
+    # ONE ordered merge, lowest to highest. Levels 3-6 are not two
+    # namespaces collapsed separately and composed afterwards: that
+    # inverts the rule that PROFILE SPECIFICITY OUTRANKS DEFINITION
+    # SPECIFICITY, so a prod per-definition default would lose to a base
+    # instance value.
+    layers = [
+      config_defaultsof(shape),                     # 1
+      input['hostdefaults'],                        # 2
+      config_optsof(doc['default'], name),          # 3
+      config_optsof(doc['instance'], ref),          # 4
+      config_optsof(overlay['default'], name),      # 5
+      config_optsof(overlay['instance'], ref),      # 6
+      input['env'],                                 # 7
+      input['hostoptions'],                         # 8
+      input['loadoptions'],                         # 9
+      input['patch']                                # 10
+    ]
+
+    out = {}
+    layers.each do |layer|
+      next if layer.nil?
+
+      out = config_mergeone(out, layer, shape)
+    end
+    out
+  end
+
+  # The shape's non-directive values are the level-1 defaults.
+  def self.config_defaultsof(shape)
+    out = {}
+    shape.each do |k, v|
+      next if v.is_a?(Hash) && v.key?('$MERGE')
+
+      out[k] = v
+    end
+    out
+  end
+
+  def self.config_optsof(src, key)
+    return nil if src.nil?
+
+    # The array form is equivalent to the map form (section 9.1).
+    if src.is_a?(Array)
+      src.each do |item|
+        return item['options'] if canon_ref(item['ref']) == key
+      end
+      return nil
+    end
+
+    src.each_key do |k|
+      next unless canon_ref(k) == key
+
+      entry = src[k]
+      return entry.is_a?(Hash) ? entry['options'] : nil
+    end
+    nil
+  end
+
+  # Merge ONE layer onto the accumulator, honouring the shape's
+  # directives. The directive holds at EVERY precedence level, not only
+  # between document levels - section 9.4 makes it a property of the
+  # shape, which does not know which layer a value arrived from.
+  def self.config_mergeone(base, over, shape)
+    return base if over.nil?
+    return Util.clone_value(over) unless base.is_a?(Hash) && over.is_a?(Hash)
+
+    out = base.dup
+
+    over.each do |k, o|
+      directive = nil
+      directive = shape[k]['$MERGE'] if shape.is_a?(Hash) && shape[k].is_a?(Hash)
+      b = out[k]
+
+      if directive == 'replace'
+        out[k] = Util.clone_value(o)
+      elsif directive == 'append'
+        bl = b.is_a?(Array) ? b : []
+        ol = o.is_a?(Array) ? o : [o]
+        out[k] = bl + ol
+      elsif directive.is_a?(Hash) && directive.key?('deep')
+        out[k] = config_deepto(b, o, directive['deep'])
+      else
+        # Library default: deep for maps, REPLACE for lists. struct.merge
+        # is element-wise by index, which for option maps is nearly
+        # always wrong - ["a"] over ["x","y","z"] yielding ["a","y","z"]
+        # is the defect station hit on secrets.providers.
+        out[k] = if b.is_a?(Hash) && o.is_a?(Hash)
+                   config_mergeone(b, o, nil)
+                 else
+                   Util.clone_value(o)
+                 end
+      end
+    end
+    out
+  end
+
+  # Merge N levels below this key, replace below that.
+  def self.config_deepto(base, over, n)
+    return Util.clone_value(over) if n <= 0
+    return Util.clone_value(over) unless base.is_a?(Hash) && over.is_a?(Hash)
+
+    out = base.dup
+    over.each { |k, v| out[k] = config_deepto(out[k], v, n - 1) }
+    out
+  end
+
+  # Section 9.4: N is an integer of at least 1, and everything else is an
+  # error.
+  #
+  # `{"deep": 0}` is rejected DESPITE having an obvious reading, because
+  # "replace at this key" already has a spelling and two spellings for
+  # one behaviour is the defect class this repo exists to avoid.
+  def self.check_shape(shape)
+    return unless shape.is_a?(Hash)
+
+    shape.each do |k, v|
+      next unless v.is_a?(Hash) && v.key?('$MERGE')
+
+      directive = v['$MERGE']
+
+      if directive.is_a?(String)
+        next if MERGE_WORDS.include?(directive)
+
+        fail_with('plugin_shape_invalid',
+                  "invalid $MERGE directive at #{k}: #{directive}",
+                  { 'key' => k, 'directive' => directive })
+      end
+
+      if directive.is_a?(Hash) && directive.key?('deep')
+        n = directive['deep']
+        # `true.is_a?(Integer)` is false in ruby, so the boolean case
+        # falls out for free here - unlike python, where it does not.
+        next if n.is_a?(Integer) && n >= 1
+
+        fail_with('plugin_shape_invalid',
+                  "invalid $MERGE deep at #{k}: #{JSON.generate(n)}",
+                  { 'key' => k, 'directive' => directive })
+      end
+
+      fail_with('plugin_shape_invalid',
+                "invalid $MERGE directive at #{k}: #{JSON.generate(directive)}",
+                { 'key' => k, 'directive' => directive })
+    end
+  end
+end

package/project/.sdk/tm/rb/feature/secrets/voxgig_plugin/depend.rb

@@ -0,0 +1,197 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (ruby/lib/voxgig_plugin/depend.rb)
+# Source: https://github.com/voxgig/plugin @ 48392f5e2b6d1434ee9b1a4a9a11f4480aaeb46a  [tag: sdk-20260908-1556-0]
+# License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+# frozen_string_literal: true
+
+# Dependency cardinality, policy, and the restart graph (section 11.3).
+#
+# TWO AXES, BOTH DECLARED BY THE DEFINITION THAT HAS THE REQUIREMENT,
+# because only it knows what it can cope with:
+#
+#                | static (default)          | dynamic
+#   -------------|---------------------------|--------------------------
+#   mandatory    | unmet -> pending;         | unmet -> pending;
+#   (default)    | lost  -> pending,         | lost  -> STAYS LIVE,
+#                |          recursively      |          notified
+#   -------------|---------------------------|--------------------------
+#   optional:true| never gates activation;   | never gates activation;
+#                | a change deactivates and  | a change is a
+#                | reactivates               | notification, nothing else
+#
+# `dynamic` means the plugin has said, IN WRITING, that it can survive
+# its provider being swapped underneath it. It is not the default because
+# most plugins cannot, and the cost of wrongly assuming they can is a
+# live instance holding a dead reference.
+#
+# The rebinding-preference axis is deliberately omitted. OSGi has
+# reluctant vs greedy and it is a knob every author must understand to
+# read anyone else's component; we take always-reluctant. Three axes were
+# more than the model can carry across twenty ports.
+
+require_relative 'types'
+
+module VoxgigPlugin
+  # A bare string is shorthand for `{name}`.
+  def self.normrequire(raw)
+    return { 'name' => raw } if raw.is_a?(String)
+
+    (raw || {}).dup
+  end
+
+  # The requirements a definition declared, normalized.
+  #
+  # BOTH AXES ARE READ AT TWO LEVELS, AND THE PER-REQUIREMENT ONE WINS.
+  #
+  # The instance-level `policy` and `optional` list are how a DOCUMENT
+  # states the axis without editing the definition, and they apply to
+  # every requirement. The per-requirement form is the one section 11.1's
+  # object syntax exists for, and it is strictly more expressive: an
+  # instance that is `static` on its store and `dynamic` on its metrics
+  # cannot be written at all at the instance level.
+  #
+  # `optional` unions rather than overriding - both spellings are
+  # statements that this requirement need not gate activation, and there
+  # is no reading under which one of them means "actually, mandatory".
+  def self.requirements(options)
+    options ||= {}
+    raw = options['requires'] || []
+    marked = options['optional'] || []
+    fallback = options['policy']
+
+    raw.map do |item|
+      req = normrequire(item)
+      req['optional'] = true if req['optional'] || marked.include?(req['name'])
+      req['policy'] = fallback if req['policy'].nil? && !fallback.nil?
+      req
+    end
+  end
+
+  # Does losing this requirement's SELECTED provider restart the
+  # consumer? The mandatory ones under `static`, and the `static`
+  # optional ones - both make a capability change deactivate and
+  # reactivate. `dynamic` never restarts.
+  def self.restartsonloss(req)
+    (req['policy'] || 'static') != 'dynamic'
+  end
+
+  # Does an unmet requirement keep the consumer out of `live`?
+  #
+  # Cardinality alone decides this, NOT policy. `dynamic` is a statement
+  # about surviving a SWAP, not about starting without the thing at all -
+  # a mandatory-dynamic consumer still waits in `pending` for its first
+  # provider.
+  def self.gatesactivation(req)
+    req['optional'] != true
+  end
+
+  # Edges that can cause a restart, which is exactly the set a cycle must
+  # be detected over (section 11.3).
+  #
+  # ONLY `dynamic` OPTIONAL EDGES ARE EXCLUDED, and they are the ones the
+  # exclusion was for: two plugins that optionally and dynamically
+  # consume each other's capabilities both activate happily, neither
+  # gates on the other, and each is merely notified when the other
+  # appears. Nothing restarts, so nothing oscillates.
+  #
+  # An earlier draft of section 11.3 excluded EVERY optional edge and
+  # thereby admitted the non-terminating case it was trying to permit.
+  def self.restartcausing(req)
+    gatesactivation(req) || restartsonloss(req)
+  end
+
+  # A cycle through restart-causing requirements is
+  # `plugin_dependency_cycle`, detected AT LOAD - before anything runs,
+  # because the failure it describes is a non-terminating reconcile and
+  # the only safe time to report that is before it starts.
+  #
+  # The graph is over capabilities, not refs: an edge runs from a
+  # consumer to EVERY node that provides what it needs, because any of
+  # them could be the one selected and a cycle through any is a cycle. A
+  # node also satisfies its own name as a ref (section 11.1), which is
+  # why the ref is a provider of itself here.
+  def self.dependencycycle(nodes)
+    # TWO INDEXES, NOT ONE MERGED MAP. Capability names and refs are
+    # matched differently - a capability by its exact name, a ref through
+    # the canonical spelling (section 4 rule 5) - and one map keyed by
+    # both can only do one of them. Keyed by both and looked up raw, as
+    # this was, a cycle spelled `a$`/`b$` found no providers and EVADED
+    # the load-time check that exists to catch a non-terminating
+    # reconcile.
+    bycap = {}
+    isref = {}
+    nodes.each do |n|
+      isref[n['ref']] = true
+      n['provides'].each do |cap|
+        (bycap[cap] ||= []) << n['ref']
+      end
+    end
+
+    edges = {}
+    nodes.each do |n|
+      out = []
+      n['requires'].each do |req|
+        next unless restartcausing(req)
+
+        from = (bycap[req['name']] || []).dup
+        # A node satisfies its own name AS A REF (section 11.1),
+        # canonically - exactly what `providersof` does at runtime.
+        # `canon` hands back a name no ref could have unchanged, and no
+        # instance ref can equal one, so it is the tolerant test here.
+        asref = VoxgigPlugin.canon(req['name'])
+        from << asref if isref[asref] && !from.include?(asref)
+        from.each do |p|
+          out << p if p != n['ref'] && !out.include?(p)
+        end
+      end
+      edges[n['ref']] = out.sort
+    end
+
+    # Iterative DFS with an explicit stack: twenty ports, and several of
+    # them have no recursion budget worth relying on.
+    white = 0
+    grey = 1
+    black = 2
+    colour = {}
+    nodes.each { |n| colour[n['ref']] = white }
+
+    edges.keys.sort.each do |start|
+      next unless colour[start] == white
+
+      path = [start]
+      stack = [[start, 0]]
+      colour[start] = grey
+
+      until stack.empty?
+        top = stack[-1]
+        if top[1] >= edges[top[0]].length
+          colour[top[0]] = black
+          stack.pop
+          path.pop
+          next
+        end
+        nxt = edges[top[0]][top[1]]
+        top[1] += 1
+        if colour[nxt] == grey
+          # Report the cycle itself, not the walk that found it.
+          return path[path.index(nxt)..] + [nxt]
+        end
+        next if colour[nxt] == black
+
+        colour[nxt] = grey
+        path << nxt
+        stack << [nxt, 0]
+      end
+    end
+    nil
+  end
+
+  # Raise on a cycle, naming it. Separate from the detector so the
+  # detector stays pure and corpus-testable.
+  def self.checkcycle(nodes)
+    cycle = dependencycycle(nodes)
+    return if cycle.nil?
+
+    fail_with('plugin_dependency_cycle',
+              "requirements cycle: #{cycle.join(' -> ')}", { 'cycle' => cycle })
+  end
+end

package/project/.sdk/tm/rb/feature/secrets/voxgig_plugin/env.rb

@@ -0,0 +1,143 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (ruby/lib/voxgig_plugin/env.rb)
+# Source: https://github.com/voxgig/plugin @ 48392f5e2b6d1434ee9b1a4a9a11f4480aaeb46a  [tag: sdk-20260908-1556-0]
+# License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+# frozen_string_literal: true
+
+# Environment overrides (section 9.5) - level 7 of the ladder.
+#
+# One prefix, so nothing drifts: `VOXGIG_PLUGIN_*`.
+#
+#   VOXGIG_PLUGIN_PROFILE            the profile name
+#   VOXGIG_PLUGIN_<REF>_<PATH>       one option
+#   VOXGIG_PLUGIN_ACTIVE/INACTIVE    comma-separated refs, INACTIVE wins
+#
+# THE ENCODING IS LOSSY, AND THIS SAYS SO RATHER THAN PRETENDING
+# OTHERWISE. Ref and path are upper-snake with `$` -> `__` and `.` ->
+# `_`. But `_` is legal in a name and in a tag, and the mapping folds
+# case, so `retry$fast` and `retry__fast` both encode to `RETRY__FAST`.
+#
+# Rather than restrict a grammar the rest of the stack already uses, the
+# host DETECTS THE COLLISION: it encodes every ref it holds, and a key
+# two refs claim is `plugin_env_ambiguous`, naming both.
+
+require 'json'
+require_relative 'types'
+require_relative 'ref'
+
+module VoxgigPlugin
+  ENV_PREFIX = 'VOXGIG_PLUGIN_'
+
+  # `retry$fast` -> `RETRY__FAST`.
+  def self.encode_ref(ref)
+    ref.gsub('$', '__').gsub('.', '_').upcase
+  end
+
+  def self.apply_env(input)
+    input ||= {}
+    env = input['env'] || {}
+    refs = (input['refs'] || []).map { |r| canon_ref(r) }
+    reserved = input['reserved'] || []
+    out = { 'options' => {}, 'active' => [], 'inactive' => [] }
+
+    # Encode every ref the host holds, and refuse a key that two of them
+    # claim. Done up front so the collision is reported even when no
+    # environment variable exercises it - a latent ambiguity is still an
+    # ambiguity, and finding it at deploy time is the failure this exists
+    # to prevent.
+    byencoded = {}
+    refs.each { |r| (byencoded[encode_ref(r)] ||= []) << r }
+    byencoded.keys.sort.each do |e|
+      next unless byencoded[e].length > 1
+
+      pair = byencoded[e].sort
+      fail_with('plugin_env_ambiguous',
+                "refs collide in the environment encoding as #{e}: #{pair.join(', ')}",
+                { 'encoded' => e, 'refs' => pair })
+    end
+
+    # Longest encoded ref first, so `retry$fast` wins over `retry` on
+    # `RETRY__FAST_MIN`. Shortest-first would read the tag as a path.
+    encoded = Util.stable_sort_by(byencoded.keys.sort) { |e| -e.length }
+
+    env.keys.sort.each do |key|
+      next unless key.start_with?(ENV_PREFIX)
+
+      rest = key[ENV_PREFIX.length..]
+
+      if rest == 'PROFILE'
+        out['profile'] = env[key]
+        next
+      end
+
+      if %w[ACTIVE INACTIVE].include?(rest)
+        env_split(env[key]).each do |raw|
+          ref = canon_ref(raw)
+          # The reservation covers EVERY input layer (section 9.1).
+          # VOXGIG_PLUGIN_INACTIVE=station is easier to set than editing
+          # a config file, and INACTIVE has the final word - so guarding
+          # documents alone would leave the one lever this mechanism
+          # exists to deny wide open.
+          env_checkreserved(ref, reserved)
+          out[rest == 'ACTIVE' ? 'active' : 'inactive'] << ref
+        end
+        next
+      end
+
+      enc = encoded.find { |e| rest == e || rest.start_with?("#{e}_") }
+      next if enc.nil?              # not for any ref this host holds
+
+      ref = byencoded[enc][0]
+      env_checkreserved(ref, reserved)
+
+      next if rest == enc           # a ref with no path sets nothing
+
+      path = rest[(enc.length + 1)..].downcase.split('_')
+
+      node = out['options'][ref]
+      unless node.is_a?(Hash)
+        node = {}
+        out['options'][ref] = node
+      end
+      path[0...-1].each do |step|
+        child = node[step]
+        unless child.is_a?(Hash)
+          child = {}
+          node[step] = child
+        end
+        node = child
+      end
+      node[path[-1]] = env_parsevalue(env[key])
+    end
+
+    out
+  end
+
+  def self.env_split(value)
+    value.to_s.split(',').map(&:strip).reject(&:empty?)
+  end
+
+  def self.env_checkreserved(ref, reserved)
+    return if reserved.empty?
+    return unless reserved.include?(refname(ref))
+
+    fail_with('plugin_ref_reserved', "ref is reserved by the host: #{ref}",
+              { 'ref' => ref })
+  end
+
+  # Values parse as JSON, FALLING BACK TO STRING - so `8080` is a number,
+  # `true` is a boolean, `{"a":1}` is a map, and `hello` is the string it
+  # looks like rather than a parse error.
+  #
+  # `quirks_mode` is belt-and-braces for a bare scalar. The json gem
+  # shipped with ruby 3.x (2.x) parses `8080` and `true` at the top level
+  # without it - RFC 7159 admits them - so on any supported ruby this
+  # option changes nothing, and a mutation removing it survives the
+  # corpus. It stays because json 1.x did reject them, and because the
+  # cost of being wrong about that is every environment scalar silently
+  # becoming a string.
+  def self.env_parsevalue(value)
+    JSON.parse(value, quirks_mode: true)
+  rescue StandardError
+    value
+  end
+end