@voxgig/sdkgen 4.8.3 → 4.10.0

package/project/.sdk/tm/kotlin/feature/secrets/plugin/Json.kt

@@ -0,0 +1,241 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (kotlin/src/Json.kt)
+// 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.
+package KOTLINPACKAGE.feature.secrets.plugin
+
+import java.util.TreeMap
+
+/**
+ * The JSON parser and writer, and the only ones this port has.
+ *
+ * NO JACKSON, NO GSON, NO KOTLINX.SERIALIZATION, NO JUNIT (section 16). The
+ * library is allowed exactly one runtime dependency, `voxgig/struct`, which
+ * has no kotlin port; everything else is the kotlin stdlib and the JDK.
+ * Parsing the corpus is a hundred and fifty lines, and a hundred and fifty
+ * lines is cheaper than a gradle `dependencies` block every embedding host
+ * inherits - and it keeps this port buildable by `kotlinc` alone.
+ */
+object Json {
+
+    fun parse(text: String): Any? {
+        val parser = Parser(text)
+        parser.skipws()
+        val value = parser.value()
+        parser.skipws()
+        if (parser.at < parser.chars.size) {
+            throw IllegalArgumentException("trailing input at ${parser.at}")
+        }
+        return value
+    }
+
+    /** Compact JSON, map keys in sorted order (which a `TreeMap` already is). */
+    fun write(value: Any?): String {
+        val out = StringBuilder()
+        writeTo(value, out)
+        return out.toString()
+    }
+
+    private fun writeTo(value: Any?, out: StringBuilder) {
+        when (value) {
+            null -> out.append("null")
+            is Boolean -> out.append(if (value) "true" else "false")
+            is Double -> out.append(writeNumber(value))
+            is Int -> out.append(value.toString())
+            is String -> writeString(value, out)
+            is List<*> -> {
+                out.append('[')
+                value.forEachIndexed { i, v ->
+                    if (0 < i) out.append(',')
+                    writeTo(v, out)
+                }
+                out.append(']')
+            }
+            is Map<*, *> -> {
+                out.append('{')
+                Types.keys(value).forEachIndexed { i, k ->
+                    if (0 < i) out.append(',')
+                    writeString(k, out)
+                    out.append(':')
+                    writeTo(value[k], out)
+                }
+                out.append('}')
+            }
+            // Anything the model has no JSON spelling for - a host, an
+            // instance handle, a callback the driver exported.
+            else -> out.append("\"(opaque)\"")
+        }
+    }
+
+    /**
+     * A whole double renders WITHOUT its fraction, so `1.0` and `1` spell the
+     * same. Every number in this port is a `Double`, so without this every
+     * message and every encoded expectation would read `1.0` where the
+     * corpus wrote `1`.
+     */
+    private fun writeNumber(value: Double): String =
+        if (value == Math.floor(value) && !value.isInfinite()) {
+            value.toLong().toString()
+        } else {
+            value.toString()
+        }
+
+    private fun writeString(value: String, out: StringBuilder) {
+        out.append('"')
+        for (c in value) {
+            when {
+                '"' == c -> out.append("\\\"")
+                CHAR_BACKSLASH == c -> out.append("\\\\")
+                CHAR_NEWLINE == c -> out.append("\\n")
+                CHAR_RETURN == c -> out.append("\\r")
+                CHAR_TAB == c -> out.append("\\t")
+                c < CHAR_SPACE -> out.append("\\u%04x".format(codeOf(c)))
+                else -> out.append(c)
+            }
+        }
+        out.append('"')
+    }
+
+    // `Char.code` is Kotlin 1.5+ and does not resolve on the 1.3.31 ubuntu
+    // ships to CI; `Char.toInt()` is deprecated from 1.5 and the Makefile
+    // builds -Werror. `Char.minus(Char)` has been Int since 1.0 and is
+    // deprecated in neither, so it is the one spelling both compilers take.
+    private fun codeOf(c: Char): Int = c - '\u0000'
+
+    private const val CHAR_SPACE = '\u0020'
+
+    private const val CHAR_BACKSLASH = '\u005C'
+    private const val CHAR_NEWLINE = '\u000A'
+    private const val CHAR_RETURN = '\u000D'
+    private const val CHAR_TAB = '\u0009'
+    private const val CHAR_BACKSPACE = '\u0008'
+    private const val CHAR_FORMFEED = '\u000C'
+
+    private class Parser(text: String) {
+        val chars: CharArray = text.toCharArray()
+        var at: Int = 0
+
+        fun skipws() {
+            while (at < chars.size &&
+                (' ' == chars[at] || CHAR_TAB == chars[at] ||
+                    CHAR_NEWLINE == chars[at] || CHAR_RETURN == chars[at])
+            ) {
+                at++
+            }
+        }
+
+        fun value(): Any? = when (chars[at]) {
+            '{' -> map()
+            '[' -> list()
+            '"' -> string()
+            't' -> literal("true", true)
+            'f' -> literal("false", false)
+            'n' -> literal("null", null)
+            else -> number()
+        }
+
+        fun literal(word: String, value: Any?): Any? {
+            if (at + word.length > chars.size ||
+                String(chars, at, word.length) != word
+            ) {
+                throw IllegalArgumentException("unexpected input at $at")
+            }
+            at += word.length
+            return value
+        }
+
+        fun map(): Map<String, Any?> {
+            val out = TreeMap<String, Any?>()
+            at++
+            skipws()
+            if ('}' == chars[at]) {
+                at++
+                return out
+            }
+            while (true) {
+                skipws()
+                val key = string()
+                skipws()
+                if (':' != chars[at]) throw IllegalArgumentException("expected : at $at")
+                at++
+                skipws()
+                out[key] = value()
+                skipws()
+                if (',' == chars[at]) {
+                    at++
+                    continue
+                }
+                if ('}' != chars[at]) throw IllegalArgumentException("expected } at $at")
+                at++
+                return out
+            }
+        }
+
+        fun list(): List<Any?> {
+            val out = ArrayList<Any?>()
+            at++
+            skipws()
+            if (']' == chars[at]) {
+                at++
+                return out
+            }
+            while (true) {
+                skipws()
+                out.add(value())
+                skipws()
+                if (',' == chars[at]) {
+                    at++
+                    continue
+                }
+                if (']' != chars[at]) throw IllegalArgumentException("expected ] at $at")
+                at++
+                return out
+            }
+        }
+
+        fun string(): String {
+            if ('"' != chars[at]) throw IllegalArgumentException("expected string at $at")
+            at++
+            val out = StringBuilder()
+            while (true) {
+                if (at >= chars.size) throw IllegalArgumentException("unterminated string")
+                val c = chars[at]
+                if ('"' == c) {
+                    at++
+                    return out.toString()
+                }
+                if (CHAR_BACKSLASH == c) {
+                    at++
+                    val e = chars[at]
+                    when (e) {
+                        'n' -> out.append(CHAR_NEWLINE)
+                        't' -> out.append(CHAR_TAB)
+                        'r' -> out.append(CHAR_RETURN)
+                        'b' -> out.append(CHAR_BACKSPACE)
+                        'f' -> out.append(CHAR_FORMFEED)
+                        'u' -> {
+                            out.append(String(chars, at + 1, 4).toInt(16).toChar())
+                            at += 4
+                        }
+                        else -> out.append(e)
+                    }
+                    at++
+                    continue
+                }
+                out.append(c)
+                at++
+            }
+        }
+
+        fun number(): Double {
+            val start = at
+            while (at < chars.size &&
+                (chars[at].isDigit() || '-' == chars[at] || '+' == chars[at] ||
+                    '.' == chars[at] || 'e' == chars[at] || 'E' == chars[at])
+            ) {
+                at++
+            }
+            if (start == at) throw IllegalArgumentException("unexpected input at $at")
+            return String(chars, start, at - start).toDouble()
+        }
+    }
+}

package/project/.sdk/tm/kotlin/feature/secrets/plugin/Order.kt

@@ -0,0 +1,180 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (kotlin/src/Order.kt)
+// 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.
+package KOTLINPACKAGE.feature.secrets.plugin
+
+/**
+ * Ordering (section 7) - one rule, one place.
+ *
+ * sdkgen grew two special cases in `makeOptions` (`test`, then `station`) and
+ * the third was not far off. This sort is the whole replacement, and the
+ * tiers are in this order for a reason:
+ *
+ *   1 constraints   before/after edges, by ref or by name
+ *   2 bands         integer, lower first, default 0
+ *   3 declaration   ties break by `pos`
+ *
+ * CONSTRAINTS BEAT BANDS precisely so the correct tool wins when both are
+ * present. A band expresses a genuine cross-cutting layer; a constraint
+ * expresses a relationship between two specific things; and a band chosen by
+ * trial and error to fix an ordering bug is a bug wearing a number.
+ */
+
+/** One node of the sort. An internal shape, never a corpus value. */
+data class OrderNode(val ref: String, val pos: Int, val order: Any?)
+
+object Order {
+
+    fun orderBand(b: OrderNode): Int =
+        Types.asInt(Types.get(b.order ?: emptyMap<String, Any?>(), "band")) ?: 0
+
+    /**
+     * Was a constraint stated? An absent value and an EMPTY LIST are both
+     * no-constraint - and an empty list is TRUTHY in most languages, which is
+     * exactly how this class of bug survives a reading.
+     */
+    fun orderDeclared(spec: Any?): Boolean = when {
+        null == spec -> false
+        spec is List<*> -> spec.any { "" != it }
+        else -> "" != spec
+    }
+
+    /**
+     * One spelling or a LIST of them. A list fans out to the UNION of what
+     * each names, so after: ['a','b'] means after BOTH, and the same instance
+     * named twice - once by name, once by ref - is one edge.
+     *
+     * Matching is by REF, or by NAME across all of that definition's
+     * instances (section 7) - which is the whole reason the two spellings
+     * exist.
+     */
+    fun orderTargets(spec: Any?, nodes: List<OrderNode>): List<String> {
+        val specs = if (spec is List<*>) spec else listOf(spec)
+        val hit = ArrayList<String>()
+        for (one in specs) {
+            for (b in nodes) {
+                if (hit.contains(b.ref)) continue
+                if (b.ref == one || Refs.refName(b.ref) == one) hit.add(b.ref)
+            }
+        }
+        return hit
+    }
+
+    @JvmOverloads
+    fun resolveOrder(bindings: List<OrderNode>, pin: Any? = null): List<String> {
+        val byref = bindings.associateBy { it.ref }
+
+        // Constraints are edges. A constraint naming an ABSENT binding is
+        // satisfied VACUOUSLY (section 7) - a plugin ordered `after: 'test'`
+        // must load in a host with no test plugin. That is sdkgen's __after__
+        // behaviour, kept.
+        val edges = HashMap<String, MutableList<String>>()
+        for (b in bindings) edges[b.ref] = ArrayList()
+
+        for (b in bindings) {
+            val block = b.order ?: emptyMap<String, Any?>()
+            if (orderDeclared(Types.get(block, "after"))) {
+                for (target in orderTargets(Types.get(block, "after"), bindings)) {
+                    edges[target]!!.add(b.ref)
+                }
+            }
+            if (orderDeclared(Types.get(block, "before"))) {
+                edges[b.ref]!!.addAll(orderTargets(Types.get(block, "before"), bindings))
+            }
+        }
+
+        val indeg = HashMap<String, Int>()
+        for (b in bindings) indeg[b.ref] = 0
+        for (tos in edges.values) {
+            for (to in tos) indeg[to] = indeg[to]!! + 1
+        }
+
+        // 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`.
+        val out = ArrayList<String>()
+        var ready = bindings.filter { 0 == indeg[it.ref] }.toMutableList()
+
+        while (ready.isNotEmpty()) {
+            ready = Types.stableSortBy(ready) { listOf(orderBand(it), it.pos) }.toMutableList()
+            val next = ready.removeAt(0)
+            out.add(next.ref)
+            for (to in edges[next.ref]!!) {
+                indeg[to] = indeg[to]!! - 1
+                if (0 == indeg[to]) ready.add(byref[to]!!)
+            }
+        }
+
+        if (out.size != bindings.size) {
+            val stuck = bindings.filter { !out.contains(it.ref) }.map { it.ref }
+            Types.fail(
+                "plugin_order_cycle",
+                "before/after constraints cycle: ${stuck.joinToString(" -> ")}",
+                mapOf("cycle" to stuck)
+            )
+        }
+
+        return applyPin(out, edges, pin)
+    }
+
+    /**
+     * A PIN IS NOT A CONSTRAINT (section 7).
+     *
+     * Constraints and bands are negotiable by definition - they are what
+     * plugins and documents say they want, and the sort's job is to satisfy
+     * them all. A pin is the host stating a structural invariant of its own
+     * architecture, which is a different kind of claim and must not lose a
+     * tie to a document.
+     *
+     * So a pin PLACES the binding at the named end, and an ordering that
+     * would move it away is `plugin_order_pinned` - rejected, not honoured
+     * into a broken wrap.
+     */
+    fun applyPin(
+        order: List<String>,
+        edges: Map<String, MutableList<String>>,
+        pin: Any?
+    ): List<String> {
+        if (null == pin) return order
+        val out = ArrayList(order)
+
+        // 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). A
+        // Go map has no order at all, so leaving it unstated made the same
+        // declaration mean different things in different ports.
+        for (name in Types.keys(pin)) {
+            val want = Types.get(pin, name)
+            val idx = out.indexOfFirst { Refs.refName(it) == name }
+            if (0 > idx) continue
+
+            // `first`/`outermost` is index 0; `last`/`innermost` is the end.
+            // Section 6.2 makes the first chain binding outermost, which is
+            // why the vocabulary is positional and why the two spellings pair
+            // this way.
+            val wantFirst = "first" == want || "outermost" == want
+            val ref = out.removeAt(idx)
+            if (wantFirst) out.add(0, ref) else out.add(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.
+        val at = HashMap<String, Int>()
+        out.forEachIndexed { i, ref -> at[ref] = i }
+        for ((from, tos) in edges) {
+            for (to in tos) {
+                if (at[from]!! <= at[to]!!) continue
+                Types.fail(
+                    "plugin_order_pinned",
+                    "a pin would move a binding an ordering constrains: " +
+                        "$from must precede $to",
+                    mapOf("before" to from, "after" to to)
+                )
+            }
+        }
+        return out
+    }
+}

package/project/.sdk/tm/kotlin/feature/secrets/plugin/Plugin.kt

@@ -0,0 +1,64 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (kotlin/src/Plugin.kt)
+// 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.
+package KOTLINPACKAGE.feature.secrets.plugin
+
+/**
+ * The canonical surface `make parity` checks (AGENTS.md section 4). Small on
+ * purpose (section 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.
+ *
+ * ELEVEN NAMES, AND THEY FORWARD. The implementation lives in the object named
+ * for its design section, so a reader who arrives at `resolveOrder` from the
+ * corpus lands in `Order` where section 7 is quoted.
+ */
+object Plugin {
+
+    // host construction
+    @JvmStatic
+    @JvmOverloads
+    fun makeHost(options: Any? = null): Host = Host(options)
+
+    @JvmStatic
+    @JvmOverloads
+    fun makeCatalog(definitions: List<Any?>? = null): Catalog {
+        val catalog = Catalog()
+        for (d in definitions ?: emptyList()) catalog.add(d)
+        return catalog
+    }
+
+    // refs - the first thing a new port implements (section 4)
+    @JvmStatic
+    fun parseRef(str: Any?): Map<String, Any?> = Refs.parseRef(str)
+
+    @JvmStatic
+    @JvmOverloads
+    fun formatRef(name: Any?, tag: Any? = null): String = Refs.formatRef(name, tag)
+
+    @JvmStatic
+    fun checkName(name: Any?): Boolean = Refs.checkName(name)
+
+    @JvmStatic
+    fun checkTag(tag: Any?): Boolean = Refs.checkTag(tag)
+
+    // pure functions over documents and definitions
+    @JvmStatic
+    fun normalizeConfig(input: Any?): Map<String, Any?> = Config.normalizeConfig(input)
+
+    @JvmStatic
+    fun resolveOptions(input: Any?): Map<String, Any?> = Config.resolveOptions(input)
+
+    @JvmStatic
+    @JvmOverloads
+    fun resolveOrder(bindings: List<OrderNode>, pin: Any? = null): List<String> =
+        Order.resolveOrder(bindings, pin)
+
+    @JvmStatic
+    @JvmOverloads
+    fun resolveCandidates(name: String, sources: Any? = null): List<String> =
+        Resolve.resolveCandidates(name, sources)
+
+    @JvmStatic
+    fun applyEnv(input: Any?): Map<String, Any?> = Env.applyEnv(input)
+}

package/project/.sdk/tm/kotlin/feature/secrets/plugin/Point.kt

@@ -0,0 +1,124 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (kotlin/src/Point.kt)
+// 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.
+package KOTLINPACKAGE.feature.secrets.plugin
+
+/**
+ * Extension points (section 6). Three kinds, chosen because they are what
+ * the two existing systems actually needed, and no more.
+ *
+ * A PLUGIN NEVER MUTATES THE HOST. That inversion is what makes deactivation
+ * possible: sdkgen's `utility.fetcher = wrapped` is not undoable, but "this
+ * instance holds slot 3 of the request chain" is undoable in O(1). OSGi named
+ * it the whiteboard pattern in 2004, in a paper called *Listeners Considered
+ * Harmful*, and for exactly this reason.
+ */
+
+/**
+ * EVERY BINDING IS ARITY TWO, `(next, arg)`, hook and chain alike. `next` is
+ * null for a hook. One signature means `Point` does not have to know which
+ * kind of point it is holding - and the kind is the HOST's property, not the
+ * binding's.
+ */
+typealias BindingFn = (Any?, Any?) -> Any?
+
+/** A live binding. An internal shape, never a corpus value. */
+data class Binding(
+    val ref: String,
+    val point: String,
+    val fn: BindingFn,
+    val band: Int
+)
+
+/** The winner and the losers on a provider point. */
+data class Picked(val winner: Binding?, val shadowed: List<String>)
+
+object Point {
+
+    /**
+     * Section 6.1: "fan-out" is not one answer but four. In a language with
+     * asynchrony, "call every binding" hides a decision - start them all and
+     * wait, await each in turn, or do not wait - and a design that leaves it
+     * unsaid gets four different answers from four ports, in the concurrency
+     * behaviour of production code no corpus entry happens to cover.
+     *
+     * KOTLIN IS A PORT WHERE THAT IS LOUD: a `suspend fun` host is one
+     * keyword away, and it would make every hook point a suspension and every
+     * ordering assertion a race. The host stays blocking (section 5.2) and
+     * the modes stay data.
+     */
+    val modes = listOf("emit", "parallel", "serial", "bail")
+
+    /** Fan-out. Return values are ignored except in `bail`. */
+    fun pointEmit(bindings: List<Binding>, mode: String, arg: Any?): Any? {
+        if ("bail" == mode) {
+            // Stops at the first binding that RETURNS A VALUE - the "handled,
+            // stop" case. A `null` RETURN DECLINES (section 6.1): kotlin has
+            // one way to say nothing, and the model's rule is written to that
+            // rather than to JavaScript's null/undefined pair. `null !=`, NOT
+            // truthiness - `false` is a value.
+            for (b in bindings) {
+                val v = b.fn(null, arg)
+                if (null != v) return v
+            }
+            return null
+        }
+
+        val errors = ArrayList<String>()
+        for (b in bindings) {
+            try {
+                b.fn(null, arg)
+            } catch (e: Exception) {
+                // `emit` raises synchronously; the collecting modes gather.
+                if ("emit" == mode) throw e
+                errors.add(Types.messageOf(e))
+            }
+        }
+        return if ("emit" == mode) null else errors
+    }
+
+    /**
+     * Composition: b1(b2(b3(base))), FIRST BINDING OUTERMOST (section 6.2).
+     *
+     * Recomputed by the host whenever the live set changes, and cached
+     * between changes. Plugins receive `next` as an argument; they never see
+     * or store the previous value of anything. A plugin that stashes `next`
+     * and calls it after deactivation is a bug the host cannot prevent, and
+     * this says so rather than pretending otherwise.
+     */
+    fun compose(bindings: List<Binding>, base: (Any?) -> Any?): (Any?) -> Any? {
+        var next = base
+        for (i in bindings.indices.reversed()) {
+            // `fn` and `inner` are declared INSIDE the loop, so each layer
+            // closes over its own pair. Kotlin captures the variable rather
+            // than the value, and hoisting either would leave every layer
+            // calling the last one.
+            val fn = bindings[i].fn
+            val inner = next
+            next = { arg -> fn(inner, arg) }
+        }
+        return next
+    }
+
+    /**
+     * At most one live implementation (section 6.3). The winner is the
+     * highest band, ties broken by ref sort, and THE LOSERS ARE VISIBLE
+     * rather than silently ignored.
+     */
+    fun pointProvider(bindings: List<Binding>, spec: Any?): Picked {
+        if (bindings.isEmpty()) return Picked(null, emptyList())
+
+        if (Types.truthy(Types.get(spec, "exclusive")) && 1 < bindings.size) {
+            val refs = bindings.map { it.ref }.sorted()
+            Types.fail(
+                "plugin_point_exclusive",
+                "point is exclusive and has ${bindings.size} bindings: " +
+                    refs.joinToString(", "),
+                mapOf("refs" to refs)
+            )
+        }
+
+        val ranked = Types.stableSortBy(bindings) { listOf(-it.band, it.ref) }
+        return Picked(ranked[0], ranked.drop(1).map { it.ref })
+    }
+}