@voxgig/sdkgen 4.20.0 → 4.22.0

package/project/.sdk/src/cmp/scala/PrepareAuth_scala.ts

@@ -15,102 +15,23 @@ import {
 import { scalaPackage } from './utility_scala'
 
 
-// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API, so it is generated
-// rather than templated. The scala port of cmp/ts/PrepareAuth_ts.ts; see
-// that file for the full account.
-//
-// scala had no prepare_auth template to delete. The logic was an `object
-// PrepareAuth` EMBEDDED in `tm/scala/utility/Prepare.scala` alongside the
-// six other prepare steps, hardcoding `val HEADER_AUTH = "authorization"`.
-// apidef has always resolved the scheme's `in` and `name` into
-// `main.kit.info.security` — joplin's says `in: "query", name: "token"` —
-// and generation dropped both, so the SDK sent a header the API does not
-// read and never sent the query parameter it does.
-//
-// EXTRACTED INTO ITS OWN FILE rather than generating the whole of
-// Prepare.scala. A Scala `object` is not tied to a file name: the compiler
-// resolves `PrepareAuth.prepareAuth` by PACKAGE, and every caller —
-// utility/Register.scala's `u.prepareAuth = (ctx) => PrepareAuth
-// .prepareAuth(ctx)`, which is the only binding — already names it
-// unqualified from inside `package SCALAPACKAGE.utility`. So moving the
-// object into `utility/PrepareAuth.scala` in the same package leaves
-// Register, core/Utility.scala's `var prepareAuth` field, utility/MakeSpec
-// .scala's `utility.prepareAuth(ctx)` and core/SdkClient.scala's call
-// site all resolving exactly as before, with no edit to any of them. The
-// other six objects in Prepare.scala (PreparePath, PrepareMethod,
-// PrepareParams, PrepareQuery, PrepareHeaders, PrepareBody) are placement-
-// independent and stay templated, so the generated surface is exactly the
-// part that varies with the API.
-//
-// A template cannot fix this, because the three placements need three
-// different bodies and a template has to pick one. A component emits the
-// branch this API actually uses and nothing else — no dead query code in a
-// bearer-token SDK, and no runtime `if` on a value that is fixed at
-// generation time.
 const PrepareAuth = cmp(async function PrepareAuth(props: any) {
   const { target } = props
   const { model } = props.ctx$
 
   const where = resolveAuthIn(model)
 
-  // LOWERCASED FOR A HEADER, VERBATIM OTHERWISE. apidef writes
-  // `name: "Authorization"`, the deleted `object PrepareAuth` hardcoded
-  // `"authorization"`, and the whole scala runtime reads the lower-case
-  // key: the shared primary corpus asserts
-  // `ctx:spec:headers:authorization`, SecretsFeature.reauth rewrites
-  // `headers.put("authorization", ...)` in place on a token refresh, and
-  // spec.headers is a plain case-sensitive LinkedHashMap. Emitting
-  // `Authorization` verbatim would put the credential under a key nothing
-  // reads. A query parameter and a cookie ARE case-sensitive, so they keep
-  // the spec's spelling exactly.
   const resolved = resolveAuthName(model)
   const name = 'header' === where ? resolved.toLowerCase() : resolved
 
   const basic = isHttpBasicAuth(model)
 
-  // Read so the resolution is visible at generation time even though the
-  // emitted code takes the prefix from options at runtime (the secrets
-  // feature rewrites it there).
   const prefix = resolveAuthPrefix(model)
 
-  // NOT `isAuthActive`, AND THE DIFFERENCE IS LOAD-BEARING. See
-  // isAuthSuppressed in sdkgen's utility.ts: `isAuthActive` is ALSO false
-  // whenever `main.kit.info.auth` is false, which says only that the SPEC
-  // declared no security scheme — such an SDK still carries a credential,
-  // because Make.scala's optspec always declares `apikey` and fills
-  // `options.auth` from its `{ "prefix": "" }` default, so the runtime
-  // `options.get("auth") == null` guard never fires and every such SDK has
-  // always sent `options.apikey`. Emitting a no-op for those would
-  // silently remove working authentication and take the secrets feature
-  // with it (SecretsFeature resolves a secret into options.apikey and
-  // prepareAuth then places nothing).
-  //
-  // `main.kit.config.auth.active: false` is the project saying "this SDK
-  // sends no credential, ever" — the only signal that can honestly be
-  // honoured before runtime, so it is the only one used.
   const active = !isAuthSuppressed(model)
 
   const scalapackage = scalaPackage(model)
 
-  // FOLDER NESTING: exactly one segment, `utility`.
-  //
-  // Worked out from the deleted code's own path and from Main_scala's call
-  // site. Main_scala's blanket `Copy({ from: 'tm/scala' })` runs at the
-  // TARGET ROOT (its excludes and the scala tree are root-relative, and
-  // project.scala/Makefile sit beside core/, utility/, entity/), so
-  // `tm/scala/utility/Prepare.scala` lands at `<root>/utility/Prepare
-  // .scala`. Reproducing that path from Main's TOP LEVEL therefore needs
-  // `utility` and nothing above it — the same one-segment shape
-  // EntityBase_scala uses for `entity`.
-  //
-  // So this component must be invoked from Main_scala's top level and NOT
-  // from inside its `Folder({ name: 'core' })`, where Config and
-  // EntityTypes are written: nested there it would emit
-  // `core/utility/PrepareAuth.scala`, whose `package <pkg>.utility`
-  // declaration contradicts its directory, while Register.scala kept
-  // binding the stale object. There is no `src` folder in a scala SDK at
-  // all, so the ts port's `src/src/utility/` failure has no scala twin —
-  // the scala twin would be `core/`.
   Folder({ name: 'utility' }, () => {
     File({ name: 'PrepareAuth.' + target.ext }, () => {
       Content(render({ scalapackage, active, where, name, prefix, basic }))
@@ -130,19 +51,10 @@ type AuthSpec = {
 
 
 function render(spec: AuthSpec): string {
-  // The package line alone. Each placement emits its OWN import block,
-  // because they need different ones and the scala templates put the
-  // java.* imports first - Prepare.scala, Make.scala and Spec.scala all
-  // read `import java.util...` then the SDK's own packages.
   const head = `package ${spec.scalapackage}.utility
 
 `
 
-  // NO AUTH AT ALL - the project switched it off explicitly (see `active`
-  // above for why only an EXPLICIT switch counts). The SDK gets a
-  // prepareAuth that is honest about it rather than one that removes a
-  // header nobody set; Struct is not imported, because nothing here reads
-  // an option.
   if (!spec.active) {
     return head + `import ${spec.scalapackage}.core.{Context, Spec}
 
@@ -169,12 +81,6 @@ object PrepareAuth {
 }
 
 
-// HEADER. Behaviourally the deleted `object PrepareAuth` when the scheme
-// resolves to the defaults (header / Authorization): the same option names,
-// the same `skip` idiom for a missing credential, the same auth_no_spec
-// error, the same empty-prefix rule. Only the constant's VALUE moves with
-// the model, plus the HTTP Basic block, which is emitted only for a basic
-// scheme.
 function renderHeader(spec: AuthSpec, head: string): string {
   return head + `${spec.basic ? `import java.nio.charset.StandardCharsets
 import java.util.Base64
@@ -266,9 +172,6 @@ function basicBlock(spec: AuthSpec): string {
 }
 
 
-// QUERY. The credential is a query parameter, so it goes in spec.query and
-// the headers are never touched. This is the placement joplin, pipedrive,
-// trello and lm-umbrella declare and no generated SDK ever emitted.
 function renderQuery(spec: AuthSpec, head: string): string {
   return head + `import ${spec.scalapackage}.core.{Context, Spec}
 import ${spec.scalapackage}.utility.struct.Struct
@@ -321,11 +224,6 @@ object PrepareAuth {
 }
 
 
-// COOKIE. A cookie IS a header, so the credential rides the header bag -
-// but the `cookie` header is SHARED with whatever cookies the caller set,
-// so the pair is spliced in and out rather than the header assigned over.
-// Splicing also makes this idempotent: a retried request cannot end up
-// carrying the credential twice.
 function renderCookie(spec: AuthSpec, head: string): string {
   return head + `import java.util.{Map => JMap}
 

package/project/.sdk/src/cmp/scala/ReadmeEntity_scala.ts

@@ -11,7 +11,6 @@ import { scalaVarName } from './utility_scala'
 
 // Type names come from the shared canonToType 'scala' column (single source of truth).
 
-// A type-correct Scala literal for a field's canonical type.
 function scalaLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
   if ('INTEGER' === k) return '1L'

package/project/.sdk/src/cmp/scala/ReadmeExamplesTest_scala.ts

@@ -2,29 +2,6 @@
 import { cmp, File, Content } from '@voxgig/sdkgen'
 
 
-// Emits sdktest/ReadmeExamplesTest.scala — a PRESENCE + STRUCTURE gate over
-// every scala fenced block in the repository ROOT README.md, the per-language
-// scala/README.md, AND the per-language scala/REFERENCE.md. It is a
-// default-package scala-cli object exposing run(rep) and is driven by the
-// generated SdkEntityTestMain aggregator (mirrors the generated per-entity
-// test objects).
-//
-// SCOPE NOTE (deliberate, documented): the Python/TS/Go equivalents EXECUTE and
-// type-check every documented block. That is infeasible here — the generated
-// Scala SDK compiles with scala-cli only (no in-process Scala compiler wired
-// into the test runtime), so a test cannot compile-and-run arbitrary doc
-// snippets at test time. This gate therefore guarantees the weaker-but-real
-// invariant that keeps the docs honest as the generator evolves:
-//   1. every doc exists and contains at least one scala block (nothing was
-//      dropped);
-//   2. every scala block is structurally well-formed — its braces, parentheses
-//      and brackets balance (catches a truncated or malformed generated
-//      snippet).
-// A per-doc summary line makes the coverage visible in the test output.
-//
-// The emitted Scala is written WITHOUT literal backticks (the fence marker is
-// built at runtime as 96.toChar.toString.repeat(3)) so this TS template literal
-// stays clean.
 const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
   const { target, ctx$: { model } } = props
 

package/project/.sdk/src/cmp/scala/ReadmeRef_scala.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -60,7 +60,7 @@ const ReadmeRef = cmp(function ReadmeRef(props: any) {
   const SDK = model.const.Name + 'SDK'
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  const feature = targetFeatures(model, target)
 
   const publishedEntities = each(entity).filter((e: any) => e.active !== false)
 
@@ -378,9 +378,6 @@ val client = new ${SDK}(options)
 \`\`\`
 
 `)
-      // The shared feature reference: options, defaults, usage and the
-      // considerations. Model facts, identical in every target, so they are
-      // written once in cmp/ReadmeRefFeatures.ts rather than here.
       ReadmeRefFeatures({ target })
     }
 

package/project/.sdk/src/cmp/scala/ReadmeTopQuick_scala.ts

@@ -54,15 +54,10 @@ val client = new ${SDK}(options)
   }
 
   if (exampleEntity) {
-    // Sanitise the local variable name — an entity whose camelCased name is a
-    // Scala keyword gets a trailing underscore (scalaVarName) so the snippet
-    // compiles.
     const eVar = scalaVarName(exampleEntity.name)
     const accessor = scalaVarName(exampleEntity.name)
     const eNameLower = nom(exampleEntity, 'Name').toLowerCase()
     const opnames = Object.keys(exampleEntity.op || {})
-    // Model-driven id key: null when the entity has no id-like field, in which
-    // case the load example takes an empty match.
     const idF = entityIdField(exampleEntity)
 
     if (opnames.includes('list')) {

package/project/.sdk/src/cmp/scala/Schema_scala.ts

@@ -0,0 +1,89 @@
+import {
+  Content,
+  File,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+import {
+  scalaPackage,
+  jsonAppendLines,
+} from './utility_scala'
+
+
+const Schema = cmp(async function Schema(props: any) {
+  const ctx$ = props.ctx$
+  const target = props.target
+
+  const model: Model = ctx$.model
+  const scalapackage = scalaPackage(model)
+
+  const optspec = optionSpec(model, target.name)
+  const entityspec = entitySpecMap(model, target.name) || {}
+
+  // Beside Config.scala, and for the same reason: core owns the generated
+  // data, so nothing in utility or feature has to reach up for it.
+  File({ name: 'Schema.' + target.ext }, () => {
+
+    Content(`package ${scalapackage}.core
+
+import java.util.{Map => JMap}
+
+import ${scalapackage}.utility.Json
+
+// ${model.const.Name} ${target.Name} SDK: generated schemas. Do not edit.
+//
+// Generated from the model: \`main.kit.optspec\` and each feature's
+// \`config.options\` for the option spec; entity \`fields[].type\` for the
+// entity specs.
+object Schema {
+
+  // Parsed ONCE, on first use. The spec is read on every client construction
+  // and never mutated, so a per-call parse would be pure waste - and a shared
+  // map is safe for the same reason the spec is a constant: makeOptions
+  // validates AGAINST it and writes into the options, never into the spec.
+  //
+  // A lazy val is initialised once, on first use, under a lock, as
+  // Config.sharedConfig is, so concurrent first calls parse it exactly once.
+
+  // The option spec makeOptions validates client options against.
+  lazy val optspec: JMap[String, Object] =
+    Json.parse(optspecJson()).asInstanceOf[JMap[String, Object]]
+
+  // Per-entity data and request specs, keyed by entity name.
+  lazy val entityspec: JMap[String, Object] =
+    Json.parse(entityspecJson()).asInstanceOf[JMap[String, Object]]
+
+  private def optspecJson(): String = {
+    val b = new StringBuilder()
+`)
+
+    Content(jsonAppendLines(optspec, 'b'))
+
+    Content(`    b.toString
+  }
+
+  private def entityspecJson(): String = {
+    val b = new StringBuilder()
+`)
+
+    Content(jsonAppendLines(entityspec, 'b'))
+
+    Content(`    b.toString
+  }
+}
+`)
+  })
+})
+
+
+export {
+  Schema
+}

package/project/.sdk/src/cmp/scala/TestEntity_scala.ts

@@ -24,11 +24,6 @@ import {
 import { scalaVarName } from './utility_scala'
 
 
-// Scala GenCtx mirrors the java donor's shape (see TestEntity_java.ts). The
-// scala per-entity test is a dependency-free scala-cli object (default
-// package) exposing run(rep) — driven by the generated SdkEntityTestMain
-// aggregator. Only the offline unit path is emitted: the in-memory test
-// transport serves the fixtures, so there is no live/env/synthetic machinery.
 type GenCtx = {
   model: Model
   entity: ModelEntity
@@ -217,9 +212,6 @@ const generateList: OpGen = (ctx, step, index) => {
 `)
   }
 
-  // Select-by-id assertions require the DATA type to carry an id field
-  // (entityDataIdField); an entity keyed only on a load-MATCH id it does not
-  // return as data has no `.get("id")` to compare, so skip them.
   const hasDataId = null != entityDataIdField(entity)
   const allSteps = Object.values(flow.step) as any[]
   const listvarUsed = hasDataId && !!step.valid?.some((v: any) => {

package/project/.sdk/src/cmp/scala/Test_scala.ts

@@ -62,9 +62,6 @@ const Test = cmp(function Test(props: any) {
       }
     })
 
-    // Documentation scala-examples presence + structure gate over the root
-    // README, scala/README.md and scala/REFERENCE.md. Driven through the same
-    // shared report by the SdkEntityTestMain aggregator below.
     ReadmeExamplesTest({ target, scalapackage })
 
     // Aggregating main: run every generated per-entity test through one

package/project/.sdk/src/cmp/scala/utility_scala.ts

@@ -17,12 +17,6 @@ function projectPath(suffix?: string): string {
 }
 
 
-// The Scala package root for the generated SDK, mirroring how the go target
-// derives GOMODULE and the java target derives its package: org segment from
-// model.origin, name segment from the model name (e.g. origin voxgig-sdk +
-// name solardemo -> voxgig.solardemosdk). Each runtime piece lives under it:
-// <pkg>.core, <pkg>.utility, <pkg>.utility.struct, <pkg>.feature,
-// <pkg>.entity, <pkg>.sdktest.
 function scalaPackage(model: any): string {
   const org = String(model.origin || 'voxgig-sdk')
     .replace(/-sdk$/, '')
@@ -55,8 +49,6 @@ const SCALA_KEYWORDS = new Set([
 ])
 
 
-// A camelCase Scala identifier for a snake_case model name
-// (`status_embed_config` -> `statusEmbedConfig`), with a reserved-word guard.
 function scalaVarName(name: string): string {
   const pascal = camelify(name)
   const out = pascal.charAt(0).toLowerCase() + pascal.slice(1)
@@ -64,29 +56,6 @@ function scalaVarName(name: string): string {
 }
 
 
-// Strip model bookkeeping keys (ending in $) from a config subtree.
-// Emission-time normalisation of a model subtree (L0).
-//
-// Always drops jostraca's iteration metadata (`$`-suffixed keys: index$,
-// key$, val$). With `dropDefaults`, also drops keys whose value IS the
-// default the runtime already assumes when the key is absent, which is pure
-// payload — see CONFIG_DEFAULT.
-//
-// Rebuilds the tree rather than mutating during a walk. The previous
-// implementation walked a clone calling `delete p[k]`, but walk() assigns its
-// callback's result back over the child (`setprop(out, ckey, walk(...))`), so
-// the delete was undone on the way out and the helper silently did nothing.
-// Returning `undefined` from the callback does not fix it either: setprop
-// stores undefined rather than removing the key, which then emits as a null.
-//
-// `dropDefaults` is opt-in and must be passed ONLY for the entity subtree.
-// `active` means something different in feature config, where absent reads as
-// INACTIVE (see feature_init) — dropping `active: true` there would silently
-// disable the feature.
-// jostraca's iteration metadata, injected by each()/names() while it walks the
-// model. Listed explicitly rather than matched by trailing-dollar suffix: a
-// trailing dollar is not exclusive to jostraca -- Seneca uses entity$ as real
-// data -- so a blanket suffix match can silently drop a legitimate API field.
 const MODEL_META = ['index$', 'key$', 'val$']
 
 // Keys whose value IS the default the runtime already assumes when the key is

package/project/.sdk/src/cmp/swift/Config_swift.ts

@@ -29,42 +29,10 @@ const Config = cmp(async function Config(props: any) {
 
   const model: Model = ctx$.model
 
-  // 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 config as data, built by the shared helper so every target embeds
-  // the same model by construction. Passing target.name opts this target
-  // into main.slug / main.version / main.target (the three station
-  // descriptor identity fields, station design §4); swift has only the
-  // JSON-literal rep, so that one call covers every rep this target emits.
-  //
-  // `def` rather than the helper's own `json`, because `in` and `name` are
-  // added to the auth block below and the JSON has to be re-serialised over
-  // that. When nothing is added, `JSON.stringify(def)` IS the helper's
-  // `json` - same object, same key order - so a header SDK's config is
-  // byte-identical to what it was.
   const { def } = configDefinition(model, target.name)
 
-  // `in` and `name` TRAVEL WITH THE PREFIX NOW. apidef resolved both from
-  // the spec's securityScheme all along (main.kit.info.security - joplin's
-  // says `in: "query", name: "token"`) and generation dropped them, so an
-  // apiKey-in-query API got an Authorization header it does not read.
-  //
-  // Emitted ONLY when they differ from the header/Authorization defaults, so
-  // every header-based SDK regenerates byte-identical. The generated
-  // prepareAuth bakes the placement in at generation time (see
-  // PrepareAuth_swift); these carry it in the config so a running SDK, and
-  // anything reading its descriptor, can say what its scheme actually is.
-  //
-  // THE OPTSPEC HAS TO NAME THEM TOO. `main.kit.optspec.auth` does, but
-  // swift does not read the model for its option spec - buildOptSpec() in
-  // tm/swift/Sources/ProjectNameSDK/utility/MakeOptions.swift is written out
-  // by hand - so both were added there in the same change. Without that this
-  // block is inert at best: makeOptions merges the config's options and
-  // validates the result against that spec, and a key the spec does not name
-  // is dropped or rejected.
   const authIn = resolveAuthIn(model)
   const authName = resolveAuthName(model)
   const authOpt: any = (def as any)?.options?.auth
@@ -75,42 +43,12 @@ const Config = cmp(async function Config(props: any) {
 
   const json = JSON.stringify(def)
 
-  // Model-data defaults may carry the ProjectName placeholder (e.g. the
-  // clienttrack clientName); resolve it to the API name so the embedded JSON
-  // matches the token-replaced runtime.
   const configJson = json.replace(/ProjectName/g, model.const.Name)
 
-  // PLUGIN DEFINITIONS AND THE featurePlugins MAP (the swift peer of
-  // Config_go's featurePlugins / Config_ts's pluginDefs).
-  //
-  // Upstream sekreto replaced its self-registration registry with
-  // voxgig/plugin definitions: a provider kind the caller did not pass in
-  // via `plugins:` is unknown to that Sekreto. So the config names each
-  // active plugin's exported Definition BY SYMBOL (the model's per-target
-  // `def.swift` map - `hashicorp`, a top-level `let` in the vendored
-  // SekretoPlugins module) and hands the list to the feature through
-  // SdkConfig.featurePlugins.
-  //
-  // Typed `[String: [Any]]`, as go types it `[]any`, so Config never has to
-  // name `Definition` - and so needs `import SekretoPlugins` only when a
-  // definition is actually listed. The feature reads the list back and
-  // downcasts.
-  //
-  // The ACCESSOR IS EMITTED UNCONDITIONALLY (empty map when nothing is
-  // selected). Its caller, feature/SecretsFeature.swift, ships whenever the
-  // feature is active, and java gated the accessor on "a feature declares a
-  // plugin block" - which a project that never selected secrets does not
-  // have - and shipped an SDK that did not compile (.handover-briefs/
-  // fixb-java.md). One rule: what a template may reference, Config always
-  // declares.
   const featurePlugins: Record<string, string[]> = {}
   each(feature, (f: any) => {
     const syms: string[] = []
     each(f.plugin, (plugin: any) => {
-      // Filter on `active` HERE rather than trusting the feature object to
-      // arrive filtered (see Config_ts.pluginImports: getting this wrong
-      // names a definition the trim just deleted, and swiftc fails the
-      // whole module on the unresolved symbol).
       if (false === plugin.active || null == plugin.active) return
       for (const sym of Object.keys(plugin.def?.swift || {})) {
         syms.push(sym)

package/project/.sdk/src/cmp/swift/EntityOperation_swift.ts

@@ -9,9 +9,6 @@ const EntityOperation = cmp(function Operation(props: any) {
   const { model } = props.ctx$
   const { ff, opname, entity, entrep, cls } = props
 
-  // The op markers sit inside the class body; the captured indent (2-space
-  // class-member indent) is applied to the whole spliced EJECT region, which
-  // is written at column 0.
   const { indent } = props
 
   Fragment({

package/project/.sdk/src/cmp/swift/EntityTypes_swift.ts

@@ -1,24 +1,4 @@
 
-// Typed-model generator (Swift target). Port of EntityTypes_rust.ts /
-// EntityTypes_go.ts.
-//
-// Reads main.<KIT>.entity.<e>.fields[] and per-op params
-// (op.<name>.points[].args.params[]) and emits one file,
-// Sources/ProjectNameSDK/entity/<Name>Types.swift, with a `struct <Name>` per
-// entity plus a request/match struct per active op. Field/param sentinels
-// ($STRING, $INTEGER, ...) map to Swift types via the SHARED canonToType
-// 'swift' column (the single source of truth per language — do not keep a
-// local table here).
-//
-// DESIGN NOTE: the Swift runtime is fully DYNAMIC — every op takes and returns
-// the vendored `Value` enum (throws on error) and the op fragments emit no
-// typed wrappers. These typed models are therefore DOCUMENTARY: they mirror the
-// entity/op shapes for reference and IDE support, but are not wired into the op
-// signatures. They compile as part of the SwiftPM target (every .swift under
-// Sources/ProjectNameSDK is built) so they stay in sync with the model.
-//   * Optional (req:false) member -> `T?`.
-//   * Unknown/missing sentinel -> the dynamic `Value` (never fails), matching
-//     the runtime's open shape.
 
 import {
   cmp, each,
@@ -48,9 +28,6 @@ function propLine(name: string, sentinel: any, optional: boolean): string {
 }
 
 
-// Emit a `struct <typeName>` from {name, type, optional} items, dropping
-// duplicate Swift identifiers (two model names can collapse to one ident). An
-// empty struct is a valid, zero-property shape.
 function emitStruct(comment: string, typeName: string, items: any[]): void {
   Content(`${comment}
 public struct ${typeName} {
@@ -78,14 +55,8 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
   // collection, so inactive entities still get generated entity code that
   // references these typed names. The typed model must cover them too.
   const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
-  // Emit for every entity that gets an entity file (filter on `name`, always
-  // present; derive `Name` here so the struct set is deterministic — parity
-  // with the rust/go emitter's fix).
   const entityList = deriveEntityNames(entity)
 
-  // Surface duplicate generated type names (two entities with the same
-  // PascalCase Name) — they would redeclare a type in statically-typed
-  // targets. Detection only; renaming is a model-level decision.
   warnEntityTypeCollisions(entity, log, LANG)
 
   Folder({ name: 'Sources' }, () => {
@@ -113,13 +84,6 @@ import Foundation
             const fields = (ent.fields ? each(ent.fields) : [])
               .filter((f: any) => f.active !== false)
 
-            // Entity data model: one property per field. req:false -> optional.
-            //
-            // Swift has no intra-module namespacing, so a spec schema named
-            // after one of our own runtime types (e.g. `Response`) would be a
-            // redeclaration and fail the build. swiftSafeTypeName appends
-            // `Type` on collision only — `Response` -> `ResponseType` — so
-            // non-colliding SDKs generate byte-identical output to before.
             const TypeName = swiftSafeTypeName(Name)
             emitStruct(
               `/// ${TypeName} is the typed data model for the ${ent.name} entity.`,
@@ -127,9 +91,6 @@ import Foundation
               fields.map((f: any) => ({ name: f.name, type: f.type, optional: false === f.req }))
             )
 
-            // Per active op: a request/match struct. Members and their
-            // optionality come from the shared partiality policy
-            // (opRequestShape).
             const ops = ent.op || {}
               ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
                 if (null == ops[opname]) {