@voxgig/sdkgen 4.9.0 → 4.11.0

package/project/.sdk/tm/zig/test/vendor/omni/omni.zig

@@ -1,5 +1,5 @@
-// VENDORED: @voxgig/omni sdk-20260907-0029-0 (zig/src/omni.zig)
-// Source: https://github.com/voxgig/omni @ 274708cc2d12b21707d975543953f845f8444be0  [tag: sdk-20260907-0029-0]
+// VENDORED: @voxgig/omni sdk-20260908-1556-0 (zig/src/omni.zig)
+// Source: https://github.com/voxgig/omni @ 274708cc2d12b21707d975543953f845f8444be0  [tag: sdk-20260908-1556-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 //! Omni: the shared multi-language test runner (Zig port).
 //!

package/project/.sdk/tm/zig/test/vendor/omni/regex.zig

@@ -1,5 +1,5 @@
-// VENDORED: @voxgig/omni sdk-20260907-0029-0 (zig/src/regex.zig)
-// Source: https://github.com/voxgig/omni @ 274708cc2d12b21707d975543953f845f8444be0  [tag: sdk-20260907-0029-0]
+// VENDORED: @voxgig/omni sdk-20260908-1556-0 (zig/src/regex.zig)
+// Source: https://github.com/voxgig/omni @ 274708cc2d12b21707d975543953f845f8444be0  [tag: sdk-20260908-1556-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 //! A small backtracking regex engine.
 //!

package/project/.sdk/tm/zig/utility/voxgigstruct/regex.zig

@@ -1,5 +1,5 @@
-// VENDORED: @voxgig/struct sdk-20260907-0029-0 (zig/src/regex.zig)
-// Source: https://github.com/voxgig/struct @ adda9521c828147573df5a8878408a3f2193ddf4  [tag: sdk-20260907-0029-0]
+// VENDORED: @voxgig/struct sdk-20260908-1556-0 (zig/src/regex.zig)
+// Source: https://github.com/voxgig/struct @ adda9521c828147573df5a8878408a3f2193ddf4  [tag: sdk-20260908-1556-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 // Copyright (c) 2025-2026 Voxgig Ltd. MIT LICENSE.
 //

package/project/.sdk/tm/zig/utility/voxgigstruct/struct.zig

@@ -1,5 +1,5 @@
-// VENDORED: @voxgig/struct sdk-20260907-0029-0 (zig/src/struct.zig)
-// Source: https://github.com/voxgig/struct @ adda9521c828147573df5a8878408a3f2193ddf4  [tag: sdk-20260907-0029-0]
+// VENDORED: @voxgig/struct sdk-20260908-1556-0 (zig/src/struct.zig)
+// Source: https://github.com/voxgig/struct @ adda9521c828147573df5a8878408a3f2193ddf4  [tag: sdk-20260908-1556-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 // Copyright (c) 2025-2026 Voxgig Ltd. MIT LICENSE.
 

package/project/sdkgen-package.json

@@ -3,14 +3,13 @@
     "package": 1
   },
   "name": "@voxgig/sdkgen",
-  "version": "4.9.0",
+  "version": "4.11.0",
   "provides": {
     "target": [
       "c",
       "clojure",
       "cpp",
       "csharp",
-      "dart",
       "elixir",
       "go",
       "go-cli",
@@ -18,7 +17,6 @@
       "java",
       "js",
       "kotlin",
-      "lean",
       "lua",
       "ocaml",
       "perl",
@@ -28,7 +26,6 @@
       "rb",
       "rust",
       "scala",
-      "seneca-provider",
       "swift",
       "ts",
       "zig"

package/src/helpers/manifest.ts

@@ -71,11 +71,29 @@ type Manifest = {
   targetsSupported?: Record<string, string[]>
 
   // Optional: the author's declared parity tier per target, in
-  // ts/test/parity.test.ts's vocabulary.
+  // ts/test/parity.test.ts's vocabulary plus CONSUMER — see PARITY below.
   parity?: Record<string, string>
 }
 
 
+// THE CLOSED PARITY VOCABULARY.
+//
+// The first three are `ts/test/parity.test.ts`'s tiers, which grade a
+// language target against the shared `.aontu` corpus. `CONSUMER` is the
+// fourth and grades nothing: a consumer target wraps another target's SDK and
+// has no primary-utility surface to measure, so `parity.test.ts` keeps the
+// bundled ones in NON_SDK_TARGETS rather than in a tier. A package holding
+// one needs a way to say the same thing, and saying nothing is not it — an
+// absent field cannot be told apart from an author who did not know the field
+// existed, which is the silently-absent shape every other guard in this repo
+// exists to prevent.
+//
+// Closed, and checked, because a declaration nothing checks is the failure
+// `engines.sdkgen` documents about itself two fields up: a typo would
+// otherwise be indistinguishable from a considered choice.
+const PARITY = ['FULL', 'MIRRORED', 'UNCOVERED', 'CONSUMER']
+
+
 // What `readManifest` found. THREE outcomes, deliberately distinct: a
 // manifest, no manifest, or a manifest that could not be read. Collapsing the
 // last two into "no manifest" is what would let a typo in a package's own
@@ -325,6 +343,67 @@ function validateManifest(
     }
   }
 
+  // The parity declaration, checked in both directions like everything else
+  // here: the VALUE against the closed vocabulary, and the KEY against what
+  // the package actually provides. A tier declared for a target the package
+  // does not ship is a leftover from a rename — harmless in itself, and
+  // exactly the kind of leftover that later reads as coverage.
+  const targets = new Set(provides.target ?? [])
+  const graded = new Set(Object.keys(manifest.parity ?? {}))
+
+  // A PROVIDED TARGET THE MANIFEST GRADES NOTHING FOR, when it grades OTHERS.
+  //
+  // Checking only the values leaves the weaker half undone: a typo'd tier is
+  // caught while an absent one passes, and absent is the failure mode the
+  // closed sets in this repo exist for — indistinguishable from an author who
+  // did not know the field was there.
+  //
+  // SCOPED TO A PARTIAL DECLARATION, and the scope is a real constraint
+  // rather than timidity. An ENTIRELY absent `parity` is the BUNDLED
+  // manifest's deliberate state: design §18.4a refused to duplicate
+  // parity.test.ts's tier map into ts/project/sdkgen-package.json, because
+  // the intended direction is the reverse — the manifest becomes the source
+  // and the suite reads it. Warning on a wholly absent field would fire on
+  // the shipped scaffold's 25 targets and demand that duplication now, which
+  // is the decision §18.4a made, not one to reverse from inside a validator.
+  //
+  // What IS unambiguous is inconsistency: a manifest that grades some of its
+  // targets and not others has no second reading. Nobody decides to grade two
+  // of three.
+  //
+  // WARNING, not error, and the level is the argument. The package works — a
+  // missing coverage declaration installs and generates correctly — so
+  // refusing it would be a worse outcome than saying so, the same call
+  // `manifest-item-unclaimed` makes for a tree nothing claims.
+  for (const name of (0 === graded.size ? [] : [...targets].sort())) {
+    if (!graded.has(name as string)) {
+      found.push({
+        level: 'warn', point: 'manifest-parity-missing', file, name: name as string,
+        note: file + ': target `' + name + '` has no `parity` entry — its ' +
+          'coverage is undeclared, which reads the same as having none. One ' +
+          'of: ' + PARITY.join(', ')
+      })
+    }
+  }
+
+  for (const [name, tier] of Object.entries(manifest.parity ?? {})) {
+    if (!PARITY.includes(tier)) {
+      found.push({
+        level: 'error', point: 'manifest-parity-unknown', file, name,
+        note: file + ': `parity.' + name + '` is "' + tier +
+          '" — must be one of: ' + PARITY.join(', ')
+      })
+    }
+
+    if (!targets.has(name)) {
+      found.push({
+        level: 'warn', point: 'manifest-parity-unprovided', file, name,
+        note: file + ': `parity.' + name + '` names a target this package ' +
+          'does not provide — nothing declares its coverage'
+      })
+    }
+  }
+
   // The other direction. Only for kinds the manifest MENTIONS plus the ones
   // this generator knows — a directory named after a kind nobody registered
   // is already reported above if claimed, and is not this check's business if
@@ -465,6 +544,7 @@ export type {
 export {
   MANIFEST,
   SCHEMA,
+  PARITY,
   ITEM_NAME_RE,
   manifestPath,
   probePackage,

package/src/helpers/modelNames.ts

@@ -0,0 +1,284 @@
+/* Copyright (c) 2024-2026 Voxgig Ltd, MIT License */
+
+// Normalise entity names in the model so every generated identifier is legal.
+//
+// An entity name is a MODEL KEY, and every target builds identifiers from it:
+// the PascalCase `Name` (class names, the SDK accessor, every generated type
+// name), the snake stem (python module names, test function names), the
+// object-literal key in the emitted config map. No target language permits an
+// identifier that starts with a digit, and ordinary resources produce one:
+// `/3ds-sessions` -> entity `3ds_session` -> `class 3dsSessionEntity`,
+// `import { 3dsSession }`, `3dsSession()`. That is not a degraded SDK, it is
+// no SDK — nothing compiles (issue #124).
+//
+// THE RENAME IS ON THE MODEL, NOT ON A DERIVED FORM, and that is the whole
+// design. Guarding `Name` where it is derived does not survive: a consumer's
+// scaffolded `Root.ts` — which lives in the consumer's repo, not here — runs
+// its own `names(entity, entity.name)` per entity per target, immediately
+// before emitting, and re-derives `Name` from the unguarded name. Only a
+// guarded `entity.name` makes that re-derivation come out right, and it fixes
+// the snake-stem and config-key positions at the same time.
+//
+// Applied before Root runs, so nothing has read a name yet.
+//
+// IT IS A NO-OP ON EVERY MODEL THAT EXISTS TODAY. apidef guards entity names
+// at the source, so a name reaching here with a leading digit means a
+// hand-authored `.sdk/model` or a pre-guard apidef. The rename is the same
+// rule, producing the same name, as apidef's own `prefixLeadingDigit` — so
+// the two layers agree rather than compete, and a model that went through
+// apidef is untouched.
+//
+// The WIRE is untouched. A request path comes from the point's `orig`, never
+// from the entity name, so renaming the entity cannot change what is called.
+
+import { each, names } from 'jostraca'
+import { KIT } from '@voxgig/apidef'
+
+import { prefixLeadingDigit } from './naming'
+
+
+// `from`/`to` are the entity NAME. `key` is where the entity sits in the
+// collection after the rename — the new name when the map was keyed by it (the
+// normal shape), the untouched original key when it was not.
+type Rename = { from: string, to: string, key: string }
+
+// The internal form, which also remembers where the entity sat BEFORE the
+// rename — the one thing the public record cannot carry and the apply pass
+// needs, since the key only moves when it was the name.
+type Plan = { from: string, to: string, origkey: string }
+
+
+// Rename every entity whose name would produce an illegal identifier, and
+// rewrite the model's own references to it. Returns the renames applied, so
+// the caller can report them; empty when the model is already clean.
+function guardModelNames(model: any, log?: any): Rename[] {
+  const entity = model?.main?.[KIT]?.entity
+  // An ARRAY is not a name-keyed collection: its keys are indices, and
+  // "renaming" one would rewrite the model into nonsense. Models are maps, but
+  // the check is cheap and the failure would be silent.
+  if (null == entity || 'object' !== typeof entity || Array.isArray(entity)) {
+    return []
+  }
+
+  const flow = flowMap(model)
+
+  // Sorted keys: the rename set, and any collision report, is byte-stable.
+  const keys = Object.keys(entity).sort()
+  const taken = new Set(keys)
+  keys.forEach((k) => {
+    const n = entity[k]?.name
+    if ('string' === typeof n) taken.add(n)
+  })
+
+  const plans: Plan[] = []
+  const blocked: string[] = []
+
+  for (const key of keys) {
+    const ent = entity[key]
+    if (null == ent || 'object' !== typeof ent) {
+      continue
+    }
+
+    // `name` is authoritative, not the key: it is the value every derived
+    // form comes from. The key moves with it only when the two agree, which
+    // is the normal shape.
+    const from = 'string' === typeof ent.name ? ent.name : key
+
+    const to = prefixLeadingDigit(from)
+    if (to === from) {
+      continue
+    }
+
+    // The guarded name is already another entity's. Renaming onto it would
+    // merge two unrelated entities — silently, since the model is a plain
+    // map — so leave this one alone and say so. The generated SDK still will
+    // not compile, but the reason is now in the log rather than in a syntax
+    // error 20 files later.
+    if (taken.has(to)) {
+      blocked.push(from)
+      continue
+    }
+
+    // The FLOW key would collide. `Basic<Name>Flow` is rebuilt from the
+    // guarded Name by every Test component, so if the guarded key is already
+    // occupied by a different flow, renaming would point all of them at that
+    // one and strand this entity's own flow under its old key — generated
+    // tests that exercise the wrong entity, silently. Refuse, exactly as for
+    // an entity-name collision: an SDK that does not compile is a better
+    // outcome than one whose tests lie.
+    if (null != flow && flowCollides(flow, from, to)) {
+      blocked.push(from)
+      continue
+    }
+
+    taken.add(to)
+    plans.push({ from, to, origkey: key })
+  }
+
+  if (0 < blocked.length && log?.warn) {
+    log.warn({
+      point: 'entity-name-guard-blocked', names: blocked.sort(),
+      note: `entity name(s) ${blocked.sort().join(', ')} start with a digit ` +
+        `and cannot be guarded: the guarded name, or the basic flow key it ` +
+        `implies, is already taken. Rename the entity (or that flow) in the ` +
+        `model — the generated SDK will not compile in any target while an ` +
+        `entity name is not an identifier`,
+    })
+  }
+
+  if (0 === plans.length) {
+    return []
+  }
+
+  const renames: Rename[] = []
+
+  for (const { from, to, origkey } of plans) {
+    const ent = entity[origkey]
+    ent.name = to
+    // jostraca's names() is memo-free but idempotent-by-absence: every derived
+    // form has to go, or a stale `Name` from an earlier pass survives the
+    // rename and the SDK is inconsistent with itself.
+    delete ent.Name
+    delete ent.NAME
+    delete ent.name_
+    delete ent['name-']
+    delete ent.name__orig
+
+    // The key moves only when it WAS the name. A key the model chose for some
+    // other reason is left where it is; every derived identifier comes from
+    // `name`, which is now guarded either way.
+    if (origkey === from) {
+      entity[to] = ent
+      delete entity[origkey]
+    }
+
+    renames.push({ from, to, key: origkey === from ? to : origkey })
+  }
+
+  renameReferences(model, renames)
+
+  // WARN, not info, because it names work only the project owner can do.
+  //
+  // The generated flow test reads its fixture from
+  // `.sdk/test/entity/<name>/<Name>TestData.json` and seeds the config under
+  // `<name>` — both derived from the guarded name. sdkgen READS that path and
+  // never writes it: the fixture is the project's own content under `.sdk/`,
+  // not generated output, so the rename cannot carry it. A project that
+  // already has one for a digit-named entity goes from an SDK that does not
+  // compile at all to one that compiles with a flow test failing on a missing
+  // fixture — better, but only if it says which file to move.
+  if (log?.warn) {
+    log.warn({
+      point: 'entity-name-guard', renames,
+      note: 'entity name(s) renamed so generated identifiers are legal: ' +
+        renames.map((r) => `${r.from} -> ${r.to}`).join(', ') +
+        '. If this project has a test fixture for one of them, move it: ' +
+        renames.map((r) =>
+          `.sdk/test/entity/${r.from}/${pascalName(r.from)}TestData.json -> ` +
+          `.sdk/test/entity/${r.to}/${pascalName(r.to)}TestData.json ` +
+          `(renaming its \`existing.${r.from}\` key to \`${r.to}\`)`)
+          .join('; '),
+    })
+  }
+
+  return renames
+}
+
+
+// The flow collection, when the model has one shaped like a map.
+function flowMap(model: any): Record<string, any> | null {
+  const flow = model?.main?.[KIT]?.flow
+  return (null != flow && 'object' === typeof flow && !Array.isArray(flow))
+    ? flow
+    : null
+}
+
+
+// Would renaming `from` to `to` put this entity's basic flow on a key another
+// flow already holds? The entity's own flow is the one sitting at the key its
+// CURRENT name implies; anything else at the guarded key belongs to something
+// else.
+function flowCollides(
+  flow: Record<string, any>, from: string, to: string,
+): boolean {
+  const held = flow[flowKey(to)]
+  return null != held && held !== flow[flowKey(from)]
+}
+
+
+// The model refers to an entity by name in two more places, and both have to
+// move with it or the reference dangles.
+function renameReferences(model: any, renames: Rename[]): void {
+  const map = new Map(renames.map((r) => [r.from, r.to]))
+
+  // 1. FLOWS. A flow names its entity, and the Test components look the flow
+  //    up by a key REBUILT from the entity's PascalCase Name
+  //    (`Basic${nom(entity, 'Name')}Flow`), so the key has to move too or the
+  //    entity silently generates no tests. Only a key that matches the
+  //    reconstructed old one is renamed; anything else the author chose is
+  //    left as it is, with just its `entity` field corrected.
+  const flow = flowMap(model)
+  if (null != flow) {
+    for (const key of Object.keys(flow).sort()) {
+      const f = flow[key]
+      if (null == f || 'object' !== typeof f) {
+        continue
+      }
+      const to = map.get(f.entity)
+      if (null == to) {
+        continue
+      }
+
+      const from = f.entity
+      f.entity = to
+
+      // The destination is free: `flowCollides` refused the rename outright
+      // when it was not, so this cannot clobber another flow.
+      const oldkey = flowKey(from)
+      if (key === oldkey) {
+        const newkey = flowKey(to)
+        f.name = newkey
+        flow[newkey] = f
+        delete flow[oldkey]
+      }
+    }
+  }
+
+  // 2. ANCESTORS. A nested entity records its parents by name.
+  const entity = model?.main?.[KIT]?.entity
+  each(entity).forEach((ent: any) => {
+    const ancestors = ent?.relations?.ancestors
+    if (!Array.isArray(ancestors)) {
+      return
+    }
+    ent.relations.ancestors = ancestors.map((a: any) =>
+      Array.isArray(a)
+        ? a.map((n: any) => map.get(n) ?? n)
+        : (map.get(a) ?? a))
+  })
+}
+
+
+// The basic flow's key for an entity name, as the Test components rebuild it
+// (`Basic${nom(entity, 'Name')}Flow`). Derived through jostraca's own names()
+// on a scratch object rather than by re-implementing PascalCase here — a
+// second spelling of that rule is exactly how the key and the lookup drift
+// apart, and the failure is silent (an entity that generates no tests).
+function flowKey(name: string): string {
+  return 'Basic' + pascalName(name) + 'Flow'
+}
+
+
+// The PascalCase `Name` for an entity name, through jostraca's own names() on
+// a scratch object — the same derivation every component gets, so a caller
+// here cannot drift from what is emitted.
+function pascalName(name: string): string {
+  const scratch: any = {}
+  names(scratch, name)
+  return scratch.Name
+}
+
+
+export {
+  guardModelNames,
+}

package/src/helpers/naming.ts

@@ -150,9 +150,14 @@ const RB_SDK_CONSTANTS = new Set<string>([
   'STRUCT_TEST_JSON_FILE',
   // vendored omni runner and its smoke test (vendor-tag rollout)
   'VoxgigOmni', 'OmniSmokeTest',
+  // vendored sekreto and its plugin host — the `secrets` feature's library,
+  // shipped only when that feature is selected, but declared at the top
+  // level when it is
+  'VoxgigSekreto', 'VoxgigPlugin',
   // the generated/templated test classes
   'ExistsTest', 'FeatureCorpusTest', 'FeatureTest', 'NetsimTest',
   'PipelineTest', 'PrimaryUtilityTest', 'ReadmeExamplesTest',
+  'SecretsFeatureTest',
   'TestHookFeature', 'TestInitFeature',
 ])
 
@@ -226,7 +231,8 @@ const SWIFT_SDK_TYPES = new Set<string>([
   'CostTotal', 'DebugFeature', 'IdempotencyFeature', 'LogFeature',
   'MetricsBucket', 'MetricsFeature', 'NetsimFeature', 'PagingFeature',
   'ProxyFeature', 'RatelimitFeature', 'RbacFeature', 'RetryFeature',
-  'StreamingFeature', 'TelemetryFeature', 'TestFeature', 'TimeoutFeature',
+  'SecretsFeature', 'StreamingFeature', 'TelemetryFeature', 'TestFeature',
+  'TimeoutFeature',
 ])
 
 
@@ -497,6 +503,43 @@ function exampleVarName(name: string, lang: string): string {
 }
 
 
+// LEADING DIGITS — the one hazard on this page that is not about a word being
+// taken. Every other guard here asks "is this name already claimed?"; this one
+// asks whether the name is an identifier at all. No target language permits
+// one that starts with a digit, and ordinary resources produce one:
+//
+//   /3ds-sessions  -> entity `3ds_session` -> Name `3dsSession`
+//   /2fa-tokens    -> entity `2fa_token`   -> Name `2faToken`
+//
+// `Name` feeds the class name, the SDK accessor and every generated type
+// name, so the SDK does not compile at all — it is not a degraded SDK, it is
+// no SDK (issue #124).
+//
+// The prefix takes the case of the name it guards — lower for `3ds_session`,
+// upper for `3DSecure` — so the result stays in whatever casing convention
+// the caller works in. Applied to the STEM before PascalCasing, which is why
+// `Name` comes out `N3dsSession` and not `n3dsSession`.
+//
+// This is deliberately the SAME rule, spelled the same way, as apidef's
+// `prefixLeadingDigit`. A model that came through apidef is already guarded,
+// so this is a no-op on it; a hand-authored `.sdk/model` entity gets the
+// identical name apidef would have given it. Idempotent by construction.
+//
+// The rule is applied ONCE, to the model's own entity name, by
+// `guardModelNames` — never to a derived form. Guarding `Name` alone does not
+// survive: a consumer's scaffolded `Root.ts` runs its own
+// `names(entity, entity.name)` per target, which re-derives `Name` from the
+// unguarded name and silently undoes the correction.
+function prefixLeadingDigit(s: string): string {
+  if (null == s || '' === s) return s
+  const first = s.charCodeAt(0)
+  if (first < 48 || first > 57) return s
+  const letter = s.match(/[a-zA-Z]/)
+  const upper = null != letter && letter[0] >= 'A' && letter[0] <= 'Z'
+  return (upper ? 'N' : 'n') + s
+}
+
+
 // A valid ECMAScript identifier — the only shape `obj.name` can express.
 const JS_IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/
 
@@ -546,4 +589,5 @@ export {
   jsProp,
   jsOptProp,
   jsKey,
+  prefixLeadingDigit,
 }

package/src/sdkgen.ts

@@ -59,10 +59,11 @@ import type { RegisterOptions } from './cmp/Registered'
 import { buildIdNames } from './helpers/buildIdNames'
 import { getMatchEntries } from './helpers/getMatchEntries'
 import { collectDeps } from './helpers/collectDeps'
+import { guardModelNames } from './helpers/modelNames'
 import type { DepEntry } from './helpers/collectDeps'
 import { canonToType, canonToDtype, canonKey, canonScalarKey } from './helpers/canonType'
 import { OP_SUFFIX, opTypeName, opParams, ownPoint, opActions, entityActions, entityPath, opRequestShape, entityIdField, entityDataIdField, entityOps, entityPrimaryOp, pickExampleEntity, entityClassName, entityTypeCollisions, warnEntityTypeCollisions, deriveEntityNames, entityCollection } from './helpers/opShape'
-import { isReservedName, safeVarName, exampleVarName, phpEntityAccessor, entityCacheField, isRbCoreConstant, isRbSdkConstant, rbSafeTypeName, isSwiftSdkType, swiftSafeTypeName, isPhpReservedType, isPhpSdkClass, phpSafeTypeName, isTsReservedType, tsSafeTypeName, jsProp, jsOptProp, jsKey } from './helpers/naming'
+import { isReservedName, safeVarName, exampleVarName, phpEntityAccessor, entityCacheField, isRbCoreConstant, isRbSdkConstant, rbSafeTypeName, isSwiftSdkType, swiftSafeTypeName, isPhpReservedType, isPhpSdkClass, phpSafeTypeName, isTsReservedType, tsSafeTypeName, jsProp, jsOptProp, jsKey, prefixLeadingDigit } from './helpers/naming'
 import { serverVariables, hasServerVariables, serverVarEnv } from './helpers/serverVars'
 import { primaryOpCall, idLiteral, matchArg, dataArg, litFor } from './helpers/opExample'
 import type { ExampleLang } from './helpers/opExample'
@@ -269,6 +270,13 @@ function SdkGen(opts: SdkGenOptions) {
     log.info({ point: 'generate-start', start, note: opts.dryrun ? '** DRY RUN **' : '' })
     log.debug({ point: 'generate-spec', spec })
 
+    // BEFORE ANYTHING READS A NAME. An entity whose name starts with a digit
+    // yields identifiers no target language accepts, and the consumer's own
+    // Root.ts re-derives those names per target — so the only correction that
+    // survives is one made to the model itself, before Root runs. No-op on
+    // every model apidef produces; see helpers/modelNames.
+    guardModelNames(model, log)
+
     let Root = spec.root
 
     if (null == Root && null != config?.root) {
@@ -1153,6 +1161,7 @@ export {
   warnEntityTypeCollisions,
   deriveEntityNames,
   entityCollection,
+  guardModelNames,
   isReservedName,
   safeVarName,
   exampleVarName,
@@ -1205,6 +1214,7 @@ export {
   jsProp,
   jsOptProp,
   jsKey,
+  prefixLeadingDigit,
 
   packageName,
   installCommand,