@voxgig/sdkgen 4.10.0 → 4.11.0

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

@@ -0,0 +1,244 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (zig/src/depend.zig)
+// 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.
+//! Dependency cardinality, policy, and the restart graph (§11.3).
+//!
+//! TWO AXES, BOTH DECLARED BY THE DEFINITION THAT HAS THE REQUIREMENT,
+//! because only it knows what it can cope with:
+//!
+//!                | static (default)          | dynamic
+//!   -------------|---------------------------|--------------------------
+//!   mandatory    | unmet -> pending;         | unmet -> pending;
+//!   (default)    | lost  -> pending,         | lost  -> STAYS LIVE,
+//!                |          recursively      |          notified
+//!   -------------|---------------------------|--------------------------
+//!   optional:true| never gates activation;   | never gates activation;
+//!                | a change deactivates and  | a change is a
+//!                | reactivates               | notification, nothing else
+//!
+//! `dynamic` means the plugin has said, IN WRITING, that it can survive
+//! its provider being swapped underneath it. It is not the default
+//! because most plugins cannot, and the cost of wrongly assuming they
+//! can is a live instance holding a dead reference.
+
+const std = @import("std");
+const v = @import("value.zig");
+const t = @import("types.zig");
+const ref = @import("ref.zig");
+
+/// A bare string is shorthand for `{name}`.
+pub fn normrequire(r: ?*v.Value) *v.Value {
+    if (v.isStr(r)) {
+        const out = v.vmap();
+        v.set(out, "name", r);
+        return out;
+    }
+    return if (v.isMap(r)) r.? else v.vmap();
+}
+
+/// BOTH AXES ARE READ AT TWO LEVELS, AND THE PER-REQUIREMENT ONE WINS.
+///
+/// The instance-level `policy` and `optional` list are how a DOCUMENT
+/// states the axis without editing the definition, and they apply to
+/// every requirement. The per-requirement form is strictly more
+/// expressive: an instance that is `static` on its store and `dynamic`
+/// on its metrics cannot be written at all at the instance level, and
+/// that is the ordinary case rather than an exotic one.
+///
+/// `optional` UNIONS rather than overriding — both spellings say this
+/// requirement need not gate activation, and there is no reading under
+/// which one of them means "actually, mandatory".
+pub fn requirements(options: ?*v.Value) *v.Value {
+    const raw = v.get(options, "requires");
+    const marked = v.get(options, "optional");
+    const fallback = v.get(options, "policy");
+
+    const out = v.vlist();
+    for (v.items(raw)) |item| {
+        const r = normrequire(item);
+        const o = v.vmap();
+        for (v.keys(r)) |k| v.set(o, k, v.get(r, k));
+
+        var opt = v.truthy(v.get(r, "optional"));
+        if (!opt and v.isList(marked)) {
+            for (v.items(marked)) |m| {
+                if (v.same(m, v.get(r, "name"))) {
+                    opt = true;
+                    break;
+                }
+            }
+        }
+        if (opt) v.set(o, "optional", v.vbool(true));
+
+        if (v.isNull(v.get(o, "policy")) and !v.isNull(fallback)) v.set(o, "policy", fallback);
+        v.push(out, o);
+    }
+    return out;
+}
+
+/// Does losing this requirement's SELECTED provider restart the
+/// consumer? The mandatory ones under `static`, and the `static`
+/// optional ones — both make a capability change deactivate and
+/// reactivate. `dynamic` never restarts.
+pub fn restartsonloss(r: ?*v.Value) bool {
+    const p = v.get(r, "policy");
+    const policy = if (v.isStr(p)) v.asStr(p) else "static";
+    return !std.mem.eql(u8, policy, "dynamic");
+}
+
+/// Does an unmet requirement keep the consumer out of `live`?
+///
+/// CARDINALITY ALONE DECIDES THIS, NOT POLICY. `dynamic` is a statement
+/// about surviving a SWAP, not about starting without the thing at all —
+/// a mandatory-dynamic consumer still waits in `pending` for its first
+/// provider. Conflating the two would let a plugin that declared it can
+/// cope with replacement activate with nothing to call.
+pub fn gatesactivation(r: ?*v.Value) bool {
+    return v.asBool(v.get(r, "optional")) != true;
+}
+
+/// Edges that can cause a restart, which is exactly the set a cycle must
+/// be detected over (§11.3): the mandatory requirements AND THE `static`
+/// OPTIONAL ONES, because both make a capability change deactivate and
+/// reactivate the consumer — and a cycle of restarts does not settle.
+///
+/// ONLY `dynamic` OPTIONAL EDGES ARE EXCLUDED, and they are the ones the
+/// exclusion was for. An earlier draft of §11.3 excluded EVERY optional
+/// edge and thereby admitted the non-terminating case it was trying to
+/// permit.
+pub fn restartcausing(r: ?*v.Value) bool {
+    return gatesactivation(r) or restartsonloss(r);
+}
+
+fn lessStr(_: void, a: []const u8, b: []const u8) bool {
+    return std.mem.order(u8, a, b) == .lt;
+}
+
+fn listhas(l: []const []const u8, s: []const u8) bool {
+    for (l) |x| {
+        if (std.mem.eql(u8, x, s)) return true;
+    }
+    return false;
+}
+
+pub fn dependencycycle(nodes: ?*v.Value) ?*v.Value {
+    // TWO INDEXES, NOT ONE MERGED MAP. Capability names and refs are
+    // matched differently — a capability by its exact name, a ref
+    // through the canonical spelling (§4 rule 5) — and one map keyed by
+    // both can only do one of them. Keyed by both and looked up raw, a
+    // cycle spelled `a$`/`b$` finds no providers and EVADES the
+    // load-time check that exists to catch a non-terminating reconcile.
+    const bycap = v.vmap();
+    const isref = v.vmap();
+    for (v.items(nodes)) |n| {
+        const nref = v.asStr(v.get(n, "ref"));
+        v.set(isref, nref, v.vbool(true));
+        for (v.items(v.get(n, "provides"))) |capv| {
+            const c = v.asStr(capv);
+            var l = v.get(bycap, c);
+            if (v.isNull(l)) {
+                l = v.vlist();
+                v.set(bycap, c, l);
+            }
+            v.push(l, v.vstr(nref));
+        }
+    }
+
+    const edges = v.vmap();
+    for (v.items(nodes)) |n| {
+        const nref = v.asStr(v.get(n, "ref"));
+        var out = v.List([]const u8).init(v.arena());
+        for (v.items(v.get(n, "requires"))) |r| {
+            if (!restartcausing(r)) continue;
+            const rname = if (v.isStr(v.get(r, "name"))) v.asStr(v.get(r, "name")) else "";
+            var from = v.List([]const u8).init(v.arena());
+            for (v.items(v.get(bycap, rname))) |x| from.append(v.asStr(x)) catch @panic("oom");
+            // A node satisfies its own name AS A REF (§11.1),
+            // canonically — exactly what `providersof` does at runtime,
+            // so the load-time graph and the running one agree about
+            // what an edge is.
+            if (ref.tryref(rname)) |asref| {
+                if (v.has(isref, asref) and !listhas(from.items, asref)) {
+                    from.append(asref) catch @panic("oom");
+                }
+            }
+            for (from.items) |p| {
+                if (!std.mem.eql(u8, p, nref) and !listhas(out.items, p)) {
+                    out.append(p) catch @panic("oom");
+                }
+            }
+        }
+        std.mem.sort([]const u8, out.items, {}, lessStr);
+        const sorted = v.vlist();
+        for (out.items) |p| v.push(sorted, v.vstr(p));
+        v.set(edges, nref, sorted);
+    }
+
+    // Iterative DFS with an explicit stack: twenty ports, and several of
+    // them have no recursion budget worth relying on.
+    const WHITE: f64 = 0;
+    const GREY: f64 = 1;
+    const BLACK: f64 = 2;
+    const colour = v.vmap();
+    for (v.items(nodes)) |n| v.set(colour, v.asStr(v.get(n, "ref")), v.vnum(WHITE));
+
+    const Frame = struct { ref: []const u8, i: usize };
+
+    for (v.sortedKeys(edges)) |start| {
+        if (v.asNum(v.get(colour, start)) != WHITE) continue;
+
+        var path = v.List([]const u8).init(v.arena());
+        var stack = v.List(Frame).init(v.arena());
+        stack.append(.{ .ref = start, .i = 0 }) catch @panic("oom");
+        v.set(colour, start, v.vnum(GREY));
+        path.append(start) catch @panic("oom");
+
+        while (stack.items.len > 0) {
+            const top = &stack.items[stack.items.len - 1];
+            const tos = v.get(edges, top.ref);
+
+            if (top.i >= v.len(tos)) {
+                v.set(colour, top.ref, v.vnum(BLACK));
+                _ = stack.pop();
+                _ = path.pop();
+                continue;
+            }
+
+            const next = v.asStr(v.at(tos, top.i));
+            top.i += 1;
+            const c = v.asNum(v.get(colour, next));
+
+            if (c == GREY) {
+                // Report the cycle itself, not the walk that found it.
+                const cycle = v.vlist();
+                var started = false;
+                for (path.items) |p| {
+                    if (!started and std.mem.eql(u8, p, next)) started = true;
+                    if (started) v.push(cycle, v.vstr(p));
+                }
+                v.push(cycle, v.vstr(next));
+                return cycle;
+            }
+            if (c == BLACK) continue;
+
+            v.set(colour, next, v.vnum(GREY));
+            path.append(next) catch @panic("oom");
+            stack.append(.{ .ref = next, .i = 0 }) catch @panic("oom");
+        }
+    }
+
+    return null;
+}
+
+/// Raise on a cycle, naming it. Separate from the detector so the
+/// detector stays pure and corpus-testable.
+pub fn checkcycle(nodes: ?*v.Value) t.Err!void {
+    const cycle = dependencycycle(nodes) orelse return;
+    var text = v.List(u8).init(v.arena());
+    text.appendSlice("requirements cycle: ") catch @panic("oom");
+    for (v.items(cycle), 0..) |x, i| {
+        if (i > 0) text.appendSlice(" -> ") catch @panic("oom");
+        text.appendSlice(v.asStr(x)) catch @panic("oom");
+    }
+    return t.fail("plugin_dependency_cycle", text.items, t.details1("cycle", cycle));
+}

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 @ 48392f5e2b6d1434ee9b1a4a9a11f4480aaeb46a  [tag: sdk-20260908-1556-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 @ 48392f5e2b6d1434ee9b1a4a9a11f4480aaeb46a  [tag: sdk-20260908-1556-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);
+}