@voxgig/sdkgen 4.10.0 → 4.11.0

package/project/.sdk/tm/lua/feature/secrets/plugin/json.lua

@@ -0,0 +1,169 @@
+-- VENDORED: @voxgig/plugin sdk-20260908-1556-0 (lua/src/plugin/json.lua)
+-- 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.
+-- The JSON parser, and the only one this port has.
+--
+-- NO LUAROCKS, NO DKJSON, NO CJSON (section 16). The library is allowed
+-- exactly one runtime dependency, `voxgig/struct`, which has no lua 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 rock
+-- every embedding host has to install.
+--
+-- EVERY TABLE IT BUILDS IS TAGGED (types.map / types.list) and every JSON
+-- null becomes `types.NULL`. That is what lets this port tell `{}` from
+-- `[]` and an absent key from a null one - two distinctions the corpus
+-- draws and a plain lua table cannot.
+
+local T = require 'feature.secrets.plugin.types'
+
+local M = {}
+
+local function skipws(s, at)
+  while at <= #s do
+    local c = s:sub(at, at)
+    if ' ' ~= c and '\t' ~= c and '\n' ~= c and '\r' ~= c then break end
+    at = at + 1
+  end
+  return at
+end
+
+local parsevalue
+
+local function parsestring(s, at)
+  if '"' ~= s:sub(at, at) then
+    error('expected a string at ' .. at, 0)
+  end
+  at = at + 1
+  local out = {}
+  while at <= #s do
+    local c = s:sub(at, at)
+    at = at + 1
+    if '"' == c then
+      return table.concat(out), at
+    end
+    if '\\' == c then
+      local e = s:sub(at, at)
+      at = at + 1
+      if '"' == e then out[#out + 1] = '"'
+      elseif '\\' == e then out[#out + 1] = '\\'
+      elseif '/' == e then out[#out + 1] = '/'
+      elseif 'b' == e then out[#out + 1] = '\b'
+      elseif 'f' == e then out[#out + 1] = '\f'
+      elseif 'n' == e then out[#out + 1] = '\n'
+      elseif 'r' == e then out[#out + 1] = '\r'
+      elseif 't' == e then out[#out + 1] = '\t'
+      elseif 'u' == e then
+        local hex = s:sub(at, at + 3)
+        at = at + 4
+        local code = tonumber(hex, 16)
+        if nil == code then error('bad \\u escape at ' .. at, 0) end
+        -- A surrogate PAIR is two escapes; lua 5.4's utf8.char takes the
+        -- joined code point, so the pair is joined here.
+        if 0xD800 <= code and code < 0xDC00 and '\\u' == s:sub(at, at + 1) then
+          local low = tonumber(s:sub(at + 2, at + 5), 16)
+          if nil ~= low and 0xDC00 <= low and low < 0xE000 then
+            at = at + 6
+            code = 0x10000 + (code - 0xD800) * 0x400 + (low - 0xDC00)
+          end
+        end
+        out[#out + 1] = utf8.char(code)
+      else
+        error('bad escape at ' .. at, 0)
+      end
+    else
+      out[#out + 1] = c
+    end
+  end
+  error('unterminated string', 0)
+end
+
+local function parsemap(s, at)
+  local out = {}
+  at = skipws(s, at + 1)
+  if '}' == s:sub(at, at) then
+    return T.map(out), at + 1
+  end
+  while true do
+    at = skipws(s, at)
+    local key
+    key, at = parsestring(s, at)
+    at = skipws(s, at)
+    if ':' ~= s:sub(at, at) then error("expected ':' at " .. at, 0) end
+    at = skipws(s, at + 1)
+    local value
+    value, at = parsevalue(s, at)
+    out[key] = value
+    at = skipws(s, at)
+    local c = s:sub(at, at)
+    if ',' == c then
+      at = at + 1
+    elseif '}' == c then
+      return T.map(out), at + 1
+    else
+      error("expected ',' or '}' at " .. at, 0)
+    end
+  end
+end
+
+local function parselist(s, at)
+  local out = {}
+  at = skipws(s, at + 1)
+  if ']' == s:sub(at, at) then
+    return T.list(out), at + 1
+  end
+  while true do
+    at = skipws(s, at)
+    local value
+    value, at = parsevalue(s, at)
+    out[#out + 1] = value
+    at = skipws(s, at)
+    local c = s:sub(at, at)
+    if ',' == c then
+      at = at + 1
+    elseif ']' == c then
+      return T.list(out), at + 1
+    else
+      error("expected ',' or ']' at " .. at, 0)
+    end
+  end
+end
+
+local function literal(s, at, word, value)
+  if word ~= s:sub(at, at + #word - 1) then
+    error('bad literal at ' .. at, 0)
+  end
+  return value, at + #word
+end
+
+parsevalue = function(s, at)
+  local c = s:sub(at, at)
+  if '{' == c then return parsemap(s, at) end
+  if '[' == c then return parselist(s, at) end
+  if '"' == c then return parsestring(s, at) end
+  if 't' == c then return literal(s, at, 'true', true) end
+  if 'f' == c then return literal(s, at, 'false', false) end
+  if 'n' == c then return literal(s, at, 'null', T.NULL) end
+
+  local body = s:match('^%-?%d+%.?%d*[eE]?[-+]?%d*', at)
+  if nil == body or '' == body then
+    error('unexpected input at ' .. at, 0)
+  end
+  local n = tonumber(body)
+  if nil == n then error('bad number at ' .. at, 0) end
+  return n, at + #body
+end
+
+function M.parse(text)
+  local at = skipws(text, 1)
+  local value
+  value, at = parsevalue(text, at)
+  at = skipws(text, at)
+  if at <= #text then
+    error('trailing input at ' .. at, 0)
+  end
+  return value
+end
+
+M.encode = T.encode
+
+return M

package/project/.sdk/tm/lua/feature/secrets/plugin/order.lua

@@ -0,0 +1,207 @@
+-- VENDORED: @voxgig/plugin sdk-20260908-1556-0 (lua/src/plugin/order.lua)
+-- 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.
+-- 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.
+
+local T = require 'feature.secrets.plugin.types'
+local R = require 'feature.secrets.plugin.ref'
+
+local M = {}
+
+-- An integer, and only an integer: `true` and `'2'` are not bands, and lua
+-- would coerce the string in a comparison.
+function M.order_band(binding)
+  local block = binding.order
+  if not T.ismap(block) then return 0 end
+  local value = T.getv(block, 'band')
+  if 'integer' == math.type(value) then return value end
+  return 0
+end
+
+-- Was a constraint stated? An absent value and an EMPTY LIST are both
+-- no-constraint - and an empty list is TRUTHY in lua as in ruby, which is
+-- exactly how this class of bug survives a reading.
+function M.order_declared(spec)
+  if nil == spec or T.NULL == spec then return false end
+  if T.islist(spec) then
+    for i = 1, #spec do
+      if '' ~= spec[i] then return true end
+    end
+    return false
+  end
+  return '' ~= spec
+end
+
+-- 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.
+function M.order_targets(spec, nodes)
+  local specs = T.islist(spec) and spec or { spec }
+  local hit = {}
+  local seen = {}
+  for i = 1, #specs do
+    local one = specs[i]
+    for _, b in ipairs(nodes) do
+      if not seen[b.ref] and (b.ref == one or R.refname(b.ref) == one) then
+        seen[b.ref] = true
+        hit[#hit + 1] = b.ref
+      end
+    end
+  end
+  return hit
+end
+
+-- 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.
+local function applypin(order, edges, edgekeys, pin)
+  if nil == pin or T.NULL == pin then return order end
+
+  local out = {}
+  for i = 1, #order do out[i] = order[i] end
+
+  -- 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. A lua table has no order at all,
+  -- which makes leaving it unstated worse here than anywhere else.
+  for _, name in ipairs(T.keys(pin)) do
+    local want = pin[name]
+    local idx
+    for i = 1, #out do
+      if R.refname(out[i]) == name then idx = i break end
+    end
+    if nil ~= idx then
+      -- `first`/`outermost` is index 1; `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.
+      local wantfirst = 'first' == want or 'outermost' == want
+      local ref = table.remove(out, idx)
+      if wantfirst then
+        table.insert(out, 1, ref)
+      else
+        out[#out + 1] = ref
+      end
+    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.
+  local at = {}
+  for i = 1, #out do at[out[i]] = i end
+  for _, from in ipairs(edgekeys) do
+    for _, to in ipairs(edges[from]) do
+      if at[from] > at[to] then
+        T.fail('plugin_order_pinned',
+               'a pin would move a binding an ordering constrains: '
+               .. from .. ' must precede ' .. to,
+               T.map { before = from, after = to })
+      end
+    end
+  end
+
+  return out
+end
+
+-- `bindings` is a plain lua array of {ref=, pos=, order=} records: an
+-- internal shape, never a corpus value, so it is not tagged.
+function M.resolve_order(bindings, pin)
+  local byref = {}
+  local edges = {}
+  local edgekeys = {}
+  local indeg = {}
+  for _, b in ipairs(bindings) do
+    byref[b.ref] = b
+    edges[b.ref] = {}
+    edgekeys[#edgekeys + 1] = b.ref
+    indeg[b.ref] = 0
+  end
+  table.sort(edgekeys)
+
+  -- 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.
+  for _, b in ipairs(bindings) do
+    local block = T.ismap(b.order) and b.order or T.map {}
+    -- An ABSENT constraint and an EMPTY LIST are both "no constraint".
+    if M.order_declared(T.getv(block, 'after')) then
+      for _, t in ipairs(M.order_targets(T.getv(block, 'after'), bindings)) do
+        table.insert(edges[t], b.ref)
+      end
+    end
+    if M.order_declared(T.getv(block, 'before')) then
+      for _, t in ipairs(M.order_targets(T.getv(block, 'before'), bindings)) do
+        table.insert(edges[b.ref], t)
+      end
+    end
+  end
+
+  for _, from in ipairs(edgekeys) do
+    for _, to in ipairs(edges[from]) do
+      indeg[to] = indeg[to] + 1
+    end
+  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`.
+  local out = {}
+  local ready = {}
+  for _, b in ipairs(bindings) do
+    if 0 == indeg[b.ref] then ready[#ready + 1] = b end
+  end
+
+  while 0 < #ready do
+    ready = T.stable_sort(ready, function(a, b)
+      local ba, bb = M.order_band(a), M.order_band(b)
+      if ba ~= bb then return ba < bb end
+      return (a.pos or 0) < (b.pos or 0)
+    end)
+    local nxt = table.remove(ready, 1)
+    out[#out + 1] = nxt.ref
+    for _, to in ipairs(edges[nxt.ref]) do
+      indeg[to] = indeg[to] - 1
+      if 0 == indeg[to] then ready[#ready + 1] = byref[to] end
+    end
+  end
+
+  if #out ~= #bindings then
+    local placed = {}
+    for _, r in ipairs(out) do placed[r] = true end
+    local stuck = {}
+    for _, b in ipairs(bindings) do
+      if not placed[b.ref] then stuck[#stuck + 1] = b.ref end
+    end
+    T.fail('plugin_order_cycle',
+           'before/after constraints cycle: ' .. table.concat(stuck, ' -> '),
+           T.map { cycle = T.list(stuck) })
+  end
+
+  return applypin(out, edges, edgekeys, pin)
+end
+
+return M

package/project/.sdk/tm/lua/feature/secrets/plugin/point.lua

@@ -0,0 +1,106 @@
+-- VENDORED: @voxgig/plugin sdk-20260908-1556-0 (lua/src/plugin/point.lua)
+-- 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.
+-- 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.
+
+local T = require 'feature.secrets.plugin.types'
+
+local M = {}
+
+-- 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.
+M.MODES = { 'emit', 'parallel', 'serial', 'bail' }
+
+-- Fan-out. Return values are ignored except in `bail`.
+function M.point_emit(bindings, mode, arg)
+  if 'bail' == mode then
+    -- Stops at the first binding that RETURNS A VALUE - the "handled,
+    -- stop" case. A `nil` RETURN DECLINES (section 6.1): lua 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.
+    for _, b in ipairs(bindings) do
+      local v = b.fn(nil, arg)
+      -- BOTH SPELLINGS OF NOTHING DECLINE. A lua callback returns `nil`,
+      -- and a callback handing back a JSON null returns `T.NULL` - the
+      -- sentinel this port uses because a table cannot store a nil. The
+      -- model's rule is that NULL declines (`point/bail#null-declines`
+      -- pins a provider configured with `value: null` letting the next one
+      -- answer), so a port that stopped on the sentinel would answer null
+      -- where every other port answers "B".
+      if nil ~= v and T.NULL ~= v then return v end
+    end
+    return nil
+  end
+
+  local errors = {}
+  for _, b in ipairs(bindings) do
+    local ok, err = pcall(b.fn, nil, arg)
+    if not ok then
+      -- `emit` raises synchronously; the collecting modes gather.
+      if 'emit' == mode then error(err, 0) end
+      errors[#errors + 1] = T.message(err)
+    end
+  end
+  if 'emit' == mode then return nil end
+  return T.list(errors)
+end
+
+-- 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.
+function M.compose(bindings, base)
+  local nxt = base
+  for i = #bindings, 1, -1 do
+    -- Fresh locals per iteration, so each layer closes over its own pair -
+    -- lua gives that for free where ruby's blocks do not.
+    local fn = bindings[i].fn
+    local inner = nxt
+    nxt = function(...) return fn(inner, ...) end
+  end
+  return nxt
+end
+
+-- 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.
+function M.point_provider(bindings, spec)
+  if 0 == #bindings then
+    return { winner = nil, shadowed = T.list {} }
+  end
+
+  if T.truthy(T.getv(spec, 'exclusive')) and 1 < #bindings then
+    local refs = {}
+    for _, b in ipairs(bindings) do refs[#refs + 1] = b.ref end
+    table.sort(refs)
+    T.fail('plugin_point_exclusive',
+           'point is exclusive and has ' .. #bindings .. ' bindings: '
+           .. table.concat(refs, ', '),
+           T.map { refs = T.list(refs) })
+  end
+
+  local ranked = T.stable_sort(bindings, function(a, b)
+    if a.band ~= b.band then return a.band > b.band end
+    return a.ref < b.ref
+  end)
+  local shadowed = {}
+  for i = 2, #ranked do shadowed[#shadowed + 1] = ranked[i].ref end
+  return { winner = ranked[1], shadowed = T.list(shadowed) }
+end
+
+return M

package/project/.sdk/tm/lua/feature/secrets/plugin/ref.lua

@@ -0,0 +1,115 @@
+-- VENDORED: @voxgig/plugin sdk-20260908-1556-0 (lua/src/plugin/ref.lua)
+-- 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.
+-- 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.
+--
+-- LUA'S `$` IS A TRUE END ANCHOR. A lua pattern has no multiline mode and
+-- `$` matches only at the end of the subject, so `^...$` here cannot admit
+-- the trailing newline that ruby, python, perl and php each had to write
+-- `\A`/`\z` (or a character walk) to exclude. The four
+-- `#trailing-newline` entries pass this port without it having to know
+-- they exist.
+
+local T = require 'feature.secrets.plugin.types'
+
+local M = {}
+
+-- Section 4: `^[a-zA-Z@][a-zA-Z0-9.~_\-/]*$`, max 1024.
+M.NAME_PAT = '^[a-zA-Z@][a-zA-Z0-9.~_/%-]*$'
+
+-- 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.
+M.TAG_PAT = '^[a-zA-Z0-9.~_%-]+$'
+
+M.REF_MAX = 1024
+
+function M.check_name(name)
+  if 'string' ~= type(name) then return false end
+  if '' == name or M.REF_MAX < #name then return false end
+  return nil ~= name:match(M.NAME_PAT)
+end
+
+function M.check_tag(tag)
+  if 'string' ~= type(tag) then return false end
+  -- The empty tag is an ordinary tag (section 4 rule 2). The
+  -- single-instance case writes no tag and never learns tags exist.
+  if '' == tag then return true end
+  if M.REF_MAX < #tag then return false end
+  return nil ~= tag:match(M.TAG_PAT)
+end
+
+-- `name$tag` -> the pair. Canonicalizing: `stripe$` and `stripe` both give
+-- tag ''.
+function M.parse_ref(str)
+  if 'string' ~= type(str) then
+    T.fail('plugin_bad_name', 'ref must be a string', nil)
+  end
+
+  -- 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.
+  local cut = str:find('$', 1, true)
+  local name = nil == cut and str or str:sub(1, cut - 1)
+  local tag = nil == cut and '' or str:sub(cut + 1)
+
+  if not M.check_name(name) then
+    T.fail('plugin_bad_name', 'invalid plugin name: ' .. name,
+           T.map { name = name })
+  end
+  if not M.check_tag(tag) then
+    T.fail('plugin_bad_tag', 'invalid plugin tag: ' .. tag,
+           T.map { name = name, tag = tag })
+  end
+
+  return T.map { name = name, tag = tag }
+end
+
+-- 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.
+function M.format_ref(name, tag)
+  if nil == tag or T.NULL == tag then tag = '' end
+  if not M.check_name(name) then
+    T.fail('plugin_bad_name', 'invalid plugin name: ' .. T.encode(name),
+           T.map { name = name })
+  end
+  if not M.check_tag(tag) then
+    T.fail('plugin_bad_tag', 'invalid plugin tag: ' .. T.encode(tag),
+           T.map { name = name, tag = tag })
+  end
+  if '' == tag then return name end
+  return name .. '$' .. tag
+end
+
+-- The canonical spelling of a ref. Section 4 rule 5: ports must
+-- canonicalize before comparison.
+function M.canon_ref(str)
+  local parsed = M.parse_ref(str)
+  return M.format_ref(parsed.name, parsed.tag)
+end
+
+-- 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.
+function M.canon(str)
+  local ok, out = pcall(M.canon_ref, str)
+  if ok then return out end
+  return str
+end
+
+function M.refname(str)
+  local ok, out = pcall(function() return M.parse_ref(str).name end)
+  if ok then return out end
+  return str
+end
+
+return M

package/project/.sdk/tm/lua/feature/secrets/plugin/resolve.lua

@@ -0,0 +1,78 @@
+-- VENDORED: @voxgig/plugin sdk-20260908-1556-0 (lua/src/plugin/resolve.lua)
+-- 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.
+-- Dynamic resolution (section 10.2) - name to candidate module ids.
+--
+-- PURE. It returns the ids a host WOULD try, in order; it does not load
+-- anything. That separation is what lets the corpus pin resolution in
+-- every language including those with no dynamic loading at all, and it is
+-- why section 15.4 puts real module loading in per-port integration tests
+-- rather than here.
+
+local T = require 'feature.secrets.plugin.types'
+
+local M = {}
+
+function M.default_sources()
+  return T.list {
+    T.map {
+      kind = 'module',
+      prefix = T.list { '@voxgig/plugin-', 'voxgig-plugin-', 'plugin-', '' },
+    },
+  }
+end
+
+function M.resolve_candidates(name, sources)
+  local out = {}
+  local seen = {}
+
+  -- A SCOPED NAME RESOLVES VERBATIM ONLY (section 10.2). `@acme/thing` is
+  -- already a package id; prefixing it produces
+  -- `@voxgig/plugin-@acme/thing`, which is not a thing that can exist.
+  if '@' == name:sub(1, 1) then
+    return T.list { name }
+  end
+
+  local list = sources
+  if not T.islist(list) or 0 == #list then
+    list = M.default_sources()
+  end
+
+  for i = 1, #list do
+    local src = list[i]
+    local kind = T.getv(src, 'kind')
+    if 'module' == kind then
+      local prefixes = T.getv(src, 'prefix')
+      if not T.islist(prefixes) or 0 == #prefixes then
+        prefixes = T.list { '' }
+      end
+      for j = 1, #prefixes do
+        local id = prefixes[j] .. name
+        if not seen[id] then
+          seen[id] = true
+          out[#out + 1] = id
+        end
+      end
+    elseif 'path' == kind then
+      local dir = (T.getv(src, 'dir') or ''):gsub('/+$', '')
+      local id = dir .. '/' .. name
+      if not seen[id] then
+        seen[id] = true
+        out[#out + 1] = id
+      end
+    end
+  end
+
+  return T.list(out)
+end
+
+-- A MODULE PATH IS NOT A NAME (section 10.2). The ref grammar starts a
+-- name with a letter or `@`, so `./local/thing` is not a ref and never
+-- reaches candidate generation - seneca allows a path where a plugin name
+-- goes, and this design deliberately does not, because a ref is an ADDRESS
+-- WITHIN A HOST and a path is a LOCATION ON A DISK.
+function M.resolve_from(from)
+  return T.list { from }
+end
+
+return M