@voxgig/sdkgen 4.9.0 → 4.10.0

package/project/.sdk/tm/js/src/feature/secrets/plugin/index.js

@@ -0,0 +1,35 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (javascript/src/index.js)
+// 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 canonical surface `make parity` checks (AGENTS.md §4). Small on
+ * purpose (§19): everything else is methods on the host and instance
+ * types, because a library that grows a second public entry point per
+ * feature is a library twenty ports pay for twice. */
+
+'use strict'
+
+const { makehost } = require('./host')
+const { makecatalog } = require('./catalog')
+const { parseref, formatref, checkname, checktag, canonref } = require('./ref')
+const { normalizeconfig, resolveoptions, checkshape } = require('./config')
+const { resolveorder } = require('./order')
+const { resolvecandidates, resolvefrom } = require('./resolve')
+const { applyenv, encoderef } = require('./env')
+const { parserange, parseversion, satisfies } = require('./version')
+const { resolvecapability, matches } = require('./capability')
+const { resolvegraph } = require('./graph')
+const { emit, compose, provider } = require('./point')
+const { resolveexport } = require('./export')
+const { PluginError, formaterror, codeof, DETAIL_ORDER, STATUSES } = require('./types')
+
+module.exports = {
+  makehost, makecatalog,
+  parseref, formatref, checkname, checktag, canonref,
+  normalizeconfig, resolveoptions, checkshape,
+  resolveorder, resolvecandidates, resolvefrom,
+  applyenv, encoderef,
+  parserange, parseversion, satisfies,
+  resolvecapability, matches, resolvegraph,
+  emit, compose, provider, resolveexport,
+  PluginError, formaterror, codeof, DETAIL_ORDER, STATUSES,
+}

package/project/.sdk/tm/js/src/feature/secrets/plugin/order.js

@@ -0,0 +1,165 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (javascript/src/order.js)
+// 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 (§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. */
+
+'use strict'
+
+const { fail } = require('./types')
+const { parseref } = require('./ref')
+
+function resolveorder(bindings, pin) {
+  const nodes = bindings.slice()
+  const byref = {}
+  for (const b of nodes) byref[b.ref] = b
+
+  // Constraints are edges. A constraint naming an ABSENT binding is
+  // satisfied VACUOUSLY (§7) — a plugin ordered `after: 'test'` must
+  // load in a host with no test plugin. That is sdkgen's __after__
+  // behaviour, kept.
+  const edges = {}
+  for (const b of nodes) edges[b.ref] = []
+
+  for (const b of nodes) {
+    const o = b.order || {}
+    if (declared(o.after)) for (const t of targets(o.after, nodes)) edges[t].push(b.ref)
+    if (declared(o.before)) for (const t of targets(o.before, nodes)) edges[b.ref].push(t)
+  }
+
+  // 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`.
+  const indeg = {}
+  for (const b of nodes) indeg[b.ref] = 0
+  for (const from of Object.keys(edges)) {
+    for (const to of edges[from]) indeg[to] = (indeg[to] || 0) + 1
+  }
+
+  const out = []
+  const ready = nodes.filter((b) => 0 === indeg[b.ref])
+
+  while (0 < ready.length) {
+    ready.sort(rank)
+    const next = ready.shift()
+    out.push(next.ref)
+    for (const to of edges[next.ref]) {
+      indeg[to] -= 1
+      if (0 === indeg[to]) ready.push(byref[to])
+    }
+  }
+
+  if (out.length !== nodes.length) {
+    const stuck = nodes.filter((b) => -1 === out.indexOf(b.ref)).map((b) => b.ref)
+    fail('plugin_order_cycle',
+      'before/after constraints cycle: ' + stuck.join(' -> '), { cycle: stuck })
+  }
+
+  return applypin(out, edges, pin)
+}
+
+function rank(a, b) {
+  const ab = band(a), bb = band(b)
+  if (ab !== bb) return ab - bb
+  return a.pos - b.pos
+}
+
+function band(b) {
+  const o = b.order || {}
+  return 'number' === typeof o.band ? o.band : 0
+}
+
+/** Matching is by REF, or by NAME across all of that definition's
+ * instances (§7) — which is the whole reason the two spellings exist. */
+/** Was a constraint stated? An absent value and an EMPTY LIST are both
+ * no-constraint - and [] is truthy, which is how this bug survives. */
+function declared(spec) {
+  return Array.isArray(spec) ? spec.some(one => '' !== one) : null != spec && '' !== spec
+}
+
+function targets(spec, nodes) {
+  const hit = []
+  // 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.
+  const specs = Array.isArray(spec) ? spec : [spec]
+  for (const one of specs) {
+    for (const b of nodes) {
+      if (hit.includes(b.ref)) continue
+      if (b.ref === one) { hit.push(b.ref); continue }
+      if (parseref(b.ref).name === one) hit.push(b.ref)
+    }
+  }
+  return hit
+}
+
+/** A PIN IS NOT A CONSTRAINT (§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. */
+function applypin(order, edges, pin) {
+  if (null == pin) return order
+  let out = order.slice()
+
+  // 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 (`{b:'first', a:'first'}` and
+  // `{a:'first', b:'first'}` give different results). JavaScript's
+  // `Object.keys` is insertion order and a Go map has none at all, so
+  // leaving it unstated made the same declaration mean different things
+  // in different ports.
+  for (const name of Object.keys(pin).sort()) {
+    const want = pin[name]
+    const idx = out.findIndex((r) => parseref(r).name === name)
+    if (-1 === idx) continue
+
+    // `first`/`outermost` is index 0; `last`/`innermost` is the end.
+    // §6.2 makes the first chain binding outermost, which is why the
+    // vocabulary is positional and why the two spellings pair this way.
+    const wantfirst = 'first' === want || 'outermost' === want
+    const ref = out[idx]
+    out.splice(idx, 1)
+    if (wantfirst) out.unshift(ref)
+    else out.push(ref)
+  }
+
+  // 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.
+  const at = {}
+  out.forEach((r, i) => { at[r] = i })
+  for (const from of Object.keys(edges)) {
+    for (const to of edges[from]) {
+      if (at[from] > at[to]) {
+        fail('plugin_order_pinned',
+          'a pin would move a binding an ordering constrains: ' +
+          from + ' must precede ' + to,
+          { before: from, after: to })
+      }
+    }
+  }
+
+  return out
+}
+
+module.exports = { resolveorder }

package/project/.sdk/tm/js/src/feature/secrets/plugin/point.js

@@ -0,0 +1,94 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (javascript/src/point.js)
+// 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 (§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. */
+
+'use strict'
+
+const { fail } = require('./types')
+
+/** §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. */
+const MODES = ['emit', 'parallel', 'serial', 'bail']
+
+/** Fan-out. Return values are ignored except in `bail`. */
+function emit(bindings, mode, arg) {
+  if ('bail' === mode) {
+    // Stops at the first binding that RETURNS A VALUE — the "handled,
+    // stop" case. A NULL DECLINES, and so does `undefined`.
+    //
+    // JavaScript can tell the two apart and almost nothing else in the
+    // target set can — Go, Python, Ruby, PHP, Lua, Java and C# each have
+    // exactly one way to say nothing. Making the distinction
+    // load-bearing would cost every one of them a wrapper type carried
+    // through the whole dispatch path, to express a difference their
+    // plugin authors cannot write. §18's budget settles it (§6.1).
+    for (const b of bindings) {
+      const v = b.fn(arg)
+      if (null != v) return v
+    }
+    return undefined
+  }
+
+  const errors = []
+  for (const b of bindings) {
+    try { b.fn(arg) }
+    catch (err) {
+      // `emit` raises synchronously; the collecting modes gather.
+      if ('emit' === mode) throw err
+      errors.push(err)
+    }
+  }
+  return 'emit' === mode ? undefined : errors
+}
+
+/** Composition: b1(b2(b3(base))), FIRST BINDING OUTERMOST (§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 compose(bindings, base) {
+  let next = base
+  for (let i = bindings.length - 1; 0 <= i; i--) {
+    const fn = bindings[i].fn
+    const inner = next
+    next = (...args) => fn(inner, ...args)
+  }
+  return next
+}
+
+/** At most one live implementation (§6.3). The winner is the highest
+ * band, ties broken by ref sort, and THE LOSERS ARE VISIBLE rather than
+ * silently ignored. */
+function provider(bindings, spec) {
+  if (0 === bindings.length) return { shadowed: [] }
+
+  if (spec.exclusive && 1 < bindings.length) {
+    const refs = bindings.map((b) => b.ref).sort()
+    fail('plugin_point_exclusive',
+      'point is exclusive and has ' + bindings.length + ' bindings: ' + refs.join(', '),
+      { refs })
+  }
+
+  const ranked = bindings.slice().sort((a, b) => {
+    if (a.band !== b.band) return b.band - a.band     // HIGHEST band wins
+    return a.ref < b.ref ? -1 : a.ref > b.ref ? 1 : 0
+  })
+
+  return { winner: ranked[0], shadowed: ranked.slice(1).map((b) => b.ref) }
+}
+
+module.exports = { MODES, emit, compose, provider }

package/project/.sdk/tm/js/src/feature/secrets/plugin/ref.js

@@ -0,0 +1,106 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (javascript/src/ref.js)
+// 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` (§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. */
+
+'use strict'
+
+const { fail } = require('./types')
+
+/** §4: `^[a-zA-Z@][a-zA-Z0-9.~_\-/]*$`, max 1024. */
+const NAME_RE = /^[a-zA-Z@][a-zA-Z0-9.~_\-\/]*$/
+
+/** §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. */
+const TAG_RE = /^[a-zA-Z0-9.~_-]+$/
+
+const MAX = 1024
+
+function checkname(name) {
+  if ('string' !== typeof name) return false
+  if (0 === name.length || MAX < name.length) return false
+  return NAME_RE.test(name)
+}
+
+function checktag(tag) {
+  if ('string' !== typeof tag) return false
+  // The empty tag is an ordinary tag (§4 rule 2). The single-instance
+  // case writes no tag and never learns tags exist.
+  if (0 === tag.length) return true
+  if (MAX < tag.length) return false
+  return TAG_RE.test(tag)
+}
+
+/** `name$tag` -> the pair. Canonicalizing: `stripe$` and `stripe` both
+ * give tag ''. */
+function parseref(str) {
+  if ('string' !== typeof str) {
+    fail('plugin_bad_name', 'ref must be a string')
+  }
+
+  // Split on the FIRST `$`. Nothing in the grammar decides this — `$` is
+  // in neither character class — so the corpus is the arbiter (§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.
+  const cut = str.indexOf('$')
+  const name = -1 === cut ? str : str.substring(0, cut)
+  const tag = -1 === cut ? '' : str.substring(cut + 1)
+
+  if (!checkname(name)) {
+    fail('plugin_bad_name', 'invalid plugin name: ' + name, { name })
+  }
+  if (!checktag(tag)) {
+    fail('plugin_bad_tag', 'invalid plugin tag: ' + tag, { name, tag })
+  }
+
+  return { name, tag }
+}
+
+/** The pair -> `name$tag`. An empty tag NEVER writes the separator,
+ * which is the half of canonicalization formatref owns: parse tolerates
+ * `stripe$`, format never produces it, so a round trip is idempotent. */
+function formatref(name, tag) {
+  const t = null == tag ? '' : tag
+  if (!checkname(name)) {
+    fail('plugin_bad_name', 'invalid plugin name: ' + name, { name })
+  }
+  if (!checktag(t)) {
+    fail('plugin_bad_tag', 'invalid plugin tag: ' + t, { name, tag: t })
+  }
+  return '' === t ? name : name + '$' + t
+}
+
+/** The canonical spelling of a ref. §4 rule 5: ports must canonicalize
+ * before comparison. */
+function canonref(str) {
+  const r = parseref(str)
+  return formatref(r.name, r.tag)
+}
+
+/** The canonical ref this string denotes, or `undefined` if it denotes
+ * none — the TOLERANT half of `canonref`, and the one a requirement name
+ * needs.
+ *
+ * A REQUIREMENT NAME IS A CAPABILITY NAME FIRST (§11.1), and capability
+ * names are free-form: the design puts no grammar on them, so `2fa` and
+ * `my cap` are perfectly good ones and neither is a well-formed ref.
+ * `canonref` RAISES on those, so asking it "is this a ref?" made a legal
+ * document kill the host. Answering `undefined` is the whole difference. */
+function tryref(str) {
+  if ('string' !== typeof str) return undefined
+  const cut = str.indexOf('$')
+  const name = -1 === cut ? str : str.substring(0, cut)
+  const tag = -1 === cut ? '' : str.substring(cut + 1)
+  if (!checkname(name) || !checktag(tag)) return undefined
+  return '' === tag ? name : name + '$' + tag
+}
+
+module.exports = { checkname, checktag, parseref, formatref, canonref, tryref }

package/project/.sdk/tm/js/src/feature/secrets/plugin/resolve.js

@@ -0,0 +1,59 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (javascript/src/resolve.js)
+// 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 (§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 §15.4 puts real module loading in per-port integration tests
+ * rather than here. */
+
+'use strict'
+
+const DEFAULT_SOURCES = [
+  { kind: 'module', prefix: ['@voxgig/plugin-', 'voxgig-plugin-', 'plugin-', ''] },
+]
+
+function resolvecandidates(name, sources) {
+  const out = []
+
+  // A SCOPED NAME RESOLVES VERBATIM ONLY (§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.startsWith('@')) return [name]
+
+  const list = sources && 0 < sources.length ? sources : DEFAULT_SOURCES
+
+  for (const src of list) {
+    if ('module' === src.kind) {
+      const prefixes = src.prefix && 0 < src.prefix.length ? src.prefix : ['']
+      for (const p of prefixes) {
+        const id = p + name
+        if (-1 === out.indexOf(id)) out.push(id)
+      }
+    }
+    else if ('path' === src.kind) {
+      const id = src.dir.replace(/\/+$/, '') + '/' + name
+      if (-1 === out.indexOf(id)) out.push(id)
+    }
+  }
+
+  return out
+}
+
+/** A MODULE PATH IS NOT A NAME (§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.
+ *
+ * Loading from an explicit location is a separate field that bypasses
+ * candidate generation entirely: `from` is passed to the resolver
+ * verbatim, and a resolver that cannot honour a location raises
+ * plugin_resolve_failed. */
+function resolvefrom(from) {
+  return [from]
+}
+
+module.exports = { resolvecandidates, resolvefrom }

package/project/.sdk/tm/js/src/feature/secrets/plugin/types.js

@@ -0,0 +1,79 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (javascript/src/types.js)
+// 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.
+/* Shared types. Deliberately small: the design's §19 budget says the
+ * library owns naming, configuration, lifecycle, ordering, binding and
+ * teardown, and nothing else.
+ *
+ * JavaScript is the canonical's own language with the types removed, so
+ * this port is the one place a divergence would be pure carelessness
+ * rather than translation. What it does NOT get for free is the
+ * canonical's compile-time shape checking, which is why the corpus runs
+ * here exactly as it does in a language that shares nothing. */
+
+'use strict'
+
+/** §5.1's seven statuses, and no more. A port that adds an eighth is
+ * diverging. `loading` and `closing` are observable only from inside a
+ * callback or from another thread. */
+const STATUSES = [
+  'declared', 'loaded', 'pending', 'live', 'failed', 'loading', 'closing',
+]
+
+/** §12's detail fields, IN THIS FIXED ORDER.
+ *
+ * The order is part of the contract, not a formatting preference. An
+ * earlier draft named six fields while other sections promised
+ * diagnostics that had nowhere to go, which would have left each port
+ * inventing its own order and breaking message parity. */
+const DETAIL_ORDER = [
+  'host', 'ref', 'name', 'tag', 'point', 'key', 'capability',
+  'range', 'version', 'match', 'candidates', 'cycle', 'holders',
+  'refs', 'path', 'cause',
+]
+
+/** `plugin/<code>: <text> [<key>=<value> …]`
+ *
+ * Values render as COMPACT JSON, so a value containing a space or a
+ * bracket cannot break the parse, and a list renders as a JSON array.
+ * The bracket is absent entirely when no field applies. */
+function formaterror(code, text, details) {
+  const d = details || {}
+  const parts = []
+  for (const k of DETAIL_ORDER) {
+    if (undefined === d[k]) continue
+    parts.push(k + '=' + JSON.stringify(d[k]))
+  }
+  const tail = 0 === parts.length ? '' : ' [' + parts.join(' ') + ']'
+  return 'plugin/' + code + ': ' + text + tail
+}
+
+/** Every error carries a §12 code. Ports compare by CODE and never by
+ * message: wording is a port's own business, and pinning the words would
+ * make every translation a corpus change. The FORMAT, however, is
+ * pinned — a parseable message is what makes a log searchable across
+ * twenty languages. */
+class PluginError extends Error {
+  constructor(code, text, details) {
+    super(formaterror(code, text, details))
+    this.name = 'PluginError'
+    this.code = code
+    this.text = text
+    this.details = details || {}
+  }
+}
+
+function fail(code, text, details) {
+  throw new PluginError(code, text, details)
+}
+
+/** The §12 code of an error, or '' for one this library did not raise.
+ * The corpus compares by code, so the driver needs one place that knows
+ * how to read it. */
+function codeof(err) {
+  return (err && err.code) || ''
+}
+
+module.exports = {
+  STATUSES, DETAIL_ORDER, formaterror, PluginError, fail, codeof,
+}

package/project/.sdk/tm/js/src/feature/secrets/plugin/version.js

@@ -0,0 +1,100 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (javascript/src/version.js)
+// 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.
+/* Versions and ranges (§11.2).
+ *
+ * TWO FIELDS AND ONE PREDICATE. A capability declares `version`, a
+ * concrete version. A requirement declares `range`. A requirement is
+ * satisfied when the names match, the `match` passes, and:
+ *
+ *   the provider's `version` falls inside the requirement's `range`.
+ *
+ * That is the whole rule. There is no third field and no second
+ * comparison — an earlier draft added a provider-side `compat` range,
+ * which left three values and no statement of how they combine, and
+ * three defensible readings of one declaration is worse than the
+ * ambiguity it was introduced to fix. */
+
+'use strict'
+
+const { fail } = require('./types')
+
+const VERSION_RE = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/
+
+// A COMPONENT IS BOUNDED, and the bound is the model's, not the host
+// language's. `Number` stops being exact past 2^53 and other ports carry
+// unbounded integers, so `9223372036854775808.0.0` parsed to a value
+// that compared wrong here and fine elsewhere. 2^31-1 is the smallest
+// bound every target language holds exactly, which makes it the model's.
+const COMPONENT_MAX = 2147483647
+
+function component(digits, whole, field) {
+  const n = Number(digits)
+  if (!Number.isInteger(n) || COMPONENT_MAX < n) {
+    fail('plugin_bad_range',
+      'version component out of range in ' + whole + ': ' + digits,
+      { [field]: whole })
+  }
+  return n
+}
+
+/** Two forms and no more (§11.2):
+ *
+ *   '2.1'    >= 2.1.0 and < 3.0.0
+ *   '~2.1'   >= 2.1.0 and < 2.2.0
+ */
+function parserange(range) {
+  if ('string' !== typeof range || 0 === range.length) {
+    fail('plugin_bad_range', 'invalid range: ' + range, { range })
+  }
+
+  const tilde = range.startsWith('~')
+  const body = tilde ? range.substring(1) : range
+  const m = VERSION_RE.exec(body)
+  if (!m) fail('plugin_bad_range', 'invalid range: ' + range, { range })
+
+  const major = component(m[1], range, 'range')
+  const minor = undefined === m[2] ? 0 : component(m[2], range, 'range')
+  const patch = undefined === m[3] ? 0 : component(m[3], range, 'range')
+
+  const lo = [major, minor, patch]
+  const hi = tilde ? [major, minor + 1, 0] : [major + 1, 0, 0]
+  return { lo, hi }
+}
+
+function parseversion(version) {
+  if ('string' !== typeof version) {
+    fail('plugin_bad_range', 'invalid version: ' + version, { version })
+  }
+  const m = VERSION_RE.exec(version)
+  if (!m) fail('plugin_bad_range', 'invalid version: ' + version, { version })
+  return [
+    component(m[1], version, 'version'),
+    undefined === m[2] ? 0 : component(m[2], version, 'version'),
+    undefined === m[3] ? 0 : component(m[3], version, 'version'),
+  ]
+}
+
+/** The one satisfaction predicate: lo <= version < hi. */
+function satisfies(version, range) {
+  const v = parseversion(version)
+  const r = parserange(range)
+  return 0 <= cmp(v, r.lo) && 0 > cmp(v, r.hi)
+}
+
+/** satisfies for the internal callers that treat an unparseable version
+ * or range as "does not satisfy" — Capability and Graph, both of which
+ * run over data the corpus has already admitted. */
+function satisfiesq(version, range) {
+  try { return satisfies(version, range) }
+  catch (err) { return false }
+}
+
+function cmp(a, b) {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1
+  }
+  return 0
+}
+
+module.exports = { parserange, parseversion, satisfies, satisfiesq, cmp }