@voxgig/sdkgen 4.9.0 → 4.11.0

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

@@ -0,0 +1,232 @@
+-- VENDORED: @voxgig/plugin sdk-20260908-1556-0 (lua/src/plugin/depend.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.
+-- 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.
+
+local T = require 'feature.secrets.plugin.types'
+local R = require 'feature.secrets.plugin.ref'
+
+local M = {}
+
+-- A bare string is shorthand for `{name}`.
+function M.normrequire(raw)
+  if 'string' == type(raw) then
+    return T.map { name = raw }
+  end
+  if not T.ismap(raw) then return T.map {} end
+  local out = T.map {}
+  for k, v in pairs(raw) do out[k] = v end
+  return out
+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".
+function M.requirements(options)
+  local raw = T.getv(options, 'requires') or T.list {}
+  local marked = T.getv(options, 'optional')
+  local fallback = T.getv(options, 'policy')
+
+  local out = {}
+  for i = 1, T.len(raw) do
+    local req = M.normrequire(raw[i])
+    local ismarked = false
+    if T.islist(marked) then
+      for j = 1, #marked do
+        if T.same(marked[j], T.getv(req, 'name')) then ismarked = true break end
+      end
+    end
+    if T.truthy(T.getv(req, 'optional')) or ismarked then
+      req.optional = true
+    end
+    if nil == T.getv(req, 'policy') and nil ~= fallback then
+      req.policy = fallback
+    end
+    out[#out + 1] = req
+  end
+  return out
+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.
+function M.restartsonloss(req)
+  return 'dynamic' ~= (T.getv(req, 'policy') or 'static')
+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.
+function M.gatesactivation(req)
+  return true ~= T.getv(req, 'optional')
+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.
+function M.restartcausing(req)
+  return M.gatesactivation(req) or M.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.
+--
+-- `nodes` is a plain lua array of {ref=, provides=, requires=} records.
+function M.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.
+  local bycap = {}
+  local isref = {}
+  for _, n in ipairs(nodes) do
+    isref[n.ref] = true
+    for _, cap in ipairs(n.provides) do
+      if nil == bycap[cap] then bycap[cap] = {} end
+      table.insert(bycap[cap], n.ref)
+    end
+  end
+
+  local edges = {}
+  local starts = {}
+  for _, n in ipairs(nodes) do
+    local out = {}
+    local seen = {}
+    for _, req in ipairs(n.requires) do
+      if M.restartcausing(req) then
+        local reqname = T.getv(req, 'name')
+        local from = {}
+        for _, p in ipairs(bycap[reqname] or {}) do from[#from + 1] = p end
+        -- 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.
+        local asref = R.canon(reqname)
+        if isref[asref] then
+          local dup = false
+          for _, p in ipairs(from) do if p == asref then dup = true end end
+          if not dup then from[#from + 1] = asref end
+        end
+        for _, p in ipairs(from) do
+          if p ~= n.ref and not seen[p] then
+            seen[p] = true
+            out[#out + 1] = p
+          end
+        end
+      end
+    end
+    table.sort(out)
+    edges[n.ref] = out
+    starts[#starts + 1] = n.ref
+  end
+  table.sort(starts)
+
+  -- Iterative DFS with an explicit stack: twenty ports, and several of
+  -- them have no recursion budget worth relying on.
+  local WHITE, GREY, BLACK = 0, 1, 2
+  local colour = {}
+  for _, n in ipairs(nodes) do colour[n.ref] = WHITE end
+
+  for _, start in ipairs(starts) do
+    if WHITE == colour[start] then
+      local path = { start }
+      local stack = { { start, 1 } }
+      colour[start] = GREY
+
+      while 0 < #stack do
+        local top = stack[#stack]
+        local outs = edges[top[1]]
+        if #outs < top[2] then
+          colour[top[1]] = BLACK
+          table.remove(stack)
+          table.remove(path)
+        else
+          local nxt = outs[top[2]]
+          top[2] = top[2] + 1
+          if GREY == colour[nxt] then
+            -- Report the cycle itself, not the walk that found it.
+            local at = 1
+            while at <= #path and path[at] ~= nxt do at = at + 1 end
+            local cycle = {}
+            for i = at, #path do cycle[#cycle + 1] = path[i] end
+            cycle[#cycle + 1] = nxt
+            return cycle
+          elseif BLACK ~= colour[nxt] then
+            colour[nxt] = GREY
+            path[#path + 1] = nxt
+            stack[#stack + 1] = { nxt, 1 }
+          end
+        end
+      end
+    end
+  end
+  return nil
+end
+
+-- Raise on a cycle, naming it. Separate from the detector so the detector
+-- stays pure and corpus-testable.
+function M.checkcycle(nodes)
+  local cycle = M.dependencycycle(nodes)
+  if nil == cycle then return end
+  T.fail('plugin_dependency_cycle',
+         'requirements cycle: ' .. table.concat(cycle, ' -> '),
+         T.map { cycle = T.list(cycle) })
+end
+
+return M

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

@@ -0,0 +1,168 @@
+-- VENDORED: @voxgig/plugin sdk-20260908-1556-0 (lua/src/plugin/env.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.
+-- 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.
+
+local T = require 'feature.secrets.plugin.types'
+local R = require 'feature.secrets.plugin.ref'
+local J = require 'feature.secrets.plugin.json'
+
+local M = {}
+
+M.ENV_PREFIX = 'VOXGIG_PLUGIN_'
+
+-- `retry$fast` -> `RETRY__FAST`.
+function M.encode_ref(ref)
+  local out = ref:gsub('%$', '__'):gsub('%.', '_')
+  return out:upper()
+end
+
+local function checkreserved(ref, reserved)
+  if not T.islist(reserved) or 0 == #reserved then return end
+  local name = R.refname(ref)
+  for i = 1, #reserved do
+    if reserved[i] == name then
+      T.fail('plugin_ref_reserved', 'ref is reserved by the host: ' .. ref,
+             T.map { ref = ref })
+    end
+  end
+end
+
+local function split(value)
+  local out = {}
+  if 'string' ~= type(value) then return out end
+  for part in (value .. ','):gmatch('([^,]*),') do
+    local trimmed = part:match('^%s*(.-)%s*$')
+    if '' ~= trimmed then out[#out + 1] = trimmed end
+  end
+  return out
+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.
+local function parsevalue(value)
+  if 'string' ~= type(value) then return value end
+  local ok, parsed = pcall(J.parse, value)
+  if ok then return parsed end
+  return value
+end
+
+function M.apply_env(input)
+  input = input or T.map {}
+  local env = T.getv(input, 'env') or T.map {}
+  local reserved = T.getv(input, 'reserved') or T.list {}
+
+  local refs = {}
+  local given = T.getv(input, 'refs') or T.list {}
+  for i = 1, T.len(given) do
+    refs[#refs + 1] = R.canon_ref(given[i])
+  end
+
+  local options = T.map {}
+  local active = T.list {}
+  local inactive = T.list {}
+  local out = T.map { options = options, active = active, inactive = 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.
+  local byencoded = {}
+  local encodedkeys = {}
+  for _, r in ipairs(refs) do
+    local e = M.encode_ref(r)
+    if nil == byencoded[e] then
+      byencoded[e] = {}
+      encodedkeys[#encodedkeys + 1] = e
+    end
+    table.insert(byencoded[e], r)
+  end
+  table.sort(encodedkeys)
+  for _, e in ipairs(encodedkeys) do
+    if 1 < #byencoded[e] then
+      local pair = T.sortstrings(byencoded[e])
+      T.fail('plugin_env_ambiguous',
+             'refs collide in the environment encoding as ' .. e .. ': '
+             .. table.concat(pair, ', '),
+             T.map { encoded = e, refs = T.list(pair) })
+    end
+  end
+
+  -- Longest encoded ref first, so `retry$fast` wins over `retry` on
+  -- `RETRY__FAST_MIN`. Shortest-first would read the tag as a path.
+  local encoded = T.stable_sort(encodedkeys, function(a, b)
+    return #a > #b
+  end)
+
+  for _, key in ipairs(T.keys(env)) do
+    if M.ENV_PREFIX == key:sub(1, #M.ENV_PREFIX) then
+      local rest = key:sub(#M.ENV_PREFIX + 1)
+
+      if 'PROFILE' == rest then
+        out.profile = env[key]
+      elseif 'ACTIVE' == rest or 'INACTIVE' == rest then
+        local target = 'ACTIVE' == rest and active or inactive
+        for _, raw in ipairs(split(env[key])) do
+          local ref = R.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.
+          checkreserved(ref, reserved)
+          target[#target + 1] = ref
+        end
+      else
+        local enc
+        for _, e in ipairs(encoded) do
+          if rest == e or (e .. '_') == rest:sub(1, #e + 1) then
+            enc = e
+            break
+          end
+        end
+
+        if nil ~= enc then
+          local ref = byencoded[enc][1]
+          checkreserved(ref, reserved)
+
+          -- A ref with no path sets nothing.
+          if rest ~= enc then
+            local path = {}
+            for piece in (rest:sub(#enc + 2):lower() .. '_'):gmatch('([^_]*)_') do
+              path[#path + 1] = piece
+            end
+
+            if not T.ismap(options[ref]) then options[ref] = T.map {} end
+            local node = options[ref]
+            for i = 1, #path - 1 do
+              if not T.ismap(node[path[i]]) then node[path[i]] = T.map {} end
+              node = node[path[i]]
+            end
+            node[path[#path]] = parsevalue(env[key])
+          end
+        end
+      end
+    end
+  end
+
+  return out
+end
+
+return M

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

@@ -0,0 +1,66 @@
+-- VENDORED: @voxgig/plugin sdk-20260908-1556-0 (lua/src/plugin/export.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.
+-- Exports (section 11).
+--
+-- An instance publishes values for other plugins and for the application.
+-- Read with `host:exports('retry$fast/client')`.
+--
+-- THE UNQUALIFIED ALIAS IS THE INTERESTING PART. `retry/client` resolves
+-- to the UNTAGGED instance if one exists; if not, and exactly one tagged
+-- instance exports that key, it resolves to that one; if two do, it is
+-- `plugin_export_ambiguous` - deliberately diverging from seneca's silent
+-- last-wins, because with multi-instance as a headline feature an
+-- ambiguous alias is a defect waiting for production.
+
+local T = require 'feature.secrets.plugin.types'
+local R = require 'feature.secrets.plugin.ref'
+
+local M = {}
+
+-- `exported` is a plain lua array of {ref=, key=, value=} records: an
+-- internal shape, never a corpus value, so it is not tagged.
+function M.resolve_export(spec, exported)
+  local cut = spec:find('/', 1, true)
+  if nil == cut then
+    T.fail('plugin_export_ambiguous', 'export spec needs a key: ' .. spec,
+           T.map { spec = spec })
+  end
+  local head = spec:sub(1, cut - 1)
+  local key = spec:sub(cut + 1)
+
+  -- A fully qualified ref: exactly one answer or none.
+  local want = R.canon(head)
+  for _, e in ipairs(exported) do
+    if e.ref == want and e.key == key then
+      return e.value
+    end
+  end
+
+  -- An alias: the name, not a ref. Look at every instance of it.
+  local byname = {}
+  for _, e in ipairs(exported) do
+    if R.refname(e.ref) == head and e.key == key then
+      byname[#byname + 1] = e
+    end
+  end
+  if 0 == #byname then return nil end
+
+  for _, e in ipairs(byname) do
+    if '' == R.parse_ref(e.ref).tag then
+      return e.value
+    end
+  end
+
+  if 1 == #byname then return byname[1].value end
+
+  local refs = {}
+  for _, e in ipairs(byname) do refs[#refs + 1] = e.ref end
+  table.sort(refs)
+  T.fail('plugin_export_ambiguous',
+         'alias ' .. spec .. ' matches ' .. #refs .. ' instances: '
+         .. table.concat(refs, ', '),
+         T.map { spec = spec, refs = T.list(refs) })
+end
+
+return M

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

@@ -0,0 +1,194 @@
+-- VENDORED: @voxgig/plugin sdk-20260908-1556-0 (lua/src/plugin/graph.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.
+-- Whole-graph resolution (section 11.4) - a phase, not a discovery.
+--
+-- "Activate, and wait in `pending` if you must" is correct and, on its
+-- own, produces a terrible experience: apply twenty instances against a
+-- registry missing one thing and you get NINETEEN pending rows and no
+-- statement of what is actually wrong.
+--
+-- `resolve_graph` is a PURE FUNCTION of the registry and the intended
+-- activation set. No callbacks run, no state changes, nothing is touched.
+-- It answers for the whole graph at once which instances can be live, and
+-- for each blocked one THE SPECIFIC REQUIREMENT that is unmet, and why.
+--
+-- The failure mode being designed against is a famous one: OSGi's resolver
+-- is correct and its diagnostics are legendarily unusable. A resolver that
+-- says "blocked" without saying WHY has moved the problem rather than
+-- solved it, so `why` is part of the contract and the corpus pins its
+-- shape.
+
+local T = require 'feature.secrets.plugin.types'
+local Cap = require 'feature.secrets.plugin.capability'
+local V = require 'feature.secrets.plugin.version'
+local R = require 'feature.secrets.plugin.ref'
+
+local M = {}
+
+local function candidates(byref, refs, name)
+  local out = {}
+  -- A NODE SATISFIES ITS OWN REF (section 11.1), and the graph learned it
+  -- here. Considering only declared capabilities made `resolve` answer
+  -- `absent` about a provider sitting right there and live - section
+  -- 11.4's job is explaining the graph the runtime reconciles.
+  local asref = R.canon(name)
+  -- Sorted refs, so the walk is deterministic in a language whose tables
+  -- have no order at all.
+  for _, ref in ipairs(refs) do
+    local node = byref[ref]
+    -- The ref match WINS OUTRIGHT for that node, as at runtime: one
+    -- candidate, not two, for a node both named `b` and providing `b`.
+    if ref == asref then
+      out[#out + 1] = T.map {
+        ref = T.getv(node, 'ref'),
+        pos = T.getv(node, 'pos') or 0,
+        provides = T.map { name = name },
+      }
+      goto continue
+    end
+    local provides = T.getv(node, 'provides') or T.list {}
+    for i = 1, T.len(provides) do
+      local prov = provides[i]
+      if T.same(T.getv(prov, 'name'), name) then
+        out[#out + 1] = T.map {
+          ref = T.getv(node, 'ref'),
+          pos = T.getv(node, 'pos') or 0,
+          provides = prov,
+        }
+      end
+    end
+    ::continue::
+  end
+  return T.list(out)
+end
+
+local function unmet(node, name, why)
+  return T.map { ref = T.getv(node, 'ref'), unmet = name, why = why }
+end
+
+local function firstunmet(node, byref, refs, resolved)
+  local requires = T.getv(node, 'requires') or T.list {}
+  for i = 1, T.len(requires) do
+    local req = requires[i]
+    if not T.truthy(T.getv(req, 'optional')) then
+      local name = T.getv(req, 'name')
+      local all = candidates(byref, refs, name)
+      if 0 == #all then
+        return unmet(node, name, T.map { kind = 'absent' })
+      end
+
+      local ok = Cap.resolve_capability(req, all)
+      if 0 < #ok then
+        -- A provider exists and matches - but if none of them is itself
+        -- resolved, this node is blocked BEHIND it, and the chain is the
+        -- useful answer rather than "unmet".
+        local any = false
+        for j = 1, #ok do
+          if resolved[T.getv(ok[j], 'ref')] then any = true break end
+        end
+        if not any then
+          local chain = {}
+          for j = 1, #ok do chain[#chain + 1] = T.getv(ok[j], 'ref') end
+          table.sort(chain)
+          return unmet(node, name,
+                       T.map { kind = 'blocked', chain = T.list(chain) })
+        end
+      else
+        -- Providers exist and none matched. Say which test failed.
+        local range = T.getv(req, 'range')
+        if nil ~= range then
+          local versions = {}
+          for j = 1, #all do
+            local have = T.getv(T.getv(all[j], 'provides'), 'version')
+            if nil == have or not V.satisfiesq(have, range) then
+              versions[#versions + 1] = have or '(none)'
+            end
+          end
+          if 0 < #versions then
+            table.sort(versions)
+            return unmet(node, name, T.map {
+              kind = 'version', range = range, found = T.list(versions),
+            })
+          end
+        end
+
+        local want = T.getv(req, 'match')
+        if nil ~= want then
+          for j = 1, #all do
+            local attrs = T.getv(T.getv(all[j], 'provides'), 'attrs') or T.map {}
+            for _, k in ipairs(T.keys(want)) do
+              if not (T.has(attrs, k) and Cap.matchvalue(want[k], attrs[k])) then
+                -- `T.has(attrs, k) and attrs[k] or T.NULL` would report a
+                -- present FALSE as a null: lua's `and`/`or` is not a
+                -- ternary when the middle term can be false, and
+                -- `graph/blocked#match` is exactly that case.
+                local found = T.NULL
+                if T.has(attrs, k) then found = attrs[k] end
+                return unmet(node, name, T.map {
+                  kind = 'match', failing = k, want = want[k], found = found,
+                })
+              end
+            end
+          end
+        end
+
+        return unmet(node, name, T.map { kind = 'absent' })
+      end
+    end
+  end
+  return nil
+end
+
+function M.resolve_graph(nodes)
+  local byref = {}
+  local refs = {}
+  for i = 1, T.len(nodes) do
+    local ref = T.getv(nodes[i], 'ref')
+    byref[ref] = nodes[i]
+    refs[#refs + 1] = ref
+  end
+  table.sort(refs)
+
+  local resolved = {}
+  local blocked = {}
+
+  -- Fixed point: a node resolves when every mandatory requirement is met
+  -- by an ALREADY-RESOLVED provider. Iterating to a fixed point is what
+  -- makes a provider that is itself blocked propagate, rather than each
+  -- node being judged against the raw registry.
+  local moved = true
+  while moved do
+    moved = false
+    for i = 1, T.len(nodes) do
+      local n = nodes[i]
+      local ref = T.getv(n, 'ref')
+      if not resolved[ref] and nil == firstunmet(n, byref, refs, resolved) then
+        resolved[ref] = true
+        moved = true
+      end
+    end
+  end
+
+  for i = 1, T.len(nodes) do
+    local n = nodes[i]
+    local ref = T.getv(n, 'ref')
+    if not resolved[ref] then
+      local why = firstunmet(n, byref, refs, resolved)
+      if nil ~= why then blocked[ref] = why end
+    end
+  end
+
+  local resolvedout = {}
+  for _, ref in ipairs(refs) do
+    if resolved[ref] then resolvedout[#resolvedout + 1] = ref end
+  end
+  local blockedout = {}
+  for _, ref in ipairs(refs) do
+    if nil ~= blocked[ref] then blockedout[#blockedout + 1] = blocked[ref] end
+  end
+
+  return T.map { resolved = T.list(resolvedout), blocked = T.list(blockedout) }
+end
+
+return M