@voxgig/sdkgen 4.10.0 → 4.12.0

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

@@ -0,0 +1,201 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (zig/src/env.zig)
+// Source: https://github.com/voxgig/plugin @ 91c4936555a4ce198669ca2c578b91e27e92e5ec  [tag: sdk-20260911-2013-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+//! Environment overrides (§9.5) — level 7 of the ladder.
+//!
+//! One prefix, so nothing drifts: `VOXGIG_PLUGIN_*`.
+//!
+//!   VOXGIG_PLUGIN_PROFILE            the profile name
+//!   VOXGIG_PLUGIN_<REF>_<PATH>       one option
+//!   VOXGIG_PLUGIN_ACTIVE/INACTIVE    comma-separated refs, INACTIVE wins
+//!
+//! THE ENCODING IS LOSSY, AND THIS SAYS SO RATHER THAN PRETENDING
+//! OTHERWISE. Ref and path are upper-snake with `$` -> `__` and `.` ->
+//! `_`. But `_` is legal in a name and in a tag, and the mapping folds
+//! case, so `retry$fast` and `retry__fast` both encode to `RETRY__FAST`.
+//!
+//! Rather than restrict a grammar the rest of the stack already uses,
+//! the host DETECTS THE COLLISION: it encodes every ref it holds, and a
+//! key two refs claim is `plugin_env_ambiguous`, naming both.
+
+const std = @import("std");
+const v = @import("value.zig");
+const t = @import("types.zig");
+const ref = @import("ref.zig");
+
+const PREFIX = "VOXGIG_PLUGIN_";
+
+pub fn encoderef(r: []const u8) []const u8 {
+    var out = v.List(u8).init(v.arena());
+    for (r) |c| {
+        if (c == '$') {
+            out.appendSlice("__") catch @panic("oom");
+        } else if (c == '.') {
+            out.append('_') catch @panic("oom");
+        } else if (c >= 'a' and c <= 'z') {
+            out.append(c - 'a' + 'A') catch @panic("oom");
+        } else {
+            out.append(c) catch @panic("oom");
+        }
+    }
+    return out.items;
+}
+
+fn lower(s: []const u8) []const u8 {
+    const out = v.arena().alloc(u8, s.len) catch @panic("oom");
+    for (s, 0..) |c, i| out[i] = if (c >= 'A' and c <= 'Z') c - 'A' + 'a' else c;
+    return out;
+}
+
+fn checkreserved(r: []const u8, reserved: ?*v.Value) t.Err!void {
+    if (!v.isList(reserved) or v.len(reserved) == 0) return;
+    const name = ref.refname(r);
+    for (v.items(reserved)) |x| {
+        if (v.isStr(x) and std.mem.eql(u8, v.asStr(x), name)) {
+            return t.fail("plugin_ref_reserved", v.print("ref is reserved by the host: {s}", .{r}), t.details1("ref", v.vstr(r)));
+        }
+    }
+}
+
+/// Values parse as JSON, FALLING BACK TO STRING — so `8080` is a number,
+/// `true` is a boolean, `{"a":1}` is a map, and `hello` is the string it
+/// looks like rather than a parse error.
+fn parsevalue(s: []const u8) *v.Value {
+    var err: []const u8 = "";
+    return v.parse(s, &err) orelse v.vstr(s);
+}
+
+fn trim(s: []const u8) []const u8 {
+    return std.mem.trim(u8, s, " \t");
+}
+
+fn lessByLenDesc(_: void, a: []const u8, b: []const u8) bool {
+    if (a.len != b.len) return a.len > b.len;
+    return std.mem.order(u8, a, b) == .lt;
+}
+
+pub fn applyenv(input: ?*v.Value) t.Err!*v.Value {
+    var env = v.get(input, "env");
+    if (!v.isMap(env)) env = v.vmap();
+    const refsin = v.get(input, "refs");
+    const reserved = v.get(input, "reserved");
+
+    const out = v.vmap();
+    const options = v.vmap();
+    const active = v.vlist();
+    const inactive = v.vlist();
+    v.set(out, "options", options);
+    v.set(out, "active", active);
+    v.set(out, "inactive", inactive);
+
+    // Encode every ref the host holds, and refuse a key that two of them
+    // claim. Done UP FRONT so the collision is reported even when no
+    // environment variable exercises it — a latent ambiguity is still an
+    // ambiguity, and finding it at deploy time is the failure this
+    // exists to prevent.
+    const byencoded = v.vmap();
+    if (v.isList(refsin)) {
+        for (v.items(refsin)) |rv| {
+            const r = try ref.canonref(rv);
+            const e = encoderef(r);
+            var list = v.get(byencoded, e);
+            if (v.isNull(list)) {
+                list = v.vlist();
+                v.set(byencoded, e, list);
+            }
+            v.push(list, v.vstr(r));
+        }
+    }
+
+    const encs = v.sortedKeys(byencoded);
+    for (encs) |e| {
+        const claims = v.get(byencoded, e);
+        if (v.len(claims) > 1) {
+            const a = v.asStr(v.at(claims, 0));
+            const b = v.asStr(v.at(claims, 1));
+            const lo = if (std.mem.order(u8, a, b) != .gt) a else b;
+            const hi = if (std.mem.order(u8, a, b) != .gt) b else a;
+            const pair = v.vlist();
+            v.push(pair, v.vstr(lo));
+            v.push(pair, v.vstr(hi));
+            const d = v.vmap();
+            v.set(d, "encoded", v.vstr(e));
+            v.set(d, "refs", pair);
+            return t.fail("plugin_env_ambiguous", v.print("refs collide in the environment encoding as {s}: {s}, {s}", .{ e, lo, hi }), d);
+        }
+    }
+
+    // LONGEST encoded ref first, so `retry$fast` wins over `retry` on
+    // `RETRY__FAST_MIN`. Shortest-first would read the tag as a path.
+    const order = v.arena().alloc([]const u8, encs.len) catch @panic("oom");
+    @memcpy(order, encs);
+    std.mem.sort([]const u8, order, {}, lessByLenDesc);
+
+    for (v.sortedKeys(env)) |key| {
+        if (key.len < PREFIX.len or !std.mem.eql(u8, key[0..PREFIX.len], PREFIX)) continue;
+        const rest = key[PREFIX.len..];
+        const raw = v.get(env, key);
+        const val = if (v.isStr(raw)) v.asStr(raw) else "";
+
+        if (std.mem.eql(u8, rest, "PROFILE")) {
+            v.set(out, "profile", v.vstr(val));
+            continue;
+        }
+
+        if (std.mem.eql(u8, rest, "ACTIVE") or std.mem.eql(u8, rest, "INACTIVE")) {
+            const isactive = std.mem.eql(u8, rest, "ACTIVE");
+            var it = std.mem.splitScalar(u8, val, ',');
+            while (it.next()) |piece| {
+                const p = trim(piece);
+                if (p.len == 0) continue;
+                const c = try ref.canonrefs(p);
+                // The reservation covers EVERY input layer (§9.1).
+                // VOXGIG_PLUGIN_INACTIVE=station is easier to set than
+                // editing a config file, and INACTIVE has the final word
+                // — so guarding documents alone would leave the one
+                // lever this mechanism exists to deny wide open.
+                try checkreserved(c, reserved);
+                v.push(if (isactive) active else inactive, v.vstr(c));
+            }
+            continue;
+        }
+
+        var enc: ?[]const u8 = null;
+        for (order) |cand| {
+            if (std.mem.eql(u8, rest, cand) or
+                (rest.len > cand.len and std.mem.eql(u8, rest[0..cand.len], cand) and rest[cand.len] == '_'))
+            {
+                enc = cand;
+                break;
+            }
+        }
+        const e = enc orelse continue; // not for any ref this host holds
+
+        const r = v.asStr(v.at(v.get(byencoded, e), 0));
+        try checkreserved(r, reserved);
+
+        if (std.mem.eql(u8, rest, e)) continue; // a ref with no path sets nothing
+
+        const pathtext = rest[e.len + 1 ..];
+        var node = v.get(options, r);
+        if (v.isNull(node)) {
+            node = v.vmap();
+            v.set(options, r, node);
+        }
+
+        var segs = std.mem.splitScalar(u8, pathtext, '_');
+        var seg = segs.next().?;
+        while (segs.peek() != null) : (seg = segs.next().?) {
+            const piece = lower(seg);
+            var next = v.get(node, piece);
+            if (!v.isMap(next)) {
+                next = v.vmap();
+                v.set(node, piece, next);
+            }
+            node = next;
+        }
+        v.set(node, lower(seg), parsevalue(val));
+    }
+
+    return out;
+}

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

@@ -0,0 +1,83 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (zig/src/export.zig)
+// Source: https://github.com/voxgig/plugin @ 91c4936555a4ce198669ca2c578b91e27e92e5ec  [tag: sdk-20260911-2013-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+//! Exports (§11).
+//!
+//! THE UNQUALIFIED ALIAS IS THE INTERESTING PART. `retry/client`
+//! resolves to the UNTAGGED instance if one exists; if not, and exactly
+//! one tagged instance exports that key, it resolves to that one; if two
+//! do, it is `plugin_export_ambiguous` — deliberately diverging from
+//! seneca's silent last-wins, because with multi-instance as a headline
+//! feature an ambiguous alias is a defect waiting for production.
+
+const std = @import("std");
+const v = @import("value.zig");
+const t = @import("types.zig");
+const ref = @import("ref.zig");
+
+fn lessStr(_: void, a: []const u8, b: []const u8) bool {
+    return std.mem.order(u8, a, b) == .lt;
+}
+
+/// Answers null for "no such export", which is not an error —
+/// `export/missing` pins that, and is why the answer is an optional
+/// rather than a null Value.
+pub fn resolveexport(spec: ?*v.Value, exported: ?*v.Value) t.Err!?*v.Value {
+    const s = if (v.isStr(spec)) v.asStr(spec) else "";
+    const cut = std.mem.indexOfScalar(u8, s, '/') orelse
+        return t.fail("plugin_export_ambiguous", v.print("export spec needs a key: {s}", .{s}), t.details1("spec", v.vstr(s)));
+    const head = s[0..cut];
+    const key = s[cut + 1 ..];
+
+    // A fully qualified ref: exactly one answer or none.
+    //
+    // VALIDATING, not tolerant. The canonical calls `canonref(head)`,
+    // which RAISES — so `retry$bad!/client` is `plugin_bad_tag` and
+    // `2fa/client` is `plugin_bad_name`. Reading it with `tryref`
+    // turned a configuration typo into an ordinary missing export,
+    // which is the error the caller most needs to see, silently
+    // swallowed.
+    const want = try ref.canonrefs(head);
+    for (v.items(exported)) |e| {
+        if (std.mem.eql(u8, v.asStr(v.get(e, "ref")), want) and
+            std.mem.eql(u8, v.asStr(v.get(e, "key")), key))
+        {
+            return v.get(e, "value");
+        }
+    }
+
+    // An alias: the NAME, not a ref. Look at every instance of it.
+    var byname = v.List(*v.Value).init(v.arena());
+    for (v.items(exported)) |e| {
+        const eref = v.asStr(v.get(e, "ref"));
+        if (std.mem.eql(u8, ref.refname(eref), head) and
+            std.mem.eql(u8, v.asStr(v.get(e, "key")), key))
+        {
+            byname.append(e) catch @panic("oom");
+        }
+    }
+    if (byname.items.len == 0) return null;
+
+    // The untagged instance wins outright when there is one.
+    for (byname.items) |e| {
+        if (std.mem.indexOfScalar(u8, v.asStr(v.get(e, "ref")), '$') == null) return v.get(e, "value");
+    }
+
+    if (byname.items.len == 1) return v.get(byname.items[0], "value");
+
+    const refs = v.arena().alloc([]const u8, byname.items.len) catch @panic("oom");
+    for (byname.items, 0..) |e, i| refs[i] = v.asStr(v.get(e, "ref"));
+    std.mem.sort([]const u8, refs, {}, lessStr);
+
+    const list = v.vlist();
+    var names = v.List(u8).init(v.arena());
+    for (refs, 0..) |r, i| {
+        if (i > 0) names.appendSlice(", ") catch @panic("oom");
+        names.appendSlice(r) catch @panic("oom");
+        v.push(list, v.vstr(r));
+    }
+    const d = v.vmap();
+    v.set(d, "spec", v.vstr(s));
+    v.set(d, "refs", list);
+    return t.fail("plugin_export_ambiguous", v.print("alias {s} matches {d} instances: {s}", .{ s, byname.items.len, names.items }), d);
+}

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

@@ -0,0 +1,212 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (zig/src/graph.zig)
+// Source: https://github.com/voxgig/plugin @ 91c4936555a4ce198669ca2c578b91e27e92e5ec  [tag: sdk-20260911-2013-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+//! Whole-graph resolution (§11.4) — a phase, not a discovery.
+//!
+//! "Activate, and wait in `pending` if you must" is correct and, on its
+//! own, produces a terrible experience: apply twenty instances against a
+//! registry missing one thing and you get NINETEEN pending rows and no
+//! statement of what is actually wrong.
+//!
+//! `resolvegraph` is a PURE FUNCTION of the registry and the intended
+//! activation set. No callbacks run, no state changes, nothing is
+//! touched. It answers for the whole graph at once which instances can
+//! be live, and for each blocked one THE SPECIFIC REQUIREMENT that is
+//! unmet, and why.
+//!
+//! The failure mode being designed against is a famous one: OSGi's
+//! resolver is correct and its diagnostics are legendarily unusable. A
+//! resolver that says "blocked" without saying WHY has moved the problem
+//! rather than solved it, so `why` is part of the contract.
+
+const std = @import("std");
+const v = @import("value.zig");
+const cap = @import("capability.zig");
+const ref = @import("ref.zig");
+const version = @import("version.zig");
+
+fn lessStr(_: void, a: []const u8, b: []const u8) bool {
+    return std.mem.order(u8, a, b) == .lt;
+}
+
+fn sortedStrings(list: [][]const u8) *v.Value {
+    std.mem.sort([]const u8, list, {}, lessStr);
+    const out = v.vlist();
+    for (list) |s| v.push(out, v.vstr(s));
+    return out;
+}
+
+fn candidates(byref: *v.Value, name: ?*v.Value) *v.Value {
+    const out = v.vlist();
+    // A NODE SATISFIES ITS OWN REF (§11.1), and this is where the graph
+    // learned it. Considering only declared capabilities made `resolve`
+    // answer `absent` about a provider sitting right there and live —
+    // §11.4's whole job is explaining the graph the runtime reconciles,
+    // and it was explaining a different one. Canonical (§4 rule 5), and
+    // tolerant, because a capability name need not be a well-formed ref.
+    const asref = if (v.isStr(name)) ref.tryref(v.asStr(name)) else null;
+
+    for (v.sortedKeys(byref)) |r| {
+        const node = v.get(byref, r);
+        var pos = v.get(node, "pos");
+        if (!v.isNum(pos)) pos = v.vnum(0);
+        // The ref match WINS OUTRIGHT for that node, as at runtime: one
+        // candidate, not two, for a node both named `b` and providing
+        // `b` — without the skip the blocked-chain explanation named it
+        // twice.
+        if (asref != null and std.mem.eql(u8, r, asref.?)) {
+            const prov = v.vmap();
+            v.set(prov, "name", name);
+            const c = v.vmap();
+            v.set(c, "ref", v.get(node, "ref"));
+            v.set(c, "pos", pos);
+            v.set(c, "provides", prov);
+            v.push(out, c);
+            continue;
+        }
+        for (v.items(v.get(node, "provides"))) |p| {
+            if (v.same(v.get(p, "name"), name)) {
+                const c = v.vmap();
+                v.set(c, "ref", v.get(node, "ref"));
+                v.set(c, "pos", pos);
+                v.set(c, "provides", p);
+                v.push(out, c);
+            }
+        }
+    }
+    return out;
+}
+
+fn blockedof(node: ?*v.Value, unmet: ?*v.Value, why: ?*v.Value) *v.Value {
+    const out = v.vmap();
+    v.set(out, "ref", v.get(node, "ref"));
+    v.set(out, "unmet", unmet);
+    v.set(out, "why", why);
+    return out;
+}
+
+fn why1(kind: []const u8) *v.Value {
+    const w = v.vmap();
+    v.set(w, "kind", v.vstr(kind));
+    return w;
+}
+
+/// The FIRST unmet requirement, with the most specific explanation
+/// available. Order matters: "no provider at all" and "a provider at the
+/// wrong version" are different problems and a reader must not have to
+/// guess which they have.
+fn firstunmet(node: *v.Value, byref: *v.Value, resolved: *v.Value) ?*v.Value {
+    for (v.items(v.get(node, "requires"))) |req| {
+        if (v.truthy(v.get(req, "optional"))) continue;
+
+        const name = v.get(req, "name");
+        const all = candidates(byref, name);
+        if (v.len(all) == 0) return blockedof(node, name, why1("absent"));
+
+        const ok = cap.resolvecapability(req, all);
+        if (v.len(ok) > 0) {
+            // A provider exists and matches — but if none of them is
+            // itself resolved, this node is blocked BEHIND it, and the
+            // chain is the useful answer rather than "unmet".
+            var live = false;
+            for (v.items(ok)) |c| {
+                if (v.has(resolved, v.asStr(v.get(c, "ref")))) {
+                    live = true;
+                    break;
+                }
+            }
+            if (live) continue;
+
+            var chain = v.List([]const u8).init(v.arena());
+            for (v.items(ok)) |c| chain.append(v.asStr(v.get(c, "ref"))) catch @panic("oom");
+            const w = why1("blocked");
+            v.set(w, "chain", sortedStrings(chain.items));
+            return blockedof(node, name, w);
+        }
+
+        // Providers exist and none matched. Say which test failed.
+        const range = v.get(req, "range");
+        if (!v.isNull(range)) {
+            var found = v.List([]const u8).init(v.arena());
+            for (v.items(all)) |c| {
+                const ver = v.get(v.get(c, "provides"), "version");
+                if (v.isNull(ver)) {
+                    found.append("(none)") catch @panic("oom");
+                } else if (!version.satisfiesq(ver, range)) {
+                    found.append(v.asStr(ver)) catch @panic("oom");
+                }
+            }
+            if (found.items.len > 0) {
+                const w = why1("version");
+                v.set(w, "range", range);
+                v.set(w, "found", sortedStrings(found.items));
+                return blockedof(node, name, w);
+            }
+        }
+
+        const m = v.get(req, "match");
+        if (!v.isNull(m)) {
+            for (v.items(all)) |c| {
+                var attrs = v.get(v.get(c, "provides"), "attrs");
+                if (v.isNull(attrs)) attrs = v.vmap();
+                for (v.sortedKeys(m)) |k| {
+                    // The same recursive partial match the selection
+                    // applies, so a nested requirement that FAILED the
+                    // selection is also the one the diagnosis names
+                    // (§11.4).
+                    if (!v.has(attrs, k) or !cap.capmatchvalue(v.get(m, k), v.get(attrs, k))) {
+                        const w = why1("match");
+                        v.set(w, "failing", v.vstr(k));
+                        v.set(w, "want", v.get(m, k));
+                        v.set(w, "found", v.get(attrs, k));
+                        return blockedof(node, name, w);
+                    }
+                }
+            }
+        }
+
+        return blockedof(node, name, why1("absent"));
+    }
+    return null;
+}
+
+pub fn resolvegraph(nodes: ?*v.Value) *v.Value {
+    const byref = v.vmap();
+    for (v.items(nodes)) |n| v.set(byref, v.asStr(v.get(n, "ref")), n);
+
+    const resolved = v.vmap();
+
+    // Fixed point: a node resolves when every mandatory requirement is
+    // met by an ALREADY-RESOLVED provider. Iterating to a fixed point is
+    // what makes a provider that is itself blocked propagate, rather
+    // than each node being judged against the raw registry.
+    var moved = true;
+    while (moved) {
+        moved = false;
+        for (v.items(nodes)) |n| {
+            const r = v.asStr(v.get(n, "ref"));
+            if (v.has(resolved, r)) continue;
+            if (firstunmet(n, byref, resolved) == null) {
+                v.set(resolved, r, v.vbool(true));
+                moved = true;
+            }
+        }
+    }
+
+    const blocked = v.vmap();
+    for (v.items(nodes)) |n| {
+        const r = v.asStr(v.get(n, "ref"));
+        if (v.has(resolved, r)) continue;
+        if (firstunmet(n, byref, resolved)) |why| v.set(blocked, r, why);
+    }
+
+    const resolvedlist = v.vlist();
+    for (v.sortedKeys(resolved)) |k| v.push(resolvedlist, v.vstr(k));
+    const blockedlist = v.vlist();
+    for (v.sortedKeys(blocked)) |k| v.push(blockedlist, v.get(blocked, k));
+
+    const out = v.vmap();
+    v.set(out, "resolved", resolvedlist);
+    v.set(out, "blocked", blockedlist);
+    return out;
+}