@voxgig/sdkgen 4.8.3 → 4.10.0

package/project/.sdk/tm/elixir/lib/projectname/feature/secrets/plugin/inst.ex

@@ -0,0 +1,139 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (elixir/lib/voxgig_plugin/inst.ex)
+# 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.
+defmodule Voxgig.Plugin.Inst do
+  @moduledoc """
+  What a definition's callbacks see. Deliberately not the internal record:
+  a plugin that could reach `status` could also write it.
+
+  THE INSTANCE IS A HANDLE, NOT A COPY - `%Inst{host:, ref:}` and nothing
+  else. Every accessor reads the entry back out of the host, so a callback
+  always sees current values and there is no snapshot to keep in sync.
+  That is the whole of this port's answer to the canonical's "REFILL
+  rather than REBIND" (section 9.6): the canonical must empty and refill
+  the options map because a definition closes over the object it was
+  handed at `define`; here there is no such object, so `apply` simply
+  replaces the entry's options and the next `options/1` reads them.
+  """
+
+  alias Voxgig.Plugin.Host
+  alias Voxgig.Plugin.Ref
+  alias Voxgig.Plugin.Types
+
+  defstruct [:host, :ref]
+
+  def ref(%__MODULE__{ref: ref}), do: ref
+
+  def name(%__MODULE__{ref: ref}), do: Ref.parse_ref(ref)["name"]
+
+  def tag(%__MODULE__{ref: ref}), do: Ref.parse_ref(ref)["tag"]
+
+  def host(%__MODULE__{host: host}), do: host
+
+  def options(%__MODULE__{host: host, ref: ref}), do: Host.field(host, ref, "options")
+
+  def state(%__MODULE__{host: host, ref: ref}), do: Host.field(host, ref, "state")
+
+  @doc """
+  The state map is a VALUE here, so a callback cannot mutate what it reads;
+  these two are the writes. Every other port spells them `i.state[k] = v`
+  because its maps are objects.
+  """
+  def state_put(%__MODULE__{host: host, ref: ref}, key, value) do
+    Host.entry_update(host, ref, &Map.put(&1, "state", Map.put(&1["state"], key, value)))
+  end
+
+  def state_update(%__MODULE__{} = inst, key, dflt, fun) do
+    state_put(inst, key, fun.(Types.get(state(inst), key) || dflt))
+  end
+
+  @doc """
+  Foreign resources the host did not hand out are registered explicitly
+  (section 8.3); host calls are recorded automatically.
+
+  SYMMETRIC WITH `acquire`, and it has to be: `open` counts the resources
+  CURRENTLY HELD, so an entry that is registered and then unwound must
+  leave the count where it found it.
+  """
+  def release(%__MODULE__{host: host, ref: ref}, fun) do
+    # Section 8.3: "`inst.release` outside `activate` is
+    # `plugin_release_scope`". A scope entry registered in `define` is
+    # never unwound, so "in a transition" is not the test - the PHASE is.
+    Host.scope_push(host, ref, fun, "release called outside activate")
+  end
+
+  @doc """
+  The synthetic counter the driver owns, so "what is open" is data rather
+  than an assertion each port words differently.
+
+  Returns its own release, so a plugin can hand one back early. The scope
+  still holds the entry and unwinding it twice is a no-op - releasing early
+  must not make teardown wrong.
+  """
+  def acquire(%__MODULE__{host: host, ref: ref}) do
+    Host.scope_push(host, ref, nil, "acquire called outside activate")
+  end
+
+  @doc """
+  Bind into a host point. Declared in `define`; the host inserts it only
+  after `activate` returns successfully (section 8.1), which is why a
+  failing activate leaves no live binding behind.
+
+  Section 12 has carried `plugin_bind_scope` - "binding declared outside
+  `define`" - since before anything raised it, and it was the half nobody
+  wrote: a binding added from `activate` went live without being part of
+  the loaded definition, and a deactivate/activate cycle appended it again.
+  """
+  def bind(%__MODULE__{host: host, ref: ref}, point, fun, band \\ nil) do
+    if "define" != Host.phase(host) do
+      Types.fail("plugin_bind_scope", "bind called outside define: #{point}",
+                 %{"ref" => ref, "point" => point})
+    end
+
+    if not Host.point?(host, point) do
+      Types.fail("plugin_point_unknown", "no such point: #{point}", %{"point" => point})
+    end
+
+    Host.entry_update(host, ref, fn e ->
+      Map.put(e, "bindings",
+              e["bindings"] ++ [%{ref: ref, point: point, fn: fun, band: band || 0}])
+    end)
+  end
+
+  @doc "Published for other plugins and for the application (section 11)."
+  def export(%__MODULE__{host: host, ref: ref}, key, value) do
+    Host.entry_update(host, ref, &Map.put(&1, "exports", Map.put(&1["exports"], key, value)))
+  end
+
+  @doc "What this instance can do for others (section 11.1)."
+  def provides(%__MODULE__{host: host, ref: ref}, prov) do
+    Host.entry_update(host, ref, &Map.put(&1, "provides", &1["provides"] ++ [prov]))
+  end
+
+  @doc """
+  Where this binding landed (section 6.6) - the plugin-side counterpart to
+  a host pin. THE HOST DOES NOT POLICE THIS; it just makes the fact
+  available. Verification tells a plugin it was misplaced; a pin (section
+  7) stops the misplacement from being expressible at all. The two are not
+  substitutes.
+  """
+  def position(%__MODULE__{host: host, ref: ref}, point), do: Host.positionof(host, ref, point)
+
+  @doc """
+  AN INSTANCE MAY ITSELF BE A HOST (section 6.5), and THE OUTER ONE OWNS
+  THE INNER ONE'S LIFETIME. Registering the teardown in the instance scope
+  is what makes that true rather than aspirational.
+  """
+  def nest(%__MODULE__{host: host, ref: ref}, nestopts \\ nil) do
+    if not Host.intransition?(host) do
+      Types.fail("plugin_release_scope", "nest called outside a lifecycle callback")
+    end
+
+    inner = Host.make_host(nestopts)
+    # NOT through `scope_push`: a nested host is not a counted resource,
+    # and `open` must read the same before and after one is created.
+    Host.scope_uncounted(host, ref, fn -> Host.close(inner) end)
+    Host.entry_update(host, ref, &Map.put(&1, "inner", inner))
+    inner
+  end
+end

package/project/.sdk/tm/elixir/lib/projectname/feature/secrets/plugin/json.ex

@@ -0,0 +1,132 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (elixir/lib/voxgig_plugin/json.ex)
+# 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.
+defmodule Voxgig.Plugin.Json do
+  @moduledoc """
+  The JSON parser, and the only one this port has.
+
+  NO JASON, NO POISON (section 16). The library is allowed exactly one
+  runtime dependency, `voxgig/struct`, which has no elixir port; everything
+  else is the standard library. Parsing the corpus is a hundred and fifty
+  lines, and a hundred and fifty lines is cheaper than a hex dependency
+  every embedding host inherits - and it keeps this port free of a
+  `mix.exs` deps list entirely.
+  """
+
+  alias Voxgig.Plugin.Types
+
+  @doc "Parse a JSON document. Raises on malformed input."
+  def parse(text) do
+    {value, rest} = value(skipws(text))
+
+    case skipws(rest) do
+      "" -> value
+      trailing -> raise ArgumentError, "trailing input: #{String.slice(trailing, 0, 20)}"
+    end
+  end
+
+  defdelegate encode(value), to: Types
+
+  defp skipws(<<c, rest::binary>>) when c in [?\s, ?\t, ?\n, ?\r], do: skipws(rest)
+  defp skipws(text), do: text
+
+  defp value("{" <> rest), do: map(skipws(rest), %{})
+  defp value("[" <> rest), do: list(skipws(rest), [])
+  defp value("\"" <> _ = text), do: string(text)
+  defp value("true" <> rest), do: {true, rest}
+  defp value("false" <> rest), do: {false, rest}
+  defp value("null" <> rest), do: {nil, rest}
+  defp value(text), do: number(text)
+
+  defp map("}" <> rest, acc), do: {acc, rest}
+
+  defp map(text, acc) do
+    {key, rest} = string(skipws(text))
+
+    rest =
+      case skipws(rest) do
+        ":" <> more -> more
+        other -> raise ArgumentError, "expected ':' at #{String.slice(other, 0, 20)}"
+      end
+
+    {v, rest} = value(skipws(rest))
+
+    case skipws(rest) do
+      "," <> more -> map(skipws(more), Map.put(acc, key, v))
+      "}" <> more -> {Map.put(acc, key, v), more}
+      other -> raise ArgumentError, "expected ',' or '}' at #{String.slice(other, 0, 20)}"
+    end
+  end
+
+  defp list("]" <> rest, acc), do: {Enum.reverse(acc), rest}
+
+  defp list(text, acc) do
+    {v, rest} = value(skipws(text))
+
+    case skipws(rest) do
+      "," <> more -> list(skipws(more), [v | acc])
+      "]" <> more -> {Enum.reverse([v | acc]), more}
+      other -> raise ArgumentError, "expected ',' or ']' at #{String.slice(other, 0, 20)}"
+    end
+  end
+
+  defp string("\"" <> rest), do: chars(rest, [])
+  defp string(other), do: raise(ArgumentError, "expected a string at #{String.slice(other, 0, 20)}")
+
+  defp chars("\"" <> rest, acc), do: {acc |> Enum.reverse() |> IO.iodata_to_binary(), rest}
+  defp chars("\\\"" <> rest, acc), do: chars(rest, ["\"" | acc])
+  defp chars("\\\\" <> rest, acc), do: chars(rest, ["\\" | acc])
+  defp chars("\\/" <> rest, acc), do: chars(rest, ["/" | acc])
+  defp chars("\\b" <> rest, acc), do: chars(rest, ["\b" | acc])
+  defp chars("\\f" <> rest, acc), do: chars(rest, ["\f" | acc])
+  defp chars("\\n" <> rest, acc), do: chars(rest, ["\n" | acc])
+  defp chars("\\r" <> rest, acc), do: chars(rest, ["\r" | acc])
+  defp chars("\\t" <> rest, acc), do: chars(rest, ["\t" | acc])
+
+  defp chars("\\u" <> <<hex::binary-size(4), rest::binary>>, acc) do
+    code = String.to_integer(hex, 16)
+
+    # A surrogate PAIR is two escapes, and elixir strings are UTF-8 - so
+    # the halves are joined here rather than appended as they arrive.
+    case {code, rest} do
+      {c, "\\u" <> <<low::binary-size(4), more::binary>>} when c >= 0xD800 and c < 0xDC00 ->
+        lowcode = String.to_integer(low, 16)
+
+        if lowcode >= 0xDC00 and lowcode < 0xE000 do
+          joined = 0x10000 + (c - 0xD800) * 0x400 + (lowcode - 0xDC00)
+          chars(more, [<<joined::utf8>> | acc])
+        else
+          chars(rest, [<<c::utf8>> | acc])
+        end
+
+      _ ->
+        chars(rest, [<<code::utf8>> | acc])
+    end
+  end
+
+  defp chars(<<c::utf8, rest::binary>>, acc), do: chars(rest, [<<c::utf8>> | acc])
+  defp chars("", _), do: raise(ArgumentError, "unterminated string")
+
+  defp number(text) do
+    {digits, rest} = numchars(text, [])
+    body = digits |> Enum.reverse() |> IO.iodata_to_binary()
+
+    cond do
+      "" == body ->
+        raise ArgumentError, "unexpected input at #{String.slice(text, 0, 20)}"
+
+      String.contains?(body, [".", "e", "E"]) ->
+        {String.to_float(body), rest}
+
+      true ->
+        {String.to_integer(body), rest}
+    end
+  end
+
+  defp numchars(<<c, rest::binary>>, acc)
+       when c in ?0..?9 or c in [?-, ?+, ?., ?e, ?E] do
+    numchars(rest, [<<c>> | acc])
+  end
+
+  defp numchars(text, acc), do: {acc, text}
+end

package/project/.sdk/tm/elixir/lib/projectname/feature/secrets/plugin/order.ex

@@ -0,0 +1,179 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (elixir/lib/voxgig_plugin/order.ex)
+# 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.
+defmodule Voxgig.Plugin.Order do
+  @moduledoc """
+  Ordering (section 7) - one rule, one place.
+
+  sdkgen grew two special cases in `makeOptions` (`test`, then `station`)
+  and the third was not far off. This sort is the whole replacement, and
+  the tiers are in this order for a reason:
+
+    1 constraints   before/after edges, by ref or by name
+    2 bands         integer, lower first, default 0
+    3 declaration   ties break by `pos`
+
+  CONSTRAINTS BEAT BANDS precisely so the correct tool wins when both are
+  present. A band expresses a genuine cross-cutting layer; a constraint
+  expresses a relationship between two specific things; and a band chosen
+  by trial and error to fix an ordering bug is a bug wearing a number.
+  """
+
+  alias Voxgig.Plugin.Ref
+  alias Voxgig.Plugin.Types
+
+  @doc """
+  An integer, and only an integer: `true` and `"2"` are not bands, and
+  elixir's `is_integer` excludes both.
+  """
+  def order_band(binding) do
+    Types.asint(Types.get(binding.order || %{}, "band")) || 0
+  end
+
+  @doc """
+  Was a constraint stated? An absent value and an EMPTY LIST are both
+  no-constraint - and an empty list is TRUTHY in most languages, which is
+  exactly how this class of bug survives a reading.
+  """
+  def order_declared(nil), do: false
+  def order_declared(spec) when is_list(spec), do: Enum.any?(spec, &("" != &1))
+  def order_declared(spec), do: "" != spec
+
+  @doc """
+  One spelling or a LIST of them. A list fans out to the UNION of what each
+  names, so after: ['a','b'] means after BOTH, and the same instance named
+  twice - once by name, once by ref - is one edge.
+  """
+  def order_targets(spec, nodes) do
+    specs = if is_list(spec), do: spec, else: [spec]
+
+    specs
+    |> Enum.flat_map(fn one ->
+      nodes
+      |> Enum.filter(fn b -> b.ref == one or Ref.refname(b.ref) == one end)
+      |> Enum.map(& &1.ref)
+    end)
+    |> Enum.uniq()
+  end
+
+  @doc """
+  `bindings` is a list of `%{ref:, pos:, order:}` - an internal shape,
+  never a corpus value.
+  """
+  def resolve_order(bindings, pin \\ nil) do
+    byref = Map.new(bindings, fn b -> {b.ref, b} end)
+
+    # Constraints are edges. A constraint naming an ABSENT binding is
+    # satisfied VACUOUSLY (section 7) - a plugin ordered `after: 'test'`
+    # must load in a host with no test plugin. That is sdkgen's __after__
+    # behaviour, kept.
+    edges =
+      Enum.reduce(bindings, Map.new(bindings, fn b -> {b.ref, []} end), fn b, acc ->
+        block = if is_map(b.order), do: b.order, else: %{}
+
+        acc =
+          if order_declared(Types.get(block, "after")) do
+            Enum.reduce(order_targets(Types.get(block, "after"), bindings), acc, fn t, a ->
+              Map.update!(a, t, &(&1 ++ [b.ref]))
+            end)
+          else
+            acc
+          end
+
+        if order_declared(Types.get(block, "before")) do
+          Map.update!(acc, b.ref, &(&1 ++ order_targets(Types.get(block, "before"), bindings)))
+        else
+          acc
+        end
+      end)
+
+    indeg =
+      Enum.reduce(edges, Map.new(bindings, fn b -> {b.ref, 0} end), fn {_from, tos}, acc ->
+        Enum.reduce(tos, acc, fn to, a -> Map.update!(a, to, &(&1 + 1)) end)
+      end)
+
+    ready = Enum.filter(bindings, fn b -> 0 == Map.get(indeg, b.ref) end)
+    out = walk(ready, indeg, edges, byref, [])
+
+    if length(out) != length(bindings) do
+      stuck = bindings |> Enum.reject(&(&1.ref in out)) |> Enum.map(& &1.ref)
+
+      Types.fail("plugin_order_cycle",
+                 "before/after constraints cycle: #{Enum.join(stuck, " -> ")}",
+                 %{"cycle" => stuck})
+    end
+
+    applypin(out, edges, pin)
+  end
+
+  # Stable topological sort. Among ready nodes, band first (lower runs
+  # first), then `pos` - the position the DOCUMENT visibly states, not the
+  # order instances happened to load and not the incarnation `seq`.
+  defp walk([], _indeg, _edges, _byref, out), do: Enum.reverse(out)
+
+  defp walk(ready, indeg, edges, byref, out) do
+    [nxt | rest] = Types.stable_sort_by(ready, fn b -> {order_band(b), b.pos} end)
+
+    {indeg, added} =
+      Enum.reduce(Map.get(edges, nxt.ref), {indeg, []}, fn to, {ind, acc} ->
+        ind = Map.update!(ind, to, &(&1 - 1))
+        if 0 == Map.get(ind, to), do: {ind, acc ++ [Map.get(byref, to)]}, else: {ind, acc}
+      end)
+
+    walk(rest ++ added, indeg, edges, byref, [nxt.ref | out])
+  end
+
+  @doc """
+  A PIN IS NOT A CONSTRAINT (section 7).
+
+  Constraints and bands are negotiable by definition - they are what
+  plugins and documents say they want, and the sort's job is to satisfy
+  them all. A pin is the host stating a structural invariant of its own
+  architecture, which is a different kind of claim and must not lose a tie
+  to a document.
+
+  So a pin PLACES the binding at the named end, and an ordering that would
+  move it away is `plugin_order_pinned` - rejected, not honoured into a
+  broken wrap.
+  """
+  def applypin(order, _edges, nil), do: order
+
+  def applypin(order, edges, pin) do
+    # SORTED, not insertion order. A pin map is data - it can arrive from a
+    # host's own construction options in any order, and two names pinned to
+    # the same end are order-sensitive.
+    out =
+      Enum.reduce(Types.keys(pin), order, fn name, acc ->
+        case Enum.find_index(acc, fn r -> Ref.refname(r) == name end) do
+          nil ->
+            acc
+
+          idx ->
+            # `first`/`outermost` is index 0; `last`/`innermost` is the
+            # end. Section 6.2 makes the first chain binding outermost,
+            # which is why the vocabulary is positional and why the two
+            # spellings pair this way.
+            ref = Enum.at(acc, idx)
+            rest = List.delete_at(acc, idx)
+            if Map.get(pin, name) in ["first", "outermost"], do: [ref | rest], else: rest ++ [ref]
+        end
+      end)
+
+    # Now check that the placement did not break a constraint. This is the
+    # half that makes a pin a rejection rather than an override: the host
+    # wins on position, but it does not get to silently discard a
+    # relationship a plugin declared.
+    at = out |> Enum.with_index() |> Map.new()
+
+    for from <- Enum.sort(Map.keys(edges)), to <- Map.get(edges, from) do
+      if Map.get(at, from) > Map.get(at, to) do
+        Types.fail("plugin_order_pinned",
+                   "a pin would move a binding an ordering constrains: " <>
+                     "#{from} must precede #{to}",
+                   %{"before" => from, "after" => to})
+      end
+    end
+
+    out
+  end
+end

package/project/.sdk/tm/elixir/lib/projectname/feature/secrets/plugin/point.ex

@@ -0,0 +1,99 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (elixir/lib/voxgig_plugin/point.ex)
+# 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.
+defmodule Voxgig.Plugin.Point do
+  @moduledoc """
+  Extension points (section 6). Three kinds, chosen because they are what
+  the two existing systems actually needed, and no more.
+
+  A PLUGIN NEVER MUTATES THE HOST. That inversion is what makes
+  deactivation possible: sdkgen's `utility.fetcher = wrapped` is not
+  undoable, but "this instance holds slot 3 of the request chain" is
+  undoable in O(1). OSGi named it the whiteboard pattern in 2004, in a
+  paper called *Listeners Considered Harmful*, and for exactly this reason.
+  """
+
+  alias Voxgig.Plugin.Types
+
+  @doc """
+  Section 6.1: "fan-out" is not one answer but four. In a language with
+  asynchrony, "call every binding" hides a decision - start them all and
+  wait, await each in turn, or do not wait - and a design that leaves it
+  unsaid gets four different answers from four ports, in the concurrency
+  behaviour of production code no corpus entry happens to cover.
+
+  ELIXIR IS THE PORT WHERE THAT IS LOUDEST: `Task.async_stream` is right
+  there, and using it for `emit` would make every hook point concurrent and
+  every ordering assertion a race. The host stays sequential (section 5.2)
+  and the modes stay data.
+  """
+  def modes, do: ~w(emit parallel serial bail)
+
+  @doc "Fan-out. Return values are ignored except in `bail`."
+  def point_emit(bindings, "bail", arg) do
+    # Stops at the first binding that RETURNS A VALUE - the "handled, stop"
+    # case. A `nil` RETURN DECLINES (section 6.1): elixir has one way to
+    # say nothing, and the model's rule is written to that rather than to
+    # JavaScript's null/undefined pair. Not truthiness - `false` is a
+    # value.
+    Enum.reduce_while(bindings, nil, fn b, _ ->
+      case b.fn.(nil, arg) do
+        nil -> {:cont, nil}
+        value -> {:halt, value}
+      end
+    end)
+  end
+
+  def point_emit(bindings, "emit", arg) do
+    # `emit` raises synchronously; the collecting modes gather.
+    Enum.each(bindings, fn b -> b.fn.(nil, arg) end)
+    nil
+  end
+
+  def point_emit(bindings, _mode, arg) do
+    Enum.reduce(bindings, [], fn b, errors ->
+      try do
+        b.fn.(nil, arg)
+        errors
+      rescue
+        e -> errors ++ [Types.message(e)]
+      end
+    end)
+  end
+
+  @doc """
+  Composition: b1(b2(b3(base))), FIRST BINDING OUTERMOST (section 6.2).
+
+  Recomputed by the host whenever the live set changes, and cached between
+  changes. Plugins receive `next` as an argument; they never see or store
+  the previous value of anything. A plugin that stashes `next` and calls it
+  after deactivation is a bug the host cannot prevent, and this says so
+  rather than pretending otherwise.
+  """
+  def compose(bindings, base) do
+    Enum.reduce(Enum.reverse(bindings), base, fn b, inner ->
+      fn arg -> b.fn.(inner, arg) end
+    end)
+  end
+
+  @doc """
+  At most one live implementation (section 6.3). The winner is the highest
+  band, ties broken by ref sort, and THE LOSERS ARE VISIBLE rather than
+  silently ignored.
+  """
+  def point_provider([], _spec), do: %{winner: nil, shadowed: []}
+
+  def point_provider(bindings, spec) do
+    if Types.truthy(Types.get(spec, "exclusive")) and 1 < length(bindings) do
+      refs = bindings |> Enum.map(& &1.ref) |> Enum.sort()
+
+      Types.fail("plugin_point_exclusive",
+                 "point is exclusive and has #{length(bindings)} bindings: " <>
+                   Enum.join(refs, ", "),
+                 %{"refs" => refs})
+    end
+
+    ranked = Types.stable_sort_by(bindings, fn b -> {-b.band, b.ref} end)
+    %{winner: hd(ranked), shadowed: ranked |> tl() |> Enum.map(& &1.ref)}
+  end
+end

package/project/.sdk/tm/elixir/lib/projectname/feature/secrets/plugin/ref.ex

@@ -0,0 +1,129 @@
+# VENDORED: @voxgig/plugin sdk-20260908-1556-0 (elixir/lib/voxgig_plugin/ref.ex)
+# 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.
+defmodule Voxgig.Plugin.Ref do
+  @moduledoc """
+  Identity: name+tag, written `name$tag` (section 4).
+
+  The four pure functions, and the whole of what `ref` pins. They are the
+  first thing a new port implements and the first corpus section it passes.
+
+  NO REGEX. Elixir's `~r/.../` is PCRE, whose `$` matches before a final
+  newline, so a `^...$` spelling would admit `"stripe\\n"` as a name - the
+  hole the ruby port surfaced in python. A character walk cannot have it,
+  and the four `#trailing-newline` entries pass here without the port
+  having to know they exist.
+  """
+
+  alias Voxgig.Plugin.Types
+
+  @ref_max 1024
+
+  @doc "Section 4: `^[a-zA-Z@][a-zA-Z0-9.~_\\-/]*$`, max 1024."
+  def check_name(name) when is_binary(name) do
+    case String.to_charlist(name) do
+      [] -> false
+      [first | rest] ->
+        byte_size(name) <= @ref_max and (alpha?(first) or ?@ == first) and
+          Enum.all?(rest, &namechar?/1)
+    end
+  end
+
+  def check_name(_), do: false
+
+  @doc """
+  Section 4: `^[a-zA-Z0-9.~_-]+$`, max 1024, or empty.
+
+  The asymmetry with a name is deliberate: a tag MAY start with a digit
+  because auto-tagging assigns integer tags (`stripe$1`), and a tag admits
+  neither `@` nor `/` because a name is a package specifier and a tag is
+  not.
+  """
+  def check_tag(""), do: true
+
+  def check_tag(tag) when is_binary(tag) do
+    byte_size(tag) <= @ref_max and Enum.all?(String.to_charlist(tag), &tagchar?/1)
+  end
+
+  def check_tag(_), do: false
+
+  defp alpha?(c), do: (?a <= c and c <= ?z) or (?A <= c and c <= ?Z)
+  defp digit?(c), do: ?0 <= c and c <= ?9
+  defp namechar?(c), do: alpha?(c) or digit?(c) or c in [?., ?~, ?_, ?-, ?/]
+  defp tagchar?(c), do: alpha?(c) or digit?(c) or c in [?., ?~, ?_, ?-]
+
+  @doc """
+  `name$tag` -> the pair. Canonicalizing: `stripe$` and `stripe` both give
+  tag "".
+  """
+  def parse_ref(str) when is_binary(str) do
+    # Split on the FIRST `$`. Nothing in the grammar decides this - `$` is
+    # in neither character class - so the corpus is the arbiter (section 4
+    # rule 5), and it picks the split that blames the part actually at
+    # fault: `a$b$c` is a good name with a bad tag, not the reverse.
+    {name, tag} =
+      case :binary.match(str, "$") do
+        :nomatch -> {str, ""}
+        {at, _} -> {binary_part(str, 0, at), binary_part(str, at + 1, byte_size(str) - at - 1)}
+      end
+
+    if not check_name(name) do
+      Types.fail("plugin_bad_name", "invalid plugin name: #{name}", %{"name" => name})
+    end
+
+    if not check_tag(tag) do
+      Types.fail("plugin_bad_tag", "invalid plugin tag: #{tag}", %{"name" => name, "tag" => tag})
+    end
+
+    %{"name" => name, "tag" => tag}
+  end
+
+  def parse_ref(_), do: Types.fail("plugin_bad_name", "ref must be a string")
+
+  @doc """
+  The pair -> `name$tag`. An empty tag NEVER writes the separator, which is
+  the half of canonicalization `format_ref` owns: parse tolerates
+  `stripe$`, format never produces it, so a round trip is idempotent.
+  """
+  def format_ref(name, tag) do
+    tag = if is_nil(tag), do: "", else: tag
+
+    if not check_name(name) do
+      Types.fail("plugin_bad_name", "invalid plugin name: #{Types.encode(name)}",
+                 %{"name" => name})
+    end
+
+    if not check_tag(tag) do
+      Types.fail("plugin_bad_tag", "invalid plugin tag: #{Types.encode(tag)}",
+                 %{"name" => name, "tag" => tag})
+    end
+
+    if "" == tag, do: name, else: name <> "$" <> tag
+  end
+
+  @doc """
+  The canonical spelling of a ref. Section 4 rule 5: ports must
+  canonicalize before comparison.
+  """
+  def canon_ref(str) do
+    parsed = parse_ref(str)
+    format_ref(parsed["name"], parsed["tag"])
+  end
+
+  @doc """
+  canon_ref for the internal callers that want the input back unchanged
+  when it is not well formed. NEVER use it where a bad ref must be reported
+  - the corpus pins plugin_bad_name at every public entry.
+  """
+  def canon(str) do
+    canon_ref(str)
+  rescue
+    Voxgig.Plugin.Error -> str
+  end
+
+  def refname(str) do
+    parse_ref(str)["name"]
+  rescue
+    Voxgig.Plugin.Error -> str
+  end
+end