@voxgig/sdkgen 4.29.0 → 4.30.1

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

@@ -1,21 +1,6 @@
 // VENDORED: @voxgig/plugin 0.1.6 (typescript/src/Order.ts)
-// Source: https://github.com/voxgig/plugin @ 721de3a1bb5ac879b5c118dd9fc55c474a8730c4  [tag: sdk-20260917-1242-0]
+// Source: https://github.com/voxgig/plugin @ 43acbf266b0dbcf52e5ab5463d85c822da9cd234  [tag: sdk-20260925-1316-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'
@@ -26,10 +11,6 @@ export type Binding = {
   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[] {
@@ -51,9 +32,6 @@ export function resolveorder(bindings: Binding[], pin?: Pin): string[] {
     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)) {
@@ -93,18 +71,12 @@ function band(b: Binding): number {
   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) {
@@ -116,39 +88,15 @@ function targets(spec: OrderRef, nodes: Binding[]): string[] {
   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)

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

@@ -1,26 +1,11 @@
 // VENDORED: @voxgig/plugin 0.1.6 (typescript/src/Point.ts)
-// Source: https://github.com/voxgig/plugin @ 721de3a1bb5ac879b5c118dd9fc55c474a8730c4  [tag: sdk-20260917-1242-0]
+// Source: https://github.com/voxgig/plugin @ 43acbf266b0dbcf52e5ab5463d85c822da9cd234  [tag: sdk-20260925-1316-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 = {
@@ -42,25 +27,12 @@ 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
@@ -80,13 +52,6 @@ export function emit(bindings: Bound[], mode: Mode, arg: any): any {
   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--) {
@@ -97,9 +62,6 @@ export function compose(bindings: Bound[], base: (...args: any[]) => any): (...a
   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: [] }
 
@@ -111,7 +73,7 @@ export function provider(bindings: Bound[], spec: Spec): { winner?: Bound, shado
   }
 
   const ranked = bindings.slice().sort((a, b) => {
-    if (a.band !== b.band) return b.band - a.band     // HIGHEST band wins
+    if (a.band !== b.band) return b.band - a.band
     return a.ref < b.ref ? -1 : a.ref > b.ref ? 1 : 0
   })
 

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

@@ -1,22 +1,11 @@
 // VENDORED: @voxgig/plugin 0.1.6 (typescript/src/Ref.ts)
-// Source: https://github.com/voxgig/plugin @ 721de3a1bb5ac879b5c118dd9fc55c474a8730c4  [tag: sdk-20260917-1242-0]
+// Source: https://github.com/voxgig/plugin @ 43acbf266b0dbcf52e5ab5463d85c822da9cd234  [tag: sdk-20260925-1316-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
@@ -36,17 +25,11 @@ export function checktag(tag: string): boolean {
   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)
@@ -61,9 +44,6 @@ export function parseref(str: string): Ref {
   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)) {
@@ -82,16 +62,6 @@ export function canonref(str: string): string {
   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('$')

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

@@ -1,15 +1,6 @@
 // VENDORED: @voxgig/plugin 0.1.6 (typescript/src/Resolve.ts)
-// Source: https://github.com/voxgig/plugin @ 721de3a1bb5ac879b5c118dd9fc55c474a8730c4  [tag: sdk-20260917-1242-0]
+// Source: https://github.com/voxgig/plugin @ 43acbf266b0dbcf52e5ab5463d85c822da9cd234  [tag: sdk-20260925-1316-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[] }
@@ -46,16 +37,6 @@ 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

@@ -1,18 +1,9 @@
 // VENDORED: @voxgig/plugin 0.1.6 (typescript/src/Types.ts)
-// Source: https://github.com/voxgig/plugin @ 721de3a1bb5ac879b5c118dd9fc55c474a8730c4  [tag: sdk-20260917-1242-0]
+// Source: https://github.com/voxgig/plugin @ 43acbf266b0dbcf52e5ab5463d85c822da9cd234  [tag: sdk-20260925-1316-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'
 
@@ -23,34 +14,11 @@ export type Instance = {
   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 }
@@ -61,12 +29,6 @@ export type Normalized = {
   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',
@@ -89,11 +51,6 @@ export function formaterror(code: string, text: string, details?: { [k: string]:
   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

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

@@ -1,19 +1,6 @@
 // VENDORED: @voxgig/plugin 0.1.6 (typescript/src/Version.ts)
-// Source: https://github.com/voxgig/plugin @ 721de3a1bb5ac879b5c118dd9fc55c474a8730c4  [tag: sdk-20260917-1242-0]
+// Source: https://github.com/voxgig/plugin @ 43acbf266b0dbcf52e5ab5463d85c822da9cd234  [tag: sdk-20260925-1316-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'
 
@@ -21,25 +8,8 @@ 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 })
@@ -72,9 +42,6 @@ export function parseversion(version: string): number[] {
   ]
 }
 
-/** 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) {

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

@@ -1,10 +1,6 @@
 // VENDORED: @voxgig/plugin 0.1.6 (typescript/src/index.ts)
-// Source: https://github.com/voxgig/plugin @ 721de3a1bb5ac879b5c118dd9fc55c474a8730c4  [tag: sdk-20260917-1242-0]
+// Source: https://github.com/voxgig/plugin @ 43acbf266b0dbcf52e5ab5463d85c822da9cd234  [tag: sdk-20260925-1316-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. */
 
 export { makehost } from './Host'
 export { makecatalog } from './Catalog'