@voxgig/sdkgen 4.8.1 → 4.8.3

package/project/.sdk/tm/ts/src/feature/secrets/plugin/Order.ts

@@ -0,0 +1,177 @@
+// VENDORED: @voxgig/plugin 0.1.6 (typescript/src/Order.ts)
+// Source: https://github.com/voxgig/plugin @ 8d8968afc0a2008fbd795b41ab166307d989f02a  [tag: sdk-20260904-1610-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. */
+
+import { OrderBlock, OrderRef, OrderSpec, fail } from './Types'
+import { parseref } from './Ref'
+
+export type Binding = {
+  ref: string
+  pos: number
+  order?: OrderBlock
+}
+
+/** Where a host has pinned a binding. Positional, not ordinal: §6.2
+ * composes b1(b2(b3(base))) with the FIRST binding OUTERMOST, so
+ * `first` and `innermost` are opposites, and a pin spelled in sort
+ * terms would be read backwards by exactly the people it protects. */
+export type Pin = { [name: string]: 'outermost' | 'innermost' | 'first' | 'last' }
+
+export function resolveorder(bindings: Binding[], pin?: Pin): string[] {
+  const nodes = bindings.slice()
+  const byref: { [ref: string]: Binding } = {}
+  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: { [from: string]: string[] } = {}
+  for (const b of nodes) edges[b.ref] = []
+
+  for (const b of nodes) {
+    const o = b.order || {}
+    // An empty list declares no constraint, so it must not be treated as one.
+    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: { [ref: string]: number } = {}
+  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: string[] = []
+  const ready = nodes.filter((b) => 0 === indeg[b.ref])
+
+  while (0 < ready.length) {
+    ready.sort(rank)
+    const next = ready.shift() as Binding
+    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: Binding, b: Binding): number {
+  const ab = band(a), bb = band(b)
+  if (ab !== bb) return ab - bb
+  return a.pos - b.pos
+}
+
+function band(b: Binding): number {
+  const o = b.order || {}
+  return 'number' === typeof o.band ? o.band : 0
+}
+
+/** Was a constraint actually declared? An ABSENT one and an EMPTY LIST
+ * are both "no constraint"; only a non-empty spelling is an edge. */
+function declared(spec?: OrderSpec): spec is OrderRef {
+  return Array.isArray(spec) ? 0 < spec.length : null != spec && '' !== spec
+}
+
+/** Matching is by REF, or by NAME across all of that definition's
+ * instances (§7) — which is the whole reason the two spellings exist. */
+function targets(spec: OrderRef, nodes: Binding[]): string[] {
+  const hit: string[] = []
+  // 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. Station's transport adapter must sit immediately
+ * outside the base transport; an `order` list that moves it has to be
+ * an error rather than a preference. */
+function applypin(order: string[], edges: { [from: string]: string[] }, pin?: Pin): string[] {
+  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. Sorted is the one order every language agrees
+  // on, and `order/pin#two-names` pins it.
+  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: { [ref: string]: number } = {}
+  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
+}

package/project/.sdk/tm/ts/src/feature/secrets/plugin/Point.ts

@@ -0,0 +1,119 @@
+// VENDORED: @voxgig/plugin 0.1.6 (typescript/src/Point.ts)
+// Source: https://github.com/voxgig/plugin @ 8d8968afc0a2008fbd795b41ab166307d989f02a  [tag: sdk-20260904-1610-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. */
+
+import { fail } from './Types'
+
+export type Kind = 'hook' | 'chain' | 'provider'
+
+/** §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. */
+export type Mode = 'emit' | 'parallel' | 'serial' | 'bail'
+
+export type Spec = {
+  kind?: Kind
+  mode?: Mode
+  /** `chain` only: the host owns the base, and a plugin cannot replace
+   * it (§6.2). One that wants to SUBSTITUTE rather than wrap binds
+   * innermost and simply does not call `next`. */
+  base?: (...args: any[]) => any
+  /** `provider` only: a second binding is an error rather than a
+   * shadow. */
+  exclusive?: boolean
+  /** `provider` only: the host's fallback. */
+  default?: any
+  pin?: { [name: string]: 'outermost' | 'innermost' | 'first' | 'last' }
+}
+
+export type Bound = {
+  ref: string
+  point: string
+  fn: any
+  /** `provider` ranks by HIGHEST band, unlike hook and chain which run
+   * lowest first. Kept as declared so the two rules stay visibly
+   * different rather than one being derived from the other by a reader
+   * who then gets it backwards. */
+  band: number
+}
+
+/** Fan-out. Return values are ignored except in `bail`. */
+export function emit(bindings: Bound[], mode: Mode, arg: any): any {
+  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: any[] = []
+  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. */
+export function compose(bindings: Bound[], base: (...args: any[]) => any): (...args: any[]) => any {
+  let next = base
+  for (let i = bindings.length - 1; 0 <= i; i--) {
+    const fn = bindings[i].fn
+    const inner = next
+    next = (...args: any[]) => 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. */
+export function provider(bindings: Bound[], spec: Spec): { winner?: Bound, shadowed: string[] } {
+  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) }
+}

package/project/.sdk/tm/ts/src/feature/secrets/plugin/Ref.ts

@@ -0,0 +1,102 @@
+// VENDORED: @voxgig/plugin 0.1.6 (typescript/src/Ref.ts)
+// Source: https://github.com/voxgig/plugin @ 8d8968afc0a2008fbd795b41ab166307d989f02a  [tag: sdk-20260904-1610-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. */
+
+import { Ref, fail } from './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
+
+export function checkname(name: string): boolean {
+  if ('string' !== typeof name) return false
+  if (0 === name.length || MAX < name.length) return false
+  return NAME_RE.test(name)
+}
+
+export function checktag(tag: string): boolean {
+  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 ''. */
+export function parseref(str: string): Ref {
+  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. */
+export function formatref(name: string, tag?: string): string {
+  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. */
+export function canonref(str: string): string {
+  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 at the first requirement whose name no ref
+ * could have. Answering `undefined` is the whole difference. */
+export function tryref(str: string): string | undefined {
+  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
+}

package/project/.sdk/tm/ts/src/feature/secrets/plugin/Resolve.ts

@@ -0,0 +1,61 @@
+// VENDORED: @voxgig/plugin 0.1.6 (typescript/src/Resolve.ts)
+// Source: https://github.com/voxgig/plugin @ 8d8968afc0a2008fbd795b41ab166307d989f02a  [tag: sdk-20260904-1610-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.
+ *
+ * The corpus `resolve` section arrives with P2. */
+
+export type Source =
+  | { kind: 'module', prefix?: string[] }
+  | { kind: 'path', dir: string }
+
+export function resolvecandidates(name: string, sources?: Source[]): string[] {
+  const out: string[] = []
+
+  // 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
+}
+
+const DEFAULT_SOURCES: Source[] = [
+  { kind: 'module', prefix: ['@voxgig/plugin-', 'voxgig-plugin-', 'plugin-', ''] },
+]
+
+/** 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. */
+export function resolvefrom(from: string): string[] {
+  return [from]
+}

package/project/.sdk/tm/ts/src/feature/secrets/plugin/Types.ts

@@ -0,0 +1,112 @@
+// VENDORED: @voxgig/plugin 0.1.6 (typescript/src/Types.ts)
+// Source: https://github.com/voxgig/plugin @ 8d8968afc0a2008fbd795b41ab166307d989f02a  [tag: sdk-20260904-1610-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. */
+
+/** The two halves of an identity (§4). `tag` is '' when absent — never
+ * null and never missing, because a port returning three shapes for two
+ * states makes every downstream comparison a special case. */
+export type Ref = { name: string, tag: string }
+
+/** §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. */
+export type Status =
+  'declared' | 'loaded' | 'pending' | 'live' | 'failed' | 'loading' | 'closing'
+
+/** A normalized instance entry. Option data is NOT merged here — see
+ * `optionlayers`. */
+export type Instance = {
+  pos: number
+  active: boolean
+  start: 'eager' | 'lazy'
+  order?: OrderBlock
+  /** Levels 3-6 that are present, IN LADDER ORDER (§9.3).
+   *
+   * Normalization does not merge these, and cannot: §9.4 makes merge
+   * behaviour a property of the definition's option shape, which
+   * normalization has never seen. Flattening them here would make
+   * `$MERGE: append` unimplementable at load time, because the layers
+   * it must concatenate would already be collapsed. */
+  optionlayers: any[]
+}
+
+/** §4.4 of DOCS.md — `band` rather than a nested `order`, because
+ * `order.order` needs explaining every time it is read. */
+/** `before`/`after` accept ONE spelling or a LIST of them. The list form
+ * is not decoration: a host may need a binding after two unrelated others,
+ * and station's per-feature `order` has carried string lists since Stage 3b.
+ * Plugin typed this as a bare string and matched with `===`, so a list was
+ * SILENTLY DROPPED - the sort came out exactly as if no constraint had been
+ * declared, with nothing raised. */
+export type OrderRef = string | string[]
+
+/** What a NORMALIZED block may hold, which is wider than what constrains
+ * anything. Normalization is a carrier, not an interpreter (§9.1): the
+ * block comes back exactly as authored, so a value written `null` is still
+ * `null` here, and `config/normorder#null-survives` pins that. Typing it
+ * as `OrderRef | undefined` told callers a runtime null was impossible
+ * while `Config.ts` assigned one straight through `any`. `declared()` is
+ * the gate that turns a spec into a constraint; nothing else may assume
+ * one. */
+export type OrderSpec = OrderRef | null
+
+export type OrderBlock = { before?: OrderSpec, after?: OrderSpec, band?: number }
+
+export type Normalized = {
+  instance: { [ref: string]: Instance }
+  order: string[]
+  default: { [name: string]: any }
+}
+
+/** §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. */
+export 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. */
+export function formaterror(code: string, text: string, details?: { [k: string]: any }): string {
+  const d = details || {}
+  const parts: string[] = []
+  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. */
+export class PluginError extends Error {
+  code: string
+  text: string
+  details: { [k: string]: any }
+  constructor(code: string, text: string, details?: { [k: string]: any }) {
+    super(formaterror(code, text, details))
+    this.name = 'PluginError'
+    this.code = code
+    this.text = text
+    this.details = details || {}
+  }
+}
+
+export function fail(code: string, text: string, details?: any): never {
+  throw new PluginError(code, text, details)
+}

package/project/.sdk/tm/ts/src/feature/secrets/plugin/Version.ts

@@ -0,0 +1,100 @@
+// VENDORED: @voxgig/plugin 0.1.6 (typescript/src/Version.ts)
+// Source: https://github.com/voxgig/plugin @ 8d8968afc0a2008fbd795b41ab166307d989f02a  [tag: sdk-20260904-1610-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. */
+
+import { fail } from './Types'
+
+export type Range = { lo: number[], hi: number[] }
+
+const VERSION_RE = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/
+
+/** A COMPONENT IS BOUNDED, like a ref is (§4's 1024).
+ *
+ * The grammar admits an unbounded digit sequence, and every language
+ * then disagrees about what happens past its integer range: JavaScript
+ * silently loses precision, Go's `Atoi` errors (and a port ignoring that
+ * gets 0), C overflows, Python is exact. `satisfies("0",
+ * "9223372036854775808")` was false in the canonical and true in go —
+ * from the same corpus.
+ *
+ * 2^31-1 because every port has a signed 32-bit integer, and no real
+ * version has ever needed more. Stated rather than left to arithmetic
+ * nobody agrees on. Found by review of the go port. */
+const COMPONENT_MAX = 2147483647
+
+/** 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
+ */
+export function parserange(range: string): 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 }
+}
+
+export function parseversion(version: string): number[] {
+  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'),
+  ]
+}
+
+/** One component, bounded. `plugin_bad_range` either way — the same code
+ * the rest of the grammar's failures use, because "this is not a version
+ * I can compare" is one fact however it went wrong. */
+function component(digits: string, whole: string, field: string): number {
+  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
+}
+
+/** The one satisfaction predicate: lo <= version < hi. */
+export function satisfies(version: string, range: string): boolean {
+  const v = parseversion(version)
+  const r = parserange(range)
+  return 0 <= cmp(v, r.lo) && 0 > cmp(v, r.hi)
+}
+
+export function cmp(a: number[], b: number[]): number {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1
+  }
+  return 0
+}