@voxgig/sdkgen 1.3.18 → 1.4.0

package/project/.sdk/tm/rb/utility/make_options.rb

@@ -52,6 +52,11 @@ module ProjectNameUtilities
       "system" => {},
       "test" => { "active" => false, "entity" => { "`$OPEN`" => true } },
       "clean" => { "keys" => "key,token,id" },
+      # Server-variable values for a templated base URL (OpenAPI server
+      # variables): {name} placeholders in "base" are substituted from this
+      # map at construction. Spec defaults arrive via the generated config;
+      # user values override them.
+      "server" => { "`$CHILD`" => "" },
     }
 
     sys_fetch = VoxgigStruct.getpath(opts, "system.fetch")
@@ -60,6 +65,38 @@ module ProjectNameUtilities
     validated = VoxgigStruct.validate(merged, optspec)
     opts = validated.is_a?(Hash) ? validated : {}
 
+    # Resolve a templated base URL (e.g. https://{tenant_id}.hanko.io).
+    # Every placeholder must resolve to a non-empty value: from
+    # options["server"] (user), else the config default. A placeholder that
+    # resolves to "" is a construction ERROR in live mode — the URL cannot
+    # work — but in test mode substitutes the deterministic value
+    # "test-<name>" so offline tests need no configuration.
+    base = opts["base"]
+    if base.is_a?(String) && base.include?("{")
+      testmode = VoxgigStruct.getpath(opts, "test.active") == true ||
+        VoxgigStruct.getpath(opts, "feature.test.active") == true
+      server = opts["server"].is_a?(Hash) ? opts["server"] : {}
+      sdkname = VoxgigStruct.getpath(config, "main.name")
+      sdkname = "SDK" unless sdkname.is_a?(String) && !sdkname.empty?
+      opts["base"] = base.gsub(/\{([A-Za-z0-9_]+)\}/) do
+        name = Regexp.last_match(1)
+        val = server[name]
+        val = "" unless val.is_a?(String)
+        if val.empty?
+          if testmode
+            "test-#{name}"
+          else
+            raise ArgumentError,
+              "#{sdkname}: the server variable '#{name}' is required: " \
+              "the API base URL is '#{base}' — pass " \
+              "{ \"server\" => { \"#{name}\" => \"...\" } } in the SDK options"
+          end
+        else
+          val
+        end
+      end
+    end
+
     if sys_fetch
       opts["system"] = {} unless opts["system"].is_a?(Hash)
       opts["system"]["fetch"] = sys_fetch

package/project/.sdk/tm/rb/utility/prepare_method.rb

@@ -1,5 +1,14 @@
 # ProjectName SDK utility: prepare_method
+require_relative 'struct/voxgig_struct'
 module ProjectNameUtilities
   METHOD_MAP = { "create"=>"POST", "update"=>"PUT", "load"=>"GET", "list"=>"GET", "remove"=>"DELETE", "patch"=>"PATCH" }
-  PrepareMethod = ->(ctx) { METHOD_MAP[ctx.op.name] || "GET" }
+
+  # The API definition is authoritative: a POST-only or PATCH-based API
+  # exposes `update` as POST or PATCH, not the PUT the op name implies.
+  # Only fall back to the op-name convention when the point has no method.
+  PrepareMethod = ->(ctx) {
+    method = VoxgigStruct.getprop(ctx.point, "method")
+    next method.upcase if method.is_a?(String) && "" != method
+    METHOD_MAP[ctx.op.name] || "GET"
+  }
 end

package/project/.sdk/tm/rust/Makefile

@@ -13,21 +13,21 @@ clean:
 # The crates.io registry entry is declared in the model with
 # state: 'pending' — a real deploy publishes the git tag rust/vX.Y.Z only;
 # `cargo publish` starts when the registry state flips to 'active'. Run
-# headless under the aql key vault, which injects the GitHub token so
+# headless under the boru key vault, which injects the GitHub token so
 # nothing lands on disk or argv:
-#   aql vault exec --for=github=<alias> -- make publish
-# aql `--dry-run` injects a filler token we detect to rehearse (no tag/push).
+#   boru vault exec --for=github=<alias> -- make publish
+# boru `--dry-run` injects a filler token we detect to rehearse (no tag/push).
 # set -e + tag-last: a failed push never leaves a tag behind.
 VERSION := $(shell cat VERSION)
 TAG := rust/v$(VERSION)
-AQL_DRY_RUN_FILLER := AQL-DRY-RUN-FILLER-NOT-A-REAL-SECRET
+BORU_DRY_RUN_FILLER := BORU-DRY-RUN-FILLER-NOT-A-REAL-SECRET
 publish:
 	@if git rev-parse -q --verify "refs/tags/$(TAG)" >/dev/null; then \
 	  echo "tag $(TAG) already exists — bump VERSION first"; exit 1; fi
 	@set -e; \
 	token="$${GITHUB_TOKEN:-$$GH_TOKEN}"; \
-	if [ "$$token" = "$(AQL_DRY_RUN_FILLER)" ]; then \
-	  echo "[dry-run] aql filler token detected: would tag $(TAG); nothing pushed."; \
+	if [ "$$token" = "$(BORU_DRY_RUN_FILLER)" ]; then \
+	  echo "[dry-run] boru filler token detected: would tag $(TAG); nothing pushed."; \
 	  exit 0; \
 	fi; \
 	git tag -a "$(TAG)" -m "rust v$(VERSION)"; \

package/project/.sdk/tm/rust/utility/prepare_method.rs

@@ -1,10 +1,22 @@
 use std::rc::Rc;
 
 use crate::core::context::Context;
+use crate::core::helpers::getp;
+use crate::utility::voxgigstruct::Value;
 
 pub fn prepare_method_util(ctx: &Rc<Context>) -> String {
     let opname = ctx.op.borrow().name.clone();
 
+    // The API definition is authoritative: a POST-only or PATCH-based API
+    // exposes `update` as POST or PATCH, not the PUT the op name implies.
+    // Only fall back to the op-name convention when the point has no method.
+    let point = ctx.point.borrow().clone();
+    if let Value::Str(pm) = getp(&point, "method") {
+        if !pm.is_empty() {
+            return pm.to_uppercase();
+        }
+    }
+
     match opname.as_str() {
         "create" => "POST",
         "update" => "PUT",

package/project/.sdk/tm/scala/utility/Prepare.scala

@@ -14,14 +14,20 @@ object PreparePath {
 }
 
 object PrepareMethod {
-  def prepareMethod(ctx: Context): String = ctx.op.name match {
-    case "create" => "POST"
-    case "update" => "PUT"
-    case "load" => "GET"
-    case "list" => "GET"
-    case "remove" => "DELETE"
-    case "patch" => "PATCH"
-    case _ => "GET"
+  // The API definition is authoritative: a POST-only or PATCH-based API
+  // exposes `update` as POST or PATCH, not the PUT the op name implies.
+  // Only fall back to the op-name convention when the point has no method.
+  def prepareMethod(ctx: Context): String = Struct.getprop(ctx.point, "method") match {
+    case s: String if s.nonEmpty => s.toUpperCase
+    case _ => ctx.op.name match {
+      case "create" => "POST"
+      case "update" => "PUT"
+      case "load" => "GET"
+      case "list" => "GET"
+      case "remove" => "DELETE"
+      case "patch" => "PATCH"
+      case _ => "GET"
+    }
   }
 }
 

package/project/.sdk/tm/swift/Makefile

@@ -13,21 +13,21 @@ clean:
 # --- Release: tag for the SwiftPM registry ---------------------------------
 # SwiftPM has no upload step - publishing IS the git tag. Publication is
 # pending (see model/target/swift.aontu publish block); publishing a version
-# currently means pushing the tag swift/vX.Y.Z. Run headless under the aql key
+# currently means pushing the tag swift/vX.Y.Z. Run headless under the boru key
 # vault, which injects the GitHub token so nothing lands on disk or argv:
-#   aql vault exec --for=github=<alias> -- make publish
-# aql `--dry-run` injects a filler token we detect to rehearse (no tag/push).
+#   boru vault exec --for=github=<alias> -- make publish
+# boru `--dry-run` injects a filler token we detect to rehearse (no tag/push).
 # set -e + tag-last: a failed push never leaves a tag behind.
 VERSION := $(shell cat VERSION)
 TAG := swift/v$(VERSION)
-AQL_DRY_RUN_FILLER := AQL-DRY-RUN-FILLER-NOT-A-REAL-SECRET
+BORU_DRY_RUN_FILLER := BORU-DRY-RUN-FILLER-NOT-A-REAL-SECRET
 publish: test
 	@if git rev-parse -q --verify "refs/tags/$(TAG)" >/dev/null; then \
 	  echo "tag $(TAG) already exists - bump VERSION first"; exit 1; fi
 	@set -e; \
 	token="$${GITHUB_TOKEN:-$$GH_TOKEN}"; \
-	if [ "$$token" = "$(AQL_DRY_RUN_FILLER)" ]; then \
-	  echo "[dry-run] aql filler token detected: would tag $(TAG); nothing pushed."; \
+	if [ "$$token" = "$(BORU_DRY_RUN_FILLER)" ]; then \
+	  echo "[dry-run] boru filler token detected: would tag $(TAG); nothing pushed."; \
 	  exit 0; \
 	fi; \
 	git tag -a "$(TAG)" -m "swift v$(VERSION)"; \

package/project/.sdk/tm/swift/Sources/ProjectNameSDK/utility/Prepare.swift

@@ -14,6 +14,14 @@ private let methodMap: [String: String] = [
 
 func prepareMethodUtil(_ ctx: Context) -> String {
   let opname = ctx.op!.name
+
+  // The API definition is authoritative: a POST-only or PATCH-based API
+  // exposes `update` as POST or PATCH, not the PUT the op name implies.
+  // Only fall back to the op-name convention when the point has no method.
+  if let pm = gp(ctx.point, "method").asString, !pm.isEmpty {
+    return pm.uppercased()
+  }
+
   return methodMap[opname] ?? "GET"
 }
 

package/project/.sdk/tm/ts/Makefile

@@ -17,22 +17,22 @@ clean:
 
 # --- Release: publish to npm ----------------------------------------------
 # Compile, then publish this package to npm and tag ts/vX.Y.Z. Run headless
-# under the aql key vault, which injects the npm auth token + the GitHub token
+# under the boru key vault, which injects the npm auth token + the GitHub token
 # (never on disk or argv):
-#   aql vault exec --for=npm=<alias> --for=github=<alias> -- make publish
-# aql `--dry-run` injects a filler token we detect to rehearse (build only, no
+#   boru vault exec --for=npm=<alias> --for=github=<alias> -- make publish
+# boru `--dry-run` injects a filler token we detect to rehearse (build only, no
 # publish/tag). set -e + tag-last: a failed publish never leaves a tag behind.
 SHELL := /bin/bash
 VERSION := $(shell node -p "require('./package.json').version")
 TAG := ts/v$(VERSION)
-AQL_DRY_RUN_FILLER := AQL-DRY-RUN-FILLER-NOT-A-REAL-SECRET
+BORU_DRY_RUN_FILLER := BORU-DRY-RUN-FILLER-NOT-A-REAL-SECRET
 publish: test
 	@if git rev-parse -q --verify "refs/tags/$(TAG)" >/dev/null; then \
 	  echo "tag $(TAG) already exists — bump package.json version first"; exit 1; fi
 	@set -e; \
 	token="$${GITHUB_TOKEN:-$$GH_TOKEN}"; \
-	if [ "$$token" = "$(AQL_DRY_RUN_FILLER)" ]; then \
-	  echo "[dry-run] aql filler token detected: would publish to npm and tag $(TAG); nothing pushed."; \
+	if [ "$$token" = "$(BORU_DRY_RUN_FILLER)" ]; then \
+	  echo "[dry-run] boru filler token detected: would publish to npm and tag $(TAG); nothing pushed."; \
 	  exit 0; \
 	fi; \
 	npm stage publish --access public --registry https://registry.npmjs.org; \

package/project/.sdk/tm/ts/src/utility/MakeOptionsUtility.ts

@@ -82,16 +82,54 @@ function makeOptions(ctx: Context) {
     },
     clean: {
       keys: 'key,token,id'
+    },
+    // Server-variable values for a templated base URL (OpenAPI server
+    // variables): `{name}` placeholders in `base` are substituted from
+    // this map at construction. Spec defaults arrive via the generated
+    // Config; user values override them.
+    server: {
+      '`$CHILD`': ''
     }
   }
 
   // JavaScript specific option values.
   optspec.system.fetch = opts.system?.fetch || global.fetch
 
-  opts = merge([{}, cfgopts, opts])
+  // Clone the config side before merging: `config` is a module-level
+  // singleton in ts/js, and merge would otherwise use its nested maps as
+  // merge TARGETS — one instance's options (server, headers, ...) would
+  // contaminate every instance constructed after it.
+  opts = merge([{}, struct.clone(cfgopts), opts])
 
   opts = validate(opts, optspec)
 
+  // Resolve a templated base URL (e.g. https://{tenant_id}.hanko.io).
+  // Every placeholder must resolve to a non-empty value: from
+  // options.server (user), else the Config default. A placeholder that
+  // resolves to '' is a construction ERROR in live mode — the URL cannot
+  // work — but in test mode substitutes the deterministic value
+  // `test-<name>` so offline tests need no configuration.
+  if ('string' === typeof opts.base && opts.base.includes('{')) {
+    const testmode = true === opts.test.active ||
+      true === (opts.feature && opts.feature.test && opts.feature.test.active)
+    const server = opts.server || {}
+    opts.base = opts.base.replace(/\{([A-Za-z0-9_]+)\}/g,
+      (_m: string, name: string) => {
+        let val = server[name]
+        val = 'string' === typeof val ? val : ''
+        if ('' === val) {
+          if (testmode) {
+            return 'test-' + name
+          }
+          throw new Error(
+            `${config?.main?.name || 'SDK'}: the server variable '${name}' is required: ` +
+            `the API base URL is '${opts.base}' — pass { server: { ${name}: '...' } } ` +
+            `in the SDK options`)
+        }
+        return val
+      })
+  }
+
   // Resolve the feature add-order: an explicit array order (above) wins;
   // otherwise order the map test-first, then the remaining names sorted, so
   // the outcome is deterministic and `test` is always the base transport.

package/project/.sdk/tm/ts/src/utility/PrepareMethodUtility.ts

@@ -16,6 +16,15 @@ function prepareMethod(ctx: Context) {
     patch: 'PATCH',
   }
 
+  // The API definition is authoritative: a POST-only or PATCH-based API
+  // exposes `update` as POST or PATCH, not the PUT the op name implies.
+  // Only fall back to the op-name convention when the point has no method.
+  const method = ctx.point?.method
+
+  if (null != method && '' !== method) {
+    return method.toUpperCase()
+  }
+
   return methodMap[key]
 }
 

package/project/.sdk/tm/ts/test/utility/PrimaryUtility.test.ts

@@ -229,6 +229,8 @@ describe('PrimaryUtility', async () => {
       body: 'present',
     })
     const reqClient = new (SDK as any)({
+      // Concrete base: a live construction must satisfy any server variables a templated base URL declares; a literal base sidesteps the requirement.
+      base: 'http://localhost:8080',
       system: { fetch: mockFetch }
     })
     const reqUtility = reqClient.utility()
@@ -410,6 +412,7 @@ describe('PrimaryUtility', async () => {
   test('fetcher-live', async () => {
     const calls: any[] = []
     const liveClient = new (SDK as any)({
+      base: 'http://localhost:8080',
       system: {
         fetch: async (url: string, init: any) => {
           calls.push({ url, init })
@@ -431,6 +434,7 @@ describe('PrimaryUtility', async () => {
 
   test('fetcher-blocked-test-mode', async () => {
     const blockedClient = new (SDK as any)({
+      base: 'http://localhost:8080',
       system: { fetch: async () => ({}) }
     })
     blockedClient._mode = 'test'

package/project/.sdk/tm/zig/core/utility.zig

@@ -825,6 +825,21 @@ pub fn param_util(ctx: *Context, paramdef: Value) Value {
 
 pub fn prepare_method_util(ctx: *Context) []const u8 {
     const opname = ctx.op.name;
+
+    // The API definition is authoritative: a POST-only or PATCH-based API
+    // exposes `update` as POST or PATCH, not the PUT the op name implies.
+    // Only fall back to the op-name convention when the point has no method.
+    switch (h.getp(ctx.point, "method")) {
+        .string => |m| {
+            if (0 < m.len) {
+                const upper = h.A().alloc(u8, m.len) catch return m;
+                for (m, 0..) |c, i| upper[i] = std.ascii.toUpper(c);
+                return upper;
+            }
+        },
+        else => {},
+    }
+
     if (std.mem.eql(u8, opname, "create")) return "POST";
     if (std.mem.eql(u8, opname, "update")) return "PUT";
     if (std.mem.eql(u8, opname, "load")) return "GET";

package/src/cmp/Deploy.ts

@@ -10,7 +10,7 @@ import {
 // `publish` sections (see model/sdkgen.aontu):
 //
 //   publish.tag       — git release tag `<prefix>/vX.Y.Z`; every port has
-//                       one, pushed with a token from the aql key vault
+//                       one, pushed with a token from the boru key vault
 //                       (--for recipe + alias, default github/github).
 //   publish.registry  — package registry details (name, url, vault
 //                       credential recipe or raw env mapping) plus a
@@ -25,7 +25,7 @@ import {
 // Follows the voxgig/struct root Makefile conventions: per-target deploy
 // targets, deliberately no all-targets real deploy (each upload is
 // irreversible), and an everything-at-once DRY run leaning on
-// `aql vault exec --dry-run` filler-token cooperation in each target's
+// `boru vault exec --dry-run` filler-token cooperation in each target's
 // publish recipe.
 const Deploy = cmp(function Deploy(props: any) {
   const { ctx$ } = props
@@ -76,7 +76,7 @@ function aliasVarName(name: string): string {
 }
 
 
-// The aql vault exec argument string for a target: `--for=<recipe>=<alias>`
+// The boru vault exec argument string for a target: `--for=<recipe>=<alias>`
 // flags where a preset recipe exists, or a raw `'alias=ENV_VAR,...'`
 // mapping when any credential lacks a preset (e.g. luarocks). The github
 // token for the tag push is always included.
@@ -142,10 +142,10 @@ function makeDeployMakefile(model: any, targets: any[]): string {
       return `
 deploy-${t.name}:
 \t@echo "deploy-${t.name}: tag-only port — publishing the git tag."
-\taql vault exec ${ghArgs} -- $(MAKE) tag-push-${t.name}
+\tboru vault exec ${ghArgs} -- $(MAKE) tag-push-${t.name}
 
 deploy-dry-${t.name}:
-\taql vault exec --dry-run ${ghArgs} -- $(MAKE) tag-push-${t.name}
+\tboru vault exec --dry-run ${ghArgs} -- $(MAKE) tag-push-${t.name}
 ${tagPushRecipe(t.name, 'tag-only port')}
 `
     }
@@ -157,20 +157,20 @@ ${tagPushRecipe(t.name, 'tag-only port')}
       return `
 deploy-${t.name}:
 \t@echo "deploy-${t.name}: ${reg.name} publication is pending — publishing the git tag only."
-\taql vault exec ${ghArgs} -- $(MAKE) tag-push-${t.name}
+\tboru vault exec ${ghArgs} -- $(MAKE) tag-push-${t.name}
 
 deploy-dry-${t.name}:
-\taql vault exec --dry-run ${ghArgs} -- $(MAKE) tag-push-${t.name}
+\tboru vault exec --dry-run ${ghArgs} -- $(MAKE) tag-push-${t.name}
 ${tagPushRecipe(t.name, reg.name + ' publication pending — tag-only deploy')}
 `
     }
 
     return `
 deploy-${t.name}:
-\taql vault exec ${args} -- $(MAKE) -C ${t.name} publish
+\tboru vault exec ${args} -- $(MAKE) -C ${t.name} publish
 
 deploy-dry-${t.name}:
-\taql vault exec --dry-run ${args} -- $(MAKE) -C ${t.name} publish
+\tboru vault exec --dry-run ${args} -- $(MAKE) -C ${t.name} publish
 `
   }).join('')
 
@@ -183,7 +183,7 @@ deploy-dry-${t.name}:
 #
 # Every port gets a git release tag <target>/vX.Y.Z. Ports with an ACTIVE
 # registry also publish a package there. Credentials are injected at exec
-# time by the aql key vault (https://github.com/aql-lang/aql) — never
+# time by the boru key vault (https://github.com/boru-lang/boru) — never
 # stored on disk or passed on the command line.
 #
 # Publication state (from the model):
@@ -194,7 +194,7 @@ ${summary}
 #                             registry upload is irreversible); while a
 #                             registry is pending this publishes the
 #                             port's git tag only
-#   make deploy-dry           rehearse EVERY target: aql --dry-run
+#   make deploy-dry           rehearse EVERY target: boru --dry-run
 #                             injects a filler token that each publish
 #                             recipe detects, so build + test run in full
 #                             but nothing is uploaded and no tag is cut
@@ -207,7 +207,7 @@ ${varLines}
 
 # Lockstep SDK version, read from the canonical ts manifest.
 VERSION := $(shell node -p "require('./ts/package.json').version" 2>/dev/null || echo 0.0.0)
-AQL_DRY_RUN_FILLER := AQL-DRY-RUN-FILLER-NOT-A-REAL-SECRET
+BORU_DRY_RUN_FILLER := BORU-DRY-RUN-FILLER-NOT-A-REAL-SECRET
 
 TARGETS := ${targets.map((t: any) => t.name).join(' ')}
 
@@ -233,7 +233,7 @@ ${deployRules}`
 
 
 
-// The root-level tag creation + push recipe for a target: aql --dry-run
+// The root-level tag creation + push recipe for a target: boru --dry-run
 // filler cooperation, idempotent tag creation, token-authenticated https
 // push (works from an ssh-remote clone without ssh keys).
 function tagPushRecipe(name: string, note: string): string {
@@ -241,9 +241,9 @@ function tagPushRecipe(name: string, note: string): string {
 tag-push-${name}:
 \t@set -e; tag="${name}/v$(VERSION)"; \\
 \ttoken="\$\${GITHUB_TOKEN:-$$GH_TOKEN}"; \\
-\tif [ "$$token" = "$(AQL_DRY_RUN_FILLER)" ]; then \\
-\t  echo "[dry-run] aql filler token detected: would create (if missing) and push tag $$tag; nothing pushed."; exit 0; fi; \\
-\tif [ -z "$$token" ]; then echo "tag-push-${name}: no GITHUB_TOKEN in env — run via make deploy-${name} (aql vault exec)"; exit 1; fi; \\
+\tif [ "$$token" = "$(BORU_DRY_RUN_FILLER)" ]; then \\
+\t  echo "[dry-run] boru filler token detected: would create (if missing) and push tag $$tag; nothing pushed."; exit 0; fi; \\
+\tif [ -z "$$token" ]; then echo "tag-push-${name}: no GITHUB_TOKEN in env — run via make deploy-${name} (boru vault exec)"; exit 1; fi; \\
 \tif git rev-parse -q --verify "refs/tags/$$tag" >/dev/null; then \\
 \t  echo "tag $$tag already exists — pushing existing tag"; \\
 \telse git tag -a "$$tag" -m "Release $$tag"; fi; \\

package/src/cmp/ReadmeTop.ts

@@ -549,28 +549,30 @@ Pass custom features via the \`extend\` option at construction time.
 `)
     }
 
-    // 13. Upstream API — contact/servers from the OpenAPI info block
+    // 13. Upstream API — always disclose the OpenAPI origin and where the
+    // spec(s) live; contact/servers links come from the OpenAPI info block.
     const upstreamUrl = (info.contact && info.contact.url)
       || (info.servers && info.servers[0] && info.servers[0].url)
       || homepage
-    if (upstreamUrl || docsUrl) {
-      Content(`## Upstream API
+    Content(`## Upstream API
 
 This SDK is generated from the upstream OpenAPI specification. It is an
 unofficial client and is not affiliated with the API provider.
 
+The OpenAPI spec(s) this SDK was generated from are kept in the
+[\`.sdk/def/\`](.sdk/def/) folder.
+
 `)
-      if (upstreamUrl) {
-        Content(`- Upstream API: [${upstreamUrl}](${upstreamUrl})
-`)
-      }
-      if (docsUrl && docsUrl !== upstreamUrl) {
-        Content(`- Documentation: [${docsUrl}](${docsUrl})
+    if (upstreamUrl) {
+      Content(`- Upstream API: [${upstreamUrl}](${upstreamUrl})
 `)
-      }
-      Content(`
+    }
+    if (docsUrl && docsUrl !== upstreamUrl) {
+      Content(`- Documentation: [${docsUrl}](${docsUrl})
 `)
     }
+    Content(`
+`)
 
     // 13b. Security
     Content(`## Security

package/src/helpers/naming.ts

@@ -126,6 +126,75 @@ function rbSafeTypeName(Name: string): string {
 }
 
 
+// Swift SDK-OWNED TYPE NAMES — a third hazard, distinct from both sets above.
+//
+// The keyword sets guard local bindings; the Ruby set guards clobbering the
+// LANGUAGE's core. This set guards clobbering OUR OWN runtime, because Swift
+// has no namespacing WITHIN a module: every type the swift templates declare
+// and every generated entity type land in the same module. Two declarations
+// of one name is a hard error, not a silent override:
+//
+//   // core/Response.swift  (template)
+//   public final class Response { ... }      // transport wrapper
+//   // entity/<Prefix>Types.swift  (generated from a spec schema named Response)
+//   public struct Response { ... }
+//   -> error: invalid redeclaration of 'Response'
+//   -> error: 'Response' is ambiguous for type lookup   (every core file)
+//
+// Found 2026-08-07: the Hook0 spec has a `Response` schema, which took the
+// whole swift target down. `Response` is merely the first collision to be
+// hit — every name below is equally exposed.
+//
+// Sourced by scanning BOTH `tm/swift/Sources/*/` (templates) and
+// `src/cmp/swift/*.ts` (components) for top-level type declarations —
+// regardless of access level. `internal` is Swift's default and is still
+// module-wide, and `open class BaseFeature` is not `public` either, so an
+// access-level filter under-collects and silently reopens the bug.
+//
+// Nested types (a `typealias Element` inside a struct) and the separate Tests
+// module (`ReadmeExamplesTest`) do NOT share this namespace and are excluded.
+//
+// `swift-sdk-types.test.ts` re-derives this list from the templates and fails
+// on drift, so adding a public type to a swift template cannot silently
+// reopen the bug.
+const SWIFT_SDK_TYPES = new Set<string>([
+  // core runtime
+  'Context', 'Control', 'Entity', 'Operation', 'Point', 'Response', 'Result',
+  'SdkConfig', 'Spec', 'Utility',
+  // struct library
+  'Injection', 'Injector', 'JSON', 'JSONParseError', 'Modify',
+  'OrderedDictionary', 'Sentinel', 'Value', 'VList', 'VMap', 'WalkApply',
+  // function/callback aliases
+  'FetcherFunc', 'Formatter', 'NativeCall0', 'NativeRef', 'SystemFetch',
+  // features
+  'AuditFeature', 'BaseFeature', 'CacheFeature', 'ClienttrackFeature',
+  'DebugFeature', 'IdempotencyFeature', 'LogFeature', 'MetricsBucket',
+  'MetricsFeature', 'NetsimFeature', 'PagingFeature', 'ProxyFeature',
+  'RatelimitFeature', 'RbacFeature', 'RetryFeature', 'StreamingFeature',
+  'TelemetryFeature', 'TestFeature', 'TimeoutFeature',
+])
+
+
+// Does `Name` collide with a type the swift SDK runtime already declares?
+function isSwiftSdkType(Name: string): boolean {
+  return SWIFT_SDK_TYPES.has(Name)
+}
+
+
+// A module-safe Swift type name for a generated type: unchanged, unless the
+// swift runtime already declares it, in which case `Type` is appended
+// (`Response` -> `ResponseType`). Mirrors rbSafeTypeName deliberately — same
+// suffix, same "only rename on an actual collision" rule, so SDKs that do not
+// collide are byte-identical to before.
+//
+// Applied ONLY to the bare entity data type. Per-op type names already carry
+// their own suffix (`ResponseCreateData`, `ResponseLoadMatch`) and the entity
+// CLASS is separately suffixed (`ResponseEntity`), so neither ever collided.
+function swiftSafeTypeName(Name: string): string {
+  return isSwiftSdkType(Name) ? Name + 'Type' : Name
+}
+
+
 // Is `name` a reserved word (an illegal identifier) in the target language?
 function isReservedName(name: string, lang: string): boolean {
   const set = RESERVED[lang]
@@ -189,6 +258,8 @@ export {
   exampleVarName,
   isRbCoreConstant,
   rbSafeTypeName,
+  isSwiftSdkType,
+  swiftSafeTypeName,
   jsProp,
   jsOptProp,
   jsKey,