@voxgig/sdkgen 4.21.0 → 4.23.0

package/project/.sdk/src/cmp/py/Main_py.ts

@@ -42,20 +42,14 @@ const Main = cmp(async function Main(props: any) {
   // helpers/applicability.
   const feature = targetFeatures(model, target)
 
-  // Does the secrets feature apply here and is it switched on? Both, since
-  // targetFeatures already dropped it for a target with no sekreto port.
   const secrets = null != (feature as any).secrets
 
-  // The one package directory everything the SDK owns lives in.
   const pkgdir = model.const.Name.toLowerCase() + '_sdk'
 
   Package({ target })
 
   Gitignore({})
 
-  // Root-level statics only (Makefile, LICENSE, test/). The runtime
-  // packages live under tm/py/pkg and are copied INSIDE the SDK package
-  // below.
   Copy({
     from: 'tm/' + target.name,
     exclude: [/src\//, /pkg\//, TEST_CONTROL_EXCLUDE],
@@ -64,35 +58,16 @@ const Main = cmp(async function Main(props: any) {
     }
   })
 
-  // Everything the SDK owns lives inside ONE package directory.
-  //
-  // core/, entity/, feature/ and utility/ used to sit at the language root
-  // as top-level importable names. `core`, `entity` and `utility` are all
-  // real PyPI distributions AND common scratch filenames, and Python puts
-  // the working directory first on sys.path — so a single utility.py beside
-  // a notebook shadowed ours and the SDK died on
-  // `No module named 'utility.voxgig_struct'`. Nesting them behind the
-  // model-named package makes that impossible.
-  //
-  // The public import is unchanged: `from <name>_sdk import <Name>SDK`,
-  // because <name>_sdk.py becomes <name>_sdk/__init__.py.
   Folder({ name: pkgdir }, () => {
 
   Copy({
     from: 'tm/' + target.name + '/pkg',
-    // An ACTIVE feature's INACTIVE plugins do not ship. py has no
-    // src/feature layout (srcfeature: false), so this blanket pkg copy is
-    // the one place the generate-time plugin trim can act; the model's
-    // `plugin.<group>.path` entries name their files relative to THIS
-    // copy's root ('feature/secrets/voxgig_sekreto/plugins/<kind>.py').
-    // See helpers/featureSource.pluginExcludes.
     exclude: [...pluginExcludes(model)],
     replace: {
       ...props.ctx$.stdrep,
     }
   })
 
-  // Generate main SDK file
   File({ name: '__init__.' + target.ext }, () => {
 
     Fragment(
@@ -101,22 +76,7 @@ const Main = cmp(async function Main(props: any) {
         replace: {
           ...props.ctx$.stdrep,
 
-          // SECRETS. Both slots are emitted only when the secrets feature
-          // applies to this target AND the model activates it - an
-          // unconditional edit would land in every generated SDK, and with
-          // the feature off the marker line is REMOVED, so the inactive
-          // output is byte-identical to pre-migration. `feature` is
-          // already gated by targetFeatures, so a target that does not
-          // provide 'sekreto' never reaches these.
-          //
-          // CUSTOM-REGEX keys, like Entity_py's hook markers: jostraca's
-          // built-in `#Name` tag pattern is hardcoded to `//` comments,
-          // so a bare '#SecretsAccessor' key would silently never match a
-          // python `# #SecretsAccessor` marker line.
-
-          // The LIVE Sekreto, not a clone: sekreto holds provider and
-          // cache state, so a clone would resolve into a copy that
-          // prepare_auth never sees.
+
           '/(?<indent>[ \\t]*)#[ \\t]*#SecretsAccessor[ \\t]*\\n?/':
             ({ indent }: any) => !secrets ? '' :
               `${indent}def secrets(self):\n` +
@@ -148,7 +108,6 @@ self._utility.feature_hook(self._rootctx, "${name}")
         }
       },
 
-      // Entities - injected at SLOT
       () => {
         each(entity, (entity: ModelEntity) => {
           const entitySDK = getModelPath(model, `main.${KIT}.entity.${entity.name}`)
@@ -177,7 +136,6 @@ if TYPE_CHECKING:
     }
   })
 
-  // Generate the typed-model module (<sdk>_types.py) next to the main SDK file.
   EntityTypes({ target })
 
   // PEP 561 marker so the inline type hints ship to consumers. Emitted at the
@@ -187,24 +145,13 @@ if TYPE_CHECKING:
     Content(``)
   })
 
-  // Generate config module
   Folder({ name: '.' }, () => {
     Config({ target })
     Schema({ target })
   })
 
-  // GENERATED, NOT COPIED. Where the credential goes is a fact about the
-  // API, and tm/ can only hold one answer. The blanket tm/py/pkg copy above
-  // no longer brings a prepare_auth.py in - it was deleted, since both
-  // writers would claim the same output path. See PrepareAuth_py.
-  //
-  // Called HERE, inside the <name>_sdk package folder and outside any
-  // other, because that is where the deleted template's own path
-  // (tm/py/pkg/utility/prepare_auth.py) put it: the component opens the one
-  // remaining segment, `utility`, itself.
   PrepareAuth({ target })
 
-  // Generate feature factory module
   File({ name: 'features.' + target.ext }, () => {
     Content(`# ${model.const.Name} SDK feature factory
 
@@ -252,11 +199,6 @@ def _has_feature(name):
 `)
   })
 
-  // Generate __init__.py files for sub-packages.
-  // NOTE: deliberately omit __init__.py at the language-root (py/) level —
-  // making py/ a package collides with the third-party `py` module on PyPI
-  // (a single-file `py.py`), which causes pytest to construct test module
-  // paths as `py.test.<file>` and fail with "'py' is not a package".
   Folder({ name: 'core' }, () => {
     File({ name: '__init__.' + target.ext }, () => {
       Content(``)
@@ -267,8 +209,6 @@ def _has_feature(name):
     File({ name: '__init__.' + target.ext }, () => {
       Content(``)
     })
-    // PEP 561 marker inside the type-bearing package so setuptools package-data
-    // ("*" = ["py.typed"]) bundles it into the wheel.
     File({ name: 'py.typed' }, () => {
       Content(``)
     })

package/project/.sdk/src/cmp/py/Package_py.ts

@@ -22,9 +22,6 @@ const Package = cmp(async function Package(props: any) {
 
   const model: Model = ctx$.model
 
-  // PyPI distribution name is namespaced to model.origin (e.g. "voxgig-sdk").
-  // PyPI names can't contain "/", so the parts are hyphen-joined. The import
-  // package (the `${model.name}_sdk/` dir) is unchanged.
   const ns = model.origin || 'voxgig-sdk'
   const pkgBase = ns.endsWith('-sdk') ? model.name : `${model.name}-sdk`
   const distName = packageName(model, target.name)

package/project/.sdk/src/cmp/py/PrepareAuth_py.ts

@@ -17,51 +17,19 @@ import {
 } from '@voxgig/apidef'
 
 
-// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API, so it is generated
-// rather than templated. The py port of cmp/ts/PrepareAuth_ts.ts; see that
-// file for the full account.
-//
-// This was a static file at `tm/py/pkg/utility/prepare_auth.py` that
-// hardcoded a lowercase `authorization` header. 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.
-//
-// 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$
 
-  // FOLDER NESTING. Main_py already opened the ONE package folder
-  // (`<name>_sdk`) that everything the SDK owns lives in, and the blanket
-  // `Copy({from: 'tm/py/pkg'})` that used to bring this file in runs inside
-  // that same folder — which is why the template's own path,
-  // `tm/py/pkg/utility/prepare_auth.py`, lands at
-  // `<name>_sdk/utility/prepare_auth.py`. So this component opens exactly
-  // ONE segment, `utility`, to reproduce that path. Opening `<name>_sdk`
-  // again would write to `<name>_sdk/<name>_sdk/utility/`, which nothing
-  // imports, while register.py kept importing the stale copy.
   Folder({ name: 'utility' }, () => {
     File({ name: 'prepare_auth.' + target.ext }, () => {
       Content(render({
-        // The generated package name, spelled the way Config_py spells it.
-        // A Copy applies ctx$.stdrep to the file it copies; Content does
-        // not, so the `projectname_sdk` placeholder the template carried
-        // has to be resolved here.
         pkg: model.const.Name.toLowerCase() + '_sdk',
         Name: model.const.Name,
         active: isAuthActive_py(model),
         where: resolveAuthIn(model),
         name: resolveAuthName(model),
         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).
         prefix: resolveAuthPrefix(model),
       }))
     })
@@ -113,10 +81,6 @@ def prepare_auth_util(ctx):
 }
 
 
-// HEADER. Byte-for-byte the old template when the scheme resolves to the
-// defaults (header / Authorization), so every header-based SDK regenerates
-// unchanged — 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 base64
 ` : '') + `from ${spec.pkg}.utility.voxgig_struct import voxgig_struct as vs
@@ -211,8 +175,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.
 function renderQuery(spec: AuthSpec, head: string): string {
   return head + `from ${spec.pkg}.utility.voxgig_struct import voxgig_struct as vs
 
@@ -257,9 +219,6 @@ def prepare_auth_util(ctx):
 }
 
 
-// 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.
 function renderCookie(spec: AuthSpec, head: string): string {
   return head + `from ${spec.pkg}.utility.voxgig_struct import voxgig_struct as vs
 
@@ -339,28 +298,6 @@ def prepare_auth_util(ctx):
 }
 
 
-// NOT `isAuthActive`, AND THE DIFFERENCE IS LOAD-BEARING. That helper is
-// false whenever the SPEC declares no security scheme (`main.kit.info.auth:
-// false`) — which is a statement about the DEFINITION, not a ban on ever
-// sending a credential. apidef writes it for every spec with no
-// securitySchemes block, GitHub's official OpenAPI included, and those SDKs
-// are still expected to honour an `apikey` the caller passes; the old
-// template placed the credential unconditionally, so they did.
-//
-// Gating the body on `isAuthActive` therefore does not just trim dead code,
-// it removes working authentication from every such SDK. The generated
-// suite catches it: generatedcompile's `py: auth null beats an explicit
-// apikey` lane generates against a fixture that declares
-// `main: kit: info: { ... auth: false }` and then requires
-// `wire({apikey: 'OPTKEY01'})` to reach the transport as an authorization
-// header. With the wider gate it reports
-//
-//   FAIL: baseline broken: an ordinary apikey was not sent:
-//         {'called': True, 'had': False, 'val': None}
-//
-// So the no-op is emitted only when the PROJECT says so — `config.auth.active:
-// false`, an explicit per-SDK switch nobody sets by accident. A spec that is
-// merely silent keeps the credential path it has always had.
 function isAuthActive_py(model: any): boolean {
   const auth = getModelPath(model, `main.${KIT}.config.auth`,
     { only_active: false, required: false })
@@ -368,12 +305,6 @@ function isAuthActive_py(model: any): boolean {
 }
 
 
-// HTTP header names are case-insensitive, and the whole py runtime spells
-// them lowercase - the debug feature's redact list, the secrets feature's
-// in-place rewrite of `fetchdef["headers"]["authorization"]`, and the
-// generated tests all match on the lowercase key. Lowercasing here keeps
-// the default byte-identical to the old template AND keeps a custom header
-// name (`X-API-Key`) findable by all of them.
 function headerName(name: string): string {
   return String(name).toLowerCase()
 }

package/project/.sdk/src/cmp/py/ReadmeEntity_py.ts

@@ -7,11 +7,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// A type-correct, JSON-serialisable Python literal for a field's canonical
-// type. The create example is EXECUTED by the doc test (the body is
-// JSON-serialised), so an Ellipsis (`...`) placeholder would raise
-// "Object of type ellipsis is not JSON serializable" — use a real value.
-// Strings render the quoted placeholder.
 function pyLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
@@ -22,14 +17,6 @@ function pyLit(type: any, placeholder: string = 'example'): string {
 }
 
 
-// Operation method spelling differs between Go and other languages — Go
-// uses PascalCase methods with explicit ctrl arg, others use lowercase
-// methods with optional ctrl. The op descriptions are language-agnostic.
-// A `list()` on a NESTED entity needs its parent path params. The
-// quickstart used to emit `client.Moon().list()` for an entity at
-// `/planet/{planet_id}/moon`, which 404s against a live server from a
-// half-built URL — indistinguishable from "no such record". The model
-// already marks those params `reqd: true`; matchArg renders exactly them.
 function listMatchArg(ent: any): string {
   const idF = entityIdField(ent)
   return matchArg('py', ent, 'list', idF, idLiteral(ent, 'list', idF))
@@ -66,7 +53,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
-    const fields = entity.fields || []
+    const fields = Object.values(entity.fields || {})
     // Model-driven id key: null when this entity has no id-like field.
     const idF = entityIdField(entity)
     // Sanitise the local variable name — an entity whose lowercased name is a
@@ -114,8 +101,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
 
       each(fields, (field: any) => {
-        const desc = field.short || ''
-        Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${desc} |
+        const desc = field.sh || ''
+        Content(`| \`${field.n}\` | \`${canonToType(field.t, target.name)}\` | ${desc} |
 `)
       })
 

package/project/.sdk/src/cmp/py/ReadmeExamplesTest_py.ts

@@ -8,37 +8,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// Emits py/test/test_readme_examples.py — a pytest COMPLETENESS GATE over
-// every ```python fenced block in the repository ROOT README.md, in the
-// per-language py/README.md, AND in the per-language py/REFERENCE.md.
-//
-// The gate GUARANTEES every documented python example is unit-tested. For each
-// of the three docs it:
-//   1. extracts every ```python block (tagged by source doc + index);
-//   2. ast.parse + compile()s EVERY block                 -> SYNTAX gate;
-//   3. EXECUTEs every RUNNABLE block (one that constructs the SDK, or drives a
-//      `client`/`sdk` the narrative built earlier) in a seeded, offline
-//      TEST-mode subprocess. A PROGRAMMING error
-//      (Name/Attribute/Type/Key/Index/Import/Syntax) FAILS; ONLY a
-//      not-found/404 domain error is tolerated. Any other error also FAILS;
-//   4. asserts COMPLETENESS: it partitions every block into exactly one of
-//      {executed, compiled-nonrunnable, illustration} and asserts
-//      total == executed + compiled + illustration. "illustration" is a NARROW
-//      explicit class (a non-runnable block that is only imports / signature
-//      stubs / bare references / literal assignments — a pure signature/table
-//      snippet) and can NEVER absorb a runnable example. A block that looks
-//      runnable (references the SDK/client) but was not executed FAILS the
-//      test; a block that fails to compile FAILS the test. A per-doc summary
-//      (total/executed/compiled/illustration) is printed.
-//
-// If mypy is importable it also type-checks the concatenated ROOT README blocks
-// (the SDK ships py.typed + TypedDicts) — a bonus TYPE gate over the primary
-// EXECUTE gate.
-//
-// The emitted Python is written WITHOUT backticks or backslashes (chr(96) is
-// the fence marker, chr(10) is newline) so this TS template literal stays
-// clean — the only interpolations are the SDK module/class names and the
-// generated entity map.
 const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
   const { target, ctx$: { model } } = props
 

package/project/.sdk/src/cmp/py/ReadmeHowto_py.ts

@@ -8,7 +8,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// A type-correct Python literal for a field's canonical type.
 function pyLit(type: any): string {
   const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
@@ -31,8 +30,6 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   // Sanitise the local variable name — an entity whose lowercased name is a
   // Python keyword (e.g. `class`) would otherwise emit uncompilable code.
   const eVar = exampleVarName(eName.toLowerCase(), 'py')
-  // Model-driven id key: null when the entity has no id-like field, so a
-  // match op takes no argument.
   const idF = exampleEntity ? entityIdField(exampleEntity) : null
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   let testArg = ''

package/project/.sdk/src/cmp/py/ReadmeModel_py.ts

@@ -117,13 +117,13 @@ On error, \`ok\` is \`False\` and \`err\` contains the error value.
 
 `)
   each(entityList, (ent: any) => {
-    const fields = ent.fields || []
+    const fields = Object.values(ent.fields || {})
     const opnames = Object.keys(ent.op || {})
     const ops = ent.op || {}
     const points = each(ops).map((op: any) =>
       op.points ? each(op.points) : []
     ).flat()
-    const path = points.length > 0 ? (points[0] as any).orig || '' : ''
+    const path = points.length > 0 ? (points[0] as any).o || '' : ''
 
     Content(`#### ${ent.Name}
 
@@ -131,7 +131,7 @@ On error, \`ok\` is \`False\` and \`err\` contains the error value.
 | --- | --- |
 `)
     each(fields, (field: any) => {
-      Content(`| \`${field.name}\` | ${field.short || ''} |
+      Content(`| \`${field.n}\` | ${field.sh || ''} |
 `)
     })
 

package/project/.sdk/src/cmp/py/ReadmeQuick_py.ts

@@ -8,11 +8,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// A `list()` on a NESTED entity needs its parent path params. The
-// quickstart used to emit `client.Moon().list()` for an entity at
-// `/planet/{planet_id}/moon`, which 404s against a live server from a
-// half-built URL — indistinguishable from "no such record". The model
-// already marks those params `reqd: true`; matchArg renders exactly them.
 function listMatchArg(ent: any): string {
   const idF = entityIdField(ent)
   return matchArg('py', ent, 'list', idF, idLiteral(ent, 'list', idF))
@@ -26,9 +21,6 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
-  // Find a nested entity if available: one with a parent chain
-  // (relations.ancestors), an active load op, and a required non-id load
-  // param to demonstrate (the parent key, e.g. page_id).
   const nestedEntity = Object.values(entity).find((e: any) =>
     e.active !== false &&
     e.relations && e.relations.ancestors && 0 < e.relations.ancestors.length &&
@@ -39,10 +31,6 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
   const authActive = isAuthActive(model)
 
-  // Server variables (a templated server URL) are REQUIRED at construction
-  // - the SDK refuses rather than request a URL with a literal
-  // {account_id} in it - so a quickstart that omits them is a quickstart
-  // that fails on its first line.
   const svars = serverVariables(model)
   const pyServerField = 0 === svars.length ? '' :
     `\n    "server": {` +
@@ -117,9 +105,6 @@ except Exception as err:
       const neArticle = /^[aeiou]/i.test(neName) ? 'an' : 'a'
       const neVar = exampleVarName(neName.toLowerCase(), 'py')
 
-      // Model-driven match: every REQUIRED load-match key — the same shape
-      // the runtime resolves path params from, so the example always works.
-      // Parent keys (e.g. page_id) first, the entity's own id last.
       const neIdF = entityIdField(nestedEntity)
       const neRequired = opRequestShape(nestedEntity, 'load').items
         .filter((it: any) => !it.optional)
@@ -148,9 +133,6 @@ except Exception as err:
 `)
     }
     else if (opnames.includes('load')) {
-      // Every REQUIRED load-match key (id first, then parent path params like
-      // page_id) — the same shape the runtime resolves path params from, so
-      // the example always works.
       const loadRequired = opRequestShape(exampleEntity, 'load').items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) =>
@@ -176,20 +158,12 @@ except Exception as err:
 `)
     }
 
-    // Model-driven example fields: derive the create/update body from the op
-    // shape (opRequestShape) so the docs reference REAL writable fields, not a
-    // hardcoded "name" the entity may not have. Literals are Python-typed by
-    // the field's canonical type. ids are rendered separately as the match key
-    // for update/remove; a REQUIRED create id stays (the call is invalid
-    // without it).
     const examplePairs = (opname: string): string[] => {
       const items = opRequestShape(exampleEntity, opname).items
         .filter((it: any) => (it.name !== idF && it.name !== 'id') ||
           ('create' === opname && !it.optional))
       const required = items.filter((it: any) => !it.optional)
       const optional = items.filter((it: any) => it.optional)
-      // create needs ALL required fields; update is a patch, so the required
-      // members plus a sample optional field or two suffice.
       const chosen = 'create' === opname
         ? (required.length ? required : items.slice(0, 2))
         : required.concat(optional).slice(0, Math.max(2, required.length))
@@ -227,8 +201,6 @@ client.${eName}().update({${updatePairs.join(', ')}})
 `)
       }
       if (opnames.includes('remove')) {
-        // Every REQUIRED remove-match key: the id (off the created record
-        // when possible) plus parent keys like page_id.
         const removePairs = opRequestShape(exampleEntity, 'remove').items
           .filter((it: any) => !it.optional || it.name === idF)
           .sort((a: any, b: any) =>

package/project/.sdk/src/cmp/py/ReadmeRef_py.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, matchArg, idLiteral } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, matchArg, idLiteral, targetFeatures } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -21,11 +21,6 @@ function pyLit(type: any, placeholder: string = 'example'): string {
 }
 
 
-// A `list()` on a NESTED entity needs its parent path params. The
-// quickstart used to emit `client.Moon().list()` for an entity at
-// `/planet/{planet_id}/moon`, which 404s against a live server from a
-// half-built URL — indistinguishable from "no such record". The model
-// already marks those params `reqd: true`; matchArg renders exactly them.
 function listMatchArg(ent: any): string {
   const idF = entityIdField(ent)
   return matchArg('py', ent, 'list', idF, idLiteral(ent, 'list', idF))
@@ -66,7 +61,7 @@ const ReadmeRef = cmp(function ReadmeRef(props: any) {
   const { model } = props.ctx$
 
   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)
 
@@ -129,7 +124,6 @@ client = ${model.const.Name}SDK.test()
 `)
 
 
-    // Entity factory methods
     publishedEntities.map((ent: any) => {
       Content(`#### \`${ent.Name}(data=None)\`
 
@@ -171,10 +165,9 @@ Prepare a fetch definition without sending. Returns the \`fetchdef\` and raises
 `)
 
 
-    // Entity reference sections
     publishedEntities.map((ent: any) => {
       const opnames = Object.keys(ent.op || {})
-      const fields = ent.fields || []
+      const fields = Object.values(ent.fields || {})
       // Model-driven id key: null when this entity has no id-like field, in
       // which case load/remove match on no argument and update omits the id.
       const idF = entityIdField(ent)
@@ -202,7 +195,6 @@ ${eVar} = client.${ent.Name}()
 `)
 
 
-      // Field schema
       if (fields.length > 0) {
         Content(`### Fields
 
@@ -210,9 +202,9 @@ ${eVar} = client.${ent.Name}()
 | --- | --- | --- | --- |
 `)
         each(fields, (field: any) => {
-          const req = field.req ? 'Yes' : 'No'
-          const desc = field.short || ''
-          Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${req} | ${desc} |
+          const req = field.r ? 'Yes' : 'No'
+          const desc = field.sh || ''
+          Content(`| \`${field.n}\` | \`${canonToType(field.t, target.name)}\` | ${req} | ${desc} |
 `)
         })
 
@@ -239,7 +231,7 @@ ${eVar} = client.${ent.Name}()
               if (fop.active === false) return '-'
               return 'Yes'
             })
-            Content(`| \`${field.name}\` | ${cols.join(' | ')} |
+            Content(`| \`${field.n}\` | ${cols.join(' | ')} |
 `)
           })
 
@@ -249,7 +241,6 @@ ${eVar} = client.${ent.Name}()
       }
 
 
-      // Operation details
       if (opnames.length > 0) {
         Content(`### Operations
 
@@ -337,7 +328,6 @@ ${updateLines}    # Fields to update
       }
 
 
-      // Common methods
       Content(`### Common Methods
 
 #### \`data_get() -> dict\`
@@ -368,7 +358,6 @@ Return the entity name.
     })
 
 
-    // Features section
     const activeFeatures = each(feature).filter((f: any) => f.active)
     if (activeFeatures.length > 0) {
       Content(`
@@ -404,9 +393,6 @@ client = ${model.const.Name}SDK({
 \`\`\`
 
 `)
-      // 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/py/ReadmeTopQuick_py.ts

@@ -22,11 +22,6 @@ function pyLit(type: any, placeholder: string = 'example'): string {
 }
 
 
-// A `list()` on a NESTED entity needs its parent path params. The
-// quickstart used to emit `client.Moon().list()` for an entity at
-// `/planet/{planet_id}/moon`, which 404s against a live server from a
-// half-built URL — indistinguishable from "no such record". The model
-// already marks those params `reqd: true`; matchArg renders exactly them.
 function listMatchArg(ent: any): string {
   const idF = entityIdField(ent)
   return matchArg('py', ent, 'list', idF, idLiteral(ent, 'list', idF))
@@ -42,10 +37,6 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
 
   const authActive = isAuthActive(model)
 
-  // Server variables (a templated server URL) are REQUIRED at construction
-  // - the SDK refuses rather than request a URL with a literal
-  // {account_id} in it - so a quickstart that omits them is a quickstart
-  // that fails on its first line.
   const svars = serverVariables(model)
   const pyServerField = 0 === svars.length ? '' :
     `\n    "server": {` +
@@ -72,8 +63,6 @@ client = ${ctor}
     // Python keyword (e.g. `class`) would otherwise emit uncompilable code.
     const eVar = exampleVarName(eName.toLowerCase(), 'py')
     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 no match argument.
     const idF = entityIdField(exampleEntity)
 
     let hasCall = false
@@ -88,9 +77,6 @@ for ${eVar} in ${eVar}s:
     }
 
     if (opnames.includes('load')) {
-      // Every REQUIRED load-match key (id first, then parent path params like
-      // page_id) — the same shape the runtime resolves path params from, so
-      // the example always works.
       const loadItems = opRequestShape(exampleEntity, 'load').items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) =>

package/project/.sdk/src/cmp/py/Schema_py.ts

@@ -12,25 +12,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
-//
-// The python peer of src/cmp/ts/Schema_ts.ts. Same two exports, same source:
-// OPTSPEC from `main.kit.optspec` plus each feature's own `config.options`,
-// ENTITYSPEC from the entity field sentinels — both built by the shared
-// helpers, so what python validates against and what ts validates against
-// cannot drift.
-//
-// EMBEDDED AS JSON, PARSED AT IMPORT, the same mechanism config.py already
-// uses for the model above the size threshold. A python dict literal would
-// also work here, but `json.loads` (the C accelerator) builds it from one
-// string constant rather than making the byte-compiler walk several hundred
-// literal nodes, and it is the one mechanism every ported target shares.
-//
-// The round-trip is exact because the spec holds only strings and booleans —
-// pinned by "strings and booleans only, so the JSON round-trip is lossless"
-// in ts/test/optspec.test.ts. JSON's single number type is the hazard that
-// test exists for: `true`/`false` and `null` differ between JSON and python
-// source, which is why this is a parsed string and not a literal paste.
 const Schema = cmp(async function Schema(props: any) {
   const ctx$ = props.ctx$
   const target = props.target
@@ -44,7 +25,7 @@ const Schema = cmp(async function Schema(props: any) {
     Content(`# ${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 OPTSPEC; entity \`fields[].type\` for ENTITYSPEC.
+# \`config.options\` for OPTSPEC; entity \`fields{}.type\` for ENTITYSPEC.
 
 from __future__ import annotations