@voxgig/sdkgen 4.9.0 → 4.10.0

package/project/.sdk/tm/php/feature/secrets/plugin/Env.php

@@ -0,0 +1,202 @@
+<?php
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (php/src/Env.php)
+// 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.
+ */
+
+declare(strict_types=1);
+
+namespace Voxgig\Plugin;
+
+const ENV_PREFIX = 'VOXGIG_PLUGIN_';
+
+/** `retry$fast` -> `RETRY__FAST`. */
+function encode_ref(string $ref): string
+{
+    return strtoupper(str_replace(['$', '.'], ['__', '_'], $ref));
+}
+
+/**
+ * @param array<string,mixed>|null $input
+ * @return array<string,mixed>
+ */
+function apply_env(?array $input): array
+{
+    $input = $input ?? [];
+    $env = $input['env'] ?? [];
+    $refs = [];
+    foreach ($input['refs'] ?? [] as $r) {
+        $refs[] = canon_ref($r);
+    }
+    $reserved = $input['reserved'] ?? [];
+    $out = ['options' => [], 'active' => [], '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.
+    $byencoded = [];
+    foreach ($refs as $r) {
+        $e = encode_ref($r);
+        if (!array_key_exists($e, $byencoded)) {
+            $byencoded[$e] = [];
+        }
+        $byencoded[$e][] = $r;
+    }
+    foreach (Util::sortedkeys($byencoded) as $e) {
+        if (count($byencoded[$e]) <= 1) {
+            continue;
+        }
+        $pair = Util::sortstrings($byencoded[$e]);
+        fail_with('plugin_env_ambiguous',
+                  'refs collide in the environment encoding as ' . $e . ': '
+                  . implode(', ', $pair),
+                  ['encoded' => $e, 'refs' => $pair]);
+    }
+
+    // Longest encoded ref first, so `retry$fast` wins over `retry` on
+    // `RETRY__FAST_MIN`. Shortest-first would read the tag as a path.
+    $encoded = Util::stable_sort_by(Util::sortedkeys($byencoded),
+        static function ($e) {
+            return [-strlen($e)];
+        });
+
+    foreach (Util::sortedkeys($env) as $key) {
+        if (!str_starts_with($key, ENV_PREFIX)) {
+            continue;
+        }
+
+        $rest = substr($key, strlen(ENV_PREFIX));
+
+        if ('PROFILE' === $rest) {
+            $out['profile'] = $env[$key];
+            continue;
+        }
+
+        if ('ACTIVE' === $rest || 'INACTIVE' === $rest) {
+            foreach (env_split($env[$key]) as $raw) {
+                $ref = canon_ref($raw);
+                // 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.
+                env_checkreserved($ref, $reserved);
+                $out['ACTIVE' === $rest ? 'active' : 'inactive'][] = $ref;
+            }
+            continue;
+        }
+
+        $enc = null;
+        foreach ($encoded as $e) {
+            if ($rest === $e || str_starts_with($rest, $e . '_')) {
+                $enc = $e;
+                break;
+            }
+        }
+        if (null === $enc) {
+            continue;              // not for any ref this host holds
+        }
+
+        $ref = $byencoded[$enc][0];
+        env_checkreserved($ref, $reserved);
+
+        if ($rest === $enc) {
+            continue;              // a ref with no path sets nothing
+        }
+
+        $path = explode('_', strtolower(substr($rest, strlen($enc) + 1)));
+
+        if (!isset($out['options'][$ref]) || !is_array($out['options'][$ref])) {
+            $out['options'][$ref] = [];
+        }
+        // A PHP ARRAY IS A VALUE, so walking into one to write a nested
+        // key needs an explicit reference - `$node = $out['options'][$ref]`
+        // would build the path in a copy and discard it. `unset` at the
+        // end releases the alias, because the next iteration's `=&`
+        // rebinds the name but any plain assignment through it would not.
+        $node = &$out['options'][$ref];
+        foreach (array_slice($path, 0, -1) as $step) {
+            if (!isset($node[$step]) || !is_array($node[$step])) {
+                $node[$step] = [];
+            }
+            $node = &$node[$step];
+        }
+        $node[$path[count($path) - 1]] = env_parsevalue($env[$key]);
+        unset($node);
+    }
+
+    return $out;
+}
+
+/**
+ * @param mixed $value
+ * @return string[]
+ */
+function env_split($value): array
+{
+    $out = [];
+    foreach (explode(',', (string)$value) as $part) {
+        $part = trim($part);
+        if ('' !== $part) {
+            $out[] = $part;
+        }
+    }
+    return $out;
+}
+
+/**
+ * @param string[] $reserved
+ */
+function env_checkreserved(string $ref, array $reserved): void
+{
+    if (empty($reserved)) {
+        return;
+    }
+    if (!in_array(refname($ref), $reserved, true)) {
+        return;
+    }
+    fail_with('plugin_ref_reserved', 'ref is reserved by the host: ' . $ref,
+              ['ref' => $ref]);
+}
+
+/**
+ * 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.
+ *
+ * PHP's `json_decode` accepts a bare scalar at the top level, so no quirks
+ * flag is needed; what it does NOT do is tell an invalid document from a
+ * valid `null`, which is why the error code is read rather than the
+ * result.
+ *
+ * @param mixed $value
+ * @return mixed
+ */
+function env_parsevalue($value)
+{
+    if (!is_string($value)) {
+        return $value;
+    }
+    $parsed = json_decode($value, true);
+    return JSON_ERROR_NONE === json_last_error() ? $parsed : $value;
+}

package/project/.sdk/tm/php/feature/secrets/plugin/Export.php

@@ -0,0 +1,74 @@
+<?php
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (php/src/Export.php)
+// 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).
+ *
+ * An instance publishes values for other plugins and for the application.
+ * Read with `host.exports('retry$fast/client')`.
+ *
+ * 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.
+ */
+
+declare(strict_types=1);
+
+namespace Voxgig\Plugin;
+
+/**
+ * @param array<int,array<string,mixed>> $exported
+ * @return mixed
+ */
+function resolve_export(string $spec, array $exported)
+{
+    $cut = strpos($spec, '/');
+    if (false === $cut) {
+        fail_with('plugin_export_ambiguous', 'export spec needs a key: ' . $spec,
+                  ['spec' => $spec]);
+    }
+    $head = substr($spec, 0, $cut);
+    $key = substr($spec, $cut + 1);
+
+    // A fully qualified ref: exactly one answer or none.
+    $want = canon($head);
+    foreach ($exported as $e) {
+        if ($e['ref'] === $want && $e['key'] === $key) {
+            return $e['value'];
+        }
+    }
+
+    // An alias: the name, not a ref. Look at every instance of it.
+    $byname = [];
+    foreach ($exported as $e) {
+        if (refname($e['ref']) === $head && $e['key'] === $key) {
+            $byname[] = $e;
+        }
+    }
+    if (empty($byname)) {
+        return null;
+    }
+
+    foreach ($byname as $e) {
+        if ('' === parse_ref($e['ref'])['tag']) {
+            return $e['value'];
+        }
+    }
+
+    if (1 === count($byname)) {
+        return $byname[0]['value'];
+    }
+
+    $refs = Util::sortstrings(array_map(static function ($e) {
+        return $e['ref'];
+    }, $byname));
+    fail_with('plugin_export_ambiguous',
+              'alias ' . $spec . ' matches ' . count($refs) . ' instances: '
+              . implode(', ', $refs),
+              ['spec' => $spec, 'refs' => $refs]);
+}

package/project/.sdk/tm/php/feature/secrets/plugin/Graph.php

@@ -0,0 +1,195 @@
+<?php
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (php/src/Graph.php)
+// 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.
+
+/**
+ * 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.
+ *
+ * `resolve_graph` 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 and the corpus pins its
+ * shape.
+ */
+
+declare(strict_types=1);
+
+namespace Voxgig\Plugin;
+
+/**
+ * @param array<int,array<string,mixed>> $nodes
+ * @return array{resolved:string[],blocked:array<int,mixed>}
+ */
+function resolve_graph(array $nodes): array
+{
+    $byref = [];
+    foreach ($nodes as $n) {
+        $byref[$n['ref']] = $n;
+    }
+
+    $resolved = [];
+    $blocked = [];
+
+    // 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.
+    $moved = true;
+    while ($moved) {
+        $moved = false;
+        foreach ($nodes as $n) {
+            if ($resolved[$n['ref']] ?? false) {
+                continue;
+            }
+            if (null !== firstunmet($n, $byref, $resolved)) {
+                continue;
+            }
+            $resolved[$n['ref']] = true;
+            $moved = true;
+        }
+    }
+
+    foreach ($nodes as $n) {
+        if ($resolved[$n['ref']] ?? false) {
+            continue;
+        }
+        $why = firstunmet($n, $byref, $resolved);
+        if (null !== $why) {
+            $blocked[$n['ref']] = $why;
+        }
+    }
+
+    $out = [];
+    foreach (Util::sortedkeys($blocked) as $r) {
+        $out[] = $blocked[$r];
+    }
+    return ['resolved' => Util::sortedkeys($resolved), 'blocked' => $out];
+}
+
+/**
+ * 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.
+ *
+ * @param array<string,mixed> $node
+ * @param array<string,array<string,mixed>> $byref
+ * @param array<string,bool> $resolved
+ * @return array<string,mixed>|null
+ */
+function firstunmet(array $node, array $byref, array $resolved): ?array
+{
+    foreach ($node['requires'] ?? [] as $req) {
+        if (Util::truthy($req['optional'] ?? null)) {
+            continue;
+        }
+
+        $all = graph_candidates($byref, $req['name']);
+        if (empty($all)) {
+            return ['ref' => $node['ref'], 'unmet' => $req['name'],
+                    'why' => ['kind' => 'absent']];
+        }
+
+        $ok = resolve_capability($req, $all);
+        if (!empty($ok)) {
+            // 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".
+            $any = false;
+            foreach ($ok as $c) {
+                if ($resolved[$c['ref']] ?? false) {
+                    $any = true;
+                    break;
+                }
+            }
+            if ($any) {
+                continue;
+            }
+            $chain = Util::sortstrings(array_map(static function ($c) {
+                return $c['ref'];
+            }, $ok));
+            return ['ref' => $node['ref'], 'unmet' => $req['name'],
+                    'why' => ['kind' => 'blocked', 'chain' => $chain]];
+        }
+
+        // Providers exist and none matched. Say which test failed.
+        if (null !== ($req['range'] ?? null)) {
+            $versions = [];
+            foreach ($all as $c) {
+                $have = $c['provides']['version'] ?? null;
+                if (null === $have || !satisfiesq($have, $req['range'])) {
+                    $versions[] = $have ?? '(none)';
+                }
+            }
+            if (!empty($versions)) {
+                return ['ref' => $node['ref'], 'unmet' => $req['name'],
+                        'why' => ['kind' => 'version', 'range' => $req['range'],
+                                  'found' => Util::sortstrings($versions)]];
+            }
+        }
+
+        if (null !== ($req['match'] ?? null)) {
+            foreach ($all as $c) {
+                $attrs = $c['provides']['attrs'] ?? [];
+                foreach (Util::sortedkeys($req['match']) as $k) {
+                    if (array_key_exists($k, $attrs)
+                        && matchvalue($req['match'][$k], $attrs[$k])) {
+                        continue;
+                    }
+                    return ['ref' => $node['ref'], 'unmet' => $req['name'],
+                            'why' => ['kind' => 'match', 'failing' => $k,
+                                      'want' => $req['match'][$k],
+                                      'found' => $attrs[$k] ?? null]];
+                }
+            }
+        }
+
+        return ['ref' => $node['ref'], 'unmet' => $req['name'],
+                'why' => ['kind' => 'absent']];
+    }
+    return null;
+}
+
+/**
+ * @param array<string,array<string,mixed>> $byref
+ * @return array<int,array<string,mixed>>
+ */
+function graph_candidates(array $byref, string $name): array
+{
+    $out = [];
+    // A NODE SATISFIES ITS OWN REF (§11.1), and the graph learned it
+    // here. Considering only declared capabilities made `resolve` answer
+    // `absent` about a provider sitting right there and live — §11.4's
+    // job is explaining the graph the runtime reconciles, and it was
+    // explaining a different one.
+    $asref = canon($name);
+    foreach (Util::sortedkeys($byref) as $ref) {
+        $node = $byref[$ref];
+        // The ref match WINS OUTRIGHT for that node, as at runtime: one
+        // candidate, not two, for a node both named `b` and providing `b`.
+        if ($ref === $asref) {
+            $out[] = ['ref' => $node['ref'], 'pos' => $node['pos'] ?? 0,
+                      'provides' => ['name' => $name]];
+            continue;
+        }
+        foreach ($node['provides'] ?? [] as $prov) {
+            if (($prov['name'] ?? null) !== $name) {
+                continue;
+            }
+            $out[] = ['ref' => $node['ref'], 'pos' => $node['pos'] ?? 0,
+                      'provides' => $prov];
+        }
+    }
+    return $out;
+}