@voxgig/sdkgen 4.9.0 → 4.11.0

package/project/.sdk/src/cmp/zig/Main_zig.ts

@@ -3,7 +3,9 @@ import * as Path from 'node:path'
 
 import {
   cmp, each,
-  File, Copy, Folder, Fragment,
+  File, Content, Copy, Folder, Fragment,
+  pluginExcludes,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -18,18 +20,124 @@ import {
 } from '@voxgig/apidef'
 
 
-import { Config } from './Config_zig'
+import { Config, FeaturePlugins, BUILTIN_FEATURES } from './Config_zig'
 import { Gitignore } from './Gitignore_zig'
 import { MainEntity } from './MainEntity_zig'
 import { Package } from './Package_zig'
 
 
+// Which features ship a zig test suite under test/feature/<name>/, and the
+// file build.zig must NAME to run it. zig has no test auto-discovery: a
+// suite the build file does not list exists and never runs. A map rather
+// than a convention because the file has to EXIST - `zig build` fails the
+// whole build on a test path it cannot find - so this may only name suites
+// the templates actually carry.
+//
+// The suite sits under test/feature/<name>/ so that it belongs to the
+// feature (helpers/featureSource), exactly as go's tm/go/test/feature/
+// secrets/ and rust's tests/feature/secrets/ do; and it is wired only for
+// a feature that is ACTIVE for this target, which is when its build modules
+// (below) exist for the suite to reach.
+//
+// Each suite gets its OWN build step (`zig build test-<name>`) as well as a
+// place in the all-tests `test` step: the corpus suites need a project's
+// compiled `.sdk/test/test.json` beside the SDK, so a checker that has the
+// feature but no corpus (sdkgen's own generatedcompile lane) can still run
+// the feature suite alone and read its count.
+const FEATURE_TESTS: Record<string, string> = {
+  secrets: 'test/feature/secrets/secrets_test.zig',
+}
+
+
+// The GATED features' build modules: what a feature's `@import("<name>")`
+// lines resolve to, declared only when the feature is active. Each entry is
+// the block of build.zig statements that wires one feature; `secrets` is
+// the first and, today, the only one.
+//
+// Upstream's own three-module boundary (sekreto's zig Makefile builds
+// exactly these): `plugin` (voxgig/plugin, rooted at its consumer root),
+// `sekreto` (the core, which imports `plugin` by name and nothing under
+// plugins/), and `sekretoplugins`, rooted at the GENERATED
+// feature/secrets/plugins.zig (Config_zig FeaturePlugins) so that only the
+// selected kinds are compiled. The sdk module gets `sekreto` and
+// `sekretoplugins`; the feature file reaches `plugin` through
+// `sekreto.plugin`, so it needs no import of its own.
+const FEATURE_MODULES: Record<string, string> = {
+  secrets: `// The secrets feature's vendored libraries (@voxgig/sekreto and
+// voxgig/plugin at the shared vendor tag), as the three named modules
+// upstream builds them as. Declared ONLY when the model activates the
+// feature: feature/secrets.zig is the sole importer, and an inactive SDK
+// never analyses it (zig compiles only what a module root reaches).
+const plugin_mod = b.addModule("plugin", .{
+    .root_source_file = b.path("feature/secrets/plugin/plugin.zig"),
+    .target = target,
+    .optimize = optimize,
+});
+const sekreto_mod = b.addModule("sekreto", .{
+    .root_source_file = b.path("feature/secrets/sekreto/sekreto.zig"),
+    .target = target,
+    .optimize = optimize,
+});
+sekreto_mod.addImport("plugin", plugin_mod);
+// Rooted at the GENERATED selection (feature/secrets/plugins.zig), never
+// at upstream's full-set all.zig: the root decides which kinds compile.
+const sekretoplugins_mod = b.addModule("sekretoplugins", .{
+    .root_source_file = b.path("feature/secrets/plugins.zig"),
+    .target = target,
+    .optimize = optimize,
+});
+sekretoplugins_mod.addImport("sekreto", sekreto_mod);
+sekretoplugins_mod.addImport("plugin", plugin_mod);
+sdk_mod.addImport("sekreto", sekreto_mod);
+sdk_mod.addImport("sekretoplugins", sekretoplugins_mod);
+`,
+}
+
+
 const Main = cmp(async function Main(props: any) {
 
   const { target } = props
   const { model } = props.ctx$
 
   const entity: ModelEntity = getModelPath(model, `main.${KIT}.entity`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
+
+  // THE PLUGIN TRIM FOR AN INACTIVE FEATURE (the scala shape, for the same
+  // reason). pluginExcludes(model) walks only the model's ACTIVE features,
+  // which is right for a target whose feature trim is on: an inactive
+  // feature's whole tree is already gone at `target add`. zig's feature trim
+  // is OFF (model/target/zig.aon `feature: { trim: false }` - root.zig's
+  // built-in exports are static), so an inactive feature's tree is all still
+  // here, and its provider plugins are the part that costs the most. EVERY
+  // declared group of an inactive feature goes, not just the groups marked
+  // inactive: a feature that is off has no active plugins whatever its
+  // `plugin` map says, because targetFeatures drops the feature before
+  // Config ever reads a group. What stays is the two vendored cores and the
+  // ungrouped httpjson/sigv4 helpers - dead files zig never analyses, since
+  // build.zig declares no module rooted in them (FEATURE_MODULES).
+  //
+  // Rooting matches pluginExcludes': zig's declared paths are
+  // target-root-relative, which is this Copy's root, and the other targets'
+  // paths in the same list cannot match anything in a zig tree.
+  const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const allfeature = getModelPath(model, `main.${KIT}.feature`,
+    { required: false, only_active: false }) || {}
+  const inactivePluginExcludes: RegExp[] = []
+  for (const fname of Object.keys(allfeature)) {
+    if (null != (feature as any)[fname]) continue
+    const groups = getModelPath(model, `main.${KIT}.feature.${fname}.plugin`,
+      { required: false, only_active: false }) || {}
+    for (const gname of Object.keys(groups)) {
+      for (const one of (groups[gname].path || [])) {
+        const pat = esc(String(one))
+        inactivePluginExcludes.push(new RegExp('(^|/)' +
+          pat.replace(/\\\/$/, '') + (/\/$/.test(String(one)) ? '/' : '$')))
+      }
+    }
+  }
 
   // build.zig.zon — the package manifest, stamped with the model package name.
   Package({ target })
@@ -43,14 +151,110 @@ const Main = cmp(async function Main(props: any) {
   // the tree root (core/, feature/, utility/, entity/, test/) — Zig's
   // idiomatic src/ is not used, to keep the exclude rule identical to the
   // reference targets.
+  //
+  // build.zig and root.zig are NOT in tm/zig any more: both carry
+  // model-driven slots (a gated feature's build modules, test step and root
+  // export) and are emitted below from src/cmp/zig/fragment/, the way
+  // core/sdk.zig always was.
   Copy({
     from: 'tm/' + target.name,
-    exclude: [/src\//, /build\.zig\.zon$/],
+    // pluginExcludes: the generate-time plugin trim for an ACTIVE feature's
+    // inactive groups (the model's `path` entries are target-root-relative,
+    // which is this Copy's root); inactivePluginExcludes (above) for the
+    // groups of a feature that is itself off.
+    exclude: [
+      /src\//,
+      /build\.zig\.zon$/,
+      ...pluginExcludes(model),
+      ...inactivePluginExcludes,
+    ],
     replace: {
       ...props.ctx$.stdrep,
     }
   })
 
+  // The active features that root.zig does not export statically: the
+  // BUILT-IN set is in the template, so this is the gated ones (`secrets`)
+  // and any bespoke feature the model adds. Config_zig names the same
+  // features in make_feature, from the same list, so the two cannot drift.
+  const extraFeatures = each(feature)
+    .filter((f: any) => 'base' !== f.name && !BUILTIN_FEATURES.includes(f.name))
+    .map((f: any) => f.name)
+    .sort()
+
+  const fragdir = Path.normalize(__dirname + '/../../../src/cmp/zig/fragment/')
+
+  // build.zig: the template with its two slots filled - a gated feature's
+  // modules after the sdk module, and its test suite as a step of its own
+  // that the all-tests step also depends on. Both empty for a model that
+  // activates no gated feature, which leaves the file byte-identical to the
+  // fragment minus the marker lines.
+  File({ name: 'build.zig' }, () => {
+    Fragment({
+      from: fragdir + 'Build.fragment.zig',
+      replace: {
+        ...props.ctx$.stdrep,
+
+        '#FeatureModules': ({ indent }: any) => {
+          for (const fname of extraFeatures) {
+            const block = FEATURE_MODULES[fname]
+            if (null != block) Content({ indent }, block)
+          }
+        },
+
+        '#FeatureTestSteps': ({ indent }: any) => {
+          for (const fname of extraFeatures) {
+            const suite = FEATURE_TESTS[fname]
+            if (null == suite) continue
+            Content({ indent }, `// The ${fname} feature suite: part of \`zig build test\`, and alone as
+// \`zig build test-${fname}\` (see FEATURE_TESTS in Main_zig).
+{
+    const ${fname}_mod = b.createModule(.{
+        .root_source_file = b.path("${suite}"),
+        .target = target,
+        .optimize = optimize,
+    });
+    ${fname}_mod.addImport("voxgig-struct", struct_mod);
+    ${fname}_mod.addImport("sdk", sdk_mod);
+    ${fname}_mod.addImport("omni", omni_mod);
+    const ${fname}_test = b.addTest(.{ .root_module = ${fname}_mod });
+    const run_${fname} = b.addRunArtifact(${fname}_test);
+    run_${fname}.has_side_effects = true;
+    test_step.dependOn(&run_${fname}.step);
+    const ${fname}_step = b.step("test-${fname}", "Run the ${fname} feature suite alone");
+    ${fname}_step.dependOn(&run_${fname}.step);
+}
+`)
+          }
+        },
+      }
+    })
+  })
+
+  // root.zig: the module root, with the gated features' type exports
+  // appended to the static built-in ones.
+  File({ name: 'root.zig' }, () => {
+    Fragment({
+      from: fragdir + 'Root.fragment.zig',
+      replace: {
+        ...props.ctx$.stdrep,
+
+        '#FeatureExports': ({ indent }: any) => {
+          for (const fname of extraFeatures) {
+            // MUST match Config_zig's make_feature spelling of the type.
+            const tname = fname.charAt(0).toUpperCase() + fname.slice(1)
+            Content({ indent },
+              `pub const ${tname}Feature = @import("feature/${fname}.zig").${tname}Feature;\n`)
+          }
+        },
+      }
+    })
+  })
+
+  // feature/<name>/plugins.zig: the selected plugin definitions, as the root
+  // of the `sekretoplugins` module build.zig declares above (active only).
+  FeaturePlugins({ target })
+
   // Generated core files: the client (sdk.zig) and the API config. The
   // branded error type (error.zig) is a plain template (copied above).
   Folder({ name: 'core' }, () => {
@@ -59,7 +263,7 @@ const Main = cmp(async function Main(props: any) {
 
       Fragment(
         {
-          from: Path.normalize(__dirname + '/../../../src/cmp/zig/fragment/Main.fragment.zig'),
+          from: fragdir + 'Main.fragment.zig',
           replace: {
             ...props.ctx$.stdrep,
           }

package/project/.sdk/{tm/zig/build.zig → src/cmp/zig/fragment/Build.fragment.zig}

@@ -15,6 +15,11 @@ const std = @import("std");
 // The Zig test framework can crash with signal 11 during cleanup *after* all
 // tests pass, due to *MapRef/*ListRef cross-references in arena teardown. The
 // Makefile filters the output: "N/N tests passed" with N==total is success.
+//
+// GENERATED from src/cmp/zig/fragment/Build.fragment.zig (Main_zig): the
+// `// #...` marker lines there are slots the generator fills from the model -
+// a GATED feature's build modules and its test step appear only when the
+// feature is active, so an SDK without that feature declares none of them.
 pub fn build(b: *std.Build) void {
     const target = b.standardTargetOptions(.{});
     const optimize = b.standardOptimizeOption(.{});
@@ -44,6 +49,7 @@ pub fn build(b: *std.Build) void {
         .optimize = optimize,
     });
     sdk_mod.addImport("voxgig-struct", struct_mod);
+    // #FeatureModules
 
     const test_step = b.step("test", "Run all tests");
 
@@ -73,4 +79,5 @@ pub fn build(b: *std.Build) void {
         run_t.has_side_effects = true;
         test_step.dependOn(&run_t.step);
     }
+    // #FeatureTestSteps
 }

package/project/.sdk/src/cmp/zig/fragment/Main.fragment.zig

@@ -40,6 +40,22 @@ pub const ProjectNameSDK = struct {
     rootctx: ?*Context = null,
 
     pub fn new(options: Value) *ProjectNameSDK {
+        return new_with(options, &.{});
+    }
+
+    // The `extend` seam, in zig's spelling. go/ts/py read live Feature
+    // objects off `options.extend`; a zig Value is a CLOSED data union that
+    // cannot carry a Feature, so the extension list is a second argument
+    // instead - same meaning, same position in construction (added after the
+    // config-driven features, before any init runs).
+    //
+    // DELIBERATE DIVERGENCE: an extension whose NAME the config already
+    // installed is skipped. go adds it regardless and the kotlin/java suites
+    // work around the resulting double install (two transport wraps, two
+    // purchases) by probing the config first; here the seam itself keeps the
+    // set to one feature per name, so a suite can always hand in the feature
+    // it needs and hold in any generated tree.
+    pub fn new_with(options: Value, extend: []const Feature) *ProjectNameSDK {
         const sdk = h.A().create(ProjectNameSDK) catch unreachable;
         sdk.* = .{
             .mode = "live",
@@ -92,6 +108,15 @@ pub const ProjectNameSDK = struct {
             }
         }
 
+        // Add extension features (see new_with).
+        for (extend) |f| {
+            var present = false;
+            for (sdk.features.items) |have| {
+                if (std.mem.eql(u8, have.name(), f.name())) present = true;
+            }
+            if (!present) sdk.sdkUtility.feature_add(rootctx, f);
+        }
+
         // Initialize features.
         var snap: std.ArrayList(Feature) = .empty;
         for (sdk.features.items) |f| snap.append(h.A(), f) catch {};

package/project/.sdk/{tm/zig/root.zig → src/cmp/zig/fragment/Root.fragment.zig}

@@ -1,5 +1,8 @@
 // ProjectName SDK for Zig (generated by @voxgig/sdkgen).
 //
+// GENERATED from src/cmp/zig/fragment/Root.fragment.zig (Main_zig) - see the
+// FeatureExports marker below for the one model-driven slot.
+//
 // The module root: it re-exports the public surface and pulls in the whole
 // SDK graph (core -> config -> features/utility/entities) so `@import("sdk")`
 // from the test suite sees everything. Layout mirrors the other targets:
@@ -59,6 +62,12 @@ pub const DebugFeature = @import("feature/debug.zig").DebugFeature;
 pub const AuditFeature = @import("feature/audit.zig").AuditFeature;
 pub const ClienttrackFeature = @import("feature/clienttrack.zig").ClienttrackFeature;
 pub const RbacFeature = @import("feature/rbac.zig").RbacFeature;
+// GATED features (model/feature/<name>.aon `needs:`), exported ONLY when the
+// model activates them: their source reaches a named build module (the
+// vendored sekreto for `secrets`) that build.zig declares under the same
+// condition, so a static export here would name a module an inactive SDK
+// does not have. Filled by Main_zig from this marker.
+// #FeatureExports
 
 // Value helpers, re-exported so tests/consumers can build data.
 pub const h = helpers;

package/project/.sdk/tm/c/Makefile

@@ -4,24 +4,65 @@
 
 CC ?= gcc
 CFLAGS ?= -std=c11 -Wall -Wextra -Wno-unused-parameter -D_GNU_SOURCE -O0 -g
-INC := -I core -I utility/struct
+# -I feature: a feature's own header (feature/<name>.h), which a suite under
+# tests/feature/<name>/ includes by bare name the way every test includes
+# sdk.h. Then EVERY payload directory two levels under feature/: a feature
+# that carries a vendored library keeps it in feature/<name>/<lib>/, and
+# every quoted include inside such a port is a bare basename resolved
+# through these. Derived from the tree rather than listed, so the Makefile
+# names no feature; harmless when the feature trim has removed the
+# directories (the wildcard is then empty), and a payload's value.h /
+# point.h / types.h shadow nothing: the SDK's own value.h (utility/struct)
+# is reached by its neighbours through the including file's directory,
+# which a quoted include searches before any -I.
+PAYLOAD_DIRS := $(patsubst %/,%,$(wildcard feature/*/*/))
+INC := -I core -I utility/struct -I feature $(addprefix -I ,$(PAYLOAD_DIRS))
 # The vendored omni test runner (tests/vendor/omni) is TEST-ONLY: it is
 # reachable from tests/ alone, never from LIB_SRCS, so it cannot enter the
 # shipped libsdk.a. That is why it lives under tests/ and not utility/.
 OMNI_INC := -I tests -I tests/vendor/omni
+# The test harness headers (ctest.h, feature_harness.h) by bare name, for a
+# suite that lives BELOW tests/ (a gated feature's tests/feature/<name>/
+# suite) and so cannot reach them through its own directory as tests/*.c do.
+TEST_INC := -I tests
 LDLIBS := -lm
 
+# ---- gated feature payloads (model/feature/<name>.aon plugin groups) --------
+#
+# A gated feature's vendored payload sits two levels under feature/
+# (feature/<name>/<lib>/*.c) - out of reach of the feature/*/*.c glob below,
+# and deliberately so. What of it is built is decided by a GENERATED make
+# fragment, feature/<name>/kinds.mk, that Config_c emits beside the
+# feature's generated kinds.c only when the model activates the feature for
+# this target. The fragment appends the payload sources to FEATURE_SRCS, the
+# feature's suite to FEATURE_TEST_SRCS, and - only when a plugin group is
+# active - the plugin layer and the external libraries it brings to LDLIBS.
+# Nothing here names a feature: a tree whose model never activated one
+# carries its payload as inert source (as rust carries a module no parent
+# declares), links libc alone, and a project's `target add` trims it
+# outright. `ldd` on any test binary shows which case this tree is.
+FEATURE_SRCS :=
+FEATURE_TEST_SRCS :=
+-include $(wildcard feature/*/kinds.mk)
+
 # feature/*/*.c: a feature may carry a vendored library payload in its own
 # subdirectory (the station feature vendors voxgig_station there - C has no
 # package registry, so tier-C libraries ride the feature source; see
 # utility/struct/ for the same precedent at the utility level). Empty when
-# no feature ships one.
-LIB_SRCS := $(wildcard core/*.c utility/*.c utility/struct/*.c feature/*.c feature/*/*.c entity/*.c)
+# no feature ships one. A gated feature's own feature/<name>.c is in this
+# glob too and always compiles (its headers are on INC above); without its
+# kinds.mk nothing references it, so the archive member is never pulled
+# into a link.
+LIB_SRCS := $(wildcard core/*.c utility/*.c utility/struct/*.c feature/*.c feature/*/*.c entity/*.c) \
+  $(FEATURE_SRCS)
 LIB_OBJS := $(LIB_SRCS:.c=.o)
 
 # Single-level on purpose: the vendored omni sources under
-# tests/vendor/omni have no main() and must not become test binaries.
-TEST_SRCS := $(wildcard tests/*.c)
+# tests/vendor/omni have no main() and must not become test binaries. A
+# gated feature's suite under tests/feature/<name>/ is added by its
+# generated kinds.mk, so it is only ever built when the feature it links
+# against is wired in.
+TEST_SRCS := $(wildcard tests/*.c) $(FEATURE_TEST_SRCS)
 TEST_BINS := $(TEST_SRCS:.c=.out)
 
 OMNI_SRCS := $(wildcard tests/vendor/omni/*.c)
@@ -36,7 +77,14 @@ build: libsdk.a
 %.o: %.c
 	$(CC) $(CFLAGS) $(INC) -c $< -o $@
 
+# `ar r` REPLACES a member by basename on an archive it finds, and this
+# archive carries duplicate basenames by construction: core/utility.o
+# beside utility/struct/utility.o, and a vendored payload's point.o,
+# config.o and value.o beside core's and utility/struct's. One cold
+# `ar rcs` keeps every member; an incremental one would silently drop
+# whichever came first, so the archive is deleted before it is written.
 libsdk.a: $(LIB_OBJS)
+	@rm -f $@
 	ar rcs $@ $(LIB_OBJS)
 
 # omni's util.c includes <regex.h>. CFLAGS is `?=`, so an operator override
@@ -50,6 +98,7 @@ tests/vendor/omni/%.o: tests/vendor/omni/%.c
 	$(CC) $(CFLAGS) -D_POSIX_C_SOURCE=200809L -D_DARWIN_C_SOURCE -c $< -o $@
 
 libomni.a: $(OMNI_OBJS)
+	@rm -f $@
 	ar rcs $@ $(OMNI_OBJS)
 
 # Only the corpus drivers and the smoke test reach for omni, and the generic
@@ -61,10 +110,10 @@ OMNI_TESTS := tests/struct_corpus_test.out tests/primary_corpus_test.out \
   tests/omni_smoke_test.out
 
 $(OMNI_TESTS): tests/%.out: tests/%.c libsdk.a libomni.a
-	$(CC) $(CFLAGS) $(INC) $(OMNI_INC) $< libsdk.a libomni.a -o $@ $(LDLIBS)
+	$(CC) $(CFLAGS) $(INC) $(TEST_INC) $(OMNI_INC) $< libsdk.a libomni.a -o $@ $(LDLIBS)
 
 tests/%.out: tests/%.c libsdk.a
-	$(CC) $(CFLAGS) $(INC) $< libsdk.a -o $@ $(LDLIBS)
+	$(CC) $(CFLAGS) $(INC) $(TEST_INC) $< libsdk.a -o $@ $(LDLIBS)
 
 # Build and run every test; aggregate pass/fail.
 test: libsdk.a libomni.a
@@ -72,7 +121,7 @@ test: libsdk.a libomni.a
 	for src in $(TEST_SRCS); do \
 	  bin=$${src%.c}.out; \
 	  case " $(OMNI_TESTS) " in *" $$bin "*) omni="libomni.a"; oinc="$(OMNI_INC)";; *) omni=""; oinc="";; esac; \
-	  $(CC) $(CFLAGS) $(INC) $$oinc $$src libsdk.a $$omni -o $$bin $(LDLIBS) || { echo "BUILD FAIL: $$src"; fail=1; continue; }; \
+	  $(CC) $(CFLAGS) $(INC) $(TEST_INC) $$oinc $$src libsdk.a $$omni -o $$bin $(LDLIBS) || { echo "BUILD FAIL: $$src"; fail=1; continue; }; \
 	  total=$$((total+1)); \
 	  if ./$$bin; then :; else echo "TEST FAIL: $$bin"; fail=1; fi; \
 	done; \
@@ -82,7 +131,7 @@ test: libsdk.a libomni.a
 
 clean:
 	rm -f $(LIB_OBJS) libsdk.a $(OMNI_OBJS) libomni.a $(TEST_BINS) tests/*.out \
-	  corpus-scoreboard.json
+	  tests/feature/*/*.out corpus-scoreboard.json
 
 # C has no central registry — publishing IS the git tag.
 VERSION := $(shell cat VERSION 2>/dev/null || echo 0.0.1)

package/project/.sdk/tm/c/core/sdk.h

@@ -448,6 +448,16 @@ voxgig_value* make_config(void);
 voxgig_value* shared_config(void);
 Feature* make_feature(const char* name);
 
+// The plugin DEFINITIONS the model selected for one feature's chain - the c
+// peer of go's core.FeaturePlugins(name). Each entry is a `Definition*` from
+// the vendored voxgig/plugin (feature/secrets/plugin/catalog.h), typed void*
+// here because core/ must never name a gated feature's types: the accessor
+// exists in every generated config.c, and answers *n = 0 / NULL for a
+// feature with no plugins or an SDK that never selected the feature. A
+// feature casts the array back at the one place it hands the list to the
+// vendored library.
+void** feature_plugins(const char* name, size_t* n);
+
 // ===========================================================================
 // Utility builder prototypes (utility/*.c). Fallible ones take PNError** err.
 // ===========================================================================

package/project/.sdk/tm/c/feature/secrets/plugin/capability.c

@@ -0,0 +1,133 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (c/src/capability.c)
+// 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.
+/* Capabilities (§11.1). */
+
+#include <stdlib.h>
+#include <string.h>
+
+#include "capability.h"
+#include "version.h"
+
+bool capmatchvalue(Value *want, Value *got) {
+  /* THIS FUNCTION IS WHAT "EVERY LEAF" MEANS, and an earlier draft of
+   * the canonical did not have it: the check was a scalar compare,
+   * which for any compound value is reference identity in JavaScript. A
+   * requirement and a capability are declared in different places and
+   * are never the same object, so `match: {limits: {max: 5}}` could not
+   * be satisfied by ANY provider — including one declaring exactly
+   * that. Invisible while every corpus entry is scalar, which is why
+   * the go port found it and P2 did not. */
+  if (vismap(want)) {
+    if (!vismap(got)) return false;
+    const char **keys;
+    size_t n = vkeys(want, &keys);
+    for (size_t i = 0; i < n; i++) {
+      if (!vhas(got, keys[i])) return false;
+      if (!capmatchvalue(vget(want, keys[i]), vget(got, keys[i]))) return false;
+    }
+    return true;
+  }
+  if (vislist(want)) {
+    if (!vislist(got) || vlen(want) != vlen(got)) return false;
+    for (size_t i = 0; i < vlen(want); i++) {
+      if (!capmatchvalue(vat(want, i), vat(got, i))) return false;
+    }
+    return true;
+  }
+  return vsame(want, got);
+}
+
+bool capmatches(Value *req, Value *prov) {
+  Value *rname = vget(req, "name");
+  Value *pname = vget(prov, "name");
+  if (!vsame(rname, pname)) return false;
+
+  Value *range = vget(req, "range");
+  if (!visnull(range)) {
+    Value *version = vget(prov, "version");
+    if (visnull(version)) return false;
+    if (!satisfiesq(version, range)) return false;
+  }
+
+  /* `match` is checked against the provider's `attrs`, key by key. A
+   * key the provider does not carry is a MISS, not a pass: a
+   * requirement asking for `transactional: true` must not be satisfied
+   * by a provider that never said. */
+  Value *match = vget(req, "match");
+  if (!visnull(match)) {
+    Value *attrs = vget(prov, "attrs");
+    if (visnull(attrs)) attrs = vmap();
+    const char **keys;
+    size_t n = vkeys(match, &keys);
+    for (size_t i = 0; i < n; i++) {
+      if (!vhas(attrs, keys[i])) return false;
+      if (!capmatchvalue(vget(match, keys[i]), vget(attrs, keys[i]))) {
+        return false;
+      }
+    }
+  }
+
+  return true;
+}
+
+/* The rank, as a comparison over two candidates. Ordering is a total
+ * rank on purpose: without one, "any provider satisfies" is true of the
+ * GRAPH and useless to the PLUGIN — two ports could bind different
+ * `store` instances, both resolve green, and behave differently, which
+ * is precisely the divergence a shared corpus exists to catch. */
+static int rank(const void *pa, const void *pb) {
+  Value *a = *(Value *const *)pa;
+  Value *b = *(Value *const *)pb;
+  Value *ap = vget(a, "provides");
+  Value *bp = vget(b, "provides");
+
+  Value *av = vget(ap, "version");
+  Value *bv = vget(bp, "version");
+  bool ahas = !visnull(av), bhas = !visnull(bv);
+  if (ahas != bhas) return ahas ? -1 : 1;   /* a version beats none */
+  if (ahas && bhas) {
+    /* HIGHEST version first, so the comparison is reversed. */
+    CatchFrame f;
+    int c = 0;
+    if (0 == PLUGIN_TRY(&f)) {
+      c = vercmp(parseversion(bv), parseversion(av));
+      PLUGIN_END(&f);
+    }
+    else {
+      c = 0;
+    }
+    if (0 != c) return c;
+  }
+
+  double apri = visnum(vget(ap, "priority")) ? vasnum(vget(ap, "priority")) : 0.0;
+  double bpri = visnum(vget(bp, "priority")) ? vasnum(vget(bp, "priority")) : 0.0;
+  if (apri != bpri) return apri < bpri ? -1 : 1;   /* LOWEST priority first */
+
+  double apos = visnum(vget(a, "pos")) ? vasnum(vget(a, "pos")) : 0.0;
+  double bpos = visnum(vget(b, "pos")) ? vasnum(vget(b, "pos")) : 0.0;
+  if (apos != bpos) return apos < bpos ? -1 : 1;
+  return 0;
+}
+
+Value *resolvecapability(Value *req, Value *candidates) {
+  size_t n = vlen(candidates);
+  Value **hits = (Value **)arena_alloc(sizeof(Value *) * (n + 1));
+  size_t count = 0;
+  for (size_t i = 0; i < n; i++) {
+    Value *c = vat(candidates, i);
+    if (capmatches(req, vget(c, "provides"))) hits[count++] = c;
+  }
+
+  /* A STABLE SORT. `qsort` is not stable, and §6.3's tie rules make the
+   * order observable — so `rank` is a TOTAL order (it falls through to
+   * `pos`, which is unique) and stability is not relied on. An earlier
+   * reading that stopped at `priority` would have left ties to qsort's
+   * discretion, which is exactly the per-port divergence the ranking
+   * exists to remove. */
+  if (1 < count) qsort(hits, count, sizeof(Value *), rank);
+
+  Value *out = vlist();
+  for (size_t i = 0; i < count; i++) vpush(out, hits[i]);
+  return out;
+}

package/project/.sdk/tm/c/feature/secrets/plugin/capability.h

@@ -0,0 +1,39 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (c/src/capability.h)
+// 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.
+/* Capabilities (§11.1).
+ *
+ * A DEPENDENCY IS ON A CAPABILITY, NOT ON A REF — because it is a
+ * dependency on something that can do the job, and which instance is
+ * doing it is exactly the configuration detail a plugin must not care
+ * about. (§11.1 makes one narrow exception for a ref, and `host.c`
+ * implements it; the ranking here is capabilities only.)
+ *
+ * But A BINDING IS TO AN INSTANCE, not to a capability, which is what
+ * decides behaviour when the bound provider leaves while another match
+ * remains. */
+
+#ifndef VOXGIG_PLUGIN_CAPABILITY_H
+#define VOXGIG_PLUGIN_CAPABILITY_H
+
+#include <stdbool.h>
+
+#include "types.h"
+#include "value.h"
+
+/* Rank the matching providers best-first: highest `version`, then
+ * LOWEST `priority` (default 0), then declaration position `pos`
+ * ascending. `candidates` is a list of {ref, pos, provides}. */
+Value *resolvecapability(Value *req, Value *candidates);
+
+/* Does one provider satisfy one requirement? */
+bool capmatches(Value *req, Value *prov);
+
+/* PARTIAL MATCH, RECURSING INTO MAPS (§11.1): every leaf in the
+ * requirement must be present and equal in the capability, keys not
+ * mentioned are not checked. A LIST IS COMPARED LEAF-WISE AT THE SAME
+ * LENGTH, not as a subset — "the first two of your three regions" is
+ * not something `match` can say. */
+bool capmatchvalue(Value *want, Value *got);
+
+#endif