@voxgig/sdkgen 4.21.0 → 4.23.0

package/project/.sdk/src/cmp/php/TestEntity_php.ts

@@ -1,3 +1,4 @@
+import { flowSteps } from '@voxgig/sdkgen'
 
 import {
   flatten,
@@ -33,9 +34,6 @@ import {
 import { formatPhpValue } from './utility_php'
 
 
-// PHP's GenCtx mirrors the shared shape (see TestEntity_ts.ts) plus an
-// `accessor` slot used to mangle the entity factory name when it collides
-// with PHP's case-insensitive `test()` static constructor.
 type GenCtx = {
   model: Model
   entity: ModelEntity
@@ -66,12 +64,6 @@ const TestEntity = cmp(function TestEntity(props: any) {
     return
   }
 
-  // The accessor may be mangled to avoid colliding with an SDK class member.
-  // This used to carry its own copy of the rule, which only knew about `test`
-  // — so an entity named `graph_ql` emitted `$client->GraphQl(null)` here,
-  // which PHP resolves (case-insensitively) to the SDK's own
-  // `graphql(string $query)` and fails with "Argument #1 must be of type
-  // string, null given". One helper, one answer.
   const entName = nom(entity, 'Name')
   const accessor = phpEntityAccessor(entName)
 
@@ -101,10 +93,10 @@ const TestEntity = cmp(function TestEntity(props: any) {
   const idnames = buildIdNames(entity, basicflow)
   const idnamesStr = idnames.map(n => `"${n}"`).join(', ')
 
-  const allSteps = Object.values(basicflow.step) as any[]
-  const updateStep = allSteps.find((s: any) => s.op === 'update')
-  const updateData = updateStep?.data
-    ? Object.entries(updateStep.data).filter(([k]: any) => k !== 'id' && !k.endsWith('$'))
+  const allSteps = Object.values(flowSteps(basicflow)) as any[]
+  const updateStep = allSteps.find((s: any) => s.o === 'update')
+  const updateData = updateStep?.d
+    ? Object.entries(updateStep.d).filter(([k]: any) => k !== 'id' && !k.endsWith('$'))
     : []
   const aliases = updateData.map(([k, v]: any) => [k, v])
 
@@ -176,7 +168,7 @@ ${hasList ? `
         $setup = ${entity.name}_basic_setup(null);
         // Per-op sdk-test-control.json skip.
         $_live = !empty($setup["live"]);
-        foreach ([${(Array.from(new Set((allSteps as any[]).map((s: any) => s.op).filter(Boolean)))).map(o => `"${o}"`).join(', ')}] as $_op) {
+        foreach ([${(Array.from(new Set((allSteps as any[]).map((s: any) => s.o).filter(Boolean)))).map(o => `"${o}"`).join(', ')}] as $_op) {
             [$_shouldSkip, $_reason] = Runner::is_control_skipped("entityOp", "${entity.name}." . $_op, $_live ? "live" : "unit");
             if ($_shouldSkip) {
                 $this->markTestSkipped($_reason ?? "skipped via sdk-test-control.json");
@@ -194,7 +186,7 @@ ${hasList ? `
 `)
 
     // Check if the flow has a create step
-    const flowHasCreate = allSteps.some((s: any) => s.op === 'create')
+    const flowHasCreate = allSteps.some((s: any) => s.o === 'create')
     if (!flowHasCreate) {
       Content(`        // Bootstrap entity data from existing test data.
         $${entity.name}_ref01_data_raw = Vs::items(Helpers::to_map(
@@ -208,16 +200,16 @@ ${hasList ? `
     }
 
     // Model-driven step iteration
-    each(basicflow.step, (step: any, index: any) => {
+    each(flowSteps(basicflow), (step: any, index: any) => {
       // Never emit a REMOVE (or its removed-item verify LIST) without a
       // preceding CREATE: a coherent CRUD flow only removes what it created,
       // so a create-less remove would mutate pre-existing (live) data.
       if (!flowHasCreate) {
-        if ('remove' === step.op) { return }
-        if ('list' === step.op &&
-          (step.valid || []).some((v: any) => 'ItemNotExists' === v.apply)) { return }
+        if ('remove' === step.o) { return }
+        if ('list' === step.o &&
+          (step.v || []).some((v: any) => 'ItemNotExists' === v.apply)) { return }
       }
-      const opgen: OpGen = GENERATE_OP[step.op]
+      const opgen: OpGen = GENERATE_OP[step.o]
       if (opgen) {
         opgen(genCtx, step, index)
         Content('\n')
@@ -325,18 +317,18 @@ ${hasList ? `
 
 const generateCreate: OpGen = (ctx, step, index) => {
   const { entity, flow, accessor } = ctx
-  const ref = step.input.ref ?? entity.name + '_ref01'
-  const entvar = step.input.entvar ?? ref + '_ent'
-  const datavar = step.input.datavar ?? (ref + '_data' + (step.input.suffix ?? ''))
+  const ref = step.i.ref ?? entity.name + '_ref01'
+  const entvar = step.i.entvar ?? ref + '_ent'
+  const datavar = step.i.datavar ?? (ref + '_data' + (step.i.suffix ?? ''))
 
-  const priorSteps = Object.values(flow.step).slice(0, Number(index)) as any[]
+  const priorSteps = Object.values(flowSteps(flow)).slice(0, Number(index)) as any[]
   const needsEnt = !priorSteps.some((s: any) =>
-    ['create', 'list', 'load', 'update', 'remove'].includes(s.op))
+    ['create', 'list', 'load', 'update', 'remove'].includes(s.o))
 
   const hasDatvar = priorSteps.some((s: any) => {
-    if ('create' === s.op) {
-      const priorRef = s.input.ref ?? entity.name + '_ref01'
-      const priorDatvar = s.input.datavar ?? (priorRef + '_data' + (s.input.suffix ?? ''))
+    if ('create' === s.o) {
+      const priorRef = s.i.ref ?? entity.name + '_ref01'
+      const priorDatvar = s.i.datavar ?? (priorRef + '_data' + (s.i.suffix ?? ''))
       return priorDatvar === datavar
     }
     return false
@@ -380,14 +372,14 @@ const generateCreate: OpGen = (ctx, step, index) => {
 const generateList: OpGen = (ctx, step, index) => {
   const { entity, flow, accessor } = ctx
   const hasDataId = null != entityDataIdField(entity)
-  const ref = step.input.ref ?? entity.name + '_ref01'
-  const entvar = step.input.entvar ?? ref + '_ent'
-  const matchvar = step.input.matchvar ?? (ref + '_match' + (step.input.suffix ?? ''))
-  const listvar = step.input.listvar ?? (ref + '_list' + (step.input.suffix ?? ''))
+  const ref = step.i.ref ?? entity.name + '_ref01'
+  const entvar = step.i.entvar ?? ref + '_ent'
+  const matchvar = step.i.matchvar ?? (ref + '_match' + (step.i.suffix ?? ''))
+  const listvar = step.i.listvar ?? (ref + '_list' + (step.i.suffix ?? ''))
 
-  const priorSteps = Object.values(flow.step).slice(0, Number(index)) as any[]
+  const priorSteps = Object.values(flowSteps(flow)).slice(0, Number(index)) as any[]
   const needsEnt = !priorSteps.some((s: any) =>
-    ['create', 'list', 'load', 'update', 'remove'].includes(s.op))
+    ['create', 'list', 'load', 'update', 'remove'].includes(s.o))
 
   Content(`        // LIST
 `)
@@ -417,12 +409,12 @@ const generateList: OpGen = (ctx, step, index) => {
 `)
 
   // Handle validators
-  const allSteps = Object.values(flow.step) as any[]
-  if (step.valid) {
-    for (const validator of step.valid) {
+  const allSteps = Object.values(flowSteps(flow)) as any[]
+  if (step.v) {
+    for (const validator of step.v) {
       const validRef = validator.def?.ref
-      const hasRefData = validRef && allSteps.some((s: any) => 'create' === s.op &&
-        ((s.input.ref ?? entity.name + '_ref01') === validRef))
+      const hasRefData = validRef && allSteps.some((s: any) => 'create' === s.o &&
+        ((s.i.ref ?? entity.name + '_ref01') === validRef))
 
       if ('ItemExists' === validator.apply && hasRefData && hasDataId) {
         const refDataVar = validRef + '_data'
@@ -448,16 +440,16 @@ const generateList: OpGen = (ctx, step, index) => {
 
 const generateUpdate: OpGen = (ctx, step, index) => {
   const { entity, flow, accessor } = ctx
-  const ref = step.input.ref ?? entity.name + '_ref01'
-  const entvar = step.input.entvar ?? ref + '_ent'
-  const datavar = step.input.datavar ?? (ref + '_data' + (step.input.suffix ?? ''))
-  const resdatavar = step.input.resdatavar ?? (ref + '_resdata' + (step.input.suffix ?? ''))
-  const markdefvar = step.input.markdefvar ?? (ref + '_markdef' + (step.input.suffix ?? ''))
-  const srcdatavar = step.input.srcdatavar ?? (ref + '_data' + (step.input.suffix ?? ''))
-
-  const priorSteps = Object.values(flow.step).slice(0, Number(index)) as any[]
+  const ref = step.i.ref ?? entity.name + '_ref01'
+  const entvar = step.i.entvar ?? ref + '_ent'
+  const datavar = step.i.datavar ?? (ref + '_data' + (step.i.suffix ?? ''))
+  const resdatavar = step.i.resdatavar ?? (ref + '_resdata' + (step.i.suffix ?? ''))
+  const markdefvar = step.i.markdefvar ?? (ref + '_markdef' + (step.i.suffix ?? ''))
+  const srcdatavar = step.i.srcdatavar ?? (ref + '_data' + (step.i.suffix ?? ''))
+
+  const priorSteps = Object.values(flowSteps(flow)).slice(0, Number(index)) as any[]
   const needsEnt = !priorSteps.some((s: any) =>
-    ['create', 'list', 'load', 'update', 'remove'].includes(s.op))
+    ['create', 'list', 'load', 'update', 'remove'].includes(s.o))
 
   const hasEntIdU = null != entity.id
 
@@ -474,8 +466,8 @@ const generateUpdate: OpGen = (ctx, step, index) => {
 `)
   }
 
-  if (step.data) {
-    const dataEntries = Object.entries(step.data).filter(([k]: any) => k !== 'id' && !k.endsWith('$'))
+  if (step.d) {
+    const dataEntries = Object.entries(step.d).filter(([k]: any) => k !== 'id' && !k.endsWith('$'))
     for (const [key] of dataEntries) {
       Content(`            "${key}" => $setup["idmap"]["${key}"],
 `)
@@ -485,10 +477,10 @@ const generateUpdate: OpGen = (ctx, step, index) => {
   Content(`        ];
 `)
 
-  if (step.spec) {
-    for (const spec of step.spec) {
-      if ('TextFieldMark' === spec.apply && null != step.input.textfield) {
-        const fieldname = step.input.textfield
+  if (step.s) {
+    for (const spec of step.s) {
+      if ('TextFieldMark' === spec.apply && null != step.i.textfield) {
+        const fieldname = step.i.textfield
         const fieldvalue = spec.def?.mark ?? `Mark01-${ref}`
         Content(`
         $${markdefvar}_name = "${fieldname}";
@@ -509,9 +501,9 @@ const generateUpdate: OpGen = (ctx, step, index) => {
 `)
   }
 
-  if (step.spec) {
-    for (const spec of step.spec) {
-      if ('TextFieldMark' === spec.apply && null != step.input.textfield) {
+  if (step.s) {
+    for (const spec of step.s) {
+      if ('TextFieldMark' === spec.apply && null != step.i.textfield) {
         Content(`        $this->assertEquals($${resdatavar}[$${markdefvar}_name], $${markdefvar}_value);
 `)
       }
@@ -522,23 +514,23 @@ const generateUpdate: OpGen = (ctx, step, index) => {
 
 const generateLoad: OpGen = (ctx, step, index) => {
   const { entity, flow, accessor } = ctx
-  const ref = step.input.ref ?? entity.name + '_ref01'
-  const entvar = step.input.entvar ?? ref + '_ent'
-  const matchvar = step.input.matchvar ?? (ref + '_match' + (step.input.suffix ?? ''))
-  const datavar = step.input.datavar ?? (ref + '_data' + (step.input.suffix ?? ''))
-  const srcdatavar = step.input.srcdatavar ?? (ref + '_data' + (step.input.suffix ?? ''))
+  const ref = step.i.ref ?? entity.name + '_ref01'
+  const entvar = step.i.entvar ?? ref + '_ent'
+  const matchvar = step.i.matchvar ?? (ref + '_match' + (step.i.suffix ?? ''))
+  const datavar = step.i.datavar ?? (ref + '_data' + (step.i.suffix ?? ''))
+  const srcdatavar = step.i.srcdatavar ?? (ref + '_data' + (step.i.suffix ?? ''))
 
-  const priorSteps = Object.values(flow.step).slice(0, Number(index)) as any[]
+  const priorSteps = Object.values(flowSteps(flow)).slice(0, Number(index)) as any[]
   const hasEntVar = priorSteps.some((s: any) =>
-    ['create', 'list', 'load', 'update', 'remove'].includes(s.op))
+    ['create', 'list', 'load', 'update', 'remove'].includes(s.o))
 
-  const flowHasCreate = Object.values(flow.step).some((s: any) => (s as any).op === 'create')
+  const flowHasCreate = Object.values(flowSteps(flow)).some((s: any) => (s as any).o === 'create')
   const preambleRef = entity.name + '_ref01'
   const hasSrcData = (!flowHasCreate && srcdatavar === (preambleRef + '_data')) ||
     priorSteps.some((s: any) => {
-      if ('create' === s.op) {
-        const priorRef = s.input.ref ?? entity.name + '_ref01'
-        const priorDatvar = s.input.datavar ?? (priorRef + '_data' + (s.input.suffix ?? ''))
+      if ('create' === s.o) {
+        const priorRef = s.i.ref ?? entity.name + '_ref01'
+        const priorDatvar = s.i.datavar ?? (priorRef + '_data' + (s.i.suffix ?? ''))
         return priorDatvar === srcdatavar
       }
       return false
@@ -585,14 +577,14 @@ const generateRemove: OpGen = (ctx, step, index) => {
   if (null == entityDataIdField(entity)) {
     return
   }
-  const ref = step.input.ref ?? entity.name + '_ref01'
-  const entvar = step.input.entvar ?? ref + '_ent'
-  const matchvar = step.input.matchvar ?? (ref + '_match' + (step.input.suffix ?? ''))
-  const srcdatavar = step.input.srcdatavar ?? (ref + '_data')
+  const ref = step.i.ref ?? entity.name + '_ref01'
+  const entvar = step.i.entvar ?? ref + '_ent'
+  const matchvar = step.i.matchvar ?? (ref + '_match' + (step.i.suffix ?? ''))
+  const srcdatavar = step.i.srcdatavar ?? (ref + '_data')
 
-  const priorSteps = Object.values(flow.step).slice(0, Number(index)) as any[]
+  const priorSteps = Object.values(flowSteps(flow)).slice(0, Number(index)) as any[]
   const needsEnt = !priorSteps.some((s: any) =>
-    ['create', 'list', 'load', 'update', 'remove'].includes(s.op))
+    ['create', 'list', 'load', 'update', 'remove'].includes(s.o))
 
   Content(`        // REMOVE
 `)

package/project/.sdk/src/cmp/php/utility_php.ts

@@ -67,28 +67,6 @@ function formatPhpValue(val: any, indent: number = 0): string {
 }
 
 
-// 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/py/Config_py.ts

@@ -34,32 +34,11 @@ import {
 } from './utility_py'
 
 
-// PLUGIN DEFINITION IMPORTS AND THE FEATURE_PLUGINS MAP (mirrors
-// cmp/ts/Config_ts.ts).
-//
-// 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 config imports each
-// active plugin's exported definition BY NAME (the model's `def.py` map)
-// and hands the list to the feature through FEATURE_PLUGINS.
-//
-// The `def` map is declared in the model rather than derived from
-// filenames because one module may export several definitions (sekreto's
-// aws.py exports awssecrets AND awsparams). A def value is the module's
-// path under tm/py ('pkg/feature/.../aws.py'); Main copies tm/py/pkg INTO
-// the <name>_sdk package, so the import module is the path with `pkg/`
-// swapped for the package name and slashes for dots.
 function pluginImports(feature: any, pkg: string) {
   each(feature, (f: any) => {
-    // path -> [symbol, ...], so one import line serves a two-definition
-    // module.
     const bypath: Record<string, string[]> = {}
 
     each(f.plugin, (plugin: any) => {
-      // Filter on `active` HERE rather than trusting the feature object
-      // to arrive filtered: getting it wrong in this direction emits an
-      // import for a module the plugin trim just deleted - an SDK that
-      // does not import, rather than one that merely carries too much.
       if (false === plugin.active || null == plugin.active) return
 
       for (const [sym, one] of Object.entries(plugin.def?.py || {})) {
@@ -76,8 +55,6 @@ function pluginImports(feature: any, pkg: string) {
   })
 }
 
-// The FEATURE_PLUGINS entries: one line per feature that has any active
-// plugin definitions, listing the imported symbols.
 function pluginDefs(feature: any) {
   each(feature, (f: any) => {
     const syms: string[] = []
@@ -99,15 +76,11 @@ const Config = cmp(async function Config(props: any) {
   const model: Model = ctx$.model
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  // 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)
 
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 
   const authActive = isAuthActive(model)
-  // config.auth.prefix override -> spec-derived info.security.prefix -> 'Bearer'
   const authPrefix = resolveAuthPrefix(model)
   // `in` and `name` travel with the prefix now. They were resolved by
   // apidef all along and dropped here, so an apiKey-in-query API got an
@@ -120,8 +93,6 @@ const Config = cmp(async function Config(props: any) {
   let baseUrl = ''
   try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }
 
-  // Templated server URL: emit the spec's server-variable defaults so the
-  // runtime can substitute {name} placeholders in base (see make_options).
   const svars = serverVariables(model)
   const serverBlock = 0 === svars.length ? '' :
     '            "server": {\n' +
@@ -136,12 +107,6 @@ const Config = cmp(async function Config(props: any) {
             },\n`
     : ''
 
-  // The same config as an OBJECT, built by the shared helper so this target's
-  // literal and the data that replaces it above the threshold are the same
-  // config by construction. The JSON is what the threshold is measured on -
-  // emitted source size varies by language, the model does not. Passing the
-  // target name opts in to the main.slug/version/target identity fields -
-  // the literal path below emits them too, keeping the two reps in step.
   const { def: configDef, json: configJson } = configDefinition(model, target.name)
   const asData = isConfigData(configJson, configReprSetting(model))
 
@@ -193,20 +158,6 @@ def shared_config():
 
 `)
 
-    // ABOVE THE THRESHOLD: emit the model as DATA.
-    //
-    // A dict literal makes CPython build the whole structure opcode by opcode
-    // at import, and the compiler hold the entire literal in memory to produce
-    // that bytecode. A string constant is one object, and `json.loads` (the C
-    // scanner) builds the dict far faster than the equivalent literal.
-    //
-    // `json.loads` yields exactly what the literal did - str keys, int for
-    // whole numbers, True/False/None - so make_config's result is unchanged.
-    //
-    // JSON.stringify output is a valid Python string literal: every escape it
-    // emits (\\", \\\\, \\n, \\uXXXX) means the same thing in Python, it never emits
-    // \\/ (which Python would not treat as an escape), and Python 3 source is
-    // UTF-8 so non-ASCII needs no escaping.
     if (asData) {
       Content(`# THE API MODEL, EMBEDDED AS DATA (sdkgen rung L1).
 #
@@ -227,10 +178,6 @@ def make_config():
       return
     }
 
-    // Identity values from configDefinition's def, not re-derived here, so
-    // the literal rep and the data rep cannot disagree on identity (the
-    // slug is CARRIED, never derived from the camel name - station's
-    // descriptor reads all three; see cmp/ts/Config_ts.ts #MainMeta).
     Content(`def make_config():
     """Build a fresh, fully materialised config dict.
 

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

@@ -1,35 +1,5 @@
 
 
-// Typed-model generator (Python target). Port of EntityTypes_ts.ts.
-//
-// Reads main.<KIT>.entity.<e>.fields[] and per-op params
-// (op.<name>.points[].args.params[]) and emits one module, <sdk>_types.py,
-// with a `class <Name>(TypedDict):` per active entity plus a request/match type
-// per active op. Field/param sentinels ($STRING, $INTEGER, ...) are turned into
-// real Python types by the shared sdkgen helper `canonToType` (source of truth:
-// @voxgig/apidef VALID_CANON).
-//
-// TYPE CHOICE: `TypedDict`, not `@dataclass`. The generated ops return/accept
-// plain runtime dicts (data_get/match_get return `vs.clone(self._data)`; ops
-// take/return dicts), so a `@dataclass` annotation is only aspirational — a
-// strict checker at a call site would see dict-vs-dataclass. A TypedDict *is* a
-// dict shape, so annotating these dict-returning/-accepting ops with TypedDict
-// makes the TYPES MATCH the runtime. Runtime behaviour is unchanged.
-//
-// OPTIONAL FIELDS: a `req:false` field/param is a key that MAY be absent, which
-// is exactly TypedDict `total=False` (key optionality), not `Optional[T]` (a
-// None value). To express required AND optional keys on py>=3.8 WITHOUT a
-// typing_extensions dependency (no `NotRequired`), a type with both splits into
-// a required base `class <Name>Required(TypedDict): ...` and a `total=False`
-// subclass `class <Name>(<Name>Required, total=False): ...` that carries the
-// public name and adds the optional keys. Degenerate shapes collapse to a
-// single class (all-required, all-optional, or empty). The all-optional
-// collapse also serves the match-mirror types (the Python analogue of TS
-// `Partial<${Name}>`).
-//
-// Keep the SAME type-name scheme as every other language: <Name>,
-// <Name>LoadMatch, <Name>ListMatch, <Name>CreateData, <Name>UpdateData,
-// <Name>RemoveMatch.
 
 import {
   cmp, each, names,
@@ -56,25 +26,11 @@ const PY_KEYWORDS = new Set([
 ])
 
 
-// A name usable as a class-syntax TypedDict key (valid identifier, not a
-// keyword). Non-identifier/keyword field names have no safe class-syntax
-// rendering, so they are skipped (they remain reachable via the runtime dict).
 function pyIdent(name: string): boolean {
   return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) && !PY_KEYWORDS.has(name)
 }
 
 
-// Emit a TypedDict named `typeName` from a list of {name, type, optional}
-// items (optionality already decided by the caller — the shared partiality
-// policy for op types, or `req` for the entity data type). Required items
-// become required keys; optional items become not-required keys via a
-// `total=False` extension.
-//
-// Shape selection (see file header for the rationale):
-//   both required + optional -> `<typeName>Required` base + `total=False` sub
-//   only required            -> single `class <typeName>(TypedDict):`
-//   only optional            -> single `class <typeName>(TypedDict, total=False):`
-//   no usable keys           -> single `class <typeName>(TypedDict): pass`
 function emitTypedDict(typeName: string, items: any[], log?: any): void {
   const usable = items.filter((it: any) => it && null != it.name && pyIdent(it.name))
 
@@ -132,10 +88,6 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
   const target = props.target || {}
   const ext = target.ext || LANG
 
-  // only_active:false — getModelPath DROPS active:false entries by default,
-  // but the consumer scaffold (create-sdkgen Root.ts) iterates the RAW entity
-  // 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 generated entity code: the consumer
   // scaffold (create-sdkgen Root.ts) iterates entities WITHOUT an active
@@ -147,17 +99,14 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
   // entity not yet named (e.g. a fieldless placeholder) would otherwise read
   // `Name = undefined` below. Parity with the go emitter's fix.
 
-  // 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)
 
   File({ name: model.const.Name.toLowerCase() + '_types.' + ext }, () => {
 
     Content(`# Typed models for the ${model.const.Name} SDK.
 #
-# GENERATED from the API model: main.${KIT}.entity.<e>.fields[] and per-op
-# params (op.<name>.points[].args.params[]). Field/param types come from the
+# GENERATED from the API model: main.${KIT}.entity.<e>.fields{} and per-op
+# params (op.<name>.points[].g.params[]). Field/param types come from the
 # canonical type sentinels via @voxgig/sdkgen canonToType (source of truth:
 # @voxgig/apidef VALID_CANON). Do not edit by hand.
 #
@@ -175,19 +124,15 @@ from typing import TypedDict, Any
     entityList.forEach((ent: any) => {
       const Name = ent.Name
       const fields = (ent.fields ? each(ent.fields) : [])
-        .filter((f: any) => f.active !== false)
+        .filter((f: any) => f.a !== false)
 
-      // Entity data model: one key per field, `req:false` -> optional key.
       Content(`
 
 `)
       emitTypedDict(Name, fields.map((f: any) => ({
-        name: f.name, type: f.type, optional: false === f.req,
+        name: f.n, type: f.t, optional: false === f.r,
       })), log)
 
-      // Per active op: a request/match type. Members and their optionality come
-      // from the shared partiality policy (opRequestShape); this file only
-      // renders them as a TypedDict.
       const ops = ent.op || {}
       ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
         if (null == ops[opname]) {

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

@@ -19,10 +19,6 @@ const Entity = cmp(function Entity(props: any) {
   const { model, stdrep } = props.ctx$
   const { target, entity } = props
 
-  // Collision-free entity CLASS name (see entityClassName): normally
-  // `<Name>Entity`, disambiguated when it would clash with another entity's
-  // data-type name. The DATA type stays `<Name>`. The snake-cased source-file
-  // name is unaffected; only the class identifier changes.
   const entityColl = entityCollection(model)
   const cls = entityClassName(entity, entityColl)
 
@@ -32,8 +28,6 @@ const Entity = cmp(function Entity(props: any) {
 
   names(entrep, entity.Name, 'EntityName')
 
-  // Import exactly the typed models this entity references: its data type plus
-  // one request type per ACTIVE op (matches what EntityTypes_py.ts emits).
   const typeNames = [entity.Name]
   const opnamesAll = Object.keys(entity.op || {})
   ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
@@ -41,8 +35,6 @@ const Entity = cmp(function Entity(props: any) {
       typeNames.push(opTypeName(entity.Name, opname))
     }
   })
-  // The generated dataclasses live inside the SDK package alongside
-  // everything else, so the import is package-qualified.
   const typesModule = model.const.Name.toLowerCase() + '_sdk.' +
     model.const.Name.toLowerCase() + '_types'
   const typeImport =
@@ -51,9 +43,6 @@ const Entity = cmp(function Entity(props: any) {
 
   const ff = Path.normalize(__dirname + '/../../../src/cmp/py/fragment/')
 
-  // Entity files go to <name>_sdk/entity/ — inside the SDK package, not at
-  // the language root. See the note in Main_py.ts: a top-level `entity`
-  // package is shadowable by any entity.py sitting beside the caller.
   Folder({ name: model.const.Name.toLowerCase() + '_sdk' }, () => {
   Folder({ name: 'entity' }, () => {
 
@@ -77,13 +66,8 @@ const Entity = cmp(function Entity(props: any) {
           EntityName: entity.Name,
           entityname: entity.name,
 
-          // Class token decoupled from the EntityName data-type token in
-          // Entity.fragment.py so the class can be renamed independently.
           EntyClass: cls,
 
-          // Literal-marker slot (jostraca's `#Name` tag pattern is hardcoded to
-          // `//` comments, so Python uses a `# #`-prefixed literal like the op
-          // frag slots) — fills in the typed-model import for this entity.
           '# #TypeImports': typeImport,
 
           // Feature-hook markers. jostraca's built-in `#Name-Tag` pattern is