@voxgig/sdkgen 1.3.17 → 1.3.19

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/Entity.ts

@@ -21,8 +21,12 @@ const Entity = cmp(function Entity(props: any) {
   const Entity_sdk = requirePath(ctx$, `./cmp/${target.name}/Entity_${target.name}`)
   Entity_sdk['Entity']({ target, entity, entitySDK })
 
+  // Log identifiers, not the model subtrees. `target` and `entity` are large
+  // aontu nodes and this fires once per entity per target (thousands of times
+  // for a big API x 22 targets), so passing them serialised the whole model
+  // fragment each time at default log level.
   log.info({
-    point: 'generate-entity', target, entity,
+    point: 'generate-entity', target: target.name, entity: entity.name,
     note: 'target:' + target.name + ', ' + 'entity: ' + entity.name
   })
 })

package/src/cmp/Feature.ts

@@ -19,7 +19,8 @@ const Feature = cmp(function Feature(props: any) {
   }
 
   log.info({
-    point: 'generate-feature', target, feature,
+    // Identifiers only — see the note in Entity.ts.
+    point: 'generate-feature', target: target.name, feature: feature.name,
     note: 'target:' + target.name + ', ' + 'feature: ' + feature.name
   })
 

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/canonType.ts

@@ -14,9 +14,14 @@
 // the SINGLE mapping per language: components must not keep local copies.
 //
 // Kept as a small mirror here (rather than importing VALID_CANON at runtime)
-// because apidef is a peer dependency and the table is the INVERSE direction;
-// `ts/test/canontype.test.ts` asserts this table covers apidef's exported
-// sentinel vocabulary whenever apidef is installed, so drift fails the suite.
+// because apidef is a peer dependency and the table is the INVERSE direction.
+//
+// `ts/test/canonsync.test.ts` guards it two ways: the vocabulary and every
+// language column are pinned LOCALLY (that check always runs), and the table
+// is cross-checked against apidef's exported VALID_CANON/CANON_ONE when the
+// installed apidef exports them. Note that the currently published apidef
+// (6.3.1) does NOT export them, so the cross-check skips — do not rely on it
+// alone; add a new sentinel to the local list in the same change.
 //
 // KNOWN GAPS (papered over sanely, documented for the port):
 //  - Unknown / missing sentinel  -> the language's "any" (never throws).

package/src/helpers/collectDeps.ts

@@ -27,21 +27,53 @@ function collectDeps(
   model: SdkModel,
   targetName: string,
   targetDeps: Record<string, ModelDep> | undefined,
+  log?: any,
 ): DepEntry[] {
   const out: DepEntry[] = []
   const feature = getModelPath(model, `main.${KIT}.feature`)
 
+  // Deduplicate by package name. Two features can require the same package
+  // (or a feature and the target itself can), and every Package_<lang>.ts
+  // renders one manifest line per entry — a duplicate key is a hard parse
+  // error in go.mod and Cargo.toml, and silently last-wins in package.json.
+  // FIRST occurrence wins, so the deterministic (sorted-key) feature order
+  // decides; a conflicting version is reported rather than silently dropped.
+  const seen: Record<string, DepEntry> = {}
+
+  const add = (dep: any, source: 'feature' | 'target', owner: string) => {
+    const name = dep.key$
+    if (null == name) return
+
+    const prev = seen[name]
+    if (null != prev) {
+      if (log?.warn && prev.version !== dep.version) {
+        log.warn({
+          point: 'dep-version-conflict', target: targetName, dep: name,
+          kept: prev.version, dropped: dep.version, from: owner,
+          note: `${targetName}: dependency ${name} declared twice with ` +
+            `different versions — keeping ${prev.version} (${prev.source}), ` +
+            `ignoring ${dep.version} (${source} ${owner})`,
+        })
+      }
+      return
+    }
+
+    const entry: DepEntry = {
+      name,
+      version: dep.version,
+      source,
+      raw: dep,
+    }
+    seen[name] = entry
+    out.push(entry)
+  }
+
   each(feature, (f: any) => {
     const langDeps = f?.deps?.[targetName]
     if (!langDeps) return
     each(langDeps, (dep: any) => {
       if (dep?.active) {
-        out.push({
-          name: dep.key$,
-          version: dep.version,
-          source: 'feature',
-          raw: dep,
-        })
+        add(dep, 'feature', f.name)
       }
     })
   })
@@ -49,12 +81,7 @@ function collectDeps(
   if (targetDeps) {
     each(targetDeps, (dep: any) => {
       if (dep?.active !== false) {
-        out.push({
-          name: dep.key$,
-          version: dep.version,
-          source: 'target',
-          raw: dep,
-        })
+        add(dep, 'target', targetName)
       }
     })
   }

package/src/helpers/naming.ts

@@ -69,6 +69,132 @@ const RESERVED: Record<string, Set<string>> = {
 }
 
 
+// Ruby CORE CONSTANTS — a different hazard from the keyword sets above.
+//
+// The keyword sets guard local-variable BINDINGS. This set guards generated
+// top-level CONSTANTS. Ruby constants share one namespace with the core
+// classes, and reassigning one is not an error — it silently replaces it:
+//
+//   File = Struct.new(:name)     # ::File is now a Struct
+//   File.join('a', 'b')          # NoMethodError — every later caller breaks
+//
+// The typed model emits `<Name> = Struct.new(...)` per entity, so an API with
+// a `/files` collection (entity `File`) used to clobber Ruby's File class and
+// take the whole SDK down with it — the generated test runner calls
+// `File.join` to locate `.env.local`, so `rb` failed at require time.
+//
+// Only names Ruby itself defines at top level are listed: reassigning any of
+// them breaks working code somewhere. Names that merely LOOK builtin but are
+// not core constants (e.g. `Response`, `Record`) are safe and stay untouched,
+// which keeps the rename off every SDK that does not actually collide.
+const RB_CORE_CONSTANTS = new Set<string>([
+  // classes an entity name plausibly lands on
+  'Array', 'Binding', 'Class', 'Comparable', 'Complex', 'Data', 'Dir',
+  'Encoding', 'Enumerator', 'Exception', 'Fiber', 'File', 'Float', 'Hash',
+  'IO', 'Integer', 'Method', 'Module', 'Mutex', 'Numeric', 'Object', 'Proc',
+  'Queue', 'Random', 'Range', 'Rational', 'Regexp', 'Set', 'Signal', 'String',
+  'Struct', 'Symbol', 'Thread', 'Time', 'UnboundMethod',
+  // modules / singletons
+  'Enumerable', 'GC', 'Kernel', 'Marshal', 'Math', 'ObjectSpace', 'Process',
+  'Warning',
+  // the rest of the exception hierarchy an API might name an entity after
+  'ArgumentError', 'IndexError', 'IOError', 'KeyError', 'NameError',
+  'NotImplementedError', 'RangeError', 'RuntimeError', 'StandardError',
+  'StopIteration', 'SystemExit', 'TypeError', 'ZeroDivisionError',
+  // literal singletons
+  'FalseClass', 'NilClass', 'TrueClass',
+])
+
+
+// Is `Name` a constant Ruby already defines at top level?
+function isRbCoreConstant(Name: string): boolean {
+  return RB_CORE_CONSTANTS.has(Name)
+}
+
+
+// A top-level-safe Ruby constant name for a generated type: the name
+// unchanged, unless Ruby core already owns it, in which case `Type` is
+// appended (`File` -> `FileType`). Applied ONLY to the bare entity data type
+// — the per-op type names always carry a suffix (`FileCreateData`,
+// `FileLoadMatch`), which no core constant matches.
+//
+// The entity ACCESSOR keeps its original name (`client.File(...)`): methods
+// and constants live in separate namespaces in Ruby, so the accessor never
+// collided and the public surface is unchanged.
+function rbSafeTypeName(Name: string): string {
+  return isRbCoreConstant(Name) ? Name + 'Type' : Name
+}
+
+
+// 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]
@@ -130,6 +256,10 @@ export {
   isReservedName,
   safeVarName,
   exampleVarName,
+  isRbCoreConstant,
+  rbSafeTypeName,
+  isSwiftSdkType,
+  swiftSafeTypeName,
   jsProp,
   jsOptProp,
   jsKey,

package/src/helpers/opShape.ts

@@ -26,7 +26,60 @@
 // flag) and render them in the target language's struct/interface/TypedDict
 // syntax; the policy itself is language-neutral and tested in isolation.
 
-import { each } from 'jostraca'
+import { each, names } from 'jostraca'
+import { KIT, getModelPath } from '@voxgig/apidef'
+
+
+// THE entity collection for a model — resolved once, with a stable identity.
+//
+// Two problems this solves, both caused by every component calling
+// `getModelPath(model, 'main.<KIT>.entity')` for itself:
+//
+//   * CORRECTNESS. getModelPath drops `active: false` entries by default, but
+//     the consumer scaffold (create-sdkgen Root.ts) generates entity code for
+//     EVERY entity and every EntityTypes_<lang> emits data types with
+//     `only_active: false`. Class-name assignment done against the filtered
+//     view cannot see the inactive entities whose data types it must avoid.
+//     This resolver always returns the unfiltered collection.
+//
+//   * PERFORMANCE. getModelPath REBUILDS the container object on every call
+//     when filtering, so the WeakMap memos below never hit across callers —
+//     the O(n·ops) class-name assignment re-ran per entity per target. At 500
+//     entities x 22 targets that was ~15s of pure recomputation; caching the
+//     resolved collection on the model makes it ~3ms.
+const _entityCollCache = new WeakMap<object, any>()
+
+function entityCollection(model: any): any {
+  if (null == model || 'object' !== typeof model) {
+    return {}
+  }
+  const cached = _entityCollCache.get(model)
+  if (null != cached) {
+    return cached
+  }
+  const coll = getModelPath(model, `main.${KIT}.entity`,
+    { only_active: false, required: false }) || {}
+  deriveEntityNames(coll)
+  _entityCollCache.set(model, coll)
+  return coll
+}
+
+
+// Derive the PascalCase `Name` on every entity in a collection.
+//
+// `Name` is injected LAZILY by jostraca's names(), historically by whichever
+// component happened to run first (create-sdkgen Root.ts, or an EntityTypes
+// emitter). Anything reading `e.Name` before that ran saw `undefined` — and
+// because the helpers below MEMOISE, one early read poisoned the result for
+// the whole run (`undefinedEntity` class names; a permanently empty collision
+// list). The helpers therefore derive `Name` themselves, up front, so they
+// never depend on component ordering. Idempotent: names() is only called for
+// an entity that lacks `Name`.
+function deriveEntityNames(entityColl: any): any[] {
+  const ents = each(entityColl).filter((e: any) => e && null != e.name)
+  ents.forEach((e: any) => { if (null == e.Name) names(e, e.name) })
+  return ents
+}
 
 
 // The five ops, and whether their request payload is a `Match` (query/id) or
@@ -156,8 +209,21 @@ function opRequestShape(ent: any, opname: string):
     return { items: [], fromParams: false }
   }
 
+  // Ops that carry a BODY are the exception to "op-declared params win":
+  // their request payload is BOTH. `PUT /v1/todo/item/{id}` declares the path
+  // param `id`, which the SDK resolves out of reqdata (see the param
+  // utility's reqmatch -> match -> reqdata search), while the fields the
+  // caller wants to change come from the entity. Params alone produced
+  // `<Name>UpdateData = { id }` — no way to send anything to update.
+  //
+  // The param stays in the payload because the path needs it; keeping it out
+  // of the request BODY is the model's job, via the op's `transform.req`
+  // (@voxgig/apidef restricts the body to a closed request schema's declared
+  // properties).
+  const isbodyop = 'create' === opname || 'update' === opname || 'patch' === opname
+
   const params = opParams(op)
-  if (0 < params.length) {
+  if (0 < params.length && !isbodyop) {
     const items = params.map((p: any) => ({
       name: p.name,
       type: p.type,
@@ -166,15 +232,25 @@ function opRequestShape(ent: any, opname: string):
     return { items, fromParams: true }
   }
 
+  const paramItems = isbodyop ? params.map((p: any) => ({
+    name: p.name,
+    type: p.type,
+    optional: false === p.reqd,
+  })) : []
+  const paramNames = new Set(paramItems.map((p: any) => p.name))
+
   const fields = (ent.fields ? each(ent.fields) : [])
     .filter((f: any) => f.active !== false)
     .filter((f: any) => fieldInOp(f, opname))
 
-  const items = fields.map((f: any) => ({
-    name: f.name,
-    type: f.type,
-    optional: fieldOptional(f, opname),
-  }))
+  const items = paramItems.concat(
+    fields
+      .filter((f: any) => !paramNames.has(f.name))
+      .map((f: any) => ({
+        name: f.name,
+        type: f.type,
+        optional: fieldOptional(f, opname),
+      })))
 
   return { items, fromParams: false }
 }
@@ -250,6 +326,16 @@ function entityPrimaryOp(ent: any): string | null {
 // … The DATA type keeps its canonical `<Name>` — only the suffixed class
 // yields. Deterministic (sorted-key iteration) and stable across runs.
 //
+// Covers EVERY entity, active or not: the consumer scaffold (create-sdkgen
+// Root.ts) iterates the RAW entity collection, and every EntityTypes_<lang>
+// emits with `only_active: false`, so an inactive entity still contributes a
+// generated data type AND still needs a class name. Filtering to actives here
+// left inactive entities on the un-deduped `<Name>Entity` fallback and left
+// their data types out of `taken` — so an ACTIVE entity's class could collide
+// with an INACTIVE entity's emitted data type (e.g. active `project` ->
+// class `ProjectEntity` vs inactive `project-entity` -> type `ProjectEntity`,
+// a redeclaration in Go).
+//
 // Memoised per entity-collection object so the O(n) assignment runs once.
 const _classNameCache = new WeakMap<object, Record<string, string>>()
 
@@ -259,7 +345,7 @@ function entityClassNames(entityColl: any): Record<string, string> {
     return cached
   }
 
-  const ents = each(entityColl).filter((e: any) => e && e.active !== false)
+  const ents = deriveEntityNames(entityColl)
 
   // 1. Every top-level DATA-type name the target emits.
   const taken: Record<string, boolean> = {}
@@ -314,8 +400,8 @@ function entityClassName(ent: any, entityColl: any): string {
 // merging in ts. The names cannot be auto-renamed here — the generated
 // entity classes and op fragments reference them by token — so the guard
 // surfaces the collision loudly instead. Returns the sorted duplicate names
-// (empty when clean). Callers must have derived `Name` on each entity
-// (every EntityTypes emitter does).
+// (empty when clean). `Name` is derived here (deriveEntityNames), so the
+// guard cannot be silently disabled by running before an emitter.
 //
 // Memoised per entity-collection object, like entityClassNames.
 const _typeCollisionCache = new WeakMap<object, string[]>()
@@ -329,8 +415,7 @@ function entityTypeCollisions(entityColl: any): string[] {
   const counts: Record<string, number> = {}
   const bump = (n: string) => { counts[n] = (counts[n] || 0) + 1 }
 
-  each(entityColl)
-    .filter((e: any) => e && null != e.name && null != e.Name)
+  deriveEntityNames(entityColl)
     .forEach((e: any) => {
       bump(e.Name)
       for (const op of ['load', 'list', 'create', 'update', 'remove']) {
@@ -444,6 +529,8 @@ function entityDataIdField(ent: any): string | null {
 
 export {
   OP_SUFFIX,
+  deriveEntityNames,
+  entityCollection,
   opTypeName,
   opParams,
   opRequestShape,